diff --git a/zh-cn/application-dev/reference/apis/js-apis-data-distributedobject.md b/zh-cn/application-dev/reference/apis/js-apis-data-distributedobject.md index 5917976c58a5840152786573c551932c20749eb8..79c474b00aa1c9e77c25a6ea710df58815c0069a 100644 --- a/zh-cn/application-dev/reference/apis/js-apis-data-distributedobject.md +++ b/zh-cn/application-dev/reference/apis/js-apis-data-distributedobject.md @@ -13,35 +13,57 @@ import distributedObject from '@ohos.data.distributedDataObject'; ``` -## distributedDataObject.createDistributedObject - -createDistributedObject(source: object): DistributedObject +## distributedObject.create9+ +create(context: Context, source: object): DistributedObjectV9 创建一个分布式数据对象。 -**系统能力：** SystemCapability.DistributedDataManager.DataObject.DistributedObject。 +**系统能力：** SystemCapability.DistributedDataManager.DataObject.DistributedObject **参数：** | 参数名 | 类型 | 必填 | 说明 | | -------- | -------- | -------- | -------- | + | context | Context | 是 | 应用的上下文。
FA模型的应用Context定义见[Context](js-apis-Context.md)。
Stage模型的应用Context定义见[Context](js-apis-ability-context.md)。 | | source | object | 是 | 设置分布式数据对象的属性。 | - + **返回值：** | 类型 | 说明 | | -------- | -------- | -| [DistributedObject](#distributedobject) | 创建完成的分布式数据对象。 | +| [DistributedObjectV9](#distributedobjectv9) | 创建完成的分布式数据对象。 | **示例：** +FA模型示例： + ```js +// 导入模块 import distributedObject from '@ohos.data.distributedDataObject'; -// 创建对象，对象包含4个属性类型，string,number,boolean和Object -var g_object = distributedObject.createDistributedObject({name:"Amy", age:18, isVis:false, parent:{mother:"jack mom",father:"jack Dad"}}); +import featureAbility from '@ohos.ability.featureAbility'; +// 获取context +let context = featureAbility.getContext(); +// 创建对象，该对象包含4个属性类型，string,number,boolean和Object +let g_object = distributedObject.create(context, {name:"Amy", age:18, isVis:false, parent:{mother:"jack mom",father:"jack Dad"}}); ``` +Stage模型示例： + +```ts +// 导入模块 +import distributedObject from '@ohos.data.distributedDataObject'; +import Ability from '@ohos.application.Ability'; +// 获取context +let context; +class MainAbility extends Ability{ + onWindowStageCreate(windowStage){ + context = this.context + } +} +// 创建对象，该对象包含4个属性类型，string,number,boolean和Object +let g_object = distributedObject.create(context, {name:"Amy", age:18, isVis:false, parent:{mother:"jack mom",father:"jack Dad"}}); +``` ## distributedObject.genSessionId @@ -49,7 +71,7 @@ genSessionId(): string 随机创建一个sessionId。 -**系统能力：** SystemCapability.DistributedDataManager.DataObject.DistributedObject。 +**系统能力：** SystemCapability.DistributedDataManager.DataObject.DistributedObject **返回值：** @@ -61,14 +83,14 @@ genSessionId(): string ```js import distributedObject from '@ohos.data.distributedDataObject'; -var sessionId = distributedObject.genSessionId(); +let sessionId = distributedObject.genSessionId(); ``` ## SaveSuccessResponse9+ save接口回调信息。 -**系统能力：** SystemCapability.DistributedDataManager.DataObject.DistributedObject。 +**系统能力：** SystemCapability.DistributedDataManager.DataObject.DistributedObject | 名称 | 类型 | 说明 | | -------- | -------- | -------- | @@ -80,25 +102,150 @@ save接口回调信息。 revokeSave接口回调信息。 -**系统能力：** SystemCapability.DistributedDataManager.DataObject.DistributedObject。 +**系统能力：** SystemCapability.DistributedDataManager.DataObject.DistributedObject | 名称 | 类型 | 说明 | | -------- | -------- | -------- | | sessionId | string | 多设备协同的唯一标识。 | -## DistributedObject +## DistributedObjectV9 表示一个分布式数据对象。 -### setSessionId +### setSessionId9+ -setSessionId(sessionId?: string): boolean +setSessionId(sessionId: string, callback: AsyncCallback<void>): void 设置同步的sessionId，当可信组网中有多个设备时，多个设备间的对象如果设置为同一个sessionId，就能自动同步。 **需要权限：** ohos.permission.DISTRIBUTED_DATASYNC。 -**系统能力：** SystemCapability.DistributedDataManager.DataObject.DistributedObject。 +**系统能力：** SystemCapability.DistributedDataManager.DataObject.DistributedObject + +**参数：** + + | 参数名 | 类型 | 必填 | 说明 | + | -------- | -------- | -------- | -------- | + | sessionId | string | 是 | 分布式数据对象在可信组网中的标识ID。| + | callback | AsyncCallback<void> | 是 | 加入session的异步回调。| + +**错误码：** + + 以下错误码的详细介绍参见[分布式数据对象错误码](../errorcodes/errorcode-distributed-data_object.md)。 + + | 类型 | 说明 | + | -------- | -------- | + | 15400001 | 创建内存数据库失败。| + +**示例：** + +FA模型示例 + +```js +import distributedObject from '@ohos.data.distributedDataObject'; +import featureAbility from '@ohos.ability.featureAbility'; +// 获取context +let context = featureAbility.getContext(); +let g_object = distributedObject.create(context, {name:"Amy", age:18, isVis:false, parent:{mother:"jack mom",father:"jack Dad"}}); +// g_object加入分布式组网 +g_object.setSessionId(distributedObject.genSessionId(), ()=>{ + console.log("join session"); +}); +``` +Stage模型示例 + +```ts +import distributedObject from '@ohos.data.distributedDataObject'; +import Ability from '@ohos.application.Ability'; +// 获取context +let context; +class MainAbility extends Ability{ + onWindowStageCreate(windowStage){ + context = this.context + } +} +let g_object = distributedObject.create(context, {name:"Amy", age:18, isVis:false, parent:{mother:"jack mom",father:"jack Dad"}}); +// g_object加入分布式组网 +g_object.setSessionId(distributedObject.genSessionId(), ()=>{ + console.log("join session"); +}); +``` + +### setSessionId9+ + +setSessionId(callback: AsyncCallback<void>): void + +退出所有已加入的session。 + +**需要权限：** ohos.permission.DISTRIBUTED_DATASYNC。 + +**系统能力：** SystemCapability.DistributedDataManager.DataObject.DistributedObject + +**参数：** + + | 参数名 | 类型 | 必填 | 说明 | + | -------- | -------- | -------- | -------- | + | callback | AsyncCallback<void> | 是 | 退出所有已加入session的异步回调。 | + +**错误码：** + + 以下错误码的详细介绍参见[分布式数据对象错误码](../errorcodes/errorcode-distributed-data_object.md)。 + + | 类型 | 说明 | + | -------- | -------- | + | 15400001 | 创建内存数据库失败。| + +**示例：** + +FA模型示例 + +```js +import distributedObject from '@ohos.data.distributedDataObject'; +import featureAbility from '@ohos.ability.featureAbility'; +// 获取context +let context = featureAbility.getContext(); +let g_object = distributedObject.create(context, {name:"Amy", age:18, isVis:false, parent:{mother:"jack mom",father:"jack Dad"}}); +// g_object加入分布式组网 +g_object.setSessionId(distributedObject.genSessionId(), ()=>{ + console.log("join session"); +}); +// 退出分布式组网 +g_object.setSessionId(() => { + console.log("leave all lession."); +}); +``` +Stage模型示例 + +```ts +import distributedObject from '@ohos.data.distributedDataObject'; +import Ability from '@ohos.application.Ability'; +// 获取context +let context; +class MainAbility extends Ability{ + onWindowStageCreate(windowStage){ + context = this.context + } +} +let g_object = distributedObject.create(context, {name:"Amy", age:18, isVis:false, parent:{mother:"jack mom",father:"jack Dad"}}); +// g_object加入分布式组网 +g_object.setSessionId(distributedObject.genSessionId(), ()=>{ + console.log("join session"); +}); +// 退出分布式组网 +g_object.setSessionId(() => { + console.log("leave all lession."); +}); +``` + +### setSessionId9+ + +setSessionId(sessionId?: string): Promise<void> + +设置同步的sessionId，当可信组网中有多个设备时，多个设备间的对象如果设置为同一个sessionId，就能自动同步。 + +**需要权限：** ohos.permission.DISTRIBUTED_DATASYNC。 + +**系统能力：** SystemCapability.DistributedDataManager.DataObject.DistributedObject **参数：** @@ -108,28 +255,75 @@ setSessionId(sessionId?: string): boolean **返回值：** +| 类型 | 说明 | +| -------- | -------- | +| Promise<void> | Promise对象。| + +**错误码：** + + 以下错误码的详细介绍参见[分布式数据对象错误码](../errorcodes/errorcode-distributed-data_object.md)。 + | 类型 | 说明 | | -------- | -------- | - | boolean | true：标识设置sessionId成功。
false：标识设置sessionId失败。 | + | 15400001 | 创建内存数据库失败。| **示例：** +FA模型示例 + ```js import distributedObject from '@ohos.data.distributedDataObject'; -var g_object = distributedObject.createDistributedObject({name:"Amy", age:18, isVis:false, parent:{mother:"jack mom",father:"jack Dad"}});; +import featureAbility from '@ohos.ability.featureAbility'; +// 获取context +let context = featureAbility.getContext(); +let g_object = distributedObject.create(context, {name:"Amy", age:18, isVis:false, parent:{mother:"jack mom",father:"jack Dad"}}); // g_object加入分布式组网 -g_object.setSessionId(distributedObject.genSessionId()); -// 设置为""退出分布式组网 -g_object.setSessionId(""); +g_object.setSessionId(distributedObject.genSessionId()).then (()=>{ + console.log("join session."); + }).catch((error)=>{ + console.info("error:" + error.code + error.message); +}); +// 退出分布式组网 +g_object.setSessionId().then (()=>{ + console.log("leave all lession."); + }).catch((error)=>{ + console.info("error:" + error.code + error.message); +}); +``` +Stage模型示例 + +```ts +import distributedObject from '@ohos.data.distributedDataObject'; +import Ability from '@ohos.application.Ability'; +// 获取context +let context; +class MainAbility extends Ability{ + onWindowStageCreate(windowStage){ + context = this.context + } +} +let g_object = distributedObject.create(context, {name:"Amy", age:18, isVis:false, parent:{mother:"jack mom",father:"jack Dad"}}); +// 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 (()=>{ + console.log("leave all lession."); + }).catch((error)=>{ + console.info("error:" + error.code + error.message); +}); ``` -### on('change') +### on('change')9+ on(type: 'change', callback: Callback<{ sessionId: string, fields: Array<string> }>): void -监听分布式数据对象的变更。 +监听分布式数据对象的数据变更。 -**系统能力：** SystemCapability.DistributedDataManager.DataObject.DistributedObject。 +**系统能力：** SystemCapability.DistributedDataManager.DataObject.DistributedObject **参数：** @@ -140,9 +334,14 @@ on(type: 'change', callback: Callback<{ sessionId: string, fields: Array<stri **示例：** +FA模型示例 + ```js -import distributedObject from '@ohos.data.distributedDataObject'; -var g_object = distributedObject.createDistributedObject({name:"Amy", age:18, isVis:false, parent:{mother:"jack mom",father:"jack Dad"}}); +import distributedObject from '@ohos.data.distributedDataObject'; +import featureAbility from '@ohos.ability.featureAbility'; +// 获取context +let context = featureAbility.getContext(); +let g_object = distributedObject.create(context, {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) { @@ -154,13 +353,37 @@ globalThis.changeCallback = (sessionId, changeData) => { g_object.on("change", globalThis.changeCallback); ``` -### off('change') +Stage模型示例 + +```ts +import distributedObject from '@ohos.data.distributedDataObject'; +import Ability from '@ohos.application.Ability'; +// 获取context +let context; +class MainAbility extends Ability{ + onWindowStageCreate(windowStage){ + context = this.context + } +} +let g_object = distributedObject.create(context, {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')9+ off(type: 'change', callback?: Callback<{ sessionId: string, fields: Array<string> }>): void 当不再进行数据变更监听时，使用此接口删除对象的变更监听。 -**系统能力：** SystemCapability.DistributedDataManager.DataObject.DistributedObject。 +**系统能力：** SystemCapability.DistributedDataManager.DataObject.DistributedObject **参数：** @@ -172,22 +395,46 @@ off(type: 'change', callback?: Callback<{ sessionId: string, fields: Array<st **示例：** +FA模型示例 + ```js -import distributedObject from '@ohos.data.distributedDataObject'; -var g_object = distributedObject.createDistributedObject({name:"Amy", age:18, isVis:false, parent:{mother:"jack mom",father:"jack Dad"}}); +import distributedObject from '@ohos.data.distributedDataObject'; +import featureAbility from '@ohos.ability.featureAbility'; +// 获取context +let context = featureAbility.getContext(); +let g_object = distributedObject.create(context, {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') +Stage模型示例 + +```ts +import distributedObject from '@ohos.data.distributedDataObject'; +import Ability from '@ohos.application.Ability'; +// 获取context +let context; +class MainAbility extends Ability{ + onWindowStageCreate(windowStage){ + context = this.context + } +} +let g_object = distributedObject.create(context, {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')9+ on(type: 'status', callback: Callback<{ sessionId: string, networkId: string, status: 'online' | 'offline' }>): void 监听分布式数据对象的上下线。 -**系统能力：** SystemCapability.DistributedDataManager.DataObject.DistributedObject。 +**系统能力：** SystemCapability.DistributedDataManager.DataObject.DistributedObject **参数：** @@ -198,22 +445,46 @@ on(type: 'status', callback: Callback<{ sessionId: string, networkId: string, st **示例：** +FA模型示例 + ```js import distributedObject from '@ohos.data.distributedDataObject'; +import featureAbility from '@ohos.ability.featureAbility'; +// 获取context +let context = featureAbility.getContext(); +globalThis.statusCallback = (sessionId, networkId, status) => { + globalThis.response += "status changed " + sessionId + " " + status + " " + networkId; +} +let g_object = distributedObject.create(context, {name:"Amy", age:18, isVis:false, parent:{mother:"jack mom",father:"jack Dad"}}); +g_object.on("status", globalThis.statusCallback); +``` + +Stage模型示例 + +```ts +import distributedObject from '@ohos.data.distributedDataObject'; +import Ability from '@ohos.application.Ability'; +// 获取context +let context; +class MainAbility extends Ability{ + onWindowStageCreate(windowStage){ + context = this.context + } +} globalThis.statusCallback = (sessionId, networkId, status) => { globalThis.response += "status changed " + sessionId + " " + status + " " + networkId; } -var g_object = distributedObject.createDistributedObject({name:"Amy", age:18, isVis:false, parent:{mother:"jack mom",father:"jack Dad"}}); +let g_object = distributedObject.create(context, {name:"Amy", age:18, isVis:false, parent:{mother:"jack mom",father:"jack Dad"}}); g_object.on("status", globalThis.statusCallback); ``` -### off('status') +### off('status')9+ off(type: 'status', callback?: Callback<{ sessionId: string, deviceId: string, status: 'online' | 'offline' }>): void 当不再进行对象上下线监听时，使用此接口删除对象的上下线监听。 -**系统能力：** SystemCapability.DistributedDataManager.DataObject.DistributedObject。 +**系统能力：** SystemCapability.DistributedDataManager.DataObject.DistributedObject **参数：** @@ -225,9 +496,36 @@ off(type: 'status', callback?: Callback<{ sessionId: string, deviceId: string, s **示例：** +FA模型示例 + ```js import distributedObject from '@ohos.data.distributedDataObject'; -var g_object = distributedObject.createDistributedObject({name:"Amy", age:18, isVis:false, parent:{mother:"jack mom",father:"jack Dad"}}); +import featureAbility from '@ohos.ability.featureAbility'; +// 获取context +let context = featureAbility.getContext(); +let g_object = distributedObject.create(context, {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"); +``` + +Stage模型示例 + +```ts +import distributedObject from '@ohos.data.distributedDataObject'; +import Ability from '@ohos.application.Ability'; +// 获取context +let context; +class MainAbility extends Ability{ + onWindowStageCreate(windowStage){ + context = this.context + } +} +let g_object = distributedObject.create(context, {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; } @@ -251,7 +549,7 @@ save(deviceId: string, callback: AsyncCallback<SaveSuccessResponse>): void - 应用卸载。 - 成功恢复数据之后。 -**系统能力：** SystemCapability.DistributedDataManager.DataObject.DistributedObject。 +**系统能力：** SystemCapability.DistributedDataManager.DataObject.DistributedObject **参数：** @@ -264,7 +562,31 @@ save(deviceId: string, callback: AsyncCallback<SaveSuccessResponse>): void ```js import distributedObject from '@ohos.data.distributedDataObject'; -var g_object = distributedObject.createDistributedObject({name:"Amy", age:18, isVis:false}); +import featureAbility from '@ohos.ability.featureAbility'; +// 获取context +let context = featureAbility.getContext(); +let g_object = distributedObject.create(context, {name:"Amy", age:18, isVis:false}); +g_object.setSessionId("123456"); +g_object.save("local", (status, result) => { + console.log("save status = " + status); + console.log("save callback"); + console.info("save sessionId: " + result.sessionId); + console.info("save version: " + result.version); + console.info("save deviceId: " + result.deviceId); +}); +``` + +```js +import distributedObject from '@ohos.data.distributedDataObject'; +import Ability from '@ohos.application.Ability'; +// 获取context +let context; +class MainAbility extends Ability{ + onWindowStageCreate(windowStage){ + context = this.context + } +} +let g_object = distributedObject.create(context, {name:"Amy", age:18, isVis:false}); g_object.setSessionId("123456"); g_object.save("local", (status, result) => { console.log("save status = " + status); @@ -289,7 +611,7 @@ save(deviceId: string): Promise<SaveSuccessResponse> - 应用卸载。 - 成功恢复数据之后。 -**系统能力：** SystemCapability.DistributedDataManager.DataObject.DistributedObject。 +**系统能力：** SystemCapability.DistributedDataManager.DataObject.DistributedObject **参数：** @@ -307,7 +629,32 @@ save(deviceId: string): Promise<SaveSuccessResponse> ```js import distributedObject from '@ohos.data.distributedDataObject'; -var g_object = distributedObject.createDistributedObject({name:"Amy", age:18, isVis:false}); +import featureAbility from '@ohos.ability.featureAbility'; +// 获取context +let context = featureAbility.getContext(); +let g_object = distributedObject.create({name:"Amy", age:18, isVis:false}); +g_object.setSessionId("123456"); +g_object.save("local").then((result) => { + console.log("save callback"); + console.info("save sessionId " + result.sessionId); + console.info("save version " + result.version); + console.info("save deviceId " + result.deviceId); +}, () => { + console.error("save failed"); +}); +``` + +```js +import distributedObject from '@ohos.data.distributedDataObject'; +import Ability from '@ohos.application.Ability'; +// 获取context +let context; +class MainAbility extends Ability{ + onWindowStageCreate(windowStage){ + context = this.context + } +} +let g_object = distributedObject.create({name:"Amy", age:18, isVis:false}); g_object.setSessionId("123456"); g_object.save("local").then((result) => { console.log("save callback"); @@ -328,7 +675,7 @@ revokeSave(callback: AsyncCallback<RevokeSaveSuccessResponse>): void 如果对象保存在本地设备，那么将删除所有受信任设备上所保存的数据。 如果对象保存在其他设备，那么将删除本地设备上的数据。 -**系统能力：** SystemCapability.DistributedDataManager.DataObject.DistributedObject。 +**系统能力：** SystemCapability.DistributedDataManager.DataObject.DistributedObject **参数：** @@ -338,9 +685,38 @@ revokeSave(callback: AsyncCallback<RevokeSaveSuccessResponse>): void **示例：** +FA模型示例 + ```js import distributedObject from '@ohos.data.distributedDataObject'; -var g_object = distributedObject.createDistributedObject({name:"Amy", age:18, isVis:false}); +import featureAbility from '@ohos.ability.featureAbility'; +// 获取context +let context = featureAbility.getContext(); +let g_object = distributedObject.create(context, {name:"Amy", age:18, isVis:false}); +g_object.setSessionId("123456"); +g_object.save("local").then((result) => { + console.log("save callback"); + console.info("save sessionId " + result.sessionId); + console.info("save version " + result.version); + console.info("save deviceId " + result.deviceId); +}, () => { + console.error("save failed"); +}); +``` + +Stage模型示例 + +```ts +import distributedObject from '@ohos.data.distributedDataObject'; +import Ability from '@ohos.application.Ability'; +// 获取context +let context; +class MainAbility extends Ability{ + onWindowStageCreate(windowStage){ + context = this.context + } +} +let g_object = distributedObject.create(context, {name:"Amy", age:18, isVis:false}); g_object.setSessionId("123456"); g_object.revokeSave((result, data) => { console.log("revokeSave callback"); @@ -356,7 +732,7 @@ revokeSave(): Promise<RevokeSaveSuccessResponse> 如果对象保存在本地设备，那么将删除所有受信任设备上所保存的数据。 如果对象保存在其他设备，那么将删除本地设备上的数据。 -**系统能力：** SystemCapability.DistributedDataManager.DataObject.DistributedObject。 +**系统能力：** SystemCapability.DistributedDataManager.DataObject.DistributedObject **返回值：** @@ -366,9 +742,14 @@ revokeSave(): Promise<RevokeSaveSuccessResponse> **示例：** +FA模型示例 + ```js import distributedObject from '@ohos.data.distributedDataObject'; -var g_object = distributedObject.createDistributedObject({name:"Amy", age:18, isVis:false}); +import featureAbility from '@ohos.ability.featureAbility'; +// 获取context +let context = featureAbility.getContext(); +let g_object = distributedObject.create(context, {name:"Amy", age:18, isVis:false}); g_object.setSessionId("123456"); g_object.revokeSave().then((result) => { console.log("revokeSave callback"); @@ -377,3 +758,231 @@ g_object.revokeSave().then((result) => { console.error("revokeSave failed"); }); ``` + +Stage模型示例 + +```ts +import distributedObject from '@ohos.data.distributedDataObject'; +import Ability from '@ohos.application.Ability'; +// 获取context +let context; +class MainAbility extends Ability{ + onWindowStageCreate(windowStage){ + context = this.context + } +} +let g_object = distributedObject.create(context, {name:"Amy", age:18, isVis:false}); +g_object.setSessionId("123456"); +g_object.save("local").then((result) => { + console.log("save callback"); + console.info("save sessionId " + result.sessionId); + console.info("save version " + result.version); + console.info("save deviceId " + result.deviceId); +}, () => { + console.error("save failed"); +}); +``` + +## distributedObject.createDistributedObject(deprecated) + +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(deprecated) + +表示一个分布式数据对象。 + +### setSessionId(deprecated) + +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成功。
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')(deprecated) + +on(type: 'change', callback: Callback<{ sessionId: string, fields: Array<string> }>): void + +监听分布式数据对象的变更。 + +> **说明：** +> +> 从 API Version 8 开始支持，从 API Version 9 开始废弃，建议使用[on('change')](#onchange9)替代。 + +**系统能力：** SystemCapability.DistributedDataManager.DataObject.DistributedObject + +**参数：** + + | 参数名 | 类型 | 必填 | 说明 | + | -------- | -------- | -------- | -------- | + | type | string | 是 | 事件类型，固定为'change'，表示数据变更。 | + | callback | Callback<{ sessionId: string, fields: Array<string> }> | 是 | 变更回调对象实例。
sessionId：标识变更对象的sessionId；
fields：标识对象变更的属性名。 | + +**示例：** + +```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"}}); +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')(deprecated) + +off(type: 'change', callback?: Callback<{ sessionId: string, fields: Array<string> }>): void + +当不再进行数据变更监听时，使用此接口删除对象的变更监听。 + +> **说明：** +> +> 从 API Version 8 开始支持，从 API Version 9 开始废弃，建议使用[off('change')](#offchange9)替代。 + +**系统能力：** SystemCapability.DistributedDataManager.DataObject.DistributedObject + +**参数：** + + | 参数名 | 类型 | 必填 | 说明 | + | -------- | -------- | -------- | -------- | + | type | string | 是 | 事件类型，固定为'change'，表示数据变更。 | + | callback | Callback<{ sessionId: string, fields: Array<string> }> | 否 | 需要删除的数据变更回调，若不设置则删除该对象所有的数据变更回调。
sessionId：标识变更对象的sessionId；
fields：标识对象变更的属性名。 | + + +**示例：** + +```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"}}); +// 删除数据变更回调changeCallback +g_object.off("change", globalThis.changeCallback); +// 删除所有的数据变更回调 +g_object.off("change"); +``` + +### on('status')(deprecated) + +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' }> | 是 | 监听上下线回调实例。
sessionId：标识变更对象的sessionId；
networkId：标识对象设备，即deviceId；
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')(deprecated) + +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' }> | 否 | 需要删除的上下线回调，若不设置则删除该对象所有的上下线回调。
sessionId：标识变更对象的sessionId；
deviceId：标识变更对象的deviceId；
status：标识对象为'online'(上线)或'offline'(下线)的状态。 | + + +**示例：** + +```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"}}); +globalThis.statusCallback = (sessionId, networkId, status) => { + globalThis.response += "status changed " + sessionId + " " + status + " " + networkId; +} +// 删除上下线回调changeCallback +g_object.off("status",globalThis.statusCallback); +// 删除所有的上下线回调 +g_object.off("status"); +``` \ No newline at end of file diff --git a/zh-cn/application-dev/reference/errorcodes/errorcode-distributed-data_object.md b/zh-cn/application-dev/reference/errorcodes/errorcode-distributed-data_object.md new file mode 100644 index 0000000000000000000000000000000000000000..1a48200bf58c284f7ba46b257d00d98d3e506904 --- /dev/null +++ b/zh-cn/application-dev/reference/errorcodes/errorcode-distributed-data_object.md @@ -0,0 +1,19 @@ +# 分布式数据对象错误码 + +## 15400001 创建内存数据库失败 + +**错误信息** + +Create table failed. + +**错误描述** + +创建内存数据库失败。 + +**可能原因** + +已经存在加入相同session的对象。 + +**处理步骤** + +检查是否已经有加入相同session的对象。 \ No newline at end of file