database package

Firebase Realtime Database

函数

函数	说明
function(应用, ...)
getDatabase(app, url)	返回与提供的 FirebaseApp 相关联的 Realtime Database SDK 实例。如果不存在实例或现有实例使用自定义数据库网址，则使用默认设置初始化新实例。
function(db, ...)
connectDatabaseEmulator(db, host, port, options)	修改所提供的实例，以便与 Realtime Database 模拟器进行通信。 注意：必须在执行任何其他操作之前调用此方法。
goOffline(db)	与服务器断开连接（所有数据库操作都将离线完成）。客户端会自动保持与数据库服务器的持久连接，该连接将无限期保持活跃状态，并在断开连接后重新连接。但是，如果不期望持久连接，可以使用 goOffline() 和 goOnline() 方法来控制客户端连接。处于离线状态时，客户端将不再接收来自数据库的数据更新。但是，本地执行的所有数据库操作将继续立即触发事件，从而使应用程序继续正常运行。此外，在本地执行的每个操作都会自动加入队列，并在重新连接到数据库服务器后重试。要重新连接到数据库并开始接收远程事件，请参阅goOnline()。
goOnline(db)	重新连接到服务器，并将离线数据库状态与服务器状态同步。在停用与 goOffline() 的有效连接后应使用此方法。重新连接后，客户端将传输适当的数据并触发适当的事件，以便客户端“跟上”。
ref(db, 路径)	返回一个 Reference，它表示数据库中与提供的路径相对应的位置。如果未提供路径，则 Reference 将指向数据库的根目录。
refFrom网址(db, url)	返回一个 Reference，它表示数据库中与提供的 Firebase 网址对应的位置。如果该网址不是有效的 Firebase 数据库网址，或者其域名与当前 Database 实例不同，则会抛出异常。请注意，所有查询参数（orderBy、limitToLast 等）都会被忽略，并且不会应用于返回的 Reference。
函数
forceLongPolling()	强制使用 longPolling 而非 websocket。如果 database网址 中使用了 websocket 协议，此字段将被忽略。
forceWebSockets()	强制使用 websocket 取代 longPolling。
orderByKey()	创建按键排序的新 QueryConstraint。按查询结果的（升序）键值对查询结果进行排序。如需详细了解 orderByKey()，请参阅对数据进行排序。
orderByPriority()	创建按优先级排序的新 QueryConstraint。应用不需要使用优先级，但可以按普通属性对集合进行排序（如需了解优先级的替代方案，请参阅对数据进行排序）。
orderByValue()	创建按值排序的新 QueryConstraint。如果查询的子项都是标量值（字符串、数字或布尔值），您可以按（升序）值对结果进行排序。您可以参阅数据排序，详细了解 orderByValue()。
serverTimestamp()	返回一个占位符值，用于自动填充由 Firebase 服务器确定的当前时间戳（自 Unix 纪元以来的时间，以毫秒为单位）。
function(delta, ...)
increment(delta)	返回一个占位符值，该值可用于以原子方式将当前数据库值增加指定的增量。
function(enabled, ...)
enableLogging(enabled, Persistent)	将调试信息记录到控制台。
function(limit, ...)
limitToFirst(limit)	创建一个新的 QueryConstraint，如果该子项限制为第一个特定子项数。limitToFirst() 方法用于为给定回调设置要同步的子项数上限。如果我们将上限设置为 100，则最初只能接收最多 100 个 child_added 事件。如果数据库中只存储了不到 100 条消息，那么每条消息都会触发一个 child_added 事件。但是，如果消息超过 100 条，则仅收到前 100 条消息的 child_added 事件。随着项发生更改，对于从有效列表中删除的每个项，我们都会收到 child_removed 事件，使总数保持为 100。您可以在过滤数据中详细了解 limitToFirst()。
limitToLast(limit)	创建一个新的 QueryConstraint，其限制为仅返回最后指定的子项数量。limitToLast() 方法用于为给定回调设置要同步的最大子项数量。如果我们将上限设置为 100，则最初只能接收最多 100 个 child_added 事件。如果数据库中只存储了不到 100 条消息，那么每条消息都会触发一个 child_added 事件。但是，如果消息超过 100 条，则只有最后 100 条消息有对应的 child_added 事件。随着项发生更改，对于从有效列表中删除的每个项，我们都会收到 child_removed 事件，使总数保持为 100。您可以在过滤数据中详细了解 limitToLast()。
function(logger, ...)
enableLogging(logger)	将调试信息记录到控制台。
function(父级, ...)
child(parent, path)	获取指定相对路径中位置的 Reference。相对路径可以是简单的子名称（例如“ada”），也可以是以斜杠分隔的路径（例如“ada/name/first”）。
push(父级, 值)	使用唯一键生成新的子位置，并返回其 Reference。这是向项集合添加数据的最常用模式。如果您向 push() 提供值，则该值会写入生成的位置。如果不传递值，系统不会向数据库写入任何内容，并且子项仍为空（但您可以在其他位置使用 Reference）。push() 生成的唯一键按当前时间排序，因此生成的项列表按时间顺序排序。这些键还设计为不可猜测（它们包含 72 个随机的熵）。请参阅附加到数据列表。请参阅确保使用唯一标识符的 2^120 种方法。
function(path, ...)
orderByChild(path)	创建按指定子键排序的新 QueryConstraint。每次查询只能按一个键进行排序。在同一个查询中多次调用 orderByChild() 会出错。借助 Firebase 查询，您可以即时按任意子键对数据进行排序。不过，如果您事先知道您的索引是什么，则可以通过安全规则中的 .indexOn 规则来定义索引，以便获得更好的性能。如需了解详情，请参阅 https://firebase.google.com/docs/database/security/indexing-data 规则。如需详细了解 orderByChild()，请参阅对数据进行排序。
函数(query, ...)
get(查询)	获取此查询的最新结果。
off(query, eventType, callback)	分离先前附加到相应 on() (onValue, onChildAdded) 监听器的回调。注意：我们不推荐使用这种方法来移除监听器。请改用从相应 on 回调中返回的回调函数。请分离之前与 on*() 关联的回调。对父监听器调用 off() 不会自动移除在子节点上注册的监听器，还必须对所有子监听器调用 off() 才能移除回调。如果未指定回调，则指定 eventType 的所有回调都将被移除。同样，如果未指定 eventType，则 Reference 的所有回调都将被移除。也可以通过调用其退订回调来移除各个监听器。
onChildAdded(query, callback, cancelCallback)	监听特定位置的数据更改。这是从数据库中读取数据的主要方式。每当数据发生变化时，系统都会针对初始数据触发回调，并再次触发回调。调用返回的退订回调以停止接收更新。如需了解详情，请参阅在网络上检索数据。此位置的每个初始子项目将触发一次 onChildAdded 事件，并且每次添加新的子项目时都会再次触发该事件。传入回调的 DataSnapshot 将反映相关子级的数据。为了便于排序，系统会传递第二个参数，这是一个字符串，其中包含按排序顺序排列的上一个同级子节点的键；如果该子节点是第一个子节点，则传递 null。
onChildAdded(query, callback, options)	监听特定位置的数据更改。这是从数据库中读取数据的主要方式。每当数据发生变化时，系统都会针对初始数据触发回调，并再次触发回调。调用返回的退订回调以停止接收更新。如需了解详情，请参阅在网络上检索数据。此位置的每个初始子项目将触发一次 onChildAdded 事件，并且每次添加新的子项目时都会再次触发该事件。传入回调的 DataSnapshot 将反映相关子级的数据。为了便于排序，系统会传递第二个参数，这是一个字符串，其中包含按排序顺序排列的上一个同级子节点的键；如果该子节点是第一个子节点，则传递 null。
onChildAdded(query, callback, cancelCallback, options)	监听特定位置的数据更改。这是从数据库中读取数据的主要方式。每当数据发生变化时，系统都会针对初始数据触发回调，并再次触发回调。调用返回的退订回调以停止接收更新。如需了解详情，请参阅在网络上检索数据。此位置的每个初始子项目将触发一次 onChildAdded 事件，并且每次添加新的子项目时都会再次触发该事件。传入回调的 DataSnapshot 将反映相关子级的数据。为了便于排序，系统会传递第二个参数，这是一个字符串，其中包含按排序顺序排列的上一个同级子节点的键；如果该子节点是第一个子节点，则传递 null。
onChildChanged(query, callback, cancelCallback)	监听特定位置的数据更改。这是从数据库中读取数据的主要方式。每当数据发生变化时，系统都会针对初始数据触发回调，并再次触发回调。调用返回的退订回调以停止接收更新。如需了解详情，请参阅在网络上检索数据。当存储在子级（或其任何子级）中的数据发生更改时，将会触发 onChildChanged 事件。请注意，单个 child_changed 事件可能代表对子项进行的多次更改。传递给回调函数的 DataSnapshot 将包含新的子项内容。为便于排序，系统还会向回调传递第二个参数，它是一个字符串，其中包含按排序顺序排列的上一个同级子节点的键；如果该子节点是第一个子节点，则返回 null。
onChildChanged(query, callback, options)	监听特定位置的数据更改。这是从数据库中读取数据的主要方式。每当数据发生变化时，系统都会针对初始数据触发回调，并再次触发回调。调用返回的退订回调以停止接收更新。如需了解详情，请参阅在网络上检索数据。当存储在子级（或其任何子级）中的数据发生更改时，将会触发 onChildChanged 事件。请注意，单个 child_changed 事件可能代表对子项进行的多次更改。传递给回调函数的 DataSnapshot 将包含新的子项内容。为便于排序，系统还会向回调传递第二个参数，它是一个字符串，其中包含按排序顺序排列的上一个同级子节点的键；如果该子节点是第一个子节点，则返回 null。
onChildChanged(query, callback, cancelCallback, options)	监听特定位置的数据更改。这是从数据库中读取数据的主要方式。每当数据发生变化时，系统都会针对初始数据触发回调，并再次触发回调。调用返回的退订回调以停止接收更新。如需了解详情，请参阅在网络上检索数据。当存储在子级（或其任何子级）中的数据发生更改时，将会触发 onChildChanged 事件。请注意，单个 child_changed 事件可能代表对子项进行的多次更改。传递给回调函数的 DataSnapshot 将包含新的子项内容。为便于排序，系统还会向回调传递第二个参数，它是一个字符串，其中包含按排序顺序排列的上一个同级子节点的键；如果该子节点是第一个子节点，则返回 null。
onChildMoved(query, callback, cancelCallback)	监听特定位置的数据更改。这是从数据库中读取数据的主要方式。每当数据发生变化时，系统都会针对初始数据触发回调，并再次触发回调。调用返回的退订回调以停止接收更新。如需了解详情，请参阅在网络上检索数据。当子项的排序顺序发生更改，使得子项相对于同级项的位置发生变化时，将会触发 onChildMoved 事件。传递给回调函数的 DataSnapshot 将用于已移动的子节点的数据。系统还会向该函数传递第二个参数，这是一个字符串，其中包含按排序顺序排列的前同级子节点的键；如果该子节点是第一个子节点，则为 null。
onChildMoved(query, callback, options)	监听特定位置的数据更改。这是从数据库中读取数据的主要方式。每当数据发生变化时，系统都会针对初始数据触发回调，并再次触发回调。调用返回的退订回调以停止接收更新。如需了解详情，请参阅在网络上检索数据。当子项的排序顺序发生更改，使得子项相对于同级项的位置发生变化时，将会触发 onChildMoved 事件。传递给回调函数的 DataSnapshot 将用于已移动的子节点的数据。系统还会向该函数传递第二个参数，这是一个字符串，其中包含按排序顺序排列的前同级子节点的键；如果该子节点是第一个子节点，则为 null。
onChildMoved(query, callback, cancelCallback, options)	监听特定位置的数据更改。这是从数据库中读取数据的主要方式。每当数据发生变化时，系统都会针对初始数据触发回调，并再次触发回调。调用返回的退订回调以停止接收更新。如需了解详情，请参阅在网络上检索数据。当子项的排序顺序发生更改，使得子项相对于同级项的位置发生变化时，将会触发 onChildMoved 事件。传递给回调函数的 DataSnapshot 将用于已移动的子节点的数据。系统还会向该函数传递第二个参数，这是一个字符串，其中包含按排序顺序排列的前同级子节点的键；如果该子节点是第一个子节点，则为 null。
onChildRemoved(query, callback, cancelCallback)	监听特定位置的数据更改。这是从数据库中读取数据的主要方式。每当数据发生变化时，系统都会针对初始数据触发回调，并再次触发回调。调用返回的退订回调以停止接收更新。如需了解详情，请参阅在网络上检索数据。每次移除子节点时，都会触发一次 onChildRemoved 事件。传入回调中的 DataSnapshot 将是已移除的子项的旧数据。当出现以下任一情况时，系统会移除子项：- 客户端对该子项或其某个祖先实体明确调用 remove()；客户端对该子项或其某个祖先实体调用 set(null)；该子项的所有子项均已移除 - 当前有效的查询滤除了子项（因为它的排序顺序已更改或已达到上限）
onChildRemoved(query, callback, options)	监听特定位置的数据更改。这是从数据库中读取数据的主要方式。每当数据发生变化时，系统都会针对初始数据触发回调，并再次触发回调。调用返回的退订回调以停止接收更新。如需了解详情，请参阅在网络上检索数据。每次移除子节点时，都会触发一次 onChildRemoved 事件。传入回调中的 DataSnapshot 将是已移除的子项的旧数据。当出现以下任一情况时，系统会移除子项：- 客户端对该子项或其某个祖先实体明确调用 remove()；客户端对该子项或其某个祖先实体调用 set(null)；该子项的所有子项均已移除 - 当前有效的查询滤除了子项（因为它的排序顺序已更改或已达到上限）
onChildRemoved(query, callback, cancelCallback, options)	监听特定位置的数据更改。这是从数据库中读取数据的主要方式。每当数据发生变化时，系统都会针对初始数据触发回调，并再次触发回调。调用返回的退订回调以停止接收更新。如需了解详情，请参阅在网络上检索数据。每次移除子节点时，都会触发一次 onChildRemoved 事件。传入回调中的 DataSnapshot 将是已移除的子项的旧数据。当出现以下任一情况时，系统会移除子项：- 客户端对该子项或其某个祖先实体明确调用 remove()；客户端对该子项或其某个祖先实体调用 set(null)；该子项的所有子项均已移除 - 当前有效的查询滤除了子项（因为它的排序顺序已更改或已达到上限）
onValue(query, callback, cancelCallback)	监听特定位置的数据更改。这是从数据库中读取数据的主要方式。每当数据发生变化时，系统都会针对初始数据触发回调，并再次触发回调。调用返回的退订回调以停止接收更新。如需了解详情，请参阅在网络上检索数据。onValue 事件将在此位置存储的初始数据触发一次，并在每次数据发生更改时再次触发。传递给回调函数的 DataSnapshot 将对应于调用 on() 的位置。只有在所有内容同步完毕之后，系统才会触发此事件。如果该营业地点没有任何数据，则会触发该营业地点并展示一个空的 DataSnapshot（val() 将返回 null）。
onValue(query, callback, options)	监听特定位置的数据更改。这是从数据库中读取数据的主要方式。每当数据发生变化时，系统都会针对初始数据触发回调，并再次触发回调。调用返回的退订回调以停止接收更新。如需了解详情，请参阅在网络上检索数据。onValue 事件将在此位置存储的初始数据触发一次，并在每次数据发生更改时再次触发。传递给回调函数的 DataSnapshot 将对应于调用 on() 的位置。只有在所有内容同步完毕之后，系统才会触发此事件。如果该营业地点没有任何数据，则会触发该营业地点并展示一个空的 DataSnapshot（val() 将返回 null）。
onValue(query, callback, cancelCallback, options)	监听特定位置的数据更改。这是从数据库中读取数据的主要方式。每当数据发生变化时，系统都会针对初始数据触发回调，并再次触发回调。调用返回的退订回调以停止接收更新。如需了解详情，请参阅在网络上检索数据。onValue 事件将在此位置存储的初始数据触发一次，并在每次数据发生更改时再次触发。传递给回调函数的 DataSnapshot 将对应于调用 on() 的位置。只有在所有内容同步完毕之后，系统才会触发此事件。如果该营业地点没有任何数据，则会触发该营业地点并展示一个空的 DataSnapshot（val() 将返回 null）。
query(query, queryConstraints)	创建 Query 的新不可变实例，该实例可通过扩展还包含其他查询限制条件。
函数(ref, ...)
onDisconnect(ref)	返回 OnDisconnect 对象 - 如需详细了解如何使用该对象，请参阅在 JavaScript 中启用离线功能。
移除(ref)	移除此数据库位置中的数据。子位置中的所有数据也将被删除。移除后的效果将立即显现，并且相应的事件“value”触发。系统还会开始将移除操作同步到 Firebase 服务器，并在完成后解析返回的 Promise。如果提供，系统会在同步完成后异步调用 onComplete 回调。
runTransaction(ref, transactionUpdate, options)	以原子方式修改此位置的数据。以原子方式修改此位置的数据。与普通 set() 不同，无论其之前的值如何都会覆盖数据，runTransaction() 用于将现有值修改为新值，确保不会与其他同时向同一位置写入数据的客户端发生冲突。为此，您需要向 runTransaction() 传递一个更新函数，该函数用于将当前值转换为新值。如果另一个客户端在您成功写入新值前向该位置写入数据，则系统会使用新的当前值再次调用更新函数，然后重新尝试执行写入操作。此过程会反复发生，直到您的写入成功且没有冲突，或者您因没有从更新函数返回值而中止事务。注意：使用 set() 修改数据将取消该位置的所有待处理事务，因此，如果混用 set() 和 runTransaction() 来更新相同的数据，应格外小心。注意：在使用具有 Security and Firebase Rules 的事务时，请注意，除了具备 .write 访问权限之外，客户端还需要 .read 访问权限才能执行这是因为事务的客户端特性要求客户端读取数据，以便以事务方式进行更新。
set(ref, value)	将数据写入此数据库位置。这将覆盖此位置和所有子位置的所有数据。写入的效果将立即可见，并且将触发相应的事件（“value”、“child_added”等）。系统还会开始将数据同步到 Firebase 服务器，并在完成后解析返回的 Promise。如果提供 onComplete 回调函数，系统会在同步完成后异步调用此回调函数。为新值传递 null 相当于调用 remove()；也就是说，此位置的所有数据和所有子位置都将被删除。set() 会移除存储在此位置中的任何优先级，因此，如果要保留优先级，则需要改用 setWithPriority()。请注意，使用 set() 修改数据会取消该位置的所有待处理交易，因此，如果您混用 set() 和 transaction() 来修改相同的数据，应格外小心。单个 set() 将生成一个“值”set() 现场发生的事件。
setPriority(ref, priority) 设置优先级	设置此数据库位置中的数据的优先级。应用不需要使用优先级，但可以按普通属性对集合进行排序（请参阅对数据进行排序和过滤）。
setWithPriority(ref, value, priority) 参数	将数据写入数据库位置。与 set() 类似，但还指定该数据的优先级。应用不需要使用优先级，但可以按普通属性对集合进行排序（请参阅对数据进行排序和过滤）。
update(ref, values)	一次将多个值写入数据库。values 参数包含多个将一起写入数据库的“属性-值”对。每个子属性可以是简单的属性（例如“name”），也可以是从当前位置到要更新的数据的相对路径（例如“name/first”）。与 set() 方法相反，update() 可用于选择性地仅更新当前位置中引用的属性（而不是替换当前位置的所有子属性）。写入的效果将立即可见，并且相应事件（已添加的子属性）将立即可见。系统还会开始将数据同步到 Firebase 服务器，并在完成后解析返回的 Promise。如果提供，系统会在同步完成后异步调用 onComplete 回调。单个 update() 会生成单个“值”事件，而不管修改了多少个子级。请注意，使用 update() 修改数据将取消该位置的所有待处理交易，因此，如果混用 update() 和 transaction() 来修改相同的数据，应格外小心。将 null 传递给 update() 会移除此位置的数据。请参阅引入多位置更新等功能。update()
function(值, ...)
endAt(值, 键)	创建具有指定终点的 QueryConstraint。通过使用 startAt()、startAfter()、endBefore()、endAt() 和 equalTo()，您可以为查询选择任意起点和终点。终点包括在内，因此与指定值的子代将包含在查询中。可选的键参数可用于进一步限制查询的范围。如果已指定，则具有正好指定值的子项的键名也必须小于或等于指定键。如需详细了解 endAt()，请参阅过滤数据。
endBefore(value, key)	创建具有指定终点（不含）的 QueryConstraint。使用 startAt()、startAfter()、endBefore()、endAt() 和 equalTo() 可让您为查询选择任意起点和终点。终点是专有的。如果仅提供了一个值，则查询中将包含值小于指定值的子节点。如果指定了键，则子项的值必须小于或等于指定值，并且键名必须小于指定键。
equalTo(value, key)	创建一个 QueryConstraint，其中包含与指定值匹配的子项。通过使用 startAt()、startAfter()、endBefore()、endAt() 和 equalTo()，您可以为查询选择任意起点和终点。可选的键参数可用于进一步限制查询的范围。如果指定了此属性，则具有精确指定值的子节点也必须将指定的键作为其键名。这可用于过滤具有相同值有许多匹配项的结果。如需详细了解 equalTo()，请参阅过滤数据。
startAfter(value, key)	创建具有指定起点（不包含）的 QueryConstraint。使用 startAt()、startAfter()、endBefore()、endAt() 和 equalTo()，可以为查询选择任意起点和终点。起点是不包含的。如果仅提供了一个值，则查询中将包含值大于指定值的子节点。如果指定了键，则子项的值必须大于或等于指定值，并且键名必须大于指定键。
startAt(值, 键)	创建具有指定起点的 QueryConstraint。通过使用 startAt()、startAfter()、endBefore()、endAt() 和 equalTo()，您可以为查询选择任意起点和终点。起点包括在内，因此具有确切指定值的子项将包含在查询中。可选的键参数可用于进一步限制查询的范围。如果已指定，则具有正好指定值的子项的键名也必须大于或等于指定键。如需详细了解 startAt()，请参阅过滤数据。

