跳到主要内容
中文系列课

迁移指南

从 @rive-app/react-webgl 迁移到 @rive-app/react-webgl2​

我们强烈建议迁移到 @rive-app/react-webgl2，在大多数情况下可获得最佳的渲染质量和性能。@rive-app/react-webgl 包已弃用，在 v4.27.3 之后不再接收更新。

无需更改 API，只需更新你的包安装和导入语句，改用 @rive-app/react-webgl2。此更改将使你能够利用 Rive 渲染器 改进的渲染能力，同时保持与现有代码库的兼容性。

从 3.x.x 迁移到 4.x.x​

从 React 运行时的 v4 版本开始，Rive 将支持运行时 Rive Text，涉及以下包：

  • React
  • @rive-app/react-canvas
  • @rive-app/react-webgl2

重大变更​

无破坏性 API 变更！

虽然发布了新的主版本，但没有破坏性 API 变更。v4 发布是因为核心 Web (JS) 运行时依赖导致包体积增大。请参见该迁移指南这里。

未来，如果你不需要文本功能，我们可能会推出不含这些大型依赖的"lite"包，但目前它仍将是主要 Web 运行时包的默认配置。

从 1.x.x 迁移到 3.x.x​

对于大多数情况，如果你使用的是 rive-react 的 v1.x.x，你应该能够升级到 v3.x.x 的新依赖，而无需太多更改。

注意：从 v2.x.x 迁移到 3.x.x 可以安全完成，无需你做任何更改。

依赖变更​

在 v2.x.x 之前，你可以通过 rive-react 包在 React 中使用 Rive。该包是 @rive-app/webgl 依赖的封装。在 v2.x.x+ 中，我们通过两个新的 React 包使 React 运行时能够同时封装 @rive-app/webgl 和 @rive-app/canvas 依赖：

  • （推荐） @rive-app/react-canvas
  • @rive-app/react-webgl

rive-react 包仍将定期与上述包一起发布，但它将两个 Web 运行时依赖都设为 dependencies，可能导致更大的包体积。因此，我们建议从 rive-react 切换到 @rive-app/react-canvas，或者如果需要使用 WebGL 后端上下文，则切换到 WebGL 变体。

之前：

npm i rive-react

之后：

npm i @rive-app/react-canvas

在 rive-react 和 @rive-app/react-canvas 之间，React 运行时的导入方式没有变化。

属性传递​

React 运行时的 RiveComponent（无论是使用默认导出还是 useRive Hook）应传入 JSX 以渲染画布。DOM 包含一个包裹画布的 div，用于处理画布的样式和大小。在 v2.x.x 之前，大多数在 RiveComponent 上传递的属性会被传递到该包裹 <div> 元素。从 v2.x.x 开始，涉及样式（即 className 和 style）的某些属性将传递到包裹 <div>，但其他任何属性现在将传递到 <canvas> 元素，以便你可以设置 role、aria-* 属性等。

之前：

<RiveComponent className="foo" aria-label="Label" />

将渲染（简化的）DOM 如下：

<div className="foo" aria-label="Label">
<canvas></canvas>
</div>

之后：

<RiveComponent className="foo" aria-label="Label" />

现在产生以下（简化的）DOM：

<div className="foo">
<canvas aria-label="Label"></canvas>
</div>

从 0.x.x 迁移到 1.x.x​

在 rive-react 的 v1.0.0 之前，React 运行时封装了 @rive-app/canvas 运行时依赖，使用 CanvasRenderingContext2D 后端。为了让 React 运行时支持即将推出的一些高级绘制功能（如 Mesh Deformations），它需要使用 @rive-app/webgl 运行时。

主版本升级到 v1.0.0 不涉及破坏性 API 变更，而是内部使用不同的后端上下文（WebGL）。如果你遇到问题，请在 rive-react 运行时的 issues 页面 提交。