From 1098bc2565210cc6d1bb8b2e09f966d7e5025293 Mon Sep 17 00:00:00 2001 From: wangxiyue Date: Mon, 6 Jun 2022 17:46:20 +0800 Subject: [PATCH] =?UTF-8?q?=E6=B7=BB=E5=8A=A0save=E5=92=8CrevokeSave?= =?UTF-8?q?=E6=8E=A5=E5=8F=A3=E8=AF=B4=E6=98=8E=E5=92=8C=E7=A4=BA=E4=BE=8B?= =?UTF-8?q?=E4=BB=A3=E7=A0=81?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Signed-off-by: wangxiyue --- .../database-distributedobject-guidelines.md | 61 ++++++- .../apis/js-apis-data-distributedobject.md | 172 +++++++++++++++++- 2 files changed, 214 insertions(+), 19 deletions(-) diff --git a/zh-cn/application-dev/database/database-distributedobject-guidelines.md b/zh-cn/application-dev/database/database-distributedobject-guidelines.md index c633b70535..6b97b3e1de 100644 --- a/zh-cn/application-dev/database/database-distributedobject-guidelines.md +++ b/zh-cn/application-dev/database/database-distributedobject-guidelines.md @@ -24,7 +24,7 @@ **表2** 分布式数据对象sessionId创建接口 | 包名 | 接口名 | 描述 | | -------- | -------- | -------- | -| ohos.data.distributedDataObject| genSessionId(): string | 创建一个sessionId，可作为分布式数据对象的sessionId | +| ohos.data.distributedDataObject| genSessionId(): string | 创建一个sessionId，可作为分布式数据对象的sessionId。 | ### 设置分布式数据对象sessionId @@ -55,7 +55,23 @@ | DistributedDataObject| on(type: 'status', callback: Callback<{ sessionId: string, networkId: string, status: 'online' \| 'offline' }>): void | 订阅数据对象上下线。 | | DistributedDataObject| off(type: 'status', callback?: Callback<{ sessionId: string, deviceId: string, status: 'online' \| 'offline' }>): void | 注销订阅。 | +### 保存和撤回已保存的数据对象 +保存数据对象：数据对象保存成功后，当应用存在时不会释放对象数据；当应用退出后，重新进入应用时，恢复保存在设备上的数据。 + +撤回保存的数据对象：如果该对象保存在本地设备，那么将删除所有受信任设备上所保存的数据；如果对象保存在其他设备，那么将删除本地设备上的数据。 + +有以下几种情况时，保存的数据将会被释放： + +- 存储时间超过24小时。 +- 应用卸载。 +- 成功恢复数据之后。 + +**表6** 分布式数据对象保存和撤回保存接口 +| 类名 | 接口名 | 描述 | +| -------- | -------- | -------- | +| DistributedDataObject | save(deviceId: string): Promise<SaveSuccessResponse> | 保存数据对象。 | +| DistributedDataObject| revokeSave(): Promise<RevokeSaveSuccessResponse> | 撤回已保存的数据对象。 | ## 开发步骤 @@ -183,16 +199,41 @@ local_object.on("status", this.statusCallback); ``` -10. 删除监听分布式对象的上下线。可以指定删除监听的上下线回调；也可以不指定，这将会删除该分布式数据对象的所有上下线回调。 - + +10. 保存和撤回已保存的数据对象。 + ```js + // 保存数据对象 + local_object.save("local", (result, data)=>{ + console.log("save callback"); + console.info("save sessionId " + data.sessionId); + console.info("save version " + data.version); + console.info("save deviceId " + data.deviceId); + }); + // 撤回保存的数据对象 + local_object.revokeSave((result, data) =>{ + console.log("revokeSave callback"); + console.info("revokeSave sessionId " + data.sessionId); + }); + ``` +11. 删除监听分布式对象的上下线。可以指定删除监听的上下线回调；也可以不指定，这将会删除该分布式数据对象的所有上下线回调。 + 以下为取消监听数据变更的代码示例： - ```js - //删除上下线回调statusCallback - local_object.off("status", statusCallback); - //删除所有的上下线回调 - local_object.off("status"); - ``` -11. 退出同步组网。分布式对象退出组网后，本地的数据变更对端不会同步。 + ```js + // 保存数据对象 + g_object.save("local", (result)=>{ + console.log("save callback"); + console.info("save sessionId " + result.sessionId); + console.info("save version " + result.version); + console.info("save deviceId " + result.deviceId); + }); + + // 撤回保存的数据对象 + g_object.revokeSave((result, data) =>{ + console.log("revokeSave callback"); + }); + + ``` +12. 退出同步组网。分布式对象退出组网后，本地的数据变更对端不会同步。 以下为退出同步组网的代码示例： ```js 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 ecf0cf125a..ef5567d3e2 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 @@ -57,6 +57,27 @@ genSessionId(): string var sessionId = distributedObject.genSessionId(); ``` +## SaveSuccessResponse + +save接口回调信息。 + +**系统能力：** SystemCapability.DistributedDataManager.DataObject.DistributedObject。 + +| 名称 | 类型 | 说明 | +| -------- | -------- | -------- | +| sessionId | string | 多设备协同的唯一标识。 | +| version | number |已保存对象的版本。 | +| deviceId | string | 存储数据的设备号，标识需要保存对象的设备。默认为"local"，标识本地设备；可自定义设置其他标识设备的字符串。 | + +## RevokeSaveSuccessResponse + +revokeSave接口回调信息。 + +**系统能力：** SystemCapability.DistributedDataManager.DataObject.DistributedObject。 + +| 名称 | 类型 | 说明 | +| -------- | -------- | -------- | +| sessionId | string | 多设备协同的唯一标识。 | ## DistributedObject @@ -68,7 +89,7 @@ setSessionId(sessionId?: string): boolean 设置同步的sessionId，当可信组网中有多个设备时，多个设备间的对象如果设置为同一个sessionId，就能自动同步。 -**需要权限：** ohos.permission.DISTRIBUTED_DATASYNC +**需要权限：** ohos.permission.DISTRIBUTED_DATASYNC。 **系统能力：** SystemCapability.DistributedDataManager.DataObject.DistributedObject。 @@ -82,7 +103,7 @@ setSessionId(sessionId?: string): boolean | 类型 | 说明 | | -------- | -------- | - | boolean | true：标识设置sessionId成功；
false：标识设置sessionId失败。 | + | boolean | true：标识设置sessionId成功。
false：标识设置sessionId失败。 | **示例：** @@ -146,9 +167,6 @@ off(type: 'change', callback?: Callback<{ sessionId: string, fields: Array<st import distributedObject from '@ohos.data.distributedDataObject'; var g_object = distributedObject.createDistributedObject({name:"Amy", age:18, isVis:false, parent:{mother:"jack mom",father:"jack Dad"}}); - g_object.on("change", function (sessionId, changeData) { - console.info("change" + sessionId); - }); //删除数据变更回调changeCallback g_object.off("change", function (sessionId, changeData) { console.info("change" + sessionId); @@ -169,7 +187,7 @@ on(type: 'status', callback: Callback<{ sessionId: string, networkId: string, st | 参数名 | 类型 | 必填 | 说明 | | -------- | -------- | -------- | -------- | | type | string | 是 | 事件类型，固定为'status'，表示对象上下线。 | - | callback | Callback<{ sessionId: string, networkId: string, status: 'online' \| 'offline' }> | 是 | 监听上下线回调实例。
sessionId：标识变更对象的sessionId；
networkId：标识对象设备的networkId；
status：标识对象为'online'(上线)或'offline'(下线)的状态。 | + | callback | Callback<{ sessionId: string, networkId: string, status: 'online' \| 'offline' }> | 是 | 监听上下线回调实例。
sessionId：标识变更对象的sessionId；
networkId：标识对象设备，即deviceId；
status：标识对象为'online'(上线)或'offline'(下线)的状态。 | **示例：** ```js @@ -200,9 +218,6 @@ off(type: 'status', callback?: Callback<{ sessionId: string, deviceId: string, s **示例：** ```js import distributedObject from '@ohos.data.distributedDataObject'; - g_object.on("status", function (sessionId, networkId, status) { - this.response += "status changed " + sessionId + " " + status + " " + networkId; - }); //删除上下线回调changeCallback g_object.off("status", function (sessionId, networkId, status) { this.response += "status changed " + sessionId + " " + status + " " + networkId; @@ -210,3 +225,142 @@ off(type: 'status', callback?: Callback<{ sessionId: string, deviceId: string, s //删除所有的上下线回调 g_object.off("status"); ``` + +### save + +save(deviceId: string, callback: AsyncCallback<SaveSuccessResponse>): void + +保存分布式数据对象。使用callback方式异步回调。 + +对象数据保存成功后，当应用存在时不会释放对象数据，当应用退出后，重新进入应用时，恢复保存在设备上的数据。 + +有以下几种情况时，保存的数据将会被释放： + +- 存储时间超过24小时。 +- 应用卸载。 +- 成功恢复数据之后。 + +**系统能力：** SystemCapability.DistributedDataManager.DataObject.DistributedObject。 + +**参数：** + | 参数名 | 类型 | 必填 | 说明 | + | -------- | -------- | -------- | -------- | + | deviceId | string | 是 | 保存数据的deviceId，当deviceId为"local"，代表存储在本地设备。 | + | callback | AsyncCallback<[SaveSuccessResponse](#savesuccessresponse)> | 是 | 回调函数。返回SaveSuccessResponse，包含sessionId、version、deviceId等信息。 | + +**示例：** + + ```js + import distributedObject from '@ohos.data.distributedDataObject'; + var g_object = distributedObject.createDistributedObject({name:"Amy", age:18, isVis:false}); + g_object.setSessionId("123456"); + g_object.save("local", (result)=>{ + console.log("save callback"); + console.info("save sessionId " + result.sessionId); + console.info("save version " + result.version); + console.info("save deviceId " + result.deviceId); + }); + + ``` + +### save + +save(deviceId: string): Promise<SaveSuccessResponse> + +保存分布式数据对象。使用Promise方式作为异步回调。 + +对象数据保存成功后，当应用存在时不会释放对象数据，当应用退出后，重新进入应用时，恢复保存在设备上的数据。 + +有以下几种情况时，保存的数据将会被释放： + +- 存储时间超过24小时。 +- 应用卸载。 +- 成功恢复数据之后。 + +**系统能力：** SystemCapability.DistributedDataManager.DataObject.DistributedObject。 + +**参数：** + | 参数名 | 类型 | 必填 | 说明 | + | -------- | -------- | -------- | -------- | + | deviceId | string | 是 | 保存数据的设备号，当deviceId默认为"local"，标识需要保存对象的设备。 | + + **返回值：** + + | 类型 | 说明 | + | -------- | -------- | + | Promise<[SaveSuccessResponse](#savesuccessresponse)> | Promise对象。返回SaveSuccessResponse，包含sessionId、version、deviceId等信息。| + +**示例：** + + ```js + import distributedObject from '@ohos.data.distributedDataObject'; + var g_object = distributedObject.createDistributedObject({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"); + }); + + ``` + +### revokeSave + +revokeSave(callback: AsyncCallback<SaveSuccessResponse>): void + +撤回保存的分布式数据对象。使用callback方式作为异步方法。 + +如果对象保存在本地设备，那么将删除所有受信任设备上所保存的数据。 +如果对象保存在其他设备，那么将删除本地设备上的数据。 + +**系统能力：** SystemCapability.DistributedDataManager.DataObject.DistributedObject。 + +**参数：** + | 参数名 | 类型 | 必填 | 说明 | + | -------- | -------- | -------- | -------- | + | callback | AsyncCallback<[RevokeSaveSuccessResponse](#revokesavesuccessresponse)> | 否 | 回调函数。返回RevokeSaveSuccessResponse，包含sessionId。 | + +**示例：** + + ```js + import distributedObject from '@ohos.data.distributedDataObject'; + var g_object = distributedObject.createDistributedObject({name:"Amy", age:18, isVis:false}); + g_object.setSessionId("123456"); + g_object.revokeSave((result, data) =>{ + console.log("revokeSave callback"); + }); + ``` + +### revokeSave + +revokeSave(): Promise<SaveSuccessResponse> + +撤回保存的分布式数据对象。使用Promise方式作为异步方法。 + +如果对象保存在本地设备，那么将删除所有受信任设备上所保存的数据。 +如果对象保存在其他设备，那么将删除本地设备上的数据。 + +**系统能力：** SystemCapability.DistributedDataManager.DataObject.DistributedObject。 + + **返回值：** + + | 类型 | 说明 | + | -------- | -------- | + | Promise<[RevokeSaveSuccessResponse](#revokesavesuccessresponse)> | Promise对象。返回RevokeSaveSuccessResponse，包含sessionId。 | + +**示例：** + + ```js + import distributedObject from '@ohos.data.distributedDataObject'; + var g_object = distributedObject.createDistributedObject({name:"Amy", age:18, isVis:false}); + g_object.setSessionId("123456"); + g_object.revokeSave("local").then((result)=>{ + console.log("revokeSave callback"); + console.log("sessionId" + result.sessionId); + }, ()=>{ + console.error("revokeSave failed"); + }); + ``` -- GitLab