语义（Semantics）

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

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

在 Rive 编辑器中，你可以为图形的某些元素添加语义含义——例如 button、checkbox、tab、image、list、dialog 等角色，以及相关的标签、值、状态和动作。这些设置因角色而异。

React 运行时是其 JavaScript 对应版本的轻量封装，因此语义在这里的行为完全相同。本页仅介绍如何通过 useRive 传递选择启用参数。

有关编辑器角色如何映射到 ARIA 角色和 DOM 元素、哪些键盘交互触发哪些语义动作、叠加层定位以及如何使用屏幕阅读器测试，请参阅 Web (JS) 语义。该页面是本页面所有内容的参考。

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

用法

像其他 Rive 参数 一样，将 semanticsMode 传递给 useRive。SemanticMode 从你的 React 包中重新导出，因此你可以在同一个地方导入两者。

import { useRive, SemanticMode } from "@rive-app/react-canvas";

export default function Login() {
  const { RiveComponent } = useRive({
    src: "/login.riv",
    stateMachine: "State Machine 1",
    autoplay: true,
    autoBind: true,
    semanticsMode: SemanticMode.Enabled,
  });

  return <RiveComponent />;
}

标注图形

使用 semanticsOptions.riveCanvasLabel 在语义叠加层容器上设置 aria-label，描述图形是什么，以便屏幕阅读器用户知道他们正在进入什么。

export default function Login() {
  const { RiveComponent } = useRive({
    src: "/login.riv",
    stateMachine: "State Machine 1",
    autoplay: true,
    autoBind: true,
    semanticsMode: SemanticMode.Enabled,
    semanticsOptions: {
      riveCanvasLabel: "Login Experience",
    },
  });

  return <RiveComponent />;
}

加载后启用语义

要控制何时启用语义，请省略 semanticsMode，并在 useRive 返回的 rive 实例上调用 enableSemantics()。

import { useEffect } from "react";
import { useRive } from "@rive-app/react-canvas";

export default function Login({ accessibilityEnabled }) {
  const { RiveComponent, rive } = useRive({
    src: "/login.riv",
    stateMachine: "State Machine 1",
    autoplay: true,
    autoBind: true,
  });

  useEffect(() => {
    if (rive && accessibilityEnabled) {
      rive.enableSemantics();
    }
  }, [rive, accessibilityEnabled]);

  return <RiveComponent />;
}

叠加层定位

RiveComponent 将 <canvas> 渲染在容器 <div> 内。如叠加层定位中所述，当画布具有已定位的祖先时，叠加层对齐效果最佳。该 <div> 容器默认未定位。

如果你的布局在组件上方没有已定位的祖先，请传递设置 position: relative 的 className。

<RiveComponent className="rive-container" />

.rive-container {
  position: relative;
  width: 100%;
  height: 100%;
}