企业官网建设流程全解析

本文围绕 Front-End-Checklist 仓库中 tabs-accessibility 规则 及其技能参考文档展开，系统讲解 ARIA Tabs 模式的角色、状态与键盘交互规范，并给出可直接落地的 HTML 与 React 实现。读完你将掌握 tablist/tab/tabpanel 三要素的用法、roving tabindex 焦点管理原理，以及如何用 25 分钟完成一个无障碍选项卡组件的实现与验证。

为什么 Tabs 需要专门的键盘导航实现

选项卡（Tabs）是 Web 产品中最常见的组件形态之一，但它也是最容易在无障碍层面"翻车"的组件。错误实现的 Tabs 会带来两类典型的伤害：

• 键盘用户被困住：如果所有 tab 都可以被 Tab 键依次聚焦，用户每次进入选项卡区域都要反复按 3~5 次 Tab 才能离开，导航效率极低；更糟的是，如果面板切换逻辑依赖 hover 或点击，纯键盘用户将根本无法操作。
• 读屏用户无法理解结构：如果缺少role="tab"、aria-selected、aria-controls等语义属性，屏幕阅读器无法向用户表达"这是一组选项卡、当前选中了哪一个、选中后对应哪块内容"，组件退化为一堆孤立的按钮。

因此，ARIA 规范专门定义了 Tabs 设计模式（Design Pattern），为"键盘导航"和"语义表达"两件事立下标准。仓库中 tabs-accessibility 技能说明 给出的快速要点是：

• 使用tablist、tab、tabpanel三种角色；
• 同一时刻只有一个 tab 位于 Tab 键序列中（roving tabindex）；
• 方向键在 tab 之间移动焦点，Tab 键移入面板；
• 用aria-controls/aria-labelledby把 tab 与 panel 关联起来。

ARIA Tabs 模式：三个角色的职责与关键属性

ARIA Tabs 模式由三个元素组成，各自承担明确职责。以下表格来自规则文档的核心定义，也是所有实现的第一步：

要点说明：

• tablist必须有无障碍名称。优先使用可见文字关联（aria-labelledby指向某个标题元素），没有合适可见标签时再使用aria-label，如aria-label="Product information"。
• tab的aria-controls值必须是目标面板的id，这是建立"按钮 → 内容"正向关联的桥梁。
• tabpanel的aria-labelledby指回tab的id，形成"内容 → 按钮"的反向关联，读屏用户聚焦面板时能听到"某某选项卡的内容"。
• tabpanel设置tabindex="0"，让面板本身可聚焦，方便后续 Tab 键在面板与 tablist 之间移动。
• 隐藏的面板要使用hidden属性（或 CSSdisplay: none等价物），避免隐藏内容仍被朗读。

键盘导航规范：一组键位搞定完整交互

规则文档给出了与 WAI-ARIA 规范一致的完整键位表，这是键盘用户操作 Tabs 的行为契约：

这里的关键设计是roving tabindex：tablist 中永远只有一个 tab 的tabindex="0"（当前激活项），其余全部为tabindex="-1"。这样 Tab 键一次就能进入 tablist，而方向键负责在内部"漫游"。规则文档对此有明确警告：

Only the active tab should havetabindex="0". All other tabs should havetabindex="-1". This is called "roving tabindex" and ensures efficient keyboard navigation.

最小可行实现：纯 HTML 结构

规则文档提供了一份完整的、不依赖任何框架的 HTML 结构，它同时是语义基准和审查参照物，可直接作为静态页面或服务端渲染模板使用：

<div class="tabs"> <div role="tablist" aria-label="Product information"> <button role="tab" id="tab-1" aria-selected="true" aria-controls="panel-1" tabindex="0" > Description </button> <button role="tab" id="tab-2" aria-selected="false" aria-controls="panel-2" tabindex="-1" > Specifications </button> <button role="tab" id="tab-3" aria-selected="false" aria-controls="panel-3" tabindex="-1" > Reviews </button> </div> <div role="tabpanel" id="panel-1" aria-labelledby="tab-1" tabindex="0" > <p>Product description content...</p> </div> <div role="tabpanel" id="panel-2" aria-labelledby="tab-2" tabindex="0" hidden > <p>Technical specifications...</p> </div> <div role="tabpanel" id="panel-3" aria-labelledby="tab-3" tabindex="0" hidden > <p>Customer reviews...</p> </div> </div>

