跳到主要内容
中文系列课

错误处理

此页面仅适用于新版运行时——不适用于旧版运行时。

将 Rive 操作包装在 try/catch 块中以处理错误。例如，加载文件时：

try {
  const riveFile = await RiveFileFactory.fromURL(
    "https://cdn.rive.app/animations/vehicles.riv"
  );
  // 使用 riveFile...
} catch (error) {
  // 处理 Rive 文件加载期间发生的错误
  console.error("Error loading Rive file:", error);
}

基于视图的错误​

使用 onError 回调属性来处理视图配置或运行时操作期间的错误：

<RiveView
  file={riveFile}
  onError={(error) => {
    // error.type 包含错误类型枚举值
    // error.message 包含描述性错误消息
    console.error(`Rive Error [${error.type}]: ${error.message}`);
  }}
/>

错误类型​

以下错误类型可能在视图操作期间发生：

错误类型值描述
RiveErrorType.Unknown0发生未知错误
RiveErrorType.FileNotFound1找不到指定的 Rive 文件
RiveErrorType.MalformedFile2Rive 文件格式错误或已损坏
RiveErrorType.IncorrectArtboardName3指定的画板名称不存在
RiveErrorType.IncorrectStateMachineName4指定的状态机名称不存在
RiveErrorType.ViewModelInstanceNotFound6未找到指定的视图模型实例
RiveErrorType.IncorrectStateMachineInputName8指定的状态机输入名称不存在

使用这些错误类型来提供特定的错误处理：

import { RiveView, RiveErrorType } from "@rive-app/react-native";

<RiveView
  file={riveFile}
  artboardName="MainArtboard"
  onError={(error) => {
    switch (error.type) {
      case RiveErrorType.IncorrectArtboardName:
        console.error("Artboard not found:", error.message);
        // 处理缺失画板（例如使用默认画板）
        break;
      case RiveErrorType.IncorrectStateMachineName:
        console.error("State machine not found:", error.message);
        // 处理缺失状态机
        break;
      case RiveErrorType.MalformedFile:
        console.error("Corrupted file:", error.message);
        // 处理损坏文件（例如显示错误 UI）
        break;
      default:
        console.error("Rive error:", error.message);
    }
  }}
  style={{ width: "100%", height: 400 }}
/>;

如果未提供 onError 处理程序，错误将默认记录到控制台。

Android 运行时初始化​

在 Android 上，Rive 本地库在应用启动时自动初始化。在极少数情况下（ABI 不匹配、缺少本地库等），此初始化可能会失败。使用 RiveRuntime.getStatus() 检查初始化是否成功：

import { RiveRuntime } from '@rive-app/react-native';

const { isInitialized, error } = RiveRuntime.getStatus();
if (!isInitialized) {
  console.error('Rive failed to initialize:', error);
}

在 iOS 上，运行时不需显式初始化 — getStatus() 将始终返回 { isInitialized: true }。

⚠️ 高级用法： 如果您需要完全控制初始化发生的时间，可以通过在 android/gradle.properties 中添加 Rive_RiveRuntimeAndroidSkipSetup=true 来禁用自动初始化，然后自己调用 RiveRuntime.initialize()。这并不推荐用于大多数应用——只有当您有特定原因需要延迟初始化时才使用此方法。