快速开始

概述

本指南介绍如何开始使用 Rive Web 运行时库。该运行时是开源的，可在这个 GitHub 仓库中获取。此库提供高级 JavaScript API（支持 TypeScript），也提供低级 API，可用于加载 Web Assembly（WASM）并自行控制渲染循环。此运行时允许你：

• 将 Rive 快速集成到所有 Web 应用中（Webflow、WordPress 等）
• 提供基础 API，用于构建其他基于 Web 的 Rive 运行时封装（React、Svelte 等）
• 通过控制渲染循环来支持高级用例（基于 Web 的游戏引擎）

快速开始

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

这些说明使用 @rive-app/webgl2，这是我们推荐用于大多数项目的包。它使用 Rive 渲染器绘制，与 Rive 编辑器使用的渲染器相同，因此支持你在 Rive 中创作的所有内容，包括矢量羽化。Rive 还发布具有不同权衡的 Canvas2D 包 —— 请参阅 Canvas 与 WebGL2。这些包共享相同的 API 表面，因此如有需要，你可以轻松切换到不同的包。

1. 安装依赖
   
   💡

   我们建议尽可能始终使用最新版本。

   📌 Script Tag

   （推荐）加载最新版本的 Web 运行时

   将以下 script 标签添加到你的网页中，以加载最新版本的 Web 运行时：

   <script src="https://unpkg.com/@rive-app/webgl2@latest"></script>

   加载固定版本的 Web 运行时

   也可以固定到某个特定版本，以便更精细地控制应用中加载的内容。随着 Rive 功能集不断扩展，你需要手动将此版本更新到较新的版本，以确保最佳兼容性。

   <script src="https://unpkg.com/@rive-app/[email protected]"></script>

   这会提供一个全局 rive 对象，让你可以通过 rive 入口访问 Rive API。继续按照下面的步骤操作。

   📌 Package Manager

   npm install @rive-app/webgl2

   pnpm add @rive-app/webgl2

   yarn add @rive-app/webgl2

   bun add @rive-app/webgl2

   // Import the entire module under the global identifier `rive`
   import * as rive from "@rive-app/webgl2";
   
   // Alternatively, import only the specific parts you need
   import { Rive } from "@rive-app/webgl2";

   💡

   没有使用 Rive Text、Rive Layouts、Rive Scripting 或 Rive Audio？可以考虑改用 @rive-app/canvas-lite，这是 Canvas 运行时的更小包变体。

2. 创建 Canvas
   

   在 HTML 中添加一个 canvas 元素，用于显示 Rive 图形：

   <canvas id="canvas" width="500" height="500"></canvas>

3. 创建 Rive 实例
   

   要创建新的 Rive 对象实例，请提供以下属性：

   • src：表示托管 .riv 文件 URL 的字符串（如下方示例所示），或公共资源 .riv 文件的路径。有关如何正确使用此属性的更多详情，请参阅 Rive 参数。
   • artboard -（可选）表示要显示的 artboard 的字符串。如果未提供，则会选择 .riv 文件中的默认 artboard。
   • stateMachine - 表示你希望播放的 state machine 名称的字符串。必须提供此项，否则 Rive 实例可能只会播放它找到的第一个线性动画。在下一个主版本中，默认行为将改为在存在默认状态机时播放画板的默认状态机。
   • canvas - 用于渲染动画的 canvas 元素。
   • autoplay - 表示动画是否应自动播放的布尔值。
   • autoBind - 表示在找到默认 ViewModelInstance 时是否自动进行数据绑定的布尔值。我们建议将其设置为 true。

   <script>
       const r = new rive.Rive({
           src: "https://cdn.rive.app/animations/vehicles.riv",
           // OR the path to a discoverable and public Rive asset
           // src: '/public/example.riv',
           canvas: document.getElementById("canvas"),
           autoplay: true,
           autoBind: true,
           // artboard: "Artboard", // Optional. If not supplied the default is selected
           stateMachine: "bumpy",
           onLoad: () => {
             r.resizeDrawingSurfaceToCanvas();
           },
       });
   </script>

   resizeDrawingSurfaceToCanvas 方法可确保 Rive 动画被正确缩放，以适配指定 canvas 元素的尺寸。默认情况下，canvas 的渲染表面可能并不与 HTML 中定义的 <canvas> 元素实际大小完全匹配，这可能导致图形模糊或缩放不正确，尤其是在高 DPI 或 Retina 显示屏上。

   调用此方法会调整内部绘图表面，使动画以清晰细节进行渲染，并匹配 canvas 的像素密度。在以下情况下尤其重要：

   • canvas 的大小会动态变化（例如，由于响应式布局而调整大小）。
   • 你希望确保动画在任何设备或屏幕分辨率下都保持清晰。

   最佳实践：

   • 加载后调用：建议在 onLoad 回调中调用 resizeDrawingSurfaceToCanvas，以确保 Rive 资源已完全加载后再调整绘图表面。这可以避免渲染问题。

   • 处理窗口大小变化：如果 canvas 的尺寸会在用户交互过程中发生变化（例如调整浏览器窗口大小），你还应监听 window resize 事件，并调用 resizeDrawingSurfaceToCanvas 来重新调整渲染表面：

     window.addEventListener("resize", () => {
         r.resizeDrawingSurfaceToCanvas();
     });

     这样，当 canvas 尺寸发生变化时，Rive 动画仍会保持清晰并正确缩放。

