快速入门 - React Native SDK

在此页面上

关于 @realm/react 包

设置您的 Realm 应用
定义对象模型
配置 Realm
处理 Realm 对象
读取、排序和过滤对象
创建、更新和删除 Realm 对象
添加 Atlas Device Sync（可选）
先决条件
配置和访问同步 Realm
下一步：查看模板应用程序和教程

Atlas Device SDK 已弃用。有关详细信息，请参阅弃用页面。

本页演示了如何通过 React Native SDK 来使用 Realm。

开始之前，请安装 Realm React Native SDK。

关于 @realm/react 包

@ 域/React 是中使用的一个包。React Native SDK它为Realm数据提供了状态感知的React钩子。这些钩子会监视Realm数据并根据需要重新呈现组件。

React Native SDK 文档使用 @realm/react npm 包作为示例并描述概念。

请参阅以下页面了解更多详细信息：

设置您的 Realm 应用

安装 realm 和 @realm/react 包后，您还需要进行一些设置，然后才能访问您的 Realm 并使用本地数据：

定义对象模型
配置 Realm，包括创建 Realm 上下文对象、提取钩子和设置提供者

定义对象模型

应用程序的对象模型定义了可在 Realm 中存储的数据类型。每个对象模型都成为一个 Realm 对象类型。

要定义 Realm 对象模型：

创建一个扩展Realm.Object 的类。
添加一个 schema 字段。
为 schema 值创建一个包含 properties 和 name 属性的对象。您 realm 中的名称值必须是唯一的。

// Define your object model
export class Profile extends Realm.Object<Profile> {
  _id!: BSON.ObjectId;
  name!: string;
  static schema: ObjectSchema = {
    name: 'Profile',
    properties: {
      _id: 'objectId',
      name: {type: 'string', indexed: 'full-text'},
    },
    primaryKey: '_id',
  };
}

要了解更多信息，请参阅定义 Realm 对象模型。

配置 Realm

在使用数据之前，您需要先配置一个 Realm。这意味着您需要从 @realm/react 中设置上下文和提供者。要了解更多信息，请参阅配置 Realm。

要配置和访问本地 Realm，请执行以下操作：

从 @realm/react 导入 RealmProvider。
将对象模型传递给 schema 属性。
将其他配置对象属性作为属性添加到RealmProvider 。

import React from 'react';
import {RealmProvider} from '@realm/react';
// Import your models
import {Profile} from '../../../models';
export const AppWrapper = () => {
  return (
    <RealmProvider schema={[Profile]}>
      <RestOfApp />
    </RealmProvider>
  );
};

处理 Realm 对象

拥有数据模型和配置的 Realm 之后，您可以创建、读取、更新或删除 Realm 对象。

您必须将执行这些操作的任何组件嵌套在 RealmProvider 内。借助 useRealm()、useQuery() 和 useObject() 钩子，您可以在 Realm 中执行读取和写入操作。

有关 RealmProvider 及其钩子的详细说明，请参阅 RealmProvider (@realm/react)

读取、排序和过滤对象

@realm/react 提供钩子来帮助您查找 Realm 对象的集合或单个 Realm 对象。

作为 useQuery() 的一部分，您可以使用 Realm 查询语言 (RQL) 对结果进行筛选或排序。

import React from 'react';
import {useQuery} from '@realm/react';
import {Profile} from '../../models';
export const Read = () => {
  // Find
  const profiles = useQuery(Profile);
  // Sort
  const sortedProfiles = useQuery(Profile, profiles => {
    return profiles.sorted('name', false);
  });
  // Filter
  const filteredProfiles = useQuery(Profile, profiles => {
    return profiles.filtered('name == "testProfile"');
  });
  // ... rest of component
};

要了解更多信息，请参阅 CRUD - 读取和查询数据。

钩子之外的读取操作

有时，您可能需要使用 Realm 读取操作，但不需要在 React Native 组件的顶层使用。由于钩子仅在组件的顶层起作用，因此在这些情况下不能使用 @realm/react 钩子。

相反，您可以使用 Realm.objects 作为集合，或者使用 Realm.objectForPrimaryKey 作为单个对象。

创建、更新和删除 Realm 对象

使用useRealm()访问域后，您可以创建、更新和删除域内的对象。所有操作必须在 Realm.write() 中事务块。

要了解更多信息，请参阅写事务。

创建对象

要创建新的 Realm 对象，请指定对象类型，传入对象的初始值，然后在写事务块中将其添加到 Realm。

import React, {useState} from 'react';
import {Text, TextInput, View} from 'react-native';
import {BSON} from 'realm';
import {useRealm} from '@realm/react';
import {Profile} from '../../models';
export const Create = () => {
  const realm = useRealm();
  const [profileName, setProfileName] = useState('');
  const addProfile = () => {
    realm.write(() => {
      realm.create(Profile, {
        _id: new BSON.ObjectId(),
        name: profileName,
      });
    });
  };
  return (
    <View>
      <Text>Create</Text>
      <TextInput
        onChangeText={setProfileName}
        value={profileName}
        placeholder="Profile name..."
      />
      <Button
        title="Add Profile"
        onPress={addProfile}
      />
    </View>
  );
};

要了解更多信息，请参阅增删改查 - 创建。

更新对象

要更新 Realm 对象，请在写事务块中更新其属性。