注意三个细节：

1. 只有激活的 tab-1 是tabindex="0"，另外两个是tabindex="-1"（roving tabindex 的静态呈现）；
2. 只有激活的面板不带hidden；
3. 每个面板都通过aria-labelledby指回自己的 tab。

在实际交互中，JavaScript 需要完成两件事：点击或聚焦 tab 时切换aria-selected与hidden，并维护 tabindex 的"0 只有一个"规则。

可复用实现：React Tabs 组件

规则文档给出了一个完整的 React 组件实现，它把上述所有语义与键盘逻辑封装成了可复用的Tabs。这个实现值得逐行拆解：

import { useState, useRef, useId, KeyboardEvent } from 'react' interface Tab { id: string label: string content: React.ReactNode } interface TabsProps { tabs: Tab[] label: string defaultTab?: number manual?: boolean // Manual or automatic activation } export function Tabs({ tabs, label, defaultTab = 0, manual = false }: TabsProps) { const [activeIndex, setActiveIndex] = useState(defaultTab) const [focusIndex, setFocusIndex] = useState(defaultTab) const tabRefs = useRef<(HTMLButtonElement | null)[]>([]) const baseId = useId() const getTabId = (index: number) => `${baseId}-tab-${index}` const getPanelId = (index: number) => `${baseId}-panel-${index}` const activateTab = (index: number) => { setActiveIndex(index) setFocusIndex(index) } const focusTab = (index: number) => { setFocusIndex(index) tabRefs.current[index]?.focus() // Automatic activation: activate on focus if (!manual) { setActiveIndex(index) } } const handleKeyDown = (e: KeyboardEvent, index: number) => { let nextIndex: number | null = null switch (e.key) { case 'ArrowLeft': e.preventDefault() nextIndex = index > 0 ? index - 1 : tabs.length - 1 break case 'ArrowRight': e.preventDefault() nextIndex = index < tabs.length - 1 ? index + 1 : 0 break case 'Home': e.preventDefault() nextIndex = 0 break case 'End': e.preventDefault() nextIndex = tabs.length - 1 break case 'Enter': case ' ': if (manual) { e.preventDefault() activateTab(index) } break } if (nextIndex !== null) { focusTab(nextIndex) } } return ( <div className="tabs"> <div role="tablist" aria-label={label} className="tabs__list" > {tabs.map((tab, index) => ( <button key={tab.id} ref={(el) => { tabRefs.current[index] = el }} role="tab" id={getTabId(index)} aria-selected={activeIndex === index} aria-controls={getPanelId(index)} tabIndex={focusIndex === index ? 0 : -1} onClick={() => activateTab(index)} onKeyDown={(e) => handleKeyDown(e, index)} className={`tabs__tab ${activeIndex === index ? 'tabs__tab--active' : ''}`} > {tab.label} </button> ))} </div> {tabs.map((tab, index) => ( <div key={tab.id} role="tabpanel" id={getPanelId(index)} aria-labelledby={getTabId(index)} tabIndex={0} hidden={activeIndex !== index} className="tabs__panel" > {tab.content} </div> ))} </div> ) }

实现中几个值得学习的设计决策：

• activeIndex与focusIndex分离：这是支持"自动/手动激活"双模式的关键。activeIndex决定哪个面板显示，focusIndex决定哪个 tab 拥有tabindex="0"。自动激活模式下二者几乎同步；手动激活模式下，焦点可以先移动到某个 tab，只有按 Enter/Space 才真正切换面板。
• useId()生成稳定且唯一的 id：getTabId/getPanelId用同一个baseId派生，保证aria-controls与aria-labelledby双向关联永远一致，也避免服务端渲染时的 id 冲突。
• 方向键环形漫游：ArrowLeft在最左端时回到最后一个 tab，ArrowRight在最右端时回到第一个（index > 0 ? index - 1 : tabs.length - 1），Home/End提供跳转，preventDefault()防止方向键触发页面滚动。
• tabRefs数组 + ref 回调：在键盘漫游时直接调用tabRefs.current[index]?.focus()，把焦点真正移到目标 tab 上。

使用示例

规则文档同时给出了组件的调用方式，数据驱动、开箱即用：

<Tabs label="Account settings" tabs={[ { id: 'profile', label: 'Profile', content: <ProfileSettings /> }, { id: 'security', label: 'Security', content: <SecuritySettings /> }, { id: 'notifications', label: 'Notifications', content: <NotificationSettings /> } ]} />

label会被透传到tablist的aria-label；每个 tab 的content是任意 ReactNode，面板切换时按需渲染对应内容。

自动激活 vs 手动激活

ARIA 规范允许两种激活模式，规则文档用一行注释给出了选择依据：

// Automatic: Tab activates on focus (default, better UX) <Tabs tabs={tabs} label="Settings" manual={false} /> // Manual: Tab activates on Enter/Space (use for destructive operations) <Tabs tabs={tabs} label="Settings" manual={true} />

• 自动激活（Automatic Activation）：焦点一到 tab 就立即切换面板。这是默认且用户体验更顺滑的模式，适合大多数"浏览型"内容（如产品信息、账户设置），在 React 组件中对应focusTab里if (!manual) setActiveIndex(index)这一行。
• 手动激活（Manual Activation）：焦点移动只改变 tabindex，必须按 Enter/Space 才切换。适用于切换代价高、不可逆或"破坏性"的操作场景——比如"删除账户""清空数据"这类确认性选项卡，避免用户仅仅路过就触发了危险内容。此时Enter/Space分支被激活。

进阶变体：垂直 Tabs 与带图标 Tabs

垂直 Tabs

当选项卡数量多、标签文字长时，垂直布局更合适。规则文档给出了VerticalTabs实现，核心变化是方向键映射：垂直布局用ArrowUp/ArrowDown，水平布局用ArrowLeft/ArrowRight：

interface VerticalTabsProps extends TabsProps { orientation?: 'horizontal' | 'vertical' } export function VerticalTabs({ tabs, label, defaultTab = 0, orientation = 'vertical' }: VerticalTabsProps) { const [activeIndex, setActiveIndex] = useState(defaultTab) const tabRefs = useRef<(HTMLButtonElement | null)[]>([]) const baseId = useId() const handleKeyDown = (e: KeyboardEvent, index: number) => { // Vertical tabs use Up/Down instead of Left/Right const prevKey = orientation === 'vertical' ? 'ArrowUp' : 'ArrowLeft' const nextKey = orientation === 'vertical' ? 'ArrowDown' : 'ArrowRight' let nextIndex: number | null = null if (e.key === prevKey) { e.preventDefault() nextIndex = index > 0 ? index - 1 : tabs.length - 1 } else if (e.key === nextKey) { e.preventDefault() nextIndex = index < tabs.length - 1 ? index + 1 : 0 } if (nextIndex !== null) { setActiveIndex(nextIndex) tabRefs.current[nextIndex]?.focus() } } return ( <div className={`tabs tabs--${orientation}`}> <div role="tablist" aria-label={label} aria-orientation={orientation} className="tabs__list" > {/* ... same as horizontal */} </div> {/* ... panels */} </div> ) }

注意tablist上显式声明了aria-orientation={orientation}，辅助技术据此得知这是垂直选项卡组；容器与 tablist 的样式也相应改为纵向排布。

带图标 Tabs

图标能显著提升扫描效率，但装饰性图标必须对读屏用户隐藏，否则会产生噪音。规则文档的TabButton展示了标准做法：图标外包一层aria-hidden="true"的<span>，让读屏用户只听到文字标签：

interface TabWithIcon { id: string label: string icon: React.ReactNode content: React.ReactNode } function TabButton({ tab, isActive, ...props }: { tab: TabWithIcon isActive: boolean }) { return ( <button role="tab" aria-selected={isActive} className={`tabs__tab ${isActive ? 'tabs__tab--active' : ''}`} {...props} > <span className="tabs__icon" aria-hidden="true"> {tab.icon} </span> <span className="tabs__label">{tab.label}</span> </button> ) }

样式：为焦点与选中态留出视觉语义

样式不是"锦上添花"，焦点可见性是键盘可达性的另一半。规则文档给出了完整的 CSS，核心关注点有三个：

.tabs__list { display: flex; gap: 0; border-bottom: 1px solid #ddd; } .tabs__tab { padding: 0.75rem 1.5rem; background: none; border: none; border-bottom: 2px solid transparent; color: #666; font-size: 1rem; cursor: pointer; transition: border-color 0.2s, color 0.2s; } .tabs__tab:hover { color: #333; } .tabs__tab:focus-visible { outline: 2px solid #0066cc; outline-offset: -2px; } .tabs__tab--active { color: #0066cc; border-bottom-color: #0066cc; font-weight: 600; } .tabs__panel { padding: 1.5rem 0; } .tabs__panel:focus { outline: none; } .tabs__panel:focus-visible { outline: 2px solid #0066cc; outline-offset: 2px; } /* Vertical tabs */ .tabs--vertical { display: flex; gap: 2rem; } .tabs--vertical .tabs__list { flex-direction: column; border-bottom: none; border-right: 1px solid #ddd; } .tabs--vertical .tabs__tab { border-bottom: none; border-right: 2px solid transparent; text-align: left; } .tabs--vertical .tabs__tab--active { border-right-color: #0066cc; }

样式要点：

• 焦点样式必须可见：.tabs__tab:focus-visible用2px solid #0066cc描边并微调outline-offset，确保键盘用户清楚知道焦点位置；.tabs__panel:focus-visible同理，而.tabs__panel:focus去 outline 是为了避免点击（鼠标聚焦）时的闪烁干扰。
• 选中态与焦点态分离：选中态用底部 2px 蓝色边框 + 加粗（.tabs__tab--active），与焦点描边是两套视觉信号，互不混淆。
• 垂直布局适配：.tabs--vertical让容器变为左右两栏，tablist 纵向排列、右侧边框替代底部边框，选中态改为右侧 2px 边框。
• 颜色选择以#0066cc为主强调色并配合#666/#333文字层级，若与设计系统冲突，可替换为设计 token 并确保对比度达标。

源码级佐证：仓库中的 roving tabindex 与 Radix Tabs

规则文档给出了"怎么做"，而仓库源码恰好能印证"为什么这么做"。Front-End-Checklist 站点自身的无障碍工具库 apps/web/lib/accessibility/focus.ts 就封装了本规则依赖的两个核心机制：

1.createRovingTabIndex——roving tabindex 的通用实现

export function createRovingTabIndex(container: HTMLElement): () => void { const items = Array.from( container.querySelectorAll<HTMLElement>('[role="menuitem"], [role="option"], [role="tab"]') ) if (items.length === 0) return () => {} let currentIndex = 0 items.forEach((item, index) => { item.setAttribute('tabindex', index === 0 ? '0' : '-1') }) function handleKeyDown(e: KeyboardEvent) { const key = e.key let newIndex = currentIndex switch (key) { case 'ArrowDown': case 'ArrowRight': e.preventDefault() newIndex = (currentIndex + 1) % items.length break case 'ArrowUp': case 'ArrowLeft': e.preventDefault() newIndex = (currentIndex - 1 + items.length) % items.length break case 'Home': e.preventDefault() newIndex = 0 break case 'End': e.preventDefault() newIndex = items.length - 1 break default: return } items[currentIndex].setAttribute('tabindex', '-1') items[newIndex].setAttribute('tabindex', '0') items[newIndex].focus() currentIndex = newIndex } container.addEventListener('keydown', handleKeyDown) return () => { container.removeEventListener('keydown', handleKeyDown) } }

对照规则文档中的 React 实现，可以看到两者共享同一套行为模型：方向键环形漫游（取模实现首尾回绕）、Home/End跳转、焦点移动时"旧项置-1、新项置0"。差异仅在于 React 版本用useState管理状态、用useRef拿到 DOM 节点，而工具函数直接操作 DOM 属性——这说明 roving tabindex 是一套与框架无关的通用模式，[role="tab"]只是它服务的三种角色之一（另两种是menuitem和option，即菜单项与组合框选项）。

2.trapFocus——与 Tabs 互补的焦点陷阱

同一个文件里的trapFocus负责把 Tab/Shift+Tab 循环限制在容器内（常用于模态框、抽屉等），与 roving tabindex 的"放行"语义互补。值得一提的是它选择可聚焦元素时排除了[tabindex="-1"]，从反面印证了"只有tabindex="0"的元素才进入 Tab 顺序"这一规则。

3. 设计系统里的生产级 Tabs

仓库的设计系统 packages/design-system/src/ui/tabs.tsx 基于 Radix UI 的@radix-ui/react-tabs二次封装。Radix 的 Tabs 原语本身就遵循 WAI-ARIA Tabs 模式：TabsPrimitive.List渲染为role="tablist"，Trigger渲染为role="tab"并自动处理aria-selected、roving tabindex 与方向键导航，Content渲染为role="tabpanel"并关联aria-labelledby。这给了一个重要启示：无论是手写组件还是引入组件库，最终都要满足同一套语义契约——这也是 SKILL.md 中"验证最终浏览器渲染出的标记，而不仅是源码层面的抽象"这句 AI 审查提示的用意所在。

验证清单：7 步确认你的 Tabs 达标

规则文档以一份可操作的验证清单收尾，按顺序执行即可系统性地排查实现：

1. Tab 进入 tablist：按 Tab 键，焦点应直接落在当前激活的 tab 上（而不是第一个 tab 或最后一个）。
2. 方向键导航：使用←/→在 tab 间移动焦点，观察焦点是否按预期环形移动。
3. 验证 tab 顺序：确认只有一个 tab 是tabindex="0"，其余都是tabindex="-1"（可用 DevTools 检查元素属性）。
4. Tab 进入面板：焦点在 tab 上时按 Tab，应能进入当前面板内容，面板需要tabindex="0"才可聚焦。
5. 测试 Home/End：分别跳到第一个和最后一个 tab。
6. 读屏验证：用 NVDA、VoiceOver 或 TalkBack 听一下 tab 角色与选中状态（"tab, 已选定, 2/3"）是否被正确播报。
7. 关联检查：确认每个面板的aria-labelledby与对应 tab 的id匹配，aria-controls指向的面板 id 真实存在。

在 AI 辅助开发或代码审查流程中，可以把这套检查逻辑直接作为提示词：用 规则文件 中定义的check/fix/explain/codeReview四个提示模板，要求 AI 审查模板、服务端渲染 HTML 与共享组件中输出的标记，定位具体元素、属性与路由上违反本规则的位置——这正是仓库把本规则同时沉淀为技能（SKILL）与内容规则（MDX）的用意。

小结

本规则的全部要点可以浓缩为一句话：用正确的角色表达结构，用 roving tabindex 控制焦点，用方向键驱动导航，用aria-controls/aria-labelledby建立双向关联。按照本文给出的 HTML 结构、React 组件、垂直变体、图标变体与样式，你可以在一小时内交付一个对键盘用户和读屏用户都友好的 Tabs 组件；而 焦点工具库 与 设计系统 Tabs 的实现则证明：无论手写还是基于组件库，无障碍的终点都是同一套 ARIA 契约。