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

var config = {
  authDomain: "<SyncAppID>.wilddog.com",
};
wilddog.initializeApp(config);
var ref = wilddog.sync().ref("city");
// ref 指向 <SyncAppID>.wilddogio.com/city

var childRef = wilddog.sync().ref("city").child("Beijing");
// childRef 指向 <SyncAppID>.wilddogio.com/city/Beijing

parent

定义

parent()

说明

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


注意：


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

wilddog.sync.Reference

示例
var config = {
  authDomain: "<SyncAppID>.wilddog.com",
};
wilddog.initializeApp(config);
var ref = wilddog.sync().ref("city");
// ref 指向 <SyncAppID>.wilddogio.com/city

var childRef = wilddog.sync().ref("city").child("Beijing");
// childRef 指向 <SyncAppID>.wilddogio.com/city/Beijing

var parentRef = childRef.parent();
// parentRef 指向 <SyncAppID>.wilddogio.com/city

root

定义

root()

说明

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

返回值

wilddog.sync.Reference

key

定义

key()

说明

获取当前节点的 key 值。

返回值

String 节点 key 值

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

toString

定义

toString()

说明

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

返回值

String 当前节点的完整 URL 。

示例
var config = {
  authDomain: "<SyncAppID>.wilddog.com",
};
wilddog.initializeApp(config);
var ref = wilddog.sync().ref("city");
var url = ref.toString();
// url == 'https://<SyncAppID>.wilddogio.com/city'

set

定义

set(value)

说明

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

支持的数据类型：

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

例如：

var array = [];
array[0] = "a";
array[2] = "b";
array[3] = "c";
array[5] = "d";
//在数据库中存储为DataSnapshot { key = list, value = {0=a, 2=b, 3=c, 5=d} }
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>

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

update

定义

update(value)

说明

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

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

wilddog.Promise.<Void>

示例
// 普通更新
wilddog.sync().ref('city').update({"temp":20,"pm25":5000})
    .then(function(){
        console.info('update data success.')
    })
    .catch(function(err){
        console.info('update data failed', err.code, err);
    });

//多路径更新
wilddog.sync().ref('/yourPath').update({
         "users/john": {"name": "john", "group": "a"},
         "groups/a/john": true
    })
    .then(function(){
        console.info('update data success.')
    })
    .catch(function(err){
        console.info('update data failed', err.code, err);
    });
// 在上面的例子中我们同时更新了两个节点，这是一个原子操作

remove

定义

remove()

说明

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

返回值

wilddog.Promise.<Void>

示例
wilddog.sync().ref('city').remove()
    .then(function(){
        console.info('remove node success.')
    })
    .catch(function(err){
        console.info('remove node failed', err.code, err);
    });

push

定义

push(value)

说明

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

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

wilddog.Promise.<wilddog.sync.Reference>

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

setWithPriority

定义

setWithPriority(value, priority)

说明

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

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

wilddog.Promise.<Void>

示例
var user = {
  name: {
    first: 'jack',
    last: 'Lee'
  }
};
wilddog.sync().ref().setWithPriority(user,100)
    .then(function(){
        console.info('set data success.')
    })
    .catch(function(err){
        console.info('set data failed', err.code, err);
    });

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>

示例
wilddog.sync().ref('user').setWithPriority(100)
    .then(function(){
        console.info('set priority success.')
    })
    .catch(function(err){
        console.info('set priority failed', err.code, err);
    });

transaction

定义

transaction(updateFunction)

说明

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


注意：


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


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


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

wilddog.Promise.<TransactionResult | TransactionResult[]>

示例
// 实现一个累加器
wilddog.sync().ref("/users/john/rank").transaction(function(currentRank) {
    // If currentRank = null, 直接返回默认值 0。
    if (currentRank == null) {
         return 0;
    } else if (currentRank >  1000) {
        return; // 大于1000, 退出事务 transaction, 直接return;
    }
    return currentRank+1;
});
//
//
// 创建一个名叫 wilma 的用户， 如果 'wilma' 已经存在，那退出事务
var wilmaRef = wilddog.sync().ref("/users/wilma");
wilmaRef.transaction(function(currentData) {
  if (currentData === null) {
    return { name: { first: 'Wilma', last: 'Flintstone' } };
  } else {
    console.log('wilma is exist.');
    return; // 退出事务
  }
}).then(function(result) {
  if (!result.committed) {
    console.log('transaction commit failed ,wilma has been exist.');
  } else {
    console.log('transaction commit success!');
  }
  console.log("Wilma's data: ", result.snapshot.val());
}).catch(function(err){
    console.log('transaction failed.', error);
});

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

野狗新手？
立即注册，为你提供安全可靠的实时通信云服务。
免费注册
没找到需要的文档？
你可以提交工单反馈 或 阅读常见问题
客服工单常见问题