Web 可访问性（a11y）：合规标准、技术实现与用户体验

<!-- ❌ 错误：纯 div，屏幕阅读器完全无法理解 -->
<div class="header">
  <div class="nav">
    <div class="item" onclick="goHome()">首页</div>
    <div class="item" onclick="goAbout()">关于</div>
  </div>
</div>

<!-- ✅ 正确：语义化标签自带可访问性 -->
<header>
  <nav aria-label="主导航">
    <ul>
      <li><a href="/">首页</a></li>
      <li><a href="/about">关于</a></li>
    </ul>
  </nav>
</header>

<main>
  <article>
    <h1>文章标题</h1>
    <p>文章内容...</p>
  </article>
</main>

<aside aria-label="相关推荐">
  <h2>推荐阅读</h2>
  <!-- ... -->
</aside>

<footer>
  <p>&copy; 2026 My Company</p>
</footer>

<!-- ✅ 正确的标题层级 —— 像书的目录 -->
<h1>网站标题</h1>
  <h2>章节一</h2>
    <h3>小节 A</h3>
    <h3>小节 B</h3>
  <h2>章节二</h2>
    <h3>小节 C</h3>
      <h4>细节 1</h4>

<!-- ❌ 错误：跳过层级、用样式代替语义 -->
<p class="h1-style">看起来像标题但不是</p>
<h1>一级标题</h1>
<h3>直接跳到三级</h3>

<!-- ❌ 过度使用 ARIA -->
<div role="button" tabindex="0" aria-pressed="false">提交</div>

<!-- ✅ 原生元素自带全部 ARIA 属性 -->
<button type="submit">提交</button>

<!-- ✅ 只有在原生元素无法表达时才用 ARIA -->
<div role="dialog" aria-modal="true" aria-labelledby="dialog-title">
  <h2 id="dialog-title">确认删除</h2>
  <p>确定要删除这条记录吗？此操作不可撤销。</p>
  <button>取消</button>
  <button>删除</button>
</div>

<!-- 状态变化自动播报 -->
<div id="status" aria-live="polite" aria-atomic="true"></div>

<script>
// 当表单提交后更新状态
function showStatus(message) {
  document.getElementById('status').textContent = message;
  // 屏幕阅读器会自动播报："保存成功"
}
showStatus('保存成功！');
</script>

<!-- aria-live 取值：
     off      — 不播报（默认）
     polite   — 礼貌：当前说完后播报
     assertive — 打断：立即播报（紧急错误用）
-->

<!-- ✅ 原生可交互元素自动可聚焦 -->
<a href="/">链接</a>
<button>按钮</button>
<input type="text">
<select>
<textarea>

<!-- ❌ 虚假按钮 —— 无法键盘聚焦和触发 -->
<div class="btn" onclick="submit()">提交</div>

<!-- ✅ 无 href 的链接也需要 focus -->
<a href="javascript:void(0)" role="button" tabindex="0"
   @keydown.enter="submit">更多</a>

<!-- ✅ 或用真正的按钮 -->
<button type="button" @click="submit">更多</button>

/* 确保焦点可见 */
:focus-visible {
  outline: 2px solid #3b82f6;
  outline-offset: 2px;
}

/* 不要隐藏焦点！ */
/* ❌ 错误 */
*:focus { outline: none; }

/* 不要用 tabindex > 0 强行改变顺序 —— 让 DOM 顺序反映视觉顺序 */

// 模态框必须困住焦点
function trapFocus(element: HTMLElement) {
  const focusable = element.querySelectorAll(
    'a[href], button, input, textarea, select, [tabindex]:not([tabindex="-1"])'
  );
  const first = focusable[0] as HTMLElement;
  const last = focusable[focusable.length - 1] as HTMLElement;

  element.addEventListener('keydown', (e) => {
    if (e.key !== 'Tab') return;

    if (e.shiftKey && document.activeElement === first) {
      e.preventDefault();
      last.focus();
    } else if (!e.shiftKey && document.activeElement === last) {
      e.preventDefault();
      first.focus();
    }
  });

  first.focus(); // 打开时聚焦第一个元素
}

// 关闭时恢复焦点
let previousFocus: HTMLElement | null = null;

function openModal() {
  previousFocus = document.activeElement as HTMLElement;
  modal.showModal();
  trapFocus(modal);
}

function closeModal() {
  modal.close();
  previousFocus?.focus(); // 回到触发元素
}

/* ✅ 对比度足够 */
.text-primary {
  color: #1e3a5f; /* 深蓝色 */
  background: #ffffff; /* 对比度 12.5:1 ✅ */
}

/* ❌ 对比度不足 */
.text-muted {
  color: #cccccc; /* 浅灰 */
  background: #ffffff; /* 对比度 1.6:1 ❌ */
}

<!-- ❌ 色觉障碍用户无法区分红绿 -->
<span class="status-red">错误</span>
<span class="status-green">成功</span>

<!-- ✅ 颜色 + 图标 + 文字 -->
<span class="text-red-600">
  <svg aria-hidden="true"><!-- 错误图标 --></svg>
  错误：请检查输入
