在面向阿尔巴尼亚地区用户的Web应用中，表单错误提示的无障碍质量直接影响屏幕阅读器用户能否顺利完成操作。阿尔巴尼亚的网络无障碍指南在参考WCAG 2.1的基础上，对错误识别、错误描述和错误纠正提出了明确要求：错误发生时必须以文本形式告知用户，且错误信息要与对应的表单控件建立程序化关联。如果错误类型只用松散的字符串表示，很容易出现拼写不一致、ARIA属性漏绑、翻译文案缺失等问题。本文将以IWAC项目的实践为例，讲解如何用TypeScript封装一套类型安全的表单错误定义体系。
为什么松散的错误定义无法满足无障碍要求
先看一段典型的松散写法。错误信息直接用字符串拼接，字段名靠手工传入：
function showError(field: string, message: string) {
const el = document.getElementById(field);
el?.setAttribute('aria-invalid', 'true');
el?.insertAdjacentHTML('afterend', `<span>${message}</span>`);
}
showError('emal', 'Emaili nuk është valid'); // 字段名拼错了，运行时静默失败这段代码有三类隐患。第一，field参数没有约束，把email拼成emal时编译器毫无察觉，错误提示渲染失败，屏幕阅读器用户完全不知道发生了什么。第二，错误消息是自由文本，阿尔巴尼亚语和英语混杂后无法统一管理翻译。第三，插入的span缺少aria-live或与控件的aria-describedby关联，不满足指南中错误必须可被程序化识别的要求。
阿尔巴尼亚无障碍指南特别强调两点：错误信息必须以role="alert"或实时区域的方式主动播报；每个出错控件必须通过aria-describedby指向错误文本的id。这两点都需要错误数据结构本身携带足够的信息，靠运行时字符串拼接是靠不住的。
设计错误码枚举与可辨识联合类型
解决思路是让错误在类型层面就是一等公民。首先定义错误码枚举，覆盖常见校验场景：
export enum FormErrorCode {
Required = 'REQUIRED',
InvalidEmail = 'INVALID_EMAIL',
TooShort = 'TOO_SHORT',
TooLong = 'TOO_LONG',
PatternMismatch = 'PATTERN_MISMATCH',
ValueMismatch = 'VALUE_MISMATCH',
}
// 可辨识联合：每种错误码携带各自的上下文数据
export type FormError =
| { code: FormErrorCode.Required; field: FieldName }
| { code: FormErrorCode.InvalidEmail; field: FieldName; value: string }
| { code: FormErrorCode.TooShort; field: FieldName; length: number; min: number }
| { code: FormErrorCode.ValueMismatch; field: FieldName; confirmField: FieldName };可辨识联合的好处在于，处理错误时编译器强制你区分每种情况，漏掉一个分支立刻报错。比如渲染TooShort错误时必须有min值才能生成可操作的提示语（告知用户至少输入多少字符），这正是WCAG 3.3.3错误建议条款的要求。如果错误类型里没有min字段，写渲染逻辑时就会被迫补齐数据结构，而不是在文案里硬编码数字。
FieldName同样不能是裸字符串，应该从表单字段配置中派生：
const FORM_FIELDS = ['email', 'password', 'confirmPassword', 'phone'] as const; export type FieldName = typeof FORM_FIELDS[number];
这样showError('emal', ...)会在编译期直接报错。新增字段时只要改FORM_FIELDS，所有依赖FieldName的类型自动更新，这是类型驱动开发带来的维护收益。
封装渲染器并联动ARIA属性
有了类型定义，接下来封装一个与阿尔巴尼亚语文案表联动的错误渲染器。文案表以错误码为键，通过映射类型保证每个错误码都有对应翻译：
type MessageParams<E extends FormError> =
E extends { min: number } ? { min: number } : Record<string, never>;
type MessageTable = {
[K in FormErrorCode]: (params: any) => string;
};
const sqMessages: MessageTable = {
[FormErrorCode.Required]: () => 'Kjo fushë është e detyrueshme',
[FormErrorCode.InvalidEmail]: () => 'Emaili nuk është i vlefshëm',
[FormErrorCode.TooShort]: (p) => `Duhet të paktën ${p.min} karaktere`,
// ...
};
export function renderError(error: FormError): void {
const input = document.getElementById(error.field) as HTMLInputElement;
const errorId = `${error.field}-error`;
const message = sqMessages[error.code](error);
// 写入错误文本并建立双向关联
document.getElementById(errorId)!.textContent = message;
input.setAttribute('aria-invalid', 'true');
input.setAttribute('aria-describedby', errorId);
// 实时区域播报，满足指南的主动告知要求
document.getElementById('form-alert')!
.setAttribute('role', 'alert');
document.getElementById('form-alert')!.textContent = message;
}注意错误容器需要预先存在于DOM中，而不是动态插入，否则role="alert"的区域可能不会被屏幕阅读器播报。这个细节在很多项目中踩过坑：动态创建的alert节点在部分读屏软件（如NVDA、JAWS）中首次插入时不触发播报，预置空节点再填充文本是最稳妥的做法。
渲染器内部还可以在设置aria-invalid前先清除旧错误，避免多个错误叠加导致aria-describedby指向多个id时读屏顺序混乱。类型系统保证了传给renderError的错误一定带有完整上下文，渲染逻辑不需要任何防御性判空，代码更简洁也更可靠。
泛型校验器与扩展性考虑
最后一步是让校验函数也走类型通道。用一个泛型工厂生成针对特定字段的校验器，返回值直接是FormError | null：
export function minLength<F extends FieldName>(field: F, min: number) {
return (value: string): FormError | null => {
if (value.length < min) {
return { code: FormErrorCode.TooShort, field, length: value.length, min };
}
return null;
};
}
const validators = [
minLength('password', 8),
(v: string) => v.includes('@')
? null
: { code: FormErrorCode.InvalidEmail, field: 'email' as FieldName, value: v },
];这种封装把校验、错误结构、文案、ARIA绑定四件事解耦：校验器只产出结构化错误，渲染器只消费结构化错误，文案表独立维护。当项目需要支持塞尔维亚语或马其顿语时，只需新增一个符合MessageTable类型的文案表，其他代码一行不改。类型定义在这里充当了无障碍规范的机器可读版本，凡是指南要求的要素（文本化错误、程序化关联、纠错建议），都会在类型层面留下痕迹，缺失时编译器替你把关。这正是强类型语言在无障碍工程化中的核心价值：让规范要求从文档约定变成编译期约束。
TypeScript无障碍表单错误处理修改时间：2026-08-31 05:22:34