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

快速入门 — Flutter SDK

在此页面上

  • 定义对象模型
  • 创建数据模型
  • 生成 RealmObject 类
  • 打开 Realm
  • 使用 Realm 对象
  • 创建对象
  • 更新对象
  • 查询对象
  • 删除对象
  • 响应变更
  • 关闭 Realm
  • 将 Realm 与 MongoDB Atlas 同步
  • 先决条件
  • 初始化 App Services
  • 验证用户身份
  • 打开同步 Realm
  • 添加同步订阅
  • 更多示例和后续步骤

此页面包含快速将 Realm 集成到 Flutter 应用程序中的信息。

开始之前，请确认您已：

  • 已安装 Flutter SDK

定义对象模型

应用程序的数据模型定义了Realm中存储的数据结构。 您可以使用Realm 对象模式，通过应用程序代码中的Dart类来定义应用程序的数据模型。 然后，您必须生成 RealmObjectBase 应用程序中使用的类。

有关更多信息，请参阅定义 Realm 对象模式。

创建数据模型

要定义应用程序的数据模型，请将 Realm 模型类定义添加到应用程序代码中。

定义 Realm 模型类时部分考虑因素：

  • 在类定义文件的顶部导入包。

  • 在文件中，为类指定一个私有名称（以 _ 开头），例如附带 _Car 类的 car.dart 文件。可以使用以下“生成 RealmObject 类”部分中的命令生成公共 RealmObject 类。此命令可输出公共类，例如 Car。

  • 确保在定义模型的代码之前包含生成的文件名，例如part car.realm.dart。这是生成 RealmObject 类的必要条件。

car.dart
import 'package:realm/realm.dart';
part 'car.realm.dart';
@RealmModel()
class _Car {
  @PrimaryKey()
  late ObjectId id;
  late String make;
  late String? model;
  late int? miles;
}
car.dart
import 'package:realm_dart/realm.dart';
part 'car.realm.dart';
@RealmModel()
class _Car {
  @PrimaryKey()
  late ObjectId id;
  late String make;
  late String? model;
  late int? miles;
}

生成 RealmObject 类

现在从数据模型类 CarCar 生成 RealmObject 类：

dart run realm generate
dart run realm_dart generate

运行此命令会在位于此目录的 car.realm.dart 文件中创建 Car 类，而您已在该目录中根据前面的“创建数据模型”部分定义了模型类。此 Car 类为公共类，且与 _Car 数据模型类同属于同一库。生成的 Car 类是在整个应用程序中使用的类。

如果希望每当 _Car 发生更改时观察数据模型类生成新的 Car 类，则运行：

dart run realm generate --watch
dart run realm_dart generate --watch

打开 Realm

使用配置类来控制您要打开的域的细节，包括模式以及该域为仅陷本地还是已同步的域。

将您的配置传递给 Realm 构造函数 以生成该域的实例：

final config = Configuration.local([Car.schema]);
final realm = Realm(config);

现在，您可使用该 Realm 实例来处理数据库中的对象。

有关更多信息，请参阅配置和打开 Realm。

使用 Realm 对象

打开 Realm 后，您可以使用 写事务区块在其中创建对象。

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

创建对象

若要创建新的Car，请实例化一个Car类实例，并以写事务区块形式将其添加到 Realm 中：

final car = Car(ObjectId(), 'Tesla', model: 'Model S', miles: 42);
realm.write(() {
  realm.add(car);
});

更新对象

要修改汽车，则在写事务区块中更新其属性：

realm.write(() {
  car.miles = 99;
});

查询对象

使用 Realm.all () 方法检索域中数据模型所有对象的集合：

final cars = realm.all<Car>();
final myCar = cars[0];
print('My car is ${myCar.make} ${myCar.model}');

筛选集合以使用 Realm 检索特定的对象段。 查询()方法。 在 query() 方法的参数中，使用RQL运算符执行筛选。

final cars = realm.query<Car>('make == "Tesla"');

删除对象

通过在写事务块中调用 Realm.delete() 来删除一个 car。

realm.write(() {
  realm.delete(car);
});

响应变更

监听并响应对查询、单个对象或对象中列表的更改。变更监听器是一个流，它可以调用回调函数，其中包含自上次调用以来的更改作为其参数。

要监听查询，请使用 RealmResults.changes.listen()。

