1# @ohos.data.distributedDataObject (分布式数据对象) 2<!--Kit: ArkData--> 3<!--Subsystem: DistributedDataManager--> 4<!--Owner: @lvcong_oh--> 5<!--Designer: @hollokin; @yuchaozhng--> 6<!--Tester: @lj_liujing; @yippo; @logic42--> 7<!--Adviser: @ge-yafang--> 8 9本模块提供管理基本数据对象的相关能力，包括创建、查询、删除、修改、订阅等；同时支持相同应用多设备间的分布式数据对象协同能力。分布式数据对象处理数据时，不会解析用户数据的内容，存储路径安全性较低，不建议传输个人敏感数据和隐私数据。 10 11> **说明：** 12> 13> 本模块首批接口从API version 8开始支持。后续版本的新增接口，采用上角标单独标记接口的起始版本。 14 15 16## 导入模块 17 18```ts 19import { distributedDataObject } from '@kit.ArkData'; 20``` 21 22## distributedDataObject.create<sup>9+</sup> 23 24create(context: Context, source: object): DataObject 25 26创建一个分布式数据对象。对象属性支持基本类型（数字类型、布尔类型和字符串类型）以及复杂类型（数组、基本类型嵌套）。 27 28**系统能力：** SystemCapability.DistributedDataManager.DataObject.DistributedObject 29 30**参数：** 31 32 | 参数名 | 类型 | 必填 | 说明 | 33 | -------- | -------- | -------- | -------- | 34 | context | Context | 是 | 应用的上下文。 <br>FA模型的应用Context定义见[Context](../apis-ability-kit/js-apis-inner-app-context.md)。 <br>Stage模型的应用Context定义见[Context](../apis-ability-kit/js-apis-inner-application-uiAbilityContext.md)。 | 35 | source | object | 是 | 设置分布式数据对象的属性。 | 36 37**返回值：** 38 39| 类型 | 说明 | 40| -------- | -------- | 41| [DataObject](#dataobject) | 创建完成的分布式数据对象。 | 42 43**错误码：** 44 45 以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)。 46 47 | 错误码ID | 错误信息 | 48 | -------- | -------- | 49 | 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types. | 50 51**示例：** 52 53FA模型示例： 54<!--code_no_check_fa--> 55```ts 56// 导入模块 57import { featureAbility } from '@kit.AbilityKit'; 58import { BusinessError } from '@kit.BasicServicesKit'; 59// 获取context 60let context = featureAbility.getContext(); 61class SourceObject { 62 name: string 63 age: number 64 isVis: boolean 65 66 constructor(name: string, age: number, isVis: boolean) { 67 this.name = name; 68 this.age = age; 69 this.isVis = isVis; 70 } 71} 72 73let source: SourceObject = new SourceObject("jack", 18, false); 74let g_object: distributedDataObject.DataObject = distributedDataObject.create(context, source); 75``` 76 77Stage模型示例： 78 79```ts 80// 导入模块 81import { UIAbility } from '@kit.AbilityKit'; 82import { BusinessError } from '@kit.BasicServicesKit'; 83import { window } from '@kit.ArkUI'; 84 85let g_object: distributedDataObject.DataObject|null = null; 86class SourceObject { 87 name: string 88 age: number 89 isVis: boolean 90 91 constructor(name: string, age: number, isVis: boolean) { 92 this.name = name; 93 this.age = age; 94 this.isVis = isVis; 95 } 96} 97 98class EntryAbility extends UIAbility { 99 onWindowStageCreate(windowStage: window.WindowStage) { 100 let source: SourceObject = new SourceObject("jack", 18, false); 101 g_object = distributedDataObject.create(this.context, source); 102 } 103} 104``` 105 106## distributedDataObject.genSessionId 107 108genSessionId(): string 109 110随机创建一个sessionId。 111 112**系统能力：** SystemCapability.DistributedDataManager.DataObject.DistributedObject 113 114**返回值：** 115 116 | 类型 | 说明 | 117 | -------- | -------- | 118 | string | 随机创建的sessionId。 | 119 120**示例：** 121 122```ts 123let sessionId: string = distributedDataObject.genSessionId(); 124``` 125 126## SaveSuccessResponse<sup>9+</sup> 127 128[save](#save9)接口回调信息。 129 130**系统能力：** SystemCapability.DistributedDataManager.DataObject.DistributedObject 131 132| 名称 | 类型 | 必填 | 说明 | 133| -------- | -------- | -------- | -------- | 134| sessionId | string | 是 | 多设备协同的唯一标识。 | 135| version | number | 是 | 已保存对象的版本，取值为非负整数。 | 136| deviceId | string | 是 | 存储数据的设备号，标识需要保存对象的设备。"local"表示本地设备，否则表示其他设备的设备号。 | 137 138## RevokeSaveSuccessResponse<sup>9+</sup> 139 140[revokeSave](#revokesave9)接口回调信息。 141 142**系统能力：** SystemCapability.DistributedDataManager.DataObject.DistributedObject 143 144| 名称 | 类型 | 必填 | 说明 | 145| -------- | -------- | -------- | -------- | 146| sessionId | string | 是 | 多设备协同的唯一标识。 | 147 148## BindInfo<sup>11+</sup> 149 150数据库的绑定信息。当前版本只支持关系型数据库的绑定。 151 152**系统能力：** SystemCapability.DistributedDataManager.DataObject.DistributedObject 153 154 | 名称 | 类型 | 只读 | 可选 | 说明 | 155 | ---------- | ------------------------------------------------------------------ | ---- | ---- | ------------------------------------ | 156 | storeName | string | 否 | 否 | 待绑定资产在所属的数据库中的库名。 | 157 | tableName | string | 否 | 否 | 待绑定资产在所属的数据库中的表名。 | 158 | primaryKey | [commonType.ValuesBucket](js-apis-data-commonType.md#valuesbucket) | 否 | 否 | 待绑定资产在所属的数据库中的主键。 | 159 | field | string | 否 | 否 | 待绑定资产在所属的数据库中的列名。 | 160 | assetName | string | 否 | 否 | 待绑定资产在所属的数据库中的资产名。 | 161 162## DataObserver<sup>20+</sup> 163 164type DataObserver = (sessionId: string, fields: Array<string>) => void 165 166定义获取分布式对象数据变更的监听回调函数。 167 168**系统能力：** SystemCapability.DistributedDataManager.DataObject.DistributedObject 169 170**参数：** 171 172| 参数名 | 类型 | 必填 | 说明 | 173| -------- | ------------------------------------------------- | ---- | ------------------------------------------------------------ | 174| sessionId | string | 是 | 标识变更对象的sessionId。长度需小于128字节，且只能包含字母、数字或下划线_。 | 175| fields | Array<string> | 是 | 标识对象变更的属性名。属性名可自定义，要求字符串非空且长度不超过128字节。 | 176 177## StatusObserver<sup>20+</sup> 178 179type StatusObserver = (sessionId: string, networkId: string, status: string) => void 180 181定义获取分布式对象状态变更的监听回调函数。 182 183**系统能力：** SystemCapability.DistributedDataManager.DataObject.DistributedObject 184 185**参数：** 186 187| 参数名 | 类型 | 必填 | 说明 | 188| -------- | -------- | -------- | -------- | 189| sessionId | string | 是 | 标识变更对象的sessionId。长度不大于128字节，且只能包含字母、数字或下划线_。 | 190| networkId | string | 是 | 对端设备的网络标识。要求字符串非空且长度不超过255字节。 | 191| status | string | 是 | 标识分布式对象的状态，可能的取值有'online'（上线）、'offline'（下线）和'restore'（恢复）。 | 192 193## ProgressObserver<sup>20+</sup> 194 195type ProgressObserver = (sessionId: string, progress: number) => void 196 197定义传输进度的监听回调函数。 198 199**系统能力：** SystemCapability.DistributedDataManager.DataObject.DistributedObject 200 201**参数：** 202 203| 参数名 | 类型 | 必填 | 说明 | 204| -------- | -------- | -------- | -------- | 205| sessionId | string | 是 | 标识变更对象的sessionId。长度不大于128字节，且只能包含字母、数字或下划线_。 | 206| progress | number | 是 | 标识资产传输进度。取值范围为[-1, 100]，取值为整数，-1表示获取进度失败，100表示传输完成。 | 207 208## DataObject 209 210表示一个分布式数据对象。在使用以下接口前，需调用[create()](#distributeddataobjectcreate9)获取DataObject对象。 211 212### setSessionId<sup>9+</sup> 213 214setSessionId(sessionId: string, callback: AsyncCallback<void>): void 215 216设置sessionId，使用callback方式异步回调。当可信组网中有多个设备处于协同状态时，如果多个设备间的分布式对象设置为同一个sessionId，就能自动同步。 217 218**需要权限：** ohos.permission.DISTRIBUTED_DATASYNC 219 220**系统能力：** SystemCapability.DistributedDataManager.DataObject.DistributedObject 221 222**参数：** 223 224 | 参数名 | 类型 | 必填 | 说明 | 225 | --------- | ------------------------- | ---- | -------------------------------------------------------------------------------------------------------------- | 226 | sessionId | string | 是 | 分布式数据对象在可信组网中的标识ID，长度不大于128，且只能包含字母数字或下划线_。当传入""、null时表示退出分布式组网。 | 227 | callback | AsyncCallback<void> | 是 | 加入session的异步回调。 | 228 229**错误码：** 230 231 以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和[分布式数据对象错误码](errorcode-distributed-dataObject.md)。 232 233 | 错误码ID | 错误信息 | 234 | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------ | 235 | 201 | Permission verification failed. | 236 | 401 | Parameter error. Possible causes: 1. Incorrect parameter types; 2. The sessionId allows only letters, digits, and underscores(_), and cannot exceed 128 in length. | 237 | 15400001 | Failed to create the in-memory database. | 238 239**示例：** 240 241```ts 242// g_object加入分布式组网 243g_object.setSessionId(distributedDataObject.genSessionId(), ()=>{ 244 console.info("join session"); 245}); 246// g_object退出分布式组网 247g_object.setSessionId("", ()=>{ 248 console.info("leave all session"); 249}); 250``` 251 252### setSessionId<sup>9+</sup> 253 254setSessionId(callback: AsyncCallback<void>): void 255 256退出所有已加入的session，使用callback方式异步回调。 257 258**系统能力：** SystemCapability.DistributedDataManager.DataObject.DistributedObject 259 260**参数：** 261 262 | 参数名 | 类型 | 必填 | 说明 | 263 | -------- | -------- | -------- | -------- | 264 | callback | AsyncCallback<void> | 是 | 退出所有已加入session的异步回调。 | 265 266**错误码：** 267 268 以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和[分布式数据对象错误码](errorcode-distributed-dataObject.md)。 269 270 | 错误码ID | 错误信息 | 271 | -------- | -------- | 272 | 401 | Parameter error. Incorrect parameter types. | 273 | 15400001 | Failed to create the in-memory database. | 274 275**示例：** 276 277```ts 278// g_object加入分布式组网 279g_object.setSessionId(distributedDataObject.genSessionId(), ()=>{ 280 console.info("join session"); 281}); 282// 退出分布式组网 283g_object.setSessionId(() => { 284 console.info("leave all session."); 285}); 286``` 287 288### setSessionId<sup>9+</sup> 289 290setSessionId(sessionId?: string): Promise<void> 291 292设置sessionId或退出分布式组网，使用Promise异步回调。当传入""、null或不传入参数时，表示退出分布式组网。当可信组网中有多个设备处于协同状态时，如果多个设备间的分布式对象设置为同一个sessionId，就能自动同步。 293 294**需要权限：** ohos.permission.DISTRIBUTED_DATASYNC 295 296**系统能力：** SystemCapability.DistributedDataManager.DataObject.DistributedObject 297 298**参数：** 299 300 | 参数名 | 类型 | 必填 | 说明 | 301 | --------- | ------ | ---- | ---------------------------------------------------------------------------------------------------------------------------- | 302 | sessionId | string | 否 | 分布式数据对象在可信组网中的标识ID，长度不大于128，且只能包含字母数字或下划线_。当传入""、null或不传入参数时表示退出分布式组网。 | 303 304**返回值：** 305 306| 类型 | 说明 | 307| -------- | -------- | 308| Promise<void> | Promise对象。| 309 310**错误码：** 311 312 以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和[分布式数据对象错误码](errorcode-distributed-dataObject.md)。 313 314 | 错误码ID | 错误信息 | 315 | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------ | 316 | 201 | Permission verification failed. | 317 | 401 | Parameter error. Possible causes: 1. Incorrect parameter types; 2. The sessionId allows only letters, digits, and underscores(_), and cannot exceed 128 in length. | 318 | 15400001 | Failed to create the in-memory database. | 319 320**示例：** 321 322```ts 323// g_object加入分布式组网 324g_object.setSessionId(distributedDataObject.genSessionId()).then (()=>{ 325 console.info("join session."); 326 }).catch((error: BusinessError)=>{ 327 console.error("error:" + error.code + error.message); 328}); 329// 退出分布式组网 330g_object.setSessionId().then (()=>{ 331 console.info("leave all session."); 332 }).catch((error: BusinessError)=>{ 333 console.error("error:" + error.code + error.message); 334}); 335``` 336 337### on('change')<sup>9+</sup> 338 339on(type: 'change', callback: (sessionId: string, fields: Array<string>) => void): void 340 341监听分布式数据对象的数据变更。 342 343**系统能力：** SystemCapability.DistributedDataManager.DataObject.DistributedObject 344 345**参数：** 346 347| 参数名 | 类型 | 必填 | 说明 | 348| -------- | -------- | -------- | -------- | 349| type | string | 是 | 事件类型，固定为'change'，表示数据变更。 | 350| callback | (sessionId: string, fields: Array<string>) => void | 是 | 变更回调对象实例。<br>sessionId：标识变更对象的sessionId； <br>fields：标识对象变更的属性名。 | 351 352**错误码：** 353 354 以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)。 355 356 | 错误码ID | 错误信息 | 357 | -------- | -------- | 358 | 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types. | 359 360**示例：** 361 362```ts 363g_object.on("change", (sessionId: string, fields: Array<string>) => { 364 console.info("change" + sessionId); 365 if (g_object != null && fields != null && fields != undefined) { 366 for (let index: number = 0; index < fields.length; index++) { 367 console.info("changed !" + fields[index] + " " + g_object[fields[index]]); 368 } 369 } 370}); 371``` 372 373### off('change')<sup>9+</sup> 374 375off(type: 'change', callback?: (sessionId: string, fields: Array<string>) => void): void 376 377当不再进行数据变更监听时，使用此接口删除对象的变更监听。 378 379**系统能力：** SystemCapability.DistributedDataManager.DataObject.DistributedObject 380 381**参数：** 382 383| 参数名 | 类型 | 必填 | 说明 | 384| -------- | -------- | -------- | -------- | 385| type | string | 是 | 事件类型，固定为'change'，表示数据变更。 | 386| callback | (sessionId: string, fields: Array<string>) => void | 否 | 需要删除的数据变更回调，若不设置则删除该对象所有的数据变更回调。<br>sessionId：标识变更对象的sessionId； <br>fields：标识对象变更的属性名。 | 387 388**错误码：** 389 390 以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)。 391 392 | 错误码ID | 错误信息 | 393 | -------- | -------- | 394 | 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types. | 395 396**示例：** 397 398```ts 399// 删除数据变更回调changeCallback 400g_object.off("change", (sessionId: string, fields: Array<string>) => { 401 console.info("change" + sessionId); 402 if (g_object != null && fields != null && fields != undefined) { 403 for (let index: number = 0; index < fields.length; index++) { 404 console.info("changed !" + fields[index] + " " + g_object[fields[index]]); 405 } 406 } 407}); 408// 删除所有的数据变更回调 409g_object.off("change"); 410``` 411 412### on('status')<sup>9+</sup> 413 414on(type: 'status', callback: (sessionId: string, networkId: string, status: 'online' \| 'offline' ) => void): void 415 416监听分布式数据对象的上下线。 417 418**系统能力：** SystemCapability.DistributedDataManager.DataObject.DistributedObject 419 420**参数：** 421 422| 参数名 | 类型 | 必填 | 说明 | 423| -------- | -------- | -------- | -------- | 424| type | string | 是 | 事件类型，固定为'status'，表示对象上下线。 | 425| callback | (sessionId: string, networkId: string, status: 'online' \| 'offline' ) => void | 是 | 监听上下线回调实例。<br>sessionId：标识变更对象的sessionId； <br>networkId：标识对象设备； <br>status：标识对象为'online'(上线)或'offline'(下线)的状态。 | 426 427**错误码：** 428 429 以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)。 430 431 | 错误码ID | 错误信息 | 432 | -------- | -------- | 433 | 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types. | 434 435**示例：** 436 437```ts 438g_object.on("status", (sessionId: string, networkId: string, status: 'online' | 'offline') => { 439 console.info("status changed " + sessionId + " " + status + " " + networkId); 440}); 441``` 442 443### off('status')<sup>9+</sup> 444 445off(type: 'status', callback?:(sessionId: string, networkId: string, status: 'online' \| 'offline') => void): void 446 447当不再进行对象上下线监听时，使用此接口删除对象的上下线监听。 448 449**系统能力：** SystemCapability.DistributedDataManager.DataObject.DistributedObject 450 451**参数：** 452 453| 参数名 | 类型 | 必填 | 说明 | 454| -------- | -------- | -------- | -------- | 455| type | string | 是 | 事件类型，固定为'status'，表示对象上下线。 | 456| callback | (sessionId: string, networkId: string, status: 'online' \| 'offline' ) => void | 否 | 需要删除的上下线回调，若不设置则删除该对象所有的上下线回调。<br>sessionId：标识变更对象的sessionId； <br>networkId：标识变更对象； <br>status：标识对象为'online'(上线)或'offline'(下线)的状态。 | 457 458**错误码：** 459 460 以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)。 461 462 | 错误码ID | 错误信息 | 463 | -------- | -------- | 464 | 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types. | 465 466**示例：** 467 468```ts 469// 删除上下线回调changeCallback 470g_object.off("status", (sessionId: string, networkId: string, status: 'online' | 'offline') => { 471 console.info("status changed " + sessionId + " " + status + " " + networkId); 472}); 473// 删除所有的上下线回调 474g_object.off("status"); 475``` 476 477### save<sup>9+</sup> 478 479save(deviceId: string, callback: AsyncCallback<SaveSuccessResponse>): void 480 481保存分布式数据对象。使用callback方式异步回调。 482 483对象数据保存成功后，当应用存在时不会释放对象数据，当应用退出后，重新进入应用时，恢复保存在设备上的数据。 484 485有以下几种情况时，保存的数据将会被释放： 486 487- 存储时间超过24小时。 488- 应用卸载。 489- 成功恢复数据之后。 490 491**系统能力：** SystemCapability.DistributedDataManager.DataObject.DistributedObject 492 493**参数：** 494 495 | 参数名 | 类型 | 必填 | 说明 | 496 | -------- | -------- | -------- | -------- | 497 | deviceId | string | 是 | 保存数据的deviceId，当deviceId为"local"，代表存储在本地设备。 | 498 | callback | AsyncCallback<[SaveSuccessResponse](#savesuccessresponse9)> | 是 | 回调函数。返回SaveSuccessResponse，包含sessionId、version、deviceId等信息。 | 499 500**错误码：** 501 502 以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)。 503 504 | 错误码ID | 错误信息 | 505 | -------- | -------- | 506 | 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types. | 507 | 801 | Capability not supported. | 508 509**示例：** 510 511```ts 512g_object.setSessionId("123456"); 513g_object.save("local", (err: BusinessError, result:distributedDataObject.SaveSuccessResponse) => { 514 if (err) { 515 console.error("save failed, error code = " + err.code); 516 console.error("save failed, error message: " + err.message); 517 return; 518 } 519 console.info("save callback"); 520 console.info("save sessionId: " + result.sessionId); 521 console.info("save version: " + result.version); 522 console.info("save deviceId: " + result.deviceId); 523}); 524``` 525 526### save<sup>9+</sup> 527 528save(deviceId: string): Promise<SaveSuccessResponse> 529 530保存分布式数据对象。使用Promise方式作为异步回调。 531 532对象数据保存成功后，当应用存在时不会释放对象数据，当应用退出后，重新进入应用时，恢复保存在设备上的数据。 533 534有以下几种情况时，保存的数据将会被释放： 535 536- 存储时间超过24小时。 537- 应用卸载。 538- 成功恢复数据之后。 539 540**系统能力：** SystemCapability.DistributedDataManager.DataObject.DistributedObject 541 542**参数：** 543 544 | 参数名 | 类型 | 必填 | 说明 | 545 | -------- | -------- | -------- | -------- | 546 | deviceId | string | 是 | 保存数据的设备号，当deviceId默认为"local"，标识需要保存对象的设备。 | 547 548**返回值：** 549 550 | 类型 | 说明 | 551 | -------- | -------- | 552 | Promise<[SaveSuccessResponse](#savesuccessresponse9)> | Promise对象。返回SaveSuccessResponse，包含sessionId、version、deviceId等信息。| 553 554**错误码：** 555 556 以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)。 557 558 | 错误码ID | 错误信息 | 559 | -------- | -------- | 560 | 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types. | 561 | 801 | Capability not supported. | 562 563**示例：** 564 565```ts 566g_object.setSessionId("123456"); 567g_object.save("local").then((callbackInfo: distributedDataObject.SaveSuccessResponse) => { 568 console.info("save callback"); 569 console.info("save sessionId " + callbackInfo.sessionId); 570 console.info("save version " + callbackInfo.version); 571 console.info("save deviceId " + callbackInfo.deviceId); 572}).catch((err: BusinessError) => { 573 console.error("save failed, error code = " + err.code); 574 console.error("save failed, error message: " + err.message); 575}); 576``` 577 578### revokeSave<sup>9+</sup> 579 580revokeSave(callback: AsyncCallback<RevokeSaveSuccessResponse>): void 581 582撤回保存的分布式数据对象。使用callback方式作为异步方法。 583 584如果对象保存在本地设备，那么将删除所有受信任设备上所保存的数据。 585如果对象保存在其他设备，那么将删除本地设备上的数据。 586 587**系统能力：** SystemCapability.DistributedDataManager.DataObject.DistributedObject 588 589**参数：** 590 591 | 参数名 | 类型 | 必填 | 说明 | 592 | -------- | -------- | -------- | -------- | 593 | callback | AsyncCallback<[RevokeSaveSuccessResponse](#revokesavesuccessresponse9)> | 是 | 回调函数。返回RevokeSaveSuccessResponse，包含sessionId。 | 594 595**错误码：** 596 597 以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)。 598 599 | 错误码ID | 错误信息 | 600 | -------- | -------- | 601 | 401 | Parameter error. Incorrect parameter types. | 602 | 801 | Capability not supported. | 603 604**示例：** 605 606```ts 607g_object.setSessionId("123456"); 608// 持久化数据 609g_object.save("local", (err: BusinessError, result: distributedDataObject.SaveSuccessResponse) => { 610 if (err) { 611 console.error("save failed, error code = " + err.code); 612 console.error("save failed, error message: " + err.message); 613 return; 614 } 615 console.info("save callback"); 616 console.info("save sessionId: " + result.sessionId); 617 console.info("save version: " + result.version); 618 console.info("save deviceId: " + result.deviceId); 619}); 620// 删除持久化保存的数据 621g_object.revokeSave((err: BusinessError, result: distributedDataObject.RevokeSaveSuccessResponse) => { 622 if (err) { 623 console.error("revokeSave failed, error code = " + err.code); 624 console.error("revokeSave failed, error message: " + err.message); 625 return; 626 } 627 console.info("revokeSave callback"); 628 console.info("revokeSave sessionId " + result.sessionId); 629}); 630``` 631 632### revokeSave<sup>9+</sup> 633 634revokeSave(): Promise<RevokeSaveSuccessResponse> 635 636撤回保存的分布式数据对象。使用Promise方式作为异步方法。 637 638如果对象保存在本地设备，那么将删除所有受信任设备上所保存的数据。 639如果对象保存在其他设备，那么将删除本地设备上的数据。 640 641**系统能力：** SystemCapability.DistributedDataManager.DataObject.DistributedObject 642 643**返回值：** 644 645 | 类型 | 说明 | 646 | -------- | -------- | 647 | Promise<[RevokeSaveSuccessResponse](#revokesavesuccessresponse9)> | Promise对象。返回RevokeSaveSuccessResponse，包含sessionId。 | 648 649**错误码：** 650 651 以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)。 652 653 | 错误码ID | 错误信息 | 654 | -------- | -------- | 655 | 801 | Capability not supported. | 656 657**示例：** 658 659```ts 660g_object.setSessionId("123456"); 661// 持久化数据 662g_object.save("local").then((result: distributedDataObject.SaveSuccessResponse) => { 663 console.info("save callback"); 664 console.info("save sessionId " + result.sessionId); 665 console.info("save version " + result.version); 666 console.info("save deviceId " + result.deviceId); 667}).catch((err: BusinessError) => { 668 console.error("save failed, error code = " + err.code); 669 console.error("save failed, error message: " + err.message); 670}); 671// 删除持久化保存的数据 672g_object.revokeSave().then((result: distributedDataObject.RevokeSaveSuccessResponse) => { 673 console.info("revokeSave callback"); 674 console.info("sessionId" + result.sessionId); 675}).catch((err: BusinessError)=> { 676 console.error("revokeSave failed, error code = " + err.code); 677 console.error("revokeSave failed, error message = " + err.message); 678}); 679``` 680 681### bindAssetStore<sup>11+</sup> 682 683bindAssetStore(assetKey: string, bindInfo: BindInfo, callback: AsyncCallback<void>): void 684 685绑定分布式对象中的单个资产与其对应的数据库信息，当前版本只支持分布式对象中的资产与关系型数据库的绑定。使用callback方式异步回调。 686 687当分布式对象中包含的资产和关系型数据库中包含的资产指向同一个实体资产文件，即两个资产的Uri相同时，就会存在冲突，我们把这种资产称为融合资产。如果需要分布式数据管理进行融合资产的冲突解决，需要先进行资产的绑定。当应用退出session后，绑定关系随之消失。 688 689**系统能力：** SystemCapability.DistributedDataManager.DataObject.DistributedObject 690 691**参数：** 692 693 | 参数名 | 类型 | 必填 | 说明 | 694 | -------- | ------------------------- | ---- | ---------------------------------------------------------------------------------- | 695 | assetKey | string | 是 | 待绑定的融合资产在分布式对象中的键值。 | 696 | bindInfo | [BindInfo](#bindinfo11) | 是 | 待绑定的融合资产在数据库中的信息，包含库名、表名、主键、列名及在数据库中的资产名。 | 697 | callback | AsyncCallback<void> | 是 | 绑定数据库的回调。 | 698 699**错误码：** 700 701 以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)。 702 703 | 错误码ID | 错误信息 | 704 | -------- | -------- | 705 | 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types. | 706 | 801 | Capability not supported. | 707 708**示例：** 709 710```ts 711import { UIAbility } from '@kit.AbilityKit'; 712import { window } from '@kit.ArkUI'; 713import { commonType } from '@kit.ArkData'; 714import { BusinessError } from '@kit.BasicServicesKit'; 715 716class Note { 717 title: string | undefined 718 text: string | undefined 719 attachment: commonType.Asset | undefined 720 721 constructor(title: string | undefined, text: string | undefined, attachment: commonType.Asset | undefined) { 722 this.title = title; 723 this.text = text; 724 this.attachment = attachment; 725 } 726} 727 728class EntryAbility extends UIAbility { 729 onWindowStageCreate(windowStage: window.WindowStage) { 730 let attachment: commonType.Asset = { 731 name: 'test_img.jpg', 732 uri: 'file://com.example.myapplication/data/storage/el2/distributedfiles/dir/test_img.jpg', 733 path: '/dir/test_img.jpg', 734 createTime: '2024-01-02 10:00:00', 735 modifyTime: '2024-01-02 10:00:00', 736 size: '5', 737 status: commonType.AssetStatus.ASSET_NORMAL 738 } 739 let note: Note = new Note('test', 'test', attachment); 740 let g_object: distributedDataObject.DataObject = distributedDataObject.create(this.context, note); 741 g_object.setSessionId('123456'); 742 743 const bindInfo: distributedDataObject.BindInfo = { 744 storeName: 'notepad', 745 tableName: 'note_t', 746 primaryKey: { 747 'uuid': '00000000-0000-0000-0000-000000000000' 748 }, 749 field: 'attachment', 750 assetName: attachment.name as string 751 } 752 753 g_object.bindAssetStore('attachment', bindInfo, (err: BusinessError) => { 754 if (err) { 755 console.error('bindAssetStore failed.'); 756 } 757 console.info('bindAssetStore success.'); 758 }); 759 } 760} 761``` 762 763### bindAssetStore<sup>11+</sup> 764 765bindAssetStore(assetKey: string, bindInfo: BindInfo): Promise<void> 766 767绑定分布式对象中的单个资产与其对应的数据库信息，当前版本只支持分布式对象中的资产与关系型数据库的绑定。使用Promise方式作为异步回调。 768 769当分布式对象中包含的资产和关系型数据库中包含的资产指向同一个实体资产文件，即两个资产的Uri相同时，就会存在冲突，我们把这种资产称为融合资产。如果需要分布式数据管理进行融合资产的冲突解决，需要先进行资产的绑定。当应用退出session后，绑定关系随之消失。 770 771**系统能力：** SystemCapability.DistributedDataManager.DataObject.DistributedObject 772 773**参数：** 774 775 | 参数名 | 类型 | 必填 | 说明 | 776 | -------- | ----------------------- | ---- | ---------------------------------------------------------------------------------- | 777 | assetKey | string | 是 | 待绑定的融合资产在分布式对象中的键值。 | 778 | bindInfo | [BindInfo](#bindinfo11) | 是 | 待绑定的融合资产在数据库中的信息，包含库名、表名、主键、列名及在数据库中的资产名。 | 779 780**返回值：** 781 782 | 类型 | 说明 | 783 | ------------------- | ------------- | 784 | Promise<void> | 无返回结果的Promise对象。 | 785 786**错误码：** 787 788 以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)。 789 790 | 错误码ID | 错误信息 | 791 | -------- | -------- | 792 | 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types. | 793 | 801 | Capability not supported. | 794 795**示例：** 796 797```ts 798import { UIAbility } from '@kit.AbilityKit'; 799import { window } from '@kit.ArkUI'; 800import { commonType } from '@kit.ArkData'; 801import { BusinessError } from '@kit.BasicServicesKit'; 802 803class Note { 804 title: string | undefined 805 text: string | undefined 806 attachment: commonType.Asset | undefined 807 808 constructor(title: string | undefined, text: string | undefined, attachment: commonType.Asset | undefined) { 809 this.title = title; 810 this.text = text; 811 this.attachment = attachment; 812 } 813} 814 815class EntryAbility extends UIAbility { 816 onWindowStageCreate(windowStage: window.WindowStage) { 817 let attachment: commonType.Asset = { 818 name: 'test_img.jpg', 819 uri: 'file://com.example.myapplication/data/storage/el2/distributedfiles/dir/test_img.jpg', 820 path: '/dir/test_img.jpg', 821 createTime: '2024-01-02 10:00:00', 822 modifyTime: '2024-01-02 10:00:00', 823 size: '5', 824 status: commonType.AssetStatus.ASSET_NORMAL 825 } 826 let note: Note = new Note('test', 'test', attachment); 827 let g_object: distributedDataObject.DataObject = distributedDataObject.create(this.context, note); 828 g_object.setSessionId('123456'); 829 830 const bindInfo: distributedDataObject.BindInfo = { 831 storeName: 'notepad', 832 tableName: 'note_t', 833 primaryKey: { 834 'uuid': '00000000-0000-0000-0000-000000000000' 835 }, 836 field: 'attachment', 837 assetName: attachment.name as string 838 } 839 840 g_object.bindAssetStore("attachment", bindInfo).then(() => { 841 console.info('bindAssetStore success.'); 842 }).catch((err: BusinessError) => { 843 console.error("bindAssetStore failed, error code = " + err.code); 844 }); 845 } 846} 847``` 848 849### on('change')<sup>20+</sup> 850 851on(type: 'change', callback: DataObserver): void 852 853监听分布式对象的数据变更。 854 855**系统能力：** SystemCapability.DistributedDataManager.DataObject.DistributedObject 856 857**参数：** 858 859| 参数名 | 类型 | 必填 | 说明 | 860| -------- | -------- | -------- | -------- | 861| type | string | 是 | 事件类型，固定为'change'，表示数据变更。 | 862| callback | [DataObserver](#dataobserver20) | 是 | 表示分布式对象数据变更的回调实例。 | 863 864**示例：** 865 866```ts 867const changeCallback1: distributedDataObject.DataObserver = (sessionId: string, fields: Array<string>) => { 868 console.info("change callback1 " + sessionId); 869 if (fields != null && fields != undefined) { 870 for (let index: number = 0; index < fields.length; index++) { 871 console.info("change !" + fields[index]); 872 } 873 } 874} 875try { 876 g_object.on("change", changeCallback1); 877} catch (error) { 878 console.error("Execute failed, error code = " + error.code); 879} 880``` 881 882### off('change')<sup>20+</sup> 883 884off(type: 'change', callback?: DataObserver): void 885 886当不再进行数据变更监听时，使用此接口删除分布式对象数据变更监听的回调实例。 887 888**系统能力：** SystemCapability.DistributedDataManager.DataObject.DistributedObject 889 890**参数：** 891 892| 参数名 | 类型 | 必填 | 说明 | 893| -------- | -------- | -------- | -------- | 894| type | string | 是 | 事件类型，固定为'change'，表示数据变更。 | 895| callback | [DataObserver](#dataobserver20) | 否 | 需要删除的数据变更回调实例，若不设置则删除该对象所有的数据变更回调实例。 | 896 897**示例：** 898 899```ts 900const changeCallback1: distributedDataObject.DataObserver = (sessionId: string, fields: Array<string>) => { 901 console.info("change callback1 " + sessionId); 902 if (fields != null && fields != undefined) { 903 for (let index: number = 0; index < fields.length; index++) { 904 console.info("change !" + fields[index]); 905 } 906 } 907} 908 909const changeCallback2: distributedDataObject.DataObserver = (sessionId: string, fields: Array<string>) => { 910 console.info("change callback2 " + sessionId); 911 if (fields != null && fields != undefined) { 912 for (let index: number = 0; index < fields.length; index++) { 913 console.info("change !" + fields[index]); 914 } 915 } 916} 917 918try { 919 // 删除单个数据变更回调函数 920 g_object.on("change", changeCallback1); 921 g_object.off("change", changeCallback1); 922 923 // 删除所有数据变更回调函数 924 g_object.on("change", changeCallback1); 925 g_object.on("change", changeCallback2); 926 g_object.off("change"); 927} catch (error) { 928 console.error("Execute failed, error code = " + error.code); 929} 930``` 931 932### on('status')<sup>20+</sup> 933 934on(type: 'status', callback: StatusObserver): void 935 936监听分布式对象的状态变更。 937 938**系统能力：** SystemCapability.DistributedDataManager.DataObject.DistributedObject 939 940**参数：** 941 942| 参数名 | 类型 | 必填 | 说明 | 943| -------- | -------- | -------- | -------- | 944| type | string | 是 | 事件类型，固定为'status'，表示分布式对象状态变更事件。 | 945| callback | [StatusObserver](#statusobserver20) | 是 | 表示分布式对象状态变更的回调实例。 | 946 947**示例：** 948 949```ts 950const statusCallback1: distributedDataObject.StatusObserver = (sessionId: string, networkId: string, status: string) => { 951 console.info("status callback " + sessionId); 952} 953try { 954 g_object.on("status", statusCallback1); 955} catch (error) { 956 console.error("Execute failed, error code = " + error.code); 957} 958``` 959 960### off('status')<sup>20+</sup> 961 962off(type: 'status', callback?: StatusObserver): void 963 964当不再进行分布式对象状态变更监听时，使用此接口删除分布式对象状态变更的回调实例。 965 966**系统能力：** SystemCapability.DistributedDataManager.DataObject.DistributedObject 967 968**参数：** 969 970| 参数名 | 类型 | 必填 | 说明 | 971| -------- | -------- | -------- | -------- | 972| type | string | 是 | 事件类型，固定为'status'，表示数据对象状态变更事件。 | 973| callback | [StatusObserver](#statusobserver20) | 否 | 需要删除状态变更的回调实例，若不设置则删除该对象所有的状态变更回调实例。 | 974 975**示例：** 976 977```ts 978const statusCallback1: distributedDataObject.StatusObserver = (sessionId: string, networkId: string, status: string) => { 979 console.info("status callback1" + sessionId); 980} 981 982const statusCallback2: distributedDataObject.StatusObserver = (sessionId: string, networkId: string, status: string) => { 983 console.info("status callback2" + sessionId); 984} 985try { 986 // 删除单个状态变更回调函数 987 g_object.on("status", statusCallback1); 988 g_object.off("status", statusCallback1); 989 990 // 删除所有状态变更回调函数 991 g_object.on("status", statusCallback1); 992 g_object.on("status", statusCallback2); 993 g_object.off("status"); 994} catch (error) { 995 console.error("Execute failed, error code = " + error.code); 996} 997``` 998 999### on('progressChanged')<sup>20+</sup> 1000 1001on(type: 'progressChanged', callback: ProgressObserver): void 1002 1003监听资产传输进度。 1004 1005**系统能力：** SystemCapability.DistributedDataManager.DataObject.DistributedObject 1006 1007**参数：** 1008 1009| 参数名 | 类型 | 必填 | 说明 | 1010| -------- | -------- | -------- | -------- | 1011| type | string | 是 | 事件类型，固定为'progressChanged'，表示资产传输进度变化事件。 | 1012| callback | [ProgressObserver](#progressobserver20) | 是 | 表示资产传输进度变化的回调实例。 | 1013 1014**示例：** 1015 1016```ts 1017const progressChangedCallback: distributedDataObject.ProgressObserver = (sessionId: string, progress: number) => { 1018 console.info("progressChanged callback" + sessionId); 1019 console.info("progressChanged callback" + progress); 1020} 1021try { 1022 g_object.on("progressChanged", progressChangedCallback); 1023} catch (error) { 1024 console.error("Execute failed, error code = " + error.code); 1025} 1026``` 1027 1028### off('progressChanged')<sup>20+</sup> 1029 1030off(type: 'progressChanged', callback?: ProgressObserver): void 1031 1032当不再进行资产传输进度监听时，使用此接口取消监听。 1033 1034**系统能力：** SystemCapability.DistributedDataManager.DataObject.DistributedObject 1035 1036**参数：** 1037 1038| 参数名 | 类型 | 必填 | 说明 | 1039| -------- | -------- | -------- | -------- | 1040| type | string | 是 | 事件类型，固定为'progressChanged'，表示资产传输进度变化事件。 | 1041| callback | [ProgressObserver](#progressobserver20) | 否 | 需要取消监听的事件回调，若不设置，则取消对该事件的所有监听。 | 1042 1043**示例：** 1044 1045```ts 1046const progressChangedCallback1: distributedDataObject.ProgressObserver = (sessionId: string, progress: number) => { 1047 console.info("progressChanged callback1" + sessionId); 1048 console.info("progressChanged callback1" + progress); 1049} 1050 1051const progressChangedCallback2: distributedDataObject.ProgressObserver = (sessionId: string, progress: number) => { 1052 console.info("progressChanged callback2" + sessionId); 1053 console.info("progressChanged callback2" + progress); 1054} 1055try { 1056 g_object.on("progressChanged", progressChangedCallback1); 1057 // 取消对资产传输进度的监听 1058 g_object.off("progressChanged", progressChangedCallback1); 1059 1060 g_object.on("progressChanged", progressChangedCallback1); 1061 g_object.on("progressChanged", progressChangedCallback2); 1062 //取消对资产传输进度的所有监听 1063 g_object.off("progressChanged"); 1064} catch (error) { 1065 console.error("Execute failed, error code = " + error.code); 1066} 1067``` 1068### setAsset<sup>20+</sup> 1069 1070setAsset(assetKey: string, uri: string): Promise<void> 1071 1072设置分布式对象中的单个资产的属性信息，该接口必须在[setSessionId](#setsessionid9-2)接口调用前使用。使用Promise异步回调。 1073 1074> **注意：** 1075> 1076> 在设置资产时必须保证assetKey存在且对应文件为资产类型文件，否则无法保证对端能接收到此次设置的资产。 1077> 1078> 在设置资产时必须保证uri为正确且真实存在的分布式路径，否则无法保证对端能接收到此次设置的资产。 1079 1080有以下几种异常场景: 1081 1082 | 触发条件 | 操作结果 | 1083 | -------- | -------- | 1084 | 调用[setSessionId](#setsessionid9-2)接口设置sessionId后再调用[setAsset](#setasset20)接口设置资产。 | 设置资产失败，抛出15400003异常。 | 1085 | assetKey为无效值，例如：null（不存在）、undefined（未定义）或''（空字符串）。 | 设置资产失败，抛出15400002异常。 | 1086 | assetKey存在、对应文件为非资产类型。 | 系统会强制修改该字段对应的文件类型为资产类型且设置资产字段，可能出现真实资产无法同步至对端设备。 | 1087 | uri为无效值，例如：null（不存在）、undefined（未定义）或''（空字符串）。 | 设置资产失败，抛出15400002异常。 | 1088 1089 1090**系统能力：** SystemCapability.DistributedDataManager.DataObject.DistributedObject 1091 1092**参数：** 1093 1094 | 参数名 | 类型 | 必填 | 说明 | 1095 | -------- | ----------------------- | ---- | ---------------------------------------------------------------------------------- | 1096 | assetKey | string | 是 | 分布式对象中资产类型数据对应的属性名。<br/>**使用约束：** <br/>（1）提供的assetKey对应的文件必须已存在且类型为资产[Asset](js-apis-data-commonType.md#asset)，才可进行正确的设置资产。若assetKey对应文件不存在或文件存在但类型不是资产类型，可能会出现资产设置错误。<br/>（2）在协同或接续场景下需要双端满足assetKey对应的文件存在且为资产类型，才可将设置的资产同步到对端设备。 | 1097 | uri | string | 是 | 待设置的新资产的uri，表示该资产的存放的分布式路径。必须为真实存在的资产对应的分布式路径。 | 1098 1099**返回值：** 1100 1101 | 类型 | 说明 | 1102 | ------------------- | ------------- | 1103 | Promise<void> | 无返回结果的Promise对象。 | 1104 1105**错误码：** 1106 1107 以下错误码的详细介绍请参见[分布式数据对象错误码](errorcode-distributed-dataObject.md)。 1108 1109 | 错误码ID | 错误信息 | 1110 | -------- | -------- | 1111 | 15400002 | Parameter error. Possible causes: 1. The assetKey is invalid, such as ""; 2. The uri is invalid, such as "". | 1112 | 15400003 | The sessionId of the distributed object has been set. | 1113 1114**示例:** 1115 1116```ts 1117import { UIAbility } from '@kit.AbilityKit'; 1118import { window } from '@kit.ArkUI'; 1119import { BusinessError } from '@kit.BasicServicesKit'; 1120import { commonType, distributedDataObject } from '@kit.ArkData'; 1121 1122class Note { 1123 title: string | undefined 1124 text: string | undefined 1125 attachment: commonType.Asset | undefined 1126 1127 constructor(title: string | undefined, text: string | undefined, attachment: commonType.Asset | undefined) { 1128 this.title = title; 1129 this.text = text; 1130 this.attachment = attachment; 1131 } 1132} 1133 1134class EntryAbility extends UIAbility { 1135 onWindowStageCreate(windowStage: window.WindowStage) { 1136 let attachment: commonType.Asset = { 1137 name: 'test_img.jpg', 1138 uri: 'file://com.example.myapplication/data/storage/el2/distributedfiles/dir/test_img.jpg', 1139 path: '/dir/test_img.jpg', 1140 createTime: '2024-01-02 10:00:00', 1141 modifyTime: '2024-01-02 10:00:00', 1142 size: '5', 1143 status: commonType.AssetStatus.ASSET_NORMAL 1144 } 1145 let note: Note = new Note('test', 'test', attachment); 1146 let g_object: distributedDataObject.DataObject = distributedDataObject.create(this.context, note); 1147 1148 let uri = "file://test/test.img"; 1149 g_object.setAsset("attachment", uri).then(() => { 1150 console.info('setAsset success.'); 1151 }).catch((err: BusinessError) => { 1152 console.error("setAsset failed, error code = " + err.code); 1153 }); 1154 } 1155} 1156``` 1157 1158### setAssets<sup>20+</sup> 1159 1160setAssets(assetsKey: string, uris: Array<string>): Promise<void> 1161 1162设置分布式对象中的多个资产的属性信息，该接口必须在[setSessionId](#setsessionid9-2)接口调用前使用。uris数组的数量范围为1-50。使用Promise异步回调。 1163 1164> **注意：** 1165> 1166> 在设置资产时必须保证assetsKey存在且对应文件为资产类型文件，否则无法保证对端能接收到此次设置的资产。 1167> 1168> 在设置资产时必须保证uris数组内uri均为正确且真实存在的分布式路径，否则无法保证对端能接收到此次设置的资产。 1169 1170有以下几种异常场景: 1171 1172 | 触发条件 | 操作结果 | 1173 | -------- | -------- | 1174 | 调用[setSessionId](#setsessionid9-2)接口设置sessionId后再调用[setAssets](#setassets20)接口设置资产。 | 设置资产失败，抛出15400003异常。 | 1175 | assetsKey为无效值，例如：null（不存在）、undefined（未定义）或''（空字符串）。 | 设置资产失败，抛出15400002异常。 | 1176 | assetsKey存在、对应文件为非资产类型。 | 系统会强制修改该字段对应的文件类型为资产类型且设置资产字段，可能出现真实资产无法同步至对端设备。 | 1177 | assetsKey存在、且对应文件为资产类型。 | 设置资产成功、更新uri信息。 | 1178 | uris数组uri元素数量为0或超过50（不包含50）个字符。 | 设置资产失败，抛出15400002异常。 | 1179 | uris数组uri元素数量为1-50之间，存在单个或多个uri无效，例如：null（不存在）、undefined（未定义）或''（空字符串）。| 设置资产失败，抛出15400002异常。 | 1180 1181**系统能力：** SystemCapability.DistributedDataManager.DataObject.DistributedObject 1182 1183**参数：** 1184 1185 | 参数名 | 类型 | 必填 | 说明 | 1186 | -------- | ----------------------- | ---- | ---------------------------------------------------------------------------------- | 1187 | assetsKey | string | 是 | 分布式对象中资产数组类型数据对应的属性名。<br/>**使用约束：** <br/>（1）提供的assetsKey对应的文件已存在且类型必须为资产[Asset](js-apis-data-commonType.md#asset)，才可进行正确的设置资产。若assetsKey对应文件不存在或文件存在但类型不是资产类型，可能会出现资产设置错误。<br/>（2）在协同或接续场景下需要双端满足assetsKey对应的文件存在且为资产类型，才可将设置的资产数组同步到对端设备。 | 1188 | uris | Array<string> | 是 | 待设置的新资产数组的uri集合，表示资产数组内每个资产的存放的分布式路径。数组元素有效范围为1-50，元素uri必须为真实存在的资产对应的分布式路径。 | 1189 1190**返回值：** 1191 1192 | 类型 | 说明 | 1193 | ------------------- | ------------- | 1194 | Promise<void> | 无返回结果的Promise对象。 | 1195 1196**错误码：** 1197 1198 以下错误码的详细介绍请参见[分布式数据对象错误码](errorcode-distributed-dataObject.md)。 1199 1200 | 错误码ID | 错误信息 | 1201 | -------- | -------- | 1202 | 15400002 | Parameter error. Possible causes:1. The assetsKey is invalid, such as ""; 2. The uris is invalid, such as the length of uris is more than 50. | 1203 | 15400003 | The sessionId of the distributed object has been set. | 1204 1205**示例:** 1206 1207```ts 1208import { UIAbility } from '@kit.AbilityKit'; 1209import { window } from '@kit.ArkUI'; 1210import { BusinessError } from '@kit.BasicServicesKit'; 1211import { commonType, distributedDataObject } from '@kit.ArkData'; 1212 1213class Note { 1214 title: string | undefined 1215 text: string | undefined 1216 attachment: commonType.Asset | undefined 1217 1218 constructor(title: string | undefined, text: string | undefined, attachment: commonType.Asset | undefined) { 1219 this.title = title; 1220 this.text = text; 1221 this.attachment = attachment; 1222 } 1223} 1224 1225class EntryAbility extends UIAbility { 1226 onWindowStageCreate(windowStage: window.WindowStage) { 1227 let attachment: commonType.Asset = { 1228 name: 'test_img.jpg', 1229 uri: 'file://com.example.myapplication/data/storage/el2/distributedfiles/dir/test_img.jpg', 1230 path: '/dir/test_img.jpg', 1231 createTime: '2024-01-02 10:00:00', 1232 modifyTime: '2024-01-02 10:00:00', 1233 size: '5', 1234 status: commonType.AssetStatus.ASSET_NORMAL 1235 } 1236 let note: Note = new Note('test', 'test', attachment); 1237 let g_object: distributedDataObject.DataObject = distributedDataObject.create(this.context, note); 1238 1239 let uris: Array<string> = ["file://test/test_1.txt", "file://test/test_2.txt"]; 1240 g_object.setAssets("attachment", uris).then(() => { 1241 console.info('setAssets success.'); 1242 }).catch((err: BusinessError) => { 1243 console.error("setAssets failed, error code = " + err.code); 1244 }); 1245 } 1246} 1247``` 1248 1249## distributedDataObject.createDistributedObject<sup>(deprecated)</sup> 1250 1251createDistributedObject(source: object): DistributedObject 1252 1253 1254创建一个分布式数据对象。 1255 1256> **说明：** 1257> 1258> 从 API Version 8 开始支持，从 API Version 9 开始废弃，建议使用[distributedDataObject.create](#distributeddataobjectcreate9)替代。 1259 1260**系统能力：** SystemCapability.DistributedDataManager.DataObject.DistributedObject 1261 1262**参数：** 1263 1264 | 参数名 | 类型 | 必填 | 说明 | 1265 | -------- | -------- | -------- | -------- | 1266 | source | object | 是 | 设置分布式数据对象的属性。 | 1267 1268**返回值：** 1269 1270| 类型 | 说明 | 1271| -------- | -------- | 1272| [DistributedObject](#distributedobjectdeprecated) | 创建完成的分布式数据对象。 | 1273 1274**示例：** 1275 1276```ts 1277class SourceObject { 1278 name: string 1279 age: number 1280 isVis: boolean 1281 1282 constructor(name: string, age: number, isVis: boolean) { 1283 this.name = name 1284 this.age = age 1285 this.isVis = isVis 1286 } 1287} 1288 1289let source: SourceObject = new SourceObject("jack", 18, false); 1290let g_object: distributedDataObject.DistributedObject = distributedDataObject.createDistributedObject(source); 1291``` 1292 1293## DistributedObject<sup>(deprecated)</sup> 1294 1295表示一个分布式数据对象。在使用以下接口前，需调用[createDistributedObject()](#distributeddataobjectcreatedistributedobjectdeprecated)获取DistributedObject对象。 1296 1297### setSessionId<sup>(deprecated)</sup> 1298 1299setSessionId(sessionId?: string): boolean 1300 1301设置sessionId。当可信组网中有多个设备处于协同状态时，如果多个设备间的分布式对象设置为同一个sessionId，就能自动同步。 1302 1303> **说明：** 1304> 1305> 从 API Version 8 开始支持，从 API Version 9 开始废弃，建议使用[setSessionId](#setsessionid9)替代。 1306 1307**需要权限：** ohos.permission.DISTRIBUTED_DATASYNC 1308 1309**系统能力：** SystemCapability.DistributedDataManager.DataObject.DistributedObject 1310 1311**参数：** 1312 1313 | 参数名 | 类型 | 必填 | 说明 | 1314 | -------- | -------- | -------- | -------- | 1315 | sessionId | string | 否 | 分布式数据对象在可信组网中的标识ID。如果要退出分布式组网，设置为""或不设置均可。 | 1316 1317**返回值：** 1318 1319 | 类型 | 说明 | 1320 | -------- | -------- | 1321 | boolean | true：标识设置sessionId成功。 <br>false：标识设置sessionId失败。 | 1322 1323**示例：** 1324 1325```ts 1326class SourceObject { 1327 name: string 1328 age: number 1329 isVis: boolean 1330 1331 constructor(name: string, age: number, isVis: boolean) { 1332 this.name = name 1333 this.age = age 1334 this.isVis = isVis 1335 } 1336} 1337 1338let source: SourceObject = new SourceObject("jack", 18, false); 1339let g_object: distributedDataObject.DistributedObject = distributedDataObject.createDistributedObject(source); 1340// g_object加入分布式组网 1341g_object.setSessionId(distributedDataObject.genSessionId()); 1342// 设置为""退出分布式组网 1343g_object.setSessionId(""); 1344``` 1345 1346### on('change')<sup>(deprecated)</sup> 1347 1348on(type: 'change', callback: (sessionId: string, fields: Array<string>) => void): void 1349 1350监听分布式数据对象的变更。 1351 1352> **说明：** 1353> 1354> 从 API Version 8 开始支持，从 API Version 9 开始废弃，建议使用[on('change')](#onchange9)替代。 1355 1356**系统能力：** SystemCapability.DistributedDataManager.DataObject.DistributedObject 1357 1358**参数：** 1359 1360| 参数名 | 类型 | 必填 | 说明 | 1361| -------- | -------- | -------- | -------- | 1362| type | string | 是 | 事件类型，固定为'change'，表示数据变更。 | 1363| callback | (sessionId: string, fields: Array<string>) => void | 是 | 变更回调对象实例。<br>sessionId：标识变更对象的sessionId； <br>fields：标识对象变更的属性名。 | 1364 1365**示例：** 1366 1367```ts 1368class SourceObject { 1369 name: string 1370 age: number 1371 isVis: boolean 1372 1373 constructor(name: string, age: number, isVis: boolean) { 1374 this.name = name 1375 this.age = age 1376 this.isVis = isVis 1377 } 1378} 1379 1380let source: SourceObject = new SourceObject("jack", 18, false); 1381let g_object: distributedDataObject.DistributedObject = distributedDataObject.createDistributedObject(source); 1382g_object.on("change", (sessionId: string, fields: Array<string>) => { 1383 console.info("change" + sessionId); 1384 if (fields != null && fields != undefined) { 1385 for (let index: number = 0; index < fields.length; index++) { 1386 console.info("changed !" + fields[index] + " " + g_object[fields[index]]); 1387 } 1388 } 1389}); 1390``` 1391 1392### off('change')<sup>(deprecated)</sup> 1393 1394off(type: 'change', callback?: (sessionId: string, fields: Array<string>) => void): void 1395 1396当不再进行数据变更监听时，使用此接口删除对象的变更监听。 1397 1398> **说明：** 1399> 1400> 从 API Version 8 开始支持，从 API Version 9 开始废弃，建议使用[off('change')](#offchange9)替代。 1401 1402**系统能力：** SystemCapability.DistributedDataManager.DataObject.DistributedObject 1403 1404**参数：** 1405 1406| 参数名 | 类型 | 必填 | 说明 | 1407| -------- | -------- | -------- | -------- | 1408| type | string | 是 | 事件类型，固定为'change'，表示数据变更。 | 1409| callback | (sessionId: string, fields: Array<string>) => void | 否 | 需要删除的数据变更回调，若不设置则删除该对象所有的数据变更回调。<br>sessionId：标识变更对象的sessionId； <br>fields：标识对象变更的属性名。 | 1410 1411**示例：** 1412 1413```ts 1414class SourceObject { 1415 name: string 1416 age: number 1417 isVis: boolean 1418 1419 constructor(name: string, age: number, isVis: boolean) { 1420 this.name = name 1421 this.age = age 1422 this.isVis = isVis 1423 } 1424} 1425 1426let source: SourceObject = new SourceObject("jack", 18, false); 1427let g_object: distributedDataObject.DistributedObject = distributedDataObject.createDistributedObject(source); 1428// 删除数据变更回调changeCallback 1429g_object.off("change", (sessionId: string, fields: Array<string>) => { 1430 console.info("change" + sessionId); 1431 if (fields != null && fields != undefined) { 1432 for (let index: number = 0; index < fields.length; index++) { 1433 console.info("changed !" + fields[index] + " " + g_object[fields[index]]); 1434 } 1435 } 1436}); 1437// 删除所有的数据变更回调 1438g_object.off("change"); 1439``` 1440 1441### on('status')<sup>(deprecated)</sup> 1442 1443on(type: 'status', callback: (sessionId: string, networkId: string, status: 'online' | 'offline' ) => void): void 1444 1445监听分布式数据对象的上下线。 1446 1447> **说明：** 1448> 1449> 从 API Version 8 开始支持，从 API Version 9 开始废弃，建议使用[on('status')](#onstatus9)替代。 1450 1451**系统能力：** SystemCapability.DistributedDataManager.DataObject.DistributedObject 1452 1453**参数：** 1454 1455| 参数名 | 类型 | 必填 | 说明 | 1456| -------- | -------- | -------- | -------- | 1457| type | string | 是 | 事件类型，固定为'status'，表示对象上下线。 | 1458| callback | (sessionId: string, networkId: string, status: 'online' \| 'offline' ) => void | 是 | 监听上下线回调实例。<br>sessionId：标识变更对象的sessionId； <br>networkId：标识对象设备； <br>status：标识对象为'online'(上线)或'offline'(下线)的状态。 | 1459 1460**示例：** 1461 1462```ts 1463class SourceObject { 1464 name: string 1465 age: number 1466 isVis: boolean 1467 1468 constructor(name: string, age: number, isVis: boolean) { 1469 this.name = name 1470 this.age = age 1471 this.isVis = isVis 1472 } 1473} 1474 1475let source: SourceObject = new SourceObject("jack", 18, false); 1476let g_object: distributedDataObject.DistributedObject = distributedDataObject.createDistributedObject(source); 1477 1478g_object.on("status", (sessionId: string, networkId: string, status: 'online' | 'offline') => { 1479 console.info("status changed " + sessionId + " " + status + " " + networkId); 1480}); 1481``` 1482 1483### off('status')<sup>(deprecated)</sup> 1484 1485off(type: 'status', callback?: (sessionId: string, networkId: string, status: 'online' | 'offline' ) => void): void 1486 1487当不再进行对象上下线监听时，使用此接口删除对象的上下线监听。 1488 1489> **说明：** 1490> 1491> 从 API Version 8 开始支持，从 API Version 9 开始废弃，建议使用[off('status')](#offstatus9)替代。 1492 1493**系统能力：** SystemCapability.DistributedDataManager.DataObject.DistributedObject 1494 1495**参数：** 1496 1497| 参数名 | 类型 | 必填 | 说明 | 1498| -------- | -------- | -------- | -------- | 1499| type | string | 是 | 事件类型，固定为'status'，表示对象上下线。 | 1500| callback | (sessionId: string, networkId: string, status: 'online' \| 'offline' ) => void | 否 | 需要删除的上下线回调，若不设置则删除该对象所有的上下线回调。<br>sessionId：标识变更对象的sessionId； <br>networkId：标识变更对象； <br>status：标识对象为'online'(上线)或'offline'(下线)的状态。 | 1501 1502 1503**示例：** 1504 1505```ts 1506class SourceObject { 1507 name: string 1508 age: number 1509 isVis: boolean 1510 1511 constructor(name: string, age: number, isVis: boolean) { 1512 this.name = name 1513 this.age = age 1514 this.isVis = isVis 1515 } 1516} 1517 1518let source: SourceObject = new SourceObject("jack", 18, false); 1519let g_object: distributedDataObject.DistributedObject = distributedDataObject.createDistributedObject(source); 1520// 删除上下线回调changeCallback 1521g_object.off("status", (sessionId: string, networkId: string, status: 'online' | 'offline') => { 1522 console.info("status changed " + sessionId + " " + status + " " + networkId); 1523}); 1524// 删除所有的上下线回调 1525g_object.off("status"); 1526```
