js-apis-data-distributedobject.md 25.0 KB
Newer Older
Z
zengyawen 已提交
1
# @ohos.data.distributedDataObject (分布式数据对象)
L
li_juntao 已提交
2

3 4
本模块提供管理基本数据对象的相关能力,包括创建、查询、删除、修改、订阅等;同时支持相同应用多设备间的分布式数据对象协同能力。

G
ge-yafang 已提交
5
> **说明:**
6
>
L
li_juntao 已提交
7
> 本模块首批接口从API version 8开始支持。后续版本的新增接口,采用上角标单独标记接口的起始版本。
L
LiRui 已提交
8
> 本模块接口仅支持在JS文件中使用。
L
li_juntao 已提交
9 10 11 12 13


## 导入模块

```js
G
ge-yafang 已提交
14
import distributedObject from '@ohos.data.distributedDataObject';
L
li_juntao 已提交
15 16
```

17
## distributedObject.create<sup>9+</sup>
L
li_juntao 已提交
18

W
wangxiyue 已提交
19
create(context: Context, source: object): DataObject
L
li_juntao 已提交
20

21
创建一个分布式数据对象。
W
wuyongning 已提交
22

23
**系统能力:** SystemCapability.DistributedDataManager.DataObject.DistributedObject
W
wuyongning 已提交
24

W
wuyongning 已提交
25
**参数:**
26

L
li_juntao 已提交
27 28
  | 参数名 | 类型 | 必填 | 说明 |
  | -------- | -------- | -------- | -------- |
29
  | context | Context | 是 | 应用的上下文。 <br>FA模型的应用Context定义见[Context](js-apis-inner-app-context.md)<br>Stage模型的应用Context定义见[Context](js-apis-inner-application-uiAbilityContext.md)。 |
30
  | source | object | 是 | 设置分布式数据对象的属性。 |
31

W
wuyongning 已提交
32
**返回值:**
33

