让屏幕阅读器也能读懂的图表:TanStack Charts键盘导航与ARIA可访问性实战
让屏幕阅读器也能读懂的图表:TanStack Charts键盘导航与ARIA可访问性实战
TanStack Charts 是一个基于 D3 原语构建的 TypeScript 可视化语法,主打响应式、可访问、服务端可渲染的图表。与"画完再补无障碍"不同,它把可访问性写进了图表契约本身:每个图表组件都要求提供 ariaLabel,SVG 根节点自动携带 image 角色与 chart roledescription,键盘导航、ARIA 通告、reduced-motion 支持全部开箱即用。本文用实战视角带你快速上手这套 图表可访问性(Accessibility) 方案。
一、给图表起个"名字":两个属性解决 80% 的问题
屏幕阅读器首先问的不是"图里有什么",而是"这是什么"。TanStack Charts 中所有 DOM 宿主与框架适配器都强制要求 ariaLabel,需要补充上下文时再加 ariaDescription:
<Chart
definition={definition}
ariaLabel="Weekly downloads for three packages"
ariaDescription="Values are seven-day totals. Missing weeks are rendered as gaps."
/>
渲染器会据此做三件事:
- SVG 渲染器:在根节点输出
role="image"、roledescription="chart",并提供<desc>元素; - Canvas 渲染器:在根节点挂上同样的 image 角色、名称与
tabIndex,5 个 canvas 子孙元素全部aria-hidden,避免重复朗读; - 命名纪律:不要把操作说明、结论和全部数据塞进一个超长的可访问名称里,名字只回答"这是什么"。
官方建议把可见标题、单位、时间范围、来源说明、摘要表格留在图表外的普通 HTML 中——它们比嵌在 SVG 里的文字更易导航、更易翻译和打印。这部分约定在 docs/guides/accessibility.md 中有完整阐述。
二、键盘导航默认行为:一张速查表
图表交互的焦点、选择与键盘策略定义在 docs/reference/focus-and-interaction.md。默认情况下,启用 keyboard 后 SVG 会带着 tabIndex(默认 0)进入 Tab 顺序,聚焦即选中第一个点,之后的键盘体验是:
| 按键 | 行为 |
|---|---|
Tab |
进入/离开图表焦点区域 |
← → ↑ ↓ |
按像素 x 再按 y 排序,在数据点间移动 |
Home / End |
跳到第一个 / 最后一个点 |
Enter / Space |
切换(固定)内置 tooltip,并触发 onSelect |
Escape |
取消已固定的 tooltip |
几个新手容易忽略的细节:
- 指针和键盘共享同一套数据契约:焦点回调无论来自鼠标还是键盘,暴露的都是同一个类型化的
ChartPoint,应用侧无需写两套逻辑; maxFocusDistance默认 48 像素,空旷区域超出该距离会清空临时焦点,避免误触;- 分组焦点:多序列对比场景使用
focus: 'group-x',键盘每次跳转的是一个语义 x 值的"代表点",tooltip 会一次性列出该组所有序列,效率远高于逐点移动; - 若应用自己接管了指针手势,可设
pointer: false关闭指针处理,键盘导航保持独立可用——这是无障碍设计的关键逃生通道。
三、tooltip 不只是"看得见",还要"读得出"
内置 tooltip(来自 @tanstack/charts/tooltip)在展示结构化标签-值表格的同时,会通过 polite 状态区(role="status" + aria-live="polite")把内容播报给屏幕阅读器。这意味着:
- 键盘用户按
Enter固定 tooltip 后,数值会被朗读出来,而不只是画在屏幕上; - tooltip 是"补充信息",不能替代标签、坐标轴、图例或数据表格——关键信息必须在不悬停时也能获得;
- 复杂自定义内容可通过适配器提供的 tooltip-body 组合面渲染,固定(pinned)表面具备非模态 dialog 语义,
Escape或dismiss()关闭后焦点会回到图表。
相关规则与更多配置见 docs/guides/tooltips-and-focus.md。
四、复杂控件:刷选、缩放、图例的键盘等价物
TanStack Charts 的官方交互控件在 SVG/Canvas DOM 宿主中自动暴露为语义化控件,而不是纯视觉覆盖层:
brushX(区间刷选):两个手柄暴露为带名称的水平滑块,方向键移动一个候选值,Home/End到范围边界,Escape撤销指针手势;handleX(刻度手柄):暴露为单个命名滑块,format结果直接成为aria-valuetext,命中区域默认 44 像素高(符合触控目标规范);zoomX(缩放平移):+/-缩放、方向键平移、Home复位、Escape取消手势,滚轮默认仅在绘图区获得焦点后才被捕获,不打断页面滚动;interactiveColorLegend(可交互图例):使用原生浏览器按钮 +aria-pressed、命名单元组与稳定焦点顺序,序列显隐状态可被完整朗读。
这些控件的"图表负责交互细节、应用负责语义状态"的边界,在 docs/guides/interactions-and-selections.md 中有系统说明。静态 SVG 导出与 React Native 环境则保留已接受的视觉绘制,需要应用自行提供等价的范围输入。
五、两条纪律:别只用颜色说话,尊重 motion 偏好
- 颜色冗余编码:把语义色与直接标签、形状/线型、排序、图例文本或选中轮廓叠加。主题无法替你判断任意数据色是否对比度达标,务必在浅色与深色模式下都实测;
- 动效克制:默认 SVG tween 与可选
motion()渲染器默认遵循prefers-reduced-motion(respectReducedMotion: true),reduced motion 下入场、更新、焦点变化直接跳到最终几何。动画只应解释状态连续性,不该延迟数值访问、无限循环或成为变化的唯一证据。详见 docs/reference/motion.md。
六、上线前 10 项可访问性检查清单
官方文档给出的验收清单非常实用,建议作为团队 checklist:
- 用纯键盘完成页面与图表的全部导航;
- 焦点可见,且导航顺序符合直觉;
- 选择、固定、缩放、编辑均可脱离指针完成;
- 数据更新后焦点与选择仍正确保持;
- 开启 reduced motion 验证无干扰动画;
- 覆盖浅色、深色、forced-colors 与放大字号场景;
- 检查可访问名称与描述内容是否恰当;
- 精确数值在悬停之外(如表格)可获得;
- 状态与错误不靠颜色单独编码;
- 用真实屏幕阅读器跑通完整任务流。
自动化工具只能发现缺失的 role 和命名,判断"表达是否正确"仍然靠人。
七、延伸阅读
- 可访问性总纲:docs/guides/accessibility.md
- 焦点与交互参考:docs/reference/focus-and-interaction.md
- 交互所有权边界:docs/guides/interactions-and-selections.md
- React 适配器实现:packages/react-charts/src/
把 ariaLabel 写对、把键盘任务跑通、把颜色冗余做好,你的图表就从"给眼睛看"升级到了"给所有人读"。