类

类	说明
数据库	这个类表示 Firebase Realtime Database。
DataSnapshot	DataSnapshot 包含来自 Database 位置的数据。每当您从 Database 读取数据时，都会以 DataSnapshot 的形式收到数据。系统会将 DataSnapshot 传递给您使用 on() 或 once() 附加的事件回调。您可以通过调用 val() 方法将快照的内容提取为 JavaScript 对象。或者，您也可以通过调用 child() 返回子快照（然后您可以对其调用 val()），遍历到快照。DataSnapshot 是数据库位置中数据高效生成的不可变副本。它无法修改，也永远不会改变（若要修改数据，您始终是直接对 Reference 调用 set() 方法）。
OnDisconnect	借助 onDisconnect 类，您可以在客户端与数据库服务器断开连接时写入或清除数据。无论客户端是否正常断开连接，这些更新都会发生，因此，即使连接中断或客户端崩溃，您也可以依靠更新来清理数据。onDisconnect 类最常用于管理应用中的在线状态，它有助于检测已连接的客户端数量以及其他客户端断开连接的时间。如需了解详情，请参阅在 JavaScript 中启用离线功能。为避免在将请求传输到数据库服务器之前连接断开时出现问题，应在写入任何数据之前调用这些函数。请注意，onDisconnect 操作仅触发一次。如果您希望在每次断开连接时都执行操作，则需要在每次重新连接时都重新建立 onDisconnect 操作。
QueryConstraint	QueryConstraint 用于缩小 Database 查询返回的文档集的范围。QueryConstraint是通过调用 endAt()、endBefore()、endBefore()、startAt()、startAt()、startAt()、startAt()、startAfter()、startAfter()、startAfter()、limitToFirstFirst()、limitToLast()、limitToLast()、limitToLast()、orderToLast()、orderByChild()、orderByChild()QueryConstraint
TransactionResult	runTransaction() 的解析值的类型。

