跳到主要内容
中文系列课

Rive Parameters

本页是高级 Rive 类的构造函数选项、类型和实例方法，以及若干其他导出类的参考。如需演练和示例，请使用下面的指南；当你需要精确签名时，再链接回本页。

相关指南

  • 入门 — 从这里开始，了解如何将 Rive 加载到你的 Web 应用中
  • Artboards — 选择要从 .riv 文件加载的 artboard
  • Layout — 了解如何在 canvas 中布局 Rive 图形，并让它响应尺寸变化
  • State machine playback — 处理 Rive 状态机的播放控制
  • Loading assets — 处理 Rive 文件的资源加载
  • Caching a Rive file — RiveFile + riveFile，用于多个实例
  • Data binding — autoBind、view model、bindViewModelInstance
  • Playing audio — 处理音频资源并控制音量级别

Rive 构造函数参数​

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

export interface RiveParameters {
  canvas: HTMLCanvasElement | OffscreenCanvas; // required
  src?: string; // one of src, buffer, or riveFile is required
  buffer?: ArrayBuffer; // one of src, buffer, or riveFile is required
  riveFile?: RiveFile; // one of src, buffer, or riveFile is required
  artboard?: string;
  stateMachines?: string | string[]; // strongly recommended setting this property
  layout?: Layout;
  autoplay?: boolean;
  autoBind?: boolean;
  useOffscreenRenderer?: boolean;
  enableRiveAssetCDN?: boolean;
  shouldDisableRiveListeners?: boolean;
  isTouchScrollEnabled?: boolean;
  automaticallyHandleEvents?: boolean;
  dispatchPointerExit?: boolean;
  enableMultiTouch?: boolean;
  drawingOptions?: DrawOptimizationOptions;
  onLoad?: EventCallback;
  onLoadError?: EventCallback;
  onPlay?: EventCallback;
  onPause?: EventCallback;
  onStop?: EventCallback;
  onLoop?: EventCallback;
  onStateChange?: EventCallback;
  onAdvance?: EventCallback;
  assetLoader?: AssetLoadCallback;
  enablePerfMarks?: boolean;
  tabIndex?: number;
  focusOptions?: RiveFocusOptions;

