语义
本页介绍如何在 Flutter 运行时中启用语义，让你的 Rive 图形可被屏幕阅读器访问。要了解什么是语义以及如何将其添加到图形中，请参阅编辑器文档中的语义。
概述
在 Rive 编辑器中，你可以为图形的某些元素添加语义含义——例如 button、checkbox、tab、image、list、dialog 等角色，以及相关的标签、值、状态和动作。这些设置因角色而异。
Flutter 运行时从正在运行的状态机中读取这些语义，并将它们投影到 Flutter 的语义树中。每个 Rive 语义节点都会成为一个 Flutter 语义节点，具有匹配的角色、标志和动作，定位在它所描述的元素上方，并随着状态机推进保持同步。
图形本身只是绘制出的像素，对辅助技术是不透明的，因此这棵被投影出来的语义树才是让图形可被发现的关键。运行时还会将屏幕阅读器的动作转发回状态机，例如点击按钮、调节滑块，或移动无障碍焦点。
语义是选择启用的。默认模式为 RiveSemantics.disabled，因此在你启用语义之前，不会查询或构建语义树。
必须在编辑器中定义语义才会产生效果。如果元素没有语义，则不会暴露给屏幕阅读器——无论你设置什么模式。请参阅功能支持，了解当前哪些运行时支持语义。
要求
rive版本0.15.0或更高。RiveWidget.semantics在0.14.x中不可用。- Flutter
3.32.0或更高（Dart3.8.0），这也是rive包的最低要求。
语义模式
语义由 RiveWidget 的 semantics 参数控制，该参数接受 RiveSemantics 模式，例如 RiveSemantics.auto：
| 模式 | 说明 |
|---|---|
disabled | 默认。 禁用语义。不会查询或构建语义树。 |
enabled | 语义已激活。语义树在 widget 挂载时构建，并随着状态机推进保持更新。 |
auto | 平台首次请求无障碍时激活语义，例如屏幕阅读器连接时，之后行为与 enabled 相同。在此之前不会查询或构建任何内容。 |
激活是单向的。一旦启用语义，控制器会持续跟踪它们直到被销毁，因此切回 RiveSemantics.disabled 会移除语义节点，但不会停止跟踪。
用法
构建 RiveWidget 时传入 semantics。
return RiveWidget(
controller: controller,
semantics: RiveSemantics.enabled,
);
使用 useSharedTexture 或 sharedTexture 绘制到共享纹理时，语义的工作方式相同。
仅为屏幕阅读器用户激活
使用 RiveSemantics.auto，这样在平台请求无障碍之前不会查询或构建任何内容。这对大多数应用是最佳默认值，因为从未开启屏幕阅读器的用户完全不会产生额外开销。
return RiveWidget(
controller: controller,
semantics: RiveSemantics.auto,
);
在 Web 上，平台会在用户激活页面中隐藏的 "Enable accessibility" 元素时请求无障碍，而不是在启动时。
语义如何映射到 Flutter
运行时将每个编辑器语义角色转换为匹配的 Flutter 语义角色、标志和动作。
在语义功能处于抢先体验阶段时，这组角色和特征可能会发生变化。
| 编辑器角色 | Flutter 语义 |
|---|---|
| Button | 带有点击动作的按钮 |
| Checkbox | 带有点击动作和勾选状态的按钮 |
| Switch | 带有点击动作和切换状态的按钮 |
| Slider | 带有值和增加/减少动作的滑块 |
| Text | 标签文本。标题还会报告标题级别。 |
| Image | 图像 |
| Group / None | 分组节点 |
| List / List item | 列表 / 列表项 |
| Tab / Tab list | 带有点击动作的标签页 / 标签栏 |
| Dialog / Alert dialog | 对话框 / 警告对话框。模态时，屏幕阅读器将其视为独立路由。 |
| Radio group / Radio button | 单选组 / 互斥组中带有点击动作的按钮 |
状态和特征映射到匹配的 Flutter 语义标志，例如 enabled、expanded、selected、checked、toggled 和 required。只有当编辑器中存在相应特征时才会设置标志，因此辅助技术看到的是"不适用"而非"false"。
- 标签（Label）、提示（Hint） 和 值（Value） 映射到节点的 label、hint 和 value。
- 隐藏（Hidden） 会将节点对辅助技术隐藏。
- 实时区域（Live Region） 将节点标记为实时区域，以便播报变化。
测试语义
Rive 语义走的是 Flutter 自带的无障碍支持，因此请使用 Flutter 支持的屏幕阅读器 进行测试：
- Android：TalkBack
- iOS / macOS：VoiceOver
- Windows：Narrator 或 NVDA
- Linux：Orca
- Web：宿主平台的屏幕阅读器，例如 macOS 和 iOS 上的 VoiceOver、Android 上的 TalkBack，或 Windows 上的 NVDA 或 JAWS
在运行时启用语义后，打开其中一种屏幕阅读器并导航你的图形。检查每个元素是否播报了清晰的标签、正确的角色、准确的值和状态，以及导航是否遵循逻辑顺序。在 MaterialApp 上设置 showSemanticsDebugger: true 会在屏幕上绘制生成的语义树。
Flutter 仅在平台请求时才会构建语义树，在 Web 上这意味着用户激活隐藏的 "Enable accessibility" 元素。调用 SemanticsBinding.instance.ensureSemantics() 可自行构建，无论是为了在没有屏幕阅读器的情况下检查它，还是为用户跳过该步骤；请在需要期间一直持有返回的 handle。
完整检查清单请参阅编辑器文档中的测试语义。