让屏幕阅读器也能读懂的图表:TanStack Charts键盘导航与ARIA可访问性实战

原创2026-10-25 12:54:46672 阅读

让屏幕阅读器也能读懂的图表:TanStack Charts键盘导航与ARIA可访问性实战

TanStack Charts 是一个基于 D3 原语构建的 TypeScript 可视化语法,主打响应式、可访问、服务端可渲染的图表。与"画完再补无障碍"不同,它把可访问性写进了图表契约本身:每个图表组件都要求提供 ariaLabel,SVG 根节点自动携带 image 角色与 chart roledescription,键盘导航、ARIA 通告、reduced-motion 支持全部开箱即用。本文用实战视角带你快速上手这套 图表可访问性(Accessibility) 方案。

TanStack Charts 可访问柱状图:当前焦点高亮与状态文本让屏幕阅读器可朗读

一、给图表起个"名字":两个属性解决 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

几个新手容易忽略的细节:

  1. 指针和键盘共享同一套数据契约:焦点回调无论来自鼠标还是键盘,暴露的都是同一个类型化的 ChartPoint,应用侧无需写两套逻辑;
  2. maxFocusDistance 默认 48 像素,空旷区域超出该距离会清空临时焦点,避免误触;
  3. 分组焦点:多序列对比场景使用 focus: 'group-x',键盘每次跳转的是一个语义 x 值的"代表点",tooltip 会一次性列出该组所有序列,效率远高于逐点移动;
  4. 若应用自己接管了指针手势,可设 pointer: false 关闭指针处理,键盘导航保持独立可用——这是无障碍设计的关键逃生通道。

TanStack Charts 可交互柱状图:支持指针与键盘等价操作的演示

三、tooltip 不只是"看得见",还要"读得出"

内置 tooltip(来自 @tanstack/charts/tooltip)在展示结构化标签-值表格的同时,会通过 polite 状态区(role="status" + aria-live="polite")把内容播报给屏幕阅读器。这意味着:

  • 键盘用户按 Enter 固定 tooltip 后,数值会被朗读出来,而不只是画在屏幕上;
  • tooltip 是"补充信息",不能替代标签、坐标轴、图例或数据表格——关键信息必须在不悬停时也能获得;
  • 复杂自定义内容可通过适配器提供的 tooltip-body 组合面渲染,固定(pinned)表面具备非模态 dialog 语义,Escape 或 dismiss() 关闭后焦点会回到图表。

TanStack Charts 图表 tooltip 演示:屏幕阅读器可通过 ARIA 状态区朗读提示内容

相关规则与更多配置见 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 环境则保留已接受的视觉绘制,需要应用自行提供等价的范围输入。

TanStack Charts 可访问折线图:焦点环、十字线与 ARIA 描述协同工作的演示

五、两条纪律:别只用颜色说话,尊重 motion 偏好

  • 颜色冗余编码:把语义色与直接标签、形状/线型、排序、图例文本或选中轮廓叠加。主题无法替你判断任意数据色是否对比度达标,务必在浅色与深色模式下都实测;
  • 动效克制:默认 SVG tween 与可选 motion() 渲染器默认遵循 prefers-reduced-motion(respectReducedMotion: true),reduced motion 下入场、更新、焦点变化直接跳到最终几何。动画只应解释状态连续性,不该延迟数值访问、无限循环或成为变化的唯一证据。详见 docs/reference/motion.md。

六、上线前 10 项可访问性检查清单

官方文档给出的验收清单非常实用,建议作为团队 checklist:

  1. 用纯键盘完成页面与图表的全部导航;
  2. 焦点可见,且导航顺序符合直觉;
  3. 选择、固定、缩放、编辑均可脱离指针完成;
  4. 数据更新后焦点与选择仍正确保持;
  5. 开启 reduced motion 验证无干扰动画;
  6. 覆盖浅色、深色、forced-colors 与放大字号场景;
  7. 检查可访问名称与描述内容是否恰当;
  8. 精确数值在悬停之外(如表格)可获得;
  9. 状态与错误不靠颜色单独编码;
  10. 用真实屏幕阅读器跑通完整任务流。

自动化工具只能发现缺失的 role 和命名,判断"表达是否正确"仍然靠人。

七、延伸阅读

把 ariaLabel 写对、把键盘任务跑通、把颜色冗余做好,你的图表就从"给眼睛看"升级到了"给所有人读"。

登录后查看全文
charts