  // Deprecated parameters
  animations?: string | string[]; // deprecated in favor of stateMachines
}
  • canvas - （必需） 提供一个用于绘制 Rive 动画的 <canvas> 元素。
  • 要加载 .riv 文件，必须提供以下其中一项：
    • src - （可选） 指向 .riv 文件的托管 URL 或应用相对的公共路径。最小示例请参阅入门指南。
    • buffer - （可选） .riv 字节的 ArrayBuffer。
    • riveFile - （可选） 提供一个可跨实例复用的已加载 RiveFile。更多详情请参阅 Caching a Rive file。
  • artboard - （可选） 要使用的 artboard 名称。如果未提供，将从导出的 .riv 文件中获取默认 artboard。
  • stateMachines - （强烈建议） 要从 .riv 文件加载的状态机名称（例如 "State Machine 1"）。如果未提供，目前 Rive 会获取它找到的第一个线性动画（已弃用的行为）。在运行时的下一个主要版本中，Rive 将默认获取 artboard 上的默认状态机。

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

  • layout - （可选） 提供一个 new Layout() 实例。有关适配模式、对齐、边界和响应式布局，请参阅该指南。
  • autoplay - （可选） 如果为 true，动画将在加载后自动开始播放。默认为 false。
  • autoBind - （可选） 设置为 true 时，Rive 会自动查找默认 view model 和 view model instance，并将其绑定到 artboard。默认为 false。
  • useOffscreenRenderer - （可选） 布尔标志，用于确定是否使用共享的离屏 WebGL2 上下文，而不是为此 Rive 实例创建自己的 WebGL2 上下文。这仅与基于 WebGL 的运行时相关，例如 @rive-app/webgl2。如果你在一个页面上显示多个 Rive 实例，强烈建议将此标志设置为 true。默认为 false。
  • enableRiveAssetCDN - （可选） 允许运行时自动加载托管在 Rive CDN 中的资源（例如字体）。默认为 true。
  • shouldDisableRiveListeners - （可选） 布尔标志，用于禁止在 <canvas> 元素上设置 Rive Listeners，从而阻止在该元素上设置任何事件监听器。
    • 注意： 默认情况下，如果没有正在播放的状态机，或者状态机上没有设置任何 Rive Listeners，则不会在 <canvas> 元素上设置 Rive Listeners。
  • isTouchScrollEnabled - （可选） 对于 Rive Listeners，允许在支持触摸的设备上对 canvas 元素执行触摸/拖拽操作时仍然发生滚动行为。否则，默认情况下，在 canvas 上执行触摸/拖拽操作时，滚动行为可能会被阻止。
  • automaticallyHandleEvents - （可选） 启用由运行时处理 Rive Events。这意味着任何特殊的 Rive Event 都可能隐式地产生副作用。例如，如果在渲染循环期间检测到 OpenUrlEvent，浏览器可能会尝试打开 payload 中指定的 URL。此标志默认为 false，以防止发生任何非预期行为。这意味着任何特殊的 Rive Event 都必须通过订阅 EventType.RiveEvent 手动处理。
  • dispatchPointerExit - （可选） 对于 Rive Listeners，当指针离开 canvas 时分发 pointer exit 事件。这有助于确保当用户光标离开 canvas 区域时，hover 状态能够正确重置。默认为 true。
  • enableMultiTouch - （可选） 为 Rive Listeners 启用多点触控支持。启用后，运行时会在支持触摸的设备上跟踪并响应多个同时发生的触摸点。默认为 false。
  • drawingOptions - （可选） 一个枚举（DrawOptimizationOptions），提供绘制优化选项。可用于配置渲染性能优化。默认值为 DrawOptimizationOptions.DrawOnChanged，仅当 artboard 发生视觉更新时才会提交绘制命令。
    • DrawOptimizationOptions.DrawOnChanged - 仅当 artboard 发生视觉更新时提交绘制命令
    • DrawOptimizationOptions.AlwaysDraw - 始终提交绘制命令，即使 artboard 没有发生视觉更新。
  • onLoad - （可选） 当 .riv 文件加载完成时触发的回调。
  • onLoadError - （可选） 当加载 .riv 文件时发生错误时触发的回调。
  • onPlay - （可选） 当动画开始播放时触发的回调。
  • onPause - （可选） 当动画暂停时触发的回调。
  • onStop - （可选） 当动画停止时触发的回调。
  • onLoop - （可选） 当动画完成一次循环时触发的回调。
  • onStateChange - （可选） 当发生状态变化时触发的回调。
  • onAdvance - （可选） 当 Artboard 在每一帧推进时触发的回调。
  • assetLoader - （可选） 用于加载资源的回调。完整模式和示例请见 loading assets 指南。
  • enablePerfMarks - （可选） 为关键 Rive 启动和渲染事件发出 performance.mark / performance.measure 条目，用于性能分析。默认为 false。也可在 RuntimeLoader 和 RiveFile 上使用。
  • tabIndex - （可选） canvas 元素的 tab index。用于为焦点管理指定 tab index。或者，你也可以直接在 <canvas> 上设置 tabindex 属性。
  • focusOptions - （可选） 焦点管理选项。
    • allowFocusInterrupt - （可选） 如果 Rive 内部检测到焦点变化，则允许中断浏览器焦点并将焦点设置到 Rive canvas 上。默认为 false。

已弃用参数​

  • animations - （可选） 已弃用，请改用 stateMachines。要从 .riv 文件加载的单个时间线动画名称。如果未提供，Rive 将获取它找到的第一个线性动画。在运行时的下一个主要版本中，Rive 将默认获取 artboard 上的默认状态机。

APIs​

构造完成后，Rive 实例上可使用以下 API。

数据绑定（View Models）​

