企业官网建设流程全解析

• 开发工具
• 版本控制

本篇指南以 GitLens（vscode-gitlens）仓库中的 docs/accessibility.md 为骨架，结合 docs/webview-accessibility-patterns.md 及提交图（commit graph）等复杂 Lit webview 的源码实现，系统讲解在 VS Code 扩展 webview 中创建无障碍 Lit 组件时必须满足的六大需求：焦点管理、焦点陷阱、ARIA 属性、工具提示、视觉焦点指示器与颜色对比度。读完你将掌握一套可直接复用的键盘导航与焦点管理模式（roving tabindex 组、aria-activedescendant 菜单、虚拟化树、焦点跟随导航等），并能在仓库中找到每一类模式的落点实现。

一、需求清单：创建或修改 Lit Web 组件时的六项硬性要求

accessibility.md是一份需求检查清单（requirements checklist），它不讨论具体实现方式，只规定"必须做到什么"。任何在 GitLens 中新增或改动 Lit webview 组件（包括提交图、搜索面板、侧栏视图等）的代码，都必须逐条对照以下六项要求自查。

1. 焦点管理（Focus Management）

• 键盘导航必须可用，Tab 顺序必须符合逻辑；
• 自定义交互元素需要设置tabindex="0"，并挂载键盘事件处理器（用Enter / Space触发激活）。

从源码看，GitLens 对此的实现并不是简单地把tabindex="0"撒在每个控件上，而是大量使用roving tabindex模式：一组控件中永远只有一个持有tabindex="0"（Tab 停靠点），其余为tabindex="-1"，通过方向键在组内移动停靠点。共享实现见 packages/components/src/controllers/rovingTabindex.ts 与 src/webviews/apps/shared/components/actions/action-nav.ts，这两处将在后文"模式一"中详细展开。

2. 焦点陷阱（Focus Traps）

• 模态框 / 浮层（modal/overlay）组件在打开时必须把焦点困在内部，关闭时必须把焦点恢复到触发元素；
• 必须使用经过测试的焦点陷阱工具，而不是从零手写。

在 GitLens 中，浮层组件（如gl-popover、gl-tooltip）位于 packages/components/src/components/overlays/，源码注释明确要求复用共享实现而非手写，原因在于手写陷阱极易在边界条件下（连续打开多个浮层、焦点被虚拟化回收等）漏掉恢复逻辑。

3. ARIA 属性

• 交互元素必须有恰当的role与aria-*属性；
• 自定义部件按需具备aria-expanded、aria-selected、aria-disabled。

例如提交图中的 ref 药丸（pill）菜单按钮会维护aria-expanded；action-nav组件在初始化时会给每个参与 roving 的控件写入aria-posinset与aria-setsize（见 action-nav.ts 的handleSlotChange），向读屏器表明"这是 N 个控件中的第 i 个"；禁用态则通过disabled/aria-disabled="true"双通道表达（isDisabled方法同时检查两者）。

4. 工具提示（Tooltips）

• 必须同时出现在**悬停（hover）与键盘焦点（keyboard focus）**两种状态下；
• 必须能用Escape关闭。

GitLens 的提交图采用"单一委托式工具提示"（一个 host 持有的gl-popover根据聚焦元素解析data-tooltip），实现见 packages/plus/commit-graph-ui/src/rows/tooltip.ts 中的DelegatedTooltipController。它分别提供指针路径（onPointerOverTooltip）与键盘路径（showForFocus）两条触发链路，保证键盘用户能获得与鼠标用户完全一致的信息。

5. 视觉指示器（Visual Indicators）

• 焦点轮廓必须可见：禁止只写outline: none而不提供替代的可见指示器；
• 避免:focus与:focus-visible同时生效造成的双重轮廓。

GitLens 提交图的实践是：行焦点环用内嵌（inset）的::afterbox-shadow 绘制（.gl-graph__row.is-focused），约为行边缘向内 1px，与 VS Code 列表行的outline-offset: -1px视觉一致，同时能避开虚拟化器在行左缘的 overflow 裁剪（详见模式八）。

6. 颜色对比度（Color Contrast）

• 使用 VS Code 主题的 CSS 自定义属性（--vscode-*）着色；
• 禁止硬编码颜色。

这与 docs/webview-styling.md 的设计令牌体系一脉相承：焦点环颜色应取--vscode-focusBorder与--vscode-list-focusOutline，而不是写死某个 RGB 值，这样深色/浅色主题切换后对比度仍能达标。

通用准则（模式文档中的"经验法则"）：键盘用户必须能到达鼠标能到达的每一个控件；焦点指示器必须始终显示在实际持有焦点的元素上；当一个动作把用户带到别处时，焦点必须跟随移动。

二、为什么是"需求"与"模式"两份文档

