画板（Artboards）

更多编辑器侧背景：

Artboards（Editor）

概览（Overview）

Rive 文件里可以有多个 Artboard（画板）。在运行时你通常需要决定“渲染哪一个”。

通用规则：

若明确传入 artboard 名称/索引 → 使用指定项
若未传入 → 使用编辑器里设置的默认 artboard
若也没有默认值 → 回退到第一个 artboard

同一个 Rive 渲染实例一次只会渲染一个 Artboard。

Web（JavaScript）

new rive.Rive({
  src: 'https://cdn.rive.app/animations/vehicles.riv',
  canvas: document.getElementById('canvas'),
  artboard: 'Truck',
  autoplay: true,
});

React

组件方式

<Rive
  src="https://cdn.rive.app/animations/vehicles.riv"
  artboard="Truck"
/>

`useRive` 方式

const { RiveComponent } = useRive({
  src: 'https://cdn.rive.app/animations/vehicles.riv',
  artboard: 'Truck',
  autoplay: true,
});

React Native

新版通常通过 artboardName 指定：

<RiveView
  file={riveFile}
  artboardName="My Artboard"
  autoPlay
/>

Flutter

Flutter 里你可以先从 File 取 Artboard，再交给控制器/渲染组件。

// 默认
final ab0 = riveFile.defaultArtboard();

// 按名称
final ab1 = riveFile.artboard('My Artboard');

// 按索引
final ab2 = riveFile.artboardAt(0);

也可以通过 selector 指定：

final controller = RiveWidgetController(
  riveFile,
  artboardSelector: ArtboardSelector.byName('My Artboard'),
);

Apple（新版）

通常流程：

创建 File
获取/创建目标 Artboard
传入 Rive(...)

let file = try await File(source: .local("my_file", Bundle.main), worker: Worker())
let artboard = try await file.createArtboard("Artboard")
let rive = try await Rive(file: file, artboard: artboard)

Apple 新版 API 中，很多查询是 async + throws，建议做好错误处理。

Android（Compose）

Compose 中常见写法：

val artboard = rememberArtboard(riveFile, "My Artboard")
Rive(riveFile, artboard = artboard)

非 Compose 场景可手动创建并在生命周期结束时 close()。

与 State Machine 的关系

Artboard 决定了你能访问哪些状态机与元素。
先选对 Artboard，再选择 State Machine，通常最稳。

可继续阅读：

实践建议

生产项目尽量固定约定 artboard 名称，避免“默认值漂移”
做 A/B 或多主题时，用“同文件多 artboard”可减少资源碎片
读取失败（名称不存在）时，提供回退策略和日志

概览（Overview）​

Web（JavaScript）​

React​

组件方式​

useRive 方式​

React Native​

Flutter​

Apple（新版）​

Android（Compose）​

与 State Machine 的关系​

实践建议​