Rive 上的 view model API 在数据绑定指南中有深入说明。有关 Rive 实例上可用 API 的快速参考，请见下文：

  • viewModelInstance（getter）— 当前绑定的实例（如果有）。当 autoBind 为 true 且存在可引用的默认 View Model instance 时，此属性可用。通过实例，你可以根据类型获取 view model 属性的引用：
    • .number(path: string): ViewModelInstanceNumber
    • .boolean(path: string): ViewModelInstanceBoolean
    • .string(path: string): ViewModelInstanceString
    • .color(path: string): ViewModelInstanceColor
    • .trigger(path: string): ViewModelInstanceTrigger
    • .enum(path: string): ViewModelInstanceEnum
    • .list(path: string): ViewModelInstanceList
    • .image(path: string): ViewModelInstanceAssetImage
    • .font(path: string): ViewModelInstanceAssetFont
    • .artboard(path: string): ViewModelInstanceArtboard
    • .viewModel(path: string): ViewModelInstance
    • .viewModelName - Getter 属性，用于返回创建该实例所基于的 ViewModel 的名称
    • .properties - Getter 属性，用于返回此 ViewModel 上可用的属性列表
  • viewModelCount（getter）
  • viewModelByIndex(index: number): ViewModel | null - 返回 .riv 文件中由索引指定的 ViewModel；如果不存在或文件尚未加载，则返回 null
  • viewModelByName(name: string): ViewModel | null - 返回由名称指定的 ViewModel；如果不存在或文件尚未加载，则返回 null
  • defaultViewModel(): ViewModel | null - 返回文件的默认 ViewModel；如果不存在或文件尚未加载，则返回 null
  • bindViewModelInstance(instance: ViewModelInstance | null): void - 设置并绑定主 ViewModelInstance 到状态机。请注意，如果 autoBind 为 true，这会自动完成。
  • setViewModelInstance(instance: ViewModelInstance | null): void - 设置主 ViewModelInstance 到状态机，但不绑定。调用 bind() 来应用此更改。
  • setGlobalViewModelInstance(name: string, instance: ViewModelInstance): boolean - 设置（或替换）占用名为 name 的全局视图模型槽位的 ViewModelInstance，但不绑定。调用 bind() 来应用此更改。如果 name 与文件中的全局视图模型不匹配，则返回 false。
  • globalViewModelInstance(name: string): ViewModelInstance | null - 返回当前占用指定全局视图模型槽位的 ViewModelInstance；如果尚未设置或创建，则返回 null。这是纯读取操作——它不会创建实例。
  • globalViewModelNames(): string[] - 文件的全局视图模型名称列表，按文件顺序排列。与 setGlobalViewModelInstance() / globalViewModelInstance() 配合使用。
  • bind(): void - 将已设置的主 ViewModelInstance 和全局 ViewModelInstance 应用到状态机。当状态机运行时，如果尚未设置，它还会为文件中的主视图模型和全局视图模型创建默认实例。如果 autoBind 为 true，这会自动完成。
  • enums(): DataEnum[] - 文件中定义的枚举列表
  • getBindableArtboard(name: string): BindableArtboard | null - 返回一个命名 artboard，类型为 BindableArtboard，它会暴露数据绑定 API。获得 bindable artboard 后，你可以在该 artboard 上设置 .viewModel 属性，以绑定 ViewModelInstance。Bindable artboard 可以作为值设置到另一个 ViewModel 上的 artboard 属性。如果 artboard 不存在或文件尚未加载，则返回 null。
  • getDefaultBindableArtboard(): BindableArtboard | null - 返回文件的默认 artboard，类型为 BindableArtboard；如果不可用，则返回 null。

播放​

示例和面向 UX 的讨论：State machine playback。

play()​

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

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

pause()​

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

通过传入的名称暂停指定状态机。如果未传入名称，则会暂停所有已实例化的时间线动画或状态机。

stop()​

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

通过传入的名称停止指定状态机。如果未传入名称，则会停止所有已实例化的时间线动画或状态机。

reset()​

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

reset(params?: RiveResetParameters): void

从起始位置（或 entry state）重置 artboard、时间线动画和/或状态机。会先清理现有的 artboard/animation/state machine 实例。重置后的播放行为遵循 autoplay 和 autoBind（含义与构造函数参数相同）。示例：State machine playback。

画布尺寸和布局​

使用这些 API 来响应画布或窗口尺寸变化，确保 Rive 内容能够清晰地缩放和渲染。

resizeDrawingSurfaceToCanvas()​

resizeDrawingSurfaceToCanvas(customDevicePixelRatio?: number): void

根据 canvas 元素的 CSS 布局尺寸和设备像素比（或你可选传入的 customDevicePixelRatio）设置 canvas 元素的 width 和 height。这可以减少高 DPI 显示器上的模糊。会调用 resizeToCanvas() 并更新 devicePixelRatioUsed。如果 layout.fit 设置为 Fit.Layout，则会根据布局调整 artboard 的宽度/高度。

在此运行时未来的主版本中，该 API 可能会在初始化时默认在内部调用，并提供一个可选择退出的选项，以便你在需要时为 canvas 设置特定的 width 和 height 属性。

