!18425 备份恢复接口说明文档说明调整

Merge pull request !18425 from 花轻似梦/master

zh-cn/application-dev/reference/apis/js-apis-file-backup.md

@@ -20,7 +20,7 @@ import backup from '@ohos.file.backup';
 **系统能力**：SystemCapability.FileManagement.StorageService.Backup
 
 | 名称       | 类型   | 必填 | 说明                                                                                           |
-| ---------- | ------ | ---- | ------------------------- |
+| ---------- | ------ | ---- | ---------------------------------------------------------------------------------------------- |
 | bundleName | string | 是   | 应用名称，可通过[bundle.BundleInfo](js-apis-bundle-BundleInfo.md)提供的获取方式获取。          |
 | uri        | string | 是   | 应用沙箱内待传输文件的名称，当前uri尚未升级为标准格式，仅接受0-9a-zA-Z下划线(_)点(.)组成的名称 |
 
@@ -70,8 +70,9 @@ onFileReady : AsyncCallback<File>
 **错误码：**
 
 以下错误码的详细介绍请参见[文件管理子系统错误码](../errorcodes/errorcode-filemanagement.md)。
+
 | 错误码ID | 错误信息                |
-| ---------------------------- | ---------- |
+| -------- | ----------------------- |
 | 13600001 | IPC error               |
 | 13900005 | I/O error               |
 | 13900011 | Out of memory           |
@@ -103,8 +104,9 @@ onBundleBegin : AsyncCallback<string>
 **错误码：**
 
 以下错误码的详细介绍请参见[文件管理子系统错误码](../errorcodes/errorcode-filemanagement.md)。
+
 | 错误码ID | 错误信息                |
-| ---------------------------- | ---------- |
+| -------- | ----------------------- |
 | 13600001 | IPC error               |
 | 13900005 | I/O error               |
 | 13900011 | Out of memory           |
@@ -134,8 +136,9 @@ onBundleEnd : AsyncCallback<string>
 **错误码：**
 
 以下错误码的详细介绍请参见[文件管理子系统错误码](../errorcodes/errorcode-filemanagement.md)。
+
 | 错误码ID | 错误信息                |
-| ---------------------------- | ---------- |
+| -------- | ----------------------- |
 | 13600001 | IPC error               |
 | 13900005 | I/O error               |
 | 13900011 | Out of memory           |
@@ -165,8 +168,9 @@ onAllBundlesEnd : AsyncCallback<undefined>
 **错误码：**
 
 以下错误码的详细介绍请参见[文件管理子系统错误码](../errorcodes/errorcode-filemanagement.md)。
+
 | 错误码ID | 错误信息                |
-| ---------------------------- | ---------- |
+| -------- | ----------------------- |
 | 13600001 | IPC error               |
 | 13900005 | I/O error               |
 | 13900011 | Out of memory           |
@@ -214,14 +218,15 @@ getLocalCapabilities(callback: AsyncCallback<FileData>): void
 **参数：**
 
 | 参数名   | 类型                                       | 必填 | 说明                                                   |
