让SVG图标对屏幕阅读器友好:grunt-svgstore无障碍配置完全指南
让SVG图标对屏幕阅读器友好:grunt-svgstore无障碍配置完全指南
grunt-svgstore 是一款 Grunt 插件,可以把一个文件夹里的多个 SVG 图标合并成一个"图标雪碧图"(sprite),供页面通过 <use> 引用。合并后的图标如何被屏幕阅读器正确朗读?本文带你完整配置 includeTitleElement、preserveDescElement 等无障碍参数,让图标对视障用户同样友好。
先认识 grunt-svgstore:它解决什么问题
网站动辄上百个图标,每个图标单独一个 <img> 请求既慢又难维护。grunt-svgstore 的工作流程是:
- 扫描你指定的文件夹,读取其中所有
.svg源文件 - 把每个图标转成带
id的<symbol>元素,合并进一个输出 SVG - 页面中用
<svg><use xlink:href="#图标名"/></svg>即可任意复用
任务的核心实现位于 tasks/svgstore.js,其中第 67 行的 includeTitleElement: true 和第 70 行的 preserveDescElement: true 正是本文重点——它们决定了图标是否自带"可读的名字"。
为什么 SVG 图标需要无障碍配置
屏幕阅读器(如 NVDA、VoiceOver)无法"看到"画面,它只能朗读标记。对于图标雪碧图,有三层信息:
<title>:图标的可访问名称,朗读优先级高<desc>:更详细的描述,补充说明用途- 纯装饰图标:应显式标记
aria-hidden="true",避免干扰朗读流
如果雪碧图里每个 <symbol> 都没有 <title>,屏幕阅读器用户经过图标区域时只会听到一串无意义的沉默——这就是"图标不可见"的典型场景。
一键安装与最小配置
git clone https://gitcode.com/gh_mirrors/gr/grunt-svgstore
npm install grunt-svgstore --save-dev
在 Gruntfile 中加载任务(参考项目自带的 Gruntfile.js):
grunt.loadNpmTasks('grunt-svgstore');
grunt.initConfig({
svgstore: {
default: {
options: {
prefix: 'icon-' // 给每个 symbol 的 id 加前缀,避免与页面其他 id 冲突
},
files: {
'dest/icons.svg': ['svgs/*.svg']
}
}
}
});
只写上面这段,默认行为就已经是"无障碍友好"的:<title> 和 <desc> 都会保留(默认值见 tasks/svgstore.js#L59-L78)。接下来看它具体做了什么。
核心选项 1:includeTitleElement 自动生成可访问名称
| 选项 | 类型 | 默认值 | 作用 |
|---|---|---|---|
includeTitleElement |
Boolean | true |
为每个 symbol 生成 <title>,供屏幕阅读器朗读 |
preserveDescElement |
Boolean | true |
保留源文件中的 <desc> 描述元素 |
工作机制分两步:
- 优先读取源 SVG 里的
<title>文本(见 tasks/svgstore.js#L241-L250) - 源文件没有
<title>时,自动用文件名兜底
也就是说,名为 search.svg 的文件,即使内部没写 <title>,合并后也会获得"search"这个朗读名。这是非常贴心的降级策略。
💡 建议:在源 SVG 顶部写明人类可读的标题,效果最好:
<svg viewBox="0 0 100 100" xmlns="http://www.w3.org/2000/svg">
<title>搜索图标</title>
<desc>点击后打开搜索框</desc>
<path d="..."/>
</svg>
项目测试样例 test/fixtures/codepen.svg 就包含 <title>Codepen Icon</title>,其合并产物 test/expected/no_desc_element.svg 中可以看到 <desc> 被原样保留进 symbol。
何时应该关闭它们?
官方说明(README.md#L269-L281)给了明确建议:
- 当你在使用处已经自行提供了可访问名称时(例如在包裹元素上写
aria-label),才需要把includeTitleElement设为false - 完全不需要描述内容时,把
preserveDescElement设为false
对比效果可以看两个测试期望文件:关闭 title 后的输出为 test/expected/no_title_element.svg,symbol 里不再出现 <title> 节点。
核心选项 2:用 prefix 与 symbol 属性完善标记
无障碍不仅靠 <title>,还要靠"不冲突的 id"和"正确的隐藏标记":
prefix:为所有 symbol id 加前缀(如icon-),防止雪碧图 id 与页面中其他元素 id 重名——id 冲突会导致<use>引用错乱,进而让可访问名称张冠李戴symbol:给每个<symbol>批量添加属性,例如:
symbol: {
'aria-hidden': 'true', // 批量给纯装饰图标打隐藏标记
'focusable': 'false' // 阻止 IE/Edge 下 SVG 获得焦点
}
批量打 aria-hidden="true" 配合 options.symbol 是处理装饰性图标的常用手法;而功能性图标则保留 <title> 让它可读。
进阶选项:cleanup 清理内联样式
设计工具导出的 SVG 常带一堆 fill、style 内联属性,既臃肿又阻碍 CSS 统一控制颜色。相关选项:
cleanup: true:移除所有内联style;也可以传数组精细指定要删除的属性,如cleanup: ['fill', 'stroke']cleanupdefs: true:对<defs>内部也执行同样的清理(默认不动 defs,见 README.md#L166-L172)- 隐藏特性:源 SVG 中给属性加
preserve--前缀,可强制其保留到输出,例如preserve--stroke会变成普通stroke(实现见 tasks/svgstore.js#L187-L190) currentColor保护:fill或stroke的值为currentColor时,即使开启cleanup也不会被删除,让你可以用父级 CSScolor统一换色(见 test/expected/cleanup_with_currentColor.svg)
颜色统一由 CSS 控制,还能保证图标在不同背景下的对比度达标——这也是无障碍评分(WCAG 对比度要求)的一部分。
配套技巧:includedemo 生成可视验证页
开启 includedemo 后,插件会自动额外输出一份 xxx-demo.html,里面把每个图标渲染出来并附上 <use> 引用代码,方便你肉眼核对图标是否合并正确(默认模板见 tasks/svgstore.js#L22-L43)。模板数据中带有每个图标的 title 与 description,配合浏览器无障碍检查工具,可以快速验证每个 symbol 是否都能读出名字。
无障碍配置清单(快速自查)
- [ ]
includeTitleElement保持默认true,除非使用处已提供aria-label - [ ] 源 SVG 都写了有意义的
<title>(写不出来就靠文件名兜底) - [ ] 说明性描述写入
<desc>,并保持preserveDescElement: true - [ ] 使用
prefix避免 id 冲突 - [ ] 纯装饰图标通过
symbol选项批量加aria-hidden="true" - [ ] 用
cleanup清掉内联样式,颜色交给 CSS,保留currentColor - [ ] 用
includedemo生成演示页,跑一遍屏幕阅读器或开发者工具的无障碍检查
去哪里查看源码与测试
| 资源 | 路径 |
|---|---|
| 任务主逻辑(title/desc 处理) | tasks/svgstore.js#L241-L268 |
| 无障碍选项默认值 | tasks/svgstore.js#L59-L78 |
| 选项文档 | README.md#L57-L242 |
| title/desc 选项文档 | README.md#L269-L281 |
| 版本记录(0.5.0 引入无障碍选项) | CHANGELOG.md#L20-L24 |
| 单元测试 | test/svgstore_test.js#L305-L323 |
| 测试样例输入/输出 | test/fixtures/ 与 test/expected/ |
小结
grunt-svgstore 把"合并 SVG 图标"做成了自动化的一步,而 includeTitleElement 与 preserveDescElement 两个默认开启的选项,让合并产物天然携带屏幕阅读器可读的 <title> / <desc>。再配合 prefix、symbol 属性注入和 cleanup 样式清理,你就能得到一个既轻巧、可复用、又对所有人友好的图标雪碧图。