1# 分布式数据对象开发指导 2 3## 场景介绍 4 5分布式数据对象通过屏蔽设备间复杂的数据交互处理，提供了与本地变量类似的极简操作，当设备1的应用A的分布式数据对象增、删、改数据后，设备2的应用A也可以获取到对应的数据变化，同时还能监听数据变更以及对端数据对象的上下线。分布式数据对象支持的数据类型包括数字型、字符型、布尔型等基本类型，同时也支持数组、基本类型嵌套等复杂类型。 6 7 8## 接口说明 9具体分布式数据对象相关功能接口请见[分布式数据对象](../reference/apis/js-apis-data-distributedobject.md)。 10 11### 创建数据对象实例 12 13创建一个分布式数据对象实例，用户可以通过source指定分布式对象中的属性。 14 15 16**表1** 分布式数据对象实例创建接口 17| 包名 | 接口名 | 描述 | 18| -------- | -------- | -------- | 19| ohos.data.distributedDataObject| createDistributedObject(source: object): DistributedObject | 创建一个分布式数据对象实例，用于数据操作 <br>- source：设置distributedObject的属性。<br>- DistributedObject：返回值是创建好的分布式对象。| 20 21### 创建分布式数据对象sessionId 22 23创建一个随机的sessionId，可将其设置为一个分布式数据对象的sessionId。 24 25**表2** 分布式数据对象sessionId创建接口 26| 包名 | 接口名 | 描述 | 27| -------- | -------- | -------- | 28| ohos.data.distributedDataObject| genSessionId(): string | 创建一个sessionId，可作为分布式数据对象的sessionId | 29 30### 设置分布式数据对象sessionId 31 32设置分布式数据对象的sessionId，sessionId是一次（多设备）协同的唯一标识，同步的多个数据对象需要关联同一个sessionId。 33 34**表3** 分布式数据对象sessionId设置接口 35| 类名 | 接口名 | 描述 | 36| -------- | -------- | -------- | 37| DistributedDataObject | setSessionId(sessionId?: string): boolean | 为分布式数据对象设置sessionId <br> sessionId：分布式对象在可信组网中的标识ID。如果要退出分布式组网，设置为""或不设置均可。| 38 39### 订阅数据变更 40 41订阅数据变更需要指定Callback作为回调方法，订阅的数据对象发生数据变更后，Callback被回调。 42 43**表4** 分布式数据对象数据变更订阅接口 44| 类名 | 接口名 | 描述 | 45| -------- | -------- | -------- | 46| DistributedDataObject| on(type: 'change', callback: Callback<{ sessionId: string, fields: Array<string> }>): void | 订阅数据变更。 | 47| DistributedDataObject| off(type: 'change', callback?: Callback<{ sessionId: string, fields: Array<string> }>): void | 注销订阅。需要删除的变更回调，若不设置则删除该对象所有的变更回调。 | 48 49### 订阅数据对象上下线 50 51订阅数据对象上下线需要指定Callback作为回调方法，订阅的数据对象上线/下线后，对端的数据对象会收到Callback回调。 52 53**表5** 分布式数据对象数据上下线订阅接口 54| 类名 | 接口名 | 描述 | 55| -------- | -------- | -------- | 56| DistributedDataObject| on(type: 'status', callback: Callback<{ sessionId: string, networkId: string, status: 'online' \| 'offline' }>): void | 订阅数据对象上下线。 | 57| DistributedDataObject| off(type: 'status', callback?: Callback<{ sessionId: string, deviceId: string, status: 'online' \| 'offline' }>): void | 注销订阅。 | 58 59 60 61## 开发步骤 62 63以一次分布式数据对象同步为例，说明开发步骤。 64 651. 准备工作，导入@ohos.data.distributedDataObject模块到开发环境。 66 ```js 67 import distributedObject from '@ohos.data.distributedDataObject' 68 ``` 69 702. 获取分布式数据对象实例。 71 72 以下为创建分布式数据对象的代码示例： 73 ```js 74 var local_object = distributedObject.createDistributedObject({name:undefined, age:undefined, isVis:true, 75 parent:undefined, list:undefined}); 76 var sessionId = distributedObject.genSessionId(); 77 ``` 78 79 803. 加入同步组网。同步组网中的数据对象分为发起方和被拉起方。 81 82 以下为加入同步组网的代码示例: 83 84 ```js 85 //发起方 86 var local_object = distributedObject.createDistributedObject({name:"jack", age:18, isVis:true, 87 parent:{mother:"jack mom",father:"jack Dad"},list:[{mother:"jack mom"}, {father:"jack Dad"}]}); 88 local_object.setSessionId(sessionId); 89 90 //被拉起方 91 var remote_object = distributedObject.createDistributedObject({name:undefined, age:undefined, isVis:true, 92 parent:undefined, list:undefined}); 93 remote_object.setSessionId(sessionId); 94 //收到status上线后remote_object同步数据，即name变成jack,age是18 95 ``` 96 974. 监听对象数据变更。可监听对端数据的变更，以callback作为变更回调实例。 98 99 以下为监听对象数据变更的代码示例。 100 101 ```js 102 function changeCallback(sessionId, changeData) { 103 console.info("change" + sessionId); 104 105 if (changeData != null && changeData != undefined) { 106 changeData.forEach(element => { 107 console.info("changed !" + element + " " + local_object[element]); 108 }); 109 } 110 } 111 112 // 发起方要在changeCallback里刷新界面，则需要将正确的this绑定给changeCallback 113 local_object.on("change", this.changeCallback.bind(this)); 114 ``` 115 1165. 修改对象属性，对象属性支持基本类型（数字类型、布尔类型、字符串类型）以及复杂类型（数组、基本类型嵌套等）。 117 118 以下为修改分布式数据对象属性的代码示例： 119 ```js 120 local_object.name = "jack"; 121 local_object.age = 19; 122 local_object.isVis = false; 123 local_object.parent = {mother:"jack mom",father:"jack Dad"}; 124 local_object.list = [{mother:"jack mom"}, {father:"jack Dad"}]; 125 ``` 126 127 >  **说明：** 128 > 针对复杂类型的数据修改，目前支持对根属性的修改，暂不支持对下级属性的修改。示例如下： 129 ```js 130 //支持的修改方式 131 local_object.parent = {mother:"mom", father:"dad"}; 132 //不支持的修改方式 133 local_object.parent.mother = "mom"; 134 ``` 135 1366. 访问对象。可以通过直接获取的方式访问到分布式数据对象的属性，且该数据为组网内的最新数据。 137 138 以下为访问对象的代码示例： 139 ```js 140 console.info("name " + local_object["name"]); 141 ``` 1427. 删除监听数据变更。可以指定删除监听的数据变更回调；也可以不指定，这将会删除该分布式数据对象的所有数据变更回调。 143 144 以下为取消监听数据变更的代码示例： 145 ```js 146 //删除变更回调changeCallback 147 local_object.off("change", changeCallback); 148 //删除所有的变更回调 149 local_object.off("change"); 150 ``` 1518. 监听分布式对象的上下线。可以监听对端分布式数据对象的上下线。 152 以下为访问对象的代码示例： 153 ```js 154 function statusCallback(sessionId, networkId, status) { 155 this.response += "status changed " + sessionId + " " + status + " " + networkId; 156 } 157 158 local_object.on("status", this.statusCallback); 159 ``` 1609. 删除监听分布式对象的上下线。可以指定删除监听的上下线回调；也可以不指定，这将会删除该分布式数据对象的所有上下线回调。 161 162 以下为取消监听数据变更的代码示例： 163 ```js 164 //删除上下线回调statusCallback 165 local_object.off("status", statusCallback); 166 //删除所有的上下线回调 167 local_object.off("status"); 168 ``` 16910. 退出同步组网。分布式对象退出组网后，本地的数据变更对端不会同步。 170 171 以下为退出同步组网的代码示例： 172 ```js 173 local_object.setSessionId(""); 174 ``` 175 176 177