接口

接口	说明
DatabaseReference	DatabaseReference 表示数据库中的特定位置，可用于从该数据库位置读取数据或向其写入数据。您可以通过调用 ref() 或 ref("child/path") 引用数据库中的根或子位置。写入通过 set() 方法完成，读取可通过 on*() 方法完成。请参阅 https://firebase.google.com/docs/database/web/read-and-write
IteratedDataSnapshot	表示正在迭代的 Reference 的子快照。键永远不会未定义。
ListenOptions	可用于自定义监听器的选项对象。
查询	Query 用于排序和过滤 Database 位置的数据，因此其中仅包含一部分子数据。这可用于按某个属性（例如恐龙的高度）对数据集进行排序，以及将大量项目（例如聊天消息）的数量限制到适合同步到客户端的数字。查询是通过将此处定义的一个或多个过滤器方法链接在一起来创建的。与 DatabaseReference 一样，您可以使用 on*() 方法从 Query 接收数据。您将只能收到与您的查询匹配的部分数据对应的事件和 DataSnapshot。如需了解详情，请参阅 https://firebase.google.com/docs/database/web/lists-of-data#sorting_and_filtering_data。
ThenableReference	一个 Promise，在由 push() 返回时也可充当 DatabaseReference。此引用会立即可用，并且 Promise 会在写入后端的操作完成时解析。
TransactionOptions	用于配置交易的选项对象。

类型别名

类型别名	说明
EventType	以下任一字符串：“value”“child_added”“child_changed”“child_removed”或“child_moved”。
QueryConstraintType	介绍此 SDK 中提供的不同查询限制。
退订	可以调用以移除监听器的回调。

function(应用, ...)

getDatabase(app, url)

返回与提供的 FirebaseApp 相关联的 Realtime Database SDK 实例。如果不存在实例或现有实例使用自定义数据库网址，则使用默认设置初始化新实例。

签名：

export declare function getDatabase(app?: FirebaseApp, url?: string): Database;

参数

参数	类型	说明
应用	FirebaseApp	与返回的 Realtime Database 实例关联的 FirebaseApp 实例。
网址	字符串	要连接的 Realtime Database 实例的网址。如果未提供，则 SDK 将连接到 Firebase 应用的默认实例。

返回：

数据库

所提供应用的 Database 实例。

function(db, ...)

connectDatabaseEmulator(db, host, port, options)

修改所提供的实例，以便与 Realtime Database 模拟器进行通信。

注意：必须在执行任何其他操作之前调用此方法。

签名：

export declare function connectDatabaseEmulator(db: Database, host: string, port: number, options?: {
    mockUserToken?: EmulatorMockTokenOptions | string;
}): void;

参数