G
ge-yafang 已提交
34 35
| 类型 | 说明 |
| -------- | -------- |
W
wangxiyue 已提交
36
| [DataObject](#dataobject) | 创建完成的分布式数据对象。 |
W
wuyongning 已提交
37 38

**示例:**
39

40 41
FA模型示例:

W
wufengshan 已提交
42
```js
43
// 导入模块
W
wufengshan 已提交
44
import distributedObject from '@ohos.data.distributedDataObject';
45 46 47
import featureAbility from '@ohos.ability.featureAbility';
// 获取context
let context = featureAbility.getContext();
L
LiRui 已提交
48 49
// 创建对象,该对象包含4个属性类型:string、number、boolean和Object
let g_object = distributedObject.create(context, {name:"Amy", age:18, isVis:false, parent:{mother:"jack mom",father:"jack Dad"}});
W
wufengshan 已提交
50
```
L
li_juntao 已提交
51

52 53 54 55 56
Stage模型示例:

```ts
// 导入模块
import distributedObject from '@ohos.data.distributedDataObject';
57
import UIAbility from '@ohos.app.ability.UIAbility';
L
LiRui 已提交
58 59 60

let g_object;

61
class EntryAbility extends UIAbility {
L
LiRui 已提交
62 63 64
    onWindowStageCreate(windowStage){
        // 创建对象,该对象包含4个属性类型:string、number、boolean和Object
        g_object = distributedObject.create(this.context, {name:"Amy", age:18, isVis:false, parent:{mother:"jack mom",father:"jack Dad"}});
65 66 67
    }
}
```
L
li_juntao 已提交
68

69
## distributedObject.genSessionId
L
li_juntao 已提交
70 71 72

genSessionId(): string

W
wuyongning 已提交
73
随机创建一个sessionId。
L
li_juntao 已提交
74

75
**系统能力:** SystemCapability.DistributedDataManager.DataObject.DistributedObject
L
li_juntao 已提交
76

W
wuyongning 已提交
77
**返回值:**
78

L
li_juntao 已提交
79 80 81 82
  | 类型 | 说明 |
  | -------- | -------- |
  | string | 随机创建的sessionId。 |

W
wuyongning 已提交
83
**示例:**
84

W
wufengshan 已提交
85 86
```js
import distributedObject from '@ohos.data.distributedDataObject';
L
LiRui 已提交
87
let sessionId = distributedObject.genSessionId();
W
wufengshan 已提交
88
```
L
li_juntao 已提交
89

90
## SaveSuccessResponse<sup>9+</sup>
91 92 93

save接口回调信息。

94
**系统能力:** SystemCapability.DistributedDataManager.DataObject.DistributedObject
95

W
wangdengze 已提交
96 97 98 99 100
| 名称 | 类型 | 必填 | 说明 |
| -------- | -------- | -------- | -------- |
| sessionId | string | 是 | 多设备协同的唯一标识。 |
| version | number | 是 | 已保存对象的版本。 |
| deviceId | string | 是 | 存储数据的设备号,标识需要保存对象的设备。默认为"local",标识本地设备;可自定义设置其他标识设备的字符串。 |
101

102
## RevokeSaveSuccessResponse<sup>9+</sup>
103 104 105

revokeSave接口回调信息。

106
**系统能力:** SystemCapability.DistributedDataManager.DataObject.DistributedObject
107

W
wangdengze 已提交
108 109 110
| 名称 | 类型 | 必填 | 说明 |
| -------- | -------- | -------- | -------- |
| sessionId | string | 是 | 多设备协同的唯一标识。 |
L
li_juntao 已提交
111

W
wangxiyue 已提交
112
## DataObject
L
li_juntao 已提交
113

W
wangxiyue 已提交
114
表示一个分布式数据对象。在使用以下接口前,需调用[create()](#distributedobjectcreate9)获取DataObject对象。
115

116
### setSessionId<sup>9+</sup>
L
li_juntao 已提交
117

118
setSessionId(sessionId: string, callback: AsyncCallback&lt;void&gt;): void
L
li_juntao 已提交
119

W
wuyongning 已提交
120
设置同步的sessionId,当可信组网中有多个设备时,多个设备间的对象如果设置为同一个sessionId,就能自动同步。
L
li_juntao 已提交
121

122
**需要权限:** ohos.permission.DISTRIBUTED_DATASYNC。
W
wufengshan 已提交
123

124 125 126 127 128 129 130 131 132 133 134
**系统能力:** SystemCapability.DistributedDataManager.DataObject.DistributedObject

**参数:**

  | 参数名 | 类型 | 必填 | 说明 |
  | -------- | -------- | -------- | -------- |
  | sessionId | string | 是 | 分布式数据对象在可信组网中的标识ID。|
  | callback | AsyncCallback&lt;void&gt; | 是 | 加入session的异步回调。|

**错误码:**

Z
zengyawen 已提交
135
  以下错误码的详细介绍参见[分布式数据对象错误码](../errorcodes/errorcode-distributed-dataObject.md)
136

137
  | 错误码ID | 错误信息 |
138
  | -------- | -------- |
L
LiRui 已提交
139
  | 15400001 | Create table failed.|
140 141 142 143 144 145

**示例:**

```js
// g_object加入分布式组网
g_object.setSessionId(distributedObject.genSessionId(), ()=>{
W
wangxiyue 已提交
146
    console.info("join session");
147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167
});
```

### setSessionId<sup>9+</sup>

setSessionId(callback: AsyncCallback&lt;void&gt;): void

退出所有已加入的session。

**需要权限:** ohos.permission.DISTRIBUTED_DATASYNC。

**系统能力:** SystemCapability.DistributedDataManager.DataObject.DistributedObject

**参数:**

  | 参数名 | 类型 | 必填 | 说明 |
  | -------- | -------- | -------- | -------- |
  | callback | AsyncCallback&lt;void&gt; | 是 | 退出所有已加入session的异步回调。 |

**错误码:**

Z
zengyawen 已提交
168
  以下错误码的详细介绍参见[分布式数据对象错误码](../errorcodes/errorcode-distributed-dataObject.md)
169

170
  | 错误码ID | 错误信息 |
171
  | -------- | -------- |
L
LiRui 已提交
172
  | 15400001 | Create table failed.|
173 174 175 176 177 178

**示例:**

```js
// g_object加入分布式组网
g_object.setSessionId(distributedObject.genSessionId(), ()=>{
W
wangxiyue 已提交
179
    console.info("join session");
180 181 182
});
// 退出分布式组网
g_object.setSessionId(() => {
L
LiRui 已提交
183
    console.info("leave all session.");
184 185 186 187 188 189 190 191 192 193 194 195
});
```

### setSessionId<sup>9+</sup>

setSessionId(sessionId?: string): Promise&lt;void&gt;

设置同步的sessionId,当可信组网中有多个设备时,多个设备间的对象如果设置为同一个sessionId,就能自动同步。

**需要权限:** ohos.permission.DISTRIBUTED_DATASYNC。

**系统能力:** SystemCapability.DistributedDataManager.DataObject.DistributedObject
W
wuyongning 已提交
196

W
wuyongning 已提交
197
**参数:**
198

L
li_juntao 已提交
199 200
  | 参数名 | 类型 | 必填 | 说明 |
  | -------- | -------- | -------- | -------- |
201
  | sessionId | string | 否 | 分布式数据对象在可信组网中的标识ID。如果要退出分布式组网,设置为""或不设置均可。 |
W
wuyongning 已提交
202

W
wuyongning 已提交
203
**返回值:**
204

205 206 207 208 209 210
| 类型 | 说明 |
| -------- | -------- |
| Promise&lt;void&gt; | Promise对象。|

**错误码:**

Z
zengyawen 已提交
211
  以下错误码的详细介绍参见[分布式数据对象错误码](../errorcodes/errorcode-distributed-dataObject.md)
212

213
  | 错误码ID | 错误信息 |
W
wuyongning 已提交
214
  | -------- | -------- |
L
LiRui 已提交
215
  | 15400001 | Create table failed.|
G
ge-yafang 已提交
216

W
wuyongning 已提交
217
**示例:**
218

W
wufengshan 已提交
219
```js
220 221 222
// g_object加入分布式组网
g_object.setSessionId(distributedObject.genSessionId()).then (()=>{
    console.info("join session.");
L
LiRui 已提交
223
    }).catch((error)=>{
224 225 226 227
        console.info("error:" + error.code + error.message);
});
// 退出分布式组网
g_object.setSessionId().then (()=>{
L
LiRui 已提交
228
    console.info("leave all session.");
L
LiRui 已提交
229
    }).catch((error)=>{
230 231
        console.info("error:" + error.code + error.message);
});
W
wufengshan 已提交
232
```
L
li_juntao 已提交
233

234
### on('change')<sup>9+</sup>
L
li_juntao 已提交
235 236 237

on(type: 'change', callback: Callback<{ sessionId: string, fields: Array&lt;string&gt; }>): void

238
监听分布式数据对象的数据变更。
L
li_juntao 已提交
239

240
**系统能力:** SystemCapability.DistributedDataManager.DataObject.DistributedObject
L
li_juntao 已提交
241

W
wuyongning 已提交
242
**参数:**
243

L
li_juntao 已提交
244 245 246
  | 参数名 | 类型 | 必填 | 说明 |
  | -------- | -------- | -------- | -------- |
  | type | string | 是 | 事件类型,固定为'change',表示数据变更。 |
W
wuyongning 已提交
247
  | callback | Callback<{ sessionId: string, fields: Array&lt;string&gt; }> | 是 | 变更回调对象实例。<br>sessionId:标识变更对象的sessionId; <br>fields:标识对象变更的属性名。 |
L
li_juntao 已提交
248

W
wuyongning 已提交
249
**示例:**
250

251
```js
L
LiRui 已提交
252 253 254 255 256 257
globalThis.changeCallback = (sessionId, changeData) => {
    console.info("change" + sessionId);
    if (changeData != null && changeData != undefined) {
        changeData.forEach(element => {
        console.info("changed !" + element + " " + g_object[element]);
        });
L
LiRui 已提交
258
    }
L
LiRui 已提交
259 260
}
g_object.on("change", globalThis.changeCallback);
261 262 263
```

### off('change')<sup>9+</sup>
L
li_juntao 已提交
264 265 266

off(type: 'change', callback?: Callback<{ sessionId: string, fields: Array&lt;string&gt; }>): void

W
wuyongning 已提交
267
当不再进行数据变更监听时,使用此接口删除对象的变更监听。
L
li_juntao 已提交
268

269
**系统能力:** SystemCapability.DistributedDataManager.DataObject.DistributedObject
W
wuyongning 已提交
270

W
wuyongning 已提交
271
**参数:**
272

L
li_juntao 已提交
273 274 275
  | 参数名 | 类型 | 必填 | 说明 |
  | -------- | -------- | -------- | -------- |
  | type | string | 是 | 事件类型,固定为'change',表示数据变更。 |
W
wufengshan 已提交
276
  | callback | Callback<{ sessionId: string, fields: Array&lt;string&gt; }> | 否 | 需要删除的数据变更回调,若不设置则删除该对象所有的数据变更回调。<br>sessionId:标识变更对象的sessionId; <br>fields:标识对象变更的属性名。 |
L
li_juntao 已提交
277 278


W
wuyongning 已提交
279
**示例:**
280

281
```js
282
// 删除数据变更回调changeCallback
L
LiRui 已提交
283
g_object.off("change", globalThis.changeCallback);
284 285 286 287 288
// 删除所有的数据变更回调
g_object.off("change");
```

### on('status')<sup>9+</sup>
L
li_juntao 已提交
289 290 291

on(type: 'status', callback: Callback<{ sessionId: string, networkId: string, status: 'online' | 'offline' }>): void

292
监听分布式数据对象的上下线。
L
li_juntao 已提交
293

294
**系统能力:** SystemCapability.DistributedDataManager.DataObject.DistributedObject
W
wuyongning 已提交
295

W
wuyongning 已提交
296
**参数:**
297

L
li_juntao 已提交
298 299 300
  | 参数名 | 类型 | 必填 | 说明 |
  | -------- | -------- | -------- | -------- |
  | type | string | 是 | 事件类型,固定为'status',表示对象上下线。 |
301
  | callback | Callback<{ sessionId: string, networkId: string, status: 'online' \| 'offline' }> | 是 | 监听上下线回调实例。<br>sessionId:标识变更对象的sessionId; <br>networkId:标识对象设备,即deviceId; <br>status:标识对象为'online'(上线)或'offline'(下线)的状态。 |
W
wuyongning 已提交
302 303

**示例:**
304

305
```js
L
LiRui 已提交
306 307
globalThis.statusCallback = (sessionId, networkId, status) => {
    globalThis.response += "status changed " + sessionId + " " + status + " " + networkId;
308
}
L
LiRui 已提交
309
g_object.on("status", globalThis.statusCallback);
310
```
L
li_juntao 已提交
311

312
### off('status')<sup>9+</sup>
L
li_juntao 已提交
313 314 315

off(type: 'status', callback?: Callback<{ sessionId: string, deviceId: string, status: 'online' | 'offline' }>): void

W
wuyongning 已提交
316
当不再进行对象上下线监听时,使用此接口删除对象的上下线监听。
L
li_juntao 已提交
317

318
**系统能力:** SystemCapability.DistributedDataManager.DataObject.DistributedObject
L
li_juntao 已提交
319

W
wuyongning 已提交
320
**参数:**
321

L
li_juntao 已提交
322 323 324
  | 参数名 | 类型 | 必填 | 说明 |
  | -------- | -------- | -------- | -------- |
  | type | string | 是 | 事件类型,固定为'status',表示对象上下线。 |
W
wuyongning 已提交
325
  | callback | Callback<{ sessionId: string, deviceId: string, status: 'online' \| 'offline' }> | 否 | 需要删除的上下线回调,若不设置则删除该对象所有的上下线回调。<br>sessionId:标识变更对象的sessionId; <br>deviceId:标识变更对象的deviceId; <br>status:标识对象为'online'(上线)或'offline'(下线)的状态。 |
L
li_juntao 已提交
326 327


W
wuyongning 已提交
328
**示例:**
329

330
```js
L
LiRui 已提交
331 332
globalThis.statusCallback = (sessionId, networkId, status) => {
    globalThis.response += "status changed " + sessionId + " " + status + " " + networkId;
333
}
“wangxiyue” 已提交
334
// 删除上下线回调changeCallback
L
LiRui 已提交
335
g_object.off("status",globalThis.statusCallback);
“wangxiyue” 已提交
336
// 删除所有的上下线回调
337 338
g_object.off("status");
```
339

340
### save<sup>9+</sup>
341 342 343 344 345 346 347 348 349 350 351 352 353

save(deviceId: string, callback: AsyncCallback&lt;SaveSuccessResponse&gt;): void

保存分布式数据对象。使用callback方式异步回调。

对象数据保存成功后,当应用存在时不会释放对象数据,当应用退出后,重新进入应用时,恢复保存在设备上的数据。

有以下几种情况时,保存的数据将会被释放:

- 存储时间超过24小时。
- 应用卸载。
- 成功恢复数据之后。

354
**系统能力:** SystemCapability.DistributedDataManager.DataObject.DistributedObject
355 356

**参数:**
357

358 359 360
  | 参数名 | 类型 | 必填 | 说明 |
  | -------- | -------- | -------- | -------- |
  | deviceId | string | 是 | 保存数据的deviceId,当deviceId为"local",代表存储在本地设备。 |
W
wufengshan 已提交
361
  | callback | AsyncCallback&lt;[SaveSuccessResponse](#savesuccessresponse9)&gt; | 是 | 回调函数。返回SaveSuccessResponse,包含sessionId、version、deviceId等信息。 |
362 363

**示例:**
364

W
wangxiyue 已提交
365
```ts
W
wufengshan 已提交
366
g_object.setSessionId("123456");
L
LiRui 已提交
367
g_object.save("local", (err, result) => {
W
wangxiyue 已提交
368 369 370 371 372
    if (err) {
        console.info("save failed, error code = " + err.code);
        console.info("save failed, error message: " + err.message);
        return;
    }
W
wangxiyue 已提交
373
    console.info("save callback");
W
wangxiyue 已提交
374 375 376
    console.info("save sessionId: " + result.sessionId);
    console.info("save version: " + result.version);
    console.info("save deviceId:  " + result.deviceId);
W
wufengshan 已提交
377 378
});
```
379

380
### save<sup>9+</sup>
381 382 383 384 385 386 387 388 389 390 391 392 393

save(deviceId: string): Promise&lt;SaveSuccessResponse&gt;

保存分布式数据对象。使用Promise方式作为异步回调。

对象数据保存成功后,当应用存在时不会释放对象数据,当应用退出后,重新进入应用时,恢复保存在设备上的数据。

有以下几种情况时,保存的数据将会被释放:

- 存储时间超过24小时。
- 应用卸载。
- 成功恢复数据之后。

394
**系统能力:** SystemCapability.DistributedDataManager.DataObject.DistributedObject
395 396

**参数:**
397

398 399 400 401
  | 参数名 | 类型 | 必填 | 说明 |
  | -------- | -------- | -------- | -------- |
  | deviceId | string | 是 | 保存数据的设备号,当deviceId默认为"local",标识需要保存对象的设备。 |

W
wufengshan 已提交
402
**返回值:**
403 404 405

  | 类型 | 说明 |
  | -------- | -------- |
W
wufengshan 已提交
406
  | Promise&lt;[SaveSuccessResponse](#savesuccessresponse9)&gt; | Promise对象。返回SaveSuccessResponse,包含sessionId、version、deviceId等信息。|
407 408 409

**示例:**

W
wufengshan 已提交
410
```js
411
g_object.setSessionId("123456");
L
LiRui 已提交
412
g_object.save("local").then((result) => {
W
wangxiyue 已提交
413
    console.info("save callback");
W
wufengshan 已提交
414 415 416
    console.info("save sessionId " + result.sessionId);
    console.info("save version " + result.version);
    console.info("save deviceId " + result.deviceId);
L
LiRui 已提交
417
}).catch((err) => {
W
wangxiyue 已提交
418 419
    console.info("save failed, error code = " + err.code);
    console.info("save failed, error message: " + err.message);
W
wufengshan 已提交
420 421
});
```
422

423
### revokeSave<sup>9+</sup>
424

425
revokeSave(callback: AsyncCallback&lt;RevokeSaveSuccessResponse&gt;): void
426 427 428 429 430 431

撤回保存的分布式数据对象。使用callback方式作为异步方法。

如果对象保存在本地设备,那么将删除所有受信任设备上所保存的数据。
如果对象保存在其他设备,那么将删除本地设备上的数据。

432
**系统能力:** SystemCapability.DistributedDataManager.DataObject.DistributedObject
433 434

**参数:**
435

436 437
  | 参数名 | 类型 | 必填 | 说明 |
  | -------- | -------- | -------- | -------- |
438
  | callback | AsyncCallback&lt;[RevokeSaveSuccessResponse](#revokesavesuccessresponse9)&gt; | 是 | 回调函数。返回RevokeSaveSuccessResponse,包含sessionId。 |
439 440 441

**示例:**

W
wufengshan 已提交
442 443
```js
g_object.setSessionId("123456");
W
wangxiyue 已提交
444
// 持久化数据
L
LiRui 已提交
445
g_object.save("local", (err, result) => {
W
wangxiyue 已提交
446 447 448 449 450
    if (err) {
        console.info("save failed, error code = " + err.code);
        console.info("save failed, error message: " + err.message);
        return;
    }
W
wangxiyue 已提交
451
    console.info("save callback");
W
wangxiyue 已提交
452 453 454
    console.info("save sessionId: " + result.sessionId);
    console.info("save version: " + result.version);
    console.info("save deviceId:  " + result.deviceId);
W
wangxiyue 已提交
455 456
});
// 删除持久化保存的数据
L
LiRui 已提交
457
g_object.revokeSave((err, result) => {
W
wangxiyue 已提交
458 459 460 461 462 463 464
    if (err) {
      console.info("revokeSave failed, error code = " + err.code);
      console.info("revokeSave failed, error message: " + err.message);
      return;
    }
    console.info("revokeSave callback");
    console.info("revokeSave sessionId " + result.sessionId);
W
wufengshan 已提交
465 466
});
```
467

468
### revokeSave<sup>9+</sup>
469

470
revokeSave(): Promise&lt;RevokeSaveSuccessResponse&gt;
471 472 473 474 475 476

撤回保存的分布式数据对象。使用Promise方式作为异步方法。

如果对象保存在本地设备,那么将删除所有受信任设备上所保存的数据。
如果对象保存在其他设备,那么将删除本地设备上的数据。

477
**系统能力:** SystemCapability.DistributedDataManager.DataObject.DistributedObject
478

W
wufengshan 已提交
479
**返回值:**
480 481 482

  | 类型 | 说明 |
  | -------- | -------- |
W
wufengshan 已提交
483
  | Promise&lt;[RevokeSaveSuccessResponse](#revokesavesuccessresponse9)&gt; | Promise对象。返回RevokeSaveSuccessResponse,包含sessionId。 |
484 485 486

**示例:**

W
wangxiyue 已提交
487
```ts
W
wufengshan 已提交
488
g_object.setSessionId("123456");
W
wangxiyue 已提交
489
// 持久化数据
L
LiRui 已提交
490
g_object.save("local").then((result) => {
W
wangxiyue 已提交
491
    console.info("save callback");
492 493 494
    console.info("save sessionId " + result.sessionId);
    console.info("save version " + result.version);
    console.info("save deviceId " + result.deviceId);
L
LiRui 已提交
495
}).catch((err) => {
W
wangxiyue 已提交
496 497
    console.info("save failed, error code = " + err.code);
    console.info("save failed, error message: " + err.message);
498
});
W
wangxiyue 已提交
499
// 删除持久化保存的数据
L
LiRui 已提交
500
g_object.revokeSave().then((result) => {
W
wangxiyue 已提交
501 502
    console.info("revokeSave callback");
    console.info("sessionId" + result.sessionId);
L
LiRui 已提交
503
}).catch((err)=> {
W
wangxiyue 已提交
504 505
    console.info("revokeSave failed, error code = " + err.code);
    console.info("revokeSave failed, error message = " + err.message);
W
wangxiyue 已提交
506
});
507 508 509 510 511 512 513 514 515 516 517 518 519 520 521 522 523 524 525 526 527 528 529 530 531 532 533 534 535 536 537
```

## distributedObject.createDistributedObject<sup>(deprecated)</sup>

createDistributedObject(source: object): DistributedObject


创建一个分布式数据对象。

> **说明:**
>
> 从 API Version 8 开始支持,从 API Version 9 开始废弃,建议使用distributedObject.create替代。

**系统能力:** SystemCapability.DistributedDataManager.DataObject.DistributedObject

**参数:**

  | 参数名 | 类型 | 必填 | 说明 |
  | -------- | -------- | -------- | -------- |
  | source | object | 是 | 设置分布式数据对象的属性。 |

**返回值:**

| 类型 | 说明 |
| -------- | -------- |
| [DistributedObject](#distributedobjectdeprecated) | 创建完成的分布式数据对象。 |

**示例:**

```js
import distributedObject from '@ohos.data.distributedDataObject';
L
LiRui 已提交
538 539
// 创建对象,对象包含4个属性类型,string,number,boolean和Object
let g_object = distributedObject.createDistributedObject({name:"Amy", age:18, isVis:false, parent:{mother:"jack mom",father:"jack Dad"}});
540 541 542 543
```

## DistributedObject<sup>(deprecated)</sup>

W
wangxiyue 已提交
544
表示一个分布式数据对象。在使用以下接口前,需调用[createDistributedObject()](#distributedobjectcreatedistributedobjectdeprecated)获取DistributedObject对象。
545 546 547 548 549 550 551 552 553 554 555 556 557 558 559 560 561 562 563 564 565 566 567 568 569 570 571 572 573 574 575

### setSessionId<sup>(deprecated)</sup>

setSessionId(sessionId?: string): boolean

设置同步的sessionId,当可信组网中有多个设备时,多个设备间的对象如果设置为同一个sessionId,就能自动同步。

> **说明:**
>
> 从 API Version 8 开始支持,从 API Version 9 开始废弃,建议使用[setSessionId](#setsessionid9)替代。

**需要权限:** ohos.permission.DISTRIBUTED_DATASYNC。

**系统能力:** SystemCapability.DistributedDataManager.DataObject.DistributedObject

**参数:**

  | 参数名 | 类型 | 必填 | 说明 |
  | -------- | -------- | -------- | -------- |
  | sessionId | string | 否 | 分布式数据对象在可信组网中的标识ID。如果要退出分布式组网,设置为""或不设置均可。 |

**返回值:**

  | 类型 | 说明 |
  | -------- | -------- |
  | boolean | true:标识设置sessionId成功。 <br>false:标识设置sessionId失败。 |

**示例:**

```js
import distributedObject from '@ohos.data.distributedDataObject';
L
LiRui 已提交
576
let g_object = distributedObject.createDistributedObject({name:"Amy", age:18, isVis:false, parent:{mother:"jack mom",father:"jack Dad"}});;
577 578 579 580 581 582 583 584 585 586 587 588 589 590 591 592 593 594 595 596 597 598 599 600 601 602 603 604
// g_object加入分布式组网
g_object.setSessionId(distributedObject.genSessionId());
// 设置为""退出分布式组网
g_object.setSessionId("");
```

### on('change')<sup>(deprecated)</sup>

on(type: 'change', callback: Callback<{ sessionId: string, fields: Array&lt;string&gt; }>): void

监听分布式数据对象的变更。

> **说明:**
>
> 从 API Version 8 开始支持,从 API Version 9 开始废弃,建议使用[on('change')](#onchange9)替代。

**系统能力:** SystemCapability.DistributedDataManager.DataObject.DistributedObject

**参数:**

  | 参数名 | 类型 | 必填 | 说明 |
  | -------- | -------- | -------- | -------- |
  | type | string | 是 | 事件类型,固定为'change',表示数据变更。 |
  | callback | Callback<{ sessionId: string, fields: Array&lt;string&gt; }> | 是 | 变更回调对象实例。<br>sessionId:标识变更对象的sessionId; <br>fields:标识对象变更的属性名。 |

**示例:**

```js
W
wangxiyue 已提交
605
import distributedObject from '@ohos.data.distributedDataObject';
L
LiRui 已提交
606 607 608 609 610 611 612
let g_object = distributedObject.createDistributedObject({name:"Amy", age:18, isVis:false, parent:{mother:"jack mom",father:"jack Dad"}});
globalThis.changeCallback = (sessionId, changeData) => {
    console.info("change" + sessionId);
    if (changeData != null && changeData != undefined) {
        changeData.forEach(element => {
        console.info("changed !" + element + " " + g_object[element]);
        });
L
LiRui 已提交
613
    }
L
LiRui 已提交
614 615
}
g_object.on("change", globalThis.changeCallback);
616 617 618 619 620 621 622 623 624 625 626 627 628 629 630 631 632 633 634 635 636 637 638 639 640
```

### off('change')<sup>(deprecated)</sup>

off(type: 'change', callback?: Callback<{ sessionId: string, fields: Array&lt;string&gt; }>): void

当不再进行数据变更监听时,使用此接口删除对象的变更监听。

> **说明:**
>
> 从 API Version 8 开始支持,从 API Version 9 开始废弃,建议使用[off('change')](#offchange9)替代。

**系统能力:** SystemCapability.DistributedDataManager.DataObject.DistributedObject

**参数:**

  | 参数名 | 类型 | 必填 | 说明 |
  | -------- | -------- | -------- | -------- |
  | type | string | 是 | 事件类型,固定为'change',表示数据变更。 |
  | callback | Callback<{ sessionId: string, fields: Array&lt;string&gt; }> | 否 | 需要删除的数据变更回调,若不设置则删除该对象所有的数据变更回调。<br>sessionId:标识变更对象的sessionId; <br>fields:标识对象变更的属性名。 |


**示例:**

```js
W
wangxiyue 已提交
641
import distributedObject from '@ohos.data.distributedDataObject';
L
LiRui 已提交
642
let g_object = distributedObject.createDistributedObject({name:"Amy", age:18, isVis:false, parent:{mother:"jack mom",father:"jack Dad"}});
643
// 删除数据变更回调changeCallback
L
LiRui 已提交
644
g_object.off("change", globalThis.changeCallback);
645 646 647 648 649 650 651 652 653 654 655 656 657 658 659 660 661 662 663 664 665 666 667 668 669 670 671
// 删除所有的数据变更回调
g_object.off("change");
```

### on('status')<sup>(deprecated)</sup>

on(type: 'status', callback: Callback<{ sessionId: string, networkId: string, status: 'online' | 'offline' }>): void

监听分布式数据对象的上下线。

> **说明:**
>
> 从 API Version 8 开始支持,从 API Version 9 开始废弃,建议使用[on('status')](#onstatus9)替代。

**系统能力:** SystemCapability.DistributedDataManager.DataObject.DistributedObject

**参数:**

  | 参数名 | 类型 | 必填 | 说明 |
  | -------- | -------- | -------- | -------- |
  | type | string | 是 | 事件类型,固定为'status',表示对象上下线。 |
  | callback | Callback<{ sessionId: string, networkId: string, status: 'online' \| 'offline' }> | 是 | 监听上下线回调实例。<br>sessionId:标识变更对象的sessionId; <br>networkId:标识对象设备,即deviceId; <br>status:标识对象为'online'(上线)或'offline'(下线)的状态。 |

**示例:**

```js
import distributedObject from '@ohos.data.distributedDataObject';
L
LiRui 已提交
672 673
globalThis.statusCallback = (sessionId, networkId, status) => {
    globalThis.response += "status changed " + sessionId + " " + status + " " + networkId;
L
LiRui 已提交
674
}
L
LiRui 已提交
675 676
let g_object = distributedObject.createDistributedObject({name:"Amy", age:18, isVis:false, parent:{mother:"jack mom",father:"jack Dad"}});
g_object.on("status", globalThis.statusCallback);
677 678 679 680 681 682 683 684 685 686 687 688 689 690 691 692 693 694 695 696 697 698 699 700 701
```

### off('status')<sup>(deprecated)</sup>

off(type: 'status', callback?: Callback<{ sessionId: string, deviceId: string, status: 'online' | 'offline' }>): void

当不再进行对象上下线监听时,使用此接口删除对象的上下线监听。

> **说明:**
>
> 从 API Version 8 开始支持,从 API Version 9 开始废弃,建议使用[off('status')](#offstatus9)替代。

**系统能力:** SystemCapability.DistributedDataManager.DataObject.DistributedObject

**参数:**

  | 参数名 | 类型 | 必填 | 说明 |
  | -------- | -------- | -------- | -------- |
  | type | string | 是 | 事件类型,固定为'status',表示对象上下线。 |
  | callback | Callback<{ sessionId: string, deviceId: string, status: 'online' \| 'offline' }> | 否 | 需要删除的上下线回调,若不设置则删除该对象所有的上下线回调。<br>sessionId:标识变更对象的sessionId; <br>deviceId:标识变更对象的deviceId; <br>status:标识对象为'online'(上线)或'offline'(下线)的状态。 |


**示例:**

```js
W
wangxiyue 已提交
702
import distributedObject from '@ohos.data.distributedDataObject';
L
LiRui 已提交
703 704 705
let g_object = distributedObject.createDistributedObject({name:"Amy", age:18, isVis:false, parent:{mother:"jack mom",father:"jack Dad"}});
globalThis.statusCallback = (sessionId, networkId, status) => {
    globalThis.response += "status changed " + sessionId + " " + status + " " + networkId;
L
LiRui 已提交
706
}
707
// 删除上下线回调changeCallback
L
LiRui 已提交
708
g_object.off("status",globalThis.statusCallback);
709 710
// 删除所有的上下线回调
g_object.off("status");
L
LiRui 已提交
711
```