import React, {useState} from 'react';
import {Text, FlatList, View, Pressable, TextInput} from 'react-native';
import {useRealm, useQuery} from '@realm/react';
import {Profile} from '../../models';
export const Update = () => {
  const realm = useRealm();
  const profiles = useQuery(Profile);
  const [profileToUpdate, setProfileToUpdate] = useState('');
  const [newProfileName, setNewProfileName] = useState('');
  const updateProfile = () => {
    const toUpdate = realm
      .objects(Profile)
      .filtered('name == $0', profileToUpdate);
    realm.write(() => {
      toUpdate[0].name = newProfileName;
    });
  };
  return (
    <View>
      <Text>Update</Text>
      {profiles.length ? (
        <View>
          <Text>Profiles: </Text>
          <FlatList
            scrollEnabled={false}
            data={profiles}
            horizontal={true}
            renderItem={({item}) => (
              <Pressable
                onPress={() => {
                  setProfileToUpdate(item.name);
                }}>
                <Text
                 >
                  {item.name}
                </Text>
              </Pressable>
            )}
            keyExtractor={item => item.name}
          />
        </View>
      ) : (
        <Text>🛑 No profiles found</Text>
      )}
      {profileToUpdate && (
        <TextInput
          style={styles.textInput}
          onChangeText={setNewProfileName}
          value={newProfileName}
          placeholder="New profile name..."
        />
      )}
      <Button
        title="Update profile"
        onPress={updateProfile}
      />
    </View>
  );
};

要了解更多信息，请参阅 CRUD - 更新。

删除对象

要删除 Realm 对象，请在写事务块内将该对象传递给 Realm.Delete ()。

import React, {useState} from 'react';
import {Text, FlatList, View, Pressable} from 'react-native';
import {useRealm, useQuery} from '@realm/react';
import {Profile} from '../../models';
export const Delete = () => {
  const realm = useRealm();
  const profiles = useQuery(Profile);
  const [profileToDelete, setProfileToDelete] = useState('');
  const deleteProfile = () => {
    const toDelete = realm
      .objects(Profile)
      .filtered('name == $0', profileToDelete);
    realm.write(() => {
      realm.delete(toDelete);
    });
  };
  return (
    <View>
      <Text>Delete</Text>
      {profiles.length ? (
        <View>
          <Text>Profiles: </Text>
          <FlatList
            scrollEnabled={false}
            data={profiles}
            horizontal={true}
            renderItem={({item}) => (
              <Pressable
                onPress={() => {
                  setProfileToDelete(item.name);
                }}>
                <Text
                 >
                  {item.name}
                </Text>
              </Pressable>
            )}
            keyExtractor={item => item.name}
          />
        </View>
      ) : (
        <Text>🛑 No profiles found</Text>
      )}
      <Button
        title="Delete profile"
        onPress={deleteProfile}
      />
    </View>
  );
};

要了解更多信息，请参阅 CRUD - 删除。

添加 Atlas Device Sync（可选）

运行非同步 Realm 后，您可以添加 Atlas Device Sync。以便 Realm 的数据能够与 MongoDB Atlas 集群和其他客户端设备同步。

要使用 Device Sync，您需要再进行一些设置：

在 Atlas App Services 中创建后端（请参阅下面的前提条件）
配置灵活同步 Realm，而不是非同步 Realm

先决条件

App Services App
在用户界面中启用匿名身份验证Atlas App Services
在开发模式开启的情况下启用了 Flexible Sync

配置和访问同步 Realm

要使用 Device Sync，需要配置三个 @realm/react 提供程序：

初始化应用、完成用户身份验证并定义对象模型后，您可以配置同步 Realm。这类似于配置本地 Realm。不过，您需要为 RealmProvider 添加一些额外的属性。

将sync属性添加到RealmProvider并为其传递FlexibleSyncConfiguration对象。此同步对象必须包含flexible: true 。您还应该添加初始订阅。您必须拥有至少一个同步订阅，才能读取或写入同步数据。

要配置和访问同步 Realm，请执行以下操作：

使用 AppProvider 初始化应用。您可以在 App Services 用户界面中找到您的 App ID。
使用以下内容对用户进行身份验证： UserProvider
使用以下内容配置同步 Realm： RealmProvider

import React from 'react';
import {Credentials} from 'realm';
import {RealmProvider, AppProvider, UserProvider, useApp} from '@realm/react';
// Import your models
import {Profile} from '../../../models';
// Expose a sync realm
export function AppWrapperSync() {
  return (
    <AppProvider id={APP_ID}>
      <UserProvider fallback={LogIn}>
        <RealmProvider
          schema={[Profile]}
          sync={{
            flexible: true,
            onError: (_session, error) => {
              console.log(error);
            },
            initialSubscriptions: {
              update(subs, realm) {
                subs.add(realm.objects('Profile'));
              },
              rerunOnOpen: true,
            },
          }}
          fallback={fallback}>
          <RestOfApp />
        </RealmProvider>
      </UserProvider>
    </AppProvider>
  );
}

在同步 Realm 中创建、读取、更新和删除对象的语法与适用于非同步 Realm 的语法相同。当您使用本地数据时，后台线程可以高效地集成、上传和下载变更集。

要了解更多信息，请参阅配置同步 Realm。

下一步：查看模板应用程序和教程

如果你对引导式体验感兴趣，可以阅读我们的 Realm React Native SDK 教程。本教程实现并扩展了使用 Realm 和 Device Sync 构建的基础 React Native 应用。

您还可以使用模板应用来自行开展 React Native SDK 实验。要设置模板应用，请参阅 Atlas App Services 文档中的模板应用部分。

来年

欢迎使用 Atlas Device SDK 文档