---
title: "无障碍"
description: "Tanrei 内建于令牌和组件规格中的无障碍要求，以及保证这些要求得到遵守的检查。"
url: "https://tanrei.chnotchy.com/zh-cn/foundations/accessibility/"
last_updated: 2026-10-23T17:33:05.000Z
---

# 无障碍

> Tanrei 内建于令牌和组件规格中的无障碍要求，以及保证这些要求得到遵守的检查。

在 Tanrei 中，无障碍是对系统本身施加的一组约束。令牌构建不会输出对比度不达标的配色方案；组件规格如果缺少角色、键盘操作表和目标尺寸保证，就不是有效的规格。

## 对比度

令牌构建会用以下阈值测量每一种配色方案（浅色和深色，各自在标准、中、高对比度下），只要有一对达不到就会失败：

| 内容 | 标准与中对比度 | 高对比度 |
| --- | --- | --- |
| 文本，以及用内容色绘制的图标 | 4.5:1 | 7:1 |
| 状态标记相对于该状态自己的色调容器 | 3:1 | 3:1 |
| 识别或操作控件所必需的边界和图形 | 3:1 | 3:1 |
| 焦点环相对于相邻表面 | 3:1 | 3:1 |

大号文本没有更低的阈值。WCAG 对常规字重约 24px 及以上、或粗体约 19px 及以上的文本接受较低的对比度，但构建对所有文本角色都按 4.5:1 检查，高对比度下按 7:1：颜色角色并不知道自己会以多大的字号使用。

禁用的元素和纯装饰不受此限，标准对比度下 `outline-variant` 的细线也在其列。正因为有这项豁免，当边框是表明控件存在的唯一线索时，必须使用 `outline`，而不是 `outline-variant`。

### 强制执行的不变式

以下条件在每个主题、每个对比度级别下（共 6 种组合）都成立，否则构建失败：

- 每一对 `(X, on-X)` 角色，以及每个文本角色（`on-surface`、`on-surface-variant`、`link`、意图的颜色）相对于每个表面角色，对比度至少为 4.5:1，在两种高对比度方案中至少为 7:1；
- 每个状态的颜色相对于该状态自己的色调容器至少为 3:1；
- `outline` 相对于每个表面角色至少为 3:1；
- 在默认系统的中、高对比度下，`outline-variant` 相对于每个表面角色分别至少为 3:1 和 4.5:1，并且 `outline` 始终更强；
- `focus-ring` 相对于表面至少为 3:1。

项目规则禁止为了让检查通过而放宽阈值。

## 目标尺寸

The least sizes of what a person presses. minimum is the least height (and, for an icon-only control, width) anything pressable is drawn at; touch and pointer are the least hit areas, which a control reaches past what it draws where it stands alone.

| 令牌 | 值 | 预览 |
| --- | --- | --- |
| `--tanrei-sys-target-minimum` | 32px |  |
| `--tanrei-sys-target-pointer` | 44px |  |
| `--tanrei-sys-target-spacing` | 8px |  |
| `--tanrei-sys-target-touch` | 48px |  |

生成自 `design/tokens/tanrei.light.tokens.json`, `tokens/sys/measure.tokens.json`

**外观尺寸不等于点击区域。** Tanrei 的小号按钮高 32 个单位，适合紧凑的工具栏，但它的响应范围在触摸时仍不小于 48 个单位，在使用指针时不小于 44 个单位。组件会以不可见的方式扩大点击区域，并让相邻目标之间至少保持 8 个单位的距离。每份规格都声明这项保证，每个平台都对它进行测试。

## 焦点

每个可交互的组件，在获得键盘焦点或辅助技术焦点时，都会显示“先留间隙、再画圆环”的焦点指示。它立即出现，不带动画。焦点顺序与阅读顺序一致。禁用的组件不在焦点顺序之内。

## 键盘

每份组件规格都包含一张按键与动作的对照表，显示在该组件文档页面的“**无障碍**”一节。支持硬件键盘的平台严格按这张表实现。

## 文本缩放

文本放大到 **200%** 时，界面必须仍然可用。容器随文本一起变大，标签先换行、再截断，任何地方都不依赖固定高度来容纳一行文本。原生实现使用各平台自带的文本缩放机制。

## 减弱动态效果

当系统要求减弱动态效果时，空间上的动画会被移除，或替换为短暂的淡入淡出，并且没有任何循环播放的动画。参见[动效](https://tanrei.chnotchy.com/zh-cn/foundations/motion/)。

## 语义

规格会写明组件的 WAI-ARIA 角色，以及它的无障碍名称如何确定。各平台把这个角色映射为各自的原生对应物：SwiftUI 的无障碍特征（accessibility traits）、Compose 和 Flutter 的语义属性、React Native 的 `accessibilityRole`。在 Web 上，Tanrei 优先在 shadow root 内使用原生元素，让浏览器和测试工具读到真实的语义。

## 如何测试

| 平台 | 自动化检查 |
| --- | --- |
| Web | 在 Playwright 中运行 axe-core |
| SwiftUI | XCTest 的无障碍审计 |
| Compose | Accessibility Test Framework 的检查 |
| Flutter | `meetsGuideline` 匹配器 |
| React Native | 对角色和标签的断言，以及通过示例应用进行的原生审计 |

> [!NOTE]
> **注意**
>
> 自动化检查只能发现实际问题中的一小部分。它们只是底线。凡是用这些组件构建的界面，都请用屏幕阅读器和键盘实际操作一遍。