Docs 菜单
Docs 主页
/
MongoDB Atlas
/
Atlas Device SDKs

快速入门 - React Native SDK

在此页面上

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

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

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

关于 @realm/react 包

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

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

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

设置您的 Realm 应用

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

  • 定义对象模型

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

定义对象模型

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

要定义 Realm 对象模型：

  1. 创建一个扩展Realm.Object 的类。

  2. 添加一个 schema 字段。

  3. 为 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，请执行以下操作：

  1. 从 @realm/react 导入 RealmProvider。

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

  3. 将其他配置对象属性作为属性添加到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

先决条件

配置和访问同步 Realm

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

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

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

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

  1. 使用 AppProvider 初始化应用。您可以在 App Services 用户界面中找到您的 App ID。

  2. 使用以下内容对用户进行身份验证： UserProvider

  3. 使用以下内容配置同步 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 文档