跳到主要内容

Rive 参数（Rive Parameters）

Rive 实例的 API 文档。

参数（Parameters）​

在实例化 Rive 对象时，您可以设置以下任何参数：

export interface RiveParameters {
  canvas: HTMLCanvasElement | OffscreenCanvas, // 必需
  src?: string, // src 或 buffer 必须提供一个
  buffer?: ArrayBuffer, // src 或 buffer 必须提供一个
  file?: rc.File,
  artboard?: string,
  animations?: string | string[],
  stateMachines?: string | string[],
  layout?: Layout,
  autoplay?: boolean,
  useOffscreenRenderer?: boolean,
  enableRiveAssetCDN?: boolean,
  shouldDisableRiveListeners?: boolean,
  isTouchScrollEnabled?: boolean,
  automaticallyHandleEvents?: boolean,
  onLoad?: EventCallback,
  onLoadError?: EventCallback,
  onPlay?: EventCallback,
  onPause?: EventCallback,
  onStop?: EventCallback,
  onLoop?: EventCallback,
  onStateChange?: EventCallback,
  onAdvance?: EventCallback,
  assetLoader?: AssetLoadCallback,
}

  • canvas - （必需） 用于绘制 Rive 动画的画布元素。

  • src? - （可选） 有两种可选的使用 src 的方式：通过 .riv 文件的 URL，或者指向公共 .riv 资源的路径。必须提供 src 或 buffer 其中之一。

    • URL - 如果您在某个公开访问的存储桶/CDN（如 AWS、GCS 等）上托管您的 .riv 文件，您可以在此处传入 URL。
    • 或者，使用 ES6，您可以将 .riv 文件作为数据 URI 导入。根据您的打包加载器，您可能需要使用插件（如 Webpack 的 url-loader）来正确解析和加载 .riv 文件作为数据 URI 字符串。参见此项目作为如何设置的基本示例。
    • 公共资源路径 - 这是指向应用程序中打包的 .riv 公共资源的字符串路径。注意，这不是从当前 JS 文件所在位置到资源的相对路径。将 .riv 文件视为应用程序中打包的任何其他资源，如图像或字体。如果您的 JS 在 web 应用程序的根目录下编译和运行，您必须从根目录指定到资源位置的路径。例如，如果您的资源在 public/foo.riv，并且您的 JS 从根目录运行，您应该在此属性中指定：src: 'public/foo.riv'。

  • buffer? - （可选） 包含 .riv 文件原始字节的 ArrayBuffer。必须提供 src 或 buffer 其中之一。

  • file? - （可选） 允许您重用先前加载的 Rive 运行时文件对象，无需再次从 src URL 获取或从 buffer 重新加载。这可以通过消除冗余的网络请求和加载时间来提高性能，特别是在从相同源创建多个 Rive 实例时。与 buffer 和 src 参数不同（它们仍需要在底层进行解析以创建运行时文件对象），file 参数使用已解析的对象，包括任何已加载的资源。

  • artboard? - （可选） 要使用的画板名称。

  • animations? - （可选） 要播放的动画名称或名称列表。

目前，如果未提供 stateMachines 或 animations 参数，Rive 将播放它找到的第一个时间轴动画，但是在 rive-wasm 的未来主要版本中，默认将播放它找到的第一个状态机。

  • stateMachines? - （可选） 要加载的状态机名称或名称列表。

注意：您应该只为 stateMachines 提供单个状态机字符串。同时运行同一画板的多个状态机可能会导致意外后果。