参数	类型	说明
db	数据库	要修改的实例。
主机	字符串	模拟器主机（例如：localhost）
端口	数字	模拟器端口（例如：8080）
选项	{ mockUserToken?:EmulatorMockTokenOptions |字符串；}

返回：

void

goOffline(db)

断开与服务器的连接（所有数据库操作都将离线完成）。

客户端自动保持与数据库服务器的持久连接，该连接将无限期地保持活动状态，并在断开连接时重新连接。但是，如果不需要使用持久连接，则可以使用 goOffline() 和 goOnline() 方法来控制客户端连接。

处于离线状态时，客户端将不会再收到来自数据库的数据更新。但是，本地执行的所有数据库操作将继续立即触发事件，从而使应用程序继续正常运行。此外，本地执行的每个操作都会自动排入队列，并在重新连接到数据库服务器后重试。

如需重新连接到数据库并开始接收远程事件，请参阅 goOnline()。

签名：

export declare function goOffline(db: Database): void;

参数

参数	类型	说明
db	数据库	要断开连接的实例。

返回：

void

goOnline(db)

重新连接到服务器，并将离线数据库状态与服务器状态同步。

您应在停用与 goOffline() 的有效连接后使用此方法。重新连接后，客户端将传输适当的数据并触发适当的事件，以便客户端“跟上”。

签名：

export declare function goOnline(db: Database): void;

参数

参数	类型	说明
db	数据库	要重新连接的实例。

返回：

void

ref(数据库, 路径)

返回一个 Reference，它表示数据库中与提供的路径相对应的位置。如果未提供路径，则 Reference 将指向数据库的根目录。

签名：

export declare function ref(db: Database, path?: string): DatabaseReference;

参数

参数	类型	说明
db	数据库	要获取其引用的数据库实例。
路径	字符串	可选路径，表示返回的 Reference 将指向的位置。如果未提供，返回的 Reference 将指向数据库的根目录。

返回：

DatabaseReference

如果提供了路径，则返回指向所提供的路径的 Reference。否则，为指向数据库根目录的 Reference。

refFrom网址(数据库, 网址)

返回一个 Reference，它表示数据库中与提供的 Firebase 网址对应的位置。

如果该网址不是有效的 Firebase 数据库网址，或者与当前 Database 实例的域名不同，则会抛出异常。

请注意，所有查询参数（orderBy、limitToLast 等）都会被忽略，并且不会应用于返回的 Reference。

签名：

export declare function refFromURL(db: Database, url: string): DatabaseReference;

参数

参数	类型	说明
db	数据库	要获取其引用的数据库实例。
网址	字符串	返回的 Reference 将指向的 Firebase 网址。

返回：

DatabaseReference

指向所提供的 Firebase 网址的 Reference。

function()

forceLongPolling()

强制使用 longPolling 而非 websocket。如果 database网址 中使用了 websocket 协议，此字段将被忽略。

签名：

export declare function forceLongPolling(): void;

返回：

void

forceWebSockets()

强制使用 websocket 取代 longPolling。

签名：

export declare function forceWebSockets(): void;

返回：

void

orderByKey()

创建一个按键排序的新 QueryConstraint。

按（升序）键值对查询结果进行排序。

如需详细了解 orderByKey()，请参阅对数据进行排序。

签名：

export declare function orderByKey(): QueryConstraint;

返回：

QueryConstraint

orderByPriority()

创建按优先级排序的新 QueryConstraint。

应用不需要使用优先级，但可以按普通属性对集合进行排序（如需了解优先级的替代方案，请参阅对数据进行排序）。

签名：

export declare function orderByPriority(): QueryConstraint;

返回：

QueryConstraint

orderByValue()

创建按值排序的新 QueryConstraint。

如果查询的子项都是标量值（字符串、数字或布尔值），您可以按（升序）值对结果进行排序。

如需详细了解 orderByValue()，请参阅对数据进行排序。

签名：

export declare function orderByValue(): QueryConstraint;

返回：

QueryConstraint

serverTimestamp()

返回一个占位符值，用于自动填充由 Firebase 服务器确定的当前时间戳（自 Unix 纪元以来的时间，以毫秒为单位）。

签名：

export declare function serverTimestamp(): object;

返回：

对象

function(delta, ...)

增量(delta)

返回一个占位符值，该值可用于以原子方式将当前数据库值增加指定的增量。

签名：

export declare function increment(delta: number): object;

参数

参数	类型	说明
delta	数字	以原子方式修改当前值的数量。

返回：

对象

用于在服务器端以原子方式修改数据的占位值。

function(enabled, ...)

enableLogging(已启用，永久)

将调试信息记录到控制台。

签名：

export declare function enableLogging(enabled: boolean, persistent?: boolean): any;

参数

参数	类型	说明
已启用	布尔值	如果为 true，则启用日志记录；如果为 false，则停用日志记录。
永久性	布尔值	如果 true，则记住页面刷新之间的日志记录状态。

返回：

任意

function(limit, ...)

limitToFirst(限制)

创建一个新的 QueryConstraint，如果其子项数量限制为第一个特定数量。

limitToFirst() 方法用于为指定回调设置要同步的最大子项目数。如果我们将上限设置为 100，则最初只能接收最多 100 个 child_added 事件。如果数据库中只存储了不到 100 条消息，那么每条消息都会触发一个 child_added 事件。但是，如果消息超过 100 条，则仅收到前 100 条消息的 child_added 事件。随着商品发生更改，对于从有效列表中删除的每个商品，我们都会收到 child_removed 事件，使总数保持为 100。

如需详细了解 limitToFirst()，请参阅过滤数据。

签名：

export declare function limitToFirst(limit: number): QueryConstraint;

参数

参数	类型	说明
限制	数字	此查询中可包含的节点数上限。

返回：

QueryConstraint

limitToLast(限制)

创建一个新的 QueryConstraint，其限制为仅返回最后指定数量的子项。

limitToLast() 方法用于为指定回调设置要同步的最大子项目数。如果我们将上限设置为 100，则最初只能接收最多 100 个 child_added 事件。如果数据库中只存储了不到 100 条消息，那么每条消息都会触发一个 child_added 事件。但是，如果消息超过 100 条，则只有最后 100 条消息有对应的 child_added 事件。随着商品发生更改，对于从有效列表中删除的每个商品，我们都会收到 child_removed 事件，使总数保持为 100。

如需详细了解 limitToLast()，请参阅过滤数据。

签名：

export declare function limitToLast(limit: number): QueryConstraint;

参数

参数	类型	说明
限制	数字	此查询中可包含的节点数上限。

返回：

QueryConstraint

function(logger, ...)

enableLogging(logger)

将调试信息记录到控制台。

签名：

export declare function enableLogging(logger: (message: string) => unknown): any;

参数

参数	类型	说明
logger	（消息：字符串）=>未知	用于控制内容的记录方式的自定义日志记录器函数。

返回：

任意

function(parent, ...)

子（父级，路径）

获取指定相对路径中位置的 Reference。

相对路径可以是简单的子名称（例如“ada”），也可以是以斜杠分隔的路径（例如“ada/name/first”）。

签名：

export declare function child(parent: DatabaseReference, path: string): DatabaseReference;

参数

参数	类型	说明
父级	DatabaseReference	父级位置。
路径	字符串	从此位置到所需子位置的相对路径。

返回：

DatabaseReference

指定的子位置。

push(parent, value)

使用唯一键生成新的子位置，并返回其 Reference。

这是将数据添加到项集合的最常用模式。

如果您向 push() 提供值，该值将写入生成的位置。如果不传递值，则不会向数据库写入任何内容，并且子节点仍为空（但您可以在其他位置使用 Reference）。

push() 生成的唯一键按当前时间排序，因此生成的项列表是按时间顺序排序的。这些密钥还设计为不可猜测（它们包含 72 个随机的熵）。

请参阅附加到数据列表。请参阅确保使用唯一标识符的 2^120 种方法。

签名：

export declare function push(parent: DatabaseReference, value?: unknown): ThenableReference;

参数

参数	类型	说明
父级	DatabaseReference	父级位置。
值	未知	在生成位置写入的可选值。

返回：

ThenableReference

组合了 Promise 和 Reference；在写入完成时解析，但可立即用作子位置的 Reference。

function(path, ...)

orderByChild(路径)

创建一个按指定子键进行排序的新 QueryConstraint。

每次查询都只能按照一个键进行排序。对同一查询多次调用 orderByChild() 会出错。

借助 Firebase 查询，您可以即时按任意子键对数据进行排序。不过，如果您事先知道您的索引是什么，则可以通过安全规则中的 .indexOn 规则来定义索引，以便获得更好的性能。如需了解详情，请参阅 https://firebase.google.com/docs/database/security/indexing-data 规则。

如需详细了解 orderByChild()，请参阅对数据进行排序。

签名：

export declare function orderByChild(path: string): QueryConstraint;

参数

参数	类型	说明
路径	字符串	排序依据的路径。

返回：

QueryConstraint

function(query, ...)

get(查询)