-| -------- | ------------------------- | ---- | --------------------- |
+| -------- | ------------------------------------------ | ---- | ------------------------------------------------------ |
 | callback | AsyncCallback<[FileData](#filedata)> | 是   | 回调函数。当获取成功，err为undefined，否则为错误对象。 |
 
 **错误码：**
 
 以下错误码的详细介绍请参见[文件管理子系统错误码](../errorcodes/errorcode-filemanagement.md)。
+
 | 错误码ID | 错误信息                |
-| ---------------------------- | ---------- |
+| -------- | ----------------------- |
 | 13600001 | IPC error               |
 | 13900005 | I/O error               |
 | 13900011 | Out of memory           |
@@ -276,14 +281,15 @@ getLocalCapabilities(): Promise<FileData>
 **返回值：**
 
 | 类型                                 | 说明                                                |
-| -------------------- | ------------------ |
+| ------------------------------------ | --------------------------------------------------- |
 | Promise<[FileData](#filedata)> | Promise对象，返回描述本地能力的Json文件的FileData。 |
 
 **错误码：**
 
 以下错误码的详细介绍请参见[文件管理子系统错误码](../errorcodes/errorcode-filemanagement.md)。
+
 | 错误码ID | 错误信息                |
-| ---------------------------- | ---------- |
+| -------- | ----------------------- |
 | 13600001 | IPC error               |
 | 13900005 | I/O error               |
 | 13900011 | Out of memory           |
@@ -294,6 +300,7 @@ getLocalCapabilities(): Promise<FileData>
 
   ```js
   import fs from '@ohos.file.fs';
+  async function getLocalCapabilities() {
     try {
       let fileData = await backup.getLocalCapabilities();
       console.info('getLocalCapabilities success');
@@ -301,6 +308,7 @@ getLocalCapabilities(): Promise<FileData>
     } catch (err) {
       console.error('getLocalCapabilities failed with err: ' + err);
     }
+  }
   ```
 
   **返回的能力文件内容示例：**
@@ -345,7 +353,7 @@ constructor(callbacks: GeneralCallbacks);
 
   ```js
   import fs from '@ohos.file.fs';
-  let sessionBackup = new backup.SessionBackup({
+  let generalCallbacks = backup.GeneralCallbacks({
     onFileReady: (err, file) => {
       if (err) {
         console.error('onFileReady failed with err: ' + err);
@@ -375,6 +383,7 @@ constructor(callbacks: GeneralCallbacks);
       console.info('service died');
     }
   });
+  let sessionBackup = new backup.SessionBackup(generalCallbacks);
   ```
 
 ### appendBundles
@@ -397,8 +406,9 @@ appendBundles(bundlesToBackup: string[], callback: AsyncCallback<void>): v
 **错误码：**
 
 以下错误码的详细介绍请参见[文件管理子系统错误码](../errorcodes/errorcode-filemanagement.md)。
+
 | 错误码ID | 错误信息                |
-| ---------------------------- | ---------- |
+| -------- | ----------------------- |
 | 13600001 | IPC error               |
 | 13900001 | Operation not permitted |
 | 13900005 | I/O error               |
@@ -409,7 +419,39 @@ appendBundles(bundlesToBackup: string[], callback: AsyncCallback<void>): v
 
 **示例：**
 
+
   ```js
+  import fs from '@ohos.file.fs';
+  let sessionBackup = new backup.SessionBackup({
+    onFileReady: (err, file) => {
+      if (err) {
+        console.error('onFileReady failed with err: ' + err);
+      }
+      console.info('onFileReady success');
+      fs.closeSync(file.fd);
+    },
+    onBundleBegin: (err, bundleName) => {
+      if (err) {
+        console.error('onBundleBegin failed with err: ' + err);
+      }
+      console.info('onBundleBegin success');
+    },
+    onBundleEnd: (err, bundleName) => {
+      if (err) {
+        console.error('onBundleEnd failed with err: ' + err);
+      }
+      console.info('onBundleEnd success');
+    },
+    onAllBundlesEnd: (err) => {
+      if (err) {
+        console.error('onAllBundlesEnd failed with err: ' + err);
+      }
+      console.info('onAllBundlesEnd success');
+    },
+    onBackupServiceDied: () => {
+      console.info('service died');
+    }
+  });
   try {
     sessionBackup.appendBundles(['com.example.hiworld'], (err) => {
       if (err) {
@@ -447,8 +489,9 @@ appendBundles(bundlesToBackup: string[]): Promise<void>
 **错误码：**
 
 以下错误码的详细介绍请参见[文件管理子系统错误码](../errorcodes/errorcode-filemanagement.md)。
+
 | 错误码ID | 错误信息                |
-| ---------------------------- | ---------- |
+| -------- | ----------------------- |
 | 13600001 | IPC error               |
 | 13900001 | Operation not permitted |
 | 13900005 | I/O error               |
@@ -460,12 +503,45 @@ appendBundles(bundlesToBackup: string[]): Promise<void>
 **示例：**
 
   ```js
+  import fs from '@ohos.file.fs';
+  let sessionBackup = new backup.SessionBackup({
+    onFileReady: (err, file) => {
+      if (err) {
+        console.error('onFileReady failed with err: ' + err);
+      }
+      console.info('onFileReady success');
+      fs.closeSync(file.fd);
+    },
+    onBundleBegin: (err, bundleName) => {
+      if (err) {
+        console.error('onBundleBegin failed with err: ' + err);
+      }
+      console.info('onBundleBegin success');
+    },
+    onBundleEnd: (err, bundleName) => {
+      if (err) {
+        console.error('onBundleEnd failed with err: ' + err);
+      }
+      console.info('onBundleEnd success');
+    },
+    onAllBundlesEnd: (err) => {
+      if (err) {
+        console.error('onAllBundlesEnd failed with err: ' + err);
+      }
+      console.info('onAllBundlesEnd success');
+    },
+    onBackupServiceDied: () => {
+      console.info('service died');
+    }
+  });
+  async function appendBundles() {
     try {
       await sessionBackup.appendBundles(['com.example.hiworld']);
       console.info('appendBundles success');
     } catch (err) {
     console.error('appendBundles failed with err: ' + err);
     }
+  }
   ```
 
 ## SessionRestore
@@ -492,7 +568,7 @@ constructor(callbacks: GeneralCallbacks);
 
   ```js
   import fs from '@ohos.file.fs';
-  let sessionRestore = new backup.SessionRestore({
+  let generalCallbacks = backup.GeneralCallbacks({
     onFileReady: (err, file) => {
       if (err) {
         console.error('onFileReady failed with err: ' + err);
@@ -518,10 +594,11 @@ constructor(callbacks: GeneralCallbacks);
       }
       console.info('onAllBundlesEnd success');
     },
-    onRestoreServiceDied: () => {
+    onBackupServiceDied: () => {
       console.info('service died');
     }
   });
+  let sessionRestore = new backup.SessionRestore(generalCallbacks);
   ```
 
 ### appendBundles
@@ -550,8 +627,9 @@ appendBundles(remoteCapabilitiesFd: number, bundlesToBackup: string[], callback:
 **错误码：**
 
 以下错误码的详细介绍请参见[文件管理子系统错误码](../errorcodes/errorcode-filemanagement.md)。
+
 | 错误码ID | 错误信息                |
-| ---------------------------- | ---------- |
+| -------- | ----------------------- |
 | 13600001 | IPC error               |
 | 13900001 | Operation not permitted |
 | 13900005 | I/O error               |
@@ -563,6 +641,38 @@ appendBundles(remoteCapabilitiesFd: number, bundlesToBackup: string[], callback:
 **示例：**
 
   ```js
+  import fs from '@ohos.file.fs';
+  let sessionRestore = new backup.SessionRestore({
+    onFileReady: (err, file) => {
+      if (err) {
+        console.error('onFileReady failed with err: ' + err);
+      }
+      console.info('onFileReady success');
+      fs.closeSync(file.fd);
+    },
+    onBundleBegin: (err, bundleName) => {
+      if (err) {
+        console.error('onBundleBegin failed with err: ' + err);
+      }
+      console.info('onBundleBegin success');
+    },
+    onBundleEnd: (err, bundleName) => {
+      if (err) {
+        console.error('onBundleEnd failed with err: ' + err);
+      }
+      console.info('onBundleEnd success');
+    },
+    onAllBundlesEnd: (err) => {
+      if (err) {
+        console.error('onAllBundlesEnd failed with err: ' + err);
+      }
+      console.info('onAllBundlesEnd success');
+    },
+    onBackupServiceDied: () => {
+      console.info('service died');
+    }
+  });
+  async function appendBundles() {
     try {
       let fileData = await backup.getLocalCapabilities();
       console.info('getLocalCapabilities success');
@@ -573,7 +683,8 @@ appendBundles(remoteCapabilitiesFd: number, bundlesToBackup: string[], callback:
       console.info('appendBundles success');
     });
     } catch (err) {
-    console.error('appendBundles failed with err: ' + err);
+      console.error('getLocalCapabilities failed with err: ' + err);
+    }
   }
   ```
 
@@ -608,8 +719,9 @@ appendBundles(remoteCapabilitiesFd: number, bundlesToBackup: string[]): Promise&
 **错误码：**
 
 以下错误码的详细介绍请参见[文件管理子系统错误码](../errorcodes/errorcode-filemanagement.md)。
+
 | 错误码ID | 错误信息                |
-| ---------------------------- | ---------- |
+| -------- | ----------------------- |
 | 13600001 | IPC error               |
 | 13900001 | Operation not permitted |
 | 13900005 | I/O error               |
@@ -621,13 +733,46 @@ appendBundles(remoteCapabilitiesFd: number, bundlesToBackup: string[]): Promise&
 **示例：**
 
   ```js
+  import fs from '@ohos.file.fs';
+  let sessionRestore = new backup.SessionRestore({
+    onFileReady: (err, file) => {
+      if (err) {
+        console.error('onFileReady failed with err: ' + err);
+      }
+      console.info('onFileReady success');
+      fs.closeSync(file.fd);
+    },
+    onBundleBegin: (err, bundleName) => {
+      if (err) {
+        console.error('onBundleBegin failed with err: ' + err);
+      }
+      console.info('onBundleBegin success');
+    },
+    onBundleEnd: (err, bundleName) => {
+      if (err) {
+        console.error('onBundleEnd failed with err: ' + err);
+      }
+      console.info('onBundleEnd success');
+    },
+    onAllBundlesEnd: (err) => {
+      if (err) {
+        console.error('onAllBundlesEnd failed with err: ' + err);
+      }
+      console.info('onAllBundlesEnd success');
+    },
+    onBackupServiceDied: () => {
+      console.info('service died');
+    }
+  });
+  async function appendBundles() {
     try {
       let fileData = await backup.getLocalCapabilities();
       console.info('getLocalCapabilities success');
       await sessionRestore.appendBundles(fileData.fd, ['com.example.hiworld']);
       console.info('appendBundles success');
     } catch (err) {
-    console.error('appendBundles failed with err: ' + err);
+      console.error('getLocalCapabilities failed with err: ' + err);
+    }
   }
   ```
 
@@ -658,8 +803,9 @@ getFileHandle(fileMeta: FileMeta, callback: AsyncCallback<void>): void
 **错误码：**
 
 以下错误码的详细介绍请参见[文件管理子系统错误码](../errorcodes/errorcode-filemanagement.md)。
+
 | 错误码ID | 错误信息                |
-| ---------------------------- | ---------- |
+| -------- | ----------------------- |
 | 13600001 | IPC error               |
 | 13900001 | Operation not permitted |
 | 13900020 | Invalid argument        |
@@ -668,7 +814,37 @@ getFileHandle(fileMeta: FileMeta, callback: AsyncCallback<void>): void
 **示例：**
 
   ```js
-  try {
+  import fs from '@ohos.file.fs';
+  let sessionRestore = new backup.SessionRestore({
+    onFileReady: (err, file) => {
+      if (err) {
+        console.error('onFileReady failed with err: ' + err);
+      }
+      console.info('onFileReady success');
+      fs.closeSync(file.fd);
+    },
+    onBundleBegin: (err, bundleName) => {
+      if (err) {
+        console.error('onBundleBegin failed with err: ' + err);
+      }
+      console.info('onBundleBegin success');
+    },
+    onBundleEnd: (err, bundleName) => {
+      if (err) {
+        console.error('onBundleEnd failed with err: ' + err);
+      }
+      console.info('onBundleEnd success');
+    },
+    onAllBundlesEnd: (err) => {
+      if (err) {
+        console.error('onAllBundlesEnd failed with err: ' + err);
+      }
+      console.info('onAllBundlesEnd success');
+    },
+    onBackupServiceDied: () => {
+      console.info('service died');
+    }
+  });
   sessionRestore.getFileHandle({
       bundleName: "com.example.hiworld",
       uri: "test.txt"
@@ -678,9 +854,6 @@ getFileHandle(fileMeta: FileMeta, callback: AsyncCallback<void>): void
       }
       console.info('getFileHandle success');
     });
-  } catch (err) {
-    console.error('getFileHandle failed with err: ' + err);
-  }
   ```
 
 ### getFileHandle
@@ -715,8 +888,9 @@ getFileHandle(fileMeta: FileMeta): Promise<void>
 **错误码：**
 
 以下错误码的详细介绍请参见[文件管理子系统错误码](../errorcodes/errorcode-filemanagement.md)。
+
 | 错误码ID | 错误信息                |
-| ---------------------------- | ---------- |
+| -------- | ----------------------- |
 | 13600001 | IPC error               |
 | 13900001 | Operation not permitted |
 | 13900020 | Invalid argument        |
@@ -725,6 +899,38 @@ getFileHandle(fileMeta: FileMeta): Promise<void>
 **示例：**
 
   ```js
+  import fs from '@ohos.file.fs';
+  let sessionRestore = new backup.SessionRestore({
+    onFileReady: (err, file) => {
+      if (err) {
+        console.error('onFileReady failed with err: ' + err);
+      }
+      console.info('onFileReady success');
+      fs.closeSync(file.fd);
+    },
+    onBundleBegin: (err, bundleName) => {
+      if (err) {
+        console.error('onBundleBegin failed with err: ' + err);
+      }
+      console.info('onBundleBegin success');
+    },
+    onBundleEnd: (err, bundleName) => {
+      if (err) {
+        console.error('onBundleEnd failed with err: ' + err);
+      }
+      console.info('onBundleEnd success');
+    },
+    onAllBundlesEnd: (err) => {
+      if (err) {
+        console.error('onAllBundlesEnd failed with err: ' + err);
+      }
+      console.info('onAllBundlesEnd success');
+    },
+    onBackupServiceDied: () => {
+      console.info('service died');
+    }
+  });
+  async function getFileHandle() {
     try {
       await sessionRestore.getFileHandle({
         bundleName: "com.example.hiworld",
@@ -734,6 +940,7 @@ getFileHandle(fileMeta: FileMeta): Promise<void>
     } catch (err) {
       console.error('getFileHandle failed with err: ' + err);
     }
+  }
   ```
 
 ### publishFile
@@ -762,8 +969,9 @@ publishFile(fileMeta: FileMeta, callback: AsyncCallback<void>): void
 **错误码：**
 
 以下错误码的详细介绍请参见[文件管理子系统错误码](../errorcodes/errorcode-filemanagement.md)。
+
 | 错误码ID | 错误信息                |
-| ---------------------------- | ---------- |
+| -------- | ----------------------- |
 | 13600001 | IPC error               |
 | 13900001 | Operation not permitted |
 | 13900020 | Invalid argument        |
@@ -772,14 +980,17 @@ publishFile(fileMeta: FileMeta, callback: AsyncCallback<void>): void
 **示例：**
 
   ```js
-  try {
+  import fs from '@ohos.file.fs';
+  let g_session;
+  function createSessionRestore() {
+    let sessionRestore = new backup.SessionRestore({
       onFileReady: (err, file) => {
         if (err) {
           console.error('onFileReady failed with err: ' + err);
         }
         console.info('onFileReady success');
         fs.closeSync(file.fd);
-      sessionRestore.publishFile({
+        g_session.publishFile({
           bundleName: file.bundleName,
           uri: file.uri
         }, (err) => {
@@ -788,10 +999,32 @@ publishFile(fileMeta: FileMeta, callback: AsyncCallback<void>): void
           }
           console.info('publishFile success');
         });
+      },
+      onBundleBegin: (err, bundleName) => {
+        if (err) {
+          console.error('onBundleBegin failed with err: ' + err);
         }
-  } catch (err) {
-    console.error('publishFile failed with err: ' + err);
+        console.info('onBundleBegin success');
+      },
+      onBundleEnd: (err, bundleName) => {
+        if (err) {
+          console.error('onBundleEnd failed with err: ' + err);
         }
+        console.info('onBundleEnd success');
+      },
+      onAllBundlesEnd: (err) => {
+        if (err) {
+          console.error('onAllBundlesEnd failed with err: ' + err);
+        }
+        console.info('onAllBundlesEnd success');
+      },
+      onBackupServiceDied: () => {
+        console.info('service died');
+      }
+    });
+    return sessionRestore;
+  }
+  g_session = createSessionRestore();
   ```
 
 ### publishFile
@@ -825,8 +1058,9 @@ publishFile(fileMeta: FileMeta): Promise<void>
 **错误码：**
 
 以下错误码的详细介绍请参见[文件管理子系统错误码](../errorcodes/errorcode-filemanagement.md)。
+
 | 错误码ID | 错误信息                |
-| ---------------------------- | ---------- |
+| -------- | ----------------------- |
 | 13600001 | IPC error               |
 | 13900001 | Operation not permitted |
 | 13900020 | Invalid argument        |
@@ -835,20 +1069,49 @@ publishFile(fileMeta: FileMeta): Promise<void>
 **示例：**
 
   ```js
-  try {
+  import fs from '@ohos.file.fs';
+  let g_session;
+  async function publishFile(file)
+  {
+    await g_session.publishFile({
+      bundleName: file.bundleName,
+      uri: file.uri
+    });
+  }
+  function createSessionRestore() {
+    let sessionRestore = new backup.SessionRestore({
       onFileReady: (err, file) => {
         if (err) {
           console.error('onFileReady failed with err: ' + err);
         }
         console.info('onFileReady success');
         fs.closeSync(file.fd);
-      await sessionRestore.publishFile({
-      bundleName: file.bundleName,
-      uri: file.uri
-      });
+        publishFile(file);
         console.info('publishFile success');
       },
-  } catch (err) {
-    console.error('publishFile failed with err: ' + err);
+      onBundleBegin: (err, bundleName) => {
+        if (err) {
+          console.error('onBundleBegin failed with err: ' + err);
+        }
+        console.info('onBundleBegin success');
+      },
+      onBundleEnd: (err, bundleName) => {
+        if (err) {
+          console.error('onBundleEnd failed with err: ' + err);
+        }
+        console.info('onBundleEnd success');
+      },
+      onAllBundlesEnd: (err) => {
+        if (err) {
+          console.error('onAllBundlesEnd failed with err: ' + err);
+        }
+        console.info('onAllBundlesEnd success');
+      },
+      onBackupServiceDied: () => {
+        console.info('service died');
+      }
+    });
+    return sessionRestore;
   }
+  g_session = createSessionRestore();
   ```