在 rive-wasm 的未来主要版本中，stateMachines 将是您传入的单个字符串。

  • layout? - （可选） 布局对象，用于定义动画如何在画布上显示。

  • autoplay? - （可选） 如果为 true，动画将在加载时自动开始播放。默认为 false。

  • useOffscreenRenderer? - （可选） 布尔标志，用于确定是否使用共享的离屏 WebGL 上下文，而不是为此 Rive 实例创建自己的 WebGL 上下文。这仅与 @rive-app/webgl 包相关。如果您要显示多个 Rive 动画，强烈建议将此标志设置为 true。默认为 false。

  • enableRiveAssetCDN? - （可选） 允许运行时自动加载托管在 Rive CDN 中的资源。默认启用。

  • shouldDisableRiveListeners? - （可选） 布尔标志，用于禁用在 <canvas> 元素上设置 Rive 监听器，从而防止在元素上设置任何事件监听器。

    • 注意： 如果没有正在播放的状态机，或者状态机上没有设置任何 Rive 监听器，则默认情况下不会在 <canvas> 元素上设置 Rive 监听器。

  • isTouchScrollEnabled? - （可选） 对于 Rive 监听器，允许在触控设备上执行触摸/拖动操作时保持画布元素的滚动行为。否则，默认情况下可能会在画布上的触摸/拖动操作中阻止滚动行为。

  • automaticallyHandleEvents? - （可选） 启用运行时处理 Rive 事件。这意味着任何特殊的 Rive 事件可能会隐式执行副作用。例如，如果在渲染循环期间检测到 OpenUrlEvent，浏览器可能会尝试打开负载中指定的 URL。此标志默认为 false 以防止任何不需要的行为发生。这意味着任何特殊的 Rive 事件都必须通过订阅 EventType.RiveEvent 手动处理。

  • onLoad? - （可选） .riv 文件加载时触发的回调。

  • onLoadError? - （可选） 加载 .riv 文件出错时触发的回调。

  • onPlay? - （可选） 动画开始播放时触发的回调。

  • onPause? - （可选） 动画暂停时触发的回调。

  • onStop? - （可选） 动画停止播放时触发的回调。

  • onLoop? - （可选） 动画完成一个循环时触发的回调。

  • onStateChange? - （可选） 状态改变发生时触发的回调。

  • onAdvance? - （可选） 画板前进每一帧时触发的回调。

  • assetLoader? - （可选） 对 Rive 文件中检测到的每个资源（无论是包含还是排除）调用的回调。回调会传入对 Rive FileAsset 的引用和文件的相关 bytes（如果资源嵌入在文件中）。在此回调中，您将决定是自己在应用程序中加载资源，还是让 Rive 为您加载。有关更多详细信息和示例，请参阅加载资源页面。

API​

实例化 Rive 后，可以使用以下 API：

play()​

play(names?: string | string[], autoplay?: true): void

通过传入的名称播放指定的线性时间轴动画或状态机。如果您以编程方式调用了 pause() 或 stop()，或在实例化 Rive 时设置了 autoplay: false，这很有用。如果未传入名称，它将播放所有已实例化的时间轴动画或状态机（或者如果两者都未实例化，则播放默认动画）。

示例：

import {Rive} from '@rive-app/canvas';

const riveInstance = new Rive({
  src: "https://cdn.rive.app/animations/vehicles.riv",
  autoplay: false,
  canvas: document.querySelector("canvas"),
});

const buttonEl = document.querySelector("button");
buttonEl.onclick = function() {
  // 播放 'bumpy' 状态机
  riveInstance.play("bumpy");
};

pause()​

pause(names?: string | string[]): void

通过传入的名称暂停指定的线性时间轴动画或状态机。当您想要以编程方式暂停正在播放的动画和渲染循环时很有用。如果相关的 Rive 实例的 <canvas> 元素滚动出屏幕，您可能也想使用此 API。如果未传入名称，它将暂停所有已实例化的时间轴动画或状态机。

示例：

import {Rive} from '@rive-app/canvas';

const riveInstance = new Rive({
  src: "https://cdn.rive.app/animations/vehicles.riv",
  autoplay: true,
  canvas: document.querySelector("canvas"),
});

const buttonEl = document.querySelector("button");
buttonEl.onclick = function() {
  // 暂停 'bumpy' 状态机
  riveInstance.pause("bumpy");
};

stop()​

stop(names?: string | string[]): void

