跳到主要内容
中文系列课

入门指南

⚠️ 注意：某些 Rive 功能可能尚未被特定运行时支持，或者需要使用 Rive 渲染器。详情请参考功能支持和选择渲染器页面。

概述​

本指南介绍如何使用 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 提供 WebGL2、Canvas 和 Lite 版本等 Web 包。请参考 Canvas vs WebGL2 来选择适合你的用例的包。

安装依赖​

⚠️ 我们建议始终使用最新版本。下面列出版本号和示例中的版本可能与最新版本不同。

Script 标签​

// 将以下 script 标签添加到你的网页中以获取最新版本：

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

// 你也可以固定到特定版本（最新版本请查看 [这里](https://www.npmjs.com/package/@rive-app/webgl2)）：

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

// 这样会提供一个全局的 `rive` 对象，允许你通过 `rive` 入口点访问 Rive API：

new rive.Rive({});

包管理器​

npm install @rive-app/webgl2
pnpm add @rive-app/webgl2
yarn add @rive-app/webgl2
bun add @rive-app/webgl2
// 在全局标识符 `rive` 下导入整个模块
import * as rive from "@rive-app/webgl2";

// 或者，只导入你需要的特定部分
import { Rive } from "@rive-app/webgl2";

如果你没有使用 Rive 文本、Rive 布局、Rive 脚本 或 Rive 音频，可以考虑使用 @rive-app/canvas-lite，这是 Canvas 运行时的一个较小包变体。

创建 Canvas​

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

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

创建 Rive 实例​

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

  • src：表示托管的 .riv 文件的 URL 字符串（如以下示例所示），或公共资源 .riv 文件的路径。有关如何正确使用此属性的更多详细信息，请参考 Rive 参数。
  • artboard：（可选）表示要显示的画板的字符串。如果未提供，则从 .riv 文件中选择默认画板。
  • stateMachines：表示要播放的状态机名称的字符串。必须提供此项，否则 Rive 实例可能只播放它找到的第一个线性动画。在下一个大版本中，默认行为将是播放画板的默认状态机。
  • canvas：渲染动画的 canvas 元素。
  • autoplay：布尔值，指示动画是否应自动播放。
  • autoBind：布尔值，指示是否自动绑定默认的 ViewModelInstance（如果存在）。
<script>
    const r = new rive.Rive({
        src: "https://cdn.rive.app/animations/vehicles.riv",
        // 或者指向可发现和公开 Rive 资源的路径
        // src: '/public/example.riv',
        canvas: document.getElementById("canvas"),
        autoplay: true,
        autoBind: true,
        // artboard: "Artboard", // 可选。如果不提供则选择默认画板
        stateMachines: "bumpy",
        onLoad: () => {
          r.resizeDrawingSurfaceToCanvas();
        },
    });
</script>

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

调用此方法会调整内部绘制表面，使动画以清晰的细节渲染，匹配 canvas 的像素密度。这在以下情况下特别重要：

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

最佳实践：

  • 加载后调用：建议在 onLoad 回调中调用 resizeDrawingSurfaceToCanvas，以确保 Rive 资源已完全加载后再调整绘制表面，防止渲染问题。
  • 处理窗口大小调整：如果 canvas 大小在用户交互期间发生变化（例如调整浏览器窗口大小时），你还应该监听窗口调整事件并调用 resizeDrawingSurfaceToCanvas 重新调整渲染表面：
window.addEventListener("resize", () => {
    r.resizeDrawingSurfaceToCanvas();
});

这样，Rive 动画将在 canvas 大小变化时继续保持清晰和正确缩放。

完整示例​

将它们组合在一起，以下是如何在单个 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/webgl2"></script>
    <script>
      const r = new rive.Rive({
        src: "https://cdn.rive.app/animations/vehicles.riv",
        canvas: document.getElementById("canvas"),
        autoplay: true,
        // artboard: "Arboard", // 可选。如果不提供则选择默认画板
        stateMachines: "bumpy",
        onLoad: () => {
          // 确保绘制表面匹配 canvas 大小和设备像素比
          r.resizeDrawingSurfaceToCanvas();
        },
      });
    </script>
  </body>
</html>

加载 Rive 文件​

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

  1. 托管 URL：使用表示 .riv 文件托管位置的 URL 字符串。在创建新 Rive 实例时将其设置为 src 属性。
  2. 打包中的静态资源：提供指向 Web 项目中可公开访问的 .riv 文件路径的字符串。像处理项目中的任何其他静态资源（例如图片或字体）一样处理 .riv 文件。
  3. 获取文件：不使用 src 属性，而是在获取文件时使用 buffer 属性加载 ArrayBuffer。这在多个 Rive 实例间重用同一 .riv 文件时很有用，只需加载一次。
  4. 重用已加载的文件：使用 riveFile 参数重用先前加载的 Rive 运行时文件对象，避免通过 src URL 重新获取或从 buffer 重新加载。这可以显著提高性能，消除冗余的网络请求和加载时间，特别是在从同一源创建多个 Rive 实例时。与 src 和 buffer 参数需要在底层解析以创建运行时文件对象不同，riveFile 参数使用已解析的对象，包括任何已加载的资源。参见缓存 Rive 文件。

更多详情，请参考 Rive 参数部分中关于 src 属性的说明。

清理 Rive​

使用 Rive 实例时，当不再需要时正确清理非常重要。在以下情况下尤其必要：

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

在底层，Rive 会在 C++ 中创建各种低级对象（如画板实例、动画实例和状态机实例），这些对象需要手动删除以防止内存泄漏。如果未清理，这些对象可能会消耗不必要的资源，可能影响应用程序的性能。

幸运的是，高级 JavaScript API 简化了此过程。你无需跟踪 Rive 实例生命周期中创建的每个对象。只需在 Rive 实例上调用一个方法即可清理所有关联对象。

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

const riveInstance = new Rive({...));
...
// 准备好清理时
riveInstance.cleanup();

更多 Rive Web 资源

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

示例