参数和返回值

Hooks

useRive

useRive hook 是接入 Rive runtime 的推荐方式，可提供完整控制，尤其适用于使用 Rive 状态机时。请参阅下文了解可传入的参数和返回值。

useRive(riveParams: UseRiveParameters, opts: UseRiveOptions): RiveState

• riveParams - 请参阅下文，了解在实例化 Web runtime 的 Rive 对象时传入的一组参数。可以传入 null 和 undefined，用于有条件地显示 .riv 文件
• opts - (可选) 请参阅下文，了解特定于 rive-react 的一组选项

参数

UseRiveParameters

这些参数大多来自底层 Web runtime 中用于配置 Rive 对象的项目，但不包括提供 canvas 元素这一项。有关此对象中可提供的所有参数，请参阅 Rive 参数。

以下参数特定于 useRive：

• onRiveReady - (可选) 当 Rive 文件完全加载并且 Rive 实例已初始化后调用的回调。该回调会接收 Rive 实例作为其参数：(rive: Rive) => void。它在状态机推进之前同步触发，因此所有预渲染数据绑定工作都应在此处进行——使用 setViewModelInstance() / setGlobalViewModelInstance() 设置视图模型实例、设置属性值，然后用 bind() 统一应用。数据绑定 Hook 在第一帧已经渲染后才解析。参见首帧前绑定。

💡

请使用 onRiveReady，而不是传入 onLoad 回调。当 JS 触发 RiveEvent.Load 事件时，会调用 onRiveReady。

UseRiveOptions

• useDevicePixelRatio - (可选) 如果为 true，hook 会根据 devicePixelRatio 缩放动画的分辨率。默认值为 true。注意：需要将 setContainerRef ref 回调传递给包裹 canvas 元素的元素。如果使用 RiveComponent，则会自动完成此操作
• fitCanvasToArtboardHeight - (可选) 如果为 true，canvas 将根据 artboard 的高度调整大小。默认值为 false
• useOffscreenRenderer - (可选) 如果为 true，Rive 实例将共享一个离屏 WebGL 上下文（如果不存在则创建一个）。这允许你在一个屏幕上显示多个 Rive 动画，以规避某些浏览器对多个并发 WebGL 上下文的限制。如果为 false，每个 Rive 实例都会拥有自己专用的 WebGL 上下文，你可能需要注意前面提到的浏览器限制。我们建议不要更改此默认属性，这样你就无需管理 WebGL 上下文。销毁 React 组件并不能保证浏览器会清理 canvas 挂载时创建的 WebGL 上下文。仅在使用 @rive-app/react-webgl2 时相关。默认值为 true

返回值

RiveState

• canvas - Rive 实例渲染到的 Canvas 元素
• container - Rive 实例渲染到的 canvas 的容器元素
• setCanvasRef - 要传递给 canvas 元素的 ref 回调
• setContainerRef - 要传递给 canvas 容器元素的 ref 回调。此项是可选的；但是，如果不使用它，则当窗口尺寸变化时，hook 不会自动将 canvas 调整为其外部容器的大小
• rive - 从 Web runtime 新创建的 Rive 实例
• RiveComponent - 用于在 DOM 中渲染 Rive 实例的 JSX 元素

在大多数情况下，你只需要从 useRive hook 中获取 RiveComponent 和 rive 返回值。只有在你需要自行控制 canvas/容器元素时，才需要设置 canvas ref 和 container ref。

useStateMachineInput

⚠️

已在 v4.33.0 中弃用。 此 hook 仍然可用，尚未移除任何内容，但状态机输入将在未来的主版本中被移除。新项目请使用数据绑定——参见迁移指南。

useStateMachineInput hook 可用于获取 Rive 状态机输入的引用，既可读取输入值，也可设置（或触发）它们。请参阅下文了解可传入的参数和返回值。

useStateMachineInput(rive: Rive | null, stateMachineName?: string, inputName?: string, initialValue?: number | boolean): StateMachineInput | null

