如何用TypeScript为IWAC无障碍网页应用封装加纳焦点指示器类型定义？

加纳无障碍指南（IWAC，Inclusive Web Accessibility Guidelines）对键盘焦点指示器提出了明确要求：焦点可见、对比度充足、不能仅依赖颜色传达信息。如果只用原生:focus样式草草了事，很容易出现指示器过细、颜色对比不足等问题，导致键盘用户完全找不到自己在页面上的位置。用TypeScript为这些约束建模，可以把规范条文直接固化进类型系统，让不合规的配置在编译期就报错。本文围绕焦点指示器的类型定义展开，从属性建模、配置结构设计到运行时校验，逐步给出一套可落地的封装方案。

一、用字面量联合类型约束指示器核心属性

焦点指示器的第一个问题是形状和颜色的取值是有限集合，而不是任意字符串。如果定义为string类型，调用方随手传入"dotted"或拼错单词，编译器毫无察觉。字面量联合类型可以精确表达IWAC允许的取值范围。

IWAC建议焦点指示器至少提供轮廓线、底色变化、下划线三种呈现方式，并且不允许只用颜色作为唯一线索。据此可以先定义形状相关的类型：

// 焦点指示器的呈现风格，IWAC要求至少支持这三种
export type FocusIndicatorStyle =
  | 'outline'    // 外轮廓线
  | 'box-shadow' // 阴影环绕
  | 'underline'; // 下划线增强

// 轮廓线风格枚举，保持有限取值
export type FocusOutlinePattern =
  | 'solid'
  | 'double'
  | 'dashed';

// 状态标记，用于区分键盘焦点与鼠标焦点
export type FocusVisibilityMode =
  | 'always'       // 始终显示
  | 'keyboard-only'; // 仅键盘操作时显示

这样定义的好处是显而易见的：当某个组件传入'dash'这种拼错的值，TypeScript会立刻标红提示。相比运行时才发现样式不生效，编译期拦截的成本几乎为零。此外，联合类型自带文档属性，IDE的自动补全会列出所有合法值，接口使用方不需要翻规范文档。

对于颜色，IWAC要求焦点指示器与背景的对比度不低于3:1。颜色本身无法用联合类型穷举，但可以把对比度校验逻辑封装到后面的小节中，类型层面只约束输入格式：

export interface FocusColorConfig {
  /** 前景色，支持 HEX 或 RGB 字符串 */
  foreground: string;
  /** 背景色，用于计算对比度 */
  background: string;
  /** 是否允许仅在深色背景下自动反转颜色 */
  autoInvert?: boolean;
}

二、组合出可复用的配置接口与泛型结构

有了基础类型，下一步是把它们组装成完整的配置结构。实际项目中，焦点指示器往往要区分尺寸档位（如细、标准、加粗），还要支持为不同交互元素（按钮、输入框、链接）配置差异化样式。用接口继承加泛型可以做到一套结构多处复用。

export interface FocusIndicatorOptions {
  style: FocusIndicatorStyle;
  outline?: {
    pattern: FocusOutlinePattern;
    /** IWAC要求轮廓宽度不低于2px */
    width: 2 | 3 | 4;
    offset?: number;
  };
  color: FocusColorConfig;
  visibility: FocusVisibilityMode;
}

// 泛型约束：不同元素类型可以有各自的默认配置
export type ElementFocusConfig<T extends string = string> = {
  elementType: T;
  options: FocusIndicatorOptions;
};

export interface IWACFocusPreset {
  button: ElementFocusConfig<'button'>;
  input: ElementFocusConfig<'input'>;
  link: ElementFocusConfig<'link'>;
  global: FocusIndicatorOptions;
}

注意width: 2 | 3 | 4这个写法，它把IWAC的最低宽度要求直接编码进了类型。传1会被拒绝，传2.5也会被拒绝，规范条文变成了类型约束。这是类型驱动开发最有价值的实践之一：规范不再只是文档里的描述，而是编译器强制执行规则。

泛型参数T在这里的作用是让预设结构扩展性更好。假设后续项目需要支持tab组件的焦点配置，只需扩展联合类型而不用改动已有定义。如果团队规模较大，还可以进一步用Readonly包装导出的预设常量，防止运行时被意外篡改：

export const defaultPreset: Readonly<IWACFocusPreset> = {
  button: {
    elementType: 'button',
    options: {
      style: 'outline',
      outline: { pattern: 'solid', width: 2, offset: 2 },
      color: { foreground: '#0b5fff', background: '#ffffff' },
      visibility: 'keyboard-only',
    },
  },
  input: {
    elementType: 'input',
    options: {
      style: 'box-shadow',
      color: { foreground: '#1a1a1a', background: '#ffffff' },
      visibility: 'always',
    },
  },
  link: {
    elementType: 'link',
    options: {
      style: 'underline',
      color: { foreground: '#0b5fff', background: '#ffffff' },
      visibility: 'keyboard-only',
    },
  },
  global: {
    style: 'outline',
    color: { foreground: '#0b5fff', background: '#ffffff' },
    visibility: 'keyboard-only',
  },
};

