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 8 9 10 11 12
> 本模块首批接口从API version 8开始支持。后续版本的新增接口,采用上角标单独标记接口的起始版本。


## 导入模块

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

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

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

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

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

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

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

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

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

**示例:**
38

39 40
FA模型示例:

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

51 52 53 54 55
Stage模型示例:

```ts
// 导入模块
import distributedObject from '@ohos.data.distributedDataObject';
56 57
import UIAbility from '@ohos.app.ability.UIAbility';

W
wangxiyue 已提交
58 59
let g_object = null;

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

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

genSessionId(): string

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

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

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

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

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

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

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

save接口回调信息。

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

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

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

revokeSave接口回调信息。

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

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

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

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

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

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

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

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

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

**参数:**

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

**错误码:**

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

136
  | 错误码ID | 错误信息 |
137 138 139 140 141 142 143 144
  | -------- | -------- |
  | 15400001 | 创建内存数据库失败。|

**示例:**

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

### 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 已提交
167
  以下错误码的详细介绍参见[分布式数据对象错误码](../errorcodes/errorcode-distributed-dataObject.md)
168

169
  | 错误码ID | 错误信息 |
170 171 172 173 174 175 176 177
  | -------- | -------- |
  | 15400001 | 创建内存数据库失败。|

**示例:**

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

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

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

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

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

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

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

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

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

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

**错误码:**

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

212
  | 错误码ID | 错误信息 |
W
wuyongning 已提交
213
  | -------- | -------- |
214
  | 15400001 | 创建内存数据库失败。|
G
ge-yafang 已提交
215

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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


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

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

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

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

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

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

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

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

**示例:**
303

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

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

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

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

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

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

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


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

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

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

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

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

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

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

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

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

**参数:**
356

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

**示例:**
363

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

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

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

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

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

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

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

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

**参数:**
396

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

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

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

**示例:**

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

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

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

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

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

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

**参数:**
434

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

**示例:**

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

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

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

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

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

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

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

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

**示例:**

W
wangxiyue 已提交
486
```ts
W
wufengshan 已提交
487
g_object.setSessionId("123456");
W
wangxiyue 已提交
488 489
// 持久化数据
g_object.save("local").then((result) => {
W
wangxiyue 已提交
490
    console.info("save callback");
491 492 493
    console.info("save sessionId " + result.sessionId);
    console.info("save version " + result.version);
    console.info("save deviceId " + result.deviceId);
W
wangxiyue 已提交
494 495 496
}).catch((err) => {
    console.info("save failed, error code = " + err.code);
    console.info("save failed, error message: " + err.message);
497
});
W
wangxiyue 已提交
498 499
// 删除持久化保存的数据
g_object.revokeSave().then((result) => {
W
wangxiyue 已提交
500 501
    console.info("revokeSave callback");
    console.info("sessionId" + result.sessionId);
W
wangxiyue 已提交
502 503 504
}).catch((err)=> {
    console.info("revokeSave failed, error code = " + err.code);
    console.info("revokeSave failed, error message = " + err.message);
W
wangxiyue 已提交
505
});
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 538 539 540 541 542
```

## 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';
// 创建对象,对象包含4个属性类型,string,number,boolean和Object
let g_object = distributedObject.createDistributedObject({name:"Amy", age:18, isVis:false, parent:{mother:"jack mom",father:"jack Dad"}});
```

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

W
wangxiyue 已提交
543
表示一个分布式数据对象。在使用以下接口前,需调用[createDistributedObject()](#distributedobjectcreatedistributedobjectdeprecated)获取DistributedObject对象。
544 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 576 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

### 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';
let g_object = distributedObject.createDistributedObject({name:"Amy", age:18, isVis:false, parent:{mother:"jack mom",father:"jack Dad"}});;
// 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 已提交
604
import distributedObject from '@ohos.data.distributedDataObject';
605 606 607 608 609 610 611 612 613 614 615 616 617 618 619 620 621 622 623 624 625 626 627 628 629 630 631 632 633 634 635 636 637 638 639
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]);
        });
    }
}
g_object.on("change", globalThis.changeCallback);
```

### 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 已提交
640
import distributedObject from '@ohos.data.distributedDataObject';
641 642 643 644 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 672 673 674 675 676 677 678 679 680 681 682 683 684 685 686 687 688 689 690 691 692 693 694 695 696 697 698 699 700
let g_object = distributedObject.createDistributedObject({name:"Amy", age:18, isVis:false, parent:{mother:"jack mom",father:"jack Dad"}});
// 删除数据变更回调changeCallback
g_object.off("change", globalThis.changeCallback);
// 删除所有的数据变更回调
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';
globalThis.statusCallback = (sessionId, networkId, status) => {
    globalThis.response += "status changed " + sessionId + " " + status + " " + networkId;
}
let g_object = distributedObject.createDistributedObject({name:"Amy", age:18, isVis:false, parent:{mother:"jack mom",father:"jack Dad"}});
g_object.on("status", globalThis.statusCallback);
```

### 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 已提交
701
import distributedObject from '@ohos.data.distributedDataObject';
702 703 704 705 706 707 708 709
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;
}
// 删除上下线回调changeCallback
g_object.off("status",globalThis.statusCallback);
// 删除所有的上下线回调
g_object.off("status");
W
wangxiyue 已提交
710
```