1# @ohos.data.distributedDataObject (分布式数据对象) 2 3本模块提供管理基本数据对象的相关能力，包括创建、查询、删除、修改、订阅等；同时支持相同应用多设备间的分布式数据对象协同能力。 4 5> **说明：** 6> 7> 本模块首批接口从API version 8开始支持。后续版本的新增接口，采用上角标单独标记接口的起始版本。 8 9 10## 导入模块 11 12```ts 13import { distributedDataObject } from '@kit.ArkData'; 14``` 15 16## distributedDataObject.create<sup>9+</sup> 17 18create(context: Context, source: object): DataObject 19 20创建一个分布式数据对象。 21 22**系统能力：** SystemCapability.DistributedDataManager.DataObject.DistributedObject 23 24**参数：** 25 26 | 参数名 | 类型 | 必填 | 说明 | 27 | -------- | -------- | -------- | -------- | 28 | 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)。 | 29 | source | object | 是 | 设置分布式数据对象的属性。 | 30 31**返回值：** 32 33| 类型 | 说明 | 34| -------- | -------- | 35| [DataObject](#dataobject) | 创建完成的分布式数据对象。 | 36 37**错误码：** 38 39 以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)。 40 41 | 错误码ID | 错误信息 | 42 | -------- | -------- | 43 | 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types. | 44 45**示例：** 46 47FA模型示例： 48<!--code_no_check_fa--> 49```ts 50// 导入模块 51import { featureAbility } from '@kit.AbilityKit'; 52import { BusinessError } from '@kit.BasicServicesKit'; 53// 获取context 54let context = featureAbility.getContext(); 55class SourceObject { 56 name: string 57 age: number 58 isVis: boolean 59 60 constructor(name: string, age: number, isVis: boolean) { 61 this.name = name 62 this.age = age 63 this.isVis = isVis 64 } 65} 66 67let source: SourceObject = new SourceObject("jack", 18, false); 68let g_object: distributedDataObject.DataObject = distributedDataObject.create(context, source); 69``` 70 71Stage模型示例： 72 73```ts 74// 导入模块 75import { UIAbility } from '@kit.AbilityKit'; 76import { BusinessError } from '@kit.BasicServicesKit'; 77import { window } from '@kit.ArkUI'; 78 79let g_object: distributedDataObject.DataObject|null = null; 80class SourceObject { 81 name: string 82 age: number 83 isVis: boolean 84 85 constructor(name: string, age: number, isVis: boolean) { 86 this.name = name 87 this.age = age 88 this.isVis = isVis 89 } 90} 91 92class EntryAbility extends UIAbility { 93 onWindowStageCreate(windowStage: window.WindowStage) { 94 let source: SourceObject = new SourceObject("jack", 18, false); 95 g_object = distributedDataObject.create(this.context, source); 96 } 97} 98``` 99 100## distributedDataObject.genSessionId 101 102genSessionId(): string 103 104随机创建一个sessionId。 105 106**系统能力：** SystemCapability.DistributedDataManager.DataObject.DistributedObject 107 108**返回值：** 109 110 | 类型 | 说明 | 111 | -------- | -------- | 112 | string | 随机创建的sessionId。 | 113 114**示例：** 115 116```ts 117let sessionId: string = distributedDataObject.genSessionId(); 118``` 119 120## SaveSuccessResponse<sup>9+</sup> 121 122[save](#save9)接口回调信息。 123 124**系统能力：** SystemCapability.DistributedDataManager.DataObject.DistributedObject 125 126| 名称 | 类型 | 必填 | 说明 | 127| -------- | -------- | -------- | -------- | 128| sessionId | string | 是 | 多设备协同的唯一标识。 | 129| version | number | 是 | 已保存对象的版本。 | 130| deviceId | string | 是 | 存储数据的设备号，标识需要保存对象的设备。"local"表示本地设备，否则表示其他设备的设备号。 | 131 132## RevokeSaveSuccessResponse<sup>9+</sup> 133 134[revokeSave](#revokesave9)接口回调信息。 135 136**系统能力：** SystemCapability.DistributedDataManager.DataObject.DistributedObject 137 138| 名称 | 类型 | 必填 | 说明 | 139| -------- | -------- | -------- | -------- | 140| sessionId | string | 是 | 多设备协同的唯一标识。 | 141 142## BindInfo<sup>11+</sup> 143 144数据库的绑定信息。当前版本只支持关系型数据库。 145 146**系统能力：** SystemCapability.DistributedDataManager.DataObject.DistributedObject 147 148 | 名称 | 类型 | 只读 | 可选 | 说明 | 149 | ---------- | ------------------------------------------------------------------ | ---- | ---- | ------------------------------------ | 150 | storeName | string | 否 | 否 | 待绑定资产在所属的数据库中的库名。 | 151 | tableName | string | 否 | 否 | 待绑定资产在所属的数据库中的表名。 | 152 | primaryKey | [commonType.ValuesBucket](js-apis-data-commonType.md#valuesbucket) | 否 | 否 | 待绑定资产在所属的数据库中的主键。 | 153 | field | string | 否 | 否 | 待绑定资产在所属的数据库中的列名。 | 154 | assetName | string | 否 | 否 | 待绑定资产在所属的数据库中的资产名。 | 155 156## DataObject 157 158表示一个分布式数据对象。在使用以下接口前，需调用[create()](#distributeddataobjectcreate9)获取DataObject对象。 159 160### setSessionId<sup>9+</sup> 161 162setSessionId(sessionId: string, callback: AsyncCallback<void>): void 163 164设置sessionId，使用callback方式异步回调。当可信组网中有多个设备处于协同状态时，如果多个设备间的分布式对象设置为同一个sessionId，就能自动同步。 165 166**需要权限：** ohos.permission.DISTRIBUTED_DATASYNC。 167 168**系统能力：** SystemCapability.DistributedDataManager.DataObject.DistributedObject 169 170**参数：** 171 172 | 参数名 | 类型 | 必填 | 说明 | 173 | --------- | ------------------------- | ---- | -------------------------------------------------------------------------------------------------------------- | 174 | sessionId | string | 是 | 分布式数据对象在可信组网中的标识ID，长度不大于128，且只能包含字母数字或下划线_。设置为""时表示退出分布式组网。 | 175 | callback | AsyncCallback<void> | 是 | 加入session的异步回调。 | 176 177**错误码：** 178 179 以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和[分布式数据对象错误码](errorcode-distributed-dataObject.md)。 180 181 | 错误码ID | 错误信息 | 182 | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------ | 183 | 201 | Permission verification failed. | 184 | 401 | Parameter error. Possible causes: 1. Incorrect parameter types; 2. The sessionId allows only letters, digits, and underscores(_), and cannot exceed 128 in length. | 185 | 15400001 | Failed to create the in-memory database. | 186 187**示例：** 188 189```ts 190// g_object加入分布式组网 191g_object.setSessionId(distributedDataObject.genSessionId(), ()=>{ 192 console.info("join session"); 193}); 194// g_object退出分布式组网 195g_object.setSessionId("", ()=>{ 196 console.info("leave all session"); 197}); 198``` 199 200### setSessionId<sup>9+</sup> 201 202setSessionId(callback: AsyncCallback<void>): void 203 204退出所有已加入的session，使用callback方式异步回调。 205 206**需要权限：** ohos.permission.DISTRIBUTED_DATASYNC。 207 208**系统能力：** SystemCapability.DistributedDataManager.DataObject.DistributedObject 209 210**参数：** 211 212 | 参数名 | 类型 | 必填 | 说明 | 213 | -------- | -------- | -------- | -------- | 214 | callback | AsyncCallback<void> | 是 | 退出所有已加入session的异步回调。 | 215 216**错误码：** 217 218 以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和[分布式数据对象错误码](errorcode-distributed-dataObject.md)。 219 220 | 错误码ID | 错误信息 | 221 | -------- | -------- | 222 | 201 | Permission verification failed. | 223 | 401 | Parameter error. Incorrect parameter types. | 224 | 15400001 | Failed to create the in-memory database. | 225 226**示例：** 227 228```ts 229// g_object加入分布式组网 230g_object.setSessionId(distributedDataObject.genSessionId(), ()=>{ 231 console.info("join session"); 232}); 233// 退出分布式组网 234g_object.setSessionId(() => { 235 console.info("leave all session."); 236}); 237``` 238 239### setSessionId<sup>9+</sup> 240 241setSessionId(sessionId?: string): Promise<void> 242 243设置sessionId，使用Promise异步返回。当可信组网中有多个设备处于协同状态时，如果多个设备间的分布式对象设置为同一个sessionId，就能自动同步。 244 245**需要权限：** ohos.permission.DISTRIBUTED_DATASYNC。 246 247**系统能力：** SystemCapability.DistributedDataManager.DataObject.DistributedObject 248 249**参数：** 250 251 | 参数名 | 类型 | 必填 | 说明 | 252 | --------- | ------ | ---- | ---------------------------------------------------------------------------------------------------------------------------- | 253 | sessionId | string | 否 | 分布式数据对象在可信组网中的标识ID，长度不大于128，且只能包含字母数字或下划线_。如果要退出分布式组网，设置为""或不设置均可。 | 254 255**返回值：** 256 257| 类型 | 说明 | 258| -------- | -------- | 259| Promise<void> | Promise对象。| 260 261**错误码：** 262 263 以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和[分布式数据对象错误码](errorcode-distributed-dataObject.md)。 264 265 | 错误码ID | 错误信息 | 266 | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------ | 267 | 201 | Permission verification failed. | 268 | 401 | Parameter error. Possible causes: 1. Incorrect parameter types; 2. The sessionId allows only letters, digits, and underscores(_), and cannot exceed 128 in length. | 269 | 15400001 | Failed to create the in-memory database. | 270 271**示例：** 272 273```ts 274// g_object加入分布式组网 275g_object.setSessionId(distributedDataObject.genSessionId()).then (()=>{ 276 console.info("join session."); 277 }).catch((error: BusinessError)=>{ 278 console.info("error:" + error.code + error.message); 279}); 280// 退出分布式组网 281g_object.setSessionId().then (()=>{ 282 console.info("leave all session."); 283 }).catch((error: BusinessError)=>{ 284 console.info("error:" + error.code + error.message); 285}); 286``` 287 288### on('change')<sup>9+</sup> 289 290on(type: 'change', callback: (sessionId: string, fields: Array<string>) => void): void 291 292监听分布式数据对象的数据变更。 293 294**系统能力：** SystemCapability.DistributedDataManager.DataObject.DistributedObject 295 296**参数：** 297 298| 参数名 | 类型 | 必填 | 说明 | 299| -------- | -------- | -------- | -------- | 300| type | string | 是 | 事件类型，固定为'change'，表示数据变更。 | 301| callback | Function | 是 | 变更回调对象实例。<br>sessionId：标识变更对象的sessionId； <br>fields：标识对象变更的属性名。 | 302 303**错误码：** 304 305 以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)。 306 307 | 错误码ID | 错误信息 | 308 | -------- | -------- | 309 | 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types. | 310 311**示例：** 312 313```ts 314g_object.on("change", (sessionId: string, fields: Array<string>) => { 315 console.info("change" + sessionId); 316 if (g_object != null && fields != null && fields != undefined) { 317 for (let index: number = 0; index < fields.length; index++) { 318 console.info("changed !" + fields[index] + " " + g_object[fields[index]]); 319 } 320 } 321}); 322``` 323 324### off('change')<sup>9+</sup> 325 326off(type: 'change', callback?: (sessionId: string, fields: Array<string>) => void): void 327 328当不再进行数据变更监听时，使用此接口删除对象的变更监听。 329 330**系统能力：** SystemCapability.DistributedDataManager.DataObject.DistributedObject 331 332**参数：** 333 334| 参数名 | 类型 | 必填 | 说明 | 335| -------- | -------- | -------- | -------- | 336| type | string | 是 | 事件类型，固定为'change'，表示数据变更。 | 337| callback | Function | 否 | 需要删除的数据变更回调，若不设置则删除该对象所有的数据变更回调。<br>sessionId：标识变更对象的sessionId； <br>fields：标识对象变更的属性名。 | 338 339**错误码：** 340 341 以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)。 342 343 | 错误码ID | 错误信息 | 344 | -------- | -------- | 345 | 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types. | 346 347**示例：** 348 349```ts 350// 删除数据变更回调changeCallback 351g_object.off("change", (sessionId: string, fields: Array<string>) => { 352 console.info("change" + sessionId); 353 if (g_object != null && fields != null && fields != undefined) { 354 for (let index: number = 0; index < fields.length; index++) { 355 console.info("changed !" + fields[index] + " " + g_object[fields[index]]); 356 } 357 } 358}); 359// 删除所有的数据变更回调 360g_object.off("change"); 361``` 362 363### on('status')<sup>9+</sup> 364 365on(type: 'status', callback: (sessionId: string, networkId: string, status: 'online' \| 'offline' ) => void): void 366 367监听分布式数据对象的上下线。 368 369**系统能力：** SystemCapability.DistributedDataManager.DataObject.DistributedObject 370 371**参数：** 372 373| 参数名 | 类型 | 必填 | 说明 | 374| -------- | -------- | -------- | -------- | 375| type | string | 是 | 事件类型，固定为'status'，表示对象上下线。 | 376| callback | Function | 是 | 监听上下线回调实例。<br>sessionId：标识变更对象的sessionId； <br>networkId：标识对象设备； <br>status：标识对象为'online'(上线)或'offline'(下线)的状态。 | 377 378**错误码：** 379 380 以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)。 381 382 | 错误码ID | 错误信息 | 383 | -------- | -------- | 384 | 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types. | 385 386**示例：** 387 388```ts 389g_object.on("status", (sessionId: string, networkId: string, status: 'online' | 'offline') => { 390 console.info("status changed " + sessionId + " " + status + " " + networkId); 391}); 392``` 393 394### off('status')<sup>9+</sup> 395 396off(type: 'status', callback?:(sessionId: string, networkId: string, status: 'online' \| 'offline') => void): void 397 398当不再进行对象上下线监听时，使用此接口删除对象的上下线监听。 399 400**系统能力：** SystemCapability.DistributedDataManager.DataObject.DistributedObject 401 402**参数：** 403 404| 参数名 | 类型 | 必填 | 说明 | 405| -------- | -------- | -------- | -------- | 406| type | string | 是 | 事件类型，固定为'status'，表示对象上下线。 | 407| callback | Function | 否 | 需要删除的上下线回调，若不设置则删除该对象所有的上下线回调。<br>sessionId：标识变更对象的sessionId； <br>networkId：标识变更对象； <br>status：标识对象为'online'(上线)或'offline'(下线)的状态。 | 408 409**错误码：** 410 411 以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)。 412 413 | 错误码ID | 错误信息 | 414 | -------- | -------- | 415 | 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types. | 416 417**示例：** 418 419```ts 420// 删除上下线回调changeCallback 421g_object.off("status", (sessionId: string, networkId: string, status: 'online' | 'offline') => { 422 console.info("status changed " + sessionId + " " + status + " " + networkId); 423}); 424// 删除所有的上下线回调 425g_object.off("status"); 426``` 427 428### save<sup>9+</sup> 429 430save(deviceId: string, callback: AsyncCallback<SaveSuccessResponse>): void 431 432保存分布式数据对象。使用callback方式异步回调。 433 434对象数据保存成功后，当应用存在时不会释放对象数据，当应用退出后，重新进入应用时，恢复保存在设备上的数据。 435 436有以下几种情况时，保存的数据将会被释放： 437 438- 存储时间超过24小时。 439- 应用卸载。 440- 成功恢复数据之后。 441 442**系统能力：** SystemCapability.DistributedDataManager.DataObject.DistributedObject 443 444**参数：** 445 446 | 参数名 | 类型 | 必填 | 说明 | 447 | -------- | -------- | -------- | -------- | 448 | deviceId | string | 是 | 保存数据的deviceId，当deviceId为"local"，代表存储在本地设备。 | 449 | callback | AsyncCallback<[SaveSuccessResponse](#savesuccessresponse9)> | 是 | 回调函数。返回SaveSuccessResponse，包含sessionId、version、deviceId等信息。 | 450 451**错误码：** 452 453 以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)。 454 455 | 错误码ID | 错误信息 | 456 | -------- | -------- | 457 | 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types. | 458 | 801 | Capability not supported. | 459 460**示例：** 461 462```ts 463g_object.setSessionId("123456"); 464g_object.save("local", (err: BusinessError, result:distributedDataObject.SaveSuccessResponse) => { 465 if (err) { 466 console.info("save failed, error code = " + err.code); 467 console.info("save failed, error message: " + err.message); 468 return; 469 } 470 console.info("save callback"); 471 console.info("save sessionId: " + result.sessionId); 472 console.info("save version: " + result.version); 473 console.info("save deviceId: " + result.deviceId); 474}); 475``` 476 477### save<sup>9+</sup> 478 479save(deviceId: string): Promise<SaveSuccessResponse> 480 481保存分布式数据对象。使用Promise方式作为异步回调。 482 483对象数据保存成功后，当应用存在时不会释放对象数据，当应用退出后，重新进入应用时，恢复保存在设备上的数据。 484 485有以下几种情况时，保存的数据将会被释放： 486 487- 存储时间超过24小时。 488- 应用卸载。 489- 成功恢复数据之后。 490 491**系统能力：** SystemCapability.DistributedDataManager.DataObject.DistributedObject 492 493**参数：** 494 495 | 参数名 | 类型 | 必填 | 说明 | 496 | -------- | -------- | -------- | -------- | 497 | deviceId | string | 是 | 保存数据的设备号，当deviceId默认为"local"，标识需要保存对象的设备。 | 498 499**返回值：** 500 501 | 类型 | 说明 | 502 | -------- | -------- | 503 | Promise<[SaveSuccessResponse](#savesuccessresponse9)> | Promise对象。返回SaveSuccessResponse，包含sessionId、version、deviceId等信息。| 504 505**错误码：** 506 507 以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)。 508 509 | 错误码ID | 错误信息 | 510 | -------- | -------- | 511 | 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types. | 512 | 801 | Capability not supported. | 513 514**示例：** 515 516```ts 517g_object.setSessionId("123456"); 518g_object.save("local").then((result: distributedDataObject.SaveSuccessResponse) => { 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}).catch((err: BusinessError) => { 524 console.info("save failed, error code = " + err.code); 525 console.info("save failed, error message: " + err.message); 526}); 527``` 528 529### revokeSave<sup>9+</sup> 530 531revokeSave(callback: AsyncCallback<RevokeSaveSuccessResponse>): void 532 533撤回保存的分布式数据对象。使用callback方式作为异步方法。 534 535如果对象保存在本地设备，那么将删除所有受信任设备上所保存的数据。 536如果对象保存在其他设备，那么将删除本地设备上的数据。 537 538**系统能力：** SystemCapability.DistributedDataManager.DataObject.DistributedObject 539 540**参数：** 541 542 | 参数名 | 类型 | 必填 | 说明 | 543 | -------- | -------- | -------- | -------- | 544 | callback | AsyncCallback<[RevokeSaveSuccessResponse](#revokesavesuccessresponse9)> | 是 | 回调函数。返回RevokeSaveSuccessResponse，包含sessionId。 | 545 546**错误码：** 547 548 以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)。 549 550 | 错误码ID | 错误信息 | 551 | -------- | -------- | 552 | 401 | Parameter error. Incorrect parameter types. | 553 | 801 | Capability not supported. | 554 555**示例：** 556 557```ts 558g_object.setSessionId("123456"); 559// 持久化数据 560g_object.save("local", (err: BusinessError, result: distributedDataObject.SaveSuccessResponse) => { 561 if (err) { 562 console.info("save failed, error code = " + err.code); 563 console.info("save failed, error message: " + err.message); 564 return; 565 } 566 console.info("save callback"); 567 console.info("save sessionId: " + result.sessionId); 568 console.info("save version: " + result.version); 569 console.info("save deviceId: " + result.deviceId); 570}); 571// 删除持久化保存的数据 572g_object.revokeSave((err: BusinessError, result: distributedDataObject.RevokeSaveSuccessResponse) => { 573 if (err) { 574 console.info("revokeSave failed, error code = " + err.code); 575 console.info("revokeSave failed, error message: " + err.message); 576 return; 577 } 578 console.info("revokeSave callback"); 579 console.info("revokeSave sessionId " + result.sessionId); 580}); 581``` 582 583### revokeSave<sup>9+</sup> 584 585revokeSave(): Promise<RevokeSaveSuccessResponse> 586 587撤回保存的分布式数据对象。使用Promise方式作为异步方法。 588 589如果对象保存在本地设备，那么将删除所有受信任设备上所保存的数据。 590如果对象保存在其他设备，那么将删除本地设备上的数据。 591 592**系统能力：** SystemCapability.DistributedDataManager.DataObject.DistributedObject 593 594**返回值：** 595 596 | 类型 | 说明 | 597 | -------- | -------- | 598 | Promise<[RevokeSaveSuccessResponse](#revokesavesuccessresponse9)> | Promise对象。返回RevokeSaveSuccessResponse，包含sessionId。 | 599 600**错误码：** 601 602 以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)。 603 604 | 错误码ID | 错误信息 | 605 | -------- | -------- | 606 | 801 | Capability not supported. | 607 608**示例：** 609 610```ts 611g_object.setSessionId("123456"); 612// 持久化数据 613g_object.save("local").then((result: distributedDataObject.SaveSuccessResponse) => { 614 console.info("save callback"); 615 console.info("save sessionId " + result.sessionId); 616 console.info("save version " + result.version); 617 console.info("save deviceId " + result.deviceId); 618}).catch((err: BusinessError) => { 619 console.info("save failed, error code = " + err.code); 620 console.info("save failed, error message: " + err.message); 621}); 622// 删除持久化保存的数据 623g_object.revokeSave().then((result: distributedDataObject.RevokeSaveSuccessResponse) => { 624 console.info("revokeSave callback"); 625 console.info("sessionId" + result.sessionId); 626}).catch((err: BusinessError)=> { 627 console.info("revokeSave failed, error code = " + err.code); 628 console.info("revokeSave failed, error message = " + err.message); 629}); 630``` 631 632### bindAssetStore<sup>11+</sup> 633 634bindAssetStore(assetKey: string, bindInfo: BindInfo, callback: AsyncCallback<void>): void 635 636绑定分布式对象中的单个资产与其对应的数据库信息，当前版本只支持分布式对象中的资产与关系型数据库的绑定。使用callback方式异步回调。 637 638当分布式对象中包含的资产和关系型数据库中包含的资产指向同一个实体资产文件，即两个资产的Uri相同时，就会存在冲突，我们把这种资产称为融合资产。如果需要分布式数据管理进行融合资产的冲突解决，需要先进行资产的绑定。当应用退出session后，绑定关系随之消失。 639 640**系统能力：** SystemCapability.DistributedDataManager.DataObject.DistributedObject 641 642**参数：** 643 644 | 参数名 | 类型 | 必填 | 说明 | 645 | -------- | ------------------------- | ---- | ---------------------------------------------------------------------------------- | 646 | assetKey | string | 是 | 待绑定的融合资产在分布式对象中的键值。 | 647 | bindInfo | [BindInfo](#bindinfo11) | 是 | 待绑定的融合资产在数据库中的信息，包含库名、表名、主键、列名及在数据库中的资产名。 | 648 | callback | AsyncCallback<void> | 是 | 绑定数据库的回调。 | 649 650**错误码：** 651 652 以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)。 653 654 | 错误码ID | 错误信息 | 655 | -------- | -------- | 656 | 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types. | 657 | 801 | Capability not supported. | 658 659**示例：** 660 661```ts 662import { UIAbility } from '@kit.AbilityKit'; 663import { window } from '@kit.ArkUI'; 664import { commonType } from '@kit.ArkData'; 665import { BusinessError } from '@kit.BasicServicesKit'; 666 667class Note { 668 title: string | undefined 669 text: string | undefined 670 attachment: commonType.Asset | undefined 671 672 constructor(title: string | undefined, text: string | undefined, attachment: commonType.Asset | undefined) { 673 this.title = title; 674 this.text = text; 675 this.attachment = attachment; 676 } 677} 678 679class EntryAbility extends UIAbility { 680 onWindowStageCreate(windowStage: window.WindowStage) { 681 let attachment: commonType.Asset = { 682 name: 'test_img.jpg', 683 uri: 'file://com.example.myapplication/data/storage/el2/distributedfiles/dir/test_img.jpg', 684 path: '/dir/test_img.jpg', 685 createTime: '2024-01-02 10:00:00', 686 modifyTime: '2024-01-02 10:00:00', 687 size: '5', 688 status: commonType.AssetStatus.ASSET_NORMAL 689 } 690 let note: Note = new Note('test', 'test', attachment); 691 let g_object: distributedDataObject.DataObject = distributedDataObject.create(this.context, note); 692 g_object.setSessionId('123456'); 693 694 const bindInfo: distributedDataObject.BindInfo = { 695 storeName: 'notepad', 696 tableName: 'note_t', 697 primaryKey: { 698 'uuid': '00000000-0000-0000-0000-000000000000' 699 }, 700 field: 'attachment', 701 assetName: attachment.name as string 702 } 703 704 g_object.bindAssetStore('attachment', bindInfo, (err: BusinessError) => { 705 if (err) { 706 console.error('bindAssetStore failed.'); 707 } 708 console.info('bindAssetStore success.'); 709 }); 710 } 711} 712``` 713 714### bindAssetStore<sup>11+</sup> 715 716bindAssetStore(assetKey: string, bindInfo: BindInfo): Promise<void> 717 718绑定分布式对象中的单个资产与其对应的数据库信息，当前版本只支持分布式对象中的资产与关系型数据库的绑定。使用Promise方式作为异步回调。 719 720当分布式对象中包含的资产和关系型数据库中包含的资产指向同一个实体资产文件，即两个资产的Uri相同时，就会存在冲突，我们把这种资产称为融合资产。如果需要分布式数据管理进行融合资产的冲突解决，需要先进行资产的绑定。当应用退出session后，绑定关系随之消失。 721 722**系统能力：** SystemCapability.DistributedDataManager.DataObject.DistributedObject 723 724**参数：** 725 726 | 参数名 | 类型 | 必填 | 说明 | 727 | -------- | ----------------------- | ---- | ---------------------------------------------------------------------------------- | 728 | assetKey | string | 是 | 待绑定的融合资产在分布式对象中的键值。 | 729 | bindInfo | [BindInfo](#bindinfo11) | 是 | 待绑定的融合资产在数据库中的信息，包含库名、表名、主键、列名及在数据库中的资产名。 | 730 731**返回值：** 732 733 | 类型 | 说明 | 734 | ------------------- | ------------- | 735 | Promise<void> | 无返回结果的Promise对象。 | 736 737**错误码：** 738 739 以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)。 740 741 | 错误码ID | 错误信息 | 742 | -------- | -------- | 743 | 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types. | 744 | 801 | Capability not supported. | 745 746**示例:** 747 748```ts 749import { UIAbility } from '@kit.AbilityKit'; 750import { window } from '@kit.ArkUI'; 751import { commonType } from '@kit.ArkData'; 752import { BusinessError } from '@kit.BasicServicesKit'; 753 754class Note { 755 title: string | undefined 756 text: string | undefined 757 attachment: commonType.Asset | undefined 758 759 constructor(title: string | undefined, text: string | undefined, attachment: commonType.Asset | undefined) { 760 this.title = title; 761 this.text = text; 762 this.attachment = attachment; 763 } 764} 765 766class EntryAbility extends UIAbility { 767 onWindowStageCreate(windowStage: window.WindowStage) { 768 let attachment: commonType.Asset = { 769 name: 'test_img.jpg', 770 uri: 'file://com.example.myapplication/data/storage/el2/distributedfiles/dir/test_img.jpg', 771 path: '/dir/test_img.jpg', 772 createTime: '2024-01-02 10:00:00', 773 modifyTime: '2024-01-02 10:00:00', 774 size: '5', 775 status: commonType.AssetStatus.ASSET_NORMAL 776 } 777 let note: Note = new Note('test', 'test', attachment); 778 let g_object: distributedDataObject.DataObject = distributedDataObject.create(this.context, note); 779 g_object.setSessionId('123456'); 780 781 const bindInfo: distributedDataObject.BindInfo = { 782 storeName: 'notepad', 783 tableName: 'note_t', 784 primaryKey: { 785 'uuid': '00000000-0000-0000-0000-000000000000' 786 }, 787 field: 'attachment', 788 assetName: attachment.name as string 789 } 790 791 g_object.bindAssetStore("attachment", bindInfo).then(() => { 792 console.info('bindAssetStore success.'); 793 }).catch((err: BusinessError) => { 794 console.error("bindAssetStore failed, error code = " + err.code); 795 }); 796 } 797} 798``` 799 800## distributedDataObject.createDistributedObject<sup>(deprecated)</sup> 801 802createDistributedObject(source: object): DistributedObject 803 804 805创建一个分布式数据对象。 806 807> **说明：** 808> 809> 从 API Version 8 开始支持，从 API Version 9 开始废弃，建议使用[distributedDataObject.create](#distributeddataobjectcreate9)替代。 810 811**系统能力：** SystemCapability.DistributedDataManager.DataObject.DistributedObject 812 813**参数：** 814 815 | 参数名 | 类型 | 必填 | 说明 | 816 | -------- | -------- | -------- | -------- | 817 | source | object | 是 | 设置分布式数据对象的属性。 | 818 819**返回值：** 820 821| 类型 | 说明 | 822| -------- | -------- | 823| [DistributedObject](#distributedobjectdeprecated) | 创建完成的分布式数据对象。 | 824 825**示例：** 826 827```ts 828class SourceObject { 829 name: string 830 age: number 831 isVis: boolean 832 833 constructor(name: string, age: number, isVis: boolean) { 834 this.name = name 835 this.age = age 836 this.isVis = isVis 837 } 838} 839 840let source: SourceObject = new SourceObject("jack", 18, false); 841let g_object: distributedDataObject.DistributedObject = distributedDataObject.createDistributedObject(source); 842``` 843 844## DistributedObject<sup>(deprecated)</sup> 845 846表示一个分布式数据对象。在使用以下接口前，需调用[createDistributedObject()](#distributeddataobjectcreatedistributedobjectdeprecated)获取DistributedObject对象。 847 848### setSessionId<sup>(deprecated)</sup> 849 850setSessionId(sessionId?: string): boolean 851 852设置sessionId。当可信组网中有多个设备处于协同状态时，如果多个设备间的分布式对象设置为同一个sessionId，就能自动同步。 853 854> **说明：** 855> 856> 从 API Version 8 开始支持，从 API Version 9 开始废弃，建议使用[setSessionId](#setsessionid9)替代。 857 858**需要权限：** ohos.permission.DISTRIBUTED_DATASYNC。 859 860**系统能力：** SystemCapability.DistributedDataManager.DataObject.DistributedObject 861 862**参数：** 863 864 | 参数名 | 类型 | 必填 | 说明 | 865 | -------- | -------- | -------- | -------- | 866 | sessionId | string | 否 | 分布式数据对象在可信组网中的标识ID。如果要退出分布式组网，设置为""或不设置均可。 | 867 868**返回值：** 869 870 | 类型 | 说明 | 871 | -------- | -------- | 872 | boolean | true：标识设置sessionId成功。 <br>false：标识设置sessionId失败。 | 873 874**示例：** 875 876```ts 877class SourceObject { 878 name: string 879 age: number 880 isVis: boolean 881 882 constructor(name: string, age: number, isVis: boolean) { 883 this.name = name 884 this.age = age 885 this.isVis = isVis 886 } 887} 888 889let source: SourceObject = new SourceObject("jack", 18, false); 890let g_object: distributedDataObject.DistributedObject = distributedDataObject.createDistributedObject(source); 891// g_object加入分布式组网 892g_object.setSessionId(distributedDataObject.genSessionId()); 893// 设置为""退出分布式组网 894g_object.setSessionId(""); 895``` 896 897### on('change')<sup>(deprecated)</sup> 898 899on(type: 'change', callback: (sessionId: string, fields: Array<string>) => void): void 900 901监听分布式数据对象的变更。 902 903> **说明：** 904> 905> 从 API Version 8 开始支持，从 API Version 9 开始废弃，建议使用[on('change')](#onchange9)替代。 906 907**系统能力：** SystemCapability.DistributedDataManager.DataObject.DistributedObject 908 909**参数：** 910 911| 参数名 | 类型 | 必填 | 说明 | 912| -------- | -------- | -------- | -------- | 913| type | string | 是 | 事件类型，固定为'change'，表示数据变更。 | 914| callback | Function | 是 | 变更回调对象实例。<br>sessionId：标识变更对象的sessionId； <br>fields：标识对象变更的属性名。 | 915 916**示例：** 917 918```ts 919class SourceObject { 920 name: string 921 age: number 922 isVis: boolean 923 924 constructor(name: string, age: number, isVis: boolean) { 925 this.name = name 926 this.age = age 927 this.isVis = isVis 928 } 929} 930 931let source: SourceObject = new SourceObject("jack", 18, false); 932let g_object: distributedDataObject.DistributedObject = distributedDataObject.createDistributedObject(source); 933g_object.on("change", (sessionId: string, fields: Array<string>) => { 934 console.info("change" + sessionId); 935 if (fields != null && fields != undefined) { 936 for (let index: number = 0; index < fields.length; index++) { 937 console.info("changed !" + fields[index] + " " + g_object[fields[index]]); 938 } 939 } 940}); 941``` 942 943### off('change')<sup>(deprecated)</sup> 944 945off(type: 'change', callback?: (sessionId: string, fields: Array<string>) => void): void 946 947当不再进行数据变更监听时，使用此接口删除对象的变更监听。 948 949> **说明：** 950> 951> 从 API Version 8 开始支持，从 API Version 9 开始废弃，建议使用[off('change')](#offchange9)替代。 952 953**系统能力：** SystemCapability.DistributedDataManager.DataObject.DistributedObject 954 955**参数：** 956 957| 参数名 | 类型 | 必填 | 说明 | 958| -------- | -------- | -------- | -------- | 959| type | string | 是 | 事件类型，固定为'change'，表示数据变更。 | 960| callback | Function | 否 | 需要删除的数据变更回调，若不设置则删除该对象所有的数据变更回调。<br>sessionId：标识变更对象的sessionId； <br>fields：标识对象变更的属性名。 | 961 962**示例：** 963 964```ts 965class SourceObject { 966 name: string 967 age: number 968 isVis: boolean 969 970 constructor(name: string, age: number, isVis: boolean) { 971 this.name = name 972 this.age = age 973 this.isVis = isVis 974 } 975} 976 977let source: SourceObject = new SourceObject("jack", 18, false); 978let g_object: distributedDataObject.DistributedObject = distributedDataObject.createDistributedObject(source); 979// 删除数据变更回调changeCallback 980g_object.off("change", (sessionId: string, fields: Array<string>) => { 981 console.info("change" + sessionId); 982 if (fields != null && fields != undefined) { 983 for (let index: number = 0; index < fields.length; index++) { 984 console.info("changed !" + fields[index] + " " + g_object[fields[index]]); 985 } 986 } 987}); 988// 删除所有的数据变更回调 989g_object.off("change"); 990``` 991 992### on('status')<sup>(deprecated)</sup> 993 994on(type: 'status', callback: (sessionId: string, networkId: string, status: 'online' | 'offline' ) => void): void 995 996监听分布式数据对象的上下线。 997 998> **说明：** 999> 1000> 从 API Version 8 开始支持，从 API Version 9 开始废弃，建议使用[on('status')](#onstatus9)替代。 1001 1002**系统能力：** SystemCapability.DistributedDataManager.DataObject.DistributedObject 1003 1004**参数：** 1005 1006| 参数名 | 类型 | 必填 | 说明 | 1007| -------- | -------- | -------- | -------- | 1008| type | string | 是 | 事件类型，固定为'status'，表示对象上下线。 | 1009| callback | Function | 是 | 监听上下线回调实例。<br>sessionId：标识变更对象的sessionId； <br>networkId：标识对象设备； <br>status：标识对象为'online'(上线)或'offline'(下线)的状态。 | 1010 1011**示例：** 1012 1013```ts 1014class SourceObject { 1015 name: string 1016 age: number 1017 isVis: boolean 1018 1019 constructor(name: string, age: number, isVis: boolean) { 1020 this.name = name 1021 this.age = age 1022 this.isVis = isVis 1023 } 1024} 1025 1026let source: SourceObject = new SourceObject("jack", 18, false); 1027let g_object: distributedDataObject.DistributedObject = distributedDataObject.createDistributedObject(source); 1028 1029g_object.on("status", (sessionId: string, networkId: string, status: 'online' | 'offline') => { 1030 console.info("status changed " + sessionId + " " + status + " " + networkId); 1031}); 1032``` 1033 1034### off('status')<sup>(deprecated)</sup> 1035 1036off(type: 'status', callback?: (sessionId: string, networkId: string, status: 'online' | 'offline' ) => void): void 1037 1038当不再进行对象上下线监听时，使用此接口删除对象的上下线监听。 1039 1040> **说明：** 1041> 1042> 从 API Version 8 开始支持，从 API Version 9 开始废弃，建议使用[off('status')](#offstatus9)替代。 1043 1044**系统能力：** SystemCapability.DistributedDataManager.DataObject.DistributedObject 1045 1046**参数：** 1047 1048| 参数名 | 类型 | 必填 | 说明 | 1049| -------- | -------- | -------- | -------- | 1050| type | string | 是 | 事件类型，固定为'status'，表示对象上下线。 | 1051| callback | Function | 否 | 需要删除的上下线回调，若不设置则删除该对象所有的上下线回调。<br>sessionId：标识变更对象的sessionId； <br>networkId：标识变更对象； <br>status：标识对象为'online'(上线)或'offline'(下线)的状态。 | 1052 1053 1054**示例：** 1055 1056```ts 1057class SourceObject { 1058 name: string 1059 age: number 1060 isVis: boolean 1061 1062 constructor(name: string, age: number, isVis: boolean) { 1063 this.name = name 1064 this.age = age 1065 this.isVis = isVis 1066 } 1067} 1068 1069let source: SourceObject = new SourceObject("jack", 18, false); 1070let g_object: distributedDataObject.DistributedObject = distributedDataObject.createDistributedObject(source); 1071// 删除上下线回调changeCallback 1072g_object.off("status", (sessionId: string, networkId: string, status: 'online' | 'offline') => { 1073 console.info("status changed " + sessionId + " " + status + " " + networkId); 1074}); 1075// 删除所有的上下线回调 1076g_object.off("status"); 1077```
