跳到主要内容
中文系列课

Web（JS）

Rive 的 JavaScript / WASM 运行时。

概述​

本页介绍如何开始使用 Rive 的 Web 运行时库。该运行时是开源的，可在 GitHub 仓库 获取。

这个库同时提供：

  • 高级 JavaScript API（支持 TypeScript）
  • 低级 API（可自行加载 WebAssembly / WASM，并控制渲染循环）

它可以帮助你：

  • 快速把 Rive 集成到各类 Web 应用（Webflow、WordPress 等）
  • 作为基础层，封装成其它 Web 生态运行时（如 React、Svelte 等）
  • 通过自定义 render loop 支持高级场景（例如 Web 游戏引擎）

快速开始​

上述示例主要展示了几种 .riv 文件加载方式与 Rive 实例创建方式。

入门​

下面以 @rive-app/canvas 为例说明接入流程。

Rive 在 Web 端提供多种包（Canvas、WebGL、Lite 等）。

包选型可参考：Canvas vs WebGL

1) 安装依赖​

建议始终使用 最新版本。

方式 A：Script Tag​

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

如需固定版本（请先确认最新版本号）：

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

这种方式会暴露全局 rive 对象，可直接使用：

new rive.Rive({});

方式 B：包管理器​

npm install @rive-app/canvas
pnpm add @rive-app/canvas
yarn add @rive-app/canvas
bun add @rive-app/canvas

导入方式：

// 导入整个模块
import * as rive from '@rive-app/canvas';

// 或按需导入
import { Rive } from '@rive-app/canvas';

如果你不使用 Rive Text 与 Rive Audio，可以考虑更小体积的 @rive-app/canvas-lite。详见 Canvas vs WebGL。

2) 创建 Canvas​

在 HTML 中放置用于渲染的 <canvas>：

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

3) 创建 Rive 实例​

创建实例时常用参数：

  • src：.riv 文件 URL，或公开可访问的 .riv 静态资源路径
  • artboard：（可选）要显示的 Artboard 名称
  • stateMachines：要播放的状态机名称
  • canvas：渲染目标 canvas 元素
  • autoplay：是否自动播放
<script>
  const r = new rive.Rive({
    src: 'https://cdn.rive.app/animations/vehicles.riv',
    // 或公开静态资源路径
    // src: '/public/example.riv',
    canvas: document.getElementById('canvas'),
    autoplay: true,
    // artboard: 'Artboard', // 可选，不传则默认第一个
    stateMachines: 'bumpy',
    onLoad: () => {
      r.resizeDrawingSurfaceToCanvas();
    },
  });
</script>

关于 resizeDrawingSurfaceToCanvas​

resizeDrawingSurfaceToCanvas() 用于让内部绘制表面与 canvas 实际显示尺寸、设备像素比对齐，从而避免高 DPI 设备上的模糊问题。

建议：

  • 在 onLoad 中调用一次
  • 如果画布尺寸会变化（响应式布局、窗口缩放），在 resize 事件中再次调用
window.addEventListener('resize', () => {
  r.resizeDrawingSurfaceToCanvas();
});

完整示例​

<!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: 'Artboard',
        stateMachines: 'bumpy',
        onLoad: () => {
          r.resizeDrawingSurfaceToCanvas();
        },
      });
    </script>
  </body>
</html>

加载 .riv 文件的几种方式​

参考示例：CodeSandbox

  1. Hosted URL：通过 src 传入远程 URL
  2. 静态资源路径：通过 src 传入项目公开路径
  3. buffer：先 fetch，再把 ArrayBuffer 传给 buffer
  4. riveFile 复用：复用已加载的运行时文件对象，减少重复请求和解析

更多参数说明见：Rive Parameters

4) 清理实例​

当动画不再需要时，建议主动清理，避免内存泄漏（底层含 C++/WASM 资源）。

const riveInstance = new Rive({ ... });

// 不再使用时
riveInstance.cleanup();

运行时交互概念​

你可以继续深入这些主题：

  • 动画播放控制
  • 状态机输入
  • 事件回调与交互
  • 与滚动/鼠标/可见性联动

相关文档​

示例​