跳到主要内容
中文系列课

加载 Rive 文件

新版运行时（推荐）​

有几种方式可以在 React Native 项目中使用新版运行时加载 Rive 文件：

  • 选项 1：使用 require() — 从项目目录加载文件（推荐用于开发和 OTA 更新）
  • 选项 2：URL — 从远程 URL 加载文件
  • 选项 3：资源名称 — 从本地资源包加载文件
  • 选项 4：ArrayBuffer — 从二进制数据加载文件

所有加载方法都使用 useRiveFile hook，它返回一个 RiveFile 对象，您通过 file 属性将其传递给 RiveView 组件。

选项 1：使用 require()（推荐）​

推荐使用 require() 加载 Rive 文件，因为当您更新 Rive 文件时不需要重新构建本地代码。在开发期间，使用 require() 加载的文件由 Metro 开发服务器提供。当您构建应用时，文件会自动打包到应用资源中。使用 Expo 时，这也启用无线 (OTA) 更新。

import { View, ActivityIndicator, Text } from "react-native";
import { RiveView, useRiveFile, Fit } from "@rive-app/react-native";

export default function RiveDemo() {
  const { riveFile, isLoading, error } = useRiveFile(
    require("./assets/flying_car.riv")
  );

  if (isLoading) {
    return <ActivityIndicator size="large" />;
  }

  if (error || !riveFile) {
    return <Text>Error: {error || "Failed to load file"}</Text>;
  }

  return (
    <RiveView
      file={riveFile}
      fit={Fit.Contain}
      autoPlay={true}
      style={{ width: 400, height: 400 }}
    />
  );
}

要实现此功能，确保您的 metro.config.js 支持 .riv 文件。 如果您使用 Expo 且没有此文件，可以通过以下命令生成：

npx expo customize metro.config.js

然后添加：

const { getDefaultConfig } = require("expo/metro-config");

const config = getDefaultConfig(__dirname);

// 添加对 `.riv` 文件的支持
config.resolver.assetExts.push("riv");

module.exports = config;

选项 2：从 URL 加载​

您可以从远程 URL（例如 AWS S3、Google Storage、CDN）加载 Rive 文件：

import { View, ActivityIndicator, Text } from "react-native";
import { RiveView, useRiveFile, Fit } from "@rive-app/react-native";

export default function RiveDemo() {
  const { riveFile, isLoading, error } = useRiveFile(
    "https://cdn.rive.app/animations/vehicles.riv"
  );

  if (isLoading) {
    return <ActivityIndicator size="large" />;
  }

  if (error || !riveFile) {
    return <Text>Error: {error || "Failed to load file"}</Text>;
  }

  return (
    <RiveView
      file={riveFile}
      fit={Fit.Contain}
      autoPlay={true}
      style={{ width: 400, height: 400 }}
    />
  );
}

选项 3：从资源名称加载​

您可以通过引用资源名称（不带 .riv 扩展名）从本地资源包加载 Rive 文件。

import { View, ActivityIndicator, Text } from "react-native";
import { RiveView, useRiveFile, Fit } from "@rive-app/react-native";

export default function RiveDemo() {
  const { riveFile, isLoading, error } = useRiveFile("weather_app");

  if (isLoading) {
    return <ActivityIndicator size="large" />;
  }

  if (error || !riveFile) {
    return <Text>Error: {error || "Failed to load file"}</Text>;
  }

  return (
    <RiveView
      file={riveFile}
      fit={Fit.Contain}
      autoPlay={true}
      style={{ width: 400, height: 400 }}
    />
  );
}

添加到 iOS​

在 React Native 项目的 ios/ 文件夹中，在 XCode 中打开 .xcodeproj 文件。这将打开本地 iOS 项目。

在项目根目录下创建一个 New Group 并给它取个名字（例如 Assets）。将您的 .riv 文件拖入此组，当 XCode 提示时，将其添加到应用的 Target 中。这确保 Rive 文件被包含在包资源中。

Image

添加到 Android​

在 Android Studio 中打开 React Native 项目的 android/ 文件夹。

在 /app/src/main/res/ 目录下，创建一个新的 Android Resource Directory，这是您存储 Rive 文件资源的地方。当提示选择文件夹名称和资源类型时，从资源类型下拉菜单中选择 raw。将您的 .riv 文件拖入此新文件夹，这确保 Rive 文件被包含在包资源中。

Image

将 weather_app.riv 添加到 Android 项目

选项 4：从 ArrayBuffer 加载​

您可以使用 ArrayBuffer 从二进制数据加载 Rive 文件：

import { View, ActivityIndicator, Text } from "react-native";
import { RiveView, useRiveFile, Fit } from "@rive-app/react-native";
import { useState, useEffect } from "react";

export default function RiveDemo() {
  const [arrayBuffer, setArrayBuffer] = useState<ArrayBuffer | undefined>();

  useEffect(() => {
    const loadFile = async () => {
      try {
        const response = await fetch(
          "https://cdn.rive.app/animations/vehicles.riv"
        );
        const buffer = await response.arrayBuffer();
        setArrayBuffer(buffer);
      } catch (error) {
        console.error("Failed to load file:", error);
      }
    };

    loadFile();
  }, []);

  const { riveFile, isLoading, error } = useRiveFile(arrayBuffer);

  if (isLoading || !arrayBuffer) {
    return <ActivityIndicator size="large" />;
  }

  if (error || !riveFile) {
    return <Text>Error: {error || "Failed to load file"}</Text>;
  }

  return (
    <RiveView
      file={riveFile}
      fit={Fit.Contain}
      autoPlay={true}
      style={{ width: 400, height: 400 }}
    />
  );
}

旧版运行时​

有几种方式可以在 React Native 项目中包含 Rive 文件：

  • 选项 1：托管 Rive 文件的 URL
  • 选项 2：将资源添加到本地 iOS 和 Android 项目的资源包中
  • 选项 3：使用 expo-asset 将资源添加到 Expo 项目的资源包中
  • 选项 4：Source 属性和 require

当您渲染 <Rive /> 组件时，必须分别对应上述选项提供 url 或 resourceName 属性，否则组件将加载失败。

选项 1：URL​

<Rive url="https://cdn.rive.app/animations/vehicles.riv" />

使用 Rive React Native 运行时加载 Rive 文件时，一种选择是引用托管 Rive 文件的 URL（例如 AWS S3 存储桶、Google Storage 等）。这可以通过在实例化 <Rive /> 组件时使用 url 参数来完成。

选项 2：资源包​

<Rive
  resourceName="weather_app" // weather_app.riv
/>

为 <Rive /> 组件加载 Rive 文件的另一种选择是引用相应 ios/ 和 android/ 项目中的资源/资源名称。

添加到 iOS​

在 React Native 项目的 ios/ 文件夹中，在 XCode 中打开 .xcodeproj 文件。这将打开本地 iOS 项目。

在项目根目录下创建一个 New Group 并给资源文件夹取任何您喜欢的名字（例如 Assets）。将您的 .riv 文件拖入此组，当 XCode 提示时，将其添加到应用的 Target 中。这确保 Rive 文件被包含在包资源中。

Image

添加到 Android​

在 React Native 项目的 android/ 文件夹中，在 Android Studio 中打开整个文件夹。这将打开 Android 项目。

在 /app/src/main/res/ 目录下，创建一个新的 Android Resource Directory，这是您存储 Rive 文件资源的地方。当提示选择文件夹名称和资源类型时，从资源类型下拉菜单中选择 raw。将您的 .riv 文件拖入此新文件夹；这确保 Rive 文件被包含在包资源中。

Image

将 weather_app.riv 添加到 Android 项目

一旦 Rive 文件被添加到 React Native 应用中 iOS 和 Android 项目的资源/资源包中，您就可以在创建 <Rive /> 组件时使用 resourceName 属性引用文件名（不带 .riv 扩展名）。

选项 3：使用 expo-asset 与 Expo CNG​

<Rive
  resourceName="weather_app" // weather_app.riv
/>

如果您使用 Expo SDK 53 或更高版本，并希望利用 Expo CNG（持续本地代码生成），您可以使用 expo-asset 插件将 .riv 文件打包到本地构建中。

在您的 app.json 或 app.config.js 中，添加 expo-asset 插件并指定您的 .riv 文件或资源目录：

{
  "expo": {
    "plugins": [
      [
        "expo-asset",
        {
          "assets": ["path/to/file.riv", "path/to/directory"]
        }
      ]
    ]
  }
}

要在 Metro 中启用对 Rive 文件的支持，更新您的 metro.config.js。 如果您还没有此文件，生成它：

npx expo customize metro.config.js

然后按如下方式编辑：

const { getDefaultConfig } = require("expo/metro-config");

const config = getDefaultConfig(__dirname);

// 添加对 `.riv` 文件的支持
config.resolver.assetExts.push("riv");

module.exports = config;

然后重新生成您的开发构建，如果您使用任何 expo run:* 命令，只需记得先运行 npx expo prebuild。

如果您使用较早版本的 Expo，可以在此 Github Issue 中找到替代方法。

选项 4：Source 属性与 Require​

<Rive source={require("./flying_car.riv")} />

如果您希望将 Rive 文件保留在与组件代码相同的文件夹中，可以使用 source 属性和 require() 通过引用其路径来加载 Rive 文件。

要实现此功能，确保您的 metro.config.js 支持 .riv 文件。 如果您使用 Expo 且没有此文件，可以通过以下命令生成：

npx expo customize metro.config.js

然后添加：

// 添加对 `.riv` 文件的支持
config.resolver.assetExts.push("riv");

此方法的另一个优势是，在开发期间，文件由 Metro 开发服务器提供，允许您在不重建应用的情况下更新它。当您构建应用时，文件会自动打包到应用资源中。