如何使用TypeScript为IWAC封装古巴网络无障碍指南的链接上下文类型？

把链接上下文建模为TypeScript类型，并不是简单地把href和text塞进一个接口。古巴网络无障碍指南对链接可辨识性的要求可以拆成两层：第一层是链接文本本身是否传达了目标意图；第二层是当文本不足时，标题、ARIA标签、相邻文本或目标描述是否提供了补偿。IWAC在做自动审计时，需要同时读取这些信息并给出判定。如果这些字段没有类型约束，检测代码里就会出现大量的空值判断和字符串拼接，最终漏掉某些指南条款。下面先定义清晰的数据结构，再逐步加入联合类型和类型守卫。

一、从基础接口开始：把隐性规则显性化

古巴指南中规定，链接必须能够通过程序化方式确定其目的。为此，链接文本、可访问名称和上下文补充信息不能只存在于审计人员脑中。先用一个最基础的接口描述最小字段集合，然后在后续小节引入判别联合。这个基础接口不要急于包含所有可选字段，否则联合类型会变得臃肿。

type LinkPurpose = 'internal' | 'external' | 'document';

interface LinkContextBase {
  href: string;
  text: string;
  purpose: LinkPurpose;
  accessibleName?: string;
  adjacentText?: string;
  titleAttribute?: string;
  ariaLabel?: string;
  targetDescription?: string;
}

上面接口里的可选字段对应的是补偿性上下文。古巴网络无障碍指南并非要求每个链接都提供相邻文本，而是要求当链接文本无法独立说明目标时，必须存在至少一项补偿。类型层面虽然用可选字段不能直接表达“至少一项”的约束，但可以先让数据来源规范起来，后续通过类型守卫和自定义校验函数补足。

同时，href不要定义为any或unknown。一旦失去原始字符串的约束，后续解析内部锚点、外部域名和文件类型时就需要反复进行运行时类型判断。保留string并配合联合类型，能让IWAC的校验模块在编译期就获得足够信息。

二、用联合类型区分链接场景，避免属性错配

不同类型的链接需要不同的上下文字段。内部锚点需要fragmentId，外部链接需要domain和targetDescription，文档下载需要fileType和fileSize。如果只用一个大接口，IWAC检测时就会不断判断“这个字段到底该不该存在”。用判别联合可以在编译期把不同场景拆开。

type LinkContextBase = {
  href: string;
  text: string;
  purpose: 'internal' | 'external' | 'document';
};

type InternalLinkContext = LinkContextBase & {
  purpose: 'internal';
  fragmentId: string;
};

type ExternalLinkContext = LinkContextBase & {
  purpose: 'external';
  domain: string;
  targetDescription: string;
};

type DocumentLinkContext = LinkContextBase & {
  purpose: 'document';
  fileType: string;
  fileSize?: number;
};

type LinkContext = InternalLinkContext | ExternalLinkContext | DocumentLinkContext;

这里使用了交叉类型，交叉类型中的&在TypeScript里表示同时满足两组约束。这样外部链接上下文不可能缺少targetDescription，内部锚点也不能把domain混进去。相比单一接口，这种方式能减少大量属性拼写错误和字段遗漏。

古巴指南对外部资源的可访问性要求还包括“目标内容应当可预测”。例如一个外部链接指向PDF，应该预先告知用户文件类型。在DocumentLinkContext中把fileType设为必填，可以推动开发者补充描述。若仍需要大小信息，可用fileSize?: number保持可选。

三、类型守卫把联合收窄为具体分支

当IWAC拿到一个LinkContext联合类型值时，不能直接读取targetDescription，因为TypeScript会提示该属性不一定存在。需要先根据purpose字段做判别。手动写if (context.purpose === 'external')虽然可以收窄，但分散在多个检测函数里并不统一。封装成类型守卫能复用判别逻辑。

function isExternalLinkContext(context: LinkContext): context is ExternalLinkContext {
  return context.purpose === 'external';
}

function isInternalLinkContext(context: LinkContext): context is InternalLinkContext {
  return context.purpose === 'internal';
}

function isDocumentLinkContext(context: LinkContext): context is DocumentLinkContext {
  return context.purpose === 'document';
}

类型守卫函数中使用了context is ExternalLinkContext这种类型谓词语法，它告诉TypeScript：当函数返回true时，参数应当按ExternalLinkContext处理。这样后续代码里访问targetDescription就不会报错。对于IWAC检测脚本来说，各规则函数可以先经过守卫，再执行特定检测，不必重复判断。

例如外部链接规则只关心href、text和targetDescription，可以这样组织：

function auditExternalLink(context: LinkContext): string[] {
  if (!isExternalLinkContext(context)) {
    return [];
  }

  const issues: string[] = [];

  if (context.text.trim().length === 0 && context.accessibleName === undefined) {
    issues.push('缺少可访问名称且链接文本为空');
  }

  if (context.targetDescription.trim().length === 0) {
    issues.push('外部链接未提供目标描述');
  }

  return issues;
}

注意代码中的逻辑判断使用了&&，在TypeScript中表示逻辑与。古巴指南强调的“链接文本为空但可访问名称存在”也是可接受的，因此这里条件写的是两者都缺失才记录问题。这个例子展示了类型守卫如何让审计函数不产生多余的属性访问。

四、运行时校验与编译期约束的边界

有些开发者会认为，既然TypeScript已经约束了字段，运行时就不再需要校验。但IWAC的数据可能来自DOM扫描结果，这些结果在类型层面仍然被认为是LinkContext，实际上可能存在缺失字段。因此类型建模不能替代数据清洗。建议在数据进入检测层之前，用单独的解析函数把原始DOM信息转换为符合联合类型的对象，并在解析时完成兜底。

function parseLinkContext(raw: Record<string, unknown>): LinkContext | null {
  if (typeof raw.href !== 'string' || typeof raw.text !== 'string') {
    return null;
  }

  const purpose = raw.purpose;

  if (purpose === 'internal') {
    return {
      href: raw.href,
      text: raw.text,
      purpose: 'internal',
      fragmentId: typeof raw.fragmentId === 'string' ? raw.fragmentId : '#'
    };
  }

  if (purpose === 'external') {
    return {
      href: raw.href,
      text: raw.text,
      purpose: 'external',
      domain: typeof raw.domain === 'string' ? raw.domain : '',
      targetDescription: typeof raw.targetDescription === 'string' ? raw.targetDescription : ''
    };
  }

  return null;
}

可以看到，Record<string, unknown>是一种常见的原始数据描述方式。这里的<和>是TypeScript泛型语法，写入HTML代码块时需要转义为<与>，但在实际源码中仍是尖括号。解析函数返回null表示数据无法映射为已知链接类型，从而阻止无效对象进入后续审计。

这种“编译期约束+运行时清洗”的组合，能让IWAC在复杂页面中保持稳定。类型定义负责团队成员之间的契约，解析函数负责外部边界的防御。古巴指南中涉及链接的条款较多，后续若要增加新场景，例如邮箱链接或电话链接，可以在联合类型中增加分支，并同步补充解析逻辑。

TypeScriptIWAC网络无障碍指南修改时间：2026-09-20 08:48:06