rstudio/gt · 上手攻略

  • 仓库：rstudio/gt
  • 链接：https://github.com/rstudio/gt
  • 分类：数据可视化 · R 语言
  • 作者：Tom
  • 更新：2026-08-20

是什么

gt 是 R 语言中的一个包，用于生成信息丰富、出版品质的展示表格（display tables）。它由 Posit（原 RStudio）团队维护，核心维护者是 Rich Iannone。gt 的设计哲学是「用一套统一的表格部件来构建各种实用表格」，表格部件包括：表头（header）、存根（stub，表格左侧的标签列）、列标签、跨列大标题、表体和表脚。

gt 接收 tibble 或 data.frame 数据，经过流水线式的函数链式调用（dplyr 风格）完成数据处理、格式化、样式设置，最终渲染为 HTML、LaTeX 或 RTF 三种输出格式，支持在 R Markdown 文档里直接嵌入，也支持通过 gtsave() 导出为独立文件。

解决什么问题

在 R 生态里，生成好看表格一直是个痛点：

  • print.data.frame() 输出的原始文本表格没有任何样式可言
  • xtable、stargazer 等老包输出 LaTeX 但 API 繁琐、样式定制困难
  • kable（knitr）简单够用但定制上限低

gt 的目标是：像 ggplot2 之于图表那样，给表格一个「声明式、可组合、语义清晰」的数据管道。用 dplyr 处理数据，用 gt() 渲染表格，用 tab_xxx() 系列函数精细控制各部件——整个流程既适合探索阶段快速出图，也适合最终报告里直接使用。

快速安装

# 从 CRAN 安装稳定版（版本号请以 CRAN 实际发布为准）
install.packages("gt")

# 或从 GitHub 安装开发版
devtools::install_github("rstudio/gt")

⚠️ 版本参考：截至 2025 年 12 月 16 日，gt 已在 CRAN 发布 1.2.0 版本（gt 1.0.0 = 2025-04-05，1.1.0 = 2025-09-23）。建议优先使用 CRAN 稳定版。

核心用法

最简例子（S&P 500 数据）

gt 内置了 18 个示例数据集，这里用 sp500 演示最基本的工作流：

library(gt)

start_date <- "2010-06-07"
end_date   <- "2010-06-14"

sp500 |>
  dplyr::filter(date >= start_date & date <= end_date) |>
  dplyr::select(-adj_close) |>
  gt() |>
  tab_header(
    title = "S&P 500",
    subtitle = glue::glue("{start_date} to {end_date}")
  ) |>
  fmt_currency(columns = c(open, high, low, close)) |>
  fmt_date(columns = date, date_style = "wd_m_day_year") |>
  fmt_number(columns = volume, suffixing = TRUE)

核心管道：数据 |> gt() |> fmt_xxx() |> ... |> 渲染

常用格式化函数

函数 作用 示例
fmt_number() 数字格式化（千分位、小数位、后缀） fmt_number(columns = x, decimals = 2)
fmt_currency() 货币格式 fmt_currency(columns = price, currency = "USD")
fmt_date() 日期格式化 fmt_date(columns = date, date_style = "ydb")
fmt_scientific() 科学计数法 fmt_scientific(columns = x)
fmt_percent() 百分比 fmt_percent(columns = pct, decimals = 1)
fmt_missing() 缺失值显示文字 fmt_missing(columns = x, missing_text = "N/A")

表格样式与结构

gt_table <- gt(data) |>
  # 表头
  tab_header(
    title = "销售报表",
    subtitle = "2025年Q3"
  ) |>
  # 跨列大标题
  tab_spanner(
    label = "季度数据",
    columns = c(q1_sales, q2_sales, q3_sales, q4_sales)
  ) |>
  # 列标签重命名
  cols_label(
    product = "产品",
    q1_sales = "Q1",
    q2_sales = "Q2"
  ) |>
  # 脚注
  tab_footnote(
    footnote = "数据截至 2025-09-30",
    cells_column_labels(columns = q4_sales)
  ) |>
  # 来源
  tab_source_note("数据来源：内部 CRM 系统")

输出与导出

# 在 R Markdown / R Console 直接渲染打印
gt_table  # 交互环境直接 print 即可

# 导出为独立文件
gtsave(gt_table, "mytable.html")    # HTML（默认）
gtsave(gt_table, "mytable.tex")     # LaTeX
gtsave(gt_table, "mytable.rtf")    # RTF
gtsave(gt_table, "mytable.png", expand = 10)  # PNG 图片（expand 调分辨率）

条件格式化

