前端唯一 ID 检查规则实战基于 Front-End-Checklist 的 unique-id 全面指南【免费下载链接】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 仓库中的unique-id规则为绝对主体系统讲解「HTML 文档内所有 ID 属性必须唯一」这一前端基础规范的原理、代码范式与工程化落地方式。你将掌握重复 ID 对表单无障碍、ARIA 关联和 JavaScript 取元素的破坏性影响Next.js / React / Vue 中生成唯一 ID 的标准姿势以及本仓库 MCP 服务中基于正则启发式与 AST 结构检测的双层自动校验实现。规则速览unique-id规则在本仓库中定位为priority: high高优先级、difficulty: beginner入门难度、预计耗时 10 分钟归属于html大类下的document-structure文档结构子类。规则核心要求一句话即可概括All ID attributes are unique within the document. No duplicate IDs exist on the page.文档内所有 ID 属性唯一页面上不存在重复 ID。四条快速参考要点每个 ID 在同一份 HTML 文档中只能出现一次样式用 classID 只用于唯一锚点 / 引用警惕组件库引入的重复 ID重复 ID 会破坏表单标签、ARIA 和getElementById规则完整定义位于 packages/content/rules/en/html/unique-id.mdx面向 AI Agent 的技能封装位于 skills/unique-id/SKILL.md其详细技术参考见 skills/unique-id/references/rule.md。为什么 ID 必须唯一重复 ID 会引发三类静默故障——代码不报错但行为悄然出错表单无障碍断裂label forx通过 ID 与表单控件建立关联。当存在两个idx时标签无法确定连接哪个控件屏幕阅读器朗读的表单字段名错乱用户无法理解输入项含义。ARIA 关系失效aria-labelledby、aria-controls、aria-describedby等属性全部依赖 ID 引用。ID 重复后辅助技术会引用到错误的元素弹窗、标签页、菜单的无障碍语义全部失联。JavaScript 取错元素document.getElementById(x)按规范只返回文档中第一个匹配元素。重复 ID 会让脚本悄悄操作错误节点引发难以排查的 bug。规范 HTML 示例!DOCTYPE html html langen head titleUnique IDs Example/title /head body header idmain-header h1Site Title/h1 /header nav idmain-navigation ul lia href#section-1Section 1/a/li lia href#section-2Section 2/a/li /ul /nav main section idsection-1 h2First Section/h2 /section section idsection-2 h2Second Section/h2 /section /main /body /html注意这里的href#section-1锚点跳转同样依赖 ID 唯一性——页面内锚点定位在重复 ID 场景下同样会跳到错误位置。表单标签与 ID 关联每个label for...必须精确对应一个唯一id这是表单无障碍的基石form div label forfirst-nameFirst Name/label input typetext idfirst-name namefirstName required /div div label forlast-nameLast Name/label input typetext idlast-name namelastName required /div div label foremail-addressEmail/label input typeemail idemail-address nameemail required /div div label formessage-textMessage/label textarea idmessage-text namemessage rows4/textarea /div /formARIA 与无障碍 ID 关系ARIA 的引用型属性aria-labelledby、aria-controls、aria-describedby等以 ID 为指针标签页与菜单弹层是最典型的场景section aria-labelledbyproducts-heading h2 idproducts-headingOur Products/h2 div roletablist aria-labelledbyproducts-heading button roletab aria-controlselectronics-panel aria-selectedtrue idelectronics-tab Electronics /button button roletab aria-controlsclothing-panel aria-selectedfalse idclothing-tab Clothing /button /div div roletabpanel aria-labelledbyelectronics-tab idelectronics-panel pElectronics content.../p /div div roletabpanel aria-labelledbyclothing-tab idclothing-panel hidden pClothing content.../p /div /section !-- Modal with proper ID relationships -- button aria-controlsuser-menu aria-expandedfalse iduser-menu-button User Menu /button ul iduser-menu rolemenu aria-labelledbyuser-menu-button hidden li rolemenuitema href/profileProfile/a/li li rolemenuitema href/settingsSettings/a/li li rolemenuitema href/logoutLogout/a/li /ul可以看到electronics-tab与electronics-panel之间通过aria-controls/aria-labelledby双向互引任何一侧的 ID 重复都会让整个标签页语义崩溃。框架实战Next.js / React 的 useId组件复用是重复 ID 最常见的来源同一个表单组件被渲染多次如果硬编码idname页面就会产出多个相同 ID。React 官方给出的标准答案是useId()import { useId } from react function ContactForm() { // 为当前组件实例生成唯一 ID 前缀 const formId useId() const nameId ${formId}-name const emailId ${formId}-email const messageId ${formId}-message return ( form id{formId} div label htmlFor{nameId}Name/label input typetext id{nameId} namename / /div div label htmlFor{emailId}Email/label input typeemail id{emailId} nameemail / /div div label htmlFor{messageId}Message/label textarea id{messageId} namemessage / /div /form ) } // 多个实例不会产生 ID 冲突 export default function ContactPage() { return ( div ContactForm / {/* IDs: :r1:-name, :r1:-email, :r1:-message */} ContactForm / {/* IDs: :r2:-name, :r2:-email, :r2:-message */} /div ) }useId()生成的是形如:r1:、:r2:的全局唯一前缀每个组件实例都不同且保证客户端 / 服务端渲染SSR一致性不会产生水合不匹配。本仓库的 Web 应用就在真实使用这一模式见 apps/web/components/rules/listing/rule-row.tsx组件用useId()生成checkboxId与contentId再拼出${checkboxId}-label用于表单标签关联这正是规则在仓库内的自证实例。React 自定义 HookuseUniqueId当useId的冒号前缀不满足命名需求如需要可读的 DOM 类名或 CSS 定位时可以用自定义 Hook 封装一套组件级唯一 ID 生成逻辑import { useRef } from react // 自定义 hook为组件实例生成唯一 ID function useUniqueId(prefix id) { const idRef useRef() if (!idRef.current) { idRef.current ${prefix}-${Math.random().toString(36).substr(2, 9)} } return idRef.current } function FormField({ label, type text, name, ...props }) { const fieldId useUniqueId(field-${name}) return ( div classNameform-field label htmlFor{fieldId}{label}/label input type{type} id{fieldId} name{name} {...props} / /div ) } // 用法确保每个字段 ID 唯一 function UserForm() { return ( form FormField labelUsername nameusername / FormField labelEmail nameemail typeemail / FormField labelPassword namepassword typepassword / /form ) }核心技巧是借用useRef的跨渲染缓存能力组件首次渲染时生成随机后缀并缓存此后所有渲染返回同一个 ID保证稳定性又避免手动维护计数器。Vue.jsOptions API 与 Composition APIVue 侧没有内置的useId通用的做法是组件实例化时基于随机串生成一个componentId前缀再拼接各字段名。Options APItemplate form div v-forfield in formFields :keyfield.name label :forgetFieldId(field.name){{ field.label }}/label input :typefield.type :idgetFieldId(field.name) :namefield.name v-modelformData[field.name] / /div /form /template script export default { data() { return { componentId: form-${Math.random().toString(36).substr(2, 9)}, formFields: [ { name: firstName, label: First Name, type: text }, { name: lastName, label: Last Name, type: text }, { name: email, label: Email, type: email } ], formData: {} } }, methods: { getFieldId(fieldName) { return ${this.componentId}-${fieldName} } } } /scriptComposition APIscript setup写法更紧凑标签页组件是最佳演示场景template div h2 :idheadingIdProduct Reviews/h2 div roletablist :aria-labelledbyheadingId button v-fortab in tabs :keytab.id :idgetTabId(tab.id) :aria-controlsgetPanelId(tab.id) :aria-selectedactiveTab tab.id clickactiveTab tab.id {{ tab.label }} /button /div div v-fortab in tabs :keytab.id :idgetPanelId(tab.id) :aria-labelledbygetTabId(tab.id) :hiddenactiveTab ! tab.id {{ tab.content }} /div /div /template script setup import { ref } from vue const componentId reviews-${Math.random().toString(36).substr(2, 9)} const headingId ${componentId}-heading const activeTab ref(recent) const tabs [ { id: recent, label: Recent Reviews, content: Recent reviews content... }, { id: helpful, label: Most Helpful, content: Helpful reviews content... }, { id: critical, label: Critical Reviews, content: Critical reviews content... } ] const getTabId (tabId) ${componentId}-tab-${tabId} const getPanelId (tabId) ${componentId}-panel-${tabId} /script原生 JavaScript 动态 ID 管理纯前端动态生成 DOM 时必须自己管理 ID 的唯一性。以下两段代码演示了生产级的两种策略递增计数器 时间戳以及 Set 登记 冲突检测。策略一ComponentManager自增 时间戳class ComponentManager { constructor() { this.componentCounter 0 } generateUniqueId(prefix component) { return ${prefix}-${this.componentCounter}-${Date.now()} } createFormField(label, type text, name) { const fieldId this.generateUniqueId(field) const container document.createElement(div) container.className form-field const labelEl document.createElement(label) labelEl.htmlFor fieldId labelEl.textContent label const input document.createElement(input) input.type type input.id fieldId input.name name container.appendChild(labelEl) container.appendChild(input) return { container, input, label: labelEl } } createModal(title, content) { const modalId this.generateUniqueId(modal) const headingId this.generateUniqueId(modal-heading) const closeButtonId this.generateUniqueId(modal-close) const modal document.createElement(div) modal.id modalId modal.setAttribute(role, dialog) modal.setAttribute(aria-labelledby, headingId) modal.setAttribute(aria-modal, true) modal.innerHTML div classmodal-content header h2 id${headingId}${title}/h2 button id${closeButtonId} aria-labelClose modaltimes;/button /header div classmodal-body ${content} /div /div // Add close functionality modal.querySelector(#${closeButtonId}).addEventListener(click, () { modal.remove() }) return modal } } // Usage const manager new ComponentManager() // 创建多个表单也不会产生 ID 冲突 const userForm manager.createFormField(Username, text, username) const emailForm manager.createFormField(Email, email, email) document.body.appendChild(userForm.container) document.body.appendChild(emailForm.container)策略二IDManagerSet 登记 页面级校验class IDManager { constructor() { this.usedIds new Set() } isIdUnique(id) { return !this.usedIds.has(id) !document.getElementById(id) } registerID(id) { if (!this.isIdUnique(id)) { throw new Error(ID ${id} is already in use) } this.usedIds.add(id) return id } generateUniqueId(prefix auto) { let counter 1 let id ${prefix}-${counter} while (!this.isIdUnique(id)) { counter id ${prefix}-${counter} } this.registerID(id) return id } removeID(id) { this.usedIds.delete(id) } validatePage() { const elements document.querySelectorAll([id]) const foundIds new Set() const duplicates [] elements.forEach(element { const id element.id if (foundIds.has(id)) { duplicates.push(id) } else { foundIds.add(id) } }) return { valid: duplicates.length 0, duplicates, totalElements: elements.length, uniqueIds: foundIds.size } } } // Usage const idManager new IDManager() // 安全生成 ID const uniqueId idManager.generateUniqueId(my-component) const element document.createElement(div) element.id uniqueId // 校验整个页面 const validation idManager.validatePage() if (!validation.valid) { console.error(Duplicate IDs found:, validation.duplicates) }IDManager.validatePage()返回{ valid, duplicates, totalElements, uniqueIds }结构化结果非常适合挂到调试工具或测试断言上。CSS 与 ID 选择器ID 选择器的特异性specificity远高于 class因此文档建议样式交给 classID 只作唯一锚点。但在必须针对唯一元素书写样式的场景下保持 ID 命名语义化同样重要/* 针对唯一元素的样式 */ #main-header { background-color: #333; color: white; padding: 1rem; } #main-navigation ul { list-style: none; display: flex; gap: 1rem; } /* 表单样式 */ #contact-form { max-width: 600px; margin: 0 auto; } #contact-form label { display: block; margin-bottom: 0.5rem; font-weight: bold; } #contact-form input, #contact-form textarea { width: 100%; padding: 0.5rem; border: 1px solid #ccc; border-radius: 4px; } /* 状态相关样式依赖 ID 配合 ARIA 状态 */ #user-menu[aria-expandedtrue] { display: block; } #user-menu[aria-expandedfalse] { display: none; }常见问题与解决方案❌ 重复 ID!-- Bad: Same ID used multiple times -- div idcontentFirst content/div div idcontentSecond content/div script // 只会选中第一个元素 const content document.getElementById(content) /script✅ 唯一且描述性的 ID!-- Good: Unique, descriptive IDs -- div idmain-contentMain page content/div div idsidebar-contentSidebar content/div script const mainContent document.getElementById(main-content) const sidebarContent document.getElementById(sidebar-content) /script❌ 泛化或含义不明的 ID!-- Bad: Not descriptive -- div iddiv1.../div div idbox.../div input idinput1✅ 语义清晰的 ID!-- Good: Clear purpose -- div idproduct-gallery.../div div idshopping-cart-summary.../div input idsearch-query typesearch工具与验证HTML 验证器使用 W3C 的 Nu Html Checkervalidator.w3.org/nu对最终渲染出的 HTML 进行校验重复 ID 会以硬错误error级别报出。注意必须验证浏览器实际渲染后的标记而不是源码框架抽象。浏览器 DevTools 控制台在浏览器 Console 中粘贴以下函数立即扫出页面上的重复 ID// 在控制台检查重复 ID 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 } console.log(Duplicate IDs:, findDuplicateIds())自动化测试Jest将 ID 唯一性断言纳入测试套件防止回归// Jest 测试所有 ID 必须唯一 describe(Page HTML validation, () { test(all IDs should be unique, () { const elements document.querySelectorAll([id]) const ids Array.from(elements).map(el el.id) const uniqueIds [...new Set(ids)] expect(ids.length).toBe(uniqueIds.length) }) })最佳实践清单使用描述性名称user-profile-form而非form1遵循命名约定HTML 用 kebab-caseJavaScript 用 camelCase对关联元素做命名空间化modal-login、modal-login-title、modal-login-close开发期即校验用 linter 和验证器尽早捕获重复注释复杂的 ID 关系在代码中记录 ID 的引用网络仓库内的工程化落地MCP 自动检测实现Front-End-Checklist 仓库不仅是规则文档库还把该规则落进了自动化检测管线——frontend-checklist/mcp包的review_code工具内置了对unique-id的检测采用正则启发式 AST 结构检测双层架构第一层正则启发式packages/mcp/src/tools/review-code.ts// Unique IDs check — 只提取 ID 值而非完整属性字符串以准确去重 if (slug.includes(unique-id)) { const ids ...code.matchAll(/id\s*\s*[[]/gi)].map(m m[1].toLowerCase()) const seen new Setstring() const dupes new Setstring() for (const id of ids) { if (seen.has(id)) dupes.add(id) else seen.add(id) } if (dupes.size 0) { return { hasIssue: true, issue: Duplicate ID values found: ${[...dupes].slice(0, 3).join(, )} } } }关键实现细节正则只捕获id...引号内的值而非整串属性匹配后统一转小写再放入 Set 去重命中的重复值最多上报前 3 个保证报错信息紧凑可读。第二层AST 结构检测packages/mcp/src/tools/review-code.ts// ── duplicate IDs: same id value used on multiple elements const idCounts new Mapstring, number() for (const el of root.querySelectorAll([id])) { const id (el.getAttribute(id) ?? ).toLowerCase() if (!id || id.includes({) || id.includes(})) continue idCounts.set(id, (idCounts.get(id) ?? 0) 1) } const dupeIds [...idCounts.entries()].filter(([, count]) count 1).map(([id]) id) if (dupeIds.length 0) { issues.set(unique-id, Duplicate ID values found: ${dupeIds.slice(0, 3).join(, )}) }这一层将输入解析为 DOM 树后遍历所有[id]元素做精确计数并且主动跳过含{或}的 ID——这正是 JSX 动态表达式如id{category}的形态特征避免对同一模板动态渲染出不同 ID的合法代码产生误报。测试保障packages/mcp/tests/unit/review-code-detection.test.ts用两个用例锁定了检测器的行为边界it(does not flag unique-id when all IDs are distinct, () { const html htmlbodydiv idheaderA/divdiv idmainB/divdiv idfooterC/div/body/html expect(noIssuesIn(html, unique-id)).toBe(true) }) it(does not flag unique-id for dynamic JSX id expressions, () { const jsx export function Section({ category }: { category: string }) { return div id{category}Section/div } expect(noIssuesIn(jsx, unique-id)).toBe(true) })此外该规则还纳入了 packages/mcp/tests/unit/false-positive-audit.test.ts 的误报审计和 packages/mcp/tests/unit/heuristic-coverage.test.ts 的启发式覆盖率矩阵确保它在真实代码上既不漏报也不误报。验证清单自动化检查在浏览器或页面源码中检查最终渲染的 HTML确认规则被满足用浏览器工具或 HTML 验证器校验受影响标记至少测试一个使用该模式的代表性路由 / 模板重新检查所有输出相同标记的共享组件确保修复一致手动检查在代表性路由和受支持浏览器上手动验证渲染后的浏览器行为确保用户可见结果符合规则关联规则unique-id常与以下同属html/document-structure区域的规则一起评审可在 packages/content/rules/en/html/ 目录下继续查阅doctype文档类型声明duplicate-id-active重复 ID 与tabindex聚焦冲突navigation-landmark导航地标结构listitem列表项语义w3c-compliant整体 W3C 合规性其中duplicate-id-active与本文规则最易混淆unique-id关注 ID 本身的唯一性而duplicate-id-active关注重复 ID 是否导致页面多个可聚焦元素共享同一 ID 引发的键盘 / 焦点混乱。二者配套使用可以完整覆盖 ID 相关的无障碍风险面。总结唯一 ID 是 HTML 有效性的硬性要求也是表单、ARIA 与 JavaScript 三者协作的寻址系统。在组件化框架时代重复 ID 主要来自组件复用的隐性输出因此正确姿势是用框架原生能力ReactuseId或组件级前缀策略Vue 组合 API / 自定义 Hook从源头保证唯一再用验证器、DevTools 脚本与自动化测试兜底。本仓库的unique-id规则文档与 MCP 双层检测实现为这套方法论提供了文档 代码 测试的完整闭环参考可直接迁移到你的前端工程质量体系中。【免费下载链接】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），仅供参考