1# 分布式数据对象 2 3本模块提供管理基本数据对象的相关能力，包括创建、查询、删除、修改、订阅等；同时支持相同应用多设备间的分布式数据对象协同能力。 4 5> **说明：** 6> 7> 本模块首批接口从API version 8开始支持。后续版本的新增接口，采用上角标单独标记接口的起始版本。 8 9 10## 导入模块 11 12```js 13import distributedObject from '@ohos.data.distributedDataObject'; 14``` 15 16## distributedDataObject.createDistributedObject 17 18createDistributedObject(source: object): DistributedObject 19 20 21创建一个分布式对象。 22 23**系统能力：** SystemCapability.DistributedDataManager.DataObject.DistributedObject。 24 25**参数：** 26 | 参数名 | 类型 | 必填 | 说明 | 27 | -------- | -------- | -------- | -------- | 28 | source | object | 是 | 设置distributedObject的属性。 | 29 30**返回值：** 31| 类型 | 说明 | 32| -------- | -------- | 33| [DistributedObject](#distributedobject) | 创建完成的分布式对象。 | 34 35**示例：** 36 ```js 37 import distributedObject from '@ohos.data.distributedDataObject'; 38 // 创建对象，对象包含4个属性类型，string,number,boolean和Object 39 var g_object = distributedObject.createDistributedObject({name:"Amy", age:18, isVis:false, 40 parent:{mother:"jack mom",father:"jack Dad"}}); 41 ``` 42 43 44## distributedObject.genSessionId 45 46genSessionId(): string 47 48随机创建一个sessionId。 49 50**系统能力：** SystemCapability.DistributedDataManager.DataObject.DistributedObject。 51 52**返回值：** 53 | 类型 | 说明 | 54 | -------- | -------- | 55 | string | 随机创建的sessionId。 | 56 57**示例：** 58 ```js 59 import distributedObject from '@ohos.data.distributedDataObject'; 60 var sessionId = distributedObject.genSessionId(); 61 ``` 62 63 64## DistributedObject 65 66表示一个分布式对象。 67 68### setSessionId 69 70setSessionId(sessionId?: string): boolean 71 72设置同步的sessionId，当可信组网中有多个设备时，多个设备间的对象如果设置为同一个sessionId，就能自动同步。 73 74**系统能力：** SystemCapability.DistributedDataManager.DataObject.DistributedObject。 75 76**参数：** 77 78 | 参数名 | 类型 | 必填 | 说明 | 79 | -------- | -------- | -------- | -------- | 80 | sessionId | string | 否 | 分布式对象在可信组网中的标识ID。如果要退出分布式组网，设置为""或不设置均可。 | 81 82**返回值：** 83 84 | 类型 | 说明 | 85 | -------- | -------- | 86 | boolean | true：标识设置sessionId成功； <br>false：标识设置sessionId失败。 | 87 88**示例：** 89 90 ```js 91 import distributedObject from '@ohos.data.distributedDataObject'; 92 var g_object = distributedObject.createDistributedObject({name:"Amy", age:18, isVis:false, 93 parent:{mother:"jack mom",father:"jack Dad"}}); 94 //g_object加入分布式组网 95 g_object.setSessionId(distributedObject.genSessionId()); 96 //设置为""退出分布式组网 97 g_object.setSessionId(""); 98 ``` 99 100 101### on('change') 102 103on(type: 'change', callback: Callback<{ sessionId: string, fields: Array<string> }>): void 104 105监听分布式对象的变更。 106 107**系统能力：** SystemCapability.DistributedDataManager.DataObject.DistributedObject。 108 109**参数：** 110 | 参数名 | 类型 | 必填 | 说明 | 111 | -------- | -------- | -------- | -------- | 112 | type | string | 是 | 事件类型，固定为'change'，表示数据变更。 | 113 | callback | Callback<{ sessionId: string, fields: Array<string> }> | 是 | 变更回调对象实例。<br>sessionId：标识变更对象的sessionId； <br>fields：标识对象变更的属性名。 | 114 115**示例：** 116```js 117import distributedObject from '@ohos.data.distributedDataObject'; 118var g_object = distributedObject.createDistributedObject({name:"Amy", age:18, isVis:false,parent:{mother:"jack mom",father:"jack Dad"}}); 119globalThis.changeCallback = (sessionId, changeData) => { 120 console.info("change" + sessionId); 121 if (changeData != null && changeData != undefined) { 122 changeData.forEach(element => { 123 console.info("changed !" + element + " " + g_object[element]); 124 }); 125 } 126} 127g_object.on("change", globalThis.changeCallback); 128``` 129 130### off('change') 131 132off(type: 'change', callback?: Callback<{ sessionId: string, fields: Array<string> }>): void 133 134当不再进行数据变更监听时，使用此接口删除对象的变更监听。 135 136**系统能力：** SystemCapability.DistributedDataManager.DataObject.DistributedObject。 137 138**参数：** 139 | 参数名 | 类型 | 必填 | 说明 | 140 | -------- | -------- | -------- | -------- | 141 | type | string | 是 | 事件类型，固定为'change'，表示数据变更。 | 142 | callback | Callback<{ sessionId: string, fields: Array<string> }> | 否 | 需要删除的数据变更回调，若不设置则删除该对象所有的数据变更回调。<br>sessionId：标识变更对象的sessionId； <br>fields：标识对象变更的属性名。 | 143 144 145**示例：** 146```js 147import distributedObject from '@ohos.data.distributedDataObject'; 148var g_object = distributedObject.createDistributedObject({name:"Amy", age:18, isVis:false,parent:{mother:"jack mom",father:"jack Dad"}}); 149//删除数据变更回调changeCallback 150g_object.off("change", globalThis.changeCallback); 151//删除所有的数据变更回调 152g_object.off("change"); 153``` 154 155### on('status') 156 157on(type: 'status', callback: Callback<{ sessionId: string, networkId: string, status: 'online' | 'offline' }>): void 158 159监听分布式对象的上下线。 160 161**系统能力：** SystemCapability.DistributedDataManager.DataObject.DistributedObject。 162 163**参数：** 164 | 参数名 | 类型 | 必填 | 说明 | 165 | -------- | -------- | -------- | -------- | 166 | type | string | 是 | 事件类型，固定为'status'，表示对象上下线。 | 167 | callback | Callback<{ sessionId: string, networkId: string, status: 'online' \| 'offline' }> | 是 | 监听上下线回调实例。<br>sessionId：标识变更对象的sessionId； <br>networkId：标识对象设备的networkId； <br>status：标识对象为'online'(上线)或'offline'(下线)的状态。 | 168 169**示例：** 170```js 171import distributedObject from '@ohos.data.distributedDataObject'; 172globalThis.statusCallback = (sessionId, networkId, status) => { 173 globalThis.response += "status changed " + sessionId + " " + status + " " + networkId; 174} 175var g_object = distributedObject.createDistributedObject({name:"Amy", age:18, isVis:false,parent:{mother:"jack mom",father:"jack Dad"}}); 176g_object.on("status", globalThis.statusCallback); 177``` 178 179### off('status') 180 181off(type: 'status', callback?: Callback<{ sessionId: string, deviceId: string, status: 'online' | 'offline' }>): void 182 183 184当不再进行对象上下线监听时，使用此接口删除对象的上下线监听。 185 186**系统能力：** SystemCapability.DistributedDataManager.DataObject.DistributedObject。 187 188**参数：** 189 | 参数名 | 类型 | 必填 | 说明 | 190 | -------- | -------- | -------- | -------- | 191 | type | string | 是 | 事件类型，固定为'status'，表示对象上下线。 | 192 | callback | Callback<{ sessionId: string, deviceId: string, status: 'online' \| 'offline' }> | 否 | 需要删除的上下线回调，若不设置则删除该对象所有的上下线回调。<br>sessionId：标识变更对象的sessionId； <br>deviceId：标识变更对象的deviceId； <br>status：标识对象为'online'(上线)或'offline'(下线)的状态。 | 193 194 195**示例：** 196```js 197import distributedObject from '@ohos.data.distributedDataObject'; 198var g_object = distributedObject.createDistributedObject({name:"Amy", age:18, isVis:false,parent:{mother:"jack mom",father:"jack Dad"}}); 199globalThis.statusCallback = (sessionId, networkId, status) => { 200 globalThis.response += "status changed " + sessionId + " " + status + " " + networkId; 201} 202//删除上下线回调changeCallback 203g_object.off("status",globalThis.statusCallback); 204//删除所有的上下线回调 205g_object.off("status"); 206```