需要在 React/Web 中实现状态机驱动…

当动画需要根据用户输入、应用数据或状态变化实时切换，并要求与代码双向通信时，使用 Rive 状态机、ViewModel 和事件系统进行集成。

适用场景

解决思路

1. 安装 React 包：运行 `npm install rive-react`。
2. 显示基础动画：引入 `Rive`，设置 `src='animation.riv'`、`artboard='Main'`、`animations='idle'`、`layout={{ fit: 'contain', alignment: 'center' }}` 和 `style` 宽高。
3. 用状态机控制动画：调用 `useRive({ src: 'button.riv', stateMachines: 'Button State Machine', autoplay: true })` 获取 `rive` 和 `RiveComponent`。
4. 获取状态机输入：调用 `useStateMachineInput(rive, 'Button State Machine', 'isHovered', false)`，传入 rive、状态机名、输入名和默认值。
5. 控制 Boolean 输入：设置 `hoverInput.value = true` 或 `false`。
6. 控制 Number 输入：设置 `numberInput.value = 50`。
7. 控制 Trigger 输入：调用 `triggerInput.fire()`。
8. 通过 DOM 事件驱动输入：在 `onMouseEnter`/`onMouseLeave` 中设置 boolean 输入，在 `onClick` 中触发 trigger 输入。
9. 使用 ViewModel 双向绑定：在 `useRive` 中设置 `autoBind: false` 以启用手动 ViewModel 控制。
10. 获取 ViewModel：调用 `useViewModel(rive, { name: 'Dashboard' })`。
11. 获取 ViewModel 实例：调用 `useViewModelInstance(viewModel, { rive })`。
12. 绑定字符串属性：调用 `useViewModelInstanceString('title', viewModelInstance)`，在 `useEffect` 中用 `setTitle('Stock Dashboard')` 更新。
13. 绑定数字属性：调用 `useViewModelInstanceNumber('stockPrice', viewModelInstance)`，在 `useEffect` 中用 `setPrice(stockPrice)` 更新。
14. 绑定颜色属性：调用 `useViewModelInstanceColor('avatarColor', viewModelInstance)`，用 `parseInt(user.color.substring(1), 16)` 将十六进制颜色转为数字后设置。
15. 绑定枚举属性：调用 `useViewModelInstanceEnum` 选择预定义选项。
16. 绑定触发器属性：调用 `useViewModelInstanceTrigger` 发送动画事件。
17. 在数据变化时更新 ViewModel：用 `useEffect` 监听应用数据并调用各属性的 `setValue`。
18. 处理 Rive 事件：在 `useRive` 中设置 `automaticallyHandleEvents: true`。
19. 注册事件监听：在 `useEffect` 中调用 `rive.on(EventType.RiveEvent, onRiveEvent)`。
20. 读取事件数据：从 `event.data` 获取 `type`、`name`、`properties`，并判断 `eventData.type === RiveEventType.General`。
21. 清理事件监听：在 `useEffect` 返回函数中调用 `rive.off(EventType.RiveEvent, onRiveEvent)`。
22. 预加载 Rive 文件：调用 `useRiveFile({ src: 'large-animation.riv' })` 获取 `riveFile` 和 `status`。
23. 根据加载状态渲染：当 `status === 'loading'` 显示加载中，当 `status === 'failed'` 显示失败。
24. 使用预加载文件：把 `riveFile` 传给 `useRive({ riveFile, artboard: 'Main', autoplay: true })`。
25. 暴露父组件控制方法：用 `forwardRef` 和 `useImperativeHandle` 暴露 `spin`、`pause`、`play`。
26. 在受控组件中获取默认 ViewModel：调用 `useViewModel(rive, { useDefault: true })`，再 `useViewModelInstance(viewModel, { rive })`。
27. 获取 ViewModel trigger：调用 `useViewModelInstanceTrigger('triggerSpin', viewModelInstance)`，暴露 `spin: () => spinTrigger && spinTrigger()`。
28. 暴露播放/暂停：暴露 `pause: () => rive && rive.pause()` 和 `play: () => rive && rive.play()`。
29. 父组件调用控制：通过 `ref` 调用 `animationRef.current?.spin()`、`animationRef.current?.pause()`、`animationRef.current?.play()`。
30. 多属性 ViewModel 更新：同时绑定 `useViewModelInstanceString('name', viewModelInstance)`、`useViewModelInstanceNumber('score', viewModelInstance)`、`useViewModelInstanceColor('avatarColor', viewModelInstance)`。
31. 批量更新多属性：在 `useEffect` 中调用 `setName(user.name)`、`setScore(user.score)`、`setColor(parseInt(user.color.substring(1), 16))`。
32. 与 Framer Motion 集成：用 `motion.div` 的 `initial`、`animate`、`whileHover` 包裹 `Rive`，Rive 负责交互内容并传入 `stateMachines`。
33. 与 GSAP ScrollTrigger 集成：调用 `gsap.registerPlugin(ScrollTrigger)`。
34. 用 ScrollTrigger 驱动 Rive：在 `useRive` 中设置 `stateMachines` 和 `autoplay`，用 `useStateMachineInput(rive, 'State Machine 1', 'trigger')` 获取 trigger。
35. 滚动进入时触发：调用 `ScrollTrigger.create({ trigger: containerRef.current, start: 'top center', onEnter: () => trigger.fire() })`。
36. 开启离屏渲染：在 `Rive` 组件上设置 `useOffscreenRenderer={true}` 提升性能。
37. 优化 Rive 文件：在 Rive Editor 中保持 artboards 小于 2MB。
38. 使用矢量图形：尽量避免栅格图像。
39. 减少骨骼：最小化骨骼动画中的骨骼数量。
40. 降低状态机复杂度：减少状态机复杂度。
41. 预加载关键动画：用 `useRiveFile({ src: 'critical.riv' })` 在应用初始化期间预加载。
42. 手动控制事件：设置 `automaticallyHandleEvents={false}` 禁用自动事件处理。
43. 修复输入找不到：确保 `useStateMachineInput` 的输入名与 Rive editor 完全匹配，并在使用前检查 `if (input)`。
44. 修复 ViewModel 不更新：在 `useRive` 中设置 `autoBind: false`。
45. 修复事件不触发：在 `useRive` 中设置 `automaticallyHandleEvents: true`。
46. 生成组件样板：从 skill 目录运行 `./scripts/component_generator.py`。
47. 构建 ViewModel 绑定：从 skill 目录运行 `./scripts/viewmodel_builder.py`。
48. 使用模板和示例：参考 `starter_rive/` 的完整 React + Rive 模板和 `examples/` 的真实集成模式。

适用边界 · 注意事项

• 只需要简单时间线动画、不需要状态机、输入或双向数据绑定时，优先考虑 Lottie。
• 需要代码优先的 React 弹簧物理或手势动画时，考虑 Framer Motion。
• 只需要滚动驱动网页动画且不需要 Rive 状态机时，考虑 GSAP ScrollTrigger。