UI 视觉设计 / 系统课时
补齐交互组件的无障碍语义
补齐交互组件的无障碍语义
设计稿中的聚焦描边、错误红框和禁用灰态只描述外观。实现 React 组件时,还要让浏览器知道控件的名称、类型、状态和错误原因,并保证键盘能操作。本课以一个邮箱设置表单为例,把视觉状态转成可验证的真实行为。
学习目标
- 用原生 HTML 标签建立可访问名称、类型和交互行为。
- 用
aria-invalid、aria-describedby关联输入错误与说明。 - 实现可见键盘焦点,并按操作步骤核对读屏和提交反馈。
从视觉状态确定原生语义
先选对 HTML 元素,再用 ARIA 补充原生语义没有覆盖的信息。Figma 的“看起来像按钮”不等于浏览器中的按钮;用 div 模拟按钮,还得自行处理焦点、Enter、空格键及禁用状态。
| 设计状态或用途 | React 中的实现 | 必须验证的行为 |
|---|---|---|
| 执行操作 | <button type="button"> 或提交时用 type="submit" |
Tab 可聚焦,Enter/空格可激活 |
| 页面跳转 | 带 href 的 <a> |
Enter 打开目标,不借 onClick 模拟链接 |
| 输入字段 | <label htmlFor> 关联 <input id> |
点击标签能聚焦输入,读屏能读出名称 |
| 必填与无效 | required,校验后设置 aria-invalid |
空值或格式错误有文字说明 |
| 不可操作 | 原生 disabled |
不可激活且退出正常 Tab 顺序 |
占位符 placeholder 不能替代可见标签;单靠边框颜色也不能解释错误原因。对重复渲染的组件,使用 useId() 生成关联 ID,避免同页多个输入框互相引用(参见 React useId 文档)。

实现有名称和错误反馈的输入框
以下完整组件适用于 React 18/19 的 Vite React + TypeScript 项目。将它保存为 src/App.tsx。表单使用原生 type="email"、required 与 checkValidity() 校验;noValidate 只关闭浏览器提交时的默认提示气泡,由页面统一显示错误说明。
import { useId, useRef, useState } from 'react';
import type { FormEvent } from 'react';
import './App.css';
export default function App() {
const id = useId();
const emailId = `${id}-email`;
const hintId = `${id}-hint`;
const errorId = `${id}-error`;
const inputRef = useRef<HTMLInputElement>(null);
const [email, setEmail] = useState('');
const [touched, setTouched] = useState(false);
const [submitted, setSubmitted] = useState(false);
const [invalid, setInvalid] = useState(false);
const [saved, setSaved] = useState(false);
// 初次渲染不报错,失焦或提交后才显示错误。
const showError = (touched || submitted) && invalid;
function handleSubmit(event: FormEvent<HTMLFormElement>) {
event.preventDefault();
setSubmitted(true);
const field = inputRef.current;
if (!field) return;
const valid = field.checkValidity();
setInvalid(!valid);
if (!valid) {
setSaved(false);
// 校验失败后回到需要修正的字段。
field.focus();
return;
}
setSaved(true);
}
return (
<main>
<h1>邮箱通知设置</h1>
<form noValidate onSubmit={handleSubmit}>
<label htmlFor={emailId}>邮箱地址</label>
<input
ref={inputRef}
id={emailId}
name="email"
type="email"
autoComplete="email"
required
value={email}
aria-invalid={showError ? 'true' : undefined}
aria-describedby={`${hintId}${showError ? ` ${errorId}` : ''}`}
onChange={(event) => {
setEmail(event.currentTarget.value);
setInvalid(!event.currentTarget.validity.valid);
setSaved(false);
}}
onBlur={(event) => {
setTouched(true);
setInvalid(!event.currentTarget.validity.valid);
}}
/>
<p id={hintId}>请输入有效的邮箱地址。</p>
{showError && (
<p id={errorId} role="alert">
邮箱不能为空,且格式应为 name@example.com。
</p>
)}
<button type="submit">保存设置</button>
</form>
{saved && (
<p role="status">校验通过;本示例未向服务器保存数据。</p>
)}
</main>
);
}预期结果:组件显示邮箱标签、输入框、说明文字和保存按钮;留空或输入错误格式后触发校验,会显示与输入框关联的错误文本。
aria-describedby 总是关联提示,只有错误出现时才附加错误段落的 ID;此时 aria-invalid 同时变成 true。role="alert" 提示新出现的错误,role="status" 用于较温和的成功反馈。实际项目提交成功前还应等待服务端响应,不能把本地校验通过当成数据已保存。
让焦点可见且错误不只靠颜色
在 src/App.css 写入以下样式。outline 与布局边框分开,不会因为错误状态改变边框而丢失焦点位置;使用 :focus-visible 让键盘导航时保留清楚的焦点环。
main {
max-width: 28rem;
margin: 3rem auto;
font: 16px/1.5 system-ui, sans-serif;
}
form { display: grid; gap: 0.65rem; }
input {
padding: 0.6rem;
border: 1px solid #64748b;
border-radius: 0.35rem;
font: inherit;
}
/* 错误描边不代替键盘焦点。 */
input[aria-invalid="true"] { border: 2px solid #b91c1c; }
:where(input, button):focus-visible {
outline: 3px solid #1d4ed8;
outline-offset: 3px;
}
button {
justify-self: start;
padding: 0.6rem 1rem;
border: 0;
border-radius: 0.35rem;
background: #1d4ed8;
color: white;
font: inherit;
}
/* 错误文字与红色描边一起传达状态。 */
[role="alert"] { color: #991b1b; }预期结果:使用键盘 Tab 导航时,输入框和按钮周围显示蓝色焦点环;输入校验失败后出现红色边框及可见的错误文本。
不要为了贴近设计稿写 outline: none 却不提供替代焦点指示。设计系统至少应分别检查默认、聚焦、错误、错误且聚焦四种状态;红色边框只是辅助线索,错误文本必须一直可见(参见 WCAG 焦点可见要求)。
按键盘与读屏实际验收
在现有 Vite 工程中运行 npm run dev 并打开显示的本地地址;端口会因环境不同而变化。预期页面标题是“邮箱通知设置”,下方依次有标签、输入框、帮助文本和保存按钮。
- 从页面外按
Tab进入输入框,再按Tab到按钮,用Shift+Tab返回;两个控件都应有明显焦点环,且不需要鼠标。 - 输入框留空后激活“保存设置”:焦点回到邮箱框,错误文本出现,元素具有
aria-invalid="true",其aria-describedby同时指向帮助与错误文本。 - 输入
abc后失焦,仍显示格式错误;改为name@example.com,错误与红框消失,再提交出现成功状态文字。 - 用 Chrome 的开发者工具检查输入元素的无障碍名称,或用 NVDA + Chrome、VoiceOver + Safari 逐项确认可读到“邮箱地址”、帮助说明及错误原因;读屏措辞和播报次序可能因组合不同而变化。
如果按钮在设计稿中呈禁用态,优先使用原生 disabled,但要先确认用户仍能找到无法提交的原因;不要只降低透明度。aria-disabled="true" 不会自动阻止点击或键盘触发,必须额外控制事件。完成这些检查后,组件才同时具备视觉状态和真实的操作语义。