title: Reference

一个 SyncReference 实例表示要操作的特定数据节点，你可以通过它来读写数据。SyncReference 是 wilddog.sync.Query 的子类。

方法

child

定义

child(path)

说明

获得一个在当前节点下指定路径节点处的 SyncReference 实例。 根据相对路径 path，来获取当前节点下 path 子节点的引用。 相对路径可以是一个简单的节点路径（例如: "fred"），或者是一个更深的路径（例如: "fred/name/first"）。

参数
参数名 说明
path String(non-null)类型
path为相对路径，多层级间需要使用”/“分隔，例如“a/b”。如果path为空或null则返回当前引用。如果直接选取下一级节点，可以使用无分隔符(/)的节点名称表示，例如“a”。如果定位的path不存在，依然可以定位，后续数据操作的时候，将延迟动态创建不存在的路径节点。
返回值

wilddog.sync.Reference

  1. var config = {
  2.   authDomain: "<appId>.wilddog.com",
  3. };
  4. wilddog.initializeApp(config);
  5. var ref = wilddog.sync().ref("city");
  6. // ref 指向 <appId>.wilddogio.com/city
  8. var childRef = wilddog.sync().ref("city").child("Beijing");
  9. // childRef 指向 <appId>.wilddogio.com/city/Beijing

parent

定义

parent()

说明

获取当前节点的父节点引用。

注意：

如果当前节点是根节点，返回的依然是根节点的引用。
返回值

wilddog.sync.Reference

示例
  1. var config = {
  2.   authDomain: "<appId>.wilddog.com",
  3. };
  4. wilddog.initializeApp(config);
  5. var ref = wilddog.sync().ref("city");
  6. // ref 指向 <appId>.wilddogio.com/city
  8. var childRef = wilddog.sync().ref("city").child("Beijing");
  9. // childRef 指向 <appId>.wilddogio.com/city/Beijing
  11. var parentRef = childRef.parent();
  12. // parentRef 指向 <appId>.wilddogio.com/city

root

定义

root()

说明

获取根节点的引用。使用此方法可以直接获取到当前子节点的根节点引用，等价于多次调用 parent() 方法获取根节点。

返回值

wilddog.sync.Reference

key

定义

key()

说明

获取当前节点的 key 值。

返回值

String 节点 key 值

示例
  1. var child_ref = wilddog.sync().ref().child("Beijing");
  2. var key = child_ref.key();
  3. //key == 'Bejing'

toString

定义

toString()

说明

获取当前节点的的完整 URL 。

返回值

String 当前节点的完整 URL 。

示例
  1. var config = {
  2.   authDomain: "<appId>.wilddog.com",
  3. };
  4. wilddog.initializeApp(config);
  5. var ref = wilddog.sync().ref("city");
  6. var url = ref.toString();
  7. // url == 'https://<appId>.wilddogio.com/city'

set

定义

set(value)

说明

向指定节点写入数据。此方法会先清空指定节点，再写入数据。详细使用请参考：set() 完整指南-写入数据。

支持的数据类型：

  • Object、 Array、String、 Number、 Boolean 等基本数据类型; Wliddog Sync 没有对数组的原生支持，但是支持以数组下标作为 key ，数组元素作为 value 的方式进行存储。

例如：

  1.         var array = [];
  2.         array[0] = "a";
  3.         array[2] = "b";
  4.         array[3] = "c";
  5.         array[5] = "d";
  6.         //在数据库中存储为DataSnapshot { key = list, value = {0=a, 2=b, 3=c, 5=d} }
  7.         ref.child("list").setValue(array);

在数据监听中获取数据时，如果满足条件：当 0 到最大的 key（比如 n ） 之间，n+1 个元素中超过一半以上有值，数据将被转换为数组类型; 如果不满足条件，Wilddog Sync 处理数据时会将其转换为 JSON。

  • null 当 value 为 null 时，等价于当前节点的 remove() 操作，会删除当前节点。
参数
参数名 说明
value Object
String
Number
Boolean
null
如果value != null ，当前节点上的数据会被value覆盖，如果中间路径不存在， Wilddog 会自动将中间路径补全。如果value == null，效果等同于remove操作。
返回值

wilddog.Promise.<Void>

示例
  1. wilddog.sync().ref('city').set({"temp":10,"pm25":500})
  2.     .then(function(){
  3.         console.info('set data success.');
  4.     })
  5.     .catch(function(err){
  6.         console.info('set data failed', err.code, err);
  7.     });