</span>
<span class="text-green-600">
  <svg aria-hidden="true"><!-- 成功图标 --></svg>
  成功：保存完成
</span>

<!-- ✅ 表单错误同时用多种方式 -->
<input aria-invalid="true" aria-describedby="error-name">
<span id="error-name" class="text-red-600">姓名不能为空</span>

/* 尊重用户的减少动画偏好 */
@media (prefers-reduced-motion: reduce) {
  *,
  *::before,
  *::after {
    animation-duration: 0.01ms !important;
    animation-iteration-count: 1 !important;
    transition-duration: 0.01ms !important;
  }
}

/* 或在 Vue/React 中动态判断 */

<!-- ✅ 显式关联 -->
<label for="email">邮箱地址</label>
<input type="email" id="email" name="email" required
       aria-required="true"
       aria-describedby="email-hint email-error">
<p id="email-hint">我们将向您发送验证邮件</p>

<!-- ✅ 隐式关联 -->
<label>
  用户名
  <input type="text" name="username">
</label>

<!-- ❌ 无关联：屏幕阅读器无法知道 input 的用途 -->
<span>邮箱</span>
<input type="email">

<form>
  <label for="password">密码</label>
  <input
    type="password"
    id="password"
    aria-invalid="true"
    aria-describedby="password-error"
  >
  <span id="password-error" role="alert" class="error">
    密码至少需要 8 位字符
  </span>
</form>

<script setup lang="ts">
import { ref, watch } from 'vue';

const isOpen = ref(false);
const modalRef = ref<HTMLElement>();

// 打开时聚焦模态框，关闭时恢复
watch(isOpen, (open) => {
  if (open) {
    setTimeout(() => modalRef.value?.focus(), 0);
  }
});
</script>

<template>
  <button @click="isOpen = true" aria-haspopup="dialog">
    打开设置
  </button>

  <div
    v-if="isOpen"
    ref="modalRef"
    role="dialog"
    aria-modal="true"
    aria-labelledby="modal-title"
    tabindex="-1"
    @keydown.esc="isOpen = false"
  >
    <h2 id="modal-title">设置</h2>
    <!-- 内容 -->
    <button @click="isOpen = false">关闭</button>
  </div>
</template>

import { useRef, useEffect } from 'react';

function Modal({ isOpen, onClose, title, children }) {
  const modalRef = useRef<HTMLDivElement>(null);
  const previousFocus = useRef<HTMLElement | null>(null);

  useEffect(() => {
    if (isOpen) {
      previousFocus.current = document.activeElement as HTMLElement;
      modalRef.current?.focus();

      // 焦点陷阱
      const handleTab = (e: KeyboardEvent) => {
        if (e.key !== 'Tab') return;
        const focusable = modalRef.current?.querySelectorAll(
          'a, button, input, textarea, select, [tabindex]:not([tabindex="-1"])'
        );
        if (!focusable?.length) return;
        const first = focusable[0] as HTMLElement;
        const last = focusable[focusable.length - 1] as HTMLElement;

        if (e.shiftKey && document.activeElement === first) {
          e.preventDefault();
          last.focus();
        } else if (!e.shiftKey && document.activeElement === last) {
          e.preventDefault();
          first.focus();
        }
      };

      document.addEventListener('keydown', handleTab);
      return () => {
        document.removeEventListener('keydown', handleTab);
        previousFocus.current?.focus();
      };
    }
  }, [isOpen]);

  if (!isOpen) return null;

  return (
    <div
      ref={modalRef}
      role="dialog"
      aria-modal="true"
      aria-labelledby="modal-title"
      tabIndex={-1}
      onKeyDown={(e) => e.key === 'Escape' && onClose()}
    >
      <h2 id="modal-title">{title}</h2>
      {children}
    </div>
  );
}

# axe-core（最权威的 a11y 测试引擎）
npm install -D @axe-core/cli

# CLI 扫描
npx axe https://example.com --tags wcag2aa

# 集成 Playwright
npm install -D @axe-core/playwright

// e2e/a11y.spec.ts
import { test, expect } from '@playwright/test';
import AxeBuilder from '@axe-core/playwright';

test('homepage should not have accessibility violations', async ({ page }) => {
  await page.goto('/');

  const accessibilityScanResults = await new AxeBuilder({ page })
    .withTags(['wcag2a', 'wcag2aa', 'wcag21aa'])
    .analyze();

  expect(accessibilityScanResults.violations).toEqual([]);
});

键盘测试清单：
□ Tab 键可以遍历所有可交互元素
□ Shift+Tab 反向遍历
□ Enter/Space 可以激活按钮和链接
□ Esc 可以关闭模态框/下拉菜单
□ 焦点顺序符合视觉顺序
□ 焦点始终可见

屏幕阅读器测试：
□ 页面有标题（<title>）
□ 图片有替代文本
□ 表单有标签关联
□ 错误信息被播报
□ 数据表格有表头