通过传入的名称停止指定的线性时间轴动画或状态机。当您想要以编程方式停止正在播放的动画和渲染循环时很有用。如果相关的 Rive 实例的状态机处于"完成"状态或退出状态，您可能也想使用此 API。如果未传入名称，它将停止所有已实例化的时间轴动画或状态机。

示例：

import {Rive} from '@rive-app/canvas';

const riveInstance = new Rive({
  src: "https://cdn.rive.app/animations/vehicles.riv",
  autoplay: true,
  canvas: document.querySelector("canvas"),
});

const buttonEl = document.querySelector("button");
buttonEl.onclick = function() {
  // 停止 'bumpy' 状态机
  riveInstance.stop("bumpy");
};

reset()​

interface RiveResetParameters {
  artboard?: string;
  animations?: string | string[];
  stateMachines?: string | string[];
  autoplay?: boolean;
}

reset(params?: RiveResetParameters): void

根据传入的参数从起始位置（或入口状态）重置 Rive 画板、线性时间轴动画和/或状态机。隐式地，此方法还会在创建新实例之前清理任何已创建的现有实例（画板、动画和/或状态机）。根据传入的 autoplay 属性，实例化的时间轴动画或状态机将立即开始播放。

示例：

import {Rive} from '@rive-app/canvas';

const riveInstance = new Rive({
  src: "https://cdn.rive.app/animations/vehicles.riv",
  autoplay: true,
  canvas: document.querySelector("canvas"),
  stateMachines: "bumpy"
});

const buttonEl = document.querySelector("button");
buttonEl.onclick = function() {
  // 重置 Rive 实例到不同的状态机
  riveInstance.reset({
    stateMachines: "idle",
    autoplay: true
  });
};

on()​

on(event: EventType, callback: EventCallback): void

订阅 Rive 事件。可用的事件类型包括：

  • EventType.Load - 当 .riv 文件加载完成时触发
  • EventType.LoadError - 当加载 .riv 文件出错时触发
  • EventType.Play - 当动画开始播放时触发
  • EventType.Pause - 当动画暂停时触发
  • EventType.Stop - 当动画停止时触发
  • EventType.Loop - 当动画完成一个循环时触发
  • EventType.StateChange - 当状态改变时触发
  • EventType.Draw - 当画板绘制时触发
  • EventType.RiveEvent - 当触发 Rive 事件时触发

示例：

import { Rive, EventType } from '@rive-app/canvas';

const riveInstance = new Rive({
  src: "https://cdn.rive.app/animations/vehicles.riv",
  canvas: document.querySelector("canvas"),
  autoplay: true,
});

// 监听加载事件
riveInstance.on(EventType.Load, () => {
  console.log('Rive 文件已加载');
});

// 监听播放事件
riveInstance.on(EventType.Play, () => {
  console.log('动画开始播放');
});

off()​

off(event: EventType, callback: EventCallback): void

取消订阅特定的 Rive 事件。

示例：

import { Rive, EventType } from '@rive-app/canvas';

const riveInstance = new Rive({
  src: "https://cdn.rive.app/animations/vehicles.riv",
  canvas: document.querySelector("canvas"),
  autoplay: true,
});

// 创建事件处理函数
const handleLoad = () => {
  console.log('Rive 文件已加载');
};

// 订阅事件
riveInstance.on(EventType.Load, handleLoad);

// 取消订阅事件
riveInstance.off(EventType.Load, handleLoad);

removeAllEventListeners()​

removeAllEventListeners(): void

移除所有事件监听器。

scrub()​

scrub(animationName: string, value: number): void

手动设置动画的进度。value 参数应该是一个介于 0 和 1 之间的数字，表示动画的完成百分比。

示例：

import { Rive } from '@rive-app/canvas';

const riveInstance = new Rive({
  src: "https://cdn.rive.app/animations/vehicles.riv",
  canvas: document.querySelector("canvas"),
  animations: "idle"
});

// 将动画设置到 50% 的进度
riveInstance.scrub("idle", 0.5);

cleanup()​

cleanup(): void

