knitr 2024-2026 版本更新回顾

自从我宣布更新已经很久了编织者上次了，所以我写这篇文章是为了介绍一些显著的变化编织者v1.46–v1.52。完整更新日志请参见发行说明在GitHub上。

希望你会觉得这三年回顾有帮助。

Knitr 1.46（2024-04-06）

新区块选项tab.cap

你现在可以在块头里设置表格标题，而不是在内部kable()，例如，

```{r tab.cap="Motor Trend car data (first six rows)"}
knitr::kable(head(mtcars))
```

以前你必须写作knitr::kable(head(mtcars), caption = "...")这在你想保持区块选项统一且R代码干净时很不方便 （#1679).

spin()认可# %%以及#|

还有两个块分隔符可以加入spin()现在。例如，一个VS Code / Jupyter风格的脚本：

# My report

# %%
plot(cars)

# %% results="hide"
invisible(summary(cars))

还有Quarto风格的风笛评论：

#| label: fig-cars
#| fig-cap: "Speed vs. distance"
plot(cars)

两者都可以被合成成文档knitr::spin("script.R").旧的#-分隔符已失效;请使用#+或上述任何新的分隔符（#2307,#2320).

块钩接受...

以前，每个区块钩子都必须声明参数before,options,envir， 和name具体地，例如，

# old: had to list explicitly
knitr::knit_hooks$set(my_hook = function(before, options, envir, name) {
  if (before) cat("starting\n")
})

现在...可以用来捕捉所有和编织者将所有参数隐式传递给...（如果你的引子不支持这些论点，它们将被悄悄放弃）：

knitr::knit_hooks$set(my_hook = function(before, ...) {
  if (before) cat("starting\n")
})

包小品的PNG优化

如果optipng或pngquant在你的PATH，PNG小图在R CMD build.无需更改代码——只需安装工具即可。CRAN 上的 PNG 图有常常出乎意料地大;对于包含多个图块的短片，这可以显著减少安装包的大小。

破坏：不平衡的区块围栏是错误

任何块头/页脚不匹配都会报错，例如，

