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 文档)。

Figma 状态映射到 React 语义与可访问行为

实现有名称和错误反馈的输入框

以下完整组件适用于 React 18/19 的 Vite React + TypeScript 项目。将它保存为 src/App.tsx。表单使用原生 type="email"、required 与 checkValidity() 校验;noValidate 只关闭浏览器提交时的默认提示气泡,由页面统一显示错误说明。

tsx
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 让键盘导航时保留清楚的焦点环。

css
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 并打开显示的本地地址;端口会因环境不同而变化。预期页面标题是“邮箱通知设置”,下方依次有标签、输入框、帮助文本和保存按钮。

  1. 从页面外按 Tab 进入输入框,再按 Tab 到按钮,用 Shift+Tab 返回;两个控件都应有明显焦点环,且不需要鼠标。
  2. 输入框留空后激活“保存设置”:焦点回到邮箱框,错误文本出现,元素具有 aria-invalid="true",其 aria-describedby 同时指向帮助与错误文本。
  3. 输入 abc 后失焦,仍显示格式错误;改为 name@example.com,错误与红框消失,再提交出现成功状态文字。
  4. 用 Chrome 的开发者工具检查输入元素的无障碍名称,或用 NVDA + Chrome、VoiceOver + Safari 逐项确认可读到“邮箱地址”、帮助说明及错误原因;读屏措辞和播报次序可能因组合不同而变化。

如果按钮在设计稿中呈禁用态,优先使用原生 disabled,但要先确认用户仍能找到无法提交的原因;不要只降低透明度。aria-disabled="true" 不会自动阻止点击或键盘触发,必须额外控制事件。完成这些检查后,组件才同时具备视觉状态和真实的操作语义。

按自己的节奏,确认真正理解。

目录与阅读设置

阅读设置

17

记录一个想法

补齐交互组件的无障碍语义

0 / 10000 · 笔记保存到账号。未提交的修改会在关闭、离开或刷新后丢失。

登录哪都通