语义

本页介绍如何在 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 或更高（Dart 3.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。

完整检查清单请参阅编辑器文档中的测试语义。