accessibility.md回答"必须做什么"（requirements checklist），而 docs/webview-accessibility-patterns.md 回答"怎么做"（thehow）。模式文档以提交图（packages/plus/commit-graph-ui/src/）为主要实例——它是一个虚拟化的role="tree"，每行还带有丰富的行内控件，堪称最密集、最复杂的可访问性场景，但这些模式适用于任何高密度交互的 webview 界面。

下面八个模式是该文档的核心内容，本文逐一展开，并附上仓库源码中的落点。

三、模式一：Roving tabindex 组——N 个控件只占一个 Tab 停靠点

工具栏或列表里有 N 个可聚焦控件时，应该只提供一个 Tab 停靠点：一个控件持有tabindex="0"，其余为tabindex="-1"，用方向键在组内移动"0"；Tab 把整组作为单元进入/离开，Home/End 跳到首尾。

必须复用共享实现，禁止手写：

这两个实现在仓库中的使用者包括：提交图头部（graph header）、侧栏图标导轨（sidebar icon rail）、概览卡片（overview cards）、搜索框的选项簇（option clusters）与面板头部（panel headers）。

源码层面的几个关键设计值得学习：

• 稳定 key 而非索引：RovingTabindexItem.key是"图标类型、分支 id"这类稳定身份。hostUpdated()在每次 host 更新后重断言tabindex，如果跟踪的 key 仍在，就把停靠点恢复到它上面，而不是每次渲染都重置到第一项——这正好回应了accessibility.md中"Tab 顺序必须逻辑合理"的要求，避免用户焦点在重渲染时被粗暴踢回开头。
• 默认项跟踪而非锁定：用户尚未交互时，每次渲染都跟踪默认项（如导航栏中"当前激活的面板图标"）但不锁定它，这样后续布局中晚出现的项不会因为先渲染而被错误地锁为停靠点；一旦用户真的聚焦或按了方向键，activeKey被写入，从此锁定用户选择。
• 修饰键守卫：onKeydown对 Alt/Ctrl/Meta/Shift 修饰键提前返回，把 Shift+Arrow 之类的组合键（例如提交图列头的 Shift+方向键调整列宽/重排）留给控件自身处理，避免被 roving 吞掉。
• composed path 解析：itemFromEvent用e.composedPath()而非e.target解析事件来源，因为事件会跨 Shadow DOM 边界从控件的内部元素冒泡上来。

action-nav的补充细节：

• 穿透包装器：resolveFocusable对"渲染display: contents且不代理焦点"的透明包装器（如gl-tooltip）会解析到其包裹的唯一可聚焦控件，否则设置在外层的 roving tabindex 会被忽略，而内部控件又保留自己的 tabindex，导致双重停靠点。
• 禁用态变化监视：MutationObserver监听每个项的disabled/aria-disabled属性。因为"正则关闭时 Match Case 变灰、到达最后一条结果时 Next 禁用"这类禁用态翻转不会触发 slotchange，只有属性监视才能保证 roving tabindex 永不滞留在禁用控件上。
• 全禁用兜底：defaultItem在所有控件都禁用时仍返回第一个控件，保持恰好一个Tab 停靠点——因为按 WAI-ARIA，一个没有可聚焦停靠点的工具栏会整个掉出 Tab 顺序。
• 角色默认为role="navigation"，但尊重显式传入的role（例如role="toolbar"）。

四、模式二：虚拟化树 = 单一 Tab 停靠点 + 行内"下潜"

gl-commit-graph是role="tree"+aria-activedescendant：只有一个 Tab 停靠点，Up/Down 在虚拟层移动活动行（每一行都没有自己的 Tab 停靠点）。模式文档给出了五个配套设计：

1. 头优先排序（Header-first ordering）。树的role/tabindex="0"/aria-activedescendant放在包着虚拟化器的内层.gl-graph__tree上，列头作为它的前一个兄弟节点——这样 Tab 进入时先落到列头，再到树，全程无需 DOM 重排。

2. 下潜进入活动行（Dive into the active row）。从树按 Tab 进入当前活动行的控件，控件按视觉顺序组织成 roving 组：refs（药丸）→ actions（按钮）。源码实现：

• rowGroupControls（graph.ts）收集一行的可见、可交互控件，排除：静止时隐藏的控件、aria-hidden子树（hover 展开浮层的重复芯片、幽灵锚点药丸）、分组药丸打开状态下弹层里的菜单行（那些是 Up/Down 的菜单，不是 Left/Right 的停靠点）；
• enterActiveRowGroup（graph.ts）把焦点移入活动行第一个非空组（refs 优先，其次 actions），找不到任何控件时返回 false 让 Tab 自然走出图；
• 行内所有控件都是tabindex="-1"（受管）：Left/Right 在组内 rove（roveRowControls），Tab 跨到下一组（moveToAdjacentGroup）后离开图，Shift+Tab / Esc 退回树。

