定义 Realm 对象模式 - Flutter SDK

创建模型

import 'package:realm/realm.dart';

import 'package:realm_dart/realm.dart';

part 'schemas.realm.dart';

@RealmModel()
class _Car {
  @PrimaryKey()
  late ObjectId id;
  late String make;
  late String? model;
  late int? miles;
}

dart run realm generate

dart run realm_dart generate

.
├── schemas.dart
├── schemas.realm.dart // newly generated file
├── myapp.dart
└── ...rest of application

import './schemas.dart';
final hondaCivic = Car(ObjectId(), 'Honda', model: 'Civic', miles: 99);

将模式与 Device Sync 一起使用

App Services 模式是有效对象模式的列表，每个模式定义应用可以保留的对象类型。Realm 中的所有同步对象都必须符合 App Services 模式。

客户端应用程序在打开 Realm 时提供对象模式。如果 Realm 已包含数据，则它已具有模式，并且当打开该 Realm 时，它会根据现有模式验证客户端上的模式。

可以通过以下方式定义 App Services 模式：

• 如果启用了开发模式，则自动使用对象模式。

• 使用 App Services 显式定义 App Services 模式。

在模式中，必须将 MapTo("_id") 注解与 RealmModel 中的主键结合使用，才能成功将对象模式与 App Services 同步。

@RealmModel()
class _SyncSchema {
  @PrimaryKey()
  @MapTo("_id")
  late ObjectId id;
  // ... other properties
}

有关定义模式以及应考虑将哪些方法用于应用程序的更多信息，请参阅创建 Realm 模式文档。

支持的数据类型

Realm 模式支持许多 Dart 语言数据类型，此外还有一些 Realm 特定类型。要全面了解所有支持的数据类型，请参阅数据类型。

属性注解

使用注解为 Realm 对象模型中的属性添加功能。可以使用注解来执行将属性标记为可为空、设置主键、忽略属性等操作。要进一步了解可用的属性注解，请参阅属性注解。

定义关系属性

可以定义模式中 Realm 对象之间的关系。Realm Flutter SDK 支持一对一关系、一对多关系、反向关系以及将对象嵌入其他对象中。要详细了解如何在 Realm 对象模式中定义关系，请参阅关系。

将模型或类映射到其他名称

您可以使用 MapTo 注解将 Realm 对象模型或属性映射到 Realm 中存储的不同名称。这在以下场景中非常有用。例如：

• 要便于在具有不同命名约定的多个平台上工作。例如，如果 Device Sync 模式属性名称使用蛇形大小写，而项目使用驼峰大小写。

• 在不强制迁移的情况下更改类名或字段名。

• 支持不同数据包中的多个同名模型类。

• 要使用长度大于 Realm 执行的 57 个字符限制的类名。

如果使用的是 Atlas Device Sync，则在 MapTo 注解中指定的名称用作持久的 App Services 模式名称。

@RealmModel()
@MapTo('naval_ship')
class _Boat {
  @PrimaryKey()
  late ObjectId id;
  late String name;
  late int? maxKnots;
  late int? nauticalMiles;
}

class _Vehicle {
  @PrimaryKey()
  late ObjectId id;
  late String? maybeDescription; // optional value
  late double milesTravelled = 0; // 0 is default value
  @Ignored()
  late String notInRealmModel;
  @Indexed()
  late String make;
  @MapTo('wheels') // 'wheels' is property name in the RealmObject
  late int numberOfWheels;
}

对非结构化数据进行建模

从Flutter SDK版本2.0.0开始， 您可以在RealmValue属性中存储混合数据的集合。 您可以使用此功能对复杂的数据结构（例如JSON或MongoDB文档）进行建模，而无需定义严格的数据模型。

非结构化数据是指不容易符合预期模式的数据，因此对单个数据类进行建模很困难或不切实际。 示例，您的应用可能具有高度可变的数据或动态数据，其结构在运行时未知。

将集合存储在混合属性中可在不牺牲功能的情况下提供灵活性，包括使用Device Sync时的性能同步。 您可以像使用非混合集合一样使用它们：