三、类型守卫与运行时校验：让外部数据也安全

类型系统只能在编译期起作用。如果配置来自JSON文件、后端接口或用户自定义主题，TypeScript的约束就失效了，因为JSON.parse返回的是any。这时候需要类型守卫在运行时兜底，确保外部数据符合IWAC约束后再进入组件渲染流程。

类型守卫的核心是options is FocusIndicatorOptions这种返回值写法，它让TypeScript在条件分支内自动收窄类型。校验逻辑要覆盖三件事：形状取值是否合法、轮廓宽度是否达标、颜色对比度是否满足3:1。对比度计算遵循WCAG的相对亮度公式，而IWAC沿用了同一套算法：

// 将 HEX 转为 [r, g, b]
function hexToRgb(hex: string): [number, number, number] {
  const value = hex.replace('#', '');
  return [
    parseInt(value.slice(0, 2), 16),
    parseInt(value.slice(2, 4), 16),
    parseInt(value.slice(4, 6), 16),
  ];
}

// WCAG 相对亮度
function relativeLuminance(rgb: [number, number, number]): number {
  const [r, g, b] = rgb.map(v => {
    const s = v / 255;
    return s <= 0.03928 ? s / 12.92 : Math.pow((s + 0.055) / 1.055, 2.4);
  });
  return 0.2126 * r + 0.7152 * g + 0.0722 * b;
}

// IWAC 要求焦点指示器对比度不低于 3:1
export function meetsContrastRatio(fg: string, bg: string): boolean {
  const l1 = relativeLuminance(hexToRgb(fg));
  const l2 = relativeLuminance(hexToRgb(bg));
  const ratio = (Math.max(l1, l2) + 0.05) / (Math.min(l1, l2) + 0.05);
  return ratio >= 3;
}

const VALID_STYLES: FocusIndicatorStyle[] = ['outline', 'box-shadow', 'underline'];

export function isFocusIndicatorOptions(
  data: unknown,
): data is FocusIndicatorOptions {
  if (typeof data !== 'object' || data === null) return false;
  const d = data as Record<string, unknown>;
  if (typeof d.style !== 'string' || !VALID_STYLES.includes(d.style as FocusIndicatorStyle)) {
    return false;
  }
  if (!meetsContrastRatio(d.color.foreground as string, d.color.background as string)) {
    return false;
  }
  if (d.outline !== undefined && ![2, 3, 4].includes(d.outline.width as number)) {
    return false;
  }
  return d.visibility === 'always' || d.visibility === 'keyboard-only';
}

有了守卫函数，外部配置的加载逻辑就非常干净：先校验、后使用，失败时回退到默认预设并输出警告。这种模式比到处写if判断可维护得多，而且守卫函数本身可以单独导出供单元测试使用，验证各种边界输入的行为是否符合预期。

四、从类型定义到CSS生成：让封装闭环

类型定义的最终目的是驱动样式输出。可以在类型层之上再封装一个生成函数，把FocusIndicatorOptions转换成实际的CSS声明，同时针对keyboard-only模式自动添加:focus-visible选择器，这样浏览器只会在键盘操作时展示指示器，避免鼠标点击也出现一圈轮廓的干扰。

export function buildFocusCss(options: FocusIndicatorOptions): string {
  const selector =
    options.visibility === 'keyboard-only' ? ':focus-visible' : ':focus';

  switch (options.style) {
    case 'outline':
      return `${selector} {
  outline: ${options.outline?.width ?? 2}px ${options.outline?.pattern ?? 'solid'} ${options.color.foreground};
  outline-offset: ${options.outline?.offset ?? 2}px;
}`;
    case 'box-shadow':
      return `${selector} {
  box-shadow: 0 0 0 3px ${options.color.foreground};
}`;
    case 'underline':
      return `${selector} {
  text-decoration: underline;
  text-decoration-thickness: 3px;
  text-underline-offset: 3px;
}`;
  }
}

这个生成函数之所以能写得如此简洁，完全得益于前文的类型约束：宽度、风格、颜色都已经在类型层面和运行时校验中保证合法，函数内部不需要防御性检查。这就是类型封装的价值传递链条——规范条文变成类型，类型简化实现，实现保证输出合规。

最后提醒两个实践细节。第一，务必在真实键盘操作下测试焦点表现，只用鼠标点击无法暴露问题；第二，如果项目还支持深色模式，记得让FocusColorConfig的autoInvert参与对比度计算，否则深色背景下预设的蓝色指示器可能不满足3:1的要求。把这套类型定义放进公共包并配套单元测试，团队里任何人新增焦点样式都会被规范约束，无障碍质量就能长期保持。

TypeScript焦点指示器无障碍IWAC修改时间：2026-09-10 02:16:54