Gribouille 0.3.0 深度解读：为 Typst 引入更精细的图形语法控制

背景

Gribouille 是一个专为 Typst 排版系统设计的图形库，旨在提供类似 R 语言 ggplot2 的“图形语法”（Grammar of Graphics）体验。作为一个非盈利的业余项目，Gribouille 致力于在 Typst 生态中实现灵活、声明式的数据可视化。

此次发布的 Gribouille 0.3.0 版本，虽然在功能范围上比 0.2 版本更为聚焦，但引入了多项备受期待的控制功能。该版本的核心目标是简化指南（guides，如坐标轴、图例）的控制逻辑，增强 compose() 函数的主题管理能力，并优化面积图（area charts）的默认堆叠行为。此外，版本还包含大量关于图例布局和统计计算的底层修复，旨在提升绘图的一致性和鲁棒性。

核心内容

Gribouille 0.3.0 的更新主要围绕指南控制、组合图表主题、几何对象默认行为以及底层统计修复展开。

1. 指南控制的精细化

这是本次更新最显著的变化。在 0.3.0 之前，若要隐藏坐标轴的刻度线和标签，用户必须深入 theme() 函数修改特定的元素表面。现在，用户可以直接通过 guides() 参数进行控制：

• 直接隐藏：使用 guides(x: none) 或 guides(y: none) 即可隐藏指定轴上的刻度线和标签，而坐标轴线、网格线和轴标题将保留。若需同时移除标题，需配合 labs(x: none) 使用。
• 径向坐标轴支持：在 coord-radial（径向坐标系）下，guides(theta: none) 可隐藏整个角度轴（包括圆弧、次要刻度和标签），而 guides(r: none) 仅隐藏径向刻度标签，保留径向网格线。
• 默认行为：任何未显式指定指南的美学属性（aesthetic）默认继承 none。例如，若未指定颜色图例，图例将消失，绘图区域会自动填充释放出的空间。
• 快捷指令：guides(none) 替代了已移除的 guide-none()，而 guides(auto) 则恢复默认设置。

2. compose() 函数的主题与布局革新

compose() 函数用于将多个绘图面板组合在一起，0.3.0 版本对其进行了两项重要改进：

• 主题传播：新增 theme: 参数。传入主题后，它不仅样式化组合图表的“外壳”（如共享标题、提升的图例和面板标签），还会向下传播到任何未设置独立主题的面板中。这意味着用户只需设置一次主题，即可实现全局级联，无需在每个面板中重复定义。
• defer() 辅助函数：引入了 defer() 函数来替代旧的延迟绘图语法。
  • 破坏性变更：plot(..., defer: true) 已被移除。新的写法是 defer(plot, ...)。
  • 尺寸控制：位于 compose() 内部的面板不再接受独立的 width 或 height 参数，尺寸由组合容器统一控制。

3. 面积图的默认堆叠行为

geom-area() 的默认参数发生了改变，以符合数据可视化的常见需求：

• 默认设置：现在默认启用 stat: "align" 和 position: "stack"。
• 自动对齐：stat: "align" 允许不同组别拥有不同的 x 轴断点。该统计函数会在堆叠前将各组数据重新采样到共享的网格上，因此用户无需再手动确保各组 x 值完全匹配即可实现堆叠面积图。

4. 注释溢出支持

annotate() 函数新增 clip: 参数（默认为 true）：

• 默认行为：保持原有逻辑，面板外的标记会被裁剪。
• 溢出绘制：设置 clip: false 后，即使标记位于轴范围之外，也会被绘制出来。这对于在面板外添加角落插图、锚定在数据范围外的标签或边距装饰非常有用。
• 底层修复：此前，超出范围限制的 annotate(clip: false) 会在预处理阶段被静默丢弃，0.3.0 修复了此问题，确保标记能正确渲染。

5. 底层统计与图例修复

除了新功能，版本还包含大量旨在提升一致性的修复：

• 图例布局优化：水平图例在居中对齐或右对齐时，键图（key graphic）现在会正确居中或右对齐，而不是固定在左侧。
• 连续图例网格化：guide-legend(nrow:) 和 guide-legend(ncolumn:) 现在对连续大小图例生效，使其像离散色块图例一样以网格形式布局。
• 图例标题对齐：guide-legend(align:) 现在同时对齐图例标题和条目标签。若传入无效字符串（如 "left"），会报告清晰错误而非静默忽略。
• 背景继承：legend-background 现在继承基础 rect 元素，使得 theme(rect: ...) 能正确级联到图例背景。
• 布局错误报告：当提升的图例占用过多空间导致面板无位，或左右图例覆盖标题时，系统现在会报告清晰的布局错误，而非静默重叠打印。
• 统计与变换修正：
  • stat-bin-2d 和 stat-bin-hex_density 现在计算的是单元格占总计数的比例（与 ggplot2 一致），而非未文档化的每单元格面积计数。
  • sqrt 和 log10 变换现在会验证定义域，对超出范围的数据报告清晰错误。sqrt 的反变换会将填充后的视图边界钳制在零，以确保坐标轴单调并显示 0 刻度。
  • 超出范围过滤器现在尊重 scale expand 设置，保留在扩展范围内的点和注释。反转限制（翻转坐标轴）不再导致所有行被丢弃。
  • geom-linerange() 现在正确应用其 alpha 参数。

6. 编辑器支持：Tinymist 文档字符串

发布的包现在包含对 Tinymist 友好的文档字符串。在兼容的编辑器中悬停在 Gribouille 函数上时，将显示格式化后的参数、返回值和示例，而非原始的 @ 标签注释。对于可变参数接收器（如 guides() 和 theme()），会明确列出其接受的键，方便用户查阅。

关键要点

• 指南控制简化：使用 guides(x: none) 直接隐藏刻度，无需修改主题；支持径向坐标系的精细控制。
• 主题级联：compose() 新增 theme: 参数，实现主题在组合面板间的自动传播。
• API 破坏性变更：
  • plot(..., defer: true) 替换为 defer(plot, ...)。
  • compose() 内部面板不再支持独立设置宽高。
• 面积图默认堆叠：geom-area() 默认启用对齐和堆叠，自动处理不同 x 值的组别。
• 注释溢出：annotate() 支持 clip: false，允许标记绘制在面板边界之外。
• 图例与统计修复：修复了图例对齐、连续图例网格化、统计比例计算以及坐标轴变换的定义域验证问题。
• 开发者体验：集成 Tinymist 文档字符串，提升 IDE 中的函数提示和文档可读性。

意义与影响

Gribouille 0.3.0 的发布标志着该库在 API 稳定性和易用性上的重要一步。通过引入更直观的指南控制机制，开发者可以以更少的代码实现复杂的坐标轴和图例定制，降低了学习曲线。compose()