用法示例请参阅 layout 指南。

resizeToCanvas()​

resizeToCanvas(): void

根据当前 canvas 的像素宽度和高度设置布局边界（minX、minY、maxX、maxY）。当 canvas 后备存储尺寸发生变化时调用。

resetArtboardSize()​

resetArtboardSize(): void

将 artboard 尺寸恢复为文件中的原始值。

devicePixelRatioUsed​

用于获取/设置在调整绘图表面尺寸时应用的设备像素比（DPR）值（由 resizeDrawingSurfaceToCanvas() 更新）。

bounds​

Artboard 的轴对齐边界；如果 artboard 尚未就绪，则为 undefined。

layout（get/set）​

获取此属性会返回当前的 Layout 实例（请将其视为不可变；使用 new Layout({...}) 或 copyWith 进行更改）。设置此属性会替换布局。示例：Layout。

artboardWidth / artboardHeight​

逻辑 artboard 尺寸的 getter/setter。如果 artboard 尚未加载且你没有设置值，可能会看到 0。

当使用 resizeDrawingSurfaceToCanvas() 并配合 Fit.Layout 时，避免手动设置这些值，因为运行时会根据 canvas 设置宽度/高度。

音频​

volume​

Artboard 音频音量的 getter/setter。默认值为 1.0，表示音量由该 artboard 的默认级别决定。

有关控制音量级别的更多详情，请参阅 playing audio 指南。

事件​

除了可以在 Rive 构造函数中设置的事件回调（即 onLoad）之外，你还可以使用 on 和 off 方法订阅事件，以便更精细地控制 Rive 事件订阅。

on()​

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

订阅运行时事件（类似于 addEventListener）。

off()​

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

使用传递给 on() 的相同 EventType 和回调引用取消订阅。

removeAllRiveEventListeners()​

removeAllRiveEventListeners(type?: EventType): void

移除指定 EventType 的所有监听器；如果省略 type，则移除所有类型的监听器。

事件类型和载荷​

export enum EventType {
  Load = "load",
  LoadError = "loaderror",
  Play = "play",
  Pause = "pause",
  Stop = "stop",
  Loop = "loop", // Only applicable for timeline animations, not state machines
  Advance = "advance", // Called each frame after state machine advance
  StateChange = "statechange",
  RiveEvent = "riveevent",
}

Event 类型为 { type: EventType; data?: ... }。data 的形状取决于 type：

  • Load — RiveFile（已加载的文件句柄）或字符串 "buffer"，表示从 ArrayBuffer 加载
  • LoadError — string（错误消息）
  • Play、Pause、Stop — string[]（受影响的动画或状态机名称）
  • Loop — LoopEvent（{ animation: string; type: LoopType }）。LoopType 为 OneShot、Loop 或 PingPong。
  • Advance — number（该帧经过的秒数）
  • StateChange — string[]（发生变化的状态名称）
  • RiveEvent — 自定义或内置 Rive 事件载荷（例如打开 URL 事件）

有关 EventType.RiveEvent 监听器示例，请参阅 Rive Events。对于新工作，在适用的情况下优先使用 Data binding。

文件和生命周期​

当使用 Rive 加载不同的 Rive 内容，或在不再需要 Rive 时清理资源时，以下 API 可能会有帮助。

load()​

interface RiveLoadParameters {
  src?: string;
  buffer?: ArrayBuffer;
  riveFile?: RiveFile;
  autoplay?: boolean;
  autoBind?: boolean;
  artboard?: string;
  animations?: string | string[];
  stateMachines?: string | string[];
  useOffscreenRenderer?: boolean;
  shouldDisableRiveListeners?: boolean;
  tabIndex?: number;
}

load(params: RiveLoadParameters): void

替换当前 .riv 源并重新初始化实例。这也会停止当前播放，并清除先前的文件引用。重置时必须提供 src、buffer 或 riveFile 之一（与构造函数规则相同）。WASM 通常已经加载，因此如果你指向一个新的托管 .riv 位置，通常只需要承担网络成本。

cleanup()​

cleanup(): void

停止渲染循环，并释放 artboard、动画、状态机、渲染器、文件句柄、监听器以及视图模型实例引用。当不再需要 Rive 实例时调用，以避免内存泄漏。

cleanupInstances()​

cleanupInstances(): void

仅释放 artboard、时间轴动画和状态机实例。文件和渲染器保持有效，因此你可以切换 artboard，或通过 reset() / load() 重新初始化。

