如何用TypeScript为IWAC封装黎巴嫩网络无障碍指南的键盘导航类型？

为IWAC封装键盘导航类型，不只是把KeyboardEvent的key值列一遍。黎巴嫩网络无障碍指南对键盘操作有更严格的要求，例如焦点必须落在可见元素上，复合组件内部必须支持方向键切换，弹层打开后焦点不能逃逸到背景内容。TypeScript可以在编译阶段把这些规则转成类型约束，让组件在接入IWAC时暴露不符合指南的风险。本文以一套可复用的类型封装为例，说明如何设计焦点区域、按键动作映射和导航守卫，并把它们接入React、Vue或原生项目。

一、把IWAC键盘导航规则拆成可建模的约束

IWAC对键盘导航的第一层约束是焦点区域。并不是所有元素都能成为焦点，只有明确标注为交互角色的节点才允许在Tab序列中出现。用TypeScript建模时，不能简单写成HTMLElement | null，因为这种类型无法区分按钮、菜单项、复选框和对话框。先定义一个角色联合类型，把所有可交互角色固定下来：

type FocusableRole = 'button' | 'link' | 'menuitem' | 'checkbox' | 'radio' | 'tab' | 'listbox' | 'option' | 'dialog';

这一步看起来简单，但它能避免开发者在组件里随手使用<span>或<div>接收tabIndex。IWAC要求可交互元素必须使用语义化角色，类型层面对角色的收紧，实际上是在推动组件使用正确的无障碍标记。接下来可以定义焦点区域结构：

interface FocusableRegion {
  role: FocusableRole;
  label: string;
  isVisible: boolean;
  isDisabled: boolean;
  tabIndex: number;
}

type KeyboardFocusTree = {
  root: FocusableRegion;
  children: FocusableRegion[];
  trapBoundary?: {
    first: FocusableRegion;
    last: FocusableRegion;
  };
};

上面的trapBoundary用来表达焦点陷阱边界。很多弹层组件在打开时会限制Tab切换范围，但黎巴嫩指南同时要求提供明确的退出方式，比如Escape键必须可用。因此边界类型不能只记录第一个和最后一个焦点，还要关联退出动作。这个约束在后续的导航守卫里会继续展开。

第二层约束是按键动作映射。IWAC不允许组件把所有按键都监听起来，再在回调里用if (event.key === 'Tab')散落判断。更好的做法是声明一个允许的按键集合，并把每个按键对应到具体行为。这样类型系统可以检查某个组件是否遗漏了必须支持的按键。

二、设计KeyActionMap与NavigationGuard类型

键盘导航的核心类型是按键动作映射。为了避免组件随意监听ArrowUp而忽略ArrowDown，可以设计一个基于允许按键的映射结构。对于普通按钮，只需要Enter和Space；对于菜单项，需要方向键和Home/End；对于对话框，Escape必须存在。

type AllowedKey = 'Tab' | 'Enter' | 'Space' | 'Escape' | 'ArrowUp' | 'ArrowDown' | 'ArrowLeft' | 'ArrowRight' | 'Home' | 'End';

type KeyActionMap = Partial<Record<AllowedKey, (event: KeyboardEvent) => void>>;

interface NavigationGuard {
  id: string;
  allowedKeys: AllowedKey[];
  requiredKeys: Extract<AllowedKey, 'Enter' | 'Escape' | 'ArrowUp' | 'ArrowDown'>;
  preventTrapping: boolean;
  onFocusLeave?: (event: FocusEvent) => void;
}

这里使用Extract从联合类型中筛出必须处理的按键。IWAC要求弹层类组件必须支持Escape关闭，列表类组件必须支持方向键移动。通过requiredKeys字段，可以在创建配置对象时进行校验。例如，一个对话框配置如果缺少Escape，在下游类型守卫中就会直接报错。

NavigationGuard还不够，因为键盘导航还包括焦点顺序。顺序不能只靠DOM顺序推断，有些视觉上靠前的元素可能被绝对定位到文档末尾。为此引入焦点顺序声明：

interface FocusOrderEntry {
  id: string;
  next: FocusableRegion;
  previous: FocusableRegion;
  skipWhenHidden: boolean;
}

type FocusOrderMap = Map<string, FocusOrderEntry>;

