Front-End-Checklist 空链接与失效链接修复指南：为每个 `＜a＞` 提供可访问名称

Front-End-Checklist 空链接与失效链接修复指南为每个a提供可访问名称【免费下载链接】Front-End-Checklist The essential checklist for modern web development, for humans and AI agents项目地址: https://gitcode.com/gh_mirrors/fr/Front-End-Checklist本文基于 Front-End-Checklist 仓库中的 empty-links 规则skills/empty-links/references/rule.md 及同源规则 packages/content/rules/en/accessibility/empty-links.mdx系统讲解空链接empty links的成因、危害与修复方案。读完本文你将掌握三类修复手法——可见文本、aria-label图标链接、sr-only视觉隐藏文本——并能在 React 组件、浏览器控制台审计与 axe/Lighthouse 自动检查中落地实践。什么是空链接规则定义与适用场景该规则的核心断言只有一句话Every link must have an accessible name that describes its destination or purpose每个链接都必须拥有一个描述其目标或用途的可访问名称。在 SKILL.md 的元数据中这条规则被归入accessibility类别优先级为 medium、难度为 beginner、预估耗时 15 分钟同时关联 WCAG 与 MDN 的 Accessibility 文档作为标准依据。所谓空链接指以下三类常见实现完全没有内容的a href.../a空锚点内部只有图片但没有alt的图片链接内部只有图标svg且没有任何文本或标签的图标链接。这些场景下屏幕阅读器Screen Reader只会播报出孤零零的 link 一词用户无法得知链接指向何处、执行什么操作页面导航因此变得几乎不可能。为什么空链接是致命问题屏幕阅读器的真实体验从 empty-links.mdx 的 Why It Matters 一节可以看到规则维护者给出的核心论据Screen readers announce empty links as just link with no context—users have no idea where they lead or what they do, making navigation impossible.屏幕阅读器用户通常通过快捷键调出页面上的链接列表进行跳转导航。如果页面里充斥着一堆只播报为 link 的条目这份列表就完全失去了信息量——用户必须逐一进入页面逐段阅读上下文才能猜出某个链接的用途这严重阻碍了感知、操作和理解。这正是空链接被列为无障碍a11y中高关注度问题的根本原因。空链接的典型反例三种错误写法先看规则文档给出的三个反面示例!-- ❌ Bad: Completely empty link -- a href/home/a !-- Screen reader: link (no context) -- !-- ❌ Bad: Image link with no alt -- a href/profile img srcavatar.jpg /a !-- Screen reader: link, image (no context) -- !-- ❌ Bad: Icon link with no label -- a href/settings svg.../svg /a !-- Screen reader: link (no context) --注意第二个示例的细节图片链接虽然没有alt但屏幕阅读器仍会把img作为一个可聚焦的角色播报出来于是用户听到的是 link, image——比纯空链接多了一个词但依然没有任何目的地信息。第三种纯 SVG 图标链接更隐蔽svg默认不会进入无障碍树屏幕阅读器最终播报的仍然只是孤零零的 link。修复方案一添加可见文本Visible Text最直接、最符合原生语义优先原则的修复方式是让链接拥有可见的描述性文本!-- ✅ Good: Visible link text -- a href/homeGo to homepage/a !-- ✅ Good: Image with descriptive alt -- a href/profile img srcavatar.jpg altView your profile /a给img补充描述性的alt后图片链接的可访问名称即由alt提供屏幕阅读器会播报 View your profile, link。这与仓库中另一条强相关规则 link-text.mdx 的建议一脉相承链接文本应能脱离周围语境独立描述目的地避免 Click here、Read more 这类通用措辞同时导航应使用a而非button保持正确的语义。修复方案二图标链接使用 aria-label当视觉设计不允许显示文字例如工具条图标、社交图标时使用aria-label为链接提供可访问名称并对内部的装饰性 SVG 标记aria-hiddentrue避免辅助技术重复播报!-- ✅ Good: Icon link with aria-label -- a href/settings aria-labelAccount settings svg aria-hiddentrue.../svg /a !-- ✅ Good: Social media icons -- a hrefhttps://twitter.com/company aria-labelFollow us on Twitter svg aria-hiddentrue!-- Twitter icon --/svg /a要点拆解aria-label直接覆盖override元素的无障碍名称此时即使子元素没有任何文本链接的可访问名称也是完整可用的图标本身是纯装饰aria-hiddentrue将其从无障碍树中剔除避免与aria-label产生重复播报对target_blank的外链文档在 React 组件一节中还补充了relnoopener noreferrer的安全要求。修复方案三视觉隐藏文本sr-only——想隐藏文字又不想丢语义有些场景下视觉上只想要图标但又不希望依赖aria-label比如想让可访问名称与 DOM 中真实文本保持同步、便于翻译与测试可以用视觉隐藏但辅助技术可读的.sr-only方案!-- ✅ Good: Visually hidden but screen reader accessible -- a href/cart svg aria-hiddentrue!-- Cart icon --/svg span classsr-onlyShopping cart (3 items)/span /a配套的经典 CSS 实现视觉上彻底隐藏同时保留在可访问性树中.sr-only { position: absolute; width: 1px; height: 1px; padding: 0; margin: -1px; overflow: hidden; clip: rect(0, 0, 0, 0); white-space: nowrap; border: 0; }这套 CSS 的精髓在于position: absolute配合clip: rect(0,0,0,0)将元素裁剪为 1×1px 的不可见区域overflow: hidden防止内容溢出white-space: nowrap防止文本换行撑大尺寸。它没有使用display: none或visibility: hidden——那两种方式会同时把元素从辅助技术的可访问树中移除反而违背目的。这一模式在 Front-End-Checklist 的 web 应用中有大量真实落点。例如 apps/web/components/rules/detail/mdx-components.tsx 与 apps/web/components/navigation/footer.tsx 中对所有外链统一渲染span classNamesr-only (opens in new tab)/span让target_blank的链接在保持视觉简洁的同时向屏幕阅读器说明将在新标签页打开apps/web/components/rules/listing/rule-row.tsx 用span classNamesr-onlyMark as complete / Mark as incomplete/span为纯图标操作按钮补充可访问名称design-system 的 packages/design-system/src/custom/navigation/breadcrumb.tsx 中折叠面包屑的省略号图标也通过span classNamesr-onlyMore/span获得语义。这些真实实现印证了该规则的通用价值icon-only 元素 视觉精简 sr-only 文本兜底。React 组件实践可复用的 IconLink规则文档给出了一个开箱即用的 React 组件模板将aria-label、图标隐藏与新标签页提示整合在一起interface IconLinkProps { href: string label: string icon: React.ReactNode isExternal?: boolean } function IconLink({ href, label, icon, isExternal }: IconLinkProps) { return ( a href{href} aria-label{label} target{isExternal ? _blank : undefined} rel{isExternal ? noopener noreferrer : undefined} span aria-hiddentrue{icon}/span {isExternal span classNamesr-only(opens in new tab)/span} /a ) } // Usage IconLink href/settings labelAccount settings icon{SettingsIcon /} /组件的设计要点aria-label始终作为可访问名称的最终来源与图标解耦图标包一层span aria-hiddentrue从无障碍树中剔除装饰内容外链时自动追加target_blank、relnoopener noreferrer与 sr-only 的 (opens in new tab) 提示兼顾安全性与可访问性配合上面第 5 小节 的.sr-only样式即可直接投入生产。这实际上是把仓库中 mdx-components.tsx 里外链提示的做法提炼成了可复用组件——你可以在自己的设计系统中以同样的方式封装。如何批量发现空链接浏览器控制台审计脚本对于存量项目规则文档提供了可在 DevTools Console 直接运行的探测脚本// Browser console check document.querySelectorAll(a).forEach(link { const text link.textContent?.trim() const ariaLabel link.getAttribute(aria-label) const imgAlt link.querySelector(img)?.getAttribute(alt) if (!text !ariaLabel !imgAlt) { console.warn(Empty link found:, link) } })脚本逻辑与可访问名称Accessible Name的计算规则保持一致一个链接只要满足以下三者之一即视为有名称——有非空textContent含 sr-only 文本因为视觉隐藏文本仍在 DOM 中有aria-label内部图片有alt。三者皆无则判定为空链接并输出告警。需要说明的是这是一个轻量启发式检查更完整的名称计算还应考虑aria-labelledby规则文档的check提示词中明确提到了aria-label, or aria-labelledby以及更精确的浏览器无障碍树快照。若要在页面加载后、交互前后例如弹窗打开后动态注入的链接反复检查可以把它包进setInterval或在每个交互步骤后执行。例外情况什么时候不必一刀切规则文档专门给出了三条 Exceptions提醒审查者在自动化告警面前保持工程判断以渲染后的实际体验为准交互时序、浏览器行为与辅助技术的实际输出往往决定问题严重性静态代码异味不必然等于阻断性问题按影响权重排序不是每个次要可访问性问题都值得同等的修复投入应优先处理最直接阻断感知、操作或理解的问题避免为凑规则而堆砌 ARIA如果更简单的原生语义实现例如直接写可见文本就能消除问题就不应额外加冗余标记或 ARIA。验证自动检查 人工复核自动检查使用axe DevTools或Lighthouse扫描页面axe 的link-name规则、Lighthouse 的 Links do not have a discernible name 审计都能直接命中空链接结合 link-text.mdx 的建议还可打开浏览器 DevTools 的 Accessibility 面板检查目标元素的可访问名称是否被正确计算。人工检查使用屏幕阅读器NVDA、VoiceOver、TalkBack实际导航逐个确认链接播报的内容能说明其用途检查所有图片链接是否具备alt或aria-label逐一核验纯图标链接是否拥有可访问名称如购物车、设置、关闭等图标按钮。在 Front-End-Checklist 的内容体系中这条规则与 link-text描述性链接文本、aria-labels、sensory-instructions 等条目被标记为常被同时审查的关联规则见 empty-links.mdx 的 relatedRules 元数据先确保链接不空本规则再确保链接文本有描述性link-text最后确保图标类控件统一具备可访问名称aria-labels。三者合起来才构成完整的链接可访问性闭环。【免费下载链接】Front-End-Checklist The essential checklist for modern web development, for humans and AI agents项目地址: https://gitcode.com/gh_mirrors/fr/Front-End-Checklist创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考