3. 幽灵滚动容器停靠点（The phantom scroll-container stop）。当滚动容器的每个可交互子元素都是tabindex="-1"时，Chromium 会把滚动容器本身加入 Tab 顺序（keyboard-focusable scroll containers），产生一个多余的停靠点——此时 Up/Down 变成原生滚动而不是导航。修复：在滚动器（<lit-virtualizer>）上设tabindex="-1"，真正的键盘宿主是树包装器。

4. 回收围栏（Recycle corral）。虚拟化的行滚出 overhang 后会被卸载，且没有内置的焦点恢复。GitLens 的做法是跟踪受管焦点元素（_managedFocusEl，按元素而非布尔值跟踪，见 graph.ts）；当它的行被回收、焦点跌落到<body>时，recaptureFocusIfStranded（graph.ts）把焦点拉回树——但仅此而已：元素仍在 DOM 中说明用户是刻意把焦点移走的（死区点击、切到别的 webview），绝不抢焦点。

5. 点击必须初始化键盘导航。行体点击必须让焦点落到树（而不是可被点击聚焦的滚动器）上，并把焦点索引重新钉到被点击的行，否则下一次按方向键就变成了滚动而不是导航。

五、模式三：aria-activedescendant 菜单——真实焦点留在控制器上

分组（多 ref）药丸是一个菜单按钮：聚焦它打开一个 ref 弹层，游标是虚拟的——DOM 焦点始终停留在药丸上，aria-activedescendant指向当前激活项。绝不要把真实焦点移进被 hoist 的弹层内容：那会破坏弹层自身的焦点跟踪，也破坏树的焦点模型。

视觉状态被拆成两个 class、两个职责：

• .is-active—— 被游标选中的行的高亮填充（容器高亮）。当填充会与文字产生对比冲突时（如 ahead/behind 统计切换为对比色），配色必须挂在:is(:hover, .is-active)上而非仅:hover，否则键盘游标选中的行文字会"融进"填充里看不清；
• .is-cursor—— 焦点矩形跟随具体的被游标选中项（整行，或行内的某个子操作）。把填充与矩形拆开，Left/Right 才能把矩形移到子操作（比如跳转按钮）上，而行仍保持填充状态。

导航规则（源码见 graph.ts 的moveGroupedPillCursor/setRowItemCursor/clearGroupedPillCursor）：

• Up/Down移动行（游标重置到该行第一项）；从内联子芯片按 Up 会回到父药丸（菜单锚点），让游标与焦点元素对齐、Enter 才能激活；
• Left/Right在被游标行的项之间 rove（groupedRowItems：先 ref，再它的交互子操作如 upstream-jump 按钮），在端点钳制，防止游标离开当前行；
• Enter激活被游标项（行 = 它的 ref，子操作 = 它的跳转），随后清除游标；
• Esc / Up 越过顶部退出（第一次 Esc 清游标，第二次才落到行控件的"退回树"逻辑）；
• 每个 activedescendant 目标都必须有稳定的id（行和子操作都要），aria-activedescendant才指得准。

setRowItemCursor还有两个值得一提的细节：一是强制打开弹层（popover.open = true）——因为 Escape 的文档级隐藏、popup 失焦、显示延迟都可能让弹层处于关闭状态，游标指向隐藏菜单等于"方向键全死、activedescendant 指着不可见内容"；二是滚动用手动scrollTop而非scrollIntoView，后者会遍历所有滚动祖先，把图视口/外层面板都推着滚（嵌套滚动 webview 的经典坑）。

六、模式四：浮层覆盖控件——保持填充、镜像焦点环

药丸在 hover/focus 时收成一个图标，展开成绝对定位的填充浮层（.gl-graph__ref-pill-expand）。它的交互子芯片渲染两份：一份在文档流中（roving/焦点目标），一份是浮层内aria-hidden的展开孪生（见 packages/plus/commit-graph-ui/src/extensions/refs/adornmentProvider.ts）。三个配套规则：

• 填充挂在:focus-within上：让药丸在内部控件被聚焦时保持"hover 样式"。不要把填充 gate 在药丸自身的:focus上——那样焦点一下潜进子芯片，填充立刻塌掉。
• 镜像焦点环：聚焦的文档流副本此刻已被浮层盖住。用:has()把它的焦点环镜像到可见的展开孪生上（.gl-graph__ref-pill:has(<chip>:focus-visible) .gl-graph__ref-pill-expand <twin>）。真实焦点与无障碍名仍留在文档流副本上，只有视觉上的环骑在孪生上。
• 工具提示同样处理：键盘触发的工具提示必须重新锚定到可见孪生，而不是被盖住的副本（_expandedTwinIfCovered，见 rows/tooltip.ts），否则提示会指向填充背后的"空气"。

