使用导航地标区域Navigation Landmark为无障碍与 AI Agent 构建可跳转的页面导航结构【免费下载链接】Front-End-Checklist The essential checklist for modern web development, for humans and AI agents项目地址: https://gitcode.com/gh_mirrors/fr/Front-End-Checklist导航地标landmark是屏幕阅读器用户理解页面结构、快速跳转到不同导航区域的核心机制。本文基于 Front-End-Checklist 仓库中navigation-landmark规则skills/navigation-landmark/SKILL.md的完整实现文档展开结合仓库内 header.tsx、footer.tsx、table-of-contents.tsx 等真实组件源码讲解如何用nav元素配合 ARIA 标签区分多个导航区域并给出可复制的 HTML、React、Next.js 实战代码与验证清单。读完本文你将掌握导航地标的语义、命名规范、React 组件封装方式、跳过链接skip link实现以及如何在真实项目中自查与验证。一、规则概览什么是导航地标属性值规则名navigation-landmark优先级high高难度beginner入门预计耗时15 分钟类别html / accessibility规则的核心要求是页面导航应使用nav元素包裹并通过恰当的 ARIA 标签aria-label或aria-labelledby区分多个导航区域。在仓库的规则系统中该技能描述为Page navigation uses nav elements with proper ARIA labels to distinguish multiple navigation regions.对应的 SKILL.md 给出了速查清单将导航链接包裹在nav元素中使用aria-label区分多个nav区域提供跳过链接skip links以绕过重复导航屏幕阅读器用户依靠地标进行页面跳转。仓库中的规则文档references/rule.md进一步说明导航地标帮助用户理解页面结构并快速跳转到不同的导航区块。同时该规则与landmark-regions见 packages/content/rules/en/accessibility/landmark-regions.mdx、html5-semantic-elements见 packages/content/rules/en/html/html5-semantic-elements.mdx等规则经常在真实审计中一起出现、互相影响。二、为什么重要没有地标时的导航困境屏幕阅读器用户可以通过地标快速跳转到并识别不同的导航区域。如果没有这些地标用户必须逐个 Tab 遍历每个链接才能找到目标——在一个包含主导航、面包屑、目录、侧栏、页脚导航的复杂页面上这可能意味着要穿越几十个链接。导航地标本质上把线性扫描升级为按区域跳转用 NVDA 时按D键可在地标之间循环用 VoiceOver 时通过转子rotor选择地标键盘用户则依赖跳过链接直达主内容。三、完整的 HTML 示例五种导航区域一次到位规则文档给出了一份完整的参考页面涵盖主导航、面包屑、页内目录、侧栏导航与页脚导航五种典型场景!DOCTYPE html html langen head meta charsetUTF-8 titlePage Title/title /head body !-- Skip link (first element) -- a href#main-content classskip-link Skip to main content /a header !-- Primary navigation -- nav aria-labelMain ul lia href/Home/a/li lia href/productsProducts/a/li lia href/aboutAbout/a/li lia href/contactContact/a/li /ul /nav /header !-- Breadcrumb navigation -- nav aria-labelBreadcrumb ol lia href/Home/a/li lia href/productsProducts/a/li lia href/products/widgets aria-currentpageWidgets/a/li /ol /nav main idmain-content !-- Page content -- !-- In-page navigation (table of contents) -- nav aria-labelTable of contents h2On this page/h2 ul lia href#section-1Section 1/a/li lia href#section-2Section 2/a/li lia href#section-3Section 3/a/li /ul /nav h1Page Title/h1 section idsection-1.../section section idsection-2.../section section idsection-3.../section /main aside !-- Sidebar navigation -- nav aria-labelRelated pages h2Related/h2 ul lia href/related-1Related Page 1/a/li lia href/related-2Related Page 2/a/li /ul /nav /aside footer !-- Footer navigation -- nav aria-labelFooter ul lia href/privacyPrivacy Policy/a/li lia href/termsTerms of Service/a/li lia href/sitemapSitemap/a/li /ul /nav /footer /body /html几个要点跳过链接必须是body的第一个可聚焦元素这样键盘用户按 Tab 的第一步就能发现它面包屑用ol有序列表表达层级顺序且当前页用aria-currentpage标注目录放在main内部、h1之前属于页内导航。四、导航地标类型参考表不同导航区域应使用一致的命名惯例规则文档给出了如下参考区域元素aria-label 示例主导航navMain navigation次级导航navSecondary navigation页脚导航navFooter navigation面包屑navBreadcrumb分页navPagination目录navTable of contents五、React 导航组件从 HTML 到可复用组件规则文档提供了 React 版的组件封装思路包含NavLink、主导航、面包屑、页脚导航四个组件。下面整理为可直接使用的完整版本interface NavLinkProps { href: string children: React.ReactNode isCurrent?: boolean } function NavLink({ href, children, isCurrent }: NavLinkProps) { return ( li a href{href} aria-current{isCurrent ? page : undefined} {children} /a /li ) } interface MainNavProps { links: Array{ href: string; label: string } currentPath: string } function MainNav({ links, currentPath }: MainNavProps) { return ( nav aria-labelMain ul classNamemain-nav {links.map(link ( NavLink key{link.href} href{link.href} isCurrent{currentPath link.href} {link.label} /NavLink ))} /ul /nav ) } interface BreadcrumbProps { items: Array{ href: string; label: string } } function Breadcrumb({ items }: BreadcrumbProps) { return ( nav aria-labelBreadcrumb ol classNamebreadcrumb {items.map((item, index) { const isLast index items.length - 1 return ( li key{item.href} {isLast ? ( span aria-currentpage{item.label}/span ) : ( a href{item.href}{item.label}/a span aria-hiddentrue / /span / )} /li ) })} /ol /nav ) } interface FooterNavProps { sections: Array{ title: string links: Array{ href: string; label: string } } } function FooterNav({ sections }: FooterNavProps) { return ( nav aria-labelFooter div classNamefooter-nav {sections.map(section ( div key{section.title} classNamefooter-nav__section h3{section.title}/h3 ul {section.links.map(link ( li key{link.href} a href{link.href}{link.label}/a /li ))} /ul /div ))} /div /nav ) }设计要点aria-current只在当前页链接上输出其他链接输出undefined即不渲染该属性避免无意义属性污染 DOM面包屑的最后一个条目是span而非链接并用aria-currentpage标识当前位置分隔符/用aria-hiddentrue从无障碍树中隐藏面包屑ol的每个li都需要唯一的key规则文档使用item.href作为 key。六、跳过链接Skip Links绕过重复导航的钥匙跳过链接让键盘与屏幕阅读器用户跳过重复出现的导航区块直达主内容。规则文档给出了多目标跳过链接的写法与配套 CSSfunction SkipLinks() { return ( div classNameskip-links a href#main-content classNameskip-link Skip to main content /a a href#main-nav classNameskip-link Skip to navigation /a a href#search classNameskip-link Skip to search /a /div ) }配套 CSS 使跳过链接在默认状态下移出可视区域聚焦时才出现.skip-link { position: absolute; top: -40px; left: 0; padding: 8px 16px; background: #000; color: #fff; z-index: 1000; transition: top 0.2s; } .skip-link:focus { top: 0; }需要注意#main-content这类锚点目标最好配合tabindex-1如main idmain-content tabindex-1以便部分浏览器中聚焦位置能正确移动——这一点与仓库中 html5-semantic-elements.mdx 的示例一致。七、Next.js 布局实战从本仓库源码验证规则文档给出了 Next.jsapp/layout.tsx的骨架在header放主导航在footer放分组导航main idmain-content包裹{children}。这个骨架在本仓库中有完全对应的生产实现可以直接对照学习1. 头部主导航双区域命名apps/web/components/navigation/header.tsx 中桌面与移动分别使用独立的nav区域桌面导航nav classNamehidden items-center gap-1 md:flex aria-labelMain navigation第 106 行包含 Rules / Checklists / Guides 三个入口移动菜单nav idmobile-menu ... aria-labelMobile navigation第 216 行并通过aria-controlsmobile-menu与aria-expanded{mobileMenuOpen}的汉堡按钮联动搜索按钮使用aria-labelSearch rules第 150 行图标自身aria-hiddentrue以避免冗余朗读。两个nav使用不同的aria-labelMain navigation vs Mobile navigation正是多个导航区域必须有唯一标签这一规则在生产中的体现。2. 页脚导航用 aria-labelledby 关联可见标题apps/web/components/navigation/footer.tsx 的FooterLinkColumn组件展示了另一种命名方式——当导航区域带有可见标题时用aria-labelledby引用标题 id而不是重复aria-labelfunction FooterLinkColumn({ title, titleId, links }: FooterLinkColumnProps) { return ( nav aria-labelledby{titleId} h3 id{titleId} classNamefont-medium text-[11px] text-foreground-subtle uppercase tracking-[0.22em] {title} /h3 ul classNamemt-4 space-y-3 {links.map(link ( li key{link.href} ... /li ))} /ul /nav ) }页面中实际传入了三个列FooterLinkColumn titleExplore titleIdfooter-product-nav ... /、FooterLinkColumn titleProject titleIdfooter-project-nav ... /、FooterLinkColumn titleFor AI Agents titleIdfooter-agents-nav ... /分别输出三个带唯一 id 的页脚导航区域。3. 目录导航IntersectionObserver aria-currentapps/web/components/rules/detail/table-of-contents.tsx 实现了一个nav aria-labelTable of contents第 88 行通过IntersectionObserver追踪当前滚动位置所在标题并高亮当前项扫描article容器内h2、h3minLevel2、maxLevel3带id的标题当前激活项使用aria-current{activeId heading.id ? location : undefined}第 101 行标题无 id 时不渲染目录返回null避免出现空的nav。注意这里的aria-current值用的是location而非page——location表示集合中当前的元素适合目录、面包屑这类位置指示page表示当前页面链接适合分页、导航链接两者语义不同可按场景选用。八、何时用 aria-label何时用 aria-labelledby规则文档给出了两者的取舍!-- aria-label: Short, simple label -- nav aria-labelMain !-- No visible heading -- /nav !-- aria-labelledby: Reference visible heading -- nav aria-labelledbyfooter-nav-heading h2 idfooter-nav-headingQuick Links/h2 ul.../ul /nav判断标准没有可见标题时用aria-label提供简短、明确的名称如 Main、Footer已有可见标题时优先用aria-labelledby引用该标题的id——这样标题文本会自动成为地标的可访问名称且标题内容更新时名称自动同步避免标签与视觉文本不一致仓库页脚正是后者的范例h3 id{titleId}与nav aria-labelledby{titleId}一一对应。九、常见错误与纠正规则文档列出的四类高频错误审计时值得逐一对照!-- ❌ Multiple nav without labels -- nav.../nav nav.../nav !-- ✓ Labeled navigation regions -- nav aria-labelMain.../nav nav aria-labelFooter.../nav !-- ❌ Using div instead of nav -- div classnavigation.../div !-- ✓ Semantic nav element -- nav aria-labelMain.../nav !-- ❌ Nesting nav elements -- nav nav.../nav /nav !-- ✓ Separate nav regions -- nav aria-labelPrimary.../nav nav aria-labelSecondary.../nav补充两个边界判断不要过度使用nav规则文档明确提示nav只应用于主要导航区块次要链接组如社交图标不需要成为导航地标——地标过多会稀释每个地标的可用性。仓库中社交图标GitHub、X 链接直接放在 header 容器内而非nav中即遵循此原则多个nav必须标签唯一否则屏幕阅读器朗读时用户无法区分Navigation、Navigation到底指哪个。十、验证清单如何确认导航地标达标规则文档给出了 6 步验证流程同时 SKILL.md 要求验证最终浏览器输出的标记而不是框架抽象层源码Validate the final browser-facing markup, not just the source framework abstraction使用屏幕阅读器地标导航NVDA 下按D键循环地标VoiceOver 下使用转子rotor查看地标列表确认每个 nav 区域有唯一标签地标列表中不应出现多个无名称或重名的 Navigation检查跳过链接在聚焦时出现Tab 到第一个元素时跳过链接应滑入可视区域对应 CSS:focus { top: 0 }验证当前页链接的aria-current当前所在页面/条目应正确输出aria-currentpage或location测试键盘遍历所有链接确保每个nav内链接均可 Tab 到达、焦点顺序符合预期确认 nav 数量与预期区域一致主导航、面包屑、目录、页脚各应恰好出现一次无多余或缺失。自动化方面仓库规则体系中 WAVE、axe DevTools、Lighthouse 等工具见 html5-semantic-elements.mdx 的 Tools Validation 一节均可辅助检测地标结构React/Next.js 项目中建议直接查看服务端渲染后的 HTML 或浏览器 DOM因为客户端组件如 header.tsx 是use client组件最终输出由运行时决定。十一、关联规则与延伸阅读导航地标不是孤立规则在仓库的规则图谱中它与以下规则密切相关常被一同审计landmark-regions地标区域正确性要求每个地标类型在适当位置只出现一次如全页只有一个main同类型多地标必须加标签html5-semantic-elements语义化 HTML 元素nav与header、main、footer共同构成页面骨架landmark-one-main全页唯一main地标breadcrumb-navigation面包屑导航本身的无障碍实现与导航地标命名直接相关。仓库中所有规则以结构化 MDX 存储于 packages/content/rules/en每条规则都带有tldr、whyItMatters、check/fix/explain/codeReview 四类 prompt 及aiContext可直接被 Agent 与 LLM 检索复用——这也正是 Front-End-Checklist 面向人类与 AI Agent双受众定位的体现。小结导航地标是无障碍页面结构的基石。用nav包裹导航、用唯一aria-label/aria-labelledby命名、用跳过链接绕过重复区域再配合aria-current标注当前位置就能让屏幕阅读器用户、键盘用户与 AI Agent 都高效地按区域跳转。对照本仓库的 header.tsx、footer.tsx、table-of-contents.tsx 三个真实组件即可在生产级 Next.js 项目中落地这套规范。【免费下载链接】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），仅供参考