可访问性与国际化：WCAG 2.2、ARIA 与 i18n 工程实践

<!-- 反模式：用 div 模拟按钮，需要手动补键盘行为 -->
<div class="btn" role="button" tabindex="0" onclick="submit()">提交</div>

<!-- 正确：直接用 button 元素 -->
<button type="button" onclick="submit()">提交</button>

<div class="select" role="combobox" aria-expanded="false" aria-haspopup="listbox">
  <button id="select-trigger" aria-controls="select-listbox" aria-labelledby="select-label">
    当前：全部
  </button>
  <ul id="select-listbox" role="listbox" aria-labelledby="select-label">
    <li role="option" aria-selected="true">全部</li>
    <li role="option" aria-selected="false">电子</li>
    <li role="option" aria-selected="false">图书</li>
  </ul>
</div>

/* 键盘焦点时才显示清晰轮廓 */
:focus-visible {
  outline: 2px solid #2563eb;
  outline-offset: 2px;
}

/* 下拉触发器的键盘交互 */
.dropdown-trigger:focus-visible {
  box-shadow: 0 0 0 2px var(--color-focus-ring);
}

import { useEffect, useRef } from 'react';

function Dialog({ onClose, children }) {
  const dialogRef = useRef(null);

  useEffect(() => {
    const previousFocus = document.activeElement;
    dialogRef.current.focus(); // 焦点移入弹窗

    const handleKey = (e) => {
      if (e.key === 'Escape') onClose(); // Esc 关闭
    };
    document.addEventListener('keydown', handleKey);

    return () => {
      document.removeEventListener('keydown', handleKey);
      previousFocus.focus(); // 恢复焦点
    };
  }, [onClose]);

  return (
    <div
      ref={dialogRef}
      role="dialog"
      aria-modal="true"
      aria-labelledby="dialog-title"
      tabIndex={-1}
    >
      <h2 id="dialog-title">确认操作</h2>
      {children}
    </div>
  );
}

<a class="skip-link" href="#main-content">跳到主要内容</a>
<nav aria-label="主导航">…</nav>
<main id="main-content">…</main>

<!-- 表单提交后的成功提示 -->
<div role="status" aria-live="polite">
  保存成功
</div>

<!-- 校验错误汇总 -->
<div role="alert" aria-live="assertive">
  有 2 个字段填写错误
</div>

<!-- 正确：原生 label 已提供名称 -->
<label for="email">邮箱</label>
<input id="email" type="email" autocomplete="email" />

<!-- 多余：label 已够用，不应再叠加 aria-label -->
<label for="email">邮箱</label>
<input id="email" type="email" aria-label="邮箱" />

// 用 real 工具校验对比度（概念示例，可接入设计 token）
// 对比度 = (L1 + 0.05) / (L2 + 0.05)，L 为相对亮度
function contrastRatio(fg: string, bg: string): number {
  // 简化示意：真实实现需计算 sRGB 相对亮度
  const [r1, g1, b1] = hexToRgb(fg);
  const [r2, g2, b2] = hexToRgb(bg);
  const l1 = relativeLuminance(r1, g1, b1);
  const l2 = relativeLuminance(r2, g2, b2);
  return (Math.max(l1, l2) + 0.05) / (Math.min(l1, l2) + 0.05);
}

// react-intl 的 Provider 与消息定义
import { FormattedMessage, useIntl } from 'react-intl';

const messages = {
  'app.hello': '你好，{name}！',
  'app.items': '{count, plural, one {# 个商品} other {# 个商品}}',
};

function Greeting() {
  const intl = useIntl();
  const text = intl.formatMessage({ id: 'app.hello' }, { name: 'Leeting' });
  return <p>{text}</p>;
}

// locales/zh-CN.json
{
  "page.checkout.submit": "提交订单",
  "page.checkout.confirm": "确认订单信息",
  "page.cart.empty": "购物车是空的"
}

// i18next 按需加载语言资源
import i18n from 'i18next';
import LanguageDetector from 'i18next-browser-languagedetector';

i18n.use(LanguageDetector).init({
  fallbackLng: 'zh-CN',
  load: 'languageOnly',
  resources: {
    'zh-CN': { translation: zhCN },
    'en': { translation: en },
  },
});

import { FormattedMessage } from 'react-intl';

// 正确：交给 ICU 复数规则
<FormattedMessage
  id="app.itemCount"
  values={{ count: 5 }}
/>

{
  "app.itemCount": "{count, plural, =0 {没有商品} one {# 个商品} other {# 个商品}}"
}

// Intl.PluralRules 是真实标准 API，可直接获得复数类别
const rule = new Intl.PluralRules('en-US');
rule.select(1); // 'one'
rule.select(5); // 'other'

/* 使用逻辑属性，RTL 下自动翻转 */
.card {
  margin-inline-start: 16px;  /* LTR 为 left，RTL 为 right */
  padding-inline-end: 8px;
  text-align: start;           /* 跟随文档方向 */
}

/* 多语言站点的 dir 切换 */
html[dir='rtl'] .arrow-next {
  transform: scaleX(-1); /* 方向性图标翻转 */
}

// 日期与货币按区域格式化
const date = new Intl.DateTimeFormat('ar-EG').format(new Date(2026, 8, 27));
const price = new Intl.NumberFormat('de-DE', {
  style: 'currency',
  currency: 'EUR',
}).format(1999.5);

// Playwright + axe 集成
import AxeBuilder from '@axe-core/playwright';
import { test, expect } from '@playwright/test';

test('首页无严重可访问性违规', async ({ page }) => {
  await page.goto('/');
  const results = await new AxeBuilder({ page }).analyze();
  expect(results.violations.filter((v) => v.impact === 'critical')).toEqual([]);
});

import { render } from '@testing-library/react';
import { axe } from 'jest-axe';

it('组件无可访问性违规', async () => {
  const { container } = render(<NavMenu />);
  expect(await axe(container)).toHaveNoViolations();
});

npm i -D eslint-plugin-jsx-a11y

// .eslintrc 或 eslint.config.js
export default [
  {
    plugins: { 'jsx-a11y': jsxA11y },
    rules: {
      'jsx-a11y/alt-text': 'error',
      'jsx-a11y/anchor-has-content': 'error',
      'jsx-a11y/no-autofocus': 'error',
      'jsx-a11y/aria-props': 'error',
    },
  },
];

# CI 中校验翻译 key 完整性
npx @formatjs/cli extract --format simple 'src/**/*.tsx' --out-file messages.json
node scripts/check-translations.js locales/