获取此查询的最新结果。

签名：

export declare function get(query: Query): Promise<DataSnapshot>;

参数

参数	类型	说明
查询	查询	要运行的查询。

返回：

Promise<DataSnapshot>

Promise，如果有值可用，会解析为生成的 DataSnapshot；如果客户端无法返回值（例如，如果服务器无法访问且没有缓存任何内容，则会拒绝）。

off(query, eventType, callback)

分离先前附加到相应 on*()（onValue、onChildAdded）监听器的回调。注意：我们不推荐使用这种方法来移除监听器。请改用从相应 on* 回调返回的回调函数。

分离之前附加了 on*() 的回调。对父监听器调用 off() 不会自动移除在子节点上注册的监听器，您还必须对所有子监听器调用 off() 才能移除回调函数。

如果未指定回调，则指定 eventType 的所有回调都将被移除。同样，如果未指定 eventType，则将移除 Reference 的所有回调。

您还可以通过调用其退订回调来移除各个监听器。

签名：

export declare function off(query: Query, eventType?: EventType, callback?: (snapshot: DataSnapshot, previousChildName?: string | null) => unknown): void;

参数

参数	类型	说明
查询	查询	注册监听器的查询。
eventType	EventType	以下任一字符串：“value”“child_added”“child_changed”“child_removed”或“child_moved”。如果省略，Reference 的所有回调都将被移除。
callback	（快照：DataSnapshot, previousChildName?: string | null）=>未知	已传递给 on() 或 undefined 以移除所有回调的回调函数。

返回：

void

onChildAdded(query, callback, cancelCallback)

监听特定位置的数据更改。

这是从数据库中读取数据的主要方式。每当数据发生变化时，系统都会针对初始数据触发回调，并再次触发回调。调用返回的退订回调以停止接收更新。如需了解详情，请参阅在网络上检索数据。

此位置的每个初始子项都会触发一次 onChildAdded 事件，并且每次添加新的子项时都会再次触发。传入回调的 DataSnapshot 将反映相关子级的数据。为了便于排序，系统会传递第二个参数，这是一个字符串，其中包含按排序顺序排列的上一个同级子节点的键；如果该子节点是第一个子节点，则传递 null。

签名：

export declare function onChildAdded(query: Query, callback: (snapshot: DataSnapshot, previousChildName?: string | null) => unknown, cancelCallback?: (error: Error) => unknown): Unsubscribe;

参数

参数	类型	说明
查询	查询	要运行的查询。
callback	（快照：DataSnapshot, previousChildName?: string | null）=>未知	发生指定事件时触发的回调。系统会向该回调函数传递一个 DataSnapshot 和一个包含前一个子项的键的字符串（按排序顺序），如果该子项是第一个子项，则返回 null。
cancelCallback	（错误：错误）=>未知	一个可选的回调，如果您的客户端没有读取此数据的权限（或者它具有权限但现在丢失了数据）而被取消事件订阅，您将会收到该回调。系统将为此回调函数传递一个 Error 对象，说明失败的原因。

返回：

退订

可以调用以移除监听器的函数。

onChildAdded(query, callback, options)

监听特定位置的数据更改。

这是从数据库中读取数据的主要方式。每当数据发生变化时，系统都会针对初始数据触发回调，并再次触发回调。调用返回的退订回调以停止接收更新。如需了解详情，请参阅在网络上检索数据。

此位置的每个初始子项都会触发一次 onChildAdded 事件，并且每次添加新的子项时都会再次触发。传入回调的 DataSnapshot 将反映相关子级的数据。为了便于排序，系统会传递第二个参数，这是一个字符串，其中包含按排序顺序排列的上一个同级子节点的键；如果该子节点是第一个子节点，则传递 null。

签名：

export declare function onChildAdded(query: Query, callback: (snapshot: DataSnapshot, previousChildName: string | null) => unknown, options: ListenOptions): Unsubscribe;

参数

参数	类型	说明
查询	查询	要运行的查询。
callback	（快照：DataSnapshot，previousChildName：string | null）=>未知	发生指定事件时触发的回调。系统会向该回调函数传递一个 DataSnapshot 和一个包含前一个子项的键的字符串（按排序顺序），如果该子项是第一个子项，则返回 null。
选项	ListenOptions	一个对象，可用于配置 onlyOnce，然后在监听器第一次调用后移除监听器。

返回：

退订

可以调用以移除监听器的函数。

onChildAdded(query, callback, cancelCallback, options)

监听特定位置的数据更改。

这是从数据库中读取数据的主要方式。每当数据发生变化时，系统都会针对初始数据触发回调，并再次触发回调。调用返回的退订回调以停止接收更新。如需了解详情，请参阅在网络上检索数据。

此位置的每个初始子项都会触发一次 onChildAdded 事件，并且每次添加新的子项时都会再次触发。传入回调的 DataSnapshot 将反映相关子级的数据。为了便于排序，系统会传递第二个参数，这是一个字符串，其中包含按排序顺序排列的上一个同级子节点的键；如果该子节点是第一个子节点，则传递 null。

签名：

export declare function onChildAdded(query: Query, callback: (snapshot: DataSnapshot, previousChildName: string | null) => unknown, cancelCallback: (error: Error) => unknown, options: ListenOptions): Unsubscribe;

参数

参数	类型	说明
查询	查询	要运行的查询。
callback	（快照：DataSnapshot，previousChildName：string | null）=>未知	发生指定事件时触发的回调。系统会向该回调函数传递一个 DataSnapshot 和一个包含前一个子项的键的字符串（按排序顺序），如果该子项是第一个子项，则返回 null。
cancelCallback	（错误：错误）=>未知	一个可选的回调，如果您的客户端没有读取此数据的权限（或者它具有权限但现在丢失了数据）而被取消事件订阅，您将会收到该回调。系统将为此回调函数传递一个 Error 对象，说明失败的原因。
选项	ListenOptions	一个对象，可用于配置 onlyOnce，然后在监听器第一次调用后移除监听器。

返回：

退订

可以调用以移除监听器的函数。

onChildChanged(query, callback, cancelCallback)

监听特定位置的数据更改。

这是从数据库中读取数据的主要方式。每当数据发生变化时，系统都会针对初始数据触发回调，并再次触发回调。调用返回的退订回调以停止接收更新。如需了解详情，请参阅在网络上检索数据。

当存储在子级（或其任何后代）中的数据发生更改时，将会触发 onChildChanged 事件。请注意，单个 child_changed 事件可能代表对子项进行的多次更改。传递给回调函数的 DataSnapshot 将包含新的子项内容。为便于排序，系统还会向回调传递第二个参数，它是一个字符串，其中包含按排序顺序排列的上一个同级子节点的键；如果该子节点是第一个子节点，则返回 null。

签名：

export declare function onChildChanged(query: Query, callback: (snapshot: DataSnapshot, previousChildName: string | null) => unknown, cancelCallback?: (error: Error) => unknown): Unsubscribe;

参数

参数	类型	说明
查询	查询	要运行的查询。
callback	（快照：DataSnapshot，previousChildName：string | null）=>未知	发生指定事件时触发的回调。系统会向该回调函数传递一个 DataSnapshot 和一个包含前一个子项的键的字符串（按排序顺序），如果该子项是第一个子项，则返回 null。
cancelCallback	（错误：错误）=>未知	一个可选的回调，如果您的客户端没有读取此数据的权限（或者它具有权限但现在丢失了数据）而被取消事件订阅，您将会收到该回调。系统将为此回调函数传递一个 Error 对象，说明失败的原因。

返回：

退订

可以调用以移除监听器的函数。

onChildChanged(query, callback, options)

监听特定位置的数据更改。

这是从数据库中读取数据的主要方式。每当数据发生变化时，系统都会针对初始数据触发回调，并再次触发回调。调用返回的退订回调以停止接收更新。如需了解详情，请参阅在网络上检索数据。

当存储在子级（或其任何后代）中的数据发生更改时，将会触发 onChildChanged 事件。请注意，单个 child_changed 事件可能代表对子项进行的多次更改。传递给回调函数的 DataSnapshot 将包含新的子项内容。为便于排序，系统还会向回调传递第二个参数，它是一个字符串，其中包含按排序顺序排列的上一个同级子节点的键；如果该子节点是第一个子节点，则返回 null。

签名：

export declare function onChildChanged(query: Query, callback: (snapshot: DataSnapshot, previousChildName: string | null) => unknown, options: ListenOptions): Unsubscribe;

参数

参数	类型	说明
查询	查询	要运行的查询。
callback	（快照：DataSnapshot，previousChildName：string | null）=>未知	发生指定事件时触发的回调。系统会向该回调函数传递一个 DataSnapshot 和一个包含前一个子项的键的字符串（按排序顺序），如果该子项是第一个子项，则返回 null。
选项	ListenOptions	一个对象，可用于配置 onlyOnce，然后在监听器第一次调用后移除监听器。

返回：

退订

可以调用以移除监听器的函数。

onChildChanged(query, callback, cancelCallback, options)

