跳到主要内容

参数与返回值（Parameters and Return Values）

Hooks​

useRive​

签名：

useRive(riveParams: UseRiveParameters, opts?: UseRiveOptions): RiveState

  • riveParams：传给底层 Web Runtime 的初始化参数（可传 null/undefined 做条件展示）
  • opts：rive-react 专属选项

常见 opts：

  • useDevicePixelRatio（默认 true）
  • fitCanvasToArtboardHeight（默认 false）
  • useOffscreenRenderer（默认 true，主要针对 webgl 共享上下文）

返回值 RiveState 常用字段：

  • rive：Rive 实例
  • RiveComponent：用于渲染的组件
  • canvas / container
  • setCanvasRef / setContainerRef

提示（Tip）：多数场景你只需要 rive + RiveComponent。

useStateMachineInput​

签名：

useStateMachineInput(rive, stateMachineName?, inputName?, initialValue?)

返回 StateMachineInput | null，用于读写/触发输入。

常用能力：

  • value 读写
  • fire() 触发 trigger

useResizeCanvas​

用于把 <canvas> 按父容器尺寸自动缩放，并重置绘制面积。

如果你已经使用 useRive 或默认 <Rive /> 组件，通常不需要手动使用它。

useRiveFile​

用于创建并管理可复用的 RiveFile，减少重复加载与解析。

签名：

useRiveFile(params: UseRiveFileParameters): RiveFileState

params 可传：

  • src（URL 或 public 资源路径）
  • buffer（ArrayBuffer）
  • enableRiveAssetCDN（默认启用）

返回：

  • riveFile
  • status（idle/loading/failed/success）

组件​

<RiveComponent />​

注意点：

  • style / className 会作用于外层包裹 <div>
  • 其他属性（如 aria-*、role）会传给 <canvas>
  • 可在组件内部提供 fallback children