七、模式五：焦点矩形画成整高色带，而非内缩盒子

对于分段控件，焦点矩形应画成一条贯穿整高、侵入容器垂直内边距的::before色带（inset-block: -Xrem），让它贴住上下边缘——而不是在内容盒上画一圈紧巴巴的box-shadow，后者看起来像内缩的小盒子。水平间隙要保持对称：若容器只有一侧有 padding，就把色带向无 padding 一侧延伸（inset-inline: 0 -0.5rem），让文字在矩形中居中。实现参考 packages/plus/commit-graph-ui/src/graph.scss 中 ref 药丸的 upstream/jump、PR 与 issue 芯片。

八、模式六：焦点必须跟随导航

任何把选择或滚动带到别处的动作，都必须把焦点也带到目的地——否则键盘焦点会被遗弃在（可能已滚出视口的）触发器上，下一次方向键从错误的位置生效。jumpToRefRow（graph.ts）聚焦跳转目标行处的树并重新钉住焦点索引；作为额外收益，把焦点从源药丸移走会自动塌掉它的填充、关闭它的弹层（"unfocus 旧东西"）。实现细节：jumpToRefRow先treeRef.value?.focus()，再派发gl-jump-to-commit自定义事件走统一的 load/select/reveal 生命周期，无论目标是已加载、已折叠还是未加载都能保持"最新用户意图"。

九、模式七：键盘焦点上的工具提示

工具提示必须在聚焦时出现，而不只是 hover（对应accessibility.md第四条）。两个坑：

1. 委托式工具提示（单一 host 持有的 tooltip 从聚焦元素解析data-tooltip）通过视口focusin触发（showForFocus）——这覆盖了常规的 Tab 聚焦路径；
2. aria-activedescendant 游标不产生focusin——DOM 焦点从未移动，任何东西都不会触发提示。所以要在游标移动时显式挂出提示（setRowItemCursor→showForTarget），游标清除时再隐藏（clearGroupedPillCursor→scheduleHide）。

DelegatedTooltipController（rows/tooltip.ts）还有两个健壮性设计：打开状态与锚点解耦（隐藏时先置_open = false但保留锚点直到关闭动画落定，避免锚点在未 hover 的瞬间失去布局盒、弹层飞到左上角）；对同一锚点"hover + focus 同时命中"做去重（showForTarget中若目标就是当前锚点，取消待执行的 hide 计时器原位重开，不重新拉取内容）。

十、模式八：装饰元素必须让出行焦点环

行焦点环是行边缘向内约 1px 的内嵌::afterbox-shadow（.gl-graph__row.is-focused）：内嵌而非贴边，是为了与 VS Code 列表行的outline-offset: -1px一致，同时避开虚拟化器对贴左缘内容的 overflow 裁剪；它是最顶层的覆盖，因为行本身是 stacking context，其定位后代若用普通outline会把它盖掉。

由此带来的后果：接近整高的装饰（头像/身份提交节点）一旦长到行边缘就会被环裁掉——尤其在 hover/选中放大之后。因此装饰尺寸（含放大）必须保持在环的内部。头像节点半径正是为此封顶的（nodeRadiusFor/avatarNodeRadius，见 packages/plus/commit-graph-ui/src/gutter/render.ts）：半径 9（直径 18px），×1.1 放大后 19.8px，仍能清出 24px 行高约 20px 的内腔。

十一、关键文件索引

十二、实践自查清单

把两份文档合起来，一份可执行的开发自查清单如下：

1. 新增可交互元素时，确认它进入 Tab 顺序或属于某个 roving 组，tabindex永不重复；
2. 模态/浮层打开即困焦点、关闭即还原焦点，且复用共享的 popover/tooltip 组件而非手写陷阱；
3. 按需补齐role、aria-expanded、aria-selected、aria-disabled、aria-activedescendant及稳定的目标id；
4. 工具提示同时挂 hover 与 focus 两条链路（普通元素用focusin，activedescendant 游标显式showForTarget），Escape 可关；
5. 焦点环始终可见：不裸用outline: none，避免:focus+:focus-visible双环，环/色带配色取--vscode-*变量；
6. 导航型动作（跳转、滚动、选中）必须携带焦点移动；
7. 虚拟化场景做好回收围栏与幽灵滚动容器处理；
8. 深色/浅色主题下对照度做一次实际验证。

遵循这份规范，键盘与读屏器用户将获得与鼠标用户等价的 GitLens 使用体验——这正是 VS Code 生态对 webview 可访问性的核心期待。

• 开发工具
• 版本控制