清理 Rive 实例并释放所有资源。这将停止渲染循环并清理所有相关的 WASM 对象。

cleanupInstances()​

cleanupInstances(): void

清理所有 Rive 实例（画板、动画和状态机），但保持 Rive 对象本身完好无损。这在您想要重置 Rive 实例但不想完全销毁它时很有用。

load()​

load(params: RiveParameters): void

使用新的参数重新加载 Rive 实例。这在您想要更改 Rive 实例的配置时很有用。

示例：

import { Rive } from '@rive-app/canvas';

const riveInstance = new Rive({
  src: "https://cdn.rive.app/animations/vehicles.riv",
  canvas: document.querySelector("canvas"),
  autoplay: true,
});

// 稍后重新加载不同的动画
riveInstance.load({
  src: "https://cdn.rive.app/animations/other_animation.riv",
  canvas: document.querySelector("canvas"),
  autoplay: true,
});

resizeToCanvas()​

resizeToCanvas(): void

调整 Rive 实例的大小以匹配画布的尺寸。这在画布大小改变时很有用。

resizeDrawingSurfaceToCanvas()​

resizeDrawingSurfaceToCanvas(): void

调整绘图表面的大小以匹配画布的尺寸。这在处理高 DPI 显示器时特别有用，因为它会考虑设备的像素比。

stateMachineInputs()​

stateMachineInputs(stateMachineName: string): StateMachineInput[]

获取指定状态机的所有输入。这在您需要与状态机的输入进行交互时很有用。

示例：

const riveInstance = new Rive({
  src: 'https://cdn.rive.app/animations/vehicles.riv',
  canvas: document.getElementById('canvas'),
  autoplay: true,
  stateMachines: 'bumpy',
  onLoad: () => {  
    // 通过状态机名称获取输入
    const inputs = riveInstance.stateMachineInputs('bumpy');
    // 找到您想要设置值或触发的输入
    const bumpTrigger = inputs.find(i => i.name === 'bump');
    button.onclick = () => bumpTrigger.fire();
  },
});

stopRendering()​

stopRendering(): void

停止渲染循环。这在您想要暂时停止动画渲染但保持 Rive 实例状态时很有用。

startRendering()​

startRendering(): void

启动渲染循环（如果之前已停止）。如果渲染循环已经在运行，则不会产生任何效果。

getTextRunValue()​

getTextRunValue(textRunName: string): string | undefined

返回您想要检索的文本运行组件（来自 .riv 文件的层级结构）的文本值。如果无法从活动画板查询文本运行，则返回 undefined（在这种情况下，您可能会看到控制台警告以获取更多指导）。

setTextRunValue()​

setTextRunValue(textRunName: string, textValue: string): void

设置您通过 textRunName 指定的文本运行组件（来自 .riv 文件的层级结构）的文本值。如果无法从活动画板查询文本运行，您可能会看到控制台警告，因此您想要在运行上设置的 textValue 可能不会成功。

resolveAnimationFrame()​

resolveAnimationFrame(): void

只有在使用 Rive 的低级 API手动构建渲染循环并将 Rive 集成到现有的 requestAnimationFrame() 循环中时，才需要使用此函数。

解析渲染器的延迟绘制命令。如果您决定使用自己的 requestAnimationFrame() 循环并在其中添加 Rive 图形，则必须在渲染循环结束时调用此方法。否则，如果您使用 Rive 的包装 rAF 循环（即 rive.requestAnimatimationFrame()），则不需要调用此方法，因为 Rive 会处理与 Rive 图形相关的任何渲染调用的解析。

参见以下示例用法：

