[!WARNING] 我们于 2024 年 9 月宣布弃用 Atlas Device Sync + Realm SDKs。更多信息请参阅：

SDK Deprecation

Device Sync Deprecation

如需不包含同步功能的 realm-dart 版本，请安装版本 20 或查看 community 分支。

Realm 是一款直接运行在手机、平板电脑或可穿戴设备中的移动数据库。本仓库包含 Flutter™ 和 Dart™ 的 Realm SDK 源代码。

功能

移动优先： Realm 是首款从底层构建、直接运行在手机、平板电脑和可穿戴设备中的数据库。
简单： Realm 的面向对象数据模型易于学习，无需 ORM，且 API 让你用更少的代码在几分钟内让应用运行起来。
现代： Realm 支持最新的 Dart 和 Flutter 版本，并基于健全的空安全性构建。
快速： 在常见操作下，Realm 比原生 SQLite 更快，同时保持极其丰富的功能集。
MongoDB Atlas Device Sync：让跨用户、设备和后端的实时数据同步变得简单。使用模板应用免费开始，并创建云后端。

入门指南

在 dart 文件中导入 Realm app.dart

import 'package:realm/realm.dart';  // import realm package

part 'app.realm.dart'; // declare a part file.

@RealmModel() // define a data model class named `_Car`.
class _Car {
  late String make;

  late String model;

  int? kilometers = 500;
}

从数据模型类 _Car 生成 RealmObject 类 Car。
```
dart run realm generate
```

打开一个 Realm 并添加一些对象。

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

var car = Car("Tesla", "Model Y", kilometers: 5);
realm.write(() {
  realm.add(car);
});

在 Realm 中查询对象。

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

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

获取查询的结果变更流。

final cars = realm.all<Car>().query(r'make == $0', ['Tesla']);
cars.changes.listen((changes) {
  print('Inserted indexes: ${changes.inserted}');
  print('Deleted indexes: ${changes.deleted}');
  print('Modified indexes: ${changes.modified}');
});
realm.write(() => realm.add(Car('VW', 'Polo', kilometers: 22000)));

示例

完整示例请参见 Realm Flutter and Dart Samples。

文档

API 文档请访问

Flutter 应用请使用 realm 包，Dart 应用请使用 realm_dart 包。

SDK 的完整文档，请访问 Realm SDK documentation。

如果您是首次使用 Realm SDK，请参阅 Quick Start documentation。

要了解如何使用 Realm 配合 Atlas App Services 和 Device Sync，请参阅以下 Realm SDK 文档：

Realm Flutter SDK

Realm Flutter 包已发布至 realm。

Realm Flutter 环境配置

Realm Flutter 支持 iOS、Android、Windows、MacOS 和 Linux 平台。
Flutter 3.10.2 或更高版本。
关于 Flutter 桌面环境配置，请参阅 Desktop support for Flutter。
Cocoapods v1.11 或更高版本。
CMake 3.21 或更高版本。

用法

catalog.dart 的完整内容列于 usage 之后

将 realm 包添加到 Flutter 应用中。
```
flutter pub add realm
```
要运行 Flutter 小部件测试和单元测试，请运行以下命令以安装所需的原生二进制文件。
```
dart run realm install
```
在 dart 文件中导入 Realm（例如 catalog.dart）。
```
import 'package:realm/realm.dart';
```
在 catalog.dart dart 文件的所有导入之后，在文件开头声明一个 part 文件 catalog.realm.dart。
```
import 'dart:io';

part 'catalog.realm.dart';
```

创建一个数据模型类。

它应以下划线 _Item 开头，并使用 @RealmModel() 进行注解

@RealmModel()
class _Item {
    @PrimaryKey()
    late int id;

    late String name;

    int price = 42;
}

从数据模型类 _Item 生成 RealmObject 类 Item。

在 Flutter 中使用 dart run realm 运行 realm 包命令
```
dart run realm generate
```
将在 catalog.dart 旁边创建新文件 catalog.realm.dart。

*生成的文件应提交到源代码控制

使用 RealmObject 类 Item 与 Realm 配合使用。

// Create a Configuration object
var config = Configuration.local([Item.schema]);

// Opean a Realm
var realm = Realm(config);

var myItem = Item(0, 'Pen', price: 4);

// Open a write transaction
realm.write(() {
    realm.add(myItem);
    var item = realm.add(Item(1, 'Pencil')..price = 20);
});

// Objects `myItem` and `item` are now managed and persisted in the realm

// Read object properties from realm
print(myItem.name);
print(myItem.price);

// Update object properties
realm.write(() {
    myItem.price = 20;
    myItem.name = "Special Pencil";
});

// Get objects from the realm

// Get all objects of type
var items = realm.all<Item>();

// Get object by index
var item = items[1];

// Get object by primary key
var itemByKey = realm.find<Item>(0);

// Filter and sort object
var objects = realm.query<Item>("name == 'Special Pencil'");
var name = 'Pen';
objects = realm.query<Item>(r'name == $0', [name]);

// Close the realm
realm.close();

`catalog.dart` 的完整内容

import 'package:realm/realm.dart';

