# 无障碍访问（a11y）

> 在 CrossFly 中提供宽裕的触摸目标、对比度、可缩放文本以及多感官反馈。

Source: https://crossfly.dev/zh/docs/best-practices/acessibilidade — CrossFly documentation. Full docs as one file: https://crossfly.dev/llms-full.txt

# 无障碍访问（a11y）

坦诚地说明框架当今能提供什么：聚焦于在 CrossFly 原生/OpenGL 中**可落地执行**的部分。这里的很多无障碍实践都**强化了响应式设计**——采用字体相对单位就是对用户尺寸调整设置的尊重。

## 宽裕的触摸目标
用 `Relative` 来设定可触摸区域的尺寸，绝不要用极小的像素值：
```java
botao.getStyle().autoHeight(Relative.ofFont(2.5f));            // 足够高以便手指点击
icone.getStyle().autoWidth(Relative.ofScreen(0.12f, ScreenSize.MIN))
     .autoHeight(Relative.ofScreen(0.12f, ScreenSize.MIN));   // 可自适应的方形
```
实用规则：目标约为 48 dp 等效尺寸——`Relative.ofFont(2.5f)` 通常就够用。

## 文本对比度
确保足够的对比度；框架能帮上忙：
```java
int fundo  = cs.surface.color();
int texto  = ColorUtils.contrastText(fundo);                  // 根据背景取黑/白
int melhor = ColorUtils.getContrastColor(fundo, 0xFF000000, 0xFFFFFFFF);  // 在 2 个选项间选择
```
尊重浅色/深色主题（通过 `Styles.setColorScheme`/`setDarkMode`）——不要固定写死会忽略当前模式的颜色（参见 [浅色/深色模式](/docs/ui/theming/dark-mode)）。

## 可缩放的文本
由于字体是以相对单位度量的，**文本和布局会随应用的字体缩放而缩放**——这是使用 `Relative.ofFont(...)` 并避免固定像素的直接结果。让 `Label` 自动换行；**不要截断**关键信息。

## 多感官反馈与语音
```java
Device.vibrate(50);            // 重要操作的触觉确认
Device.beep();                 // 声音提示
Device.textToVoice(mensagem);  // 语音朗读（辅助）
```
将其作为**辅助**手段，而非唯一渠道——结合视觉 + 触觉/声音。

## 最佳实践
- 用 `Relative.ofFont`/`ofScreen(MIN)` 设定触摸目标；不要用只有几像素的按钮。
- 通过 `contrastText`/`getContrastColor` 处理对比度；遵循浅色/深色模式。
- 不要截断关键文本；让它缩放/换行。

## 常见错误
- 使用固定像素的极小按钮/图标（难以触碰；不会缩放）。
- 固定写死的颜色在深色模式下破坏对比度。
- 仅依靠颜色来传达状态（应加上图标/文本）。

## 局限性
**屏幕阅读器**功能取决于平台/启动器——核心中没有通用的语义无障碍层。请优先落实上面那些可执行的项目。

## 另请参阅
- [响应式设计](/docs/best-practices/responsividade) · [浅色/深色模式](/docs/ui/theming/dark-mode) · 颜色（第 11 章）