deleteRiveRenderer()​

deleteRiveRenderer(): void

删除底层渲染器对象，释放 GPU/WebGL 资源。只有在 cleanup() 之后需要完全拆除时才调用此方法——例如，当从 DOM 中完全移除 WebGL canvas 时。在大多数情况下，仅调用 cleanup() 就足够了。

渲染循环​

stopRendering()​

stopRendering(): void

停止调度帧。不会改变动画的播放/暂停/停止状态。可使用 startRendering() 恢复。这在 <canvas> 不可见的场景中很有用。

startRendering()​

startRendering(): void

如果渲染循环曾通过 stopRendering() 停止，则启动渲染循环。如果已经在运行，则不执行任何操作。

drawFrame()​

drawFrame(): void

推进并绘制一帧。当你在某些更新后需要显式绘制时可使用此方法，但通常不需要手动调用此 API。

resolveAnimationFrame()​

这不是高级 Rive 类上的方法，而是在从头构建渲染循环时供低级 API 使用的方法。在已加载的 RiveCanvas（@rive-app/canvas-advanced / @rive-app/webgl2-advanced）上，当你自己使用浏览器的 requestAnimationFrame 时，请在绘制后调用 rive.resolveAnimationFrame()。高级 Rive 实例则使用 drawFrame() 及其内部循环。完整循环示例：Low-level API — Integrating Rive into Existing rAF Loop。

Rive 监听器​

在大多数情况下，监听器会在实例化期间自动设置和处理。更多详情请参阅关于 Rive listeners 的指南。 如果你需要精确控制 Rive 如何拦截 canvas 上的输入事件，可以使用以下 API。

setupRiveListeners()​

setupRiveListeners(options?: { isTouchScrollEnabled?: boolean }): void

在 canvas 上为使用 Rive Listeners 的活动状态机（重新）附加指针/触摸监听器。在适当时会自动调用；如果动态更改后必须刷新监听器，请使用此方法。可选的 isTouchScrollEnabled 会仅针对本次设置覆盖实例默认值。

removeRiveListeners()​

removeRiveListeners(): void

移除安装在 canvas 上的 Rive Listeners 监听器回调。

已弃用​

以下 Rive 实例上的 API 已弃用。它们可能仍然可用，但为了让你的 Rive 图形面向未来，我们建议迁移 away from 这些模式。

直接设置状态机输入和文本运行已弃用。对于新工作，在可能的情况下请使用 Data binding。

stateMachineInputs()​

stateMachineInputs(stateMachineName: string): StateMachineInput[] | undefined

返回具有给定名称的已实例化状态机的输入；如果文件尚未加载，则返回 undefined。关于获取/设置值以及触发 trigger 输入，请参阅下面的接口。

export enum StateMachineInputType {
  Number = 56,
  Trigger = 58,
  Boolean = 59,
}

class StateMachineInput {
  public readonly type: StateMachineInputType;
  public get name(): string;
  public get value(): number | boolean;
  public set value(value: number | boolean);
  public fire(): void; // trigger inputs only
  public delete(): void; // clears the wrapper’s reference to the native input
}

嵌套画板路径（已弃用）​

对于嵌套画板上的输入和文本运行，请使用路径字符串（例如 "parentArtboard" 或 "group/nested"）来设置输入和文本运行值。

  • setBooleanStateAtPath(inputName: string, value: boolean, path: string): void
  • setNumberStateAtPath(inputName: string, value: number, path: string): void
  • fireStateAtPath(inputName: string, path: string): void
  • getTextRunValueAtPath(textName: string, path: string): string | undefined
  • setTextRunValueAtPath(textName: string, value: string, path: string): void

对于嵌套画板属性，建议使用数据绑定中的嵌套属性路径。

getTextRunValue() / setTextRunValue()​

getTextRunValue(textRunName: string): string | undefined

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

这些方法会作用于当前活动画板上的具名文本运行。当无法解析该文本运行时，会输出控制台警告。

对于新项目，在可行的情况下，建议使用数据绑定中的文本数据绑定。

调试和检查​

Rive 实例化后，你可以通过读取 Rive 实例上的以下一些属性/getter，来检查播放实例的各种属性。

contents​

get contents(): RiveFileContents | undefined

文件加载完成后，contents 会描述画板、动画、状态机，以及每个状态机的输入。如果尚未加载，则为 undefined。

