跳到主要内容
中文系列课

概览（Overview）

Data Binding（数据绑定）是当前推荐的运行时交互方式，用于替代旧的 Inputs / Events / TextRun 直接控制路径。

在真正调用运行时 API 前，建议先了解编辑器侧概念：

  • [Data Binding（Editor）](/docs/Editor/Data Binding/Overview)

核心对象（Core Objects）

1) View Model（VM）​

VM 描述的是“属性结构”（schema），例如：

  • health（number）
  • name（string）
  • isVip（boolean）

VM 本身不承载具体值。

2) View Model Instance（VMI）​

VMI 承载的是“属性值”。

你在代码中通常对 VMI 做三件事：

  • 读值（get）
  • 写值（set）
  • 监听值变化（watch/flow/hook，因 runtime 而异）

3) Bind（绑定）​

推荐把 VMI 绑定到 State Machine（状态机），这样会联动到 Artboard。

若你的内容没有状态机（仅静态或线性动画），才考虑直接绑定 Artboard。

创建 VMI（View Model Instance）

常见创建方式：

  1. Blank instance（空实例）
  2. Default instance（默认实例）
  3. By index（按索引）
  4. By name（按名称）

默认值语义（Blank）​

  • Number: 0
  • String: 空字符串
  • Boolean: false
  • Color: 0xFF000000
  • Trigger: 未触发
  • Enum: 第一项
  • List: 空列表
  • Image/Artboard/Nested VM: 空

各 Runtime 入口（常用）

Web​

// 注意：这里用 r 表示「Rive 实例」，避免与全局的 rive API 命名空间混淆
const r = new rive.Rive({
  src: 'x.riv',
  autoBind: false,
  onLoad: () => {
    const vm = r.viewModelByName('My View Model');
    const vmi = vm.defaultInstance();
    r.bindViewModelInstance(vmi);
  },
});

React​

const { rive } = useRive({ src: 'x.riv', autoBind: false });
const vm = useViewModel(rive, { name: 'My VM' });
const vmi = useViewModelInstance(vm, { name: 'My Instance', rive });

React Native（新版）​

const { riveFile } = useRiveFile(require('./my_file.riv'));
const instance = useViewModelInstance(riveFile, { viewModelName: 'My VM' });

<RiveView file={riveFile} dataBind={instance} />

Flutter​

final controller = RiveWidgetController(file);
final vmi = controller.dataBind(DataBind.byName('My View Model'));

Android（Compose）​

val source = ViewModelSource.Named("My View Model").namedInstance("My Instance")
val vmi = rememberViewModelInstance(riveFile, source)
Rive(riveFile, viewModelInstance = vmi)

Apple（新版）​

let file: File = ...
let vmi = try await file.createViewModelInstance(from: .name("MyInstance", from: .name("MyViewModel")))
let rive = try await Rive(file: file, dataBind: .viewModelInstance(vmi))

Auto-Bind（自动绑定）

Auto-Bind 会自动选择：

  • artboard 上的默认 VM
  • 该 VM 的默认 instance

然后绑定到状态机/画板。

示例​

Web​

const r = new rive.Rive({
  src: 'x.riv',
  autoBind: true,
});

const current = r.viewModelInstance;

React Native​

<RiveView file={riveFile} dataBind={DataBindMode.Auto} autoPlay />

Flutter​

final vmi = controller.dataBind(DataBind.auto());

属性类型（Property Types）

当前主流支持：

  • Number
  • Boolean
  • Trigger
  • String
  • Enum
  • Color
  • Nested View Model
  • List
  • Image
  • Artboard

读写属性（Reading / Writing）

Web​

const r = new rive.Rive({
  src: 'x.riv',
  autoBind: true,
  onLoad: () => {
    const vmi = r.viewModelInstance;
    vmi.number('health').value = 80;
    vmi.string('name').value = 'Rive';
    vmi.boolean('isVip').value = true;
    vmi.trigger('gameOver').trigger();
  },
});

React（hooks）​

const { value: health, setValue: setHealth } = useViewModelInstanceNumber('health', vmi);
const { value: name, setValue: setName } = useViewModelInstanceString('name', vmi);
const { trigger } = useViewModelInstanceTrigger('gameOver', vmi);

React Native（hooks）​

const { value, setValue } = useRiveNumber('health', instance);
const { trigger } = useRiveTrigger('gameOver', instance);

Flutter​

final n = stateMachine.number('health');
n?.value = 100;

注意：某些 runtime 下，设置值后需要一次推进（advance/playIfNeeded）才能立即反映到画面。

绑定策略建议（Best Practices）

  1. 新项目统一用 State Machine + Data Binding
  2. 初始值在 VMI 创建后尽早设置
  3. 统一属性路径命名（尤其嵌套路径）
  4. 旧接口迁移：
    • Inputs → Data Binding 属性
    • Events → Trigger + 属性监听
    • TextRun → String 属性

相关文档