让图标对屏幕阅读器友好:Reicon无障碍实践中的ARIA与焦点管理完整清单
让图标对屏幕阅读器友好:Reicon无障碍实践中的ARIA与焦点管理完整清单
Reicon 是一个面向设计师与开发者的开源图标库,它的各框架组件(React、Vue、Svelte 等)和 CDN 自定义元素都把 ARIA 属性透明传递到 SVG,让图标无障碍(a11y)只需两三个属性就能搞定。本文用一份完整清单讲清:何时用 aria-hidden 隐藏图标、何时用 aria-label 给图标朗读名称,以及如何通过 forwardRef 和 tabIndex 做好焦点管理——帮助视障用户用屏幕阅读器顺畅地使用你的界面。
为什么图标需要特别处理无障碍
对普通用户来说,图标是"看一眼就懂"的;但对屏幕阅读器(如 VoiceOver、NVDA、TalkBack)用户,SVG 图形默认就是一团"图形噪声"——要么被跳过,要么被读出毫无意义的内部元素名。
图标在无障碍语境里通常分两类:
| 类型 | 例子 | 正确做法 |
|---|---|---|
| 装饰性图标 | 文字按钮旁边的箭头、装饰星星 | 用 aria-hidden="true" 完全隐藏 |
| 信息性图标 | 红色警告三角、纯图标关闭按钮 | 用 role="img" + aria-label 读出语义 |
Reicon 官方无障碍指南把这四类场景归纳得非常清楚,可以直接照抄模式:docs/shared/accessibility.md。
Reicon 的无障碍底座:所有属性直通 SVG
Reicon 无障碍体验好用的根本原因,在于组件实现本身:
- React 版的每个图标都由
forwardRef工厂生成,除size、color、weight等内置属性外,其余所有 props(包括aria-label、role、tabIndex)通过...rest原样展开到<svg>元素上。实现见 packages/reicon-react/src/createIcon.js。 - CDN 自定义元素更进一步,内置了无障碍逻辑:写
decorative属性会自动加上aria-hidden="true";写label属性会自动设置role="img"和aria-label,不写时默认朗读图标名。核心逻辑在 apps/web/public/cdn/reicon.js 的_applyA11y()方法中。 - Vue、Svelte、Astro 等版本的属性表均包含
ref转发,官方属性参考:docs/shared/props.md。
这意味着你不需要任何"无障碍包装器",标准 HTML 属性写上去即生效。
三类场景的 ARIA 用法清单
装饰性图标:aria-hidden 一键隐藏
当图标只是视觉点缀、旁边已经有文字说明时,让屏幕阅读器跳过它,避免重复播报:
<button>
<Home size={20} aria-hidden="true" />
设置
</button>
信息性图标:role="img" + aria-label 让屏幕阅读器朗读
当图标独立传达含义(没有伴随文字)时,给它一个可读标签:
<AlertTriangle size={20} color="#ef4444" role="img" aria-label="警告" />
纯图标按钮:标签加在 button 上,而不是图标上
这是新手最容易犯错的场景。正确做法是给按钮加 aria-label,同时把内部图标隐藏,防止"图标 + 按钮"双重朗读:
<button aria-label="关闭对话框">
<X size={20} aria-hidden="true" />
</button>
💡 记住口诀:有文字藏图标,没文字给标签;按钮类,标签给按钮。
焦点管理:forwardRef 与 tabIndex 的正确打开方式
键盘用户同样依赖图标。Reicon 组件全部支持 forwardRef,你可以把 ref 挂到底层 SVG 上,配合 tabIndex、onFocus 等标准属性完成焦点管理:
const iconRef = useRef(null);
return <Star ref={iconRef} size={24} tabIndex={0} />;
几个实用要点:
- 可交互的图标(如可直接点选的收藏星):加
tabIndex={0}进入 Tab 序列,并配role+aria-label说明可执行的动作。 - 纯展示图标:不要加
tabIndex,避免键盘用户被迫经过一堆无意义焦点。 - 需要程序化聚焦(如弹窗打开时移焦到图标按钮)时,通过 ref 调用
element.focus()即可。 - 官方 Tip:由于 props 全部透传,
focusable、onFocus等任何标准 SVG/ARIA 属性都可直接使用。
完整页面实现可参考官方无障碍文档页:apps/web/src/pages/docs/guides/accessibility/Accessibility.tsx。
Reicon 官网自身的实践参考
Reicon 图标站本身就是一份无障碍范本,两个值得学习的细节:
- 图标卡片:每个图标是一个链接卡片,链接上写
aria-label={name},让屏幕阅读器读出图标名(如 "Star"),实现见 apps/web/src/components/ui/IconCard.tsx。 - 加载占位骨架:数据未加载时的闪烁占位元素统一加
aria-hidden="true",保证过渡态不产生噪声播报,见 apps/web/src/lib/IconRenderer.tsx。
发布前自检清单 ✅
上线前花一分钟对照检查:
- [ ] 所有装饰性图标都加了
aria-hidden="true" - [ ] 所有独立传达信息的图标都有
role="img"+ 有意义的aria-label - [ ] 纯图标按钮的
aria-label写在<button>上,内部图标已隐藏 - [ ] 可交互图标有
tabIndex,装饰图标没有意外进入 Tab 序列 - [ ] 占位/骨架屏等过渡元素均已
aria-hidden - [ ] CDN 用户:装饰图标用了
decorative属性,语义图标用了label属性 - [ ] 用浏览器键盘模式 + 一款屏幕阅读器(或 DevTools 无障碍审计)实测一遍
写在最后
图标无障碍的核心其实很朴素:装饰就藏,语义就读,交互就聚焦。Reicon 把 ARIA 属性全部透传到底层 SVG,让这套心智模型在所有框架下保持一致——无论是 React、Vue、Svelte 还是 CDN 直接引用,一份清单即可覆盖全部场景。把上面 7 项自检清单贴进你的 Code Review 模板,你的图标界面就能对每一位屏幕阅读器用户友好起来。
更多背景资料可参考仓库文档目录 docs/ 与无障碍专题 docs/shared/accessibility.md。