监听特定位置的数据更改。

这是从数据库中读取数据的主要方式。每当数据发生变化时，系统都会针对初始数据触发回调，并再次触发回调。调用返回的退订回调以停止接收更新。如需了解详情，请参阅在网络上检索数据。

当存储在子级（或其任何后代）中的数据发生更改时，将会触发 onChildChanged 事件。请注意，单个 child_changed 事件可能代表对子项进行的多次更改。传递给回调函数的 DataSnapshot 将包含新的子项内容。为便于排序，系统还会向回调传递第二个参数，它是一个字符串，其中包含按排序顺序排列的上一个同级子节点的键；如果该子节点是第一个子节点，则返回 null。

签名：

export declare function onChildChanged(query: Query, callback: (snapshot: DataSnapshot, previousChildName: string | null) => unknown, cancelCallback: (error: Error) => unknown, options: ListenOptions): Unsubscribe;

参数

参数	类型	说明
查询	查询	要运行的查询。
callback	（快照：DataSnapshot，previousChildName：string | null）=>未知	发生指定事件时触发的回调。系统会向该回调函数传递一个 DataSnapshot 和一个包含前一个子项的键的字符串（按排序顺序），如果该子项是第一个子项，则返回 null。
cancelCallback	（错误：错误）=>未知	一个可选的回调，如果您的客户端没有读取此数据的权限（或者它具有权限但现在丢失了数据）而被取消事件订阅，您将会收到该回调。系统将为此回调函数传递一个 Error 对象，说明失败的原因。
选项	ListenOptions	一个对象，可用于配置 onlyOnce，然后在监听器第一次调用后移除监听器。

返回：

退订

可以调用以移除监听器的函数。

onChildMoved(query, callback, cancelCallback)

监听特定位置的数据更改。

这是从数据库中读取数据的主要方式。每当数据发生变化时，系统都会针对初始数据触发回调，并再次触发回调。调用返回的退订回调以停止接收更新。如需了解详情，请参阅在网络上检索数据。

当子项的排序顺序发生更改，使得子项相对于同级项的位置发生变化时，将会触发 onChildMoved 事件。传递给回调函数的 DataSnapshot 将用于已移动的子节点的数据。系统还会向该函数传递第二个参数，这是一个字符串，其中包含按排序顺序排列的前同级子节点的键；如果该子节点是第一个子节点，则为 null。

签名：

export declare function onChildMoved(query: Query, callback: (snapshot: DataSnapshot, previousChildName: string | null) => unknown, cancelCallback?: (error: Error) => unknown): Unsubscribe;

参数

参数	类型	说明
查询	查询	要运行的查询。
callback	（快照：DataSnapshot，previousChildName：string | null）=>未知	发生指定事件时触发的回调。系统会向该回调函数传递一个 DataSnapshot 和一个包含前一个子项的键的字符串（按排序顺序），如果该子项是第一个子项，则返回 null。
cancelCallback	（错误：错误）=>未知	一个可选的回调，如果您的客户端没有读取此数据的权限（或者它具有权限但现在丢失了数据）而被取消事件订阅，您将会收到该回调。系统将为此回调函数传递一个 Error 对象，说明失败的原因。

返回：

退订

可以调用以移除监听器的函数。

onChildMoved(query, callback, options)

监听特定位置的数据更改。

这是从数据库中读取数据的主要方式。每当数据发生变化时，系统都会针对初始数据触发回调，并再次触发回调。调用返回的退订回调以停止接收更新。如需了解详情，请参阅在网络上检索数据。

当子项的排序顺序发生更改，使得子项相对于同级项的位置发生变化时，将会触发 onChildMoved 事件。传递给回调函数的 DataSnapshot 将用于已移动的子节点的数据。系统还会向该函数传递第二个参数，这是一个字符串，其中包含按排序顺序排列的前同级子节点的键；如果该子节点是第一个子节点，则为 null。

签名：

export declare function onChildMoved(query: Query, callback: (snapshot: DataSnapshot, previousChildName: string | null) => unknown, options: ListenOptions): Unsubscribe;

参数

参数	类型	说明
查询	查询	要运行的查询。
callback	（快照：DataSnapshot，previousChildName：string | null）=>未知	发生指定事件时触发的回调。系统会向该回调函数传递一个 DataSnapshot 和一个包含前一个子项的键的字符串（按排序顺序），如果该子项是第一个子项，则返回 null。
选项	ListenOptions	一个对象，可用于配置 onlyOnce，然后在监听器第一次调用后移除监听器。

返回：

退订

可以调用以移除监听器的函数。

onChildMoved(query, callback, cancelCallback, options)

监听特定位置的数据更改。

这是从数据库中读取数据的主要方式。每当数据发生变化时，系统都会针对初始数据触发回调，并再次触发回调。调用返回的退订回调以停止接收更新。如需了解详情，请参阅在网络上检索数据。

当子项的排序顺序发生更改，使得子项相对于同级项的位置发生变化时，将会触发 onChildMoved 事件。传递给回调函数的 DataSnapshot 将用于已移动的子节点的数据。系统还会向该函数传递第二个参数，这是一个字符串，其中包含按排序顺序排列的前同级子节点的键；如果该子节点是第一个子节点，则为 null。

签名：

export declare function onChildMoved(query: Query, callback: (snapshot: DataSnapshot, previousChildName: string | null) => unknown, cancelCallback: (error: Error) => unknown, options: ListenOptions): Unsubscribe;

参数

参数	类型	说明
查询	查询	要运行的查询。
callback	（快照：DataSnapshot，previousChildName：string | null）=>未知	发生指定事件时触发的回调。系统会向该回调函数传递一个 DataSnapshot 和一个包含前一个子项的键的字符串（按排序顺序），如果该子项是第一个子项，则返回 null。
cancelCallback	（错误：错误）=>未知	一个可选的回调，如果您的客户端没有读取此数据的权限（或者它具有权限但现在丢失了数据）而被取消事件订阅，您将会收到该回调。系统将为此回调函数传递一个 Error 对象，说明失败的原因。
选项	ListenOptions	一个对象，可用于配置 onlyOnce，然后在监听器第一次调用后移除监听器。

返回：

退订

可以调用以移除监听器的函数。

onChildRemoved(query, callback, cancelCallback)

监听特定位置的数据更改。

这是从数据库中读取数据的主要方式。每当数据发生变化时，系统都会针对初始数据触发回调，并再次触发回调。调用返回的退订回调以停止接收更新。如需了解详情，请参阅在网络上检索数据。

每次移除子级时，都会触发一次 onChildRemoved 事件。传入回调中的 DataSnapshot 将是已移除的子项的旧数据。在出现以下任一情况时，儿童将被移除：

• 客户端明确对该子项或其某个祖先实体调用 remove()（客户端会对该子项或其某个祖先实体调用 set(null)），而该子项的所有子项均已移除，则现在有一个有效的查询滤除了子项（因为它的排序顺序已更改或已达到上限）

签名：

export declare function onChildRemoved(query: Query, callback: (snapshot: DataSnapshot) => unknown, cancelCallback?: (error: Error) => unknown): Unsubscribe;

参数

参数	类型	说明
查询	查询	要运行的查询。
callback	（快照：DataSnapshot）=>未知	发生指定事件时触发的回调。系统会向该回调函数传递一个 DataSnapshot 和一个包含前一个子项的键的字符串（按排序顺序），如果该子项是第一个子项，则返回 null。
cancelCallback	（错误：错误）=>未知	一个可选的回调，如果您的客户端没有读取此数据的权限（或者它具有权限但现在丢失了数据）而被取消事件订阅，您将会收到该回调。系统将为此回调函数传递一个 Error 对象，说明失败的原因。

返回：

退订

可以调用以移除监听器的函数。

onChildRemoved(查询, 回调, 选项)

监听特定位置的数据更改。

这是从数据库中读取数据的主要方式。每当数据发生变化时，系统都会针对初始数据触发回调，并再次触发回调。调用返回的退订回调以停止接收更新。如需了解详情，请参阅在网络上检索数据。

每次移除子级时，都会触发一次 onChildRemoved 事件。传入回调中的 DataSnapshot 将是已移除的子项的旧数据。在出现以下任一情况时，儿童将被移除：

• 客户端明确对该子项或其某个祖先实体调用 remove()（客户端会对该子项或其某个祖先实体调用 set(null)），而该子项的所有子项均已移除，则现在有一个有效的查询滤除了子项（因为它的排序顺序已更改或已达到上限）

签名：

export declare function onChildRemoved(query: Query, callback: (snapshot: DataSnapshot) => unknown, options: ListenOptions): Unsubscribe;

参数

参数	类型	说明
查询	查询	要运行的查询。
callback	（快照：DataSnapshot）=>未知	发生指定事件时触发的回调。系统会向该回调函数传递一个 DataSnapshot 和一个包含前一个子项的键的字符串（按排序顺序），如果该子项是第一个子项，则返回 null。
选项	ListenOptions	一个对象，可用于配置 onlyOnce，然后在监听器第一次调用后移除监听器。

