!5067 新增save和revokeSave接口说明

Merge pull request !5067 from wangxiyue/cherry-pick-1654603513

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&lt;SaveSuccessResponse&gt; | 保存数据对象。 |
+| DistributedDataObject| revokeSave(): Promise&lt;RevokeSaveSuccessResponse&gt; | 撤回已保存的数据对象。 |
 
 ## 开发步骤
 
@@ -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");
+       // 保存数据对象
+       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");
+       });
+
        ```
-11. 退出同步组网。分布式对象退出组网后，本地的数据变更对端不会同步。
+12. 退出同步组网。分布式对象退出组网后，本地的数据变更对端不会同步。
 
      以下为退出同步组网的代码示例：
        ```js

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成功； <br>false：标识设置sessionId失败。 |
+  | boolean | true：标识设置sessionId成功。 <br>false：标识设置sessionId失败。 |
 
 **示例：**
 
@@ -146,9 +167,6 @@ off(type: 'change', callback?: Callback<{ sessionId: string, fields: Array&lt;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' }> | 是 | 监听上下线回调实例。<br>sessionId：标识变更对象的sessionId； <br>networkId：标识对象设备的networkId； <br>status：标识对象为'online'(上线)或'offline'(下线)的状态。 |
+  | callback | Callback<{ sessionId: string, networkId: string, status: 'online' \| 'offline' }> | 是 | 监听上下线回调实例。<br>sessionId：标识变更对象的sessionId； <br>networkId：标识对象设备，即deviceId； <br>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&lt;SaveSuccessResponse&gt;): void
+
+保存分布式数据对象。使用callback方式异步回调。
+
+对象数据保存成功后，当应用存在时不会释放对象数据，当应用退出后，重新进入应用时，恢复保存在设备上的数据。
+
+有以下几种情况时，保存的数据将会被释放：
+
+- 存储时间超过24小时。
+- 应用卸载。
+- 成功恢复数据之后。
+
+**系统能力：** SystemCapability.DistributedDataManager.DataObject.DistributedObject。
+
+**参数：**
+  | 参数名 | 类型 | 必填 | 说明 |
+  | -------- | -------- | -------- | -------- |
+  | deviceId | string | 是 | 保存数据的deviceId，当deviceId为"local"，代表存储在本地设备。 |
+  | callback | AsyncCallback&lt;[SaveSuccessResponse](#savesuccessresponse)&gt; | 是 | 回调函数。返回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&lt;SaveSuccessResponse&gt;
+
+保存分布式数据对象。使用Promise方式作为异步回调。
+
+对象数据保存成功后，当应用存在时不会释放对象数据，当应用退出后，重新进入应用时，恢复保存在设备上的数据。
+
+有以下几种情况时，保存的数据将会被释放：
+
+- 存储时间超过24小时。
+- 应用卸载。
+- 成功恢复数据之后。
+
+**系统能力：** SystemCapability.DistributedDataManager.DataObject.DistributedObject。
+
+**参数：**
+  | 参数名 | 类型 | 必填 | 说明 |
+  | -------- | -------- | -------- | -------- |
+  | deviceId | string | 是 | 保存数据的设备号，当deviceId默认为"local"，标识需要保存对象的设备。 |
+
+  **返回值：**
+
+  | 类型 | 说明 |
+  | -------- | -------- |
+  | Promise&lt;[SaveSuccessResponse](#savesuccessresponse)&gt; | 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&lt;SaveSuccessResponse&gt;): void
+
+撤回保存的分布式数据对象。使用callback方式作为异步方法。
+
+如果对象保存在本地设备，那么将删除所有受信任设备上所保存的数据。
+如果对象保存在其他设备，那么将删除本地设备上的数据。
+
+**系统能力：** SystemCapability.DistributedDataManager.DataObject.DistributedObject。
+
+**参数：**
+  | 参数名 | 类型 | 必填 | 说明 |
+  | -------- | -------- | -------- | -------- |
+  | callback | AsyncCallback&lt;[RevokeSaveSuccessResponse](#revokesavesuccessresponse)&gt; | 否 | 回调函数。返回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&lt;SaveSuccessResponse&gt;
+
+撤回保存的分布式数据对象。使用Promise方式作为异步方法。
+
+如果对象保存在本地设备，那么将删除所有受信任设备上所保存的数据。
+如果对象保存在其他设备，那么将删除本地设备上的数据。
+
+**系统能力：** SystemCapability.DistributedDataManager.DataObject.DistributedObject。
+
+  **返回值：**
+
+  | 类型 | 说明 |
+  | -------- | -------- |
+  | Promise&lt;[RevokeSaveSuccessResponse](#revokesavesuccessresponse)&gt; | 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");
+  });
+  ```