跳到主要内容
中文系列课

React

概述​

本指南介绍了如何开始使用 React 运行时库。Rive 运行时库是开源的，源代码可在其 GitHub 仓库 中查看。

该库包含一个 React 组件以及自定义 Hook，帮助你将 Rive 集成到 Web 应用中（含类型定义）。底层实现上，该运行时是 @rive-app/webgl2 运行时的 React 友好封装，对外暴露类型和 Rive 实例功能。

快速开始​

按照以下步骤快速将 Rive 集成到你的 React 应用中。

安装依赖​

Rive React 运行时根据所需的底层渲染器提供两个主要选项：

  • （推荐） @rive-app/react-webgl2 - 封装 @rive-app/webgl2 依赖，使用 Rive 渲染器。
  • @rive-app/react-canvas - 封装 @rive-app/canvas 依赖。不使用 Rive 渲染器，不支持矢量羽化等高级功能。
  • @rive-app/react-canvas-lite - 类似 @rive-app/react-canvas，但更小。如果 Rive 文件使用了 Rive Text 或其他高级功能，不推荐使用。

要充分利用 react-webgl2 下 Rive 渲染器的性能优势，请启用 WEBGL_shader_pixel_local_storage Chrome 扩展（添加 WebGL Draft Extensions）。

如果用户设备上未启用该扩展，在不支持该扩展的浏览器上 Rive 将回退到 MSAA 方案（同样使用 WebGL2）。

我们正在与主流浏览器合作，争取在未来默认支持该扩展。

npm i --save @rive-app/react-webgl2

渲染 Rive 组件​

Rive React 提供一个基础组件作为默认导出，用于显示简单动画，你可以设置一些属性，如画板和布局。将以下代码添加到你的 React 项目中来测试一个示例 Rive 动画。

import Rive from '@rive-app/react-webgl2';

export const Simple = () => (
  <Rive
    src="https://cdn.rive.app/animations/vehicles.riv"
    stateMachines="bumpy"
  />
);

更多关于 <Rive /> 组件的参数和返回值，请参见参数和返回值。

使用 useRive Hook​

在许多情况下，你可能不仅需要 React 组件来渲染动画，还需要控制它的 rive 对象实例。Rive 对象实例允许你调用以下 API：

  • 动态设置 Rive Text 值
  • 用自己的回调订阅 Rive 事件
  • 控制动画播放（如暂停和播放）
  • ……以及更多功能

useRive Hook 同时返回 rive 实例和 React 组件，该组件挂载 Rive 将要绘制到的底层 <canvas> 元素。

import { useRive } from '@rive-app/react-webgl2';

export default function Simple() {
  const { rive, RiveComponent } = useRive({
    src: 'https://cdn.rive.app/animations/vehicles.riv',
    stateMachines: "bumpy",
    autoplay: false,
  });

  return (
    <RiveComponent
      onMouseEnter={() => rive && rive.play()}
      onMouseLeave={() => rive && rive.pause()}
    />
  );
}

注意： Rive 在 <RiveComponent /> 渲染出来之前不会实例化，因为底层 <canvas> 元素需要存在于 DOM 中。

另外，请注意画布大小取决于其所在的容器。初始大小为 0x0。可以向 RiveComponent 传入 className，或者将 RiveComponent 包裹在适当大小的容器中。

更多关于 useRive 的参数和返回值，请参见这里。

此外，请浏览后续的运行时页面，了解如何控制动画播放、状态机等。

useRive 的渲染注意事项​

目前，如果你计划条件渲染从 useRive Hook 返回的 <RiveComponent />，我们强烈建议将 useRive 的使用隔离到自己的包装组件中。这是因为 Rive 在组件挂载时实例化，渲染上下文与特定的底层 <canvas> 元素关联。当 React 尝试卸载/重新渲染时，动画可能会重新开始，或者挂载新 <canvas> 时动画无法显示。

通过将 useRive 隔离到自己的包装组件中，Rive 将有机会正确清理并使用新画布重新开始动画。在父组件中，你可以根据任何状态或基于 prop 的逻辑条件渲染包装组件。

请参阅此 CodeSandbox 示例了解此模式的用法。

资源​

GitHub：https://github.com/rive-app/rive-react

类型定义：https://github.com/rive-app/rive-react/blob/main/src/types.ts

示例