错误处理
此页面仅适用于新版运行时——不适用于旧版运行时。
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.Unknown | 0 | 发生未知错误 |
RiveErrorType.FileNotFound | 1 | 找不到指定的 Rive 文件 |
RiveErrorType.MalformedFile | 2 | Rive 文件格式错误或已损坏 |
RiveErrorType.IncorrectArtboardName | 3 | 指定的画板名称不存在 |
RiveErrorType.IncorrectStateMachineName | 4 | 指定的状态机名称不存在 |
RiveErrorType.ViewModelInstanceNotFound | 6 | 未找到指定的视图模型实例 |
RiveErrorType.IncorrectStateMachineInputName | 8 | 指定的状态机输入名称不存在 |
⚠️ 在
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()。这并不推荐用于大多数应用——只有当您有特定原因需要延迟初始化时才使用此方法。