如何使用TypeScript为NWAC封装尼泊尔网络无障碍指南的非文本内容类型？

尼泊尔网络无障碍指南（NWAC）对非文本内容的处理要求并不是简单要求所有图片都写上替代文本，而是根据内容的用途和交互场景区分出功能型、信息型、装饰型、感官型、验证码和时间媒体等不同类别。每一类需要携带的字段差异很大，例如装饰性图片只需要标记为presentational，而功能性图标必须提供可访问名称，视频则需要字幕轨和口述影像轨。把这些规则封装成TypeScript类型与工具函数，可以让开发、测试和内容审核人员使用同一套可校验的数据结构。

先厘清非文本内容的分类结构

NWAC参考了国际通用的无障碍原则，同时针对尼泊尔多语言、多文字环境增加了本地化要求。非文本内容并不是单一实体，而是至少可以拆成六个子类。装饰性内容如果辅助了页面视觉布局，必须明确标记为presentational，不能只留空alt属性，否则屏幕阅读器会尝试读取文件名造成干扰。功能性内容主要指按钮、链接、开关等使用图标或图片作为交互控件的情况，这类内容必须提供可访问名称，名称不能依赖颜色或形状传递。

信息型内容用于传达数据或概念，例如图表、示意图、流程图，需要替代文本准确描述信息本身，而不是简单写图片二字。验证码在NWAC中被特别强调，因为尼泊尔存在多种本地语言，仅提供视觉验证码会排斥视障用户，必须提供音频替代或逻辑问题。时间媒体包括音频和视频，音频需要文字稿，视频需要字幕、口述影像或手语轨。感官内容可能涉及艺术效果或氛围营造，需要根据是否传递关键信息来决定处理策略。如果不进行这种分类，封装时很容易写成一个只有可选alt字段的普通接口，丢失大量无障碍规则信息。

在实际项目中，很多内容管理系统会把图片、图标、图表统一存储为媒体资源，但无障碍处理策略完全不同。借助TypeScript的判别联合，可以在编译期就暴露缺字段、错分类的问题，而不是等到运行阶段才发现某个视频没有字幕。

设计TypeScript类型与判别字段

封装的第一步是定义一个字符串字面量联合作为分类标识，然后让每个子类型继承一个基础接口，并通过category字段进行区分。基础接口可以包含id、分类和通用的可访问标签，但具体字段必须由子类型强制要求。这样可以避免把所有可能字段都堆在一个接口里造成大量可选属性。

type NonTextCategory = 'decorative' | 'functional' | 'informative' | 'sensory' | 'captcha' | 'media';

interface BaseNonTextContent {
  id: string;
  category: NonTextCategory;
  accessibilityLabel?: string;
}

interface DecorativeContent extends BaseNonTextContent {
  category: 'decorative';
  presentational: true;
}

interface FunctionalContent extends BaseNonTextContent {
  category: 'functional';
  role: 'button' | 'link' | 'switch';
  accessibleName: string;
}

interface InformativeContent extends BaseNonTextContent {
  category: 'informative';
  alternativeText: string;
}

interface CaptchaContent extends BaseNonTextContent {
  category: 'captcha';
  audioAlternativeUrl: string;
  logicQuestion?: string;
}

interface MediaContent extends BaseNonTextContent {
  category: 'media';
  mediaType: 'audio' | 'video';
  captions?: string[];
  audioDescription?: string;
  signLanguage?: string[];
}

type NonTextContent = DecorativeContent | FunctionalContent | InformativeContent | CaptchaContent | MediaContent;

上面的类型定义把NWAC的非文本内容要求转化为强约束。FunctionalContent要求accessibleName必须存在，DecorativeContent要求presentational必须为true，MediaContent则根据mediaType进一步区分字段。这样当开发者处理一个传入的NonTextContent对象时，TypeScript可以根据category字段自动收窄类型，访问content.accessibleName不会报错，但访问装饰性内容的accessibleName会在编译期提示可能不存在。这种设计比简单使用可选属性安全得多，也能防止把验证码的音频地址误写到普通图片对象上。