part 'catalog.realm.dart';

@RealmModel()
class _Item {
    @PrimaryKey()
    late int id;

    late String name;

    int price = 42;
}

// Create a Configuration object
var config = Configuration.local([Item.schema]);

// Open a Realm
var realm = Realm(config);

var myItem = Item(0, 'Pen', price: 4);

// Open a write transaction
realm.write(() {
    realm.add(myItem);
    var item = realm.add(Item(1, 'Pencil')..price = 20);
});

// Objects `myItem` and `item` are now managed and persisted in the realm

// Read object properties from realm
print(myItem.name);
print(myItem.price);

// Update object properties
realm.write(() {
    myItem.price = 20;
    myItem.name = "Special Pencil";
});

// Get objects from the realm

// Get all objects of type
var items = realm.all<Item>();

// Get object by index
var item = items[1];

// Get object by primary key
var itemByKey = realm.find<Item>(0);

// Filter and sort object
var objects = realm.query<Item>("name == 'Special Pencil'");
var name = 'Pen';
objects = realm.query<Item>(r'name == $0', [name]);

// Close the realm
realm.close();

Realm Dart 独立 SDK

Realm Dart 包已发布至 realm_dart。

Realm Dart 环境配置

Realm Dart 支持 Windows、Mac 和 Linux 平台。
Dart SDK 3.0.2 或更高版本。

用法

将 realm_dart 包添加到 Dart 应用中。
```
dart pub add realm_dart
```
将 realm_dart 包安装到应用程序中。此操作会将所需的原生二进制文件下载并复制到应用目录。
```
dart run realm_dart install
```
在 dart 文件中导入 realm_dart（例如 catalog.dart）。
```
import 'package:realm_dart/realm.dart';
```
要使用 realm_dart 生成 RealmObject 类，请使用此命令。

在 Dart 中使用 dart run realm_dart 运行 realm_dart 包命令

    dart run realm_dart generate
    ```
    将在 `catalog.dart` 旁边创建新文件 `catalog.realm.dart`。

_*生成的文件应提交到源代码控制*

* Realm Dart SDK 的用法与上述 Realm Flutter 相同。

# 使用 Device Sync 通过 Realm Flutter 和 Dart 同步数据

本节介绍如何使用 Realm 配合 [Device Sync](https://www.mongodb.com/docs/realm/sdk/flutter/sync/) 以及如何连接到 [Atlas App Services](https://www.mongodb.com/docs/realm/sdk/flutter/app-services/)。

### I. 设置 Atlas App Services
  1. 在 [cloud.mongodb.com](https://cloud.mongodb.com) 上创建一个账户。请遵循以下说明：[注册新的 Atlas 账户](https://www.mongodb.com/docs/atlas/tutorial/create-atlas-account/#register-a-new-service-account)。
  1. 按照此处说明创建一个新的 App：[使用 Atlas App Services UI 创建 App](https://www.mongodb.com/docs/atlas/app-services/manage-apps/create/create-with-realm-ui)。
  1. 阅读 [Authentication Providers](https://www.mongodb.com/docs/atlas/app-services/authentication/providers/) 以了解如何配置适当的身份验证提供程序类型。
  1. 前往 **Device Sync** 菜单并 [启用 Flexible Sync](https://www.mongodb.com/docs/atlas/app-services/sync/configure/enable-sync/#enable-flexible-sync)。
  1. [查找并复制](https://www.mongodb.com/docs/atlas/app-services/reference/find-your-project-or-app-id/) 您新应用程序的 App ID。

### II. 使用 Realm 的设备同步

1. 初始化 App Services `App` 客户端并认证用户。

   ``` dart
   String appId = "<Atlas App ID>";
   final appConfig = AppConfiguration(appId);
   final app = App(appConfig);
   final user = await app.logIn(Credentials.anonymous());

Open a synced realm.

final config = Configuration.flexibleSync(user, [Task.schema]);
final realm = Realm(config);

添加同步订阅并写入数据。

只有匹配订阅中查询的数据才会同步到服务器，并且只有匹配订阅的数据才会下载到本地设备 realm 文件。

realm.subscriptions.update((mutableSubscriptions) {
mutableSubscriptions.add(realm.query<Task>(r'status == $0 AND progressMinutes == $1', ["completed", 100]));
});
await realm.subscriptions.waitForSynchronization();
realm.write(() {
  realm.add(Task(ObjectId(), "Send an email", "completed", 4));
  realm.add(Task(ObjectId(), "Create a meeting", "completed", 100));
  realm.add(Task(ObjectId(), "Call the manager", "init", 2));
});
realm.close();

要了解如何使用 Device Sync 通过 Realm 同步数据，请参阅 Sync 快速入门文档。

构建源码

有关构建源码的说明，请参阅 CONTRIBUTING.md。

行为准则

本项目遵循 MongoDB 行为准则。参与本项目即表示您承诺遵守此准则。请将不当行为报告至 community-conduct@mongodb.com。

许可证

Realm Flutter 和 Dart SDK 以及 Realm Core 均基于 Apache License 2.0 发布。

功能