````{r}
1 + 1
```

开局的围栏有四个回溯刻度;闭合的围栏必须完全匹配（#2306).

突发：小插曲纠缠R CMD check

编织者不再跳过纠结的小插曲R CMD check.然后执行纠结的R脚本，因此检查失败现在可能来自小品代码，而非小品构建。CRAN 集合_R_CHECK_VIGNETTES_SKIP_RUN_MAYBE_=true所以这主要影响非CRAN检查（比如GitHub Actions）。

如果你想要原来的行为，可以把那个环境变量添加到你的工作流程中。

Knitr 1.47（2024-05-29）

极限kable()通过全局选项进行行

大数据帧意外传递到kable()可以生成巨大的表。如果你想防止意外出现巨大的表，可以设置全局上限，例如，

options(knitr.kable.max_rows = 30)
knitr::kable(big_df)  # only first 30 rows rendered, rest silently dropped

Knitr 1.48（2024-07-08）

本版本仅包含漏洞修复，无需关注。

Knitr 1.49（2024-11-08）

禁用区块内引用，使用ref.chunk = FALSE

编织者的<>语法重用区块代码默默地把真正用来处理的R代码搞砸了<</>>作为分隔符——例如，glue::glue()改变开盘/收盘标记的变体：

myglue <- function(..., .envir = parent.frame()) {
  glue(..., .open = "<<", .close = ">>", .envir = .envir)
}
x <- "<> <- function(x) { <> }"

任何<<...>>单独的图案会被编织者，所以x结果针织输出中会出现缺线。Setref.chunk = FALSE关闭受影响区块的替换 （#2360），例如，

```{r ref.chunk=FALSE}
...
x <- "<> <- function(x) { <> }"
```

fig.alt对于LaTeX来说

图形的替代文本现在可以在 LaTeX 输出中使用，例如，

```{r fig.alt="A scatter plot of speed versus stopping distance"}
plot(cars)
```

编织者发射\includegraphics[alt={A scatter plot...}]{...}该功能被最新版本的LaTeX支持，并支持可访问的PDF（#2378).

自定义评估环境

knit_global()现在接受环境参数，因此你可以将所有区块评估重定向到自定义环境。例如，推荐的模式保存并恢复了旧环境：

new_env <- new.env(parent = globalenv())
old_env <- knitr::knit_global(new_env)
on.exit(knitr::knit_global(old_env), add = TRUE)
knitr::knit("report.Rmd")  # all chunks evaluated in new_env

这对像这样的包非常有用多元宇宙需要在每个分析中分别执行块，而不是共享的全局环境。

Knitr 1.50（2025-03-16）

用于内联编码错误的精确行号

之前，内联表达式中出现的错误，如`r log(-1)`报告了周围段落的行范围。现在它指向了准确的行，使在长文档中更快定位有问题表达式（#2387).

错误追踪R CMD build

当小品未能建立时，完整的R回溯会被打印出来。以前你只会收到错误信息，然后必须交互式重现失败来查看错误来源 （#2390).

kable()组织模式的列对齐

对齐指定符现在在组织模式输出中能够正确渲染，例如，

knitr::kable(head(iris), format = "org", align = c("l","r","r","r","l"))

之前对齐被忽略，所有列都显示为左对齐（#2391).

combine_words()以及write_bib()搬到了XFUN平台

这两个职能都得到了合适的归宿XFUN（我用于杂项功能的基础），例如，

xfun::join_words(c("apples", "oranges", "bananas"))
# "apples, oranges, and bananas"

xfun::pkg_bib(c("knitr", "rmarkdown"), file = "refs.bib")

该编织者版本（combine_words(),write_bib()）仍保持封装形式且未被弃用，但新代码应优先使用XFUN版本。

Knitr 1.51（2025-12-20）

OpenTelemetry 追踪

其中酒店/奥特尔斯德克安装并配置好追踪器后，编织会自动输出可发送到任何OpenTelemetry后端的跨度，例如，

library(otelsdk)
# configure your exporter, then:
knitr::knit("report.Rmd")
# → spans: "knitr processing", "knitr output", one "knit" span per chunk

每个每个区块的范围记录区块标签和引擎，这样你可以分析大文档中哪些区块慢（#2422).

织前/后编织钩

你可以在整个编织上运行设置或拆解代码，而不仅仅是围绕每个部分，例如，

knitr::knit_hooks$set(
  before.knit = function() {
    con <<- DBI::dbConnect(RSQLite::SQLite(), "data.db")
  },
  after.knit = function() {
    DBI::dbDisconnect(con)
  }
)

(#2223,#2419)

fig.alt = ''发出空的alt属性

背景设定fig.alt = ""现在 生成，而不是完全省略该属性。使用fig.alt = NA省略它，例如，

# decorative image: alt="" tells screen readers to skip it
knitr::opts_chunk$set(fig.alt = "")   # → 

# no attribute at all (old behavior for empty alt):
knitr::opts_chunk$set(fig.alt = NA)   # →  (no alt)

这种区分对于无障碍审计很重要：alt=""明确标记该人物为装饰性;缺失alt大多数工具会标记为错误（#2415).

Knitr 1.52（2026-09-06）

新区块选项fig.note

在图下方添加来源注释或说明，与说明文字分开，例如，

```{r fig.cap="US population", fig.note="Source: US Census Bureau"}
plot(uspop)
```

对于 HTML 来说，这变为

在图形内部，你可以用CSS来样式化。对于LaTeX，它会发出\figurenote{Source: US Census Bureau}在图形环境内（你可以在序言中重新定义该命令，例如，让浮行的\floatfoot).也支持 Typst 输出（#2022).

Typst客服：.Rtyp输入和knitr::rtypVignette 引擎

我写了专门的帖子关于这个功能。简而言之，你现在可以用.Rtyp延长并像R Markdown那样编织，例如，

knitr::knit("report.Rtyp")          # → report.typ
knitr::knit2pdf("report.Rtyp")      # → report.pdf (via Typst)

我不确定有多少人会真正用到这个，但至少我很高兴弗兰克·哈雷尔一直在探索他与Typst支持的激动人心的新旅程。编织者(#2401,#2283).

新的Vignette引擎意味着包裹只需两行即可发送Typst的VignetteDESCRIPTION:

VignetteBuilder: knitr
Suggests: knitr

以及一个小品标题：

%\VignetteEngine{knitr::rtyp}
%\VignetteIndexEntry{My Typst Vignette}

(#2447)

hook_plot_tex()敬意animation.hook

之前仅此一例hook_plot_html()可通过以下方式扩展animation.hook/animation.fun.现在 LaTeX 钩子也尊重相同的选项，例如，使用XMPMULTI对于Beamer叠加层，而非动画化:

knitr::opts_chunk$set(
  animation.hook = function(x, options) {
    # use \multiinclude from xmpmulti for Beamer overlays
    paste0("\\multiinclude[format=png]{", xfun::sans_ext(x[1]), "}")
  }
)

如果没有这个变化，LaTeX 动画就会锁定在动画化包（#2452).

WebP数据来源ragg::agg_webp()

例如：

knitr::opts_chunk$set(dev = "agg_webp", fig.ext = "webp")

要求拉格>= 1.5.0。WebP在同等视觉质量下通常比PNG小25–35%，这对于文件大小很重要的HTML报告非常有用（#2434).

dev.args合作gridSVG

例如：

knitr::opts_chunk$set(
  dev = "gridSVG",
  dev.args = list(strict = FALSE, pointsize = 12)
)

编织者现今路线strict到gridSVG::grid.export()以及pointsize到grDevices::svg()所以你不再需要自定义钩子来传递选项gridSVG(#2450,#2451).

修复错误：多数字区块的字幕被删除

当一个区块生成多个带有说明文字的图形时，只有第一个文字存活，因为Pandoc将一段中连续的图片视为内嵌（无字幕）图像。编织者现在在带有说明的图形之间插入一行空白，例如，

```{r fig.cap=c("First plot","Second plot")}
plot(cars)
plot(pressure)
```

现在两种字幕都能正确出现在HTML和PDF输出中（#2032,#1524,#1760).

修复错误：include_graphics()输出DIR不同时的路径

例如：

# Rendered with rmarkdown::render("report.Rmd", output_dir = "docs/")
knitr::include_graphics("images/fig1.png")

之前这会导致输出路径断裂，因为编织者解析路径相对于输入目录，而非输出目录。它现在使用由rmarkdown>= 2.32 （#2171).

knit2html()朋友们直接使用 Litedown

knit2html(),stitch(),knit_rd()，以及knitr::knitrVignette引擎现在呼叫litedown::mark()直接而不是通过打折package。这可能是一个重大变更。

之前，markdown::mark()在交接给低音;现在这些修复不再发生了。如果你的短片依赖那个无声修复，它就会坏掉。具体来说：

1. yes/no在YAML中。YAML 布尔值必须为true/false在Litedown中。如果你的短篇标题包含例如：toc: yes，改为toc: true.
2. bibliography没有Rbibutils。如果你的YAML有bibliography:场，但Rbibutils未安装包，markdown::mark()会悄无声息地跳过田野R CMD check.现在你会收到错误，所以要添加Rbibutils到Suggests在DESCRIPTION如果你在小品中使用参考书目。
3. 列表项目- 在YAML中。litedown 使用与标准 YAML 不同的 YAML 语法。开头的项目- 在一行的开头，没有支撑;参见litedown YAML 语法为了替代方案。

对于使用knitr::knitrVignette 引擎，也更新DESCRIPTION可以依靠低音代替打折，例如，

Suggests: litedown

或者如果你需要参考书目支持：

Suggests: litedown, rbibutils

致谢

感谢所有提交问题或提交拉取请求的贡献者：Abhraneel Sarma （@abhsarma),@aksigkvgithub，阿尔诺·加卢（@arnaudgallou),@atusy塞巴斯蒂安·迈耶（@bastistician),@blset，亚历克斯·莱因哈特（@capnrefsmmat），克里斯托夫·德维厄（@cderv），帕特里克·R（@codeZeilen），大卫·切尔（@dcser123），迪帕扬·萨卡尔（@deepayan),@DeliciousRoastPotato,@dlampart，大卫·卡普兰（@dmkaplan2000），赵成（@fenguoerbian），弗洛里安·科尔特（@fkohrt），弗洛里斯·范德哈赫（@florisvdh），加里克·阿登-布伊（@gadenbuie),@ggrothendieck哈德利·威克汉姆（@hadley），Watal M. Iwasaki（@heavywatal），赫德维格·斯基尔加德（@HedvigS），道格·亨肯（@Hemken），迈克尔·希金斯（@Higgs32584），贾米尔·阿尔萨拉姆（@jameelalsalam），詹妮弗·布莱恩（@jennybc），Jeroen Ooms （@jeroen），约翰·拉尔森（@jolars），凯文·乌希（@kevinushey),@knokknok，凯尔·F·巴茨（@kylebutts），李·门德洛维茨（@LeeMendelowitz），莱昂尼达斯·扎克（@LeonidasZhak），L. 桑迪格（@lsandig），马库斯·施莱格尔（@markschl），马克斯·施密特（@maxschmi),@mbs2016,@mclements，马修·米哈尔斯卡-史密斯（@mjsmith037），尼古拉斯·A·门德斯（@naikymen南晓（@nanxstats），奥利维亚·博克斯·鲍尔（@Olivia-箱-动力），奥特·图梅特（@otoomet），塞巴斯蒂安·科普夫（@sebkopf),@shangeconnew，高查理（@shikokuchuo），托比·迪兰·霍金（@tdhock），费利克斯·图尔巴尼施（@turbanisch），乌尔里克·林格斯（@ulyngs).

这有点难以置信编织者现在快15年了。它陪伴我超过三分之一的人生。不用说，没有更广泛R社区的支持，尤其是近年来2500+ GitHub的问题/PRs，这个项目是不可能实现的。

如果你还需要什么，随时欢迎提交新问题，评论/点赞旧问题，或发送拉取请求：https://github.com/yihui/knitr谢谢！