update

定义

update(value)

说明

对当前节点进行数据合并操作，更新当前节点下的数据。详细使用请参考：update() 完整指南-更新数据。 与 set() 方法覆盖当前节点下所有数据的方式不同，使用 update() 方法，不存在的子节点将会被新增，存在的子节点将会被更新。 使用此方法可以对同一节点的子节点同时进行更新和删除操作。 update 支持多路径更新。需要同时向多个节点写入数据时，你应该优先考虑使用 update 而不是 transaction，具体使用方法参见下方示例。

参数
参数名 说明
value Object类型
包含要合并子节点的对象
返回值

wilddog.Promise.<Void>

示例
  1. // 普通更新
  2. wilddog.sync().ref('city').update({"temp":20,"pm25":5000})
  3.     .then(function(){
  4.         console.info('update data success.')
  5.     })
  6.     .catch(function(err){
  7.         console.info('update data failed', err.code, err);
  8.     });
  10. //多路径更新
  11. wilddog.sync().ref('/yourPath').update({
  12.          "users/john": {"name": "john", "group": "a"},
  13.          "groups/a/john": true
  14.     })
  15.     .then(function(){
  16.         console.info('update data success.')
  17.     })
  18.     .catch(function(err){
  19.         console.info('update data failed', err.code, err);
  20.     });
  21. // 在上面的例子中我们同时更新了两个节点，这是一个原子操作

remove

定义

remove()

说明

删除当前节点，效果等同于 set(null)，如果父级节点只有当前节点一个子节点，会递归删除父级节点。详细使用请参考：完整指南-删除数据。

返回值

wilddog.Promise.<Void>

示例
  1. wilddog.sync().ref('city').remove()
  2.     .then(function(){
  3.         console.info('remove node success.')
  4.     })
  5.     .catch(function(err){
  6.         console.info('remove node failed', err.code, err);
  7.     });

push

定义

push(value)

说明

向当前节点添加子节点。新增子节点的 key 自动生成并保证唯一（例如：-KdzI7I-AsBST9NlasJM）。 新增子节点的 key 基于时间戳和随机算法生成，并可以按照时间先后进行排序。详细使用请参考：完整指南-追加字节点。

参数
参数名 类型 属性 说明
value Object
String
Number
Boolean		 non-null 你希望在当前节点下新增的数据。
返回值

wilddog.Promise.<wilddog.sync.Reference>

示例
  1. wilddog.sync().ref("city").push('chengdu')
  2.     .then(function(newRef){
  3.        // newRef 的地址类似下面：
  4.        // https://<appId>.wilddogio.com/city/-JmRhjbYk73IFRZ7
  5.        console.info(newRef.toString());
  6.     })
  7.     .catch(function(err){
  8.        console.info('remove node failed', err.code, err);
  9.     });
  1. //也可以同步获取新的reference
  2. var newRef = wilddog.sync().ref("city").push('chengdu',function onComplete(err){
  3.     if(err == null){
  4.         //success
  5.     }
  6. })
  7. var newKey = newRef.key()

setWithPriority

定义

setWithPriority(value, priority)

说明

把数据写到当前位置，类似 set，不同之处是需要指定一个优先级。默认排序按照优先级排序（参考 orderByPriority）。详细使用请参考：完整指南-写入数据并设置节点优先级。

参数
参数名 说明
value Object
String
Number
Boolean
null
将被写入的值。
priority 优先级数据，节点的优先级是默认排序的依据。
返回值

wilddog.Promise.<Void>

示例
  1. var user = {
  2.   name: {
  3.     first: 'jack',
  4.     last: 'Lee'
  5.   }
  6. };
  7. wilddog.sync().ref().setWithPriority(user,100)
  8.     .then(function(){
  9.         console.info('set data success.')
  10.     })
  11.     .catch(function(err){
  12.         console.info('set data failed', err.code, err);
  13.     });

setPriority

定义

setPriority(priority)

说明

设置当前节点的优先级，支持为每个节点设置优先级 (priority)，用于实现节点按优先级排序。优先级是节点的隐藏属性，默认为 null。详细使用请参考：完整指南-设置节点优先级。 不能为不存在的节点设置优先级。因此，新增数据需要设置优先级时，请使用 setValue(data, priority)；为已存在的数据设置优先级的时，使用 setPriority。

