未验证 提交 3aa296ba 编写于 作者: O openharmony_ci 提交者: Gitee

!13695 fileapi加入file.fs文档

Merge pull request !13695 from zhuhongtao666/fsdoc
# @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);
}
});
```
此差异已折叠。
# @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);
}
});
```
# @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);
```
# @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);
}
});
```
......@@ -4,7 +4,7 @@
> **说明:**
> 本模块首批接口从API version 6开始支持。后续版本的新增接口,采用上角标单独标记接口的起始版本。
> 本模块自API 9开始废弃,建议使用[@ohos.file.fs](./js-apis-file-fs.md)替代。
## 导入模块
......
......@@ -4,6 +4,7 @@
> **说明:**
> 本模块首批接口从API version 8开始支持。后续版本的新增接口,采用上角标单独标记接口的起始版本。
> 本模块自API 9开始废弃,建议使用[@ohos.file.statvfs](./js-apis-file-statvfs.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);
}
```
Markdown is supported
0% .
You are about to add 0 people to the discussion. Proceed with caution.
先完成此消息的编辑!
想要评论请 注册