在无障碍开发领域，颜色对比度是最容易被忽视又最容易被自动化检测的问题。奥地利依据欧盟Web Accessibility Directive（网页无障碍指令）发布的网络无障碍法令，要求公共机构网站必须符合EN 301 549标准，其中对普通文本要求至少4.5:1的对比度，大号文本至少3:1。当我们在IWAC这样一个内部工具库中封装这些规则时，纯运行时校验往往不够，等到页面渲染出来才发现对比度不达标，修复成本已经变高。TypeScript的依赖类型机制给了我们另一条路：把颜色组合的合法性提前到编译期。
一、为什么用类型系统建模颜色依赖关系
传统的做法是提供一个函数，接收前景色和背景色，返回对比度是否达标的布尔值。这种方案的缺陷在于错误暴露得太晚：调用方完全可以在代码里写一个对比度只有2.1:1的组合，编译器毫无怨言，直到CI跑无障碍检查或者用户投诉才暴露问题。而依赖类型的思路是让颜色值本身成为类型的一部分，让非法组合根本无法通过类型检查。
具体来说，我们可以把每一种品牌色声明为一个字面量类型，再通过条件类型计算两种颜色的组合是否合法。TypeScript虽然在类型层面不能做真正的浮点运算，但对比度计算可以拆解为整数化的亮度差值，只要在类型系统中维护一张预计算的对比度表，就能实现编译期查询。
这种设计的收益是显而易见的：新人接手项目时，不需要背下奥地利法令的细节，只要写了不合规的颜色组合，编辑器里立刻出现红色波浪线，错误信息还能直接引用对应的规范条款。团队知识从文档沉淀进了类型定义，这是运行时校验做不到的。
二、设计颜色字面量类型与对比度表
第一步是定义品牌色板。假设IWAC中维护了一套奥地利政府站点常用色板，我们可以这样声明：
// 品牌色板的字面量类型
export type BrandColor =
| '#0A3D7A' // 深蓝，主背景色
| '#FFFFFF' // 白色
| '#F5F5F5' // 浅灰，次级背景色
| '#767676' // 中灰，禁止与白色组合用于正文
| '#E8253C'; // 奥地利红，仅限大号文本
// 前景与背景的有序对，作为组合类型
export type ColorPair = {
fg: BrandColor;
bg: BrandColor;
};
接下来是核心部分，用一张类型层面的映射表记录每对颜色的预计算对比度。手工维护这张表并不现实，更好的方式是写一个构建脚本，用运行时的对比度算法生成TypeScript声明文件，色板变更时重新生成即可。生成的类型大致如下：
// 由脚本自动生成，请勿手工修改
interface ContrastTable {
'#0A3D7A-#FFFFFF': 10.3;
'#0A3D7A-#F5F5F5': 9.5;
'#FFFFFF-#0A3D7A': 10.3;
'#767676-#FFFFFF': 4.5;
'#E8253C-#FFFFFF': 4.6;
// 其余组合省略
}
type Contrast<F extends BrandColor, B extends BrandColor> =
ContrastTable[`${F}-${B}`];
注意模板字面量类型在这里的作用：它把两个独立的字面量类型拼成一个键，去查表得到对比度数值。这是整个封装的关键技巧，也是依赖类型的典型应用。
三、用条件类型约束文本尺寸与对比度阈值
奥地利网络无障碍法令沿袭WCAG 2.1的分级规则，AA级要求普通文本4.5:1、大号文本3:1，AAA级则提高到7:1和4.5:1。大号文本的定义是至少18pt或14pt加粗。这些规则可以直接编码为条件类型：
type TextSize = 'normal' | 'large';
type RequiredRatio<S extends TextSize, L extends 'AA' | 'AAA'> =
L extends 'AAA'
? S extends 'large' ? 4.5 : 7
: S extends 'large' ? 3 : 4.5;
type IsAccessible<
F extends BrandColor,
B extends BrandColor,
S extends TextSize = 'normal',
L extends 'AA' | 'AAA' = 'AA'
> = Contrast<F, B> extends infer R
? R extends RequiredRatio<S, L>
? true
: R extends number
? false
: never
: never;
有了这个判断类型，就可以构造一个对外暴露的安全工厂函数，只有在组合合法时才返回可用类型，否则通过never参数报错：
function createAccessiblePair<
F extends BrandColor,
B extends BrandColor,
S extends TextSize = 'normal'
>(fg: F, bg: B, size: S):
IsAccessible<F, B, S> extends true
? ColorPair
: { __error: '对比度不足，请参考EN 301 549第9.1.4.3条' }
{
return { fg, bg } as any;
}
// 编译通过：深蓝配白，对比度10.3
const ok = createAccessiblePair('#0A3D7A', '#FFFFFF', 'normal');
// 编译报错：中灰配浅灰不满足普通文本要求
const bad = createAccessiblePair('#767676', '#F5F5F5', 'normal');
错误信息刻意引用了EN 301 549的条款编号，也就是WCAG 2.1的成功标准1.4.3。这样开发者在看到报错的瞬间就能定位到规范原文，不必再去检索奥地利法令的具体条目。
四、与IWAC校验流程集成及注意事项
类型层面的封装不能完全替代运行时检查，因为总有颜色来自接口返回、CMS配置或者用户自定义主题。推荐的架构是双层防线：编译期用上述依赖类型拦截静态代码中的硬编码颜色，运行期保留原有的对比度计算函数处理动态值。两者共用同一份由脚本生成的对比度表，避免规则漂移。
另一个实践要点是透明度的处理。当颜色带有alpha通道时，实际渲染颜色取决于叠加的背景，这在类型层面几乎无法精确建模。务实的做法是规定类型化色板只包含不透明颜色，含透明度的颜色一律走运行时校验路径，并在文档中说明原因。
最后，色板的演进需要流程保障。设计系统新增颜色时，应由CI任务重新生成ContrastTable声明文件并提交评审，评审依据就是奥地利网络无障碍法令的符合性声明模板。这样类型表、代码和合规文档三者始终同步，审计时可以直接把类型定义作为符合性证据的一部分。整体来看，这套封装前期投入不大，却能将持续性的合规成本压到最低，值得任何面向奥地利或欧盟公共站点的团队参考。
TypeScript网络无障碍颜色对比度修改时间：2026-09-06 22:40:43