由于需要先解析 rive 实例，因此作为返回值的状态机输入可能不会立即可用。你可能需要使用 useEffect 来监听 rive 实例以及 useStateMachineInput hook 的返回值何时具有值

参数

• rive - 第 1 个参数是已实例化的 Rive 对象，可通过 useRive hook 获取
• stateMachineName? - (可选) 要从中获取输入的状态机名称
• inputName? - (可选) 要获取引用的单个状态机输入名称
• initialValue? - (可选) 要在输入上设置的初始值

返回值

此 hook 返回一个默认的 StateMachineInput 实例。

StateMachineInput

• name (get) - 访问输入的名称
• value (get and set) - 访问输入的值，并通过此属性设置输入的值
• fire() - 触发一个 trigger 输入

请参阅输入页面，了解此 hook 的更多用法。

useResizeCanvas

useResizeCanvas hook 是一个可选的实用 hook，用于将 <canvas> 元素调整为其父容器元素的大小，同时也会重置 canvas 的适当表面区域大小。当你不想使用 useRive hook 来渲染 Rive，而是可能在 React 应用中使用 Web JS runtime，但仍希望能够将 <canvas> 适当地缩放到其父级大小时，这会很有用。

此 hook 已在 Rive React runtime 内部使用，因此如果你使用 useRive hook 或默认导出的 <RiveComponent /> 来渲染 Rive，就不需要自己使用此 hook。

useResizeCanvas(resizeProps: UseResizeCanvasProps): void

• resizeProps - 请参阅下文，了解可在此对象参数上设置的一组属性

参数

UseResizeCanvasProps

• riveLoaded: boolean - 如果为 true，表示 Rive 实例已创建且 Rive 文件已解析。这可确保 hook 不会过早地缩放 <canvas> 元素。默认值为 false
• canvasRef: MutableRefObject<HTMLCanvasElement | null> - 指向 Rive 将渲染到的 <canvas> 元素的 React Ref
• containerRef: MutableRefObject<HTMLElement | null> - 指向 canvas 父容器元素的 React Ref
• onCanvasHasResized?: () => void（可选）当 canvas 因其父容器尺寸变化而调整大小后调用的回调。你可以在这里重置 Rive renderer 的布局尺寸，以指定 canvas 的新 min/max 边界。
  • 使用高级 JS runtime 时，这可能只是简单调用 rive.resizeToCanvas()
  • 使用低级 JS runtime 时，这可能是调用 renderer 的 .align() 方法，并传入 Layout 以及 canvas 的 min/max X/Y 值。
• options?: Partial - （可选）传递给 useRive hook 的选项（参见本文档上方的 UseRiveOptions）
• artboardBounds?: Bounds - （可选）Artboard 的 AABB 边界；只有在 options.fitCanvasToArtboardHeight 设置为 true 时，才需要提供此项。

useRiveFile

useRiveFile hook 旨在用于在组件中初始化和管理 RiveFile 实例。它会根据提供的源参数（URL 或 ArrayBuffer）设置 RiveFile，并在组件卸载或输入变化时确保正确清理，以避免内存泄漏。

此 hook 的主要优点是，它允许你创建一个可在多个组件之间复用的 RiveFile 实例，而无需再次从 src URL 获取它，或从 buffer 重新加载它。这可以通过消除冗余的网络请求和加载时间来提升性能，尤其是在从同一来源创建多个 Rive 实例时。与直接将 buffer 和 src 参数传递给 useRive hook 不同——后者在底层仍需要解析以创建 RiveFile 对象——此 hook 会返回一个已经解析完成的 RiveFile 对象，其中包括任何已加载的资源。

useRiveFile(params: UseRiveFileParameters): RiveFileState

参数

UseRiveFileParameters

