跳到主要内容

Web (JS)

Rive 的 JavaScript/WASM 运行时。

概述（Overview）​

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

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

快速开始（Quick Start）​

查看我们的快速开始示例。

此示例仅演示了以各种方式加载 .riv 文件资源和创建 Rive 实例。其他部分详细介绍了更高级的用例。

Codesandbox

入门指南（Getting Started）​

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

以下说明描述了使用 @rive-app/canvas 包。Rive 提供了基于 web 的包，如 WebGL、Canvas 和 Lite 版本。

查看本节以了解哪个包最适合您的用例。

1. 安装依赖（Install the dependency）​

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

脚本标签（Script Tag）​

将以下脚本标签添加到您的网页以获取最新版本：

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

您也可以固定到特定版本（查看这里获取最新版本）：

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

这将使全局 rive 对象可用，允许您通过 rive 入口点访问 Rive API：

new rive.Rive({});

包管理器（Package Managers）​

1. npm​

npm install @rive-app/canvas

2. pnpm​

pnpm add @rive-app/canvas

3. yarn​

yarn add @rive-app/canvas

4. bun​

bun add @rive-app/canvas

导入（Importing）​

// 将整个模块导入到全局标识符 `rive` 下
import * as rive from "@rive-app/canvas";

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

没有使用 Rive 文本和 Rive 音频？考虑使用 @rive-app/canvas-lite，这是一个更小的包变体。

2. 创建画布（Create a Canvas）​

在您的 HTML 中添加一个画布元素，用于显示 Rive 图形：

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

3. 创建 Rive 实例（Create a Rive instance）​

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

  • src：表示托管的 .riv 文件 URL 的字符串（如下例所示）或公共资源 .riv 文件的路径。有关如何正确使用此属性的更多详细信息，请参阅 Rive 参数。
  • artboard：（可选）表示您想要显示的画板的字符串。如果未提供，则选择默认画板。
  • stateMachines：表示您想要播放的状态机名称的字符串。
  • canvas：动画将在其中渲染的画布元素。
  • autoplay：布尔值，指示动画是否应自动播放。
<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,
        // artboard: "Arboard", // 可选。如果未提供则选择默认画板
        stateMachines: "bumpy",
        onLoad: () => {
          r.resizeDrawingSurfaceToCanvas();
        },
    });
</script>

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

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

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

最佳实践：

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

这样，当画布大小改变时，Rive 动画将继续保持清晰和正确的缩放。

完整示例（Complete example）​

将所有内容整合在一起，以下是在单个 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/canvas"></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: () => {
          // 确保绘图表面匹配画布大小和设备像素比
          r.resizeDrawingSurfaceToCanvas();
        },
      });
    </script>
  </body>
</html>

加载 Rive 文件（Loading Rive files）​

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

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

有关更多详细信息，请参阅 Rive 参数部分中关于 src 属性的说明。

其他 Rive web 资源（Additional Rive web resources）​

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

示例（Examples）​