• 您最多可以嵌套100级混合集合。

• 您可以对混合集合的React进行查询和响应。

• 您可以查找并更新单个混合集合元素。

但是，与使用结构化模式或将JSON blob 序列化为单个string属性相比，在混合集合中存储数据的性能较低。

要对应用中的非结构化数据进行建模，请在模式中将相应属性定义为RealmValue类型。 然后，您可以设立这些RealmValue属性设置为RealmValue元素的RealmList或RealmMap集合。 请注意， RealmValue不能表示RealmSet或嵌入式对象。

示例，在对变量事件日志对象建模时，您可以使用包含混合数据映射的RealmValue ：

// Define class with a `RealmValue` property
@RealmModel()
class _EventLog {
  @PrimaryKey()
  late ObjectId id;
  late String eventType;
  late DateTime timestamp;
  late String userId;
  late RealmValue details;
}

realm.write(() {
  // Add `eventLog` property data as a map of mixed data, which 
  // also includes nested lists of mixed data 
  realm.add(EventLog(ObjectId(), 'purchase', DateTime.now(), 'user123',
      details: RealmValue.from({
        'ipAddress': '192.168.1.1',
        'items': [
          {'id': 1, 'name': 'Laptop', 'price': 1200.00},
          {'id': 2, 'name': 'Mouse', 'price': 49.99}
        ],
        'total': 1249.99
      })));
  final eventLog = realm.all<EventLog>().first;
  final items = eventLog.details.asMap();
  print('''
      Event Type: ${eventLog.eventType}
      Timestamp: ${eventLog.timestamp}
      User ID: ${eventLog.userId}
      Details:
        Item: 
  ''');
  for (var item in items.entries) {
    print('${item.key}: ${item.value}');
  }

Event Type: purchase
Timestamp: 2024-03-18 13:50:58.402979Z
User ID: user123
Details:
Item:
   ipAddress: RealmValue(192.168.1.1)
   items: RealmValue([RealmValue({id: RealmValue(1), name: RealmValue(Laptop), price: RealmValue(1200.0)}), RealmValue({id: RealmValue(2), name: RealmValue(Mouse), price: RealmValue(49.99)})])
   total: RealmValue(1249.99)

生成 RealmObject

完成 Realm 模型后，您必须生成 RealmObject 类才能在应用程序中进行使用。

运行以下命令以生成 RealmObjects：

dart run realm generate

dart run realm_dart generate

运行此命令会在您根据“创建模型”部分定义RealmModel类的目录中的新文件中创建一个公共类。

生成的文件与带有 RealmModel 的文件具有相同的基本名称，以 .realm.dart 结尾。例如，如果带有 RealmModel 的文件名为 schemas.dart，则生成的文件将为 schemas.realm.dart。

// ...import packages
part 'schemas.realm.dart';
@RealmModel()
// ...model definition

如果您希望观察数据模型在发生更改时生成 RealmObjects，请在命令中包含 --watch 标志。

dart run realm generate --watch

dart run realm_dart generate --watch

要清理生成器缓存，请在命令中加入 --clean 标志。进行调试时，清理生成器缓存可能很有用。

dart run realm generate --clean

dart run realm_dart generate --clean

定义非对称对象

非对称对象需要灵活同步。要定义非对称对象，请将 ObjectType.asymmetricObject 传递给 @RealmModel()。

@RealmModel(ObjectType.asymmetricObject)
class _WeatherSensor {
  @PrimaryKey()
  @MapTo("_id")
  late ObjectId id;
  late String deviceId;
  late double modtemperatureInFahrenheitel;
  late double barometricPressureInHg;
  late double windSpeedInMph;
}

在 Flutter SDK 版本 1.5.0 及更早版本中，您无法从 asymmetricObject 类型链接到 RealmObjects。在 SDK 版本 1.6.0 及更高版本中，除了嵌入式对象类型外，asymmetricObject 类型还可以链接到 RealmObjects。

要了解有关数据导入的更多信息，请参阅将数据流式传输到 Atlas。