判别联合的意义不仅在于类型安全，还在于可以通过穷举检查防止遗漏新分类。如果未来NWAC新增了一个非文本内容子类，只需扩展NonTextCategory和对应接口，TypeScript会在所有使用了switch或if的地方提示未处理的新分支。扩展封装时不会出现静默漏判。

实现NWAC规则校验器

类型定义只能约束数据形状，无法检查替代文本是否写成了占位词，也无法判断验证码是否真的提供了音频链接。因此封装还需要一层校验函数，把NWAC的定性要求转换成可执行的检查项。校验器接收一个NonTextContent对象，返回错误消息数组，数组为空表示通过了基本检查。

function validateNonTextContent(content: NonTextContent): string[] {
  const errors: string[] = [];
  switch (content.category) {
    case 'decorative':
      if (!content.presentational) {
        errors.push('装饰性内容必须标记为presentational');
      }
      break;
    case 'functional':
      if (!content.accessibleName || content.accessibleName.trim().length === 0) {
        errors.push('功能性非文本内容缺少可访问名称');
      }
      break;
    case 'informative':
      if (!content.alternativeText || content.alternativeText.length < 5) {
        errors.push('信息型非文本内容替代文本过短或缺失');
      }
      break;
    case 'captcha':
      if (!content.audioAlternativeUrl) {
        errors.push('验证码必须提供音频替代');
      }
      break;
    case 'media':
      if (content.mediaType === 'video' && (!content.captions || content.captions.length === 0)) {
        errors.push('视频内容缺少字幕轨');
      }
      break;
    case 'sensory':
      // 感官内容如果不传递关键信息，可以按装饰处理，否则需要补充描述
      break;
  }
  return errors;
}

这个校验器中的规则直接对应NWAC对非文本内容的基本要求。替代文本长度检查只是一个防止占位文本的简单策略，实际项目中还可以增加正则判断，例如检测alternativeText中是否包含image、picture、photo等无意义单词，或者是否只写了文件扩展名。验证码的audioAlternativeUrl必须是可用地址，不能是空字符串或者指向不存在的资源。视频缺少字幕轨时校验器会报错，但要注意某些视频可能通过手语或其他方式提供了等效信息，所以规则应该允许配置豁免条件。

校验器返回错误数组而不是直接抛出异常，有利于在表单提交、批量审核、测试断言等场景中灵活使用。可以在前端渲染时根据错误数组显示提示，也可以在CI流程中扫描页面数据生成报告。把校验逻辑独立成纯函数，不依赖DOM和框架，便于在不同环境中复用。

封装为可复用的TypeScript模块

将类型定义、判别字段和校验函数组织成模块后，可以发布到内部npm仓库供多个项目使用。模块入口可以统一导出类型和校验器，避免使用方从深层路径导入。导出结构保持简单清晰，后续增加新规则时不会影响已有引用。

export * from './types';
export { validateNonTextContent } from './validator';
export { nwacRules } from './rules';

在前端组件中使用时，可以结合框架的渲染逻辑自动生成无障碍属性。例如图片组件接收到NonTextContent对象后，如果是装饰性内容就输出aria-hidden为true，并省略alt；如果是功能性内容就根据accessibleName生成aria-label；如果是信息型内容就生成alt。对于HTML标签的书写，不能直接写<img>的alt为空字符串，而要根据分类调用不同输出方式。这样可以把NWAC规则沉淀到UI组件层，减少开发人员手动判断的负担。

测试环节可以利用同样的类型和校验器构造测试数据，验证页面是否遗漏了视频字幕或者验证码音频。自动化测试脚本可以遍历DOM中所有图片、按钮图标和媒体节点，将它们映射为NonTextContent对象后调用validateNonTextContent，再把返回的错误关联到具体元素。这种做法比单纯抽查几个页面更稳定，也能持续跟踪无障碍合规状态。

随着NWAC的更新，封装模块只需调整类型和校验规则，所有依赖项目升级依赖后即可获得新的检查能力。要避免把规则散落在各个业务代码中，因为一旦规则变更，分散的if判断很难全部找到。集中封装非文本内容类型是保持无障碍标准一致性的关键一步。

TypeScriptNWAC非文本内容修改时间：2026-09-24 13:31:50