// Listen for changes on whole collection
final characters = realm.all<Character>();
final subscription = characters.changes.listen((changes) {
  changes.inserted; // Indexes of inserted objects.
  changes.modified; // Indexes of modified objects.
  changes.deleted; // Indexes of deleted objects.
  changes.newModified; // Indexes of modified objects after accounting for deletions & insertions.
  changes.moved; // Indexes of moved objects.
  changes.results; // The full List of objects.
  changes.isCleared; // `true` after call to characters.clear(); otherwise, `false`.
});
// Listen for changes on RealmResults.
final hobbits = fellowshipOfTheRing.members.query('species == "Hobbit"');
final hobbitsSubscription = hobbits.changes.listen((changes) {
  // ... all the same data as above
});

您也可以暂停和恢复订阅。

subscription.pause();
// The changes.listen() method won't fire until subscription is resumed.
subscription.resume();

监听完变更后，关闭变更监听器以防止内存泄漏。

await subscription.cancel();

有关更多信息，请参阅响应变更。

关闭 Realm

使用完某个 realm 后，将其关闭以防止内存泄漏。

realm.close();

将 Realm 与 MongoDB Atlas 同步

您可以将 Realm 和 Atlas Device Sync 集成到 Flutter 应用中。Atlas Device Sync 是一项 MongoDB Atlas App Service，可在客户端应用程序与 Atlas 上的 MongoDB 数据库集群之间同步数据。

为了使用“设备同步”与 Atlas 同步数据，Flutter SDK 使用了“Flexible Sync”。通过“Flexible Sync”，您可以对从客户端应用程序同步的数据定义查询。

注意

您无需添加 Device Sync 即可在本地使用 Realm。

先决条件

在客户端应用程序中将 Device Sync 与 Realm 结合使用之前，必须使用 Atlas App Services 配置 Device Sync：

  1. 创建 App Services App

  2. 启用匿名身份验证

  3. 启用 Flexible Sync 。 将owner_id设置为可查询字段。

  4. 定义规则，确定用户在使用Device Sync时拥有哪些权限。 对于此示例，我们分配了一个默认角色，该角色适用于任何没有特定于集合的角色的集合。 在此示例中，用户可以读取和写入数据，其中登录用户的user.id owner_id与对象的 匹配：

    {
      "roles": [
        {
          "name": "owner-read-write",
          "apply_when": {},
          "document_filters": {
            "write": {
              "owner_id": "%%user.id"
            },
            "read": {
              "owner_id": "%%user.id"
            }
          },
          "read": true,
          "write": true,
          "insert": true,
          "delete": true,
          "search": true
        }
      ]
    }

现在，部署您的应用程序更新。

提示

使用 Realm Flutter 模板应用

如果您想要一个正常运行的 Flutter应用，并且已经在客户端和该 App Service后端设立了Device Sync ，请使用Flutter 模板应用程序flutter.todo.flex 。

初始化 App Services

要使用身份验证和同步等 App Services 功能，请使用您的App ID 访问 App Services 应用。您可在 App Services 用户界面中找到您的 App ID。

final app = App(AppConfiguration(appId));

有关更多信息，请参阅连接到 App Services。

验证用户身份

在 App Services 用户界面中启用匿名身份验证后，用户无需提供任何识别信息即可立即登录您的应用：

final loggedInUser = await app.logIn(Credentials.anonymous());

更多信息，请参阅验证用户身份。

打开同步 Realm

启用Device Sync并对用户进行身份验证后，使用 Configuration.FlexibleSync() 打开同步域 。然后，将配置传递给 Realm () 打开域的一个实例。同步域 必须 具有不同的 Configuration.path 来自其他打开的仅限本地 Realm。

final config = Configuration.flexibleSync(loggedInUser, [Todo.schema]);
final realm = Realm(
  config,
);

有关更多信息，请参阅打开已同步 Realm。

添加同步订阅

现在创建订阅，使用 Device Sync 与 Atlas 同步数据。 在 SubscriptionSet.update() 中添加订阅回调函数。

更新区块回调函数，包括 MutableSubscriptionSet() 对象作为参数。使用MutableSubscriptionSet.add()添加新订阅。

// Check if the subscription already exists before adding
final userTodoSub = realm.subscriptions.findByName('getUserTodos');
if (userTodoSub == null) {
  realm.subscriptions.update((mutableSubscriptions) {
    // server-side rules ensure user only downloads their own Todos
    mutableSubscriptions.add(realm.all<Todo>(), name: 'getUserTodos');
  });
}

有关更多信息，请参阅管理同步订阅。

更多示例和后续步骤

来年

欢迎使用 Atlas Device SDK 文档