返回：

退订

可以调用以移除监听器的函数。

onChildRemoved(query, callback, cancelCallback, options)

监听特定位置的数据更改。

这是从数据库中读取数据的主要方式。每当数据发生变化时，系统都会针对初始数据触发回调，并再次触发回调。调用返回的退订回调以停止接收更新。如需了解详情，请参阅在网络上检索数据。

每次移除子级时，都会触发一次 onChildRemoved 事件。传入回调中的 DataSnapshot 将是已移除的子项的旧数据。在出现以下任一情况时，儿童将被移除：

• 客户端明确对该子项或其某个祖先实体调用 remove()（客户端会对该子项或其某个祖先实体调用 set(null)），而该子项的所有子项均已移除，则现在有一个有效的查询滤除了子项（因为它的排序顺序已更改或已达到上限）

签名：

export declare function onChildRemoved(query: Query, callback: (snapshot: DataSnapshot) => unknown, cancelCallback: (error: Error) => unknown, options: ListenOptions): Unsubscribe;

参数

参数	类型	说明
查询	查询	要运行的查询。
callback	（快照：DataSnapshot）=>未知	发生指定事件时触发的回调。系统会向该回调函数传递一个 DataSnapshot 和一个包含前一个子项的键的字符串（按排序顺序），如果该子项是第一个子项，则返回 null。
cancelCallback	（错误：错误）=>未知	一个可选的回调，如果您的客户端没有读取此数据的权限（或者它具有权限但现在丢失了数据）而被取消事件订阅，您将会收到该回调。系统将为此回调函数传递一个 Error 对象，说明失败的原因。
选项	ListenOptions	一个对象，可用于配置 onlyOnce，然后在监听器第一次调用后移除监听器。

返回：

退订

可以调用以移除监听器的函数。

onValue(query, callback, cancelCallback)

监听特定位置的数据更改。

这是从数据库中读取数据的主要方式。每当数据发生变化时，系统都会针对初始数据触发回调，并再次触发回调。调用返回的退订回调以停止接收更新。如需了解详情，请参阅在网络上检索数据。

onValue 事件将使用此位置存储的初始数据触发一次，然后每当数据发生更改时再次触发。传递给回调函数的 DataSnapshot 将对应于调用 on() 的位置。只有在所有内容同步完毕之后，系统才会触发此事件。如果该营业地点没有任何数据，则会触发该营业地点并展示一个空的 DataSnapshot（val() 将返回 null）。

签名：

export declare function onValue(query: Query, callback: (snapshot: DataSnapshot) => unknown, cancelCallback?: (error: Error) => unknown): Unsubscribe;

参数

参数	类型	说明
查询	查询	要运行的查询。
callback	（快照：DataSnapshot）=>未知	发生指定事件时触发的回调。系统会向该回调函数传递一个 DataSnapshot。
cancelCallback	（错误：错误）=>未知	一个可选的回调，如果您的客户端没有读取此数据的权限（或者它具有权限但现在丢失了数据）而被取消事件订阅，您将会收到该回调。系统将为此回调函数传递一个 Error 对象，说明失败的原因。

返回：

退订

可以调用以移除监听器的函数。

onValue(查询, 回调, 选项)

监听特定位置的数据更改。

这是从数据库中读取数据的主要方式。每当数据发生变化时，系统都会针对初始数据触发回调，并再次触发回调。调用返回的退订回调以停止接收更新。如需了解详情，请参阅在网络上检索数据。

onValue 事件将使用此位置存储的初始数据触发一次，然后每当数据发生更改时再次触发。传递给回调函数的 DataSnapshot 将对应于调用 on() 的位置。只有在所有内容同步完毕之后，系统才会触发此事件。如果该营业地点没有任何数据，则会触发该营业地点并展示一个空的 DataSnapshot（val() 将返回 null）。

签名：

export declare function onValue(query: Query, callback: (snapshot: DataSnapshot) => unknown, options: ListenOptions): Unsubscribe;

参数

参数	类型	说明
查询	查询	要运行的查询。
callback	（快照：DataSnapshot）=>未知	发生指定事件时触发的回调。系统会向该回调函数传递一个 DataSnapshot。
选项	ListenOptions	一个对象，可用于配置 onlyOnce，然后在监听器第一次调用后移除监听器。

返回：

退订

可以调用以移除监听器的函数。

onValue(query, callback, cancelCallback, options)

监听特定位置的数据更改。

这是从数据库中读取数据的主要方式。每当数据发生变化时，系统都会针对初始数据触发回调，并再次触发回调。调用返回的退订回调以停止接收更新。如需了解详情，请参阅在网络上检索数据。

onValue 事件将使用此位置存储的初始数据触发一次，然后每当数据发生更改时再次触发。传递给回调函数的 DataSnapshot 将对应于调用 on() 的位置。只有在所有内容同步完毕之后，系统才会触发此事件。如果该营业地点没有任何数据，则会触发该营业地点并展示一个空的 DataSnapshot（val() 将返回 null）。

签名：

export declare function onValue(query: Query, callback: (snapshot: DataSnapshot) => unknown, cancelCallback: (error: Error) => unknown, options: ListenOptions): Unsubscribe;

参数

参数	类型	说明
查询	查询	要运行的查询。
callback	（快照：DataSnapshot）=>未知	发生指定事件时触发的回调。系统会向该回调函数传递一个 DataSnapshot。
cancelCallback	（错误：错误）=>未知	一个可选的回调，如果您的客户端没有读取此数据的权限（或者它具有权限但现在丢失了数据）而被取消事件订阅，您将会收到该回调。系统将为此回调函数传递一个 Error 对象，说明失败的原因。
选项	ListenOptions	一个对象，可用于配置 onlyOnce，然后在监听器第一次调用后移除监听器。

返回：

退订

可以调用以移除监听器的函数。

query(query, queryConstraints)

创建 Query 的新不可变实例，该实例可通过扩展还包含其他查询限制条件。

签名：

export declare function query(query: Query, ...queryConstraints: QueryConstraint[]): Query;

参数

参数	类型	说明
查询	查询	要用作新限制条件基础的 Query 实例。
queryConstraints	QueryConstraint[]	要应用的 QueryConstraint 列表。

返回：

查询

异常

如果提供的查询限制条件无法与现有或新的限制条件组合使用，则会发生该错误。

function(ref, ...)

onDisconnect(ref)

返回 OnDisconnect 对象 - 如需详细了解如何使用该对象，请参阅在 JavaScript 中启用离线功能。

签名：

export declare function onDisconnect(ref: DatabaseReference): OnDisconnect;

参数

参数	类型	说明
ref	DatabaseReference	要为其添加 OnDisconnect 触发器的引用。

返回：

OnDisconnect

移除（参考）

移除此数据库位置中的数据。

子位置的所有数据也将被删除。

移除的效果将立即可见，并且相应的事件“value”触发。系统还会开始将移除操作同步到 Firebase 服务器，并在完成后解析返回的 Promise。如果提供，系统会在同步完成后异步调用 onComplete 回调。

签名：

export declare function remove(ref: DatabaseReference): Promise<void>;

参数

参数	类型	说明
ref	DatabaseReference	要移除的营业地点。

返回：

承诺<void>

从服务器上移除完成时解析。

runTransaction(ref, transactionUpdate, options)

以原子方式修改此位置的数据。

以原子方式修改此位置的数据。与普通的 set() 不同，无论其之前的值如何都会覆盖数据，而 runTransaction() 用于将现有值修改为新值，确保不会与其他客户端同时写入同一位置。

为此，您需要向 runTransaction() 传递一个更新函数，该函数用于将当前值转换为新值。如果另一个客户端在您成功写入新值前向该位置写入数据，则系统会使用新的当前值再次调用更新函数，然后重新尝试执行写入操作。此过程将反复发生，直到写入成功完成且没有冲突，或者您因不从更新函数返回值而中止事务为止。

注意：使用 set() 修改数据将取消该位置的所有待处理交易，因此，如果混合使用 set() 和 runTransaction() 来更新相同的数据，应格外小心。

注意：在使用具有 Security and Firebase Rules 的事务时，请注意，除了 .write 访问权限之外，客户端还需要 .read 访问权限才能执行事务。这是因为事务的客户端特性要求客户端读取数据，以便以事务方式进行更新。

签名：

export declare function runTransaction(ref: DatabaseReference, transactionUpdate: (currentData: any) => unknown, options?: TransactionOptions): Promise<TransactionResult>;

参数

参数	类型	说明
ref	DatabaseReference	以原子方式修改的位置。
事务更新	（currentData：any）=>未知	开发者提供的函数，将被传递为此位置存储的当前数据（作为 JavaScript 对象）。函数应返回它要写入的新值（作为 JavaScript 对象）。如果返回 undefined（即返回时不带参数），事务将被取消，此位置的数据不会被修改。
选项	TransactionOptions	用于配置交易的选项对象。

返回：

Promise<TransactionResult>

可以选择性地使用 Promise（而不是 onComplete 回调）来处理成功和失败。

