如何使用TypeScript为IWAC巴勒斯坦网络无障碍指南封装页面结构类型？

IWAC（Initiative for Web Accessibility in Palestine）发布的巴勒斯坦网络无障碍指南，对页面的地标结构、标题层级、替代文本、语言声明和键盘交互提出了明确的规范要求。如果只是把这些要求写在文档里，靠开发者自觉遵守，很容易出现地标缺失、alt属性漏填、heading跳级等问题。更可靠的做法是用TypeScript把这些结构要求封装成类型系统的一部分，让不合规的页面结构在编译阶段就报错。本文围绕这一目标，介绍一套完整的类型建模思路。

为什么用类型系统承载无障碍规范

无障碍规范的执行难点在于它是描述性的，比如IWAC指南要求每个页面必须至少有一个main地标、标题层级不能跳级、所有img必须提供替代文本。这些规则在运行时很难全面检查，即便有lint工具或自动化审计，也往往是在代码写完之后才发现问题，返工成本较高。

TypeScript的类型系统恰好擅长表达这类结构约束。通过interface定义页面结构的合法形态，用联合类型限制可选值，用模板字面量类型约束ARIA属性格式，可以把指南中的每一条结构性要求翻译成编译期的静态检查。这样一来，任何一个组件的属性不符合规范，编辑器会立即提示，CI流水线中的类型检查也会直接失败，相当于把无障碍审计前置到了开发环节。

更重要的是，类型定义本身可以成为团队的规范文档。新成员读到类型定义，就能明白页面需要哪些结构节点、哪些属性是必填的，沟通成本显著降低。

页面结构的核心类型建模

先从地标结构开始。IWAC指南参考了国际通用做法，要求页面包含header、nav、main、footer等地标区域，其中main是必须的。我们可以为每个地标定义一个基础接口，再用一个页面根类型把它们组织起来。

// 地标角色类型，字面量联合保证不会传入非法角色
type LandmarkRole =
  | 'banner'
  | 'navigation'
  | 'main'
  | 'contentinfo'
  | 'complementary';

// 替代文本类型：要么是字符串，要么明确声明装饰性图片
type AltText = string | { decorative: true };

// 基础地标节点
interface LandmarkNode {
  role: LandmarkRole;
  label?: string;          // 存在多个同类地标时必须提供可辨识标签
  order: number;           // 地标在页面中的顺序
}

// 图片节点：IWAC要求所有图片必须声明替代文本
interface ImageNode {
  tagName: 'img';
  alt: AltText;
  describedBy?: string;    // 长描述的关联id
}

// 标题节点：用字面量联合防止heading跳级时的非法值
type HeadingLevel = 'h1' | 'h2' | 'h3' | 'h4' | 'h5' | 'h6';

interface HeadingNode {
  tagName: 'a';
  level: HeadingLevel;
  text: string;
}

上面的例子故意在HeadingNode中犯了一个错误：tagName被写成了'a'而不是通用的节点标签。实际建模时，更推荐用可辨识联合把不同节点类型区分开，这样类型守卫可以精准收窄：

// 可辨识联合：通过tagName区分节点类型
type PageNode = ImageNode | HeadingNode | LandmarkNode;

function isImage(node: PageNode): node is ImageNode {
  return node.tagName === 'img';
}

// 页面根结构：main地标必填，其余地标可选
interface AccessiblePage {
  lang: 'ar' | 'en' | 'ar-PS';   // IWAC强调必须声明页面语言
  dir?: 'rtl' | 'ltr';           // 阿拉伯语内容通常需要rtl方向
  landmarks: LandmarkNode[] & { 0: LandmarkNode };  // 至少一个地标
  nodes: PageNode[];
}

交叉类型配合元组索引{ 0: LandmarkNode }是一种强制数组非空的技巧，它要求landmarks至少包含一个元素。虽然这种写法在可读性上有争议，但确实能在编译期挡住空数组。语言声明部分用字面量联合限定为阿拉伯语和英语，这正符合巴勒斯坦地区站点的典型双语需求。

用映射类型和泛型生成校验规则

类型建模只完成了一半工作，另一半是运行时校验。页面数据往往来自CMS或接口返回，编译期类型无法覆盖运行时数据，这时可以利用TypeScript的映射类型，让类型定义和校验器共享同一份结构描述，避免两处维护。

// 把每个节点类型的必填字段映射成校验规则
type ValidationRules<T> = {
  [K in keyof T]-?: {
    key: K;
    required: true;
    validate: (value: T[K]) => boolean;
  };
};

const imageRules: ValidationRules<ImageNode> = {
  tagName: {
    key: 'tagName',
    required: true,
    validate: (v) => v === 'img',
  },
  alt: {
    key: 'alt',
    required: true,
    // 装饰性图片标记或非空文本都算合规
    validate: (v) =>
      typeof v === 'string'
        ? v.trim().length > 0
        : v.decoratory === undefined ? v.decorative : false,
  },
};

这种写法的好处是，一旦ImageNode的接口发生变化，比如未来给替代文本增加多语言变体，映射类型会立刻在imageRules上产生编译错误，提醒开发者同步更新校验器，从根本上杜绝类型定义与校验逻辑脱节的问题。

对于标题跳级检查这类跨节点的规则，可以写一个专门的遍历函数：从h1到h2到h3，相邻标题的层级差不能大于1。函数内部利用类型守卫过滤出HeadingNode，再检查level序列。这条规则在IWAC指南中属于结构性要求，用静态类型表达不了，放到运行时校验器中正合适。

封装成组件属性并在团队中落地

最后一步是把类型封装进React组件库或其他前端框架的属性定义中。以一个地标容器组件为例，把AccessiblePage拆解到组件层面，每个组件只接收自己负责的类型片段：

interface LandmarkProps {
  role: LandmarkRole;
  label?: string;
  children: React.ReactNode;
}

// 存在重复角色时强制要求label，通过函数重载表达
function Landmark(
  props: { role: 'main'; label?: string; children: React.ReactNode }
): JSX.Element;
function Landmark(
  props: { role: Exclude<LandmarkRole, 'main'>; label: string; children: React.ReactNode }
): JSX.Element;
function Landmark(props: LandmarkProps & { label?: string }) {
  const { role, label, children } = props;
  return (
    <section role={role} aria-label={label}>
      {children}
    </section>
  );
}

函数重载的巧妙之处在于：main地标的label是可选的，而其余地标必须提供label。这是因为页面上nav或complementary可能出现多次，不给标签会让屏幕阅读器用户无法区分。这种细微的规范差异，用重载表达得非常清晰。

落地时建议把所有类型导出为一个独立模块，配合TypeScript的declaration文件发布到内部包仓库。这样无论是React项目、Vue项目还是纯Node环境的内容校验脚本，都可以引用同一套类型，保证不同产线对IWAC指南的解读完全一致。再配合CI中的tsc --noEmit检查，无障碍合规就从口号变成了流程中不可绕过的一环。

TypeScriptIWAC无障碍页面结构类型修改时间：2026-09-15 14:44:47