let lastTime = 0;
function draw(time) {
  if (!lastTime) {
    lastTime = time;
  }
  const elapsedMs = time - lastTime;
  const elapsedSeconds = elapsedMs / 1000;
  lastTime = time;

  renderer.clear();
  
  if (artboard) {
    if (stateMachine) {
      stateMachine.advance(elapsedSeconds);
    }
    if (animation) {
      animation.advance(elapsedSeconds);
      animation.apply(1);
    }
    artboard.advance(elapsedSeconds);
    renderer.save();

    renderer.align(
      rive.Fit.contain,
      rive.Alignment.center,
      {
        minX: 0,
        minY: 0,
        maxX: canvas.width,
        maxY: canvas.height,
      },
      artboard.bounds
    );

    // 将我们的渲染器传递给画板，以便它可以绘制到画布上
    artboard.draw(renderer);
    renderer.restore();
    renderer.flush();
  }

  // 需要实际解析与我们的渲染器的绘制和渲染调用队列
  // 注意：仅在使用普通的 JS requestAnimationFrame 而不是我们包装的
  // rive API 中的 rAF 时才需要
  rive.resolveAnimationFrame();

  // 调用下一帧！
  requestAnimationFrame(draw);
}
// 启动动画循环
requestAnimationFrame(draw);

调试工具（Debugging Tools）​

contents​

与其他需要作为方法在 Rive 实例上调用的 API 不同，contents 是 Rive 实例上的一个属性，您可以将其记录到控制台以查看从 Rive 文件加载的对象层次结构。这对于查看加载了哪个 Rive 文件、与文件关联的所有画板、动画和状态机、状态机输入等很有用。如果您无法直接在 Rive 编辑器中检查文件，这也很有用。

示例：

const riveInstance = new rive.Rive({
  src: 'https://cdn.rive.app/animations/vehicles.riv',
  canvas: document.getElementById('canvas'),
  autoplay: true,
  stateMachines: 'bumpy',
  onLoad: () => {  
    // 记录 Rive 文件的内容
    console.log(riveInstance.contents);
  },
});

enableFPSCounter()​

type FPSCallback = (fps: number) => void;

enableFPSCounter(fpsCallback?: FPSCallback): void

报告运行时的每秒帧数（FPS）。您可以提供一个回调来处理如何显示或摄取数据，或者如果您不提供回调，调用此 API 将在页面右上角附加一个固定位置的 <div>，显示 FPS。在 onLoad 回调中或其他时间点在 Rive 初始化后调用此方法。

disableFPSCounter()​

disableFPSCounter(): void

禁用运行时的 FPS 报告。

其他（Other）​

提供了其他 API 和属性来报告 Rive 实例中的播放/暂停/停止实体。

source​

获取 Rive 实例中的 src 属性

activeArtboard​

获取活动画板的名称

animationNames​

获取加载的画板上所有动画名称的数组（即使这些动画在实例化时未指定）

stateMachineNames​

获取加载的画板上所有状态机名称的数组（即使这些状态机在实例化时未指定）

playingAnimationNames​

获取 Rive 实例上所有当前正在播放的时间轴动画名称的数组（如果您正在播放状态机，这不会返回当前活动的状态时间轴动画）

playingStateMachineNames​

获取 Rive 实例上所有当前正在播放的状态机名称的数组

pausedAnimationNames​

获取 Rive 实例上所有当前已暂停的时间轴动画名称的数组（如果您正在播放状态机，这不会返回当前活动的状态时间轴动画）

pausedStateMachineNames​

获取 Rive 实例上所有当前已暂停的状态机名称的数组

isPlaying​

如果有任何动画正在播放，则返回 true

isPaused​

如果所有已实例化的动画都已暂停，则返回 true

isStopped​

如果没有已实例化的动画正在播放或暂停，则返回 true

bounds​

返回画板的边界

layout (get/set)​

获取或设置 Rive Layout

示例：

import {Rive, Layout, Fit, Alignment} from '@rive-app/canvas';

const riveInstance = new rive.Rive({
  src: 'https://cdn.rive.app/animations/vehicles.riv',
  canvas: document.getElementById('canvas'),
  autoplay: true,
  stateMachines: 'bumpy',
});

const buttonEl = document.querySelector("button");
buttonEl.onclick = function() {
  // 设置新的布局
  riveInstance.layout = new Layout({
    fit: Fit.Cover,
    alignment: Alignment.TopCenter,
  });
};