Front-End-Checklist 无障碍规则实战为可交互元素使用唯一 IDduplicate-id-active【免费下载链接】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 项目中duplicate-id-active规则规则文档页面上所有可聚焦、可交互的元素都必须拥有全局唯一的id属性。你会掌握该规则的问题模型、判别标准、修复方法以及在现代组件化框架React/Vue与动态渲染场景下的落地方案并能用浏览器辅助功能树、axe 等工具完成自动化与手动双重验证。规则是什么duplicate-id-active是 Front-End-Checklist 中优先级为high、难度为intermediate、预估耗时10 分钟的无障碍规则。它的核心断言只有一句话所有可聚焦focusable或活动active元素都必须具有唯一的id属性。这里的 active elements 特指页面上可交互的部分链接、按钮、输入框、下拉框等。之所以单独区分出来是因为这些元素是键盘焦点与辅助技术屏幕阅读器交互的核心载体——ID 一旦重复浏览器和辅助技术就无法唯一地识别它们。在仓库中这条规则同时以两种形态存在一份是 skills/duplicate-id-active/references/rule.md面向 Agent 的技能参考文档另一份是 packages/content/rules/en/accessibility/duplicate-id-active.mdx面向站点的规则内容包含结构化 frontmatter、prompts与aiContext。两者内容同源站点版额外补充了元信息例如priority: high、difficulty: intermediate、estimatedTime: 10分类位于accessibility下的document-structure子类别关联规则relatedRulesempty-heading、listitem、table-duplicate-name、lang-attribute它们同属文档结构类无障碍检查常被一起评审aiContext使用场景是审查渲染后的 HTML、交互组件或设计系统模式先检查原生语义再检查键盘行为、焦点流、可访问名称与屏幕阅读器输出在 docs/generated/rules-catalog.md 的规则目录中它也以清单项出现All focusable or active elements must have a unique ID attribute与其姊妹规则duplicate-id-ariaARIA 引用所指向的 ID 必须唯一并列。代码示例好与坏的对比!-- ✅ Good: Unique IDs for each input -- label forfirst-nameFirst Name/label input idfirst-name typetext label forlast-nameLast Name/label input idlast-name typetext !-- ❌ Bad: Duplicate IDs on active elements -- button idsubmit-btnSave/button button idsubmit-btnCancel/button !-- Error: ID must be unique --反面示例中两个按钮共享idsubmit-btn。这意味着document.getElementById(submit-btn)只能取到第一个按钮HTML 规范要求 ID 唯一浏览器遇到重复时行为未定义通常返回第一个匹配项与 ID 绑定的焦点、标签、ARIA 关系全部错位屏幕阅读器构建页面交互控件地图时第二个按钮可能直接消失或指向错误对象。注意这条规则与 packages/content/rules/en/html/unique-id.mdx 中Ensure all IDs are unique的区别unique-id要求文档内所有ID 唯一含非交互元素的锚点、区块等而duplicate-id-active聚焦于可交互元素。两者互补unique-id是更广泛的 HTML 合法性要求duplicate-id-active是把范围收敛到对用户操作影响最直接的交互控件上。同一文档结构子类别下站点还收录了duplicate-id-ariapackages/content/rules/en/accessibility/duplicate-id-aria.mdx专门约束aria-labelledby、aria-describedby、aria-controls等属性所引用的 ID。为什么重要三条故障链焦点管理失效浏览器依赖 ID 追踪当前持有焦点的元素。重复 ID 可能导致焦点丢失或移动到错误的元素上——用户敲击 Tab 后焦点跳到预期之外的控件操作对象立刻错乱。键盘导航中断纯键盘用户通过 Tab 在交互元素间移动。当两个元素共享同一个 ID 时其中一个可能变得不可达键盘焦点序列会跳过它或聚焦行为被另一个同名元素截获。这直接违反 WCAG 2.1 键盘可达性原则。辅助技术地图损坏屏幕阅读器常以 ID 为键构建页面交互控件索引。重复 ID 会污染这张地图读屏软件可能只朗读第一个同名控件或把两个控件混为一谈导致用户听到错误标签、激活错误操作。这与duplicate-id-aria的危害一致——当 ARIA 属性指向重复 ID 时屏幕阅读器可能只读取到第一个desc的内容参见 skills/duplicate-id-aria/references/rule.md 中的示例。最佳实践✅ 自动化检查在开发阶段就引入 linter 或无障碍审计工具尽早捕获重复 ID。仓库规则文档明确推荐运行 axe其内置了同名规则duplicate-id-active或 Lighthouse 等自动检查器并对 HTML 使用 W3C 验证器进行整体校验。✅ 组件化框架中使用前缀或生成式 ID组件化框架React、Vue、Web Components中最常见的重复 ID 来源是同一组件被渲染多次而内部硬编码了相同的id。对策是为组件 ID 添加唯一前缀如modal-login-title、modal-login-close这类带命名空间的 ID使用框架生成式 IDReact 的useId()为每次组件实例生成唯一 ID从根上避免多实例冲突。仓库自身的真实代码就是一个范本在 apps/web/components/rules/listing/rule-row.tsx 中RuleRow组件通过useId()生成checkboxId与contentId再拼出${checkboxId}-label用于aria-labelledby关联按钮与标题用aria-controls{contentId}关联展开按钮与内容区。同一页面渲染几十个RuleRow也不会产生 ID 冲突——这正是多实例组件必须生成式 ID的工程级印证。✅ 语义标签与for属性对齐label for必须精确匹配对应输入的id。这是表单无障碍的根基标签与控件通过 ID 建立关联重复 ID 会让标签连错对象表单对读屏用户立刻失效。参考 packages/content/rules/en/html/unique-id.mdx 中的完整表单示例first-name、last-name、email-address、message-text一一对应。框架与动态场景下的修复方案ReactuseId与自定义 HookReact 16.8 内置useId()服务端渲染与客户端渲染都能生成稳定唯一 IDimport { useId } from react function ContactForm() { const formId useId() const nameId ${formId}-name const emailId ${formId}-email return ( form id{formId} label htmlFor{nameId}Name/label input typetext id{nameId} namename / label htmlFor{emailId}Email/label input typeemail id{emailId} nameemail / /form ) } // 同一页面渲染多个实例也不会冲突 export default function ContactPage() { return ( div ContactForm / {/* IDs: :r1:-name, :r1:-email */} ContactForm / {/* IDs: :r2:-name, :r2:-email */} /div ) }不想依赖框架 API 时也可以封装自定义 Hook用useRef缓存一次生成的随机后缀保证组件生命周期内 ID 稳定不会因重渲染而变import { useRef } from react function useUniqueId(prefix id) { const idRef useRef() if (!idRef.current) { idRef.current ${prefix}-${Math.random().toString(36).substr(2, 9)} } return idRef.current }Vue实例级随机组件 IDVue 的经典做法是在组件实例上生成一次随机 ID再把字段名拼接上去script export default { data() { return { componentId: form-${Math.random().toString(36).substr(2, 9)}, formFields: [ { name: firstName, label: First Name, type: text }, { name: email, label: Email, type: email } ] } }, methods: { getFieldId(fieldName) { return ${this.componentId}-${fieldName} } } } /scriptVue 3 Composition API 下同理componentId在模块/组件作用域内生成一次tab 与 panel 的 ID 通过getTabId(tabId)/getPanelId(tabId)统一派生详见 packages/content/rules/en/html/unique-id.mdx 中的完整 tablist 示例其中aria-labelledby、aria-controls、hidden三者的 ID 关系清晰可见。原生 JavaScript动态 DOM 的唯一 ID 管理动态创建内容弹窗、动态表单、无限列表时需要一个集中的 ID 生成与登记器。仓库规则文档给出了两种实用模式递增计数器 时间戳generateUniqueId(prefix)返回${prefix}-${counter}-${Date.now()}保证同一次会话内不重复ID 登记 全页扫描验证维护Set记录已用 IDregisterID冲突即抛错validatePage()遍历document.querySelectorAll([id])用Set比对找出重复项并返回诊断报告。后者也可以直接在浏览器控制台里执行一段轻量脚本作为开发期自查工具function findDuplicateIds() { const ids {} const duplicates [] document.querySelectorAll([id]).forEach(element { const id element.id if (ids[id]) { if (ids[id] 1) duplicates.push(id) ids[id] } else { ids[id] 1 } }) return duplicates }例外与取舍不要机械修代码规则文档明确给出了三条例外原则用于避免为了合规而合规先看渲染后的实际体验交互时机、浏览器行为、辅助技术输出往往决定严重程度。静态代码扫描发现的问题不一定在真实渲染中造成同等破坏先验证再决定是否阻断发布按影响排序并非每个次级无障碍问题都值得同等权重。优先修复最直接阻碍感知、操作、理解的问题——与其纠结某个不痛不痒的重复 ID不如先解决更严重的焦点丢失或未命名控件优先原生语义不为规则加戏不要为了满足规则而添加冗余标记或 ARIA。更简单的原生实现如直接用label、button能消除问题时就不要引入额外包装。这一原则与duplicate-id-aria规则的例外条款完全一致能改底层原生元素就让 ARIA 失效问题消失而不是叠加 ARIA 去满足规则。标准依据WCAG对齐 W3C WAI 的 WCAG 概述对应 duplicate-id-active.mdx frontmatter 中的sources角色为 primary standard且强调要验证渲染后的体验而非只检查源码MDN对齐 MDN 的 Accessibility 文档同样要求以渲染结果为准。这两条标准引用意味着duplicate-id-active的合规目标不仅是源码里没有重复 ID更是用户在实际浏览器中感知不到焦点错乱、键盘不可达或标签错配。验证方法自动化检查在浏览器辅助功能树Accessibility Tree或辅助功能面板中检查目标元素的角色role、可访问名称accessible name是否正确运行 axe其内置duplicate-id-active规则或 Lighthouse 对页面做自动扫描用document.querySelectorAll([id])脚本批量核对渲染后的 HTML——注意必须检查最终渲染的 DOM而不是源文件因为组件拼接、服务端渲染、动态注入都可能引入源码中不存在的重复 ID。手动检查纯键盘测试仅用 Tab / ShiftTab 走一遍受影响 UI确认焦点顺序正确、无元素不可达、焦点不会丢失到错误位置屏幕阅读器复测若该规则影响关键交互如表单、弹窗、菜单选取一条代表性用户流程用读屏软件走一遍确认标签朗读与控件名称与视觉呈现一致。从仓库实践看这条规则的验证闭环是源码检查 渲染后 DOM 复核 键盘/读屏实测三层源码层交给 linter 与 axe渲染层用辅助功能树与脚本扫描体验层交给键盘与读屏的真人流程测试。三管齐下才能让页面上的每个按钮、输入框和链接都成为用户可识别、可到达、可操作的对象。【免费下载链接】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），仅供参考