• src? - (可选) src 有两种可选用法：通过指向 .riv 文件的 URL，或使用指向公共 .riv 资源的路径。必须提供 src 或 buffer 之一。
  • URL - 如果你将 .riv 托管在某个可公开访问的 bucket/CDN（例如 AWS、GCS 等）上，可以在此处传入 URL。
    • 另外，使用 ES6 时，你可以将 .riv 文件作为 data URI 导入。根据你的 bundle loader，你可能需要使用插件（例如 Webpack 的 url-loader）来正确解析并加载 .riv 文件为 data URI 字符串。可参阅此项目，了解如何设置的基本示例
  • 指向公共资源的路径 - 如果 .riv 公共资源已打包到你的应用中，这是指向它的字符串路径。请注意，这不是相对于当前 JS 文件所在位置的资源相对路径。请像处理应用中打包的任何其他资源（例如图片或字体）一样对待 .riv。如果你的 JS 被编译并从 Web 应用根目录 / 运行，则必须指定从根目录到资源位置的路径。例如，如果你的资源位于 /public/foo.riv，并且你的 JS 从根目录 / 运行，则应在此属性中指定：src: '/public/foo.riv'。
• buffer? - (可选) 包含 .riv 文件原始字节的 ArrayBuffer。必须提供 src 或 buffer 之一。
• enableRiveAssetCDN? - (可选) 允许 runtime 自动加载托管在 Rive CDN 中的资源。默认启用。

返回值

RiveFileState

• riveFile - RiveFile 实例。在文件加载完成之前，此值为 null。
• status - 文件加载过程的状态，可以是 idle、loading、failed 或 success。

Components

<RiveComponent />

默认导出的 RiveComponent 以及从 useRive hook 返回的 RiveComponent 都用于在组件的 JSX 中渲染。如前所述，所有可以传递给 canvas 元素的属性和事件处理器，也都可以传递给 Rive 组件并以相同方式使用。

Props

除任何 canvas 属性外，默认导出还接受以下 props。它始终以 autoplay: true 播放。如果需要超出简单嵌入的功能——控制播放、读取 Rive 实例或数据绑定——请改用 useRive hook。

interface RiveProps {
  src: string; // 必填
  artboard?: string;
  stateMachine?: string;
  layout?: Layout;
  useOffscreenRenderer?: boolean;
  shouldDisableRiveListeners?: boolean;
  shouldResizeCanvasToContainer?: boolean;

  // 已弃用的 props
  animations?: string | string[];
  stateMachines?: string | string[];
  automaticallyHandleEvents?: boolean;
}

• src - （必填） Rive 资源的 URL，或公共 .riv 资源的路径。
• artboard - （可选） 要渲染的画板。默认为文件中的第一个画板。
• stateMachine - （强烈推荐） 要播放的状态机名称。
• layout - （可选） 一个 Layout 实例，用于设置绘制表面的 fit 和对齐方式。
• useOffscreenRenderer - （可选） 在多个 canvas 之间共享单个 WebGL 上下文。仅与 @rive-app/react-webgl2 相关。默认为 true。
• shouldDisableRiveListeners - （可选） 阻止 Rive 向 canvas 附加指针事件监听器。
• shouldResizeCanvasToContainer - （可选） 自动将 canvas 调整为其容器的大小。默认为 true。

已弃用的 props

• stateMachines - 请改用 stateMachine 并传入单个状态机名称。
• animations - 请改用 stateMachine 来播放状态机。
• automaticallyHandleEvents - 随 Rive Events 相关接口的其余部分一起弃用。请改用数据绑定。

需要注意的一点是，在组件上设置的 style/className props 会传递给外层的 <div> 元素，而不是底层的 <canvas> 本身。原因是外层的 <div> 元素会为你处理调整大小和布局，因此所有样式都应传递给此元素。

<canvas> 元素仍会接收传入组件的任何其他 props，例如 aria-* 属性、role 等。你也可以在组件内部设置 children 内容，用于 <canvas> 元素无法显示时的 fallback 场景。