**knitr** 2024 至 2026 年更新回顾
内容提要
knitr v1.46 至 v1.52 版本更新汇总：支持在代码块头设置表格标题、新增 spin() 分隔符、钩子函数可通过 ... 传参、自动压缩 PNG、新增 fig.note 图注、Typst 支持、WebP 图形设备、修复多图标题问题、引入 OpenTelemetry 追踪，并修复若干问题。
延伸解读
表格标题与代码整洁
现在可以在代码块头中设置表格标题，例如使用 tab.cap 选项，而无需在 kable() 函数内部指定 caption 参数。这有助于将代码块选项集中管理，保持 R 代码的简洁性，避免在函数调用中混杂展示逻辑。对于频繁生成表格的报告，这一改动能减少重复代码，提升可读性。
spin() 分隔符更新
spin() 现在支持两种新的代码块分隔符：VS Code/Jupyter 风格的 # %% 和 Quarto 风格的管道注释 #|。旧的 #- 分隔符已不再有效，需改用 #+ 或上述新分隔符。这使得从脚本生成文档更加灵活，尤其适合习惯使用现代编辑器或 Quarto 的用户。
钩子函数参数传递简化
以前定义 chunk 钩子函数必须显式声明 before、options、envir 和 name 等参数。现在可以使用 ... 捕获所有参数，knitr 会自动传递，不支持的参数会被静默忽略。这简化了钩子函数的编写，减少了样板代码，让开发者更专注于钩子逻辑本身。
无障碍与输出优化
新增 fig.alt 选项支持 LaTeX 输出的替代文本，有助于生成无障碍 PDF。fig.alt = "" 会生成空 alt 属性，明确标记装饰性图像，而 fig.alt = NA 则完全省略属性。此外，fig.note 选项允许在图形下方添加来源或说明注释，独立于标题，并支持 HTML、LaTeX 和 Typst 输出。
Q&A
knitr v1.46 到 v1.52 主要更新了哪些功能？
主要更新包括：支持在代码块头设置表格标题（tab.cap）、spin() 新增分隔符、钩子函数可通过 ... 传参、自动压缩 PNG、新增 fig.note 图注、Typst 支持、WebP 图形设备、修复多图标题问题、引入 OpenTelemetry 追踪，并修复若干问题。
如何在 knitr 中为表格设置标题？
可以在代码块头中使用 tab.cap 选项设置表格标题，例如：```{r tab.cap="Motor Trend car data (first six rows)"} knitr::kable(head(mtcars)) ```。这样就不必在 kable() 函数内部写 caption 参数，便于保持代码块选项集中和 R 代码整洁。
knitr 的 spin() 函数现在支持哪些分隔符？
spin() 现在支持两种新的分隔符：VS Code / Jupyter 风格的 # %% 和 Quarto 风格的管道注释 #|。旧的 #- 分隔符不再有效，请使用 #+ 或上述新分隔符。
knitr 如何自动压缩 PNG 图片？
如果 optipng 或 pngquant 在 PATH 中，knitr 会在 R CMD build 期间自动压缩 vignette 中的 PNG 图。无需修改代码，只需安装这些工具即可。这有助于减小包含多个图的 vignette 的安装包大小。
knitr 新增的 fig.note 选项有什么作用？
fig.note 用于在图形下方添加来源或说明注释，与图标题分开。例如：```{r fig.cap="US population", fig.note="Source: US Census Bureau"} plot(uspop) ```。在 HTML 中会生成 <p class="figure-note"> 元素，在 LaTeX 中生成 \figurenote{} 命令，Typst 输出也支持。
knitr 如何支持 Typst 文档？
knitr 现在支持编写 R + Typst 文档，使用 .Rtyp 扩展名，可以像 R Markdown 一样编织。例如：knitr::knit("report.Rtyp") 生成 report.typ，knitr::knit2pdf("report.Rtyp") 生成 report.pdf。包也可以通过 VignetteBuilder: knitr 和 %\VignetteEngine{knitr::rtyp} 来提供 Typst vignette。
knitr 如何启用 OpenTelemetry 追踪？
安装 otel / otelsdk 并配置 tracer 后，knitting 会自动发出 span 到任何 OpenTelemetry 后端。例如：library(otelsdk) 配置导出器后，knitr::knit("report.Rmd") 会生成 "knitr processing"、"knitr output" 以及每个代码块的 "knit" span。每个代码块 span 记录标签和引擎，可用于分析大型文档中哪些代码块较慢。
knitr 中 fig.alt 设置为空字符串和 NA 有什么区别？
设置 fig.alt = "" 会生成 <img alt="" ...>，明确标记图形为装饰性，屏幕阅读器会跳过；设置 fig.alt = NA 则完全省略 alt 属性，生成 <img ...>。对于无障碍审计，alt="" 是正确做法，而缺失 alt 会被大多数工具标记为错误。
knitr 如何解决一个代码块中多个图形标题只显示第一个的问题？
当单个代码块生成多个带标题的图形时，Pandoc 会将连续图像视为内联无标题图像，导致只有第一个标题保留。knitr 现在在带标题的图形之间插入空行，例如：```{r fig.cap=c("First plot","Second plot")} plot(cars) plot(pressure) ```，这样两个标题都能正确显示在 HTML 和 PDF 输出中。
knitr 的 WebP 图形设备如何使用？
可以设置代码块选项 dev = "agg_webp" 和 fig.ext = "webp"，需要 ragg >= 1.5.0。WebP 在同等视觉质量下通常比 PNG 小 25–35%，适用于对文件大小敏感的 HTML 报告。
