aria-label 应加在无可见文本但需被朗读的交互元素上，如纯图标按钮、仅含SVG的链接或无label的复选框；不可用于div/span等非交互容器，否则易被忽略或误读。

aria-label 该加在哪个元素上

不是所有元素都适合加 aria-label，加错位置会导致屏幕阅读器跳过内容、重复播报，甚至被完全忽略。它只该用在**本身没有可访问文本内容**，又需要被朗读的交互元素上。

常见误用：给 <div> 或 <code><span></span> 加 aria-label，但它们默认不是可聚焦/可操作的；屏幕阅读器通常不主动读取这类容器的 aria-label，除非同时加了 role="button" 或 tabindex="0" —— 这反而暴露语义缺陷。

• ✅ 推荐场景：<button></button> 没有可见文字（比如纯图标按钮）、<a></a> 只有 SVG 图标、自定义 <input type="checkbox"> 旁边没 <label></label>
• ❌ 避免场景：<div> 包裹标题、<code><section></section>、<article></article> —— 这些该用 aria-labelledby 或真实文本节点
• ⚠️ 注意：aria-label 会**完全覆盖**元素内所有文本内容（包括子元素文本），哪怕只是多写一个空格也会让原内容失效

aria-label 和 aria-labelledby 怎么选

aria-label 是硬编码字符串，aria-labelledby 是引用页面中已有文本的 ID。选哪个，取决于内容是否动态、是否复用、是否需翻译。

• 用 aria-label：图标按钮的提示固定且简短，比如“搜索”“关闭”，不需要从 DOM 中拉取
• 用 aria-labelledby：表单字段旁有可见 <label></label>，或模态框标题是真实 <h2 id="modal-title"></h2>，直接引用更可靠、支持 i18n、避免字符串重复维护
• 冲突规则：aria-labelledby 优先级高于 aria-label，两者同时存在时后者被无视 —— 别混着写
• 性能提示：ID 引用必须真实存在，否则屏幕阅读器会静默失败（不报错，也不读），调试时用浏览器的「可访问性检查器」看「Name Computation」最准

React 里用 aria-label 容易漏掉什么

JSX 中写 aria-label 看似简单，但 React 的 props 合并逻辑和条件渲染会让它悄悄失效。


htmlppt.skill
把任意文章或文档内容转换成精美的全屏翻页 HTML 演示文件（幻灯片风格）。当用户发来一篇文章、文档链接、Markdown 内容、或粘贴的文本，并且希望生成演示用的 HTML 时触发。支持任意内容来源：iWiki 链接、KM 链接、本地文件路径、直接粘贴的文本。生成的 HTML 文件保存到本地工作区，并通过企微直接发送给用户。触发词示例：帮我把这篇文章做成PPT、转成演示文档、生成HTML幻灯片、做个演示、转成可以演示的格式、article to deck、make a slide。
下载

立即学习“前端免费学习笔记（深入）”；

• 别写成 ariaLabel —— React 不识别驼峰，必须小写连字符：aria-label（JSX 里允许引号或不引，但值必须是字符串）
• 条件渲染时注意空值：aria-label={isSearch ? "搜索" : undefined} 会导致属性被完全移除；如果想清空，得显式设为 "" 或删掉该 prop
• 组件封装陷阱：自定义 Button 组件若透传 props，但内部用了 <div role="button"> 而非原生 <code><button></button>，那 aria-label 不会自动生效，必须手动绑定到最终渲染的元素上
• SSR 注意：服务端渲染时若 aria-label 值依赖客户端状态（比如 locale），可能初渲染为空，导致首屏无障碍信息缺失

测试 aria-label 是否真起作用

不能只靠肉眼检查 HTML 属性是否存在。屏幕阅读器实际播报行为受浏览器、阅读器版本、用户设置共同影响。

• 最快验证：Chrome + NVDA（Windows）或 VoiceOver（macOS），聚焦目标元素后听播报内容；别只看 DevTools 的「Accessibility」面板，它显示的是计算出的 name，不代表实际朗读流
• 命令行检查：用 axe-core 扫描：npm run test:accessibility 或在控制台执行 axe(document)，它会报 aria-label-is-valid 和 aria-allowed-attr 类错误
• 容易被忽略的点：某些图标字体（如 Font Awesome）用伪元素生成图标，aria-label 加在父元素上没问题，但如果父元素是 <i></i> 且没设 role="img"，部分阅读器会把它当文字字符读出来（比如“f002”）
• 移动端特别注意：iOS VoiceOver 在 Safari 中对 aria-label 的支持比 Chrome 更严格，尤其是 SVG 内嵌场景，建议真机测试

最麻烦的从来不是加不加 aria-label，而是加完之后没人验证它在不同阅读器+浏览器组合下是否稳定输出预期文本——尤其当文案来自配置项或 CMS 时，一个未转义的换行符或零宽空格就足以让整段语音中断。