// Documented shape; types may not be exported from the package
interface RiveFileContents {
  artboards: {
    name: string;
    animations: string[];
    stateMachines: {
      name: string;
      inputs: { name: string; type: StateMachineInputType; initialValue?: boolean | number }[];
    }[];
  }[];
}

enableFPSCounter() / disableFPSCounter()​

为当前实例启用 FPS 读数。

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

enableFPSCounter(fpsCallback?: FPSCallback): void;
disableFPSCounter(): void;

如果不提供回调，可能会在视口角落注入一个固定位置的 FPS 读数显示。

性能分析标记​

实例化 Rive 时，设置 enablePerfMarks: true 可为 WASM 初始化和文件加载等关键事件发出 performance.mark 和 performance.measure 条目。这应该能帮助你了解 Rive 启动过程中时间花费在了哪里，并可与浏览器性能分析工具配合使用。发出的标记可能包括：

  • 获取 WASM 的耗时
  • 实例化 Rive 和渲染器的耗时
  • 解析和加载 .riv 文件设置的耗时
  • 在画布上渲染最初几帧的耗时

查看 Chrome DevTools 中的性能面板，可以在火焰图上看到这些标记。 请参阅预加载 WASM 指南和缓存 Rive 文件指南，了解更多优化 Rive 加载时间的方法。

source​

Getter — 当前的 src 字符串（如果有）。

activeArtboard​

活动画板的名称；如果没有，则为 ""。

animationNames / stateMachineNames​

活动画板上的所有动画和状态机名称。

playingAnimationNames / playingStateMachineNames​

活动画板上当前正在播放的动画或状态机。

pausedAnimationNames / pausedStateMachineNames​

活动画板上当前已暂停的动画或状态机。

isPlaying / isPaused / isStopped​

已实例化动画和状态机的聚合播放标志。

相关导出（模块）​

以下是同一包中的命名导出。

RiveFile​

RiveFile 允许你解析一次 .riv 文件，并在多个 Rive 实例之间共享结果——从而避免重复的网络获取和解析开销。请参阅完整使用指南：缓存 Rive 文件。 在许多情况下，你可能希望在实际将图形渲染到 canvas 之前加载 RiveFile。如果你想在渲染前预加载 Rive WASM 和 .riv 文件，或者获取某些 .riv 文件数据，这会很有用。

RiveFile 构造函数参数​

interface RiveFileParameters {
  src?: string;           // URL or public path to the .riv file
  buffer?: ArrayBuffer;   // raw .riv bytes
  assetLoader?: AssetLoadCallback;
  enableRiveAssetCDN?: boolean;
  enablePerfMarks?: boolean;
  onLoad?: EventCallback;
  onLoadError?: EventCallback;
}

必须提供 src 或 buffer 其中之一。

const riveFile = new RiveFile({ src: '/my-animation.riv' });
await riveFile.init(); // resolves when the file is parsed and ready

调用 .init() 会开始加载并解析 .riv 文件。当文件已准备好传递给 new Rive({ riveFile }) 时，Promise 会 resolve。如果你在 RiveFile 参数中提供了 onLoad / onLoadError 回调，它们会在同一时间点触发。

on() / off()​

on(type: EventType, callback: EventCallback): void off(type: EventType, callback: EventCallback): void

订阅或取消订阅文件本身上的 EventType.Load 和 EventType.LoadError 事件。它与 Rive 实例上的相同 API 保持一致。

getBindableArtboard()​

getBindableArtboard(name: string): BindableArtboard | null

按名称返回一个 BindableArtboard。如果该 artboard 不存在，则返回 null。

获得 bindable artboard 后，你可以在该 artboard 上设置 .viewModel 属性，以绑定一个 ViewModelInstance。Bindable artboard 可以作为另一个 ViewModel 上的 artboard 属性的值来设置。

getDefaultBindableArtboard()​

getDefaultBindableArtboard(): BindableArtboard | null

将默认 artboard 作为 BindableArtboard 返回；如果不可用，则返回 null。

viewModelByName()​

viewModelByName(name: string): ViewModel | null

按名称从文件中返回一个 ViewModel；如果它不存在，或者文件尚未加载，则返回 null。这等价于 Rive 类的 .viewModelByName() API，但可以在创建 Rive 实例之前直接通过文件句柄访问。

globalViewModelNames()​