完整示例

把上述内容组合起来，下面演示如何在单个 HTML 文件中加载 Rive 图形。

<!DOCTYPE html>
<html lang="en">
  <head>
    <meta charset="UTF-8" />
    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
    <title>Rive Hello World</title>
  </head>
  <body>
    <canvas id="canvas" width="500" height="500"></canvas>

    <script src="https://unpkg.com/@rive-app/[email protected]"></script>
    <script>
      const r = new rive.Rive({
        src: "https://cdn.rive.app/animations/vehicles.riv",
        canvas: document.getElementById("canvas"),
        autoplay: true,
        autoBind: true,
        // artboard: "Artboard", // Optional. If not supplied the default is selected
        stateMachine: "bumpy",
        onLoad: () => {
          // Ensure the drawing surface matches the canvas size and device pixel ratio
          r.resizeDrawingSurfaceToCanvas();
        },
      });
    </script>
  </body>
</html>

加载 Rive 文件

请参阅此示例，了解加载 .riv 文件的不同方式，可选方式包括：

1. 托管 URL：使用表示 .riv 文件托管地址的字符串。在创建新的 Rive 实例时，将其设置为 src 属性。
2. bundle 中的静态资源：提供一个字符串，指向 Web 项目中可公开访问的 .riv 文件路径。像处理项目中的其他静态资源（例如图片或字体）一样处理 .riv 文件。
3. 获取文件：不使用 src 属性，而是在 fetch 文件时使用 buffer 属性加载 ArrayBuffer。当多个 Rive 实例复用同一个 .riv 文件时，这非常有用，因为你只需加载一次该文件。
4. 复用已加载文件：使用 riveFile 参数复用之前已加载的 Rive 运行时文件对象，避免再次通过 src URL 获取或从 buffer 重新加载。这可以显著提升性能，消除重复的网络请求和加载时间，尤其适用于从同一来源创建多个 Rive 实例的场景。与 src 和 buffer 参数不同，后两者需要在底层解析以创建运行时文件对象；riveFile 参数会使用已解析的对象，包括其中已加载的所有资源。请参阅缓存 Rive 文件。

有关更多详情，请参阅 Rive 参数中关于 src 属性的部分。

清理 Rive

使用 Rive 实例时，在不再需要它时正确清理非常重要。以下场景尤其需要这样做：

• 包含 Rive 动画的 UI 不再需要（例如，带有 Rive 图形的模态框被关闭时）。
• 动画或 state machine 已完成，且不会再次显示或运行。

在底层，Rive 会在 C++ 中创建各种低级对象（例如 artboard 实例、animation 实例和 state machine 实例），这些对象需要手动删除以防止内存泄漏。如果不进行清理，这些对象会消耗不必要的资源，并可能影响应用性能。

幸运的是，高级 JavaScript API 简化了这个过程。你不需要跟踪 Rive 实例生命周期中创建的每一个对象。相反，你可以通过一次方法调用清理所有相关对象。

要清理 Rive 实例并释放资源，请在你的 Rive 实例上调用以下方法：

const riveInstance = new Rive({...});
...
// When ready to cleanup
riveInstance.cleanup();

其他 Rive Web 资源

更深入的 Rive Web 文档与高级用例。

Rive 参数

Rive 实例的 API 文档。

Canvas 与 WebGL2

Rive Web 不同包的指南。

常见问题

常见问题。

预加载 WASM

关于如何预加载并自行托管 Rive WASM 库的说明。

低级 API 用法

控制 Rive 渲染循环和布局，并将多个 artboard 绘制到同一个 canvas 上。

示例

• 基础 gallery 应用
• 跟踪鼠标光标
• 连接到页面滚动
• 仅当滚动进入用户视口时播放 state machine