Realm
@frozen
public struct Realm
extension Realm: Equatable
一个Realm
实例(也称为“Realm”)代表一个 Realm 数据库。
Realm 可以存储在磁盘上(请参阅init(path:)
)或内存中(请参阅Configuration
)。
Realm
实例在内部缓存,构造等效的Realm
对象(例如,通过使用相同的路径或标识符)产生的开销有限。
如果您特别希望确保销毁Realm
实例(例如,如果您希望打开 Realm,检查某些属性,然后可能删除 Realm 文件并重新打开它),请将使用 Realm 文件的代码放在autoreleasepool {}
内,并确保没有其他强引用对其进行强引用。
警告
警告 未冻结的RLMRealm
实例受线程限制,不能跨线程或调度队列共享。 尝试这样做会导致抛出异常。 您必须在要与Realm交互的每个线程或队列上获取RLMRealm
的实例。 在获取RLMRealm
实例时,可以通过显式传入队列来将 Realm 限制为调度队列,而不是其打开所在的线程。 如果不这样做,尝试在分派到同一队列的多个区块中使用同一实例可能会失败,因为队列并不总是在同一线程上运行。
-
用于创建
Realm
实例的Configuration
值。声明
Swift
public var configuration: Configuration { get }
-
指示 Realm 是否包含任何对象。
声明
Swift
public var isEmpty: Bool { get }
-
获取默认 Realm 的实例。
默认 Realm 在 iOS 上作为default.realm保留在应用程序的文档目录中,在 OS X 上则保留在应用程序的Application 支持目录中。
默认 Realm 是使用默认
Configuration
创建的,可以通过将Realm.Configuration.defaultConfiguration
属性设置为新值来更改该默认值。抛出异常
如果无法初始化 Realm,则返回NSError
。声明
Swift
public init(queue: DispatchQueue? = nil) throws
参数
queue
用于限制 Realm 的可选调度队列。 如果给出,则可以在分派到给定队列的区块内而不是在当前线程上使用此 Realm 实例。
-
获取具有给定配置的
Realm
实例。抛出异常
如果无法初始化 Realm,则返回
NSError
。声明
Swift
public init(configuration: Configuration, queue: DispatchQueue? = nil) throws
参数
configuration
创建 Realm 时使用的配置值。
queue
用于限制 Realm 的可选调度队列。 如果给出,则可以在分派到给定队列的区块内而不是在当前线程上使用此 Realm 实例。
-
获取在指定文件 URL 持久保存的
Realm
实例。抛出异常
如果无法初始化 Realm,则返回
NSError
。声明
Swift
public init(fileURL: URL) throws
参数
fileURL
应保存 Realm 的文件的本地 URL。
-
异步打开 Realm 并将其传递到给定队列上的区块。
异步打开 Realm 会在分派到给定队列之前,在背景线程上执行使 Realm 进入可用状态(例如运行可能耗时的迁移)所需的所有工作。此外,同步 Realm 会等待操作开始下载并在本地可用时所有可用的远程内容。
传递给回调函数的 Realm 被限制在回调队列中,就像使用了
Realm(configuration:queue:)
一样。声明
Swift
@discardableResult public static func asyncOpen(configuration: Realm.Configuration = .defaultConfiguration, callbackQueue: DispatchQueue = .main, callback: @escaping (Result<Realm, Swift.Error>) -> Void) -> AsyncOpenTask
参数
configuration
打开 Realm 时使用的配置对象。
callbackQueue
应运行回调的调度队列。
callback
回调区块。 如果成功打开 Realm,则会将其作为参数传入。 否则,将改为将Go的
Swift.Error
传递到该区块。返回值
一个任务对象,可用于观察或取消异步打开。
-
异步打开 Realm 并将其传递到给定队列上的区块。
异步打开 Realm 会在分派到给定队列之前,在背景线程上执行使 Realm 进入可用状态(例如运行可能耗时的迁移)所需的所有工作。此外,同步 Realm 会等待操作开始下载并在本地可用时所有可用的远程内容。
传递给发布者的 Realm 被限制在回调队列中,就像使用了
Realm(configuration:queue:)
一样。声明
Swift
@available(macOS 10.15, watchOS 6.0, iOS 13.0, iOSApplicationExtension 13.0, macOSApplicationExtension 10.15, tvOS 13.0, *) public static func asyncOpen(configuration: Realm.Configuration = .defaultConfiguration) -> RealmPublishers.AsyncOpenPublisher
参数
configuration
打开 Realm 时使用的配置对象。
callbackQueue
应运行 AsyncOpenTask 的调度队列。
返回值
出版商。 如果 Realm 成功打开,订阅者将收到该 Realm。 否则,将改为向上游传递描述Go所在的
Swift.Error
。 -
一个任务对象,可用于观察或取消异步打开。
当异步打开同步 Realm 时,会在调用完成回调之前从服务器下载 Realm 的最新状态。 此任务对象可用于观察下载状态或取消下载。 应该使用此方法,而不是尝试通过同步会话观察下载,因为同步会话本身是异步创建的,并且当 Realm.asyncOpen() 返回时可能还不存在。
查看更多声明
Swift
@frozen public struct AsyncOpenTask
-
在写事务(write transaction)中执行给定区块中包含的操作。
如果区块抛出错误,则事务将被取消,并且在错误发生之前所做的任何更改都将被回滚。
每个 Realm 文件一次只能打开一个写事务(write transaction)。写事务(write transaction)不能嵌套,尝试在已处于写事务(write transaction)中的 Realm 上开始写事务(write transaction)会引发异常。
write
Realm
从其他线程或其他进程中同一 Realm 文件的实例调用 会受到阻塞,直到当前写事务(write transaction)完成或取消。在开始写事务(write transaction)之前,
write
会将Realm
实例更新到最新的 Realm 版本,就好像已调用refresh()
一样,并生成通知(如适用)。如果 Realm 已经是最新的,则此操作无效。您可以通过传入特定通知块的关联通知令牌来跳过通知特定通知块有关此写事务(write transaction)中所做更改的操作。当写事务(write transaction)正在保存用户界面中已进行的更改并且您不希望让通知块尝试重新应用相同的更改时,这主要有用。
传递给此函数的令牌必须用于此 Realm 的通知,这些通知是在执行写事务(write transaction)的同一线程上添加的。使用此方法无法跳过不同线程的通知。
抛出异常
如果无法成功完成事务,则返回
NSError
。 如果block
抛出异常,该函数将抛出传播的ErrorType
。声明
Swift
@discardableResult public func write<Result>(withoutNotifying tokens: [NotificationToken] = [], _ block: (() throws -> Result)) throws -> Result
参数
tokens
一个通知令牌数组,通过添加回调而返回,您不希望收到有关此写事务(write transaction)中所做更改的通知。
block
包含要执行的操作的区块。
返回值
从区块返回的值(如果有)。
-
在 Realm 上开始写事务。
每个 Realm 文件一次只能打开一个写事务(write transaction)。写事务(write transaction)不能嵌套,尝试在已处于写事务(write transaction)中的 Realm 上开始写事务(write transaction)会引发异常。
beginWrite
Realm
从其他线程或其他进程中同一 Realm 文件的实例调用 会受到阻塞,直到当前写事务(write transaction)完成或取消。在开始写事务(write transaction)之前,
beginWrite
会将Realm
实例更新到最新的 Realm 版本,就好像已调用refresh()
一样,并生成通知(如适用)。如果 Realm 已经是最新的,则此操作无效。让写事务(write transaction)跨越事件循环的多个周期很少是一个好主意,但如果您确实希望这样做,则需要确保参与写事务(write transaction)的 Realm 保持活动状态,直到提交写事务(write transaction)。
声明
Swift
public func beginWrite()
-
提交当前写事务(write transaction)中的所有写操作,并结束事务。
保存更改并完成写事务(write
Realm
transaction)后,将同步调用在此特定实例上注册的所有通知块。其他线程上的Realm
实例的通知块以及为任何 Realm collection(包括当前线程上的collection)注册的块都会安排同步调用。您可以通过传入特定通知块的关联通知令牌来跳过通知特定通知块有关此写事务(write transaction)中所做更改的操作。当写事务(write transaction)正在保存用户界面中已进行的更改并且您不希望让通知块尝试重新应用相同的更改时,这主要有用。
传递给此函数的令牌必须用于此 Realm 的通知,这些通知是在执行写事务(write transaction)的同一线程上添加的。使用此方法无法跳过不同线程的通知。
警告
此方法只能在写事务(write transaction)期间调用。
抛出异常
如果由于磁盘空间不足或其他 I/O 错误而无法写入事务,则返回
NSError
。声明
Swift
public func commitWrite(withoutNotifying tokens: [NotificationToken] = []) throws
参数
tokens
一个通知令牌数组,通过添加回调而返回,您不希望收到有关此写事务(write transaction)中所做更改的通知。
-
恢复当前写事务(write transaction)中进行的所有写入并结束事务。
这会将 Realm 中的所有对象回滚到写事务(write transaction)开始时的状态,然后结束事务。
这会恢复已删除对象的数据,但不会恢复失效的对象实例。 任何添加到 Realm 中的
Object
都将失效,而不是变为非托管状态。给定以下代码:
let oldObject = objects(ObjectType).first! let newObject = ObjectType() realm.beginWrite() realm.add(newObject) realm.delete(oldObject) realm.cancelWrite()
oldObject
和newObject
都会为isInvalidated
返回true
,但重新运行提供oldObject
的查询将再次返回有效对象。在事务期间修改的任何对象上的 KVO 观察者都会收到关于更改回其初始值的通知,但取消的写事务(write transaction)不会生成其他通知。
警告
此方法只能在写事务(write transaction)期间调用。声明
Swift
public func cancelWrite()
-
指示 Realm 当前是否处于写事务(write transaction)中。
警告
不要简单地检查此属性,然后在需要创建、更新或删除对象时启动写事务(write transaction)。这样做可能会导致创建大量写事务(write transaction),从而降低性能。相反,总是更喜欢在单个事务期间执行多个更新。声明
Swift
public var isInWriteTransaction: Bool { get }
-
如果在 Realm 中添加或创建的对象具有已存在的主键,该怎么办?
查看更多声明
Swift
@frozen public enum UpdatePolicy : Int
-
向此 Realm 添加一个非托管对象。
如果此 Realm 中已存在具有相同主键的对象,则会使用所选
UpdatePolicy
指定的此对象的属性值来更新该对象。 对于没有主键的对象,更新策略必须为.error
。向 Realm 添加对象时,也会添加该对象引用的所有子关系(通过
Object
和List<Object>
属性)。 这些对象也必须是有效对象才能添加到此 Realm,并且update:
参数的值会传播到这些添加。要添加的对象必须是非托管对象或已受此 Realm 托管的有效对象。 添加已由此 Realm 托管的对象属于无需操作,而添加由另一个 Realm 托管或已从任何 Realm 中删除的对象(即
isInvalidated
为true
的对象)则为错误操作。要将托管对象从一个 Realm 复制到另一个 Realm,请改用
create()
。警告
此方法只能在写事务(write transaction)期间调用。
声明
Swift
public func add(_ object: Object, update: UpdatePolicy = .error)
参数
object
要添加到此 Realm 的对象。
update
如果已经存在具有相同主键的对象,该怎么办? 对于没有主键的对象,必须为
.error
。 -
声明
Swift
public func add<S>(_ objects: S, update: UpdatePolicy = .error) where S : Sequence, S.Element : Object
参数
objects
包含要添加到 Realm 的对象的序列。
update
如何处理带有此Realm中已存在的主键的集合中的对象。 对于没有主键的对象类型,必须为
.error
。update
如何处理带有此Realm中已存在的主键的集合中的对象。 对于没有主键的对象类型,必须为
.error
。 -
创建具有给定值的 Realm 对象,将其添加到 Realm 中并返回。
value
参数可以是 Realm 对象、键值编码兼容对象、从NSJSONSerialization
中的方法返回的数组或字典,或者是包含每个托管属性一个元素的Array
。 请勿传入LinkingObjects
实例,无论是单独传入还是作为collection成员传入。如果value
参数是数组,则所有属性都必须存在、有效,并且顺序与模型中定义的属性相同。如果 Realm 对象类型 没有主键,或者不存在具有指定主键的对象,则会在 Realm 中创建一个新对象。如果 Realm 中已存在具有指定主键的对象,并且更新策略为
.modified
或.all
,则现有对象将被更新,并返回对该对象的引用。如果正在更新对象,则其模式中定义的所有属性都将通过使用键值编码从
value
复制来设置。 如果value
参数不响应给定属性名称(或 getter 名称,如果已定义)的value(forKey:)
,则该值将保持不变。 通过使用NSNull
作为更新值,或者(如果要传入Object
子类的实例)将value
的相应属性设置为 nil,可以将对象上的可空属性设置为 nil。警告
此方法只能在写事务(write transaction)期间调用。
声明
Swift
@discardableResult public func create<T>(_ type: T.Type, value: Any = [:], update: UpdatePolicy = .error) -> T where T : Object
参数
type
要创建的对象的类型。
value
用于填充对象的值。
update
如果已经存在具有相同主键的对象,该怎么办? 对于没有主键的对象类型,必须为
.error
。返回值
新创建的对象。
-
从 Realm 中删除对象。 对象一旦被删除,即被视为失效。
警告
此方法只能在写事务(write transaction)期间调用。
声明
Swift
public func delete(_ object: ObjectBase)
参数
object
要删除的对象。
-
从 Realm 中删除零个或多个对象。
请勿将切片传递给
Results
或任何其他自动updating Realm collection类型(例如,Swiftsuffix(_:)
标准库方法返回的类型)。相反,使用Array()
复制要删除的对象,然后将其传递。 直接将视图传递到自动collection中可能会导致引发“索引越界”异常。警告
此方法只能在写事务(write transaction)期间调用。
声明
Swift
public func delete<S>(_ objects: S) where S : Sequence, S.Element : ObjectBase
参数
objects
要删除的对象。 这可以是
List<Object>
、Results<Object>
或元素为Object
的任何其他 SwiftSequence
(受上述注意事项约束)。 -
从 Realm 中删除所有对象。
警告
此方法只能在写事务(write transaction)期间调用。声明
Swift
public func deleteAll()
-
返回存储在 Realm 中的给定类型的所有对象。
声明
参数
type
要返回的对象的类型。
返回值
包含对象的
Results
。 -
从 Realm 中检索具有给定主键的给定对象类型的单个实例。
此方法要求覆盖给定对象类的
primaryKey()
。看
Object.primaryKey()
声明
Swift
public func object<Element, KeyType>(ofType type: Element.Type, forPrimaryKey key: KeyType) -> Element? where Element : Object
参数
type
要返回的对象的类型。
key
所需对象的主键。
返回值
类型为
type
的对象;如果不存在具有给定主键的实例,则为nil
类型的对象。
-
为对此 Realm 所做的变更添加通知处理程序,并返回通知令牌。
通知处理程序在提交每个写事务(write transaction)后调用,与线程或进程无关。
在添加处理程序块的同一线程上调用处理程序块,并且只能在当前位于事件循环内的线程上添加处理程序块。除非您专门在背景线程上创建并运行事件循环,否则这通常只是主线程。
只要事件循环被其他活动阻止,就无法传递通知。当无法立即发送通知时,可以合并多个通知。
只要您希望将更新发送到区块,就必须保留返回的令牌。 要停止接收更新,请对令牌调用
invalidate()
。声明
Swift
public func observe(_ block: @escaping NotificationBlock) -> NotificationToken
参数
block
为处理 Realm 通知而调用的区块。 它接收以下参数:
notification
:传入通知;realm
:发生通知的 Realm。返回值
只要您希望继续接收变更通知,就必须持有的令牌。
-
将此属性设置为
true
,以便在其他线程中发生更改时自动更新此 Realm。如果设置为
true
(默认),则在其他线程上所做的更改将在提交更改后的下一个事件循环周期反映在此 Realm 中。如果设置为false
,则必须手动对 Realm 调用refresh()
来进行更新,从而获取最新数据。请注意,背景情况下,事件循环没有活动的事件循环,即使将
autorefresh
设置为true
,您也需要手动调用refresh()
才能更新到最新版本。即使启用了此属性,您仍然可以随时调用
refresh()
以在自动刷新之前更新 Realm。无论是否启用自动刷新,在提交写事务(write transaction)时都会发送通知。
在没有任何强引用的
Realm
上禁用autorefresh
不会产生任何影响,并且autorefresh
将在下次创建 Realm 时恢复为true
。 这通常无关紧要,因为它意味着无需刷新任何内容(因为托管Object
List
、Results
和Realm
对管理它们的 有强引用),但这意味着设置autorefresh = false
application(_:didFinishLaunchingWithOptions:)
稍后才存储 Realm 对象将不起作用。默认值为
true
。声明
Swift
public var autorefresh: Bool { get nonmutating set }
-
更新 Realm 和由 Realm 托管的未完成对象,使其点向最新数据。
声明
Swift
@discardableResult public func refresh() -> Bool
返回值
Realm 是否有任何更新。 请注意,即使实际没有更改数据,也可能会返回
true
。
-
如果此 Realm 被冻结,则返回。
声明
Swift
public var isFrozen: Bool { get }
-
返回此 Realm 的冻结(不可变)快照。
冻结 Realm 是特定版本 Realm 数据的不可变快照视图。 与普通 Realm 实例不同,它不会实时更新以反映对 Realm 进行的写入,并且可以从任何线程进行访问。 写入冻结的 Realm 是不被允许的,尝试开始写事务(write transaction)会引发异常。
从冻结 Realm 读取的所有对象和collection也将被冻结。
警告
在 Realm 上执行写事务(write transaction)时长时间持有冻结的 Realm 可能会导致 Realm 文件过大。有关更多信息,请参阅Realm.Configuration.maximumNumberOfActiveVersions
。声明
Swift
public func freeze() -> Realm
-
返回此 Realm 的实时(可变)引用。
从返回的 Realm 引用中读取的所有对象和collection将不再被冻结。如果在尚未冻结的 Realm 上调用,将返回 self。
声明
Swift
public func thaw() -> Realm
-
返回给定对象的冻结(不可变)快照。
冻结副本是一个不可变对象,其中包含与给定对象当前包含的数据相同的数据,但在写入包含的 Realm 时不会更新。 与活动对象不同,冻结对象可以从任何线程访问。
警告
在 Realm 上执行写事务(write transaction)时长时间持有冻结对象可能会导致 Realm 文件变大。有关更多信息,请参阅Realm.Configuration.maximumNumberOfActiveVersions
。声明
Swift
public func freeze<T>(_ obj: T) -> T where T : ObjectBase
-
返回此对象的实时(可变)引用。
此方法为同一冻结对象的实时副本创建托管访问器。 如果在已经存在的对象上调用,则会返回 self。
声明
Swift
public func thaw<T>(_ obj: T) -> T? where T : ObjectBase
-
返回给定collection的冻结(不可变)快照。
冻结副本是一个不可变的collection,其中包含与给定collection当前包含的数据相同的数据,但在写入包含的 Realm 时不会更新。与实时集合不同,冻结集合可以从任何线程访问。
警告
在写事务(write transaction)期间或 Realm 为只读时无法调用此方法。警告
在 Realm 上执行写事务(write transaction)时长时间持有冻结的 collection 可能会导致 Realm 文件过大。有关更多信息,请参阅Realm.Configuration.maximumNumberOfActiveVersions
。声明
Swift
public func freeze<Collection>(_ collection: Collection) -> Collection where Collection : RealmCollection
-
使 Realm 托管的所有
Object
、Results
、LinkingObjects
和List
失效。Realm 对其访问的数据版本持有读锁(read lock),因此在不同线程上对该 Realm 所做的更改不会修改或删除该 Realm 看到的数据。调用此方法会释放读锁(read lock),从而允许以后的写事务(write transaction)重用磁盘上使用的空间,而不是增加文件。在您之前从 Realm 读取不再需要的数据的背景线程上执行长时间阻塞操作之前,应先调用此方法。
当前线程上从此
Realm
实例获取的所有Object
、Results
和List
实例都会失效。 不能使用Object
和Array
。Results
将变空。 Realm 本身仍然有效,并且下次从 Realm 读取数据时会隐式开始新的读取事务。在没有从 Realm 读取任何数据的情况下,或者在从 Realm 读取任何数据之前,连续多次调用此方法是不执行任何操作的。
声明
Swift
public func invalidate()
-
将压缩且可选加密的 Realm 副本写入给定的本地 URL。
目标文件不能是已经存在的文件。
请注意,如果从写事务(write transaction)中调用此方法,则写入当前数据,而不是提交上一个写事务(write transaction)时的点的数据。
抛出异常
如果无法写入副本,则返回
NSError
。声明
Swift
public func writeCopy(toFile fileURL: URL, encryptionKey: Data? = nil) throws
参数
fileURL
用于保存 Realm 的本地 URL。
encryptionKey
用于加密新文件的可选 64 字节加密密钥。
-
检查给定配置的 Realm 文件是否存在于磁盘本地。
对于非同步、非内存中的 Realm,这相当于
FileManager.default.fileExists(atPath:)
。 对于同步 Realm,它负责根据服务器、虚拟路径和用户计算磁盘上的实际路径,就像打开 Realm 时所做的那样。@param config 要检查是否存在的 Realm 配置。 @return 如果磁盘上存在给定配置的 Realm 文件,则返回 true,否则返回 false。
声明
Swift
public static func fileExists(for config: Configuration) -> Bool
-
删除给定配置的本地 Realm 文件和关联的临时文件。
这会删除“域”、“.note”和“. Management”文件,这些文件是通过打开具有给定配置的 Realm 创建的。它不会删除锁文件(该文件不包含持久数据,并且每次打开 Realm 文件时都会从头开始重新创建)。
Realm 当前不得在任何线程或其他进程中打开。 如果是,则会引发 .alreadyOpen 错误。 在删除操作发生时,尝试在另一个线程上打开 Realm 会被阻塞,然后再创建并打开新的 Realm。
如果 Realm 不存在,则返回
false
。@param config Realm 配置,用于标识要删除的 Realm。 @return true 如果删除了任何文件,则为 false。
声明
Swift
public static func deleteFiles(for config: Configuration) throws -> Bool
-
每次对象更改时发出 Void 的发布者。
尽管有这个名称,但它实际上是在collection发生更改后发出的。
声明
Swift
public var objectWillChange: RealmPublishers.RealmWillChange { get }
-
描述 Realm 错误域中的错误代码的结构体。 这些值可用于捕获各种可恢复的错误,尤其是在初始化 Realm 实例时发生的错误。
查看更多let realm: Realm? do { realm = try Realm() } catch Realm.Error.incompatibleLockFile { print("Realm Browser app may be attached to Realm on device?") }
声明
-
在给定路径上的 Realm 上执行给定 Realm 配置的迁移区块。
首次打开 Realm 时会自动调用此方法,无需显式调用。 您可以选择调用此方法来精确控制执行迁移的时间和方式。
声明
Swift
public static func performMigration(for configuration: Realm.Configuration = Realm.Configuration.defaultConfiguration) throws
参数
configuration
用于打开和迁移 Realm 的 Realm 配置。
-
返回两个
Realm
实例是否相等。声明
Swift
public static func == (lhs: Realm, rhs: Realm) -> Bool
-
指示对 Realm 进行更改的通知。
查看更多声明
Swift
@frozen public enum Notification : String
-
获取此 Realm 使用的 SyncSession。 如果这不是同步 Realm,则将为 nil。
声明
Swift
public var syncSession: SyncSession? { get }
-
返回与首次创建
ThreadSafeReference
时引用的对象相同的对象,但已解析为该线程的当前 Realm。 如果在创建引用后删除了该对象,则返回nil
。警告
ThreadSafeReference
对象最多必须解析一次。 无法解析ThreadSafeReference
将导致 Realm 的源版本被固定,直到引用被解除分配。 如果多次解析引用,则会引发异常。警告
无法在写事务(write transaction)中调用。
注意
如果源 Realm 的版本高于此版本,则将刷新此 Realm。
看
ThreadSafeReference(to:)
声明
Swift
public func resolve<Confined>(_ reference: ThreadSafeReference<Confined>) -> Confined? where Confined : ThreadConfined
参数
reference
对要在此 Realm 中解析的线程对象的线程安全引用。