语义

语义目前仅在抢先体验中可用。运行时支持正在开发中，或已作为实验性功能发布。

有反馈？加入抢先体验社区分享你的想法，帮助塑造此功能。

本页介绍如何在新版 Apple Runtime 中启用语义，让你的 Rive 视图可被 VoiceOver 访问。要了解什么是语义以及如何将其添加到图形中，请参阅编辑器文档中的语义。

概述

你可以在 Rive 编辑器中为图形元素添加语义——例如 button、checkbox、tab、slider、image、link、list 或 dialog 等角色，以及它们的标签、值、状态和动作。在运行时，新版 Apple Runtime 会从正在运行的状态机中读取这些语义，并将它们作为视图的 accessibilityElements 暴露给 VoiceOver，同时随着状态机推进保持更新。

⚠️

语义是选择启用的。默认模式为 .off，因此在你为视图启用语义之前，不会创建任何无障碍元素。

必须在编辑器中定义语义才会产生效果。如果元素没有语义，则不会暴露给 VoiceOver——无论你设置什么模式。请参阅功能支持，了解当前哪些运行时支持语义。

可用性

语义仅在新版 Apple Runtime 中可用（不适用于 Legacy Runtime），并支持该运行时支持的所有 Apple 平台，macOS（AppKit）除外：

平台	支持
iOS / iPadOS	✅
tvOS	✅
visionOS	✅
Mac Catalyst	✅
macOS (AppKit)	❌

语义模式

语义由 Semantics 枚举控制，该枚举用于设置 Rive 视图的 VoiceOver 集成模式：

模式	说明
.off	默认。 禁用无障碍语义。无论 VoiceOver 状态如何，都不会创建无障碍元素。
.on	始终启用无障碍语义。元素会在每一帧创建并保持最新。
.automatic	根据 VoiceOver 当前是否正在运行，自动启用或停用无障碍语义。

对于大多数应用，建议使用 .automatic——它只会在 VoiceOver 处于活动状态时同步无障碍树，从而避免在未启用 VoiceOver 时产生不必要的工作。

用法

在视图上设置语义模式（UIKit），或使用 .semantics(_:) 修饰符（SwiftUI）。

UIKit：

let rive = try await Rive(...)
let riveView = RiveUIView(rive: rive)
// Enable semantics only while VoiceOver is running
riveView.semantics = .automatic
// Always keep semantics active
riveView.semantics = .on
// Disable semantics (default)
riveView.semantics = .off

SwiftUI：

var body: some View {
    RiveUIViewRepresentable(rive)
        .semantics(.automatic)
    // or .semantics(.on)
    // or .semantics(.off)
}

SwiftUI（异步）：

var body: some View {
    AsyncRiveUIViewRepresentable {
        let worker = try await Worker()
        let file = try await File(source: ..., worker: worker)
        let rive = try await Rive(file: file)
        return rive
    }
    .semantics(.automatic)
}