快速入门 - Kotlin SDK
在此页面上
此页面包含通过Kotlin SDK快速使用Realm的信息。 可选的 Add Device Sync部分说明了如何将Atlas Device Sync集成到您的应用程序中。
开始之前，请确保您已安装适用于平台的 Kotlin SDK。
注意
使用 KMP 快速入门
如果在新的 Kotlin Multiplatform (KMP) 模板项目中运行此项目，则可以将以下代码段复制并粘贴到commonMain 模块中的 Greeting.greeting() 方法中。
定义对象模型
应用程序的数据模型定义了 Realm 中所存储数据的结构。您可通过应用程序代码（附带 Realm 对象模式）中的 Kotlin 类来定义应用程序的数据模型。
要定义应用程序的数据模型，请将类定义添加到应用程序代码中。以下示例说明了如何创建“项目”模型，该模型表示待办事项列表应用中的待办事项。
class Item() : RealmObject { var _id: ObjectId = ObjectId() var isComplete: Boolean = false var summary: String = "" var owner_id: String = "" constructor(ownerId: String = "") : this() { owner_id = ownerId } }
打开 Realm
使用 RealmConfiguration.create() 使用默认参数打开域。将配置传递给 Realm 工厂构造函数，以生成该域的实例：
val config = RealmConfiguration.create(schema = setOf(Item::class)) val realm: Realm = Realm.open(config)
有关如何控制要打开的RealmConfiguration的细节（例如 名称、位置、模式版本），请参阅打开和关闭 Realm。
创建、读取、更新和删除对象
打开后，您可以在写事务区块中的 Realm 内创建对象。
若要创建新的Item，请实例化一个Item类实例，并以写事务区块形式将其添加到 Realm 中：
realm.writeBlocking { copyToRealm(Item().apply { summary = "Do the laundry" isComplete = false }) }
您可以使用query.find() 检索 Realm 中所有 Todo 项目的集合：
// all items in the realm val items: RealmResults<Item> = realm.query<Item>().find()
您还可以筛选集合，以检索更具体的对象集合：
// items in the realm whose name begins with the letter 'D' val itemsThatBeginWIthD: RealmResults<Item> = realm.query<Item>("summary BEGINSWITH $0", "D") .find() // todo items that have not been completed yet val incompleteItems: RealmResults<Item> = realm.query<Item>("isComplete == false") .find()
在筛选数据中查找有关字符串 Realm 查询的更多信息。
要修改 Todo 项目，请在写事务区块中更新其属性：
// change the first item with open status to complete to show that the todo item has been done realm.writeBlocking { findLatest(incompleteItems[0])?.isComplete = true }
最后，您可以在写事务块中调用 mutableRealm.delete() 删除 Todo 条目：
// delete the first item in the realm realm.writeBlocking { val writeTransactionItems = query<Item>().find() delete(writeTransactionItems.first()) }
注意更改
可以使用 observe方法观察 realm、集合或对象的更改。
重要
无服务器限制
如果数据源为 Atlas 无服务器实例，则无法监控是否出现更改。MongoDB 无服务器当前不支持变更流，而变更流可用于受监视的集合以侦听是否存在更改。
在以下示例中，我们侦听所有 Item 对象的更改。
// flow.collect() is blocking -- run it in a background context val job = CoroutineScope(Dispatchers.Default).launch { // create a Flow from the Item collection, then add a listener to the Flow val itemsFlow = items.asFlow() itemsFlow.collect { changes: ResultsChange<Item> -> when (changes) { // UpdatedResults means this change represents an update/insert/delete operation is UpdatedResults -> { changes.insertions // indexes of inserted objects changes.insertionRanges // ranges of inserted objects changes.changes // indexes of modified objects changes.changeRanges // ranges of modified objects changes.deletions // indexes of deleted objects changes.deletionRanges // ranges of deleted objects changes.list // the full collection of objects } else -> { // types other than UpdatedResults are not changes -- ignore them } } } }
稍后，当您观察完毕后，取消作业以取消协程：
job.cancel() // cancel the coroutine containing the listener
关闭 Realm
要关闭 Realm 和所有底层资源，请调用realm.close() 。 close()方法会阻塞，直到 Realm 上的所有写事务都完成为止。
realm.close()
添加 Device Sync（可选）
本节说明如何使用“匿名用户”进行身份验证，并打开“灵活同步 Realm”以开始在设备间同步数据。
先决条件
本部分中的代码片段需要满足：
在 用户界面中 启用匿名身份验证Atlas App Services
在打开 开发模式 和
owner_id部分中的Queryable Fields 字段的情况下 启用 Flexible Sync
初始化 App Services
要使用身份验证和同步等 App Services 功能，请使用您的App ID 访问 App Services 应用。您可在 App Services 用户界面中找到您的 App ID。
val app = App.create(YOUR_APP_ID)
验证用户身份
如需验证和登录用户，请调用 App.login。启用匿名身份验证后，用户无需提供任何身份信息即可立即登录应用程序：
val credentials = Credentials.anonymous() val user = app.login(credentials)
打开同步 Realm
初始化 Atlas App Services App、验证用户身份并定义对象模型后，您可以创建SyncConfiguration。
如果您在上面的“打开 Realm ”部分中打开了本地 Realm，请将RealmConfiguration替换为下面所述的SyncConfiguration 。
将经过身份验证的用户和Item类传递给SyncConfiguration.Builder函数以创建Flexible Sync 配置。
重要
首次订阅
您至少需要一个订阅，然后才能读取或写入 Realm。 使用initialSubscriptions可定义首次打开 Realm 文件时的初始订阅集。 将要订阅的查询和订阅名称传递给add()函数。
以下示例指定了名为“用户条目”的订阅，其中包含所有 Item 对象。
// create a SyncConfiguration val config = SyncConfiguration.Builder( user, setOf(Item::class) ) // the SyncConfiguration defaults to Flexible Sync, if a Partition is not specified .initialSubscriptions { realm -> add( realm.query<Item>( "owner_id == $0", // owner_id == the logged in user user.id ), "User's Items" ) } .build() val realm = Realm.open(config)
下一步：查看模板应用程序和教程
查看模板应用，尝试另一种使用 Realm Kotlin SDK 开始编码的快速方法。 标记为android.kotlin.todo.flex的 Kotlin SDK 模板是一个预制应用程序，它将 Realm 和 Atlas Device Sync 集成到可自定义的 Android 应用中。
或者，如果您对指导体验感兴趣，可以阅读我们的 Android with Kotlin SDK 教程，该教程对模板应用程序进行了扩展。