如果组件里的role、aria-expanded、aria-checked一直以普通字符串形式存在，那么TypeScript在无障碍语义层面基本帮不上忙。更麻烦的是，ARIA规范不仅约束了每个属性和角色的拼写，还约束了它们之间的组合关系。例如checkbox角色可以配合aria-checked，但通常不会使用aria-level；combobox角色则依赖aria-expanded和aria-controls来描述弹层状态与关联元素。要让这些约束进入类型系统，仅仅依赖DOM库中比较宽泛的AriaRole和AriaAttributes类型还不够，需要在此基础上做一层面向组件开发习惯的封装。
先建立可靠的ARIA角色与属性基础类型
类型封装的第一步是把常用ARIA角色从宽泛字符串中抽出来。WAI-ARIA规范定义了大量角色，不同项目可能只使用其中一部分。建议先根据实际组件库中出现的角色定义字面量联合类型，这样既能保留自动补全，也不会因为引入完整规范类型而让泛型推断变得过于复杂。例如可以定义一个相对精简的AriaRole类型，覆盖按钮、复选框、组合框、列表框、选项卡等常见交互模式。
type AriaRole = | 'button' | 'checkbox' | 'combobox' | 'listbox' | 'option' | 'radiogroup' | 'radio' | 'textbox' | 'slider' | 'tablist' | 'tab' | 'tabpanel' | 'tree' | 'treeitem' | 'menu' | 'menuitem' | 'dialog' | 'alert' | 'switch' | 'progressbar';
这个联合类型有两个作用：第一，把角色名称从string收窄到具体的字面量，任何拼写错误都会在编译阶段被提示；第二，后续所有角色到属性的映射都会以这个联合类型作为约束边界，避免出现某个角色只在接口里存在、却不在基础类型中的不一致问题。对于没有覆盖到的角色，可以通过并集扩展维护一个项目级角色表，而不建议直接退回string。
属性侧同样不能简单使用Record<string, string>。ARIA属性分为布尔型、枚举型、ID引用型和自由文本型。比如aria-hidden通常接受'true' | 'false'，aria-checked还多一个'mixed'，aria-controls接受元素ID，而aria-label接受任意文本。为了表达这些差异，可以单独定义若干属性值类型，再组合成统一的ARIA属性集合。这样组件调用方不需要记住某个属性到底该传布尔值还是字符串，编译器会直接提示合法取值。
type Booleanish = 'true' | 'false';
type CheckedState = Booleanish | 'mixed';
interface AriaAttributeMap {
'aria-hidden'?: Booleanish;
'aria-expanded'?: Booleanish;
'aria-checked'?: CheckedState;
'aria-selected'?: Booleanish;
'aria-disabled'?: Booleanish;
'aria-label'?: string;
'aria-labelledby'?: string;
'aria-describedby'?: string;
'aria-controls'?: string;
'aria-owns'?: string;
'aria-haspopup'?: 'true' | 'false' | 'menu' | 'listbox' | 'tree' | 'grid' | 'dialog';
'aria-level'?: number;
'aria-valuemin'?: number;
'aria-valuemax'?: number;
'aria-valuenow'?: number;
'aria-valuetext'?: string;
'aria-orientation'?: 'horizontal' | 'vertical';
}
这里把aria-valuemin、aria-valuemax等数值属性定义为number，比DOM类型中的字符串更符合组件使用习惯。因为React等框架在多数情况下会直接接收数值并转换为字符串，而Vue模板中绑定数值也更自然。统一的属性映射还能减少重复定义，后续如果规范出现调整，也可以集中修改这一个接口。
通过映射类型表达角色与属性的合法组合
基础角色和属性类型只解决了拼写问题，还不能阻止role="checkbox"搭配aria-level这种语义不合理的组合。要表达角色与属性之间的约束关系，核心思路是维护一个“角色到属性集合”的映射。每个角色对应一个明确允许的属性子集，再借助条件类型和索引访问，让泛型角色自动推导出可用的ARIA属性。
例如checkbox角色通常只需要aria-checked和aria-disabled，combobox角色则需要aria-expanded、aria-controls以及可能的aria-haspopup。把这些规则写入接口后，就能通过R extends keyof RolePropsMap的约束，让不存在的组合直接报错。
interface RolePropsMap {
button: Pick<AriaAttributeMap, 'aria-disabled' | 'aria-expanded' | 'aria-haspopup' | 'aria-label' | 'aria-labelledby' | 'aria-describedby'>;
checkbox: Pick<AriaAttributeMap, 'aria-checked' | 'aria-disabled' | 'aria-label' | 'aria-labelledby' | 'aria-describedby'>;
switch: Pick<AriaAttributeMap, 'aria-checked' | 'aria-disabled' | 'aria-label' | 'aria-labelledby'>;
combobox: Pick<AriaAttributeMap, 'aria-expanded' | 'aria-controls' | 'aria-haspopup' | 'aria-disabled' | 'aria-label' | 'aria-labelledby' | 'aria-describedby'>;
listbox: Pick<AriaAttributeMap, 'aria-multiselectable' | 'aria-activedescendant' | 'aria-label' | 'aria-labelledby' | 'aria-describedby'>;
option: Pick<AriaAttributeMap, 'aria-selected' | 'aria-disabled' | 'aria-label' | 'aria-labelledby'>;
radiogroup: Pick<AriaAttributeMap, 'aria-label' | 'aria-labelledby' | 'aria-describedby' | 'aria-orientation'>;
radio: Pick<AriaAttributeMap, 'aria-checked' | 'aria-disabled' | 'aria-label' | 'aria-labelledby'>;
textbox: Pick<AriaAttributeMap, 'aria-disabled' | 'aria-readonly' | 'aria-label' | 'aria-labelledby' | 'aria-describedby' | 'aria-valuetext'>;
slider: Pick<AriaAttributeMap, 'aria-valuemin' | 'aria-valuemax' | 'aria-valuenow' | 'aria-valuetext' | 'aria-disabled' | 'aria-label' | 'aria-labelledby'>;
tablist: Pick<AriaAttributeMap, 'aria-label' | 'aria-labelledby' | 'aria-orientation'>;
tab: Pick<AriaAttributeMap, 'aria-selected' | 'aria-disabled' | 'aria-controls' | 'aria-label' | 'aria-labelledby'>;
tabpanel: Pick<AriaAttributeMap, 'aria-label' | 'aria-labelledby' | 'aria-describedby'>;
tree: Pick<AriaAttributeMap, 'aria-label' | 'aria-labelledby' | 'aria-multiselectable'>;
treeitem: Pick<AriaAttributeMap, 'aria-expanded' | 'aria-selected' | 'aria-disabled' | 'aria-level' | 'aria-label' | 'aria-labelledby'>;
menu: Pick<AriaAttributeMap, 'aria-label' | 'aria-labelledby' | 'aria-describedby'>;
menuitem: Pick<AriaAttributeMap, 'aria-disabled' | 'aria-haspopup' | 'aria-label' | 'aria-labelledby'>;
dialog: Pick<AriaAttributeMap, 'aria-label' | 'aria-labelledby' | 'aria-describedby' | 'aria-modal'>;
alert: Pick<AriaAttributeMap, 'aria-live' | 'aria-label' | 'aria-labelledby' | 'aria-describedby'>;
progressbar: Pick<AriaAttributeMap, 'aria-valuemin' | 'aria-valuemax' | 'aria-valuenow' | 'aria-valuetext' | 'aria-label' | 'aria-labelledby'>;
}
type AriaPropsForRole<R extends AriaRole> = R extends keyof RolePropsMap ? RolePropsMap[R] : {};
这段代码中Pick负责从完整属性映射里提取某个角色允许使用的属性子集。如果把AriaPropsForRole<'checkbox'>展开，就会得到只包含aria-checked、aria-disabled等字段的类型。这样设计的好处是每个角色的合法属性一目了然，新增角色时也有明确的位置维护约束关系。对于某些角色需要的属性尚未在AriaAttributeMap中定义的情况，TypeScript会直接提示Pick的目标键不存在，从而倒逼开发者先补充基础属性类型。
封装通用的无障碍组件属性类型
有了角色和属性映射之后，还需要把它们组合成组件可以直接使用的Props类型。不同框架的组件属性结构不一样，但ARIA相关的部分可以抽象成独立的类型，再与框架自带属性进行交叉合并。这样可以避免每个组件都重复声明role、aria-*，也能在编译期防止错误角色和非法属性传递到最终DOM节点。
一个常见的封装方式是定义泛型类型AriaComponentProps，它接收角色作为泛型参数，然后组合角色本身、该角色允许的ARIA属性，以及组件的其他内容属性。为了让类型推断更友好，默认角色可以保留为AriaRole，而在实际组件中让调用方显式传入具体角色。
type AriaComponentProps<R extends AriaRole = AriaRole> = {
role: R;
} & AriaPropsForRole<R> & {
children?: unknown;
className?: string;
};
type CheckboxProps = AriaComponentProps<'checkbox'>;
type ComboboxProps = AriaComponentProps<'combobox'>;
const checkboxProps: CheckboxProps = {
role: 'checkbox',
'aria-checked': 'true',
children: '接收通知'
};
const invalidCheckboxProps: CheckboxProps = {
role: 'checkbox',
'aria-expanded': 'true'
};
在上面的示例中，invalidCheckboxProps会触发类型错误，因为checkbox角色并没有被映射到aria-expanded属性。这种约束在大型组件库中尤其有价值：当很多开发者同时维护不同组件时，类型系统可以充当规范文档之外的自动检查器，防止某次重构把不合适的ARIA属性加进组件。
对于需要支持多个角色的复合组件，可以使用联合类型来描述。例如某个菜单按钮组件既可能渲染为button，也可能渲染为menuitem，此时可以把角色参数扩展为'button' | 'menuitem'。但要注意，联合角色会带来属性收窄的问题。如果两个角色允许的属性不同，直接使用AriaPropsForRole<'button' | 'menuitem'>会得到属性交叉的联合结果，在某些TypeScript版本下可能不如预期。更稳妥的做法是让组件根据角色分支单独处理属性，或者在泛型中保持单一角色，再由高层组件做分发。
处理HTML元素固有语义与自定义角色
无障碍从来不只是ARIA的问题。很多HTML元素本身就带有隐式角色，例如<button>对应button角色，<input type="checkbox">对应checkbox角色。类型封装不能抛开宿主元素孤立存在。如果你把一个AriaComponentProps<'button'>合并到div上，虽然类型层面都能通过，但实际渲染出来的<div role="button">仍然需要额外的键盘交互才能达到等价体验。因此，组件封装最好在语义正确的原生元素上使用ARIA属性，而不是把ARIA当作修复语义缺陷的万能工具。
与框架内置属性合并时，可能会遇到role类型冲突。DOM类型通常把role定义为宽泛的字符串，而自定义类型希望收窄成AriaRole。如果直接做交叉类型，可能得到never或者字符串宽类型。解决方式之一是使用Omit移除框架属性中的role，再合并自定义角色类型。例如在React中，可以这样构造：
import type { HTMLAttributes } from 'react';
type BaseDivProps = Omit<HTMLAttributes<HTMLDivElement>, 'role' | 'aria-checked' | 'aria-expanded'>;
type SafeButtonDivProps = BaseDivProps & AriaComponentProps<'button'>;
这样既保留了div原有的className、style、事件等属性，又把role和关键ARIA属性替换成受约束的类型。对于aria-checked、aria-expanded等容易与DOM类型冲突的字段，也应一并从基础属性中移除，避免因为值类型不一致产生联合后收窄失败的问题。
自定义角色同样需要纳入映射。项目中如果使用了超出WAI-ARIA标准的内部角色，规范上并不推荐，因为辅助技术无法识别未知角色。但当必须对接特定的无障碍平台或测试环境时，可以在AriaRole联合类型中扩展现有字面量，并在RolePropsMap中补充对应属性。关键是要保持两个映射同步。可以利用一个辅助类型type DefinedRole = keyof RolePropsMap来检查AriaRole是否覆盖了所有已定义映射，若出现遗漏，就能通过类型错误提前发现。
用类型守卫和泛型约束提升运行期可靠性
TypeScript的类型检查只存在于编译期，运行阶段从外部传入的role字符串仍然可能是非法值。如果组件需要处理来自接口数据、用户输入或动态配置的ARIA信息，就需要在运行时做一次校验。类型守卫可以把运行期校验和编译期类型连接起来，让未知字符串安全收窄为AriaRole。
const knownAriaRoles: readonly AriaRole[] = [
'button',
'checkbox',
'combobox',
'listbox',
'option',
'radiogroup',
'radio',
'textbox',
'slider',
'tablist',
'tab',
'tabpanel',
'tree',
'treeitem',
'menu',
'menuitem',
'dialog',
'alert',
'switch',
'progressbar'
] as const;
function isAriaRole(value: unknown): value is AriaRole {
return typeof value === 'string' && knownAriaRoles.includes(value as AriaRole);
}
在获取外部角色后，先通过isAriaRole守卫判断，再决定是渲染组件还是降级处理。这样既保留了类型收窄的便利，也避免把脏数据直接交给无障碍组件。对于属性的运行期校验，可以进一步根据角色到属性的映射生成校验规则，但这部分逻辑通常会复杂一些，建议先对核心交互角色做重点覆盖。
综合来看，用TypeScript封装ARIA角色与属性的目标不是取代无障碍测试，而是让最容易出错的部分在开发阶段就暴露出来。类型系统可以约束拼写、约束角色与属性组合、约束跨框架组件属性传递，但无法验证最终读屏表现。真正可靠的无障碍体验仍然需要与人工测试、自动化可访问性检查以及真实辅助技术验证相结合。一个好的封装应该让开发者更容易写出符合规范的结构，而不是增加复杂类型体操的负担。
TypeScriptARIAWeb无障碍修改时间：2026-08-30 11:17:57