使用Map而不是数组，是为了在运行时快速查找当前焦点所在位置。类型层面，FocusableRegion的引用保证了next和previous不会指向未定义区域。IWAC特别强调焦点顺序必须与视觉逻辑一致，在弹层里还要支持循环，也就是最后一个焦点之后回到第一个。这个循环行为可以放在FocusOrderEntry中通过布尔值控制。

三、用类型守卫把运行时校验与编译期约束结合

泛型接口只能约束对象形状，无法自动判断某个DOM节点是否真的满足焦点条件。类型守卫的作用是把未知的运行时数据转换成可信任的IWAC类型。下面是一个焦点区域守卫：

function isFocusableRegion(value: unknown): value is FocusableRegion {
  if (typeof value !== 'object' || value === null) {
    return false;
  }
  const region = value as Record<string, unknown>;
  const roles: FocusableRole[] = ['button', 'link', 'menuitem', 'checkbox', 'radio', 'tab', 'listbox', 'option', 'dialog'];
  return typeof region.label === 'string' &&
    typeof region.isVisible === 'boolean' &&
    typeof region.isDisabled === 'boolean' &&
    typeof region.tabIndex === 'number' &&
    roles.includes(region.role as FocusableRole);
}

这个函数在获取DOM节点数据后调用，如果返回false，就说明该节点不符合IWAC焦点区域要求。关键在于类型收窄：一旦isFocusableRegion返回true，TypeScript后续的代码就能安全访问label、tabIndex等字段，不需要反复做空值判断。

按键动作映射同样需要守卫。经常出现的问题是，组件配置了Enter但没有配置Space，或者在按钮角色上塞入了方向键处理。对于普通按钮而言，IWAC只要求激活键，不要求方向键。类型守卫可以结合角色来检查：

function isValidKeyActionMap(role: FocusableRole, map: KeyActionMap): boolean {
  switch (role) {
    case 'button':
      return map.Enter !== undefined && map.Space !== undefined;
    case 'menuitem':
      return map.ArrowUp !== undefined && map.ArrowDown !== undefined && map.Enter !== undefined;
    case 'dialog':
      return map.Escape !== undefined;
    default:
      return map.Enter !== undefined || map.Space !== undefined;
  }
}

这种校验不会代替测试，但可以在组件初始化阶段拦截大部分配置错误。比如开发者给menuitem只绑定了Escape，isValidKeyActionMap会返回false，控制台可以直接抛出带有角色名和缺失按键的警告。这样IWAC的规则就从纸面文档变成了可执行的开发约束。

四、封装为通用配置对象并接入组件库

在真实项目中，键盘导航类型不应该散落在各个组件内部。可以创建一个工厂函数，把角色、按键映射、焦点顺序和导航守卫组合起来。这样做的好处是，React、Vue和原生项目都能复用同一套类型逻辑。

interface IWACKeyboardConfig {
  role: FocusableRole;
  keyMap: KeyActionMap;
  focusOrder?: FocusOrderMap;
  navigationGuard?: NavigationGuard;
}

function createIWACKeyboardHandler(config: IWACKeyboardConfig) {
  if (!isValidKeyActionMap(config.role, config.keyMap)) {
    throw new Error('IWAC key map does not match role: ' + config.role);
  }
  return (event: KeyboardEvent) => {
    const handler = config.keyMap[event.key as AllowedKey];
    if (handler) {
      handler(event);
    }
  };
}

在React组件中使用时，只需要在onKeyDown里传入工厂返回的处理器。需要注意的是，代码中不要直接使用any，因为那会破坏所有类型约束。以上工厂函数已经对配置进行了运行时校验，即使组件层没有做检查，错误也会在创建处理器时暴露。

IWAC键盘导航类型的另一个落地场景是自动化测试。类型定义可以生成测试脚手架，批量验证每个焦点区域是否满足FocusableRegion结构。例如在E2E测试中，通过遍历焦点顺序表，检查每个角色是否可用键盘到达。虽然测试脚本不能直接使用TypeScript类型，但类型定义可以同步出一份JSON Schema，供测试工具做快照对比。

最后需要提醒，类型封装不能解决所有无障碍问题。颜色对比度、屏幕阅读器标识、焦点可视样式仍然需要视觉和语义层面配合。但就键盘导航而言，把焦点区域、按键动作和导航守卫拆成明确类型，已经能显著减少违反IWAC指南的概率。维护类型时，应当跟随指南版本更新，定期审查FocusableRole和AllowedKey是否需要扩展。

TypeScript网络无障碍键盘导航修改时间：2026-09-28 13:38:16