gt_table |>
  data_color(
    columns = sales,
    colors = col_numeric(
      palette = c("#F8696B", "#FFEB84", "#63BE7B"),
      domain = c(0, max(data$sales))
    )
  )

典型适用场景

  • 学术论文表格：gt 支持直接输出 LaTeX，表格代码嵌入 R Markdown 后可配合 bookdown 或 rticles 各类期刊模板
  • 临床试验/生物统计报告：gt 生态里有 gtsummary（专做汇总统计表）和 pointblank（数据质量验证），三者配合是 R 统计报告的标准组合
  • 商业仪表板/HTML 报告：gt 的 HTML 输出自带 CSS 样式，可以直接嵌入 R Markdown 生成的 HTML 报告或 Shiny 应用
  • 幻灯片（Quarto/rmarkdown）：gt 表格渲染进 Quarto 幻灯片，支持 LaTeX Beamer 格式输出

生态扩展

gt 社区围绕它生长出了多个扩展包，质量和影响力都不小：

  • gtsummary：一键生成描述性统计表、回归结果表，学术写作神器
  • gtExtras：给 gt 表格加 Sparkline、条形图、堆叠图等富媒体内容
  • pointblank：数据质量验证，和 gt 搭配做「验证报告」
  • tfrmt： GSK 开发的临床报告表格模板库，专注监管提交标准
  • gto：将 gt 表格输出为 Word .docx 格式

坑与注意

⚠️ R 基础环境要求：gt 是纯 R 包，需要 R ≥ 4.1（管道操作符 |> 是 4.1+ 内置的）。依赖 dplyr、tidyr、glue 等 tidyverse 核心包。

⚠️ HTML 输出是默认的：在 RStudio Viewer 或 R Markdown HTML 文档里渲染效果最好；LaTeX 输出需要本地有 pdflatex 环境；RTF 输出兼容性一般，建议优先 HTML。

⚠️ 中文支持：gt 对 Unicode 字符（包括中文）的支持在 HTML 模式下较好，LaTeX 模式下需要文档本身加载了中文字体包（如xeCJK/luatexja），否则中文会显示异常。

⚠️ 大型表格性能：如果数据行数超过几千行，gt 的 HTML 渲染可能较慢，此时考虑先聚合数据再渲染，不要直接用原始明细数据做展示表格。

⚠️ 表格布局自由度有上限：gt 的设计哲学是「约束带来一致性」，如果你需要完全自定义的表格布局（如跨行跨列合并单元格达到 Word 表格那种自由度），gt 并不适合，这时直接用 flextable 或 officer 包更合适。

⚠️ 输出格式不是所见即所得：gt 的 HTML 输出和 LaTeX 输出的样式细节会有细微差异，如果期刊要求「提交的 LaTeX 源码能跑出同样的表格」，需要实际编译验证。

与同类对比

包 输出格式 学习曲线 定制上限 生态
gt HTML / LaTeX / RTF 中（dplyr 风格管道） 中高（语义部件系统） ⭐⭐⭐ 丰富扩展
gtsummary HTML / LaTeX 低（专做统计汇总表） 低（专注单一场景） 依赖 gt
flextable Word / PowerPoint / HTML 中 高（类似 Word 表格自由度） 独立生态
kable/knitr HTML / LaTeX 低 低（简单够用） 内置
DT HTML（交互表格） 低 中（交互筛选/排序） 独立
reactable HTML（React 组件） 中 高（自定义 CSS/JS） 独立

gt 的定位：比 kable 更强但比 flextable 更语义化，最适合已经习惯 dplyr 管道的 R 用户在 R Markdown 报告里出图。它的扩展生态（gtsummary、gtExtras）进一步覆盖了统计表和富表格场景，是目前 R 生态里最完整的表格解决方案。

一句话推荐结论

在 R Markdown / Quarto 报告里做出版级展示表格，gt 是首选；只要你在用 tidyverse，gt 的 API 会感觉非常自然——从原始 tibble 到一张带脚注、有颜色、可导出 LaTeX 的成品表格，可能不超过 15 行代码。

来源

  • https://github.com/rstudio/gt（README、工作流图）
  • https://gt.rstudio.com（官方文档站，含完整 Reference）
  • https://gt.rstudio.com/news/index.html（gt 1.0.0 发布于 2025-04-05，1.1.0 于 2025-09-23，1.2.0 于 2025-12-16）
  • https://cran.r-project.org/package=gt（CRAN 页面，维护者信息、依赖、许可证）
  • https://www.danieldsjoerger.com/gtsummary/（gtsummary 扩展包）