alt-text

编写无障碍替代文本

为此项目中的数据可视化和图像生成无障碍替代文本。

参数

• label：（可选）指定要处理的图形标签或代码块
• file：（可选）指定要处理的文件

检测项目类型

继续之前，请识别项目的上下文并阅读相关参考资料。 检查项目根目录中是否存在 _pkgdown.yml 文件，以判断是否为 pkgdown 网站：

ls _pkgdown.yml 2>/dev/null && echo "pkgdown" || echo "not pkgdown"

• pkgdown 网站（存在 _pkgdown.yml）→ 阅读 references/pkgdown.md
• Quarto 文档（不存在 _pkgdown.yml，且存在 .qmd 文件）→ 阅读 references/quarto.md

如果仍无法确定上下文，请询问用户使用的是哪种格式。

主要优势：可访问源代码

与通常只能看到图像的替代文本编写场景不同，我们可以访问生成每个图表的代码。利用这些代码提取准确的细节：

从绘图代码中提取：

• 变量映射 → 轴上变量的确切名称
• 颜色／填充映射 → 颜色编码的含义
• 绘图类型函数 → 散点图、直方图、折线图等
• 趋势线或拟合曲线 → 叠加的统计拟合结果
• 分面／子图 → 面板数量及变化的内容
• 色标 → 编码方案（顺序型、发散型、类别型）
• 轴标签和标题 → 自定义标签

从数据生成代码中提取：

• 随机分布 → 预期的分布形状
• 转换 → 对数据执行的操作
• 特征工程 → 应用的预处理
• 筛选／子集 → 展示的数据子集

从周边文字中提取：

• 代码块前后的文字解释了图表的目的和关键见解
• 章节上下文会告诉你图表旨在说明什么
• 这通常是替代文本中“关键见解”部分的最佳来源

三段式结构（Amy Cesal 公式）

1. 图表类型——开头几个词说明图表格式
2. 数据描述——坐标轴、变量及展示内容
3. 关键见解——趋势或结论（通常可从周边文字中找到）

与标题的关系

先阅读标题（fig-cap、fig.cap）。替代文本应与标题互为补充，而非重复：

• 如果标题说明了见解，替代文本可以侧重描述视觉结构
• 如果标题比较笼统，替代文本应包含关键见解
• 两者结合应能提供完整的理解

内容规则

应包含：

• 作为开头的图表类型
• 轴标签及其含义
• 代码能够揭示的具体数值／范围（例如，“峰值出现在 25–50 之间”）
• 面板／分面的数量
• 颜色／大小在有使用时所编码的信息
• 支持周边论点的关键趋势

应排除：

• “……的图像”或“展示……的图表”（屏幕阅读器会读出这些内容）
• 装饰性的颜色描述（除非颜色用于编码数据）
• 标题中已有的信息
• 实现细节（软件包名称、函数内部机制）

长度指南

复杂度	句数	适用情况
简单	2–3	单一几何图层、无分面、趋势明显
标准	3–4	多个几何图层或使用颜色编码
复杂	4–5	有分面、多个叠加层、见解细致

质量检查清单

• 以图表类型开头（散点图、直方图、分面条形图等）
• 标明坐标轴变量
• 在有帮助时包含代码中的具体数值／范围
• 陈述周边文字中的关键见解
• 与标题互为补充（而非重复）
• 对看不到图像的人来说也易于理解
• 使用通俗语言（避免“几何对象”或“美学映射”等术语）

模板示例

散点图：

Scatter chart. [X var] along the x-axis, [Y var] along the y-axis.
[Shape: linear/curved/clustered]. [Specific pattern, e.g., "peaks when X is 25–50"].
[Any overlaid fits or annotations].

直方图：

Histogram of [variable]. [Shape: right-skewed/bimodal/normal/uniform].
[If transformed: "after [transformation], the distribution [result]"].
[Notable features: outliers, gaps, multiple modes].

条形图：

Bar chart. [Categories] along the x-axis, [measure] along the y-axis.
[Key comparison: which is highest/lowest, relative differences].
[Pattern: increasing/decreasing/grouped].

瓦片／栅格图：

Tile chart [or heatmap]. [Row variable] along the y-axis, [column variable] along the x-axis.
Color encodes [what value]. [Pattern: where values are high/low].
[If faceted: "N panels showing [what varies]"].

分面图：

Faceted [chart type] with [N] panels, one per [faceting variable].
[What's constant across panels]. [What changes/varies].
[Key comparison or insight across panels].

相关性热图：

Correlation [matrix/heatmap] of [what variables]. [Arrangement].
[Overall pattern: mostly positive/negative/mixed].
[Notable clusters or strong/weak pairs].
[If relevant: contrast with expected behavior].

前后对比：

[N] [chart type]s arranged [vertically/in grid]. [Top/Left] shows [original].
[Bottom/Right] shows [transformed]. [Key difference/similarity].
[If overlay: "[color] curve shows [reference]"].

带叠加层的折线图：

[Line/Scatter] chart with overlaid [fits/curves]. [Axes].
[Number] of [lines/fits] shown: [list what each represents].
[Which fits well vs. poorly and why].

示例

代码上下文：

plotting_data |>
  ggplot(aes(value)) +
  geom_histogram(binwidth = 0.2) +
  facet_grid(name~., scales = "free_y") +
  geom_line(aes(x, y), data = norm_curve, color = "green4")

周围的文字写道：“归一化并不会让数据变得更正常”

说明文字：“归一化并不会让数据变得更正常。绿色曲线表示单位正态分布的密度。”

恰当的替代文本：

Faceted histogram with two panels stacked vertically. Top panel shows
original data with a bimodal distribution. Bottom panel shows the same
data after z-score normalization, retaining the bimodal shape. A green
normal distribution curve overlaid on the bottom panel clearly does not
match the data, demonstrating that normalization preserves distribution
shape rather than creating normality.