FAQ

常见问题

适用版本：v1.1.0。首页 · 快速入门

安装后为什么仍提示 Unknown key？

先运行 kpsewhich gradbars.sty 并查看日志中的日期和版本。项目旁旧模块会覆盖新安装。必须同时更新全部 22 个 .sty 文件，不要混装版本。可选接口还需在导言区加载对应库，如 \usegradbarslibrary{distribution,legend,reports}。

每个单元格都要重复选项吗？

不需要。普通表格用 \gradbarscolumn*{G}{max=1,width=18mm,precision=3} 后，数字列只填数值，表头用 \gradbarshead。也可用 \gradbarssetup 复用设置，或选择原生 gradtable。完整示例

图例为什么出现 missing？

它是默认显示的缺失值说明，并非编译错误。若当前图例无需该项，在 \gradheatlegend 或 \gradlegenduse 中设置 legend missing=false。实际数据中的 NA 不会因此变成零或被补齐。

两端配色能自定义吗？

可以，设置 heat low color、heat center color 和 heat high color。也可直接用 heat palette=purple-teal 等八种预设；显式颜色放在预设之后可覆盖它。配色与共享图例

表格间距大、图形太小怎么办？

先调整 column sep、row stretch、row padding，以及文本/图形/标签宽度。哑铃可用 track color=black!40,stem width=.9pt 增强轨道和连线。箱线图可增加 height，但极端离群值压缩箱体是线性尺度效果，不宜静默删去离群点。

同列图形为何不能直接比较？

同一指标需要相同范围和图形尺寸。用固定 min/max、scale=column 或命名 scale group。每行自动趋势范围主要比较形状；跨表使用命名固定尺度。只有在保留共同零点时，条长才直接表示从零开始的大小。

缺失值、空白和零有什么区别？

零是有效观测，参与范围、排名和汇总；NA 是缺失。普通收集列的星号接口将字面空白保留为空，不发出缺失图形；无星号接口保留旧行为，将空输入按缺失处理。原生表格仍应按列提供字段。

百分比和单位会改变原始统计吗？

格式化不改变原始数据。unit 附加单位文字；value format=percent 表示相对于百分比基数的比例，默认基数为 max。百分比要求 min=0 和有效正基数；自动范围扩展与显式 percent base 规则见手册。不能把单位或公式混入数字字段。

CSV 支持科学计数或筛选排序吗？

支持十进制和 e/E 科学计数数值，支持 data/source 绑定及筛选、稳定排序、limit、汇总。表头须唯一且非空；含逗号字段用双引号；只支持单行字段。字段按字符读取，不执行 TeX。表格与 CSV

long=true 为什么不能放进 table 浮动体？

跨页表格需放在单栏正文中，不能放入浮动体或 minipage。普通非跨页表格可用 center 或浮动体居中。重复图形表头和 Tagged PDF 结构另有工具链约束。

自动替代文本和完整表格标记是一回事吗？

不是。图形自动描述需要文档先启用 PDF tagging。完整 tabularray 结构需显式启用 \gradtblrtagging，指定表头和语义；带重复表头的 tagged longtblr 需要 LuaLaTeX。图形有替代文本不代表整份文档符合 PDF/UA。无障碍范围

报告问题需要提供什么？

在 Issues 提供版本与日期、实际加载路径、引擎和发行版、最小完整文档、必要的模拟 CSV 及错误日志。