节点按照如下优先级规则升序排列：null < Number < String。

  • priority 为 null 的排最先；
  • priority 为数值的次之，按照数值从小到大排序；
  • priority 为字符串的排最后，按照字典序排列。
  • 当两个子节点有相同的 priority（包括没有 priority），它们按照 key 进行排列，数字优先（按数值从小到大排序），其余以字典序排序。

注意：

数值优先级被作为 IEEE 754 双精度浮点型数字进行解析和排序， Key 以 String 类型进行存储，只有当它能被解析成 32 位整型数字时被当作数字来处理。
参数
参数名 说明
priority String
Number
优先级数据，节点的优先级是默认排序的依据。
返回值

wilddog.Promise.<Void>

示例
  1. wilddog.sync().ref('user').setWithPriority(100)
  2.     .then(function(){
  3.         console.info('set priority success.')
  4.     })
  5.     .catch(function(err){
  6.         console.info('set priority failed', err.code, err);
  7.     });

transaction

定义

transaction(updateFunction)

说明

用于多客户端并发写入操作时保证数据一致性，可以避免并发修改当前节点时的数据冲突。 与 set() 直接覆盖以前的数据不同，在不同客户端并发修改时，transaction() 不会单纯覆盖节点数据。 客户端提交事务至服务器，如果数据已被其他客户端修改，那么服务器会拒绝当前操作，并将新值返回到客户端，客户端使用新值再次运行事务处理。 在 transaction() 的执行过程中客户端可能会重复写入直到成功，也可以在 updateFunction 中直接 return; 手动终止事务。详细使用请参考：完整指南-事务处理。

注意：

- 相同的数据节点上并发执行 set() 和 transaction()，极端情况下仍会出现不可预料的结果。

- 如果只是需要同时向多个节点写入数据，请优先考虑使用 update 的多路径更新特性。

参数
参数名 说明
updateFunction updateFunction(non-null)类型
更新函数。
返回值

wilddog.Promise.<TransactionResult | TransactionResult[]>

示例
  1. // 实现一个累加器
  2. wilddog.sync().ref("/users/john/rank").transaction(function(currentRank) {
  3.     // If currentRank = null, 直接返回默认值 0。
  4.     if (currentRank == null) {
  5.          return 0;
  6.     } else if (currentRank >  1000) {
  7.         return; // 大于1000, 退出事务 transaction, 直接return;
  8.     }
  9.     return currentRank+1;
  10. });
  11. //
  12. //
  13. // 创建一个名叫 wilma 的用户， 如果 'wilma' 已经存在，那退出事务
  14. var wilmaRef = wilddog.sync().ref("/users/wilma");
  15. wilmaRef.transaction(function(currentData) {
  16.   if (currentData === null) {
  17.     return { name: { first: 'Wilma', last: 'Flintstone' } };
  18.   } else {
  19.     console.log('wilma is exist.');
  20.     return; // 退出事务
  21.   }
  22. }).then(function(result) {
  23.   if (!result.committed) {
  24.     console.log('transaction commit failed ,wilma has been exist.');
  25.   } else {
  26.     console.log('transaction commit success!');
  27.   }
  28.   console.log("Wilma's data: ", result.snapshot.val());
  29. }).catch(function(err){
  30.     console.log('transaction failed.', error);
  31. });

updateFunction

定义

function(currentValue)

说明

用于 transaction 的更新函数。

注意：

只有当 updateFunction 返回的是一个包含多个节点的 Object 时，transaction 才会返回给 Promise 一个TransactionResult 数组。
参数
参数名 说明
currentValue function
Object
String
Number
Boolean
null
第一次调用时 currentValue 为 null，你应当返回一个默认值。当回调函数第二次调用时， currentValue 是云端的最新值。
返回值

newValue {Object|String|Number|Boolean|null} 要写入当前节点的的新值。

当返回的是一个包含多个节点的 Object 时，transaction 会返回给 Promise 一个 TransactionResult 数组。

TransactionResult

定义

{“committed”: Boolean, “snapshot”: wilddog.sync.DataSnapshot}

说明

执行 transaction 成功之后返回给 Promise 的结果，包含committed 和 snapshot 两个属性。 committed: 是否提交成功。 snapshot: 事务完成后的数据快照。

onDisconnect

定义

onDisconnect()

说明

获取与当前数据节点关联的离线事件对象。详细使用请参考：完整指南-离线功能。

返回值

wilddog.sync.OnDisconnect