set(ref, value)

将数据写入此数据库位置。

这将覆盖此位置和所有子位置的所有数据。

写入的效果将立即可见，并且将触发相应的事件（“value”、“child_added”等）。系统还会开始将数据同步到 Firebase 服务器，并在完成后解析返回的 Promise。如果提供，系统会在同步完成后异步调用 onComplete 回调。

为新值传递 null 等同于调用 remove()；也就是说，此位置中的所有数据以及所有子位置都将被删除。

set() 会移除存储在此位置的所有优先级，因此如果您想要保留优先级，则需要改用 setWithPriority()。

请注意，使用 set() 修改数据会取消该位置的所有待处理交易，因此，如果您混用 set() 和 transaction() 来修改相同的数据，应格外小心。

单个 set() 会生成单个“值”在 set() 的执行地点发生的事件。

签名：

export declare function set(ref: DatabaseReference, value: unknown): Promise<void>;

参数

参数	类型	说明
ref	DatabaseReference	要向其中写入数据的位置。
值	未知	要写入的值（字符串、数字、布尔值、对象、数组或 null）。

返回：

承诺<void>

完成写入服务器时解析。

setPriority(参考, 优先级)

设置此数据库位置中数据的优先级。

应用不需要使用优先级，但可以按普通属性对集合进行排序（请参阅对数据进行排序和过滤）。

签名：

export declare function setPriority(ref: DatabaseReference, priority: string | number | null): Promise<void>;

参数

参数	类型	说明
ref	DatabaseReference	要向其中写入数据的位置。
优先级	字符串 |数字 |null	要写入的优先级（字符串、数字或 null）。

返回：

承诺<void>

完成写入服务器时解析。

setWithPriority(ref, value, priority)

将数据写入数据库位置。与 set() 类似，但还指定了该数据的优先级。

应用不需要使用优先级，但可以按普通属性对集合进行排序（请参阅对数据进行排序和过滤）。

签名：

export declare function setWithPriority(ref: DatabaseReference, value: unknown, priority: string | number | null): Promise<void>;

参数

参数	类型	说明
ref	DatabaseReference	要向其中写入数据的位置。
值	未知	要写入的值（字符串、数字、布尔值、对象、数组或 null）。
优先级	字符串 |数字 |null	要写入的优先级（字符串、数字或 null）。

返回：

承诺<void>

完成写入服务器时解析。

update(ref, values)

一次将多个值写入数据库。

values 参数包含多个将一起写入数据库的“属性-值”对。每个子属性可以是简单属性（例如“name”），也可以是从当前位置到要更新的数据的相对路径（例如“name/first”）。

与 set() 方法相反，您可以使用 update() 有选择地仅更新当前位置被引用的属性（而不是替换当前位置的所有子属性）。

写入的效果将立即可见，并且将触发相应的事件（“value”、“child_added”等）。系统还会开始将数据同步到 Firebase 服务器，并在完成后解析返回的 Promise。如果提供，系统会在同步完成后异步调用 onComplete 回调。

单个 update() 会生成单个“值”事件，而不管修改了多少个子项。update()

请注意，使用 update() 修改数据会取消该位置的所有待处理交易，因此，如果您混用 update() 和 transaction() 来修改相同的数据，应格外小心。

将 null 传递给 update() 会移除此位置的数据。

请参阅推出多位置更新等功能。

签名：

export declare function update(ref: DatabaseReference, values: object): Promise<void>;

参数

参数	类型	说明
ref	DatabaseReference	要向其中写入数据的位置。
值	对象	包含多个值的对象。

返回：

承诺<void>

当服务器上的更新完成时解析。

function(值, ...)

endAt(值, 键)

创建具有指定终点的 QueryConstraint。

通过使用 startAt()、startAfter()、endBefore()、endAt() 和 equalTo()，您可以为查询选择任意起点和终点。

该结束点包括在范围内，因此具有指定值的子节点将包含在查询中。可选的键参数可用于进一步限制查询的范围。如果已指定该属性，则具有精确指定值的子节点的键名也必须小于或等于指定键。

如需详细了解 endAt()，请参阅过滤数据。

签名：

export declare function endAt(value: number | string | boolean | null, key?: string): QueryConstraint;

参数

参数	类型	说明
值	数字 |字符串 |布尔值 |null	结束值。参数类型取决于此查询中使用的 orderBy() 函数。请指定与 orderBy() 类型匹配的值。与 orderByKey() 结合使用时，值必须是字符串。
键	字符串	在具有先前指定优先级的子项中，要在什么位置结束的子项键。只有当按子项、值或优先级排序时，才允许使用此参数。

返回：

QueryConstraint

endBefore(值, 键)

创建具有指定结束点（不含边界值）的 QueryConstraint。

通过使用 startAt()、startAfter()、endBefore()、endAt() 和 equalTo()，您可以为查询选择任意起点和终点。

此终点是不包含的。如果仅提供了一个值，则查询中将包含值小于指定值的子节点。如果指定了键，则子项的值必须小于或等于指定值，并且键名必须小于指定键。

签名：

export declare function endBefore(value: number | string | boolean | null, key?: string): QueryConstraint;

参数

参数	类型	说明
值	数字 |字符串 |布尔值 |null	要在其前面结束的值。参数类型取决于此查询中使用的 orderBy() 函数。请指定与 orderBy() 类型匹配的值。与 orderByKey() 结合使用时，值必须是字符串。
键	字符串	在具有先前指定优先级的子项中，要在其前面结束的子键。只有当按子项、值或优先级排序时，才允许使用此参数。

返回：

QueryConstraint

equalTo(值, 键)

创建一个 QueryConstraint，其中包含与指定值匹配的子项。

通过使用 startAt()、startAfter()、endBefore()、endAt() 和 equalTo()，您可以为查询选择任意起点和终点。

可选的键参数可用于进一步限制查询的范围。如果指定了此属性，则具有精确指定值的子节点也必须将指定的键作为其键名。这可用于过滤具有相同值有许多匹配项的结果集。

如需详细了解 equalTo()，请参阅过滤数据。

签名：

export declare function equalTo(value: number | string | boolean | null, key?: string): QueryConstraint;

参数

参数	类型	说明
值	数字 |字符串 |布尔值 |null	要匹配的值。参数类型取决于此查询中使用的 orderBy() 函数。请指定与 orderBy() 类型匹配的值。与 orderByKey() 结合使用时，值必须是字符串。
键	字符串	在具有先前指定优先级的子节点中，要从其开始的子键。只有当按子项、值或优先级排序时，才允许使用此参数。

返回：

QueryConstraint

startAfter(值, 键)

使用指定起点（不含边界）创建 QueryConstraint。

通过使用 startAt()、startAfter()、endBefore()、endAt() 和 equalTo()，您可以为查询选择任意起点和终点。

起点不包括在内。如果仅提供了一个值，则查询中将包含值大于指定值的子节点。如果指定了键，则子项的值必须大于或等于指定值，并且键名必须大于指定键。

签名：

export declare function startAfter(value: number | string | boolean | null, key?: string): QueryConstraint;

参数

参数	类型	说明
值	数字 |字符串 |布尔值 |null	其后的值。参数类型取决于此查询中使用的 orderBy() 函数。请指定与 orderBy() 类型匹配的值。与 orderByKey() 结合使用时，值必须是字符串。
键	字符串	要在其后启动的子键。只有当按子项、值或优先级排序时，才允许使用此参数。

返回：

QueryConstraint

startAt(值, 键)

创建具有指定起点的 QueryConstraint。

通过使用 startAt()、startAfter()、endBefore()、endAt() 和 equalTo()，您可以为查询选择任意起点和终点。

起点包括边界值，因此具有指定值的子节点将包含在查询中。可选的键参数可用于进一步限制查询的范围。如果已指定此属性，则具有正好指定值的子节点的键名也必须大于或等于指定键。

如需详细了解 startAt()，请参阅过滤数据。

签名：

export declare function startAt(value?: number | string | boolean | null, key?: string): QueryConstraint;

参数

参数	类型	说明
值	数字 |字符串 |布尔值 |null	起始值。参数类型取决于此查询中使用的 orderBy() 函数。请指定与 orderBy() 类型匹配的值。与 orderByKey() 结合使用时，值必须是字符串。
键	字符串	起始子键。只有当按子项、值或优先级排序时，才允许使用此参数。

返回：

QueryConstraint

EventType

以下任一字符串：“value”“child_added”“child_changed”“child_removed”或“child_moved”。

签名：

export declare type EventType = 'value' | 'child_added' | 'child_changed' | 'child_moved' | 'child_removed';

QueryConstraintType

介绍此 SDK 中提供的不同查询限制。

签名：

export declare type QueryConstraintType = 'endAt' | 'endBefore' | 'startAt' | 'startAfter' | 'limitToFirst' | 'limitToLast' | 'orderByChild' | 'orderByKey' | 'orderByPriority' | 'orderByValue' | 'equalTo';

退订

可以调用以移除监听器的回调。

签名：

export declare type Unsubscribe = () => void;