跳到主要内容

错误处理

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

Hook 错误(Hook errors)​

加载 hook 返回 error 而不是抛出。请将其与加载状态一起检查:

const { riveFile, error: fileError } = useRiveFile(require('./assets/my_file.riv'));
const { instance, error: instanceError } = useViewModelInstance(riveFile, { async: true });
const { value: health, error: healthError } = useRiveNumber('health', instance);

if (fileError || instanceError) {
return <Text>{(fileError ?? instanceError)!.message}</Text>;
}
  • useRiveFile 在文件无法加载或解码时设置 error。
  • useViewModelInstance 在请求的视图模型、画板或实例不存在时设置 error。使用 required: true 时会改为抛出,因此您可以使用错误边界来处理。
  • 属性 hook(useRiveNumber、useRiveTrigger 等)在无法找到或读取属性路径时设置 error。

命令式 API(Imperative APIs)​

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

try {
const riveFile = await RiveFileFactory.fromURL(
"https://cdn.rive.app/animations/vehicles.riv",
undefined // referenced assets
);
// 使用 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指定的状态机输入名称不存在

⚠️ 在 0.5.0 及更高版本中,视图错误始终报告为 RiveErrorType.Unknown。请使用 error.message 获取详细信息。特定错误类型仅在 0.4.x 中报告。

在 0.4.x 中,您可以使用这些错误类型来提供特定的错误处理:

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 处理程序,错误将通过 console.error 记录。

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()。这并不推荐用于大多数应用——只有当您有特定原因需要延迟初始化时才使用此方法。

看完还有疑问?进群交流下!
与众多 Rive 创作者、开发者一起交流探讨与答疑解惑。
加入交流群