后台与工具型界面的可访问性检查点

// ❌ 错误做法：焦点会逃出弹窗，关闭按钮不可聚焦
function ExportModal({ onClose }) {
  return (
    <div className="modal-overlay">
      <div className="modal">
        <div className="modal-close" onClick={onClose}>×</div>
        <DateRangePicker />
        <FormatSelect />
        <button>确认导出</button>
      </div>
    </div>
  )
}

// ✅ 正确做法：原生 button + 焦点捕获 + Escape 关闭
function ExportModal({ onClose }) {
  const modalRef = useRef<HTMLDivElement>(null)
 
  useEffect(() => {
    // 弹窗打开时焦点进入容器
    modalRef.current?.focus()
 
    const handleKeyDown = (e: KeyboardEvent) => {
      if (e.key === 'Escape') {
        onClose()
        return
      }
      if (e.key === 'Tab') {
        // 焦点捕获：在弹窗内的可聚焦元素之间循环
        const focusable = modalRef.current?.querySelectorAll(
          'button, [href], input, select, textarea, [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', handleKeyDown)
    return () => document.removeEventListener('keydown', handleKeyDown)
  }, [onClose])
 
  return (
    <div
      className="modal-overlay"
      role="dialog"
      aria-modal="true"
      aria-labelledby="export-modal-title"
    >
      <div className="modal" ref={modalRef} tabIndex={-1}>
        <h2 id="export-modal-title">导出数据</h2>
        {/* ✅ 原生 button，键盘天然可聚焦 */}
        <button
          className="modal-close"
          onClick={onClose}
          aria-label="关闭导出弹窗"
        >
          ×
        </button>
        <DateRangePicker />
        <FormatSelect />
        <button>确认导出</button>
      </div>
    </div>
  )
}

<!-- ❌ 错误做法：只靠颜色区分，没有文字替代，对比度不达标 -->
<svg width="600" height="300">
  <rect fill="#F5F5F5" />
  <!-- 灰色折线在浅灰背景上几乎不可见，对比度 1.9:1 -->
  <polyline points="..." stroke="#999999" fill="none" />
  <polyline points="..." stroke="#E74C3C" fill="none" />
  <polyline points="..." stroke="#27AE60" fill="none" />
  <text x="10" y="20">各渠道订单趋势</text>
</svg>

// ✅ 正确做法：高对比色 + 形状区分 + 隐藏的数据表格
function OrderTrendChart({ data }: { data: TrendData[] }) {
  // 使用色盲友好调色板，所有颜色与白色背景对比度 ≥ 3:1
  const channelStyles = {
    '直营':  { color: '#005A9C', dash: 'none',   marker: 'circle' },
    '分销':  { color: '#D35400', dash: '5,5',    marker: 'square' },
    '其他':  { color: '#1A1A1A', dash: '2,2',    marker: 'triangle' },
  }
 
  return (
    <figure>
      <figcaption>
        过去 30 天各渠道订单趋势
        {/* 屏幕阅读器可见、视觉隐藏的详细数据 */}
        <span className="sr-only">
          {data.map(channel => (
            <span key={channel.name}>
              {channel.name}渠道共{channel.total}单，
              最高{channel.peak}单（{channel.peakDate}），
              最低{channel.low}单（{channel.lowDate}）。
            </span>
          ))}
        </span>
      </figcaption>
 
      <svg role="img" aria-hidden="true" width="600" height="300">
        {data.map(channel => (
          <polyline
            key={channel.name}
            points={channel.points}
            stroke={channelStyles[channel.name].color}
            strokeDasharray={channelStyles[channel.name].dash}
            fill="none"
            strokeWidth="2"
          />
        ))}
      </svg>
 
      {/* 降级：完整的数据表格，屏幕阅读器和键盘用户可直接访问 */}
      <details>
        <summary>查看数据表格</summary>
        <table>
          <thead>
            <tr>
              <th scope="col">日期</th>
              {data.map(c => <th key={c.name} scope="col">{c.name}</th>)}
            </tr>
          </thead>
          <tbody>
            {/* 表格内容省略 */}
          </tbody>
        </table>
      </details>
    </figure>
  )
}

.sr-only {
  position: absolute;
  width: 1px;
  height: 1px;
  padding: 0;
  margin: -1px;
  overflow: hidden;
  clip: rect(0, 0, 0, 0);
  white-space: nowrap;
  border-width: 0;
}

<!-- ❌ 错误做法：div 模拟表格，丢失语义结构 -->
<div className="order-list">
  <div className="order-header">
    <div className="col">订单号</div>
    <div className="col">状态</div>
    <div className="col">金额</div>
    <div className="col">操作</div>
  </div>
  {orders.map(order => (
    <div className="order-row" key={order.id}>
      <div className="col">{order.id}</div>
      <div className="col">{order.status}</div>
      <div className="col">{order.amount}</div>
      <div className="col">
        <div onClick={() => handleEdit(order)}>编辑</div>
        <div onClick={() => handleDelete(order)}>删除</div>
      </div>
    </div>
  ))}
</div>

<!-- ✅ 正确做法：原生 table + 语义化表头 + 原生按钮 -->
<table className="order-list" aria-label="订单列表">
  <thead>
    <tr>
      <th scope="col">订单号</th>
      <th scope="col">状态</th>
      <th scope="col">金额</th>
      <th scope="col">操作</th>
    </tr>
  </thead>
  <tbody>
    {orders.map(order => (
      <tr key={order.id}>
        <td>{order.id}</td>
        <td>
          {/* 状态不只是颜色，同时提供文字 */}
          <span
            className={`status-badge status-${order.statusType}`}
          >
            {order.statusLabel}
          </span>
        </td>
        <td>{order.amount}</td>
        <td>
          {/* 原生 button，键盘天然可用 */}
          <button onClick={() => handleEdit(order)}>编辑</button>
          <button onClick={() => handleDelete(order)}>删除</button>
        </td>
      </tr>
    ))}
  </tbody>
</table>

// ❌ 错误做法：只显示红色边框和模糊错误信息
function EmailField() {
  const [error, setError] = useState(false)
  return (
    <div>
      <input
        className={error ? 'border-red' : ''}
        placeholder="邮箱"
      />
      {error && <span className="error-text">输入有误</span>}
    </div>
  )
}
 
// ✅ 正确做法：关联 label、明确错误信息、aria-live 播报
function EmailField() {
  const [error, setError] = useState<string | null>(null)
  const id = 'email'
  const errorId = `${id}-error`
 
  const validate = (value: string) => {
    if (!value) {
      setError('请输入邮箱地址')
    } else if (!/^[^\s@]+@[^\s@]+\.[^\s@]+$/.test(value)) {
      setError('邮箱格式不正确，示例：[email protected]')
    } else {
      setError(null)
    }
  }
 
  return (
    <div>
      {/* ✅ label 通过 htmlFor 关联 input */}
      <label htmlFor={id}>邮箱地址</label>
      <input
        id={id}
        type="email"
        // ✅ 错误时建立 aria-describedby 关联
        aria-describedby={error ? errorId : undefined}
        aria-invalid={!!error}
        onBlur={(e) => validate(e.target.value)}
      />
      {/* ✅ aria-live="polite" 让屏幕阅读器在空闲时播报错误 */}
      {error && (
        <div id={errorId} role="alert" aria-live="polite" className="error-text">
          {error}
        </div>
      )}
    </div>
  )
}