globalViewModelNames(): string[]

文件的全局视图模型名称列表，按文件顺序排列。这等价于 Rive 类的 .globalViewModelNames() API，但可以在创建 Rive 实例之前直接通过文件句柄访问。

cleanup()​

cleanup(): void

无条件释放底层 WASM 文件句柄以及所有关联的监听器。当不再需要 RiveFile 并希望释放内存时调用。

RuntimeLoader​

RuntimeLoader 是一个单例，用于管理页面上所有 Rive 实例的 Rive WASM 二进制文件的加载与缓存。使用此类控制 Rive WASM 从何处加载以及何时加载。

enablePerfMarks​

static enablePerfMarks: boolean

当为 true 时，会为 WASM 初始化计时发出 performance.mark / performance.measure 条目。请在第一次调用 getInstance() / awaitInstance() 之前设置。也可通过 RiveFile 以及 Rive 构造函数参数 enablePerfMarks 使用。

getInstance()​

static getInstance(callback: (rive: RiveCanvas) => void): void

通过回调提供已加载的 WASM runtime；如果尚未开始加载，则会启动加载。如果 runtime 已经加载，回调会立即触发。

RuntimeLoader.getInstance((runtime) => {
  // runtime is a RiveCanvas — the low-level WASM module
});

awaitInstance()​

static awaitInstance(): Promise<RiveCanvas>

getInstance() 的基于 Promise 的替代方案。加载完成后，会以 runtime 作为结果 resolve。

const runtime = await RuntimeLoader.awaitInstance();

setWasmUrl() / getWasmUrl()​

static setWasmUrl(url: string): void static getWasmUrl(): string

覆盖用于获取 WASM 二进制文件的默认/主 URL。请在构造任何 Rive 或 RiveFile 之前调用 setWasmUrl()，因为 WASM 会在首次使用时获取。默认情况下，Rive 会从 UNPKG CDN 拉取与你安装的包版本对应的 WASM。

RuntimeLoader.setWasmUrl('/static/rive.wasm');

setWasmFallbackUrl() / getWasmFallbackUrl()​

static setWasmFallbackUrl(url: string | null): void static getWasmFallbackUrl(): string | null

配置一个备用 WASM URL，当主 URL 加载失败时尝试使用。默认会从 jsdelivr 拉取。传入 null 可禁用备用行为。

setWasmBinary() / getWasmBinary()​

static setWasmBinary(value: ArrayBuffer | null): void static getWasmBinary(): ArrayBuffer | null

以内存中的 ArrayBuffer 形式提供 WASM 二进制文件，而不是从 URL 获取——这对于无网络访问的环境或将 WASM 内联打包的场景很有用。提供后，将使用它而不是从主 URL 获取。传入 null 可清除。

RiveFont​

RiveFont 是一个仅包含静态方法的工具类（不可实例化），用于配置fallback fonts（后备字体）——当主字体缺少某个字形时，Rive 会尝试这些字体。这对于单一字体无法覆盖所有所需 Unicode 范围的多语言内容非常有用。

setFallbackFontCallback()​

static setFallbackFontCallback(fontCallback: FallbackFontsCallback | null): void

type FallbackFontsCallback = (
  missingGlyph: number,
  weight: number
) => FontWrapper | FontWrapper[] | null | undefined;

当在当前字体中找不到某个字形时，runtime 会调用 FallbackFontsCallback。设置此回调以处理缺失的字形码点以及当前字体粗细。返回单个 FontWrapper、FontWrapper 数组，或返回 null/undefined 表示没有可用的后备字体。FontWrapper 是 decodeFont 返回的类型。

此 API 会注册一个回调；每当 runtime 遇到缺失字形时都会调用它。当此回调返回字体数组时，Rive 会按顺序逐个尝试，直到找到匹配项。调用 RiveFont.setFallbackFontCallback(null) 可清除任何先前注册的回调。

更多详情请参阅 fallback fonts。

工具解码器​

decodeAudio、decodeImage 和 decodeFont 会将原始字节解码为可传递给 assetLoader 的资源包装类。更多详情请参阅加载资源。

decodeImage() / decodeFont() / decodeAudio()​

async decodeImage(bytes: Uint8Array): Promise<ImageWrapper>

async decodeFont(bytes: Uint8Array): Promise<FontWrapper>

async decodeAudio(bytes: Uint8Array): Promise<AudioWrapper>