!13695 fileapi加入file.fs文档

Merge pull request !13695 from zhuhongtao666/fsdoc

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

-# @ohos.environment (目录环境能力)
+# @ohos.file.environment (目录环境能力)
 
 该模块提供环境目录能力，获取内存存储根目录、公共文件根目录的JS接口。
 
 > **说明：**
->
-> - 本模块首批接口从API version 8开始支持。后续版本的新增接口，采用上角标单独标记接口的起始版本。
-> - 本模块接口为系统接口，三方应用不支持调用。
+> 本模块首批接口从API version 9开始支持。后续版本的新增接口，采用上角标单独标记接口的起始版本。
+> 本模块接口为系统接口，三方应用不支持调用。
+> 本模块支持对错误码进行处理，错误码及其适配方式[参考文档](../errorcodes/errorcode-filemanagement.md#错误码适配指导)。
 
 ## 导入模块
 
 ```js
-import environment from '@ohos.environment';
+import environment from '@ohos.file.environment';
 ```
 
 ## environment.getStorageDataDir
@@ -30,10 +30,10 @@ getStorageDataDir():Promise<string>
 **示例：**
 
   ```js
-  environment.getStorageDataDir().then(function(path){
-      console.info("getStorageDataDir successfully:"+ path);
-  }).catch(function(error){
-      console.info("getStorageDataDir failed with error:"+ error);
+  environment.getStorageDataDir().then(function (path) {
+      console.info("getStorageDataDir successfully, Path: " + path);
+  }).catch(function (err) {
+      console.info("getStorageDataDir failed with error message: " + err.message + ", error code: " + err.code);
   });
   ```
 
@@ -54,8 +54,12 @@ getStorageDataDir(callback:AsyncCallback<string>):void
 **示例：**
 
   ```js
-  environment.getStorageDataDir(function(error, path){
-      // do something
+  environment.getStorageDataDir(function (error, path) {
+    if (err) {
+      console.info("getStorageDataDir failed with error message: " + err.message + ", error code: " + err.code);
+    } else {
+      console.info("getStorageDataDir successfully, Path: " + path);
+    }
   });
   ```
 
@@ -76,10 +80,10 @@ getUserDataDir():Promise<string>
 **示例：**
 
   ```js
-  environment.getUserDataDir().then(function(path){
-      console.info("getUserDataDir successfully:"+ path);
-  }).catch(function(error){
-      console.info("getUserDataDir failed with error:"+ error);
+  environment.getUserDataDir().then(function (path) {
+    console.info("getUserDataDir successfully, Path: " + path);
+  }).catch(function (err) {
+    console.info("getUserDataDir failed with error message: " + err.message + ", error code: " + err.code);
   });
   ```
 
@@ -100,8 +104,11 @@ getUserDataDir(callback:AsyncCallback<string>): void
 **示例：**
 
   ```js
-  environment.getUserDataDir(function(error, path){
-      // do something
+  environment.getUserDataDir(function (err, path) {
+    if (err) {
+      console.info("getUserDataDir failed with error message: " + err.message + ", error code: " + err.code);
+    } else {
+      console.info("getUserDataDir successfully, Path: " + path);
+    }
   });
   ```
-

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

+# @ohos.file.hash (文件哈希处理)
+
+该模块提供文件哈希处理能力，对文件内容进行哈希处理。
+
+> **说明：**
+> 本模块首批接口从API version 9开始支持。后续版本的新增接口，采用上角标单独标记接口的起始版本。
+> 本模块支持对错误码进行处理，错误码及其适配方式[参考文档](../errorcodes/errorcode-filemanagement.md#错误码适配指导)。
+
+## 导入模块
+
+```js
+import Hash from '@ohos.file.hash';
+```
+
+## 使用说明
+
+使用该功能模块对文件/目录进行操作前，需要先获取其应用沙箱路径，获取方式及其接口用法请参考：
+
+**Stage模型**
+
+ ```js
+import UIAbility from '@ohos.app.ability.UIAbility';
+
+export default class EntryAbility extends UIAbility {
+    onWindowStageCreate(windowStage) {
+        let context = this.context;
+        let pathDir = context.filesDir;
+    }
+}
+ ```
+
+**FA模型**
+
+ ```js
+ import featureAbility from '@ohos.ability.featureAbility';
+ 
+ let context = featureAbility.getContext();
+ context.getFilesDir().then((data) => {
+      let pathDir = data;
+ })
+ ```
+
+FA模型context的具体获取方法参见[FA模型](js-apis-inner-app-context.md#Context模块)。
+
+## Hash.hash
+
+hash(path: string, algorithm: string): Promise<string>
+
+计算文件的哈希值，使用Promise异步回调。
+
+**系统能力**：SystemCapability.FileManagement.File.FileIO
+
+**参数：**
+
+| 参数名    | 类型   | 必填 | 说明                                                         |
+| --------- | ------ | ---- | ------------------------------------------------------------ |
+| path      | string | 是   | 待计算哈希值文件的应用沙箱路径。                             |
+| algorithm | string | 是   | 哈希计算采用的算法。可选 "md5"、"sha1" 或 "sha256"。建议采用安全强度更高的 "sha256"。 |
+
+**返回值：**
+
+  | 类型                    | 说明                         |
+  | --------------------- | -------------------------- |
+  | Promise<string> | Promise对象。返回文件的哈希值。表示为十六进制数字串，所有字母均大写。 |
+
+**示例：**
+
+  ```js
+  let filePath = pathDir + "/test.txt";
+  Hash.hash(filePath, "sha256").then(function (str) {
+    console.info("calculate file hash succeed:" + str);
+  }).catch(function (err) {
+    console.info("calculate file hash failed with error message: " + err.message + ", error code: " + err.code);
+  });
+  ```
+
+## Hash.hash
+
+hash(path: string, algorithm: string, callback: AsyncCallback<string>): void
+
+计算文件的哈希值，使用callback异步回调。
+
+**系统能力**：SystemCapability.FileManagement.File.FileIO
+
+**参数：**
+
+| 参数名    | 类型                        | 必填 | 说明                                                         |
+| --------- | --------------------------- | ---- | ------------------------------------------------------------ |
+| path      | string                      | 是   | 待计算哈希值文件的应用沙箱路径。                             |
+| algorithm | string                      | 是   | 哈希计算采用的算法。可选 "md5"、"sha1" 或 "sha256"。建议采用安全强度更高的 "sha256"。 |
+| callback  | AsyncCallback<string> | 是   | 异步计算文件哈希操作之后的回调函数（其中给定文件哈希值表示为十六进制数字串，所有字母均大写）。 |
+
+**示例：**
+  ```js
+  Hash.hash(filePath, "sha256", function (err, str) {
+    if (err) {
+      console.info("calculate file hash failed with error message: " + err.message + ", error code: " + err.code);
+    } else {
+      console.info("calculate file hash succeed:" + str);
+    }
+  });
+  ```

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

-# @ohos.securityLabel (数据标签)
+# @ohos.file.securityLabel (数据标签)
 
 该模块提供文件数据安全等级的相关功能：向应用程序提供查询、设置文件数据安全等级的JS接口。
 
 > **说明：**
 > 本模块首批接口从API version 9开始支持。后续版本的新增接口，采用上角标单独标记接口的起始版本。
+> 本模块支持对错误码进行处理，错误码及其适配方式[参考文档](../errorcodes/errorcode-filemanagement.md#错误码适配指导)。
 
 ## 导入模块
 
 ```js
-import securityLabel from '@ohos.securityLabel';
+import securityLabel from '@ohos.file.securityLabel';
 ```
 
 ## 使用说明
 
 使用该功能模块对文件/目录进行操作前，需要先获取其应用沙箱路径，获取方式及其接口用法请参考：
 
-```js
-import featureAbility from '@ohos.ability.featureAbility';
-let context = featureAbility.getContext();
-let path = '';
-context.getFilesDir().then((data) => {
-    path = data;
-})
-```
+**Stage模型**
+
+ ```js
+import UIAbility from '@ohos.app.ability.UIAbility';
+
+export default class EntryAbility extends UIAbility {
+    onWindowStageCreate(windowStage) {
+        let context = this.context;
+        let pathDir = context.filesDir;
+    }
+}
+ ```
+
+**FA模型**
+
+ ```js
+ import featureAbility from '@ohos.ability.featureAbility';
+ 
+ let context = featureAbility.getContext();
+ context.getFilesDir().then((data) => {
+      let pathDir = data;
+ })
+ ```
+
+FA模型context的具体获取方法参见[FA模型](js-apis-inner-app-context.md#Context模块)。
 
 ## securityLabel.setSecurityLabel
 
@@ -48,10 +66,10 @@ setSecurityLabel(path:string, type:dataLevel):Promise<void>
 **示例：**
 
   ```js
-  securityLabel.setSecurityLabel(path, "s0").then(function(){
+  securityLabel.setSecurityLabel(path, "s0").then(function () {
       console.info("setSecurityLabel successfully");
-  }).catch(function(error){
-      console.info("setSecurityLabel failed with error:" + error);
+  }).catch(function (err) {
+      console.info("setSecurityLabel failed with error message: " + err.message + ", error code: " + err.code);
   });
   ```
 
@@ -74,10 +92,15 @@ setSecurityLabel(path:string, type:dataLevel, callback: AsyncCallback<void&gt
 **示例：**
 
   ```js
-  securityLabel.setSecurityLabel(path, "s0", function(error){
-      console.info("setSecurityLabel:" + JSON.stringify(error));
+  securityLabel.setSecurityLabel(path, "s0", function (err) {
+    if (err) {
+      console.info("setSecurityLabel failed with error message: " + err.message + ", error code: " + err.code);
+    } else {
+      console.info("setSecurityLabel successfully.");
+    }
   });
   ```
+
 ## securityLabel.setSecurityLabelSync
 
 setSecurityLabelSync(path:string, type:dataLevel):void
@@ -122,10 +145,10 @@ getSecurityLabel(path:string):Promise<string>
 **示例：**
 
   ```js
-  securityLabel.getSecurityLabel(path).then(function(type){
-      console.log("getSecurityLabel successfully:" + type);
-  }).catch(function(err){
-      console.log("getSecurityLabel failed with error:" + err);
+  securityLabel.getSecurityLabel(path).then(function (type) {
+      console.log("getSecurityLabel successfully, Label: " + type);
+  }).catch(function (err) {
+      console.log("getSecurityLabel failed with error message: " + err.message + ", error code: " + err.code);
   });
   ```
 
@@ -147,8 +170,12 @@ getSecurityLabel(path:string, callback:AsyncCallback<string>): void
 **示例：**
 
   ```js
-  securityLabel.getSecurityLabel(path, function(err, type){
-      console.log("getSecurityLabel successfully:" + type);
+  securityLabel.getSecurityLabel(path, function (err, type) {
+    if (err) {
+      console.log("getSecurityLabel failed with error message: " + err.message + ", error code: " + err.code);
+    } else {
+      console.log("getSecurityLabel successfully, Label: " + type);
+    }
   });
   ```
 ## securityLabel.getSecurityLabelSync
@@ -174,6 +201,6 @@ getSecurityLabelSync(path:string):string
 **示例：**
 
 ```js
-let result = securityLabel.getSecurityLabelSync(path);
-console.log("getSecurityLabel successfully:" + result);
+let type = securityLabel.getSecurityLabelSync(path);
+console.log("getSecurityLabel successfully, Label: " + type);
 ```

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

+# @ohos.file.statvfs (文件系统空间统计)
+
+该模块提供文件系统相关存储信息的功能，向应用程序提供获取文件系统总字节数、空闲字节数的JS接口。
+
+> **说明：**
+> 本模块首批接口从API version 9开始支持。后续版本的新增接口，采用上角标单独标记接口的起始版本。
+> 本模块支持对错误码进行处理，错误码及其适配方式[参考文档](../errorcodes/errorcode-filemanagement.md#错误码适配指导)。
+
+## 导入模块
+
+```js
+import statvfs from '@ohos.file.statvfs';
+```
+## statvfs.getFreeSize
+
+getFreeSize(path:string):Promise<number>
+
+异步方法获取指定文件系统空闲字节数，以Promise形式返回结果。
+
+**系统能力**：SystemCapability.FileManagement.File.FileIO
+
+**参数：**
+
+  | 参数名 | 类型   | 必填 | 说明                         |
+  | ------ | ------ | ---- | ---------------------------- |
+  | path   | string | 是   | 需要查询的文件系统的文件路径 |
+
+**返回值：**
+
+  | 类型                  | 说明           |
+  | --------------------- | -------------- |
+  | Promise<number> | 返回空闲字节数 |
+
+**示例：**
+
+  ```js
+  let path = "/dev";
+  statfs.getFreeSize(path).then(function (number) {
+    console.info("getFreeSize promise successfully, Size: " + number);
+  }).catch(function (err) {
+    console.info("getFreeSize failed with error message: " + err.message + ", error code: " + err.code);
+  });
+  ```
+
+## statfs.getFreeSize
+
+getFreeSize(path:string, callback:AsyncCallback<number>): void
+
+异步方法获取指定文件系统空闲字节数，使用callback形式返回结果。
+
+**系统能力**：SystemCapability.FileManagement.File.FileIO
+
+**参数：**
+
+  | 参数名   | 类型                        | 必填 | 说明                         |
+  | -------- | --------------------------- | ---- | ---------------------------- |
+  | path     | string                      | 是   | 需要查询的文件系统的文件路径 |
+  | callback | AsyncCallback<number> | 是   | 异步获取空闲字节数之后的回调 |
+
+**示例：**
+
+  ```js
+  let path = "/dev";
+  statfs.getFreeSize(path, function (err, number) {
+    if (err) {
+      console.info("getFreeSize failed with error message: " + err.message + ", error code: " + err.code);
+    } else {
+      console.info("getFreeSize callback successfully, Size: " + number);
+    }
+  });
+  ```
+
+## statfs.getTotalSize
+
+getTotalSize(path: string): Promise<number>
+
+异步方法获取指定文件系统总字节数，以Promise形式返回结果。
+
+**系统能力**：SystemCapability.FileManagement.File.FileIO
+
+**参数：**
+
+  | 参数名 | 类型   | 必填 | 说明                         |
+  | ---- | ------ | ---- | ---------------------------- |
+  | path | string | 是   | 需要查询的文件系统的文件路径 |
+
+**返回值：**
+
+  | 类型                  | 说明         |
+  | --------------------- | ------------ |
+  | Promise<number> | 返回总字节数 |
+
+**示例：**
+
+  ```js
+  let path = "/dev";
+  statfs.getTotalSize(path).then(function (number) {
+    console.info("getTotalSize promise successfully, Size: " + number);
+  }).catch(function (err) {
+    console.info("getTotalSize with error message: " + err.message + ", error code: " + err.code);
+  });
+  ```
+
+## statfs.getTotalSize
+
+getTotalSize(path: string, callback: AsyncCallback<number>): void
+
+异步方法获取指定文件系统总字节数，使用callback形式返回结果。
+
+**系统能力**：SystemCapability.FileManagement.File.FileIO
+
+**参数：**
+
+  | 参数名   | 类型                        | 必填 | 说明                         |
+  | -------- | --------------------------- | ---- | ---------------------------- |
+  | path     | string                      | 是   | 需要查询的文件系统的文件路径 |
+  | callback | AsyncCallback<number> | 是   | 异步获取总字节数之后的回调   |
+
+**示例：**
+
+  ```js
+  let path = "/dev";
+  statfs.getTotalSize(path, function(err, number) {
+    if (err) {
+      console.info("getTotalSize with error message: " + err.message + ", error code: " + err.code);
+    } else {
+      console.info("getTotalSize promise successfully, Size: " + number);
+    }
+  });
+  ```
+

zh-cn/application-dev/reference/apis/js-apis-fileio.md

@@ -4,7 +4,7 @@
 
 > **说明：**
 > 本模块首批接口从API version 6开始支持。后续版本的新增接口，采用上角标单独标记接口的起始版本。
-
+> 本模块自API 9开始废弃，建议使用[@ohos.file.fs](./js-apis-file-fs.md)替代。
 
 ## 导入模块
 

zh-cn/application-dev/reference/apis/js-apis-statfs.md

@@ -4,6 +4,7 @@
 
 > **说明：**
 > 本模块首批接口从API version 8开始支持。后续版本的新增接口，采用上角标单独标记接口的起始版本。
+> 本模块自API 9开始废弃，建议使用[@ohos.file.statvfs](./js-apis-file-statvfs.md)替代。
 
 ## 导入模块
 

zh-cn/application-dev/reference/errorcodes/errorcode-filemanagement.md

@@ -714,3 +714,41 @@ Fail to notify agent
 
 **处理步骤**
 检查client是否异常
+
+## 错误码适配指导
+文件管理子系统API支持异常处理。
+同步接口异常处理示例代码:
+```js
+import fs from '@ohos.file.fs'
+
+try {
+    let file = fs.openSync(path, fs.OpenMode.READ_ONLY);
+} catch (err) {
+    console.error("openSync errCode:" + err.code + ", errMessage:" + err.message);
+}
+```
+异步接口promise方法异常处理示例代码:
+```js
+import fs from '@ohos.file.fs'
+
+try {
+    let file = await fs.open(path, fs.OpenMode.READ_ONLY);
+} catch (err) {
+    console.error("open promise errCode:" + err.code + ", errMessage:" + err.message);
+}
+```
+
+异步接口callback方法异常处理示例代码:
+```js
+import fs from '@ohos.file.fs'
+
+try {
+    fs.open(path, fs.OpenMode.READ_ONLY, function(e, file){ //异步线程的错误（如系统调用等）在回调中获取
+        if (e) {
+            console.error("open in async errCode:" + e.code + ", errMessage:" + e.message);
+        }
+    });
+} catch (err) { //主线程的错误（如非法参数等）通过try catch获取
+    console.error("open callback errCode:" + err.code + ", errMessage:" + err.message);
+}
+```