中文书稿 ggplot 出图规范

scripts/book-plot 目录索引：纵轴竖排、出版主题、ragg 设备与空白图检查

ggplot2

书稿

Windows

Author

Harness 技术文档

Published

October 28, 2026

本目录是一套可整体复制到其他 Quarto + knitr 中文书稿 / 报告 项目的 ggplot 出图资产：出版社要求的纵轴题（自上而下、正向竖排、单位外置）、宋体出版主题、knitr ragg_png 设备、Cursor 交互预览防护，以及渲染后的近白 PNG 门禁。

长文（出版要求、图表单元顺序、源图 xlsx、图注圈号、验收）见中文书稿 ggplot 出图规范。Word 图题、表题与图号收紧是另一套资产：scripts/quarto-docx/，两者常同时使用，互不替代。

经验来源：report-tech2026 第2章、第5章 5.2 配图。

可交付文件

本目录文件	落到业务仓库	说明
`R/ylab-stack.R`	`scripts/book-plot/R/ylab-stack.R`	`split_ylab_unit` / `stack_ylab` 切词；`theme_ylab_stack` 与常量（11pt、simsun、间距）
`R/theme-tech.R`	`scripts/book-plot/R/theme-tech.R`	出版主题 `theme_tech`；须先于 `theme_ylab_stack` 叠加
`R/knitr-ragg.R`	`scripts/book-plot/R/knitr-ragg.R`	章 setup 设 `dev = "ragg_png"`、11×6 英寸
`R/httpgd-warmup.R`	`scripts/book-plot/R/httpgd-warmup.R`	可选：`.Rprofile` 里 source，防 httpgd 首帧 `depth(NULL)`
`py/check-fig-png.py`	`scripts/book-plot/py/check-fig-png.py`	渲完扫 figure 目录，近白 PNG 视为失败（需 Pillow）

原理笔记（从业务仓 topic 抽出，路径已改成本目录）：

从 harness 安装到业务项目

在 harness 仓库根：

.\scripts\powershell\Install-Harness.ps1 `
  -InstallProfile book-plot `
  -ProjectRoot "D:\path\to\your-repo"

安装只复制上表文件，不会改写 _quarto.yml、章 YAML 或 .Rprofile。参数见 Install-Harness 指南。

最小接线

章 setup chunk（顺序：设备 → 主题 → 纵轴题）：

source(here::here("scripts/book-plot/R/knitr-ragg.R"))
source(here::here("scripts/book-plot/R/theme-tech.R"))
source(here::here("scripts/book-plot/R/ylab-stack.R"))
# 项目自有缩写追加保护块（可选）
# ylab_keep <- c(ylab_keep, "NDVI")

单图（数值在左侧的柱/线）：

u <- split_ylab_unit("RD资金投入（亿元）")
p <- ggplot(df, aes(province, value)) +
  geom_col() +
  labs(x = NULL, y = stack_ylab(u$title)) +
  # 单位放在纵轴正上方，与轴标签同为 11pt / simsun
  annotate(
    "text", x = -Inf, y = Inf, label = u$unit,
    family = ylab_text_family, size = ylab_text_size_pt, size.unit = "pt",
    hjust = 0.5, vjust = -1.15
  ) +
  scale_y_continuous(expand = c(0, 0)) +
  coord_cartesian(clip = "off") +
  theme_tech +
  theme_ylab_stack +
  # 顶部留白给单位
  theme(plot.margin = margin(t = 18, r = 6, b = 6, l = 8))

分面图每面题不同时，关掉分面条，用 geom_text(x = -Inf, hjust = ylab_stack_hjust, size.unit = "pt") 写竖排题，左侧 plot.margin 用 ylab_stack_margin_l。翻转图底轴保持横排；热力图 labs(y = NULL)。细则见纵轴题笔记。

渲完检查：

python scripts/book-plot/py/check-fig-png.py report/ch2_files/figure-html report/ch2_files/figure-docx

本地验证沙盒

cd scripts\book-plot\test
Rscript Rscript/test-ylab-stack.R   # L0，任何平台
Rscript Rscript/run-l1-ragg.R       # L1，Windows（需宋体）

规程见 test/README.md。

不要拷走的东西

业务仓的分析脚本、行内 k_* 标量、章号累加逻辑。
techme::gg2xlsx：xlsx 源图导出依赖业务仓自己的包，本目录只在长文里写调用约定。
本目录 notes/、test/ 不必拷进业务仓。