Quarto中使用as_gt()转换gtsummary表格后PDF渲染表头格式异常求助

问题背景与重现 #

使用Quarto生成PDF报告，2023年底模板可正常生成表格，但在R 4.4.1、最新版Quarto及更新后的TinyTeX环境下，所有通过as_gt()（或as_kable()）转换的gtsummary表格，在PDF渲染后表头格式错乱，R代码块中显示正常。

正常示例（渲染PDF无问题） #

library(magrittr)
library(gt)
library(gtsummary)

mtcars %>%
  tbl_summary(by = cyl)

出错示例（PDF渲染后表头错乱） #

mtcars %>%
  tbl_summary(by = cyl) %>%
  as_gt()

可能原因 #

1. 包版本兼容性冲突：R 4.4.1为较新版本，gt、gtsummary的后续更新可能修改了LaTeX表格生成逻辑，与新版Quarto的PDF渲染引擎不兼容。
2. Quarto渲染逻辑调整：新版Quarto对LaTeX表格的解析或处理方式发生变化，导致gt生成的表头LaTeX代码无法正确渲染。
3. LaTeX依赖缺失：TinyTeX中缺少gt生成复杂表头所需的LaTeX包（如multirow、tabularx等），导致表头格式崩溃。

解决办法 #

1. 回退到兼容的包版本 #

将gt和gtsummary回退到2023年底的稳定版本（例如gt v0.9.0、gtsummary v1.7.2），避免新版本的兼容性问题：

# 安装指定版本的gt
install.packages("gt", version = "0.9.0", repos = "https://cran.r-project.org")
# 安装指定版本的gtsummary
install.packages("gtsummary", version = "1.7.2", repos = "https://cran.r-project.org")

2. 配置Quarto的PDF渲染参数 #

在Quarto文档的YAML头部添加LaTeX依赖配置，确保渲染时加载必要的表格支持包：

format:
  pdf:
    keep-tex: true  # 保留生成的LaTeX文件用于排查
    include-in-header:
      text: |
        \usepackage{booktabs}
        \usepackage{multirow}
        \usepackage{tabularx}
        \usepackage{colortbl}

3. 避免转换，直接用gtsummary内置格式 #

如果仅需要添加特定格式，可使用gtsummary的原生函数（如modify_header()、modify_table_styling()）调整表格样式，无需转换为gt对象：

mtcars %>%
  tbl_summary(by = cyl) %>%
  modify_header(all_stat_cols() ~ "**{level}**") %>%  # 自定义表头格式
  modify_table_styling(columns = all_stat_cols(), align = "center")

4. 检查并修复LaTeX代码 #

开启keep-tex: true后，打开生成的.tex文件，找到对应表格的LaTeX代码，手动修正表头的\multicolumn或\multirow逻辑，确保表头合并规则符合LaTeX语法。

5. 完全更新依赖并安装缺失LaTeX包 #

确保所有R包和TinyTeX完全更新，再安装必要的LaTeX依赖：

# 更新所有R包
update.packages(ask = FALSE)
# 安装缺失的LaTeX包
tinytex::tlmgr_install(c("booktabs", "multirow", "tabularx", "colortbl", "array"))

内容的提问来源于stack exchange，提问作者Stats Iliterate