Docs 菜单
Docs 主页
/
MongoDB Atlas
/
Atlas Device SDKs
/
React Native SDK
/
API 参考

RealmProvider (@realm /react)

在此页面上

  • Props 对象
  • 使用 RealmProvider 配置 Realm
  • 配置多个 Realm
  • RealmProvider 钩子
  • useRealm()
  • useObject（）
  • useQuery()
  • 使用 createRealmContext () 创建上下文
类型签名
RealmProvider(props, context?): null | ReactElement<any, any>

嵌套在 RealmProvider 内的组件可以访问配置好的 Realm 并使用 RealmProvider 钩子。

Props 对象

BaseConfiguration的所有属性都可以作为 props 传递。

RealmProvider 有更多定义其行为的 props：

  • fallback?: React.ComponentType<unknown> | React.ReactElement | null | undefined

    在 Realm 打开时渲染的后备组件（fallback component）。

  • closeOnUnmount?: boolean

    默认值为 true。如果设置为 false，则当组件卸载时，Realm 将不会关闭。

  • realmRef?: React.MutableRefObject<Realm | null>

    Realm 实例的引用。如果需要在 Realm 范围之外访问 Realm 实例，这很有用。

  • children: React.ReactNode

使用 RealmProvider 配置 Realm

可以通过两种方式配置 RealmProvider：

  • 直接从 @realm/react 导入 RealmProvider

  • 使用 createRealmContext() 配置一个 RealmProvider 并创建钩子

本部分详细介绍如何配置直接从 导入的RealmProvider @realm/react。有关使用createRealmContext()的信息，请参阅使用 createRealmContext() 创建上下文。

对象模型是大多数 Realm 配置的一部分。要了解有关 Realm 和数据模型的更多信息，请参阅定义 Realm 对象模型。

RealmProvider是一个向其子组件公开 Realm 的包装器。 您可以通过将属性传递给RealmProvider来配置 Realm。

呈现RealmProvider时，会打开 Realm。 这意味着如果呈现失败，子组件将无法访问 Realm。

除 RealmProvider 之外，您还需要配置 AppProvider 和 UserProvider。

默认情况下，Realm 在返回任何内容之前会同步服务器上的所有数据。如果您想在后台同步数据，请阅读脱机时配置同步 Realm。

要配置一个同步 Realm，请执行以下操作：

  1. 从 @realm/react 导入提供者。

  2. 配置 AppProvider。

  3. 配置 UserProvider 并将其嵌套在 AppProvider 中。

  4. 配置 RealmProvider 进行同步并将其嵌套在 UserProvider 中。

  5. 将对象模型传递给 schema 属性。

  6. 将其他配置对象属性作为属性添加到RealmProvider 。

您必须设置同步订阅。下面的示例使用初始订阅，但您也可以在 RealmProvider 子组件中设置订阅。

您必须像以下示例一样对提供者进行嵌套：

import React from 'react';
import {AppProvider, UserProvider, RealmProvider} from '@realm/react';
function AppWrapperSync() {
  return (
    <AppProvider id={APP_ID}>
      <UserProvider fallback={LogIn}>
        <RealmProvider
          schema={[YourObjectModel]}
          sync={{
            flexible: true,
            initialSubscriptions: {
              update(subs, realm) {
                subs.add(realm.objects(YourObjectModel));
              },
            },
          }}>
          <RestOfApp />
        </RealmProvider>
      </UserProvider>
    </AppProvider>
  );
}

有关配置同步 Realm 的更多信息，请参阅配置同步 Realm。

RealmProvider是一个向其子组件公开 Realm 的包装器。 您可以通过将属性传递给RealmProvider来配置 Realm。

呈现RealmProvider时，会打开 Realm。 这意味着如果呈现失败，子组件将无法访问 Realm。

要配置非同步 Realm：

  1. 从 @realm/react 导入 RealmProvider。

  2. 将对象模型传递给 schema 属性。

  3. 将其他配置对象属性作为属性添加到RealmProvider 。

import React from 'react';
import {RealmProvider} from '@realm/react';
function AppWrapperLocal() {
  return (
    <RealmProvider schema={[YourObjectModel]}>
      <RestOfApp />
    </RealmProvider>
  );
}

配置多个 Realm

从 @realm/react 导入 RealmProvider 时，该 Provider 具有特定上下文并与单个 Realm 关联。如果需要配置多个 Realm，请使用 createRealmContext() 为每个 Realm 实例化一个新的 Provider。

如果直接从 @realm/react 导入 useRealm()、useQuery() 或 useObject()，这些钩子将使用默认的 Realm 上下文。如需使用多个 Realm，需要从 createRealmContext() 的结果解构出一个新的 Realm Provider 及其相关钩子。应对不同的 Provider 提供不同的命名空间，以避免混淆您正在使用的 Provider 和钩子。

有关详细指南，请参阅“提供多个 Realm”。

有关 createRealmContext() 的详细信息，请参阅本页的“使用 createRealmContext() 创建上下文”。

RealmProvider 钩子

useRealm()

类型签名
useRealm(): Realm

useRealm() 钩子返回一个打开的 Realm 实例。通过 Realm 实例，可访问 Realm 方法和属性。例如，可以调用 realm.write() 将一个 Realm 对象添加到您的 Realm 中。

如需了解有关修改 Realm 数据的更多信息，请参阅“写入事务”。

const CreatePersonInput = () => {
  const [name, setName] = useState('');
  const realm = useRealm();
  const handleAddPerson = () => {
    realm.write(() => {
      realm.create('Person', {_id: PERSON_ID, name: name, age: 25});
    });
  };
  return (
    <>
      <TextInput value={name} onChangeText={setName}  />
      <Button
        onPress={() => handleAddPerson()}
        title='Add Person'
      />
    </>
  );
};

返回：

  • Realm 返回 Realm 实例。这是钩子的父组件 RealmProvider 创建的 Realm。

useObject（）

类型签名
useObject<T>(type, primaryKey): T & Realm.Object<T> | null

useObject() 钩子将根据给定的主键返回其对应的 Realm 对象。您可以传递对象类或以字符串形式传递类的名称以及主键。

如果该对象不存在或已被删除，useObject() 方法将返回空值。该钩子将自动订阅对象的更新，并在对象发生任何更改时重新渲染使用该钩子的组件。

const TaskItem = ({_id}: {_id: number}) => {
  const myTask = useObject(Task, _id);
  return (
    <View>
      {myTask ? (
        <Text>
          {myTask.name} is a task with the priority of: {myTask.priority}
        </Text>
      ) : null}
    </View>
  );
};

参数

返回：

  • Realm.Object | null Realm 对象；如果没有该找到对象，则为 null。

useQuery()

类型签名
useQuery<T>(type, query?, deps?): Realm.Results<T & Realm.Object<T>>

useQuery() 钩子返回给定类型 Realm 对象的集合。这些就是您的查询结果。查询（query）参数可以是对象类，也可以是字符串形式的类名称。

useQuery() 方法订阅集合中任何对象的更新，并在结果发生任何更改时使用它重新渲染组件。

您可以使用 .filtered() 和 .sorted() 对查询结果进行过滤和排序。您应该在 useQuery 的 query 参数中这样操作，以便其只在依赖数组发生变更时运行。有关更多示例，请参阅“CRUD — 读取”文档。

const TaskList = () => {
  const [priority, setPriority] = useState(4);
  // filter for tasks with a high priority
  const highPriorityTasks = useQuery(
    Task,
    tasks => {
      return tasks.filtered('priority >= $0', priority);
    },
    [priority],
  );
  // filter for tasks that have just-started or short-running progress
  const lowProgressTasks = useQuery(Task, tasks => {
    return tasks.filtered(
      '$0 <= progressMinutes && progressMinutes < $1',
      1,
      10,
    );
  });
  return (
    <>
      <Text>Your high priority tasks:</Text>
      {highPriorityTasks.map(taskItem => {
        return <Text>{taskItem.name}</Text>;
      })}
      <Text>Your tasks without much progress:</Text>
      {lowProgressTasks.map(taskItem => {
        return <Text>{taskItem.name}</Text>;
      })}
    </>
  );
};

参数

  • type: string 与对象模型的类名称匹配的string或对扩展Realm.Object 的类的引用。

  • query?: QueryCallback<T> 可以对查询结果进行过滤和排序的查询函数。它基于 useCallback 构建以记忆化查询函数。

  • deps?: DependencyList 查询函数的依赖项列表，用于记忆化查询函数。

返回：

  • Realm.Results<T> Realm 对象；如果没有该找到对象，则为 null。

使用 createRealmContext () 创建上下文

类型签名
createRealmContext(realmConfig?): RealmContext

大多数时候，如果需要配置多个 Realm，您只能使用createRealmContext()。否则，应直接从 @realm/react 导入 RealmProvider 和钩子。

createRealmContext()方法创建 React Context Context具有给定 Configuration 的域对象。 对象包含以下内容：

  • 上下文提供者 （在其他地方称为RealmProvider ）组件，用于包装子组件并为子组件提供对钩子的访问权限。

  • 各种预建的钩子，可访问配置好的 Realm。

有关详细指南，请参阅“提供多个 Realm”。

参数

返回：

  • RealmContext 包含一个 RealmProvider 组件和 useRealm、useQuery 和 useObject 钩子的对象。

后退

API 参考

来年

AppProvider (@realm/react)