如何用TypeScript为IWAC封装尼泊尔网络无障碍指南的键盘导航类型定义？

在承接尼泊尔政府门户的前端改造时，我们发现IWAC（尼泊尔网络无障碍指南）对键盘导航的规定非常细致，比如主菜单必须用Alt加方向键移动，弹窗关闭要优先响应Escape。直接用JavaScript写这些逻辑，稍不注意就会把按键字符串拼错，或者焦点陷阱配置缺失。借助TypeScript的类型系统，可以把这些规则变成编译期强制约束，从根源上减少无障碍缺陷。

理解IWAC键盘导航的核心约束

IWAC文档里对键盘操作的描述分散在多个章节，但归纳起来主要有三类要求：全局快捷键、区域间跳转、以及模态环境下的焦点陷阱。全局快捷键规定站点级操作（如跳到搜索框）的按键组合；区域间跳转针对Landmark结构，要求用户能用单一按键在header、nav、main之间切换；焦点陷阱则出现在对话框与菜单中，必须保证Tab键不会逃出当前容器。

如果不做类型封装，开发者通常把按键存成普通字符串，例如'Alt+ArrowRight'，然后在事件处理函数里用字符串匹配。这种方式的问题在于，拼写错误不会报错，且当尼泊尔团队提出新组合时，旧代码无法感知变更。我们需要用TypeScript把“合法按键组合”这一集合收敛为有限类型，让非法值直接编译失败。

此外，IWAC特别强调键盘导航不能依赖鼠标事件做兜底，这意味着类型定义里还要体现“纯键盘可达”的标记。我们可以在类型中加入keyboardOnly布尔字段，提示该导航路径不允许任何pointer事件参与，从而在类型层面落实规范精神。

用TypeScript枚举与接口封装按键映射

第一步是定义按键枚举。IWAC涉及的修饰键有限，我们可以用枚举固定下来，避免字符串散落。下面的代码展示了基础枚举和组合类型的写法，其中用到了字符串字面量联合类型来约束最终的组合格式。

export enum IWACModifier {
  Alt = 'Alt',
  Control = 'Control',
  Shift = 'Shift'
}

export type IWACArrowKey = 'ArrowLeft' | 'ArrowRight' | 'ArrowUp' | 'ArrowDown';

export type IWACKeyCombo = `${IWACModifier}+${IWACArrowKey}` | 'Escape' | 'Tab';

export interface IWACNavBinding {
  combo: IWACKeyCombo;
  description: string;
  keyboardOnly: boolean;
}

上面的IWACKeyCombo利用模板字面量类型，把修饰键和方向键的拼接限制死。如果有人写combo: 'Alt+Right'，TypeScript会立刻报错，因为Right不在IWACArrowKey里。这种写法比跑运行时校验轻量得多，也更适合被其他模块复用。

接下来可以声明一组预置绑定，对应IWAC的具体条款。我们用const断言让数组变成只读元组，后续遍历时类型不会拓宽成string。这样在写快捷键帮助面板时，IDE能自动提示每一个合法组合的含义，降低文档与代码不一致的风险。

export const IWAC_MAIN_MENU_BINDINGS = [
  { combo: 'Alt+ArrowRight', description: '移动到下一个主菜单项', keyboardOnly: true },
  { combo: 'Alt+ArrowLeft', description: '移动到上一个主菜单项', keyboardOnly: true },
  { combo: 'Escape', description: '关闭打开的菜单', keyboardOnly: true }
] as const satisfies readonly IWACNavBinding[];

这里用到的satisfies关键字能在不破坏字面量类型的前提下做结构校验。如果尼泊尔规范后续增加Control+Home回到顶部，只改枚举和数组即可，所有消费方的类型推导会自动更新，不必全局搜索字符串。

焦点陷阱与区域跳转的类型建模

键盘导航的另一块是焦点管理。IWAC要求模态框打开时，Tab和Shift+Tab必须在内部循环。我们可以用类型描述“陷阱容器”的能力，而不是在业务代码里写一堆querySelectorAll。下面的接口把焦点陷阱抽象为可配置对象。

export interface IWACFocusTrap {
  containerSelector: string;
  initialFocus: 'first' | 'last' | string;
  escapeExits: boolean;
  onExit: () => void;
}

export function createTrap(config: IWACFocusTrap): { activate: () => void; deactivate: () => void } {
  // 实际实现中根据config.containerSelector锁定焦点
  return {
    activate: () => {},
    deactivate: () => {}
  };
}

类型里的initialFocus用联合类型限制了只能是特定关键字或选择器字符串，避免传入无意义的值。配合前面的按键绑定，在对话框组件挂载时，我们只需把IWACFocusTrap和IWACNavBinding组合起来，就能形成一套符合尼泊尔指南的键盘交互骨架。

区域跳转方面，IWAC建议用单键在landmark之间移动。我们可以定义IWACRegionRole类型，并用映射类型生成跳转表。这样当设计稿调整区域顺序时，类型检查会提醒开发者同步更新跳转关系，防止键盘用户跳到已被移除的区域。

export type IWACRegionRole = 'banner' | 'navigation' | 'main' | 'contentinfo';

export type IWACRegionJumpMap = Record<IWACRegionRole, IWACKeyCombo>;

const nepalRegionJumps: IWACRegionJumpMap = {
  banner: 'Alt+ArrowUp',
  navigation: 'Alt+ArrowRight',
  main: 'Alt+ArrowDown',
  contentinfo: 'Alt+ArrowLeft'
};

上述代码在pre块内展示HTML相关概念时，将<input>等标签名做了转义，但在正文讨论中我们使用code标签包裹类型名如IWACRegionRole来做行内高亮。最终，把这些类型打包成npm私有包，尼泊尔外包团队和国内团队都能共享同一套键盘导航契约，大幅降低沟通成本与回归缺陷率。

TypeScriptIWACkeyboard_navigation修改时间：2026-08-18 05:48:13