diff --git a/zh-cn/application-dev/reference/apis/js-apis-environment.md b/zh-cn/application-dev/reference/apis/js-apis-file-environment.md similarity index 58% rename from zh-cn/application-dev/reference/apis/js-apis-environment.md rename to zh-cn/application-dev/reference/apis/js-apis-file-environment.md index e7e5e6ce6dfd165faae96c5a55d94872a5e1f869..a3d891cf5660e8ece94b572669be80dd6f54a049 100644 --- a/zh-cn/application-dev/reference/apis/js-apis-environment.md +++ b/zh-cn/application-dev/reference/apis/js-apis-file-environment.md @@ -1,16 +1,16 @@ -# @ohos.environment (目录环境能力) +# @ohos.file.environment (目录环境能力) 该模块提供环境目录能力，获取内存存储根目录、公共文件根目录的JS接口。 -> ![icon-note.gif](public_sys-resources/icon-note.gif) **说明：** -> -> - 本模块首批接口从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); + } }); ``` - diff --git a/zh-cn/application-dev/reference/apis/js-apis-file-fs.md b/zh-cn/application-dev/reference/apis/js-apis-file-fs.md new file mode 100644 index 0000000000000000000000000000000000000000..9bd9554fba0d41cf9435a628691c30051efcee98 --- /dev/null +++ b/zh-cn/application-dev/reference/apis/js-apis-file-fs.md @@ -0,0 +1,2374 @@ +# @ohos.file.fs (文件管理) + +该模块为基础文件操作API，提供基础文件操作能力，包括文件基本管理、文件目录管理、文件信息统计、文件流式读写等常用功能。 + +> **说明：** +> 本模块首批接口从API version 9开始支持。后续版本的新增接口，采用上角标单独标记接口的起始版本。 +> 本模块支持对错误码进行处理，错误码及其适配方式[参考文档](../errorcodes/errorcode-filemanagement.md#错误码适配指导)。 + +## 导入模块 + +```js +import fs from '@ohos.file.fs'; +``` + +## 使用说明 + +使用该功能模块对文件/目录进行操作前，需要先获取其应用沙箱路径，获取方式及其接口用法请参考： + +**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模块)。 + +## fs.stat + +stat(file: string|number): Promise<Stat> + +获取文件信息，使用Promise异步回调。 + +**系统能力**：SystemCapability.FileManagement.File.FileIO + +**参数：** + +| 参数名 | 类型 | 必填 | 说明 | +| ------ | ------ | ---- | -------------------------- | +| file | string\|number | 是 | 文件应用沙箱路径path或已打开的文件描述符fd。 | + +**返回值：** + + | 类型 | 说明 | + | ---------------------------- | ---------- | + | Promise<[Stat](#stat)> | Promise对象。返回文件的具体信息。 | + +**示例：** + + ```js + let filePath = pathDir + "test.txt"; + fs.stat(filePath).then(function (stat) { + console.info("get file info succeed, the size of file is " + stat.size); + }).catch(function (err) { + console.info("get file info failed with error message: " + err.message + ", error code: " + err.code); + }); + ``` + +## fs.stat + +stat(file: string|number, callback: AsyncCallback<Stat>): void + +获取文件信息，使用callback异步回调。 + +**系统能力**：SystemCapability.FileManagement.File.FileIO + +**参数：** + +| 参数名 | 类型 | 必填 | 说明 | +| -------- | ---------------------------------- | ---- | ------------------------------ | +| file | string\|number | 是 | 文件应用沙箱路径path或已打开的文件描述符fd。 | +| callback | AsyncCallback<[Stat](#stat)> | 是 | 异步获取文件的信息之后的回调。 | + +**示例：** + + ```js + fs.stat(pathDir, function (err, stat) { + if (err) { + console.info("get file info failed with error message: " + err.message + ", error code: " + err.code); + } else { + console.info("get file info succeed, the size of file is " + stat.size); + } + }); + ``` + +## fs.statSync + +statSync(file: string|number): Stat + +以同步方法获取文件的信息。 + +**系统能力**：SystemCapability.FileManagement.File.FileIO + +**参数：** + +| 参数名 | 类型 | 必填 | 说明 | +| ------ | ------ | ---- | -------------------------- | +| file | string\|number | 是 | 文件应用沙箱路径path或已打开的文件描述符fd。 | + + +**返回值：** + + | 类型 | 说明 | + | ------------- | ---------- | + | [Stat](#stat) | 表示文件的具体信息。 | + +**示例：** + + ```js + let stat = fs.statSync(pathDir); + console.info("get file info succeed, the size of file is " + stat.size); + ``` + +## fs.access + +access(path: string): Promise<boolean> + +检查文件是否存在，使用Promise异步回调。 + +**系统能力**：SystemCapability.FileManagement.File.FileIO + +**参数：** + +| 参数名 | 类型 | 必填 | 说明 | +| ------ | ------ | ---- | ------------------------------------------------------------ | +| path | string | 是 | 文件应用沙箱路径。 | + +**返回值：** + + | 类型 | 说明 | + | ------------------- | ---------------------------- | + | Promise<boolean> | Promise对象。返回boolean。 | + +**示例：** + + ```js + let filePath = pathDir + "/test.txt"; + fs.access(filePath).then(function (res) { + if (res) { + console.info("file exists"); + } + }).catch(function (err) { + console.info("access failed with error message: " + err.message + ", error code: " + err.code); + }); + ``` + + +## fs.access + +access(path: string, callback: AsyncCallback<boolean>): void + +检查文件是否存在，使用callback异步回调。 + +**系统能力**：SystemCapability.FileManagement.File.FileIO + +**参数：** + +| 参数名 | 类型 | 必填 | 说明 | +| -------- | ------------------------- | ---- | ------------------------------------------------------------ | +| path | string | 是 | 文件应用沙箱路径。 | +| callback | AsyncCallback<boolean> | 是 | 异步检查文件是否存在的回调。 | + +**示例：** + + ```js + let filePath = pathDir + "/test.txt"; + fs.access(filePath, function (err, res) { + if (err) { + console.info("access failed with error message: " + err.message + ", error code: " + err.code); + } else { + if (res) { + console.info("file exists"); + } + } + }); + ``` + +## fs.accessSync + +accessSync(path: string): boolean + +以同步方法检查文件是否存在。 + +**系统能力**：SystemCapability.FileManagement.File.FileIO + +**参数：** + +| 参数名 | 类型 | 必填 | 说明 | +| ------ | ------ | ---- | ------------------------------------------------------------ | +| path | string | 是 | 文件应用沙箱路径。 | + +**示例：** + + ```js + let filePath = pathDir + "/test.txt"; + try { + let res = fs.accessSync(filePath); + if (res) { + console.info("file exists"); + } + } catch(err) { + console.info("accessSync failed with error message: " + err.message + ", error code: " + err.code); + } + ``` + + +## fs.close + +close(file: File|number): Promise<void> + +关闭文件，使用Promise异步回调。 + +**系统能力**：SystemCapability.FileManagement.File.FileIO + +**参数：** + + | 参数名 | 类型 | 必填 | 说明 | + | ---- | ------ | ---- | ------------ | + | file | [File](#file)\|number | 是 | 已打开的File对象或已打开的文件描述符fd。 | + +**返回值：** + + | 类型 | 说明 | + | ------------------- | ---------------------------- | + | Promise<void> | Promise对象。无返回值。 | + +**示例：** + + ```js + let filePath = pathDir + "/test.txt"; + let file = fs.openSync(filePath); + fs.close(file).then(function () { + console.info("close file succeed"); + fs.closeSync(file); + }).catch(function (err) { + console.info("close file failed with error message: " + err.message + ", error code: " + err.code); + }); + ``` + +## fs.close + +close(file: File|number, callback: AsyncCallback<void>): void + +关闭文件，使用callback异步回调。 + +**系统能力**：SystemCapability.FileManagement.File.FileIO + +**参数：** + + | 参数名 | 类型 | 必填 | 说明 | + | -------- | ------------------------- | ---- | ------------ | + | file | [File](#file)\|number | 是 | 已打开的File对象或已打开的文件描述符fd。 | + | callback | AsyncCallback<void> | 是 | 异步关闭文件之后的回调。 | + +**示例：** + + ```js + let filePath = pathDir + "/test.txt"; + let file = fs.openSync(filePath); + fs.close(file, function (err) { + if (err) { + console.info("close file failed with error message: " + err.message + ", error code: " + err.code); + } else { + console.info("close file success"); + } + }); + ``` + +## fs.closeSync + +closeSync(file: File|number): void + +以同步方法关闭文件。 + +**系统能力**：SystemCapability.FileManagement.File.FileIO + +**参数：** + + | 参数名 | 类型 | 必填 | 说明 | + | ---- | ------ | ---- | ------------ | + | file | [File](#file)\|number | 是 | 已打开的File对象或已打开的文件描述符fd。 | + +**示例：** + + ```js + let filePath = pathDir + "/test.txt"; + let file = fs.openSync(filePath); + fs.closeSync(file); + ``` + + +## fs.copyFile + +copyFile(src: string|number, dest: string|number, mode?: number): Promise<void> + +复制文件，使用Promise异步回调。 + +**系统能力**：SystemCapability.FileManagement.File.FileIO + +**参数：** + + | 参数名 | 类型 | 必填 | 说明 | + | ---- | -------------------------- | ---- | ---------------------------------------- | + | src | string\|number | 是 | 待复制文件的路径或待复制文件的文件描述符。 | + | dest | string\|number | 是 | 目标文件路径或目标文件的文件描述符。 | + | mode | number | 否 | mode提供覆盖文件的选项，当前仅支持0，且默认为0。
0：完全覆盖目标文件。 | + +**返回值：** + + | 类型 | 说明 | + | ------------------- | ---------------------------- | + | Promise<void> | Promise对象。无返回值。 | + +**示例：** + + ```js + let srcPath = pathDir + "srcDir/test.txt"; + let dstPath = pathDir + "dstDir/test.txt"; + fs.copyFile(srcPath, dstPath).then(function () { + console.info("copy file succeed"); + }).catch(function (err) { + console.info("copy file failed with error message: " + err.message + ", error code: " + err.code); + }); + ``` + +## fs.copyFile + +copyFile(src: string|number, dest: string|number, mode?: number, callback: AsyncCallback<void>): void + +复制文件，使用callback异步回调。 + +**系统能力**：SystemCapability.FileManagement.File.FileIO + +**参数：** + + | 参数名 | 类型 | 必填 | 说明 | + | -------- | -------------------------- | ---- | ---------------------------------------- | + | src | string\|number | 是 | 待复制文件的路径或待复制文件的文件描述符。 | + | dest | string\|number | 是 | 目标文件路径或目标文件的文件描述符。 | + | mode | number | 否 | mode提供覆盖文件的选项，当前仅支持0，且默认为0。
0：完全覆盖目标文件，未覆盖部分将被裁切掉。 | + | callback | AsyncCallback<void> | 是 | 异步复制文件之后的回调。 | + +**示例：** + + ```js + let srcPath = pathDir + "srcDir/test.txt"; + let dstPath = pathDir + "dstDir/test.txt"; + fs.copyFile(srcPath, dstPath, function (err) { + if (err) { + console.info("copy file failed with error message: " + err.message + ", error code: " + err.code); + } else { + console.info("copy file success"); + } + }); + ``` + + +## fs.copyFileSync + +copyFileSync(src: string|number, dest: string|number, mode?: number): void + +以同步方法复制文件。 + +**系统能力**：SystemCapability.FileManagement.File.FileIO + +**参数：** + + | 参数名 | 类型 | 必填 | 说明 | + | ---- | -------------------------- | ---- | ---------------------------------------- | + | src | string\|number | 是 | 待复制文件的路径或待复制文件的文件描述符。 | + | dest | string\|number | 是 | 目标文件路径或目标文件的文件描述符。 | + | mode | number | 否 | mode提供覆盖文件的选项，当前仅支持0，且默认为0。
0：完全覆盖目标文件，未覆盖部分将被裁切掉。 | + +**示例：** + + ```js + let srcPath = pathDir + "srcDir/test.txt"; + let dstPath = pathDir + "dstDir/test.txt"; + fs.copyFileSync(srcPath, dstPath); + ``` + + +## fs.mkdir + +mkdir(path: string): Promise<void> + +创建目录，使用Promise异步回调。 + +**系统能力**：SystemCapability.FileManagement.File.FileIO + +**参数：** + +| 参数名 | 类型 | 必填 | 说明 | +| ------ | ------ | ---- | ------------------------------------------------------------ | +| path | string | 是 | 目录的应用沙箱路径。 | + +**返回值：** + + | 类型 | 说明 | + | ------------------- | ---------------------------- | + | Promise<void> | Promise对象。无返回值。 | + +**示例：** + + ```js + let dirPath = pathDir + '/testDir'; + fs.mkdir(dirPath).then(function () { + console.info("mkdir succeed"); + }).catch(function (err) { + console.info("mkdir failed with error message: " + err.message + ", error code: " + err.code); + }); + ``` + + +## fs.mkdir + +mkdir(path: string, callback: AsyncCallback<void>): void + +创建目录，使用callback异步回调。 + +**系统能力**：SystemCapability.FileManagement.File.FileIO + +**参数：** + +| 参数名 | 类型 | 必填 | 说明 | +| -------- | ------------------------- | ---- | ------------------------------------------------------------ | +| path | string | 是 | 目录的应用沙箱路径。 | +| callback | AsyncCallback<void> | 是 | 异步创建目录操作完成之后的回调。 | + +**示例：** + + ```js + let dirPath = pathDir + '/testDir'; + fs.mkdir(dirPath, function (err) { + if (err) { + console.info("mkdir failed with error message: " + err.message + ", error code: " + err.code); + } else { + console.info("mkdir success"); + } + }); + ``` + + +## fs.mkdirSync + +mkdirSync(path: string): void + +以同步方法创建目录。 + +**系统能力**：SystemCapability.FileManagement.File.FileIO + +**参数：** + +| 参数名 | 类型 | 必填 | 说明 | +| ------ | ------ | ---- | ------------------------------------------------------------ | +| path | string | 是 | 目录的应用沙箱路径。 | + +**示例：** + + ```js + let dirPath = path + '/testDir'; + fs.mkdirSync(dirPath); + ``` + + +## fs.open + +open(path: string, flags?: number): Promise<File> + +打开文件，使用Promise异步回调。支持使用URI打开文件。 + +**系统能力**：SystemCapability.FileManagement.File.FileIO + +**参数：** + +| 参数名 | 类型 | 必填 | 说明 | +| ------ | ------ | ---- | ------------------------------------------------------------ | +| path | string | 是 | 文件的应用沙箱路径或文件URI。 | +| flags | number | 否 | 打开文件的[选项](#openmode)，必须指定如下选项中的一个，默认以只读方式打开：
- OpenMode.READ_ONLY(0o0)：只读打开。
- OpenMode.WRITE_ONLY(0o1)：只写打开。
- OpenMode.READ_WRITE(0o2)：读写打开。
给定如下功能选项，以按位或的方式追加，默认不给定任何额外选项：
- OpenMode.CREATE(0o100)：若文件不存在，则创建文件。
- OpenMode.TRUNC(0o1000)：如果文件存在且以只写或读写的方式打开文件，则将其长度裁剪为零。
- OpenMode.APPEND(0o2000)：以追加方式打开，后续写将追加到文件末尾。
- OpenMode.NONBLOCK(0o4000)：如果path指向FIFO、块特殊文件或字符特殊文件，则本次打开及后续 IO 进行非阻塞操作。
- OpenMode.DIR(0o200000)：如果path不指向目录，则出错。
- OpenMode.NOFOLLOW(0o400000)：如果path指向符号链接，则出错。
- OpenMode.SYNC(0o4010000)：以同步IO的方式打开文件。 | + +**返回值：** + + | 类型 | 说明 | + | --------------------- | ----------- | + | Promise<[File](#file)> | Promise对象。返回File对象。 | + +**示例：** + + ```js + let filePath = pathDir + "/test.txt"; + fs.open(filePath, fs.OpenMode.READ_WRITE | fs.OpenMode.CREATE).then(function (file) { + console.info("file fd: " + file.fd); + }).catch(function (err) { + console.info("open file failed with error message: " + err.message + ", error code: " + err.code); + }); + ``` + + +## fs.open + +open(path: string, flags?: number, callback: AsyncCallback<File>): void + +打开文件，使用callback异步回调。支持使用URI打开文件。 + +**系统能力**：SystemCapability.FileManagement.File.FileIO + +**参数：** + +| 参数名 | 类型 | 必填 | 说明 | +| -------- | ------------------------------- | ---- | ------------------------------------------------------------ | +| path | string | 是 | 文件的应用沙箱路径或URI。 | +| flags | number | 否 | 打开文件的[选项](#openmode)，必须指定如下选项中的一个，默认以只读方式打开：
- OpenMode.READ_ONLY(0o0)：只读打开。
- OpenMode.WRITE_ONLY(0o1)：只写打开。
- OpenMode.READ_WRITE(0o2)：读写打开。
给定如下功能选项，以按位或的方式追加，默认不给定任何额外选项：
- OpenMode.CREATE(0o100)：若文件不存在，则创建文件。
- OpenMode.TRUNC(0o1000)：如果文件存在且以只写或读写的方式打开文件，则将其长度裁剪为零。
- OpenMode.APPEND(0o2000)：以追加方式打开，后续写将追加到文件末尾。
- OpenMode.NONBLOCK(0o4000)：如果path指向FIFO、块特殊文件或字符特殊文件，则本次打开及后续 IO 进行非阻塞操作。
- OpenMode.DIR(0o200000)：如果path不指向目录，则出错。
- OpenMode.NOFOLLOW(0o400000)：如果path指向符号链接，则出错。
- OpenMode.SYNC(0o4010000)：以同步IO的方式打开文件。 | + +**示例：** + + ```js + let filePath = pathDir + "/test.txt"; + fs.open(filePath, fs.OpenMode.READ_WRITE | fs.OpenMode.CREATE, function (err, file) { + if (err) { + console.info("mkdir failed with error message: " + err.message + ", error code: " + err.code); + } else { + console.info("file fd: " + file.fd); + } + }); + ``` + +## fs.openSync + +openSync(path: string, flags?: number): File + +以同步方法打开文件。支持使用URI打开文件。 + +**系统能力**：SystemCapability.FileManagement.File.FileIO + +**参数：** + +| 参数名 | 类型 | 必填 | 说明 | +| ------ | ------ | ---- | ------------------------------------------------------------ | +| path | string | 是 | 打开文件的应用沙箱路径或URI。 | +| flags | number | 否 | 打开文件的[选项](#openmode)，必须指定如下选项中的一个，默认以只读方式打开：
- OpenMode.READ_ONLY(0o0)：只读打开。
- OpenMode.WRITE_ONLY(0o1)：只写打开。
- OpenMode.READ_WRITE(0o2)：读写打开。
给定如下功能选项，以按位或的方式追加，默认不给定任何额外选项：
- OpenMode.CREATE(0o100)：若文件不存在，则创建文件。
- OpenMode.TRUNC(0o1000)：如果文件存在且以只写或读写的方式打开文件，则将其长度裁剪为零。
- OpenMode.APPEND(0o2000)：以追加方式打开，后续写将追加到文件末尾。
- OpenMode.NONBLOCK(0o4000)：如果path指向FIFO、块特殊文件或字符特殊文件，则本次打开及后续 IO 进行非阻塞操作。
- OpenMode.DIR(0o200000)：如果path不指向目录，则出错。
- OpenMode.NOFOLLOW(0o400000)：如果path指向符号链接，则出错。
- OpenMode.SYNC(0o4010000)：以同步IO的方式打开文件。 | + +**返回值：** + + | 类型 | 说明 | + | ------ | ----------- | + | [File](#file) | 打开的File对象。 | + +**示例：** + + ```js + let filePath = pathDir + "/test.txt"; + let file = fs.openSync(filePath, fs.OpenMode.READ_WRITE | fs.OpenMode.CREATE); + console.info("file fd: " + file.fd); + fs.closeSync(file); + ``` + +## fs.read + +read(fd: number, buffer: ArrayBuffer, options?: { offset?: number; length?: number; }): Promise<number> + +从文件读取数据，使用Promise异步回调。 + +**系统能力**：SystemCapability.FileManagement.File.FileIO + +**参数：** + +| 参数名 | 类型 | 必填 | 说明 | +| ------- | ----------- | ---- | ------------------------------------------------------------ | +| fd | number | 是 | 已打开的文件描述符。 | +| buffer | ArrayBuffer | 是 | 用于保存读取到的文件数据的缓冲区。 | +| options | Object | 否 | 支持如下选项：
- offset，number类型，表示期望读取文件的位置。可选，默认从当前位置开始读。
- length，number类型，表示期望读取数据的长度。可选，默认缓冲区长度。| + +**返回值：** + + | 类型 | 说明 | + | ---------------------------------- | ------ | + | Promise<number> | Promise对象。返回读取的结果。 | + +**示例：** + + ```js + let filePath = pathDir + "/test.txt"; + let file = fs.openSync(filePath, fs.OpenMode.READ_WRITE); + let buf = new ArrayBuffer(4096); + fs.read(file.fd, buf).then(function (readLen) { + console.info("read file data succeed"); + console.info(String.fromCharCode.apply(null, new Uint8Array(readLen))); + fs.closeSync(file); + }).catch(function (err) { + console.info("read file data failed with error message: " + err.message + ", error code: " + err.code); + }); + ``` + +## fs.read + +read(fd: number, buffer: ArrayBuffer, options?: { offset?: number; length?: number; }, callback: AsyncCallback<number>): void + +从文件读取数据，使用callback异步回调。 + +**系统能力**：SystemCapability.FileManagement.File.FileIO + +**参数：** + + | 参数名 | 类型 | 必填 | 说明 | + | -------- | ---------------------------------------- | ---- | ---------------------------------------- | + | fd | number | 是 | 已打开的文件描述符。 | + | buffer | ArrayBuffer | 是 | 用于保存读取到的文件数据的缓冲区。 | + | options | Object | 否 | 支持如下选项：
- offset，number类型，表示期望读取文件的位置。可选，默认从当前位置开始读。
- length，number类型，表示期望读取数据的长度。可选，默认缓冲区长度。| + | callback | AsyncCallback<number> | 是 | 异步读取数据之后的回调。 | + +**示例：** + + ```js + let filePath = pathDir + "/test.txt"; + let file = fs.openSync(filePath, fs.OpenMode.READ_WRITE); + let buf = new ArrayBuffer(4096); + fs.read(file.fd, buf, function (err, readLen) { + if (err) { + console.info("mkdir failed with error message: " + err.message + ", error code: " + err.code); + } else { + console.info("read file data succeed"); + console.info(String.fromCharCode.apply(null, new Uint8Array(readLen))); + fs.closeSync(file); + } + }); + ``` + + +## fs.readSync + +readSync(fd: number, buffer: ArrayBuffer, options?: { offset?: number; length?: number; }): number + +以同步方法从文件读取数据。 + +**系统能力**：SystemCapability.FileManagement.File.FileIO + +**参数：** + + | 参数名 | 类型 | 必填 | 说明 | + | ------- | ----------- | ---- | ---------------------------------------- | + | fd | number | 是 | 已打开的文件描述符。 | + | buffer | ArrayBuffer | 是 | 用于保存读取到的文件数据的缓冲区。 | + | options | Object | 否 | 支持如下选项：
- offset，number类型，表示期望读取文件的位置。可选，默认从当前位置开始读。
- length，number类型，表示期望读取数据的长度。可选，默认缓冲区长度。| + +**返回值：** + + | 类型 | 说明 | + | ------ | -------- | + | number | 实际读取的长度。 | + +**示例：** + + ```js + let filePath = pathDir + "/test.txt"; + let file = fs.openSync(filePath, fs.OpenMode.READ_WRITE); + let buf = new ArrayBuffer(4096); + let num = fs.readSync(file.fd, buf); + fs.closeSync(file); + ``` + + +## fs.rmdir + +rmdir(path: string): Promise<void> + +删除整个目录，使用Promise异步回调。 + +**系统能力**：SystemCapability.FileManagement.File.FileIO + +**参数：** + +| 参数名 | 类型 | 必填 | 说明 | +| ------ | ------ | ---- | -------------------------- | +| path | string | 是 | 目录的应用沙箱路径。 | + +**返回值：** + + | 类型 | 说明 | + | ------------------- | ---------------------------- | + | Promise<void> | Promise对象。无返回值。 | + +**示例：** + + ```js + let dirPath = pathDir + '/testDir'; + fs.rmdir(dirPath).then(function () { + console.info("rmdir succeed"); + }).catch(function (err) { + console.info("rmdir failed with error message: " + err.message + ", error code: " + err.code); + }); + ``` + + +## fs.rmdir + +rmdir(path: string, callback: AsyncCallback<void>): void + +删除整个目录，使用callback异步回调。 + +**系统能力**：SystemCapability.FileManagement.File.FileIO + +**参数：** + +| 参数名 | 类型 | 必填 | 说明 | +| -------- | ------------------------- | ---- | -------------------------- | +| path | string | 是 | 目录的应用沙箱路径。 | +| callback | AsyncCallback<void> | 是 | 异步删除目录之后的回调。 | + +**示例：** + + ```js + let dirPath = pathDir + '/testDir'; + fs.rmdir(dirPath, function (err) { + if (err) { + console.info("rmdir failed with error message: " + err.message + ", error code: " + err.code); + } else { + console.info("rmdir succeed"); + } + }); + ``` + + +## fs.rmdirSync + +rmdirSync(path: string): void + +以同步方法删除目录。 + +**系统能力**：SystemCapability.FileManagement.File.FileIO + +**参数：** + +| 参数名 | 类型 | 必填 | 说明 | +| ------ | ------ | ---- | -------------------------- | +| path | string | 是 | 目录的应用沙箱路径。 | + +**示例：** + + ```js + let dirPath = pathDir + '/testDir'; + fs.rmdirSync(dirPath); + ``` + + +## fs.unlink + +unlink(path: string): Promise<void> + +删除单个文件，使用Promise异步回调。 + +**系统能力**：SystemCapability.FileManagement.File.FileIO + +**参数：** + +| 参数名 | 类型 | 必填 | 说明 | +| ------ | ------ | ---- | -------------------------- | +| path | string | 是 | 文件的应用沙箱路径。 | + +**返回值：** + + | 类型 | 说明 | + | ------------------- | ---------------------------- | + | Promise<void> | Promise对象。无返回值。 | + +**示例：** + + ```js + let filePath = pathDir + "/test.txt"; + fs.unlink(filePath).then(function () { + console.info("remove file succeed"); + }).catch(function (err) { + console.info("remove file failed with error message: " + err.message + ", error code: " + err.codeor); + }); + ``` + + +## fs.unlink + +unlink(path: string, callback: AsyncCallback<void>): void + +删除文件，使用callback异步回调。 + +**系统能力**：SystemCapability.FileManagement.File.FileIO + +**参数：** + +| 参数名 | 类型 | 必填 | 说明 | +| -------- | ------------------------- | ---- | -------------------------- | +| path | string | 是 | 文件的应用沙箱路径。 | +| callback | AsyncCallback<void> | 是 | 异步删除文件之后的回调。 | + +**示例：** + + ```js + let filePath = pathDir + "/test.txt"; + fs.unlink(filePath, function (err) { + if (err) { + console.info("remove file failed with error message: " + err.message + ", error code: " + err.code); + } else { + console.info("remove file succeed"); + } + }); + ``` + + +## fs.unlinkSync + +unlinkSync(path: string): void + +以同步方法删除文件。 + +**系统能力**：SystemCapability.FileManagement.File.FileIO + +**参数：** + +| 参数名 | 类型 | 必填 | 说明 | +| ------ | ------ | ---- | -------------------------- | +| path | string | 是 | 文件的应用沙箱路径。 | + +**示例：** + + ```js + let filePath = pathDir + "/test.txt"; + fs.unlinkSync(filePath); + ``` + + +## fs.write + +write(fd: number, buffer: ArrayBuffer|string, options?: { offset?: number; length?: number; encoding?: string; }): Promise<number> + +将数据写入文件，使用Promise异步回调。 + +**系统能力**：SystemCapability.FileManagement.File.FileIO + +**参数：** + + | 参数名 | 类型 | 必填 | 说明 | + | ------- | ------------------------------- | ---- | ---------------------------------------- | + | fd | number | 是 | 已打开的文件描述符。 | + | buffer | ArrayBuffer\|string | 是 | 待写入文件的数据，可来自缓冲区或字符串。 | + | options | Object | 否 | 支持如下选项：
- offset，number类型，表示期望写入文件的位置。可选，默认从当前位置开始写。
- length，number类型，表示期望写入数据的长度。可选，默认缓冲区长度。
- encoding，string类型，当数据是string类型时有效，表示数据的编码方式，默认 'utf-8'。当前仅支持 'utf-8'。| + +**返回值：** + + | 类型 | 说明 | + | --------------------- | -------- | + | Promise<number> | Promise对象。返回实际写入的长度。 | + +**示例：** + + ```js + let filePath = pathDir + "/test.txt"; + let file = fs.openSync(filePath, fs.OpenMode.READ_WRITE | fs.OpenMode.CREATE); + fs.write(file.fd, "hello, world").then(function (writeLen) { + console.info("write data to file succeed and size is:" + writeLen); + fs.closeSync(file); + }).catch(function (err) { + console.info("write data to file failed with error message: " + err.message + ", error code: " + err.code); + }); + ``` + + +## fs.write + +write(fd: number, buffer: ArrayBuffer|string, options?: { offset?: number; length?: number; encoding?: string; }, callback: AsyncCallback<number>): void + +将数据写入文件，使用callback异步回调。 + +**系统能力**：SystemCapability.FileManagement.File.FileIO + +**参数：** + + | 参数名 | 类型 | 必填 | 说明 | + | -------- | ------------------------------- | ---- | ---------------------------------------- | + | fd | number | 是 | 已打开的文件描述符。 | + | buffer | ArrayBuffer\|string | 是 | 待写入文件的数据，可来自缓冲区或字符串。 | + | options | Object | 否 | 支持如下选项：
- offset，number类型，表示期望写入文件的位置。可选，默认从当前位置开始写。
- length，number类型，表示期望写入数据的长度。可选，默认缓冲区长度。
- encoding，string类型，当数据是string类型时有效，表示数据的编码方式，默认 'utf-8'。当前仅支持 'utf-8'。| + | callback | AsyncCallback<number> | 是 | 异步将数据写入完成后执行的回调函数。 | + +**示例：** + + ```js + let filePath = pathDir + "/test.txt"; + let file = fs.openSync(filePath, fs.OpenMode.READ_WRITE | fs.OpenMode.CREATE); + fs.write(file.fd, "hello, world", function (err, writeLen) { + if (err) { + console.info("write failed with error message: " + err.message + ", error code: " + err.code); + } else { + console.info("write data to file succeed and size is:" + writeLen); + fs.closeSync(file); + } + }); + ``` + + +## fs.writeSync + +writeSync(fd: number, buffer: ArrayBuffer|string, options?: { offset?: number; length?: number; encoding?: string; }): number + +以同步方法将数据写入文件。 + +**系统能力**：SystemCapability.FileManagement.File.FileIO + +**参数：** + + | 参数名 | 类型 | 必填 | 说明 | + | ------- | ------------------------------- | ---- | ---------------------------------------- | + | fd | number | 是 | 已打开的文件描述符。 | + | buffer | ArrayBuffer\|string | 是 | 待写入文件的数据，可来自缓冲区或字符串。 | + | options | Object | 否 | 支持如下选项：
- offset，number类型，表示期望写入文件的位置。可选，默认从当前位置开始写。
- length，number类型，表示期望写入数据的长度。可选，默认缓冲区长度。
- encoding，string类型，当数据是string类型时有效，表示数据的编码方式，默认 'utf-8'。当前仅支持 'utf-8'。| + +**返回值：** + + | 类型 | 说明 | + | ------ | -------- | + | number | 实际写入的长度。 | + +**示例：** + + ```js + let filePath = pathDir + "/test.txt"; + let file = fs.openSync(filePath, fs.OpenMode.READ_WRITE | fs.OpenMode.CREATE); + let writeLen = fs.writeSync(file.fd, "hello, world"); + console.info("write data to file succeed and size is:" + writeLen); + fs.closeSync(file); + ``` + +## fs.truncate + +truncate(file: string|number, len?: number): Promise<void> + +截断文件，使用Promise异步回调。 + +**系统能力**：SystemCapability.FileManagement.File.FileIO + +**参数：** + +| 参数名 | 类型 | 必填 | 说明 | +| ------ | ------ | ---- | -------------------------------- | +| file | string\|number | 是 | 文件的应用沙箱路径或已打开的文件描述符fd。 | +| len | number | 否 | 文件截断后的长度，以字节为单位。 | + +**返回值：** + + | 类型 | 说明 | + | ------------------- | ---------------------------- | + | Promise<void> | Promise对象。无返回值。 | + +**示例：** + + ```js + let filePath = pathDir + "/test.txt"; + let len = 5; + fs.truncate(filePath, len).then(function () { + console.info("truncate file succeed"); + }).catch(function (err) { + console.info("truncate file failed with error message: " + err.message + ", error code: " + err.code); + }); + ``` + + +## fs.truncate + +truncate(file: string|number, len?: number, callback: AsyncCallback<void>): void + +截断文件，使用callback异步回调。 + +**系统能力**：SystemCapability.FileManagement.File.FileIO + +**参数：** + +| 参数名 | 类型 | 必填 | 说明 | +| -------- | ------------------------- | ---- | -------------------------------- | +| file | string\|number | 是 | 文件的应用沙箱路径或已打开的文件描述符fd。 | +| len | number | 否 | 文件截断后的长度，以字节为单位。 | +| callback | AsyncCallback<void> | 是 | 回调函数，本调用无返回值。 | + +**示例：** + + ```js + let filePath = pathDir + "/test.txt"; + let len = 5; + fs.truncate(filePath, len, function (err) { + if (err) { + console.info("truncate failed with error message: " + err.message + ", error code: " + err.code); + } else { + console.info("truncate success"); + } + }); + ``` + + +## fs.truncateSync + +truncateSync(file: string|number, len?: number): void + +以同步方法截断文件。 + +**系统能力**：SystemCapability.FileManagement.File.FileIO + +**参数：** + +| 参数名 | 类型 | 必填 | 说明 | +| ------ | ------ | ---- | -------------------------------- | +| file | string\|number | 是 | 文件的应用沙箱路径或已打开的文件描述符fd。 | +| len | number | 否 | 文件截断后的长度，以字节为单位。 | + +**示例：** + + ```js + let filePath = pathDir + "/test.txt"; + let len = 5; + fs.truncateSync(filePath, len); + ``` + + +## fs.readText + +readText(filePath: string, options?: { offset?: number; length?: number; encoding?: string; }): Promise<string> + +基于文本方式读取文件（即直接读取文件的文本内容），使用Promise异步回调。 + +**系统能力**：SystemCapability.FileManagement.File.FileIO + +**参数：** + +| 参数名 | 类型 | 必填 | 说明 | +| -------- | ------ | ---- | ------------------------------------------------------------ | +| filePath | string | 是 | 文件的应用沙箱路径。 | +| options | Object | 否 | 支持如下选项：
- offset，number类型，表示期望读取文件的位置。可选，默认从当前位置开始读取。
- length，number类型，表示期望读取数据的长度。可选，默认文件长度。
- encoding，string类型，当数据是 string 类型时有效，表示数据的编码方式，默认 'utf-8'，仅支持 'utf-8'。 | + +**返回值：** + + | 类型 | 说明 | + | --------------------- | ---------- | + | Promise<string> | Promise对象。返回读取文件的内容。 | + +**示例：** + + ```js + let filePath = pathDir + "/test.txt"; + fs.readText(filePath).then(function (str) { + console.info("readText succeed:" + str); + }).catch(function (err) { + console.info("readText failed with error message: " + err.message + ", error code: " + err.code); + }); + ``` + + +## fs.readText + +readText(filePath: string, options?: { offset?: number; length?: number; encoding?: string; }, callback: AsyncCallback<string>): void + +基于文本方式读取文件（即直接读取文件的文本内容），使用callback异步回调。 + +**系统能力**：SystemCapability.FileManagement.File.FileIO + +**参数：** + +| 参数名 | 类型 | 必填 | 说明 | +| -------- | --------------------------- | ---- | ------------------------------------------------------------ | +| filePath | string | 是 | 文件的应用沙箱路径。 | +| options | Object | 否 | 支持如下选项：
- offset，number类型，表示期望读取文件的位置。可选，默认从当前位置开始读取。
- length，number类型，表示期望读取数据的长度。可选，默认文件长度。
- encoding，string类型，表示数据的编码方式，默认 'utf-8'，仅支持 'utf-8'。 | +| callback | AsyncCallback<string> | 是 | 回调函数，返回读取文件的内容。 | + +**示例：** + + ```js + let filePath = pathDir + "/test.txt"; + fs.readText(filePath, { offset: 1, encoding: 'UTF-8' }, function (err, str) { + if (err) { + console.info("read text failed with error message: " + err.message + ", error code: " + err.code); + } else { + console.info("readText succeed:" + str); + } + }); + ``` + + +## fs.readTextSync + +readTextSync(filePath: string, options?: { offset?: number; length?: number; encoding?: string; }): string + +以同步方法基于文本方式读取文件（即直接读取文件的文本内容）。 + +**系统能力**：SystemCapability.FileManagement.File.FileIO + +**参数：** + +| 参数名 | 类型 | 必填 | 说明 | +| -------- | ------ | ---- | ------------------------------------------------------------ | +| filePath | string | 是 | 文件的应用沙箱路径。 | +| options | Object | 否 | 支持如下选项：
- offset，number类型，表示期望读取文件的位置。可选，默认从当前位置开始读取。
- length，number类型，表示期望读取数据的长度。可选，默认文件长度。
- encoding，string类型，当数据是 string 类型时有效，表示数据的编码方式，默认 'utf-8'，仅支持 'utf-8'。 | + +**返回值：** + + | 类型 | 说明 | + | ------ | -------------------- | + | string | 返回读取文件的内容。 | + +**示例：** + + ```js + let filePath = pathDir + "/test.txt"; + let str = fs.readTextSync(filePath, {offset: 1, length: 3}); + console.info("readText succeed:" + str); + ``` + +## fs.lstat + +lstat(path: string): Promise<Stat> + +获取链接文件信息，使用Promise异步回调。 + +**系统能力**：SystemCapability.FileManagement.File.FileIO + +**参数：** + +| 参数名 | 类型 | 必填 | 说明 | +| ------ | ------ | ---- | -------------------------------------- | +| path | string | 是 | 文件的应用沙箱路径。 | + +**返回值：** + + | 类型 | 说明 | + | ---------------------------- | ---------- | + | Promise<[Stat](#stat)> | promise对象，返回文件对象，表示文件的具体信息，详情见stat。 | + +**示例：** + + ```js + let filePath = pathDir + "/test.txt"; + fs.lstat(filePath).then(function (stat) { + console.info("get link status succeed, the size of file is" + stat.size); + }).catch(function (err) { + console.info("get link status failed with error message: " + err.message + ", error code: " + err.code); + }); + ``` + + +## fs.lstat + +lstat(path: string, callback: AsyncCallback<Stat>): void + +获取链接文件信息，使用callback异步回调。 + +**系统能力**：SystemCapability.FileManagement.File.FileIO + +**参数：** + +| 参数名 | 类型 | 必填 | 说明 | +| -------- | ---------------------------------- | ---- | -------------------------------------- | +| path | string | 是 | 文件的应用沙箱路径。 | +| callback | AsyncCallback<[Stat](#stat)> | 是 | 回调函数，返回文件的具体信息。 | + +**示例：** + + ```js + let filePath = pathDir + "/test.txt"; + fs.lstat(filePath, function (err, stat) { + if (err) { + console.info("lstat failed with error message: " + err.message + ", error code: " + err.code); + } else { + console.info("get link status succeed, the size of file is" + stat.size); + } + }); + ``` + +## fs.lstatSync + +lstatSync(path: string): Stat + +以同步方法获取链接文件信息。 + +**系统能力**：SystemCapability.FileManagement.File.FileIO + +**参数：** + +| 参数名 | 类型 | 必填 | 说明 | +| ------ | ------ | ---- | -------------------------------------- | +| path | string | 是 | 文件的应用沙箱路径。 | + +**返回值：** + + | 类型 | 说明 | + | ------------- | ---------- | + | [Stat](#stat) | 表示文件的具体信息。 | + +**示例：** + + ```js + let filePath = pathDir + "/test.txt"; + let stat = fs.lstatSync(filePath); + ``` + +## fs.rename + +rename(oldPath: string, newPath: string): Promise<void> + +重命名文件，使用Promise异步回调。 + +**系统能力**：SystemCapability.FileManagement.File.FileIO + +**参数：** + +| 参数名 | 类型 | 必填 | 说明 | +| ------- | ------ | ---- | ---------------------------- | +| oldPath | string | 是 | 文件的应用沙箱原路径。 | +| newPath | string | 是 | 文件的应用沙箱新路径。 | + +**返回值：** + + | 类型 | 说明 | + | ------------------- | ---------------------------- | + | Promise<void> | Promise对象。无返回值。 | + +**示例：** + + ```js + let srcFile = pathDir + "/test.txt"; + let dstFile = pathDir + '/new.txt'; + fs.rename(srcFile, dstFile).then(function () { + console.info("rename succeed"); + }).catch(function (err) { + console.info("rename failed with error message: " + err.message + ", error code: " + err.code); + }); + ``` + +## fs.rename + +rename(oldPath: string, newPath: string, callback: AsyncCallback<void>): void + +重命名文件，使用callback异步回调。 + +**系统能力**：SystemCapability.FileManagement.File.FileIO + +**参数：** + +| 参数名 | 类型 | 必填 | 说明 | +| -------- | ------------------------- | ---- | ---------------------------- | +| oldPath | string | 是 | 文件的应用沙箱原路径。 | +| newPath | string | 是 | 文件的应用沙箱新路径。 | +| callback | AsyncCallback<void> | 是 | 异步重命名文件之后的回调。 | + +**示例：** + + ```js + let srcFile = pathDir + "/test.txt"; + let dstFile = pathDir + '/new.txt'; + fs.rename(srcFile, dstFile, function (err) { + if (err) { + console.info("rename failed with error message: " + err.message + ", error code: " + err.code); + } else { + console.info("rename success"); + } + }); + ``` + +## fs.renameSync + +renameSync(oldPath: string, newPath: string): void + +以同步方法重命名文件。 + +**系统能力**：SystemCapability.FileManagement.File.FileIO + +**参数：** + +| 参数名 | 类型 | 必填 | 说明 | +| ------- | ------ | ---- | ---------------------------- | +| oldPath | string | 是 | 文件的应用沙箱原路径。 | +| newPath | string | 是 | 文件的应用沙箱新路径。 | + +**示例：** + + ```js + let srcFile = pathDir + "/test.txt"; + let dstFile = pathDir + '/new.txt'; + fs.renameSync(srcFile, dstFile); + ``` + + +## fs.fsync + +fsync(fd: number): Promise<void> + +同步文件数据，使用Promise异步回调。 + +**系统能力**：SystemCapability.FileManagement.File.FileIO + +**参数：** + + | 参数名 | 类型 | 必填 | 说明 | + | ---- | ------ | ---- | ------------ | + | fd | number | 是 | 已打开的文件描述符。 | + +**返回值：** + + | 类型 | 说明 | + | ------------------- | ---------------------------- | + | Promise<void> | Promise对象。无返回值。 | + +**示例：** + + ```js + let filePath = pathDir + "/test.txt"; + let file = fs.openSync(filePath); + fs.fsync(file.fd).then(function () { + console.info("sync data succeed"); + }).catch(function (err) { + console.info("sync data failed with error message: " + err.message + ", error code: " + err.code); + }); + ``` + + +## fs.fsync + +fsync(fd: number, callback: AsyncCallback<void>): void + +同步文件数据，使用callback异步回调。 + +**系统能力**：SystemCapability.FileManagement.File.FileIO + +**参数：** + + | 参数名 | 类型 | 必填 | 说明 | + | -------- | ------------------------- | ---- | --------------- | + | fd | number | 是 | 已打开的文件描述符。 | + | Callback | AsyncCallback<void> | 是 | 异步将文件数据同步之后的回调。 | + +**示例：** + + ```js + let filePath = pathDir + "/test.txt"; + let file = fs.openSync(filePath); + fs.fsync(file.fd, function (err) { + if (err) { + console.info("fsync failed with error message: " + err.message + ", error code: " + err.code); + } else { + console.info("fsync success"); + fs.closeSync(file); + } + }); + ``` + + +## fs.fsyncSync + +fsyncSync(fd: number): void + +以同步方法同步文件数据。 + +**系统能力**：SystemCapability.FileManagement.File.FileIO + +**参数：** + + | 参数名 | 类型 | 必填 | 说明 | + | ---- | ------ | ---- | ------------ | + | fd | number | 是 | 已打开的文件描述符。 | + +**示例：** + + ```js + let filePath = pathDir + "/test.txt"; + let file = fs.openSync(filePath); + fs.fsyncSync(file.fd); + fs.closeSync(file); + ``` + + +## fs.fdatasync + +fdatasync(fd: number): Promise<void> + +实现文件内容数据同步，使用Promise异步回调。 + +**系统能力**：SystemCapability.FileManagement.File.FileIO + +**参数：** + + | 参数名 | 类型 | 必填 | 说明 | + | ---- | ------ | ---- | ------------ | + | fd | number | 是 | 已打开的文件描述符。 | + +**返回值：** + + | 类型 | 说明 | + | ------------------- | ---------------------------- | + | Promise<void> | Promise对象。无返回值。 | + +**示例：** + + ```js + let filePath = pathDir + "/test.txt"; + let file = fs.openSync(filePath); + fs.fdatasync(file.fd).then(function (err) { + console.info("sync data succeed"); + fs.closeSync(file); + }).catch(function (err) { + console.info("sync data failed with error message: " + err.message + ", error code: " + err.code); + }); + ``` + + +## fs.fdatasync + +fdatasync(fd: number, callback: AsyncCallback<void>): void + +实现文件内容数据同步，使用callback异步回调。 + +**系统能力**：SystemCapability.FileManagement.File.FileIO + +**参数：** + + | 参数名 | 类型 | 必填 | 说明 | + | -------- | ------------------------------- | ---- | ----------------- | + | fd | number | 是 | 已打开的文件描述符。 | + | callback | AsyncCallback<void> | 是 | 异步将文件内容数据同步之后的回调。 | + +**示例：** + + ```js + let filePath = pathDir + "/test.txt"; + let file = fs.openSync(filePath); + fs.fdatasync (file.fd, function (err) { + if (err) { + console.info("fdatasync failed with error message: " + err.message + ", error code: " + err.code); + } else { + console.info("fdatasync success"); + fs.closeSync(file); + } + }); + ``` + +## fs.fdatasyncSync + +fdatasyncSync(fd: number): void + +以同步方法实现文件内容数据同步。 + +**系统能力**：SystemCapability.FileManagement.File.FileIO + +**参数：** + + | 参数名 | 类型 | 必填 | 说明 | + | ---- | ------ | ---- | ------------ | + | fd | number | 是 | 已打开的文件描述符。 | + +**示例：** + + ```js + let filePath = pathDir + "/test.txt"; + let file = fs.openSync(filePath); + let stat = fs.fdatasyncSync(file.fd); + fs.closeSync(file); + ``` + + +## fs.symlink + +symlink(target: string, srcPath: string): Promise<void> + +基于文件路径创建符号链接，使用Promise异步回调。 + +**系统能力**：SystemCapability.FileManagement.File.FileIO + +**参数：** + +| 参数名 | 类型 | 必填 | 说明 | +| ------- | ------ | ---- | ---------------------------- | +| target | string | 是 | 源文件的应用沙箱路径。 | +| srcPath | string | 是 | 符号链接文件的应用沙箱路径。 | + +**返回值：** + + | 类型 | 说明 | + | ------------------- | ---------------------------- | + | Promise<void> | Promise对象。无返回值。 | + +**示例：** + + ```js + let srcFile = pathDir + "/test.txt"; + let dstFile = pathDir + '/test'; + fs.symlink(srcFile, dstFile).then(function () { + console.info("symlink succeed"); + }).catch(function (err) { + console.info("symlink failed with error message: " + err.message + ", error code: " + err.code); + }); + ``` + + +## fs.symlink +symlink(target: string, srcPath: string, callback: AsyncCallback<void>): void + +基于文件路径创建符号链接，使用callback异步回调。 + +**系统能力**：SystemCapability.FileManagement.File.FileIO + +**参数：** + +| 参数名 | 类型 | 必填 | 说明 | +| -------- | ------------------------- | ---- | -------------------------------- | +| target | string | 是 | 源文件的应用沙箱路径。 | +| srcPath | string | 是 | 符号链接文件的应用沙箱路径。 | +| callback | AsyncCallback<void> | 是 | 异步创建符号链接信息之后的回调。 | + +**示例：** + + ```js + let srcFile = pathDir + "/test.txt"; + let dstFile = pathDir + '/test'; + fs.symlink(srcFile, dstFile, function (err) { + if (err) { + console.info("symlink failed with error message: " + err.message + ", error code: " + err.code); + } else { + console.info("symlink success"); + } + }); + ``` + +## fs.symlinkSync + +symlinkSync(target: string, srcPath: string): void + +以同步的方法基于文件路径创建符号链接。 + +**系统能力**：SystemCapability.FileManagement.File.FileIO + +**参数：** + +| 参数名 | 类型 | 必填 | 说明 | +| ------- | ------ | ---- | ---------------------------- | +| target | string | 是 | 源文件的应用沙箱路径。 | +| srcPath | string | 是 | 符号链接文件的应用沙箱路径。 | + +**示例：** + + ```js + let srcFile = pathDir + "/test.txt"; + let dstFile = pathDir + '/test'; + fs.symlinkSync(srcFile, dstFile); + ``` + +## fs.mkdtemp + +mkdtemp(prefix: string): Promise<string> + +创建临时目录，使用Promise异步回调。 + +**系统能力**：SystemCapability.FileManagement.File.FileIO + +**参数：** + + | 参数名 | 类型 | 必填 | 说明 | + | ------ | ------ | ---- | --------------------------- | + | prefix | string | 是 | 用随机产生的字符串替换以“XXXXXX”结尾目录路径。 | + +**返回值：** + + | 类型 | 说明 | + | --------------------- | ---------- | + | Promise<string> | Promise对象。返回生成的唯一目录路径。 | + +**示例：** + + ```js + fs.mkdtemp(pathDir + "/XXXXXX").then(function (pathDir) { + console.info("mkdtemp succeed:" + pathDir); + }).catch(function (err) { + console.info("mkdtemp failed with error message: " + err.message + ", error code: " + err.code); + }); + ``` + + +## fs.mkdtemp + +mkdtemp(prefix: string, callback: AsyncCallback<string>): void + +创建临时目录，使用callback异步回调。 + +**系统能力**：SystemCapability.FileManagement.File.FileIO + +**参数：** + + | 参数名 | 类型 | 必填 | 说明 | + | -------- | --------------------------- | ---- | --------------------------- | + | prefix | string | 是 | 用随机产生的字符串替换以“XXXXXX”结尾目录路径。 | + | callback | AsyncCallback<string> | 是 | 异步创建临时目录之后的回调。 | + +**示例：** + + ```js + fs.mkdtemp(pathDir + "/XXXXXX", function (err, res) { + if (err) { + console.info("mkdtemp failed with error message: " + err.message + ", error code: " + err.code); + } else { + console.info("mkdtemp success"); + } + }); + ``` + +## fs.mkdtempSync + +mkdtempSync(prefix: string): string + +以同步的方法创建临时目录。 + +**系统能力**：SystemCapability.FileManagement.File.FileIO + +**参数：** + + | 参数名 | 类型 | 必填 | 说明 | + | ------ | ------ | ---- | --------------------------- | + | prefix | string | 是 | 用随机产生的字符串替换以“XXXXXX”结尾目录路径。 | + +**返回值：** + + | 类型 | 说明 | + | ------ | ---------- | + | string | 产生的唯一目录路径。 | + +**示例：** + + ```js + let res = fs.mkdtempSync(pathDir + "/XXXXXX"); + ``` + +## fs.createStream + +createStream(path: string, mode: string): Promise<Stream> + +基于文件路径打开文件流，使用Promise异步回调。 + +**系统能力**：SystemCapability.FileManagement.File.FileIO + +**参数：** + +| 参数名 | 类型 | 必填 | 说明 | +| ------ | ------ | ---- | ------------------------------------------------------------ | +| path | string | 是 | 文件的应用沙箱路径。 | +| mode | string | 是 | - r：打开只读文件，该文件必须存在。
- r+：打开可读写的文件，该文件必须存在。
- w：打开只写文件，若文件存在则文件长度清0，即该文件内容会消失。若文件不存在则建立该文件。
- w+：打开可读写文件，若文件存在则文件长度清0，即该文件内容会消失。若文件不存在则建立该文件。
- a：以附加的方式打开只写文件。若文件不存在，则会建立该文件，如果文件存在，写入的数据会被加到文件尾，即文件原先的内容会被保留。
- a+：以附加方式打开可读写的文件。若文件不存在，则会建立该文件，如果文件存在，写入的数据会被加到文件尾后，即文件原先的内容会被保留。 | + +**返回值：** + + | 类型 | 说明 | + | --------------------------------- | --------- | + | Promise<[Stream](#stream)> | Promise对象。返回文件流的结果。 | + +**示例：** + + ```js + let filePath = pathDir + "/test.txt"; + fs.createStream(filePath, "r+").then(function (stream) { + console.info("createStream succeed"); + }).catch(function (err) { + console.info("createStream failed with error message: " + err.message + ", error code: " + err.code); + }); + ``` + + +## fs.createStream + +createStream(path: string, mode: string, callback: AsyncCallback<Stream>): void + +基于文件路径打开文件流，使用callback异步回调。 + +**系统能力**：SystemCapability.FileManagement.File.FileIO + +**参数：** + +| 参数名 | 类型 | 必填 | 说明 | +| -------- | --------------------------------------- | ---- | ------------------------------------------------------------ | +| path | string | 是 | 文件的应用沙箱路径。 | +| mode | string | 是 | - r：打开只读文件，该文件必须存在。
- r+：打开可读写的文件，该文件必须存在。
- w：打开只写文件，若文件存在则文件长度清0，即该文件内容会消失。若文件不存在则建立该文件。
- w+：打开可读写文件，若文件存在则文件长度清0，即该文件内容会消失。若文件不存在则建立该文件。
- a：以附加的方式打开只写文件。若文件不存在，则会建立该文件，如果文件存在，写入的数据会被加到文件尾，即文件原先的内容会被保留。
- a+：以附加方式打开可读写的文件。若文件不存在，则会建立该文件，如果文件存在，写入的数据会被加到文件尾后，即文件原先的内容会被保留。 | +| callback | AsyncCallback<[Stream](#stream)> | 是 | 异步打开文件流之后的回调。 | + +**示例：** + + ```js + let filePath = pathDir + "/test.txt"; + fs.createStream(filePath, "r+", function (err, stream) { + if (err) { + console.info("create stream failed with error message: " + err.message + ", error code: " + err.code); + } else { + console.info("create stream success"); + } + }); + ``` + +## fs.createStreamSync + +createStreamSync(path: string, mode: string): Stream + +以同步方法基于文件路径打开文件流。 + +**系统能力**：SystemCapability.FileManagement.File.FileIO + +**参数：** + +| 参数名 | 类型 | 必填 | 说明 | +| ------ | ------ | ---- | ------------------------------------------------------------ | +| path | string | 是 | 文件的应用沙箱路径。 | +| mode | string | 是 | - r：打开只读文件，该文件必须存在。
- r+：打开可读写的文件，该文件必须存在。
- w：打开只写文件，若文件存在则文件长度清0，即该文件内容会消失。若文件不存在则建立该文件。
- w+：打开可读写文件，若文件存在则文件长度清0，即该文件内容会消失。若文件不存在则建立该文件。
- a：以附加的方式打开只写文件。若文件不存在，则会建立该文件，如果文件存在，写入的数据会被加到文件尾，即文件原先的内容会被保留。
- a+：以附加方式打开可读写的文件。若文件不存在，则会建立该文件，如果文件存在，写入的数据会被加到文件尾后，即文件原先的内容会被保留。 | + +**返回值：** + + | 类型 | 说明 | + | ------------------ | --------- | + | [Stream](#stream) | 返回文件流的结果。 | + +**示例：** + + ```js + let filePath = pathDir + "/test.txt"; + let ss = fs.createStreamSync(filePath, "r+"); + ``` + + +## fs.fdopenStream + +fdopenStream(fd: number, mode: string): Promise<Stream> + +基于文件描述符打开文件流，使用Promise异步回调。 + +**系统能力**：SystemCapability.FileManagement.File.FileIO + +**参数：** + + | 参数名 | 类型 | 必填 | 说明 | + | ---- | ------ | ---- | ---------------------------------------- | + | fd | number | 是 | 已打开的文件描述符。 | + | mode | string | 是 | - r：打开只读文件，该文件必须存在。
- r+：打开可读写的文件，该文件必须存在。
- w：打开只写文件，若文件存在则文件长度清0，即该文件内容会消失。若文件不存在则建立该文件。
- w+：打开可读写文件，若文件存在则文件长度清0，即该文件内容会消失。若文件不存在则建立该文件。
- a：以附加的方式打开只写文件。若文件不存在，则会建立该文件，如果文件存在，写入的数据会被加到文件尾，即文件原先的内容会被保留。
- a+：以附加方式打开可读写的文件。若文件不存在，则会建立该文件，如果文件存在，写入的数据会被加到文件尾后，即文件原先的内容会被保留。 | + +**返回值：** + + | 类型 | 说明 | + | --------------------------------- | --------- | + | Promise<[Stream](#stream)> | Promise对象。返回文件流的结果。 | + +**示例：** + + ```js + let filePath = pathDir + "/test.txt"; + let file = fs.openSync(filePath); + fs.fdopenStream(file.fd, "r+").then(function (stream) { + console.info("openStream succeed"); + fs.closeSync(file); + }).catch(function (err) { + console.info("openStream failed with error message: " + err.message + ", error code: " + err.code); + }); + ``` + + +## fs.fdopenStream + +fdopenStream(fd: number, mode: string, callback: AsyncCallback<Stream>): void + +基于文件描述符打开文件流，使用callback异步回调。 + +**系统能力**：SystemCapability.FileManagement.File.FileIO + +**参数：** + + | 参数名 | 类型 | 必填 | 说明 | + | -------- | ---------------------------------------- | ---- | ---------------------------------------- | + | fd | number | 是 | 已打开的文件描述符。 | + | mode | string | 是 | - r：打开只读文件，该文件必须存在。
- r+：打开可读写的文件，该文件必须存在。
- w：打开只写文件，若文件存在则文件长度清0，即该文件内容会消失。若文件不存在则建立该文件。
- w+：打开可读写文件，若文件存在则文件长度清0，即该文件内容会消失。若文件不存在则建立该文件。
- a：以附加的方式打开只写文件。若文件不存在，则会建立该文件，如果文件存在，写入的数据会被加到文件尾，即文件原先的内容会被保留。
- a+：以附加方式打开可读写的文件。若文件不存在，则会建立该文件，如果文件存在，写入的数据会被加到文件尾后，即文件原先的内容会被保留。 | + | callback | AsyncCallback<[Stream](#stream)> | 是 | 异步打开文件流之后的回调。 | + +**示例：** + + ```js + let filePath = pathDir + "/test.txt"; + let file = fs.openSync(filePath, fs.OpenMode.READ_ONLY); + fs.fdopenStream(file.fd, "r+", function (err, stream) { + if (err) { + console.info("fdopen stream failed with error message: " + err.message + ", error code: " + err.code); + } else { + console.info("fdopen stream success"); + fs.closeSync(file); + } + }); + ``` + +## fs.fdopenStreamSync + +fdopenStreamSync(fd: number, mode: string): Stream + +以同步方法基于文件描述符打开文件流。 + +**系统能力**：SystemCapability.FileManagement.File.FileIO + +**参数：** + + | 参数名 | 类型 | 必填 | 说明 | + | ---- | ------ | ---- | ---------------------------------------- | + | fd | number | 是 | 已打开的文件描述符。 | + | mode | string | 是 | - r：打开只读文件，该文件必须存在。
- r+：打开可读写的文件，该文件必须存在。
- w：打开只写文件，若文件存在则文件长度清0，即该文件内容会消失。若文件不存在则建立该文件。
- w+：打开可读写文件，若文件存在则文件长度清0，即该文件内容会消失。若文件不存在则建立该文件。
- a：以附加的方式打开只写文件。若文件不存在，则会建立该文件，如果文件存在，写入的数据会被加到文件尾，即文件原先的内容会被保留。
- a+：以附加方式打开可读写的文件。若文件不存在，则会建立该文件，如果文件存在，写入的数据会被加到文件尾后，即文件原先的内容会被保留。 | + +**返回值：** + + | 类型 | 说明 | + | ------------------ | --------- | + | [Stream](#stream) | 返回文件流的结果。 | + +**示例：** + + ```js + let filePath = pathDir + "/test.txt"; + let file = fs.openSync(filePath, fs.OpenMode.READ_ONLY | fs.OpenMode.CREATE); + let ss = fs.fdopenStreamSync(file.fd, "r+"); + fs.closeSync(file); + ``` + +## Stat + +文件具体信息，在调用Stat的方法前，需要先通过[stat()](#fsstat)方法（同步或异步）来构建一个Stat实例。 + +**系统能力**：以下各项对应的系统能力均为SystemCapability.FileManagement.File.FileIO。 + +### 属性 + +| 名称 | 类型 | 可读 | 可写 | 说明 | +| ------ | ------ | ---- | ---- | ---------------------------------------- | +| ino | number | 是 | 否 | 标识该文件。通常同设备上的不同文件的INO不同。| | +| mode | number | 是 | 否 | 表示文件权限，各特征位的含义如下：
- 0o400：用户读，对于普通文件，所有者可读取文件；对于目录，所有者可读取目录项。
- 0o200：用户写，对于普通文件，所有者可写入文件；对于目录，所有者可创建/删除目录项。
- 0o100：用户执行，对于普通文件，所有者可执行文件；对于目录，所有者可在目录中搜索给定路径名。
- 0o040：用户组读，对于普通文件，所有用户组可读取文件；对于目录，所有用户组可读取目录项。
- 0o020：用户组写，对于普通文件，所有用户组可写入文件；对于目录，所有用户组可创建/删除目录项。
- 0o010：用户组执行，对于普通文件，所有用户组可执行文件；对于目录，所有用户组是否可在目录中搜索给定路径名。
- 0o004：其他读，对于普通文件，其余用户可读取文件；对于目录，其他用户组可读取目录项。
- 0o002：其他写，对于普通文件，其余用户可写入文件；对于目录，其他用户组可创建/删除目录项。
- 0o001：其他执行，对于普通文件，其余用户可执行文件；对于目录，其他用户组可在目录中搜索给定路径名。 | +| uid | number | 是 | 否 | 文件所有者的ID。| +| gid | number | 是 | 否 | 文件所有组的ID。| +| size | number | 是 | 否 | 文件的大小，以字节为单位。仅对普通文件有效。 | +| atime | number | 是 | 否 | 上次访问该文件的时间，表示距1970年1月1日0时0分0秒的秒数。 | +| mtime | number | 是 | 否 | 上次修改该文件的时间，表示距1970年1月1日0时0分0秒的秒数。 | +| ctime | number | 是 | 否 | 最近改变文件状态的时间，表示距1970年1月1日0时0分0秒的秒数。 | + + +### isBlockDevice + +isBlockDevice(): boolean + +用于判断文件是否是块特殊文件。一个块特殊文件只能以块为粒度进行访问，且访问的时候带缓存。 + +**系统能力**：SystemCapability.FileManagement.File.FileIO + +**返回值：** + + | 类型 | 说明 | + | ------- | ---------------- | + | boolean | 表示文件是否是块特殊设备。 | + +**示例：** + + ```js + let filePath = pathDir + "/test.txt"; + let isBLockDevice = fs.statSync(filePath).isBlockDevice(); + ``` + +### isCharacterDevice + +isCharacterDevice(): boolean + +用于判断文件是否是字符特殊文件。一个字符特殊设备可进行随机访问，且访问的时候不带缓存。 + +**系统能力**：SystemCapability.FileManagement.File.FileIO + +**返回值：** + + | 类型 | 说明 | + | ------- | ----------------- | + | boolean | 表示文件是否是字符特殊设备。 | + +**示例：** + + ```js + let filePath = pathDir + "/test.txt"; + let isCharacterDevice = fs.statSync(filePath).isCharacterDevice(); + ``` + + +### isDirectory + +isDirectory(): boolean + +用于判断文件是否是目录。 + +**系统能力**：SystemCapability.FileManagement.File.FileIO + +**返回值：** + + | 类型 | 说明 | + | ------- | ------------- | + | boolean | 表示文件是否是目录。 | + +**示例：** + + ```js + let dirPath = pathDir + "/test"; + let isDirectory = fs.statSync(dirPath).isDirectory(); + ``` + + +### isFIFO + +isFIFO(): boolean + +用于判断文件是否是命名管道（有时也称为FIFO）。命名管道通常用于进程间通信。 + +**系统能力**：SystemCapability.FileManagement.File.FileIO + +**返回值：** + + | 类型 | 说明 | + | ------- | --------------------- | + | boolean | 表示文件是否是 FIFO。 | + +**示例：** + + ```js + let filePath = pathDir + "/test.txt"; + let isFIFO = fs.statSync(filePath).isFIFO(); + ``` + + +### isFile + +isFile(): boolean + +用于判断文件是否是普通文件。 + +**系统能力**：SystemCapability.FileManagement.File.FileIO + +**返回值：** + + | 类型 | 说明 | + | ------- | --------------- | + | boolean | 表示文件是否是普通文件。 | + +**示例：** + + ```js + let filePath = pathDir + "/test.txt"; + let isFile = fs.statSync(filePath).isFile(); + ``` + + +### isSocket + +isSocket(): boolean + +用于判断文件是否是套接字。 + +**系统能力**：SystemCapability.FileManagement.File.FileIO + +**返回值：** + + | 类型 | 说明 | + | ------- | -------------- | + | boolean | 表示文件是否是套接字。 | + +**示例：** + + ```js + let filePath = pathDir + "/test.txt"; + let isSocket = fs.statSync(filePath).isSocket(); + ``` + + +### isSymbolicLink + +isSymbolicLink(): boolean + +用于判断文件是否是符号链接。 + +**系统能力**：SystemCapability.FileManagement.File.FileIO + +**返回值：** + + | 类型 | 说明 | + | ------- | --------------- | + | boolean | 表示文件是否是符号链接。 | + +**示例：** + + ```js + let filePath = pathDir + "/test"; + let isSymbolicLink = fs.statSync(filePath).isSymbolicLink(); + ``` + +## Stream + +文件流，在调用Stream的方法前，需要先通过createStream()方法（同步或异步）来构建一个Stream实例。 + + +### close + +close(): Promise<void> + +关闭文件流，使用Promise异步回调。 + +**系统能力**：SystemCapability.FileManagement.File.FileIO + +**返回值：** + + | 类型 | 说明 | + | ------------------- | ------------- | + | Promise<void> | Promise对象。返回表示异步关闭文件流的结果。 | + +**示例：** + + ```js + let filePath = pathDir + "/test.txt"; + let ss= fs.createStreamSync(filePath, "r+"); + ss.close().then(function () { + console.info("close fileStream succeed"); + }).catch(function (err) { + console.info("close fileStream failed with error message: " + err.message + ", error code: " + err.code); + }); + ``` + + +### close + +close(callback: AsyncCallback<void>): void + +异步关闭文件流，使用callback异步回调。 + +**系统能力**：SystemCapability.FileManagement.File.FileIO + +**参数：** + + | 参数名 | 类型 | 必填 | 说明 | + | -------- | ------------------------- | ---- | ------------- | + | callback | AsyncCallback<void> | 是 | 异步关闭文件流之后的回调。 | + +**示例：** + + ```js + let filePath = pathDir + "/test.txt"; + let ss= fs.createStreamSync(filePath, "r+"); + ss.close(function (err) { + if (err) { + console.info("close stream failed with error message: " + err.message + ", error code: " + err.code); + } else { + console.info("close stream success"): + } + }); + ``` + +### closeSync + +closeSync(): void + +同步关闭文件流。 + +**系统能力**：SystemCapability.FileManagement.File.FileIO + +**示例：** + + ```js + let filePath = pathDir + "/test.txt"; + let ss= fs.createStreamSync(filePath, "r+"); + ss.closeSync(); + ``` + +### flush + +flush(): Promise<void> + +刷新文件流，使用Promise异步回调。 + +**系统能力**：SystemCapability.FileManagement.File.FileIO + +**返回值：** + + | 类型 | 说明 | + | ------------------- | ------------- | + | Promise<void> | Promise对象。返回表示异步刷新文件流的结果。 | + +**示例：** + + ```js + let filePath = pathDir + "/test.txt"; + let ss= fs.createStreamSync(filePath, "r+"); + ss.flush().then(function () { + console.info("flush succeed"); + }).catch(function (err) { + console.info("flush failed with error message: " + err.message + ", error code: " + err.code); + }); + ``` + + +### flush + +flush(callback: AsyncCallback<void>): void + +异步刷新文件流，使用callback异步回调。 + +**系统能力**：SystemCapability.FileManagement.File.FileIO + +**参数：** + + | 参数名 | 类型 | 必填 | 说明 | + | -------- | ------------------------- | ---- | -------------- | + | callback | AsyncCallback<void> | 是 | 异步刷新文件流后的回调函数。 | + +**示例：** + + ```js + let filePath = pathDir + "/test.txt"; + let ss= fs.createStreamSync(filePath, "r+"); + ss.flush(function (err) { + if (err) { + console.info("flush stream failed with error message: " + err.message + ", error code: " + err.code); + } else { + console.info("flush success"); + } + }); + ``` + +### flushSync + +flushSync(): void + +同步刷新文件流。 + +**系统能力**：SystemCapability.FileManagement.File.FileIO + +**示例：** + + ```js + let filePath = pathDir + "/test.txt"; + let ss= fs.createStreamSync(filePath, "r+"); + ss.flushSync(); + ``` + +### write + +write(buffer: ArrayBuffer|string, options?: { offset?: number; length?: number; encoding?: string; }): Promise<number> + +将数据写入流文件，使用Promise异步回调。 + +**系统能力**：SystemCapability.FileManagement.File.FileIO + +**参数：** + + | 参数名 | 类型 | 必填 | 说明 | + | ------- | ------------------------------- | ---- | ---------------------------------------- | + | buffer | ArrayBuffer\|string | 是 | 待写入文件的数据，可来自缓冲区或字符串。 | + | options | Object | 否 | 支持如下选项：
- length，number类型，表示期望写入数据的长度。默认缓冲区长度。
- offset，number类型，表示期望写入文件的位置。可选，默认从当前位置开始写。
- encoding，string类型，当数据是string类型时有效，表示数据的编码方式，默认 'utf-8'。仅支持 'utf-8'。| + +**返回值：** + + | 类型 | 说明 | + | --------------------- | -------- | + | Promise<number> | Promise对象。返回实际写入的长度。 | + +**示例：** + + ```js + let filePath = pathDir + "/test.txt"; + let ss= fs.createStreamSync(filePath, "r+"); + ss.write("hello, world",{ offset: 5, length: 5, encoding: 'utf-8' }).then(function (number) { + console.info("write succeed and size is:" + number); + }).catch(function (err) { + console.info("write failed with error message: " + err.message + ", error code: " + err.code); + }); + ``` + + +### write + +write(buffer: ArrayBuffer|string, options?: { offset?: number; length?: number; encoding?: string; }, callback: AsyncCallback<number>): void + +将数据写入流文件，使用callback异步回调。 + +**系统能力**：SystemCapability.FileManagement.File.FileIO + +**参数：** + + | 参数名 | 类型 | 必填 | 说明 | + | -------- | ------------------------------- | ---- | ------------------------------------------------------------ | + | buffer | ArrayBuffer\|string | 是 | 待写入文件的数据，可来自缓冲区或字符串。 | + | options | Object | 否 | 支持如下选项：
- length，number类型，表示期望写入数据的长度。可选，默认缓冲区长度。
- offset，number类型，表示期望写入文件的位置。可选，默认从当前位置开始写。
- encoding，string类型，当数据是string类型时有效，表示数据的编码方式，默认 'utf-8'。仅支持 'utf-8'。| + | callback | AsyncCallback<number> | 是 | 异步写入完成后执行的回调函数。 | + +**示例：** + + ```js + let filePath = pathDir + "/test.txt"; + let ss= fs.createStreamSync(filePath, "r+"); + ss.write("hello, world", { offset: 5, length: 5, encoding :'utf-8'}, function (err, bytesWritten) { + if (err) { + console.info("write stream failed with error message: " + err.message + ", error code: " + err.code); + } else { + if (bytesWritten) { + console.info("write succeed and size is:" + bytesWritten); + } + } + }); + ``` + +### writeSync + +writeSync(buffer: ArrayBuffer|string, options?: { offset?: number; length?: number; encoding?: string; }): number + +以同步方法将数据写入流文件。 + +**系统能力**：SystemCapability.FileManagement.File.FileIO + +**参数：** + + | 参数名 | 类型 | 必填 | 说明 | + | ------- | ------------------------------- | ---- | ---------------------------------------- | + | buffer | ArrayBuffer\|string | 是 | 待写入文件的数据，可来自缓冲区或字符串。 | + | options | Object | 否 | 支持如下选项：
- length，number类型，表示期望写入数据的长度。可选，默认缓冲区长度。
- offset，number类型，表示期望写入文件的位置。可选，默认从当前位置开始写。
- encoding，string类型，当数据是string类型时有效，表示数据的编码方式，默认 'utf-8'。仅支持 'utf-8'。| + +**返回值：** + + | 类型 | 说明 | + | ------ | -------- | + | number | 实际写入的长度。 | + +**示例：** + + ```js + let filePath = pathDir + "/test.txt"; + let ss= fs.createStreamSync(filePath,"r+"); + let num = ss.writeSync("hello, world", {offset: 5, length: 5, encoding :'utf-8'}); + ``` + +### read + +read(buffer: ArrayBuffer, options?: { offset?: number; length?: number; }): Promise<number> + +从流文件读取数据，使用Promise异步回调。 + +**系统能力**：SystemCapability.FileManagement.File.FileIO + +**参数：** + + | 参数名 | 类型 | 必填 | 说明 | + | ------- | ----------- | ---- | ---------------------------------------- | + | buffer | ArrayBuffer | 是 | 用于读取文件的缓冲区。 | + | options | Object | 否 | 支持如下选项：
- length，number类型，表示期望读取数据的长度。可选，默认缓冲区长度。
- offset，number类型，表示期望读取文件的位置。可选，默认从当前位置开始读。 | + +**返回值：** + + | 类型 | 说明 | + | ---------------------------------- | ------ | + | Promise<number> | Promise对象。返回读取的结果。 | + +**示例：** + + ```js + let filePath = pathDir + "/test.txt"; + let ss = fs.createStreamSync(filePath, "r+"); + let buf = new ArrayBuffer(4096); + ss.read(buf, {offset: 5, length: 5}).then(function (readLen) { + console.info("read data succeed"); + console.log(String.fromCharCode.apply(null, new Uint8Array(buf))); + }).catch(function (err) { + console.info("read data failed with error message: " + err.message + ", error code: " + err.code); + }); + ``` + + +### read + +read(buffer: ArrayBuffer, options?: { position?: number; offset?: number; length?: number; }, callback: AsyncCallback<number>): void + +从流文件读取数据，使用callback异步回调。 + +**系统能力**：SystemCapability.FileManagement.File.FileIO + +**参数：** + + | 参数名 | 类型 | 必填 | 说明 | + | -------- | ---------------------------------------- | ---- | ---------------------------------------- | + | buffer | ArrayBuffer | 是 | 用于读取文件的缓冲区。 | + | options | Object | 否 | 支持如下选项：
- length，number类型，表示期望读取数据的长度。可选，默认缓冲区长度。
- offset，number类型，表示期望读取文件的位置。可选，默认从当前位置开始读. | + | callback | AsyncCallback<number> | 是 | 异步从流文件读取数据之后的回调。 | + +**示例：** + + ```js + let filePath = pathDir + "/test.txt"; + let ss = fs.createStreamSync(filePath, "r+"); + let buf = new ArrayBuffer(4096) + ss.read(buf, {offset: 5, length: 5},function (err, readLen) { + if (err) { + console.info("read stream failed with error message: " + err.message + ", error code: " + err.code); + } else { + console.info("read data succeed"); + console.log(String.fromCharCode.apply(null, new Uint8Array(buf))); + } + }); + ``` + +### readSync + +readSync(buffer: ArrayBuffer, options?: { offset?: number; length?: number; }): number + +以同步方法从流文件读取数据。 + +**系统能力**：SystemCapability.FileManagement.File.FileIO + +**参数：** + + | 参数名 | 类型 | 必填 | 说明 | + | ------- | ----------- | ---- | ---------------------------------------- | + | buffer | ArrayBuffer | 是 | 用于读取文件的缓冲区。 | + | options | Object | 否 | 支持如下选项：
- length，number类型，表示期望读取数据的长度。可选，默认缓冲区长度。
- offset，number类型，表示期望读取文件的位置。可选，默认从当前位置开始读。
| + +**返回值：** + + | 类型 | 说明 | + | ------ | -------- | + | number | 实际读取的长度。 | + +**示例：** + + ```js + let filePath = pathDir + "/test.txt"; + let ss = fs.createStreamSync(filePath, "r+"); + let num = ss.readSync(new ArrayBuffer(4096), {offset: 5, length: 5}); + ``` + +## File + +由open接口打开的File对象。 + +**系统能力**：SystemCapability.FileManagement.File.FileIO + +### 属性 + +| 名称 | 类型 | 可读 | 可写 | 说明 | +| ---- | ------ | ---- | ---- | ------- | +| fd | number | 是 | 否 | 打开的文件描述符。 | + +## OpenMode + +open接口flags参数常量。文件打开标签。 + +**系统能力**：SystemCapability.FileManagement.File.FileIO + +| 名称 | 类型 | 值 | 说明 | +| ---- | ------ |---- | ------- | +| READ_ONLY | number | 0o0 | 只读打开。 | +| WRITE_ONLY | number | 0o1 | 只写打开。 | +| READ_WRITE | number | 0o2 | 读写打开。 | +| CREATE | number | 0o100 | 若文件不存在，则创建文件。 | +| TRUNC | number | 0o1000 | 如果文件存在且以只写或读写的方式打开文件，则将其长度裁剪为零。 | +| APPEND | number | 0o2000 | 以追加方式打开，后续写将追加到文件末尾。 | +| NONBLOCK | number | 0o4000 | 如果path指向FIFO、块特殊文件或字符特殊文件，则本次打开及后续 IO 进行非阻塞操作。 | +| DIR | number | 0o200000 | 如果path不指向目录，则出错。 | +| NOFOLLOW | number | 0o400000 | 如果path指向符号链接，则出错。 | +| SYNC | number | 0o4010000 | 以同步IO的方式打开文件。 | diff --git a/zh-cn/application-dev/reference/apis/js-apis-file-hash.md b/zh-cn/application-dev/reference/apis/js-apis-file-hash.md new file mode 100644 index 0000000000000000000000000000000000000000..0405e3943eb4768af1a592889937b37796ba2cdd --- /dev/null +++ b/zh-cn/application-dev/reference/apis/js-apis-file-hash.md @@ -0,0 +1,102 @@ +# @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); + } + }); + ``` diff --git a/zh-cn/application-dev/reference/apis/js-apis-securityLabel.md b/zh-cn/application-dev/reference/apis/js-apis-file-securityLabel.md similarity index 69% rename from zh-cn/application-dev/reference/apis/js-apis-securityLabel.md rename to zh-cn/application-dev/reference/apis/js-apis-file-securityLabel.md index c221b64c540e94da3b3d9bcc24980f51c823a551..4d725ba3edf970a79ab274bfb9a3d9aac5f3decb 100644 --- a/zh-cn/application-dev/reference/apis/js-apis-securityLabel.md +++ b/zh-cn/application-dev/reference/apis/js-apis-file-securityLabel.md @@ -1,28 +1,46 @@ -# @ohos.securityLabel (数据标签) +# @ohos.file.securityLabel (数据标签) 该模块提供文件数据安全等级的相关功能：向应用程序提供查询、设置文件数据安全等级的JS接口。 -> ![icon-note.gif](public_sys-resources/icon-note.gif) **说明：** +> **说明：** > 本模块首批接口从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> **示例：** ```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); ``` diff --git a/zh-cn/application-dev/reference/apis/js-apis-file-statvfs.md b/zh-cn/application-dev/reference/apis/js-apis-file-statvfs.md new file mode 100644 index 0000000000000000000000000000000000000000..99b8602eef0638f89cb1f6d239a00b0893113df9 --- /dev/null +++ b/zh-cn/application-dev/reference/apis/js-apis-file-statvfs.md @@ -0,0 +1,131 @@ +# @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); + } + }); + ``` + diff --git a/zh-cn/application-dev/reference/apis/js-apis-fileio.md b/zh-cn/application-dev/reference/apis/js-apis-fileio.md index d298a50b4346f29802267f447a051e1f007a426e..ccf923eea852415bade810a291241376bbf2de0a 100644 --- a/zh-cn/application-dev/reference/apis/js-apis-fileio.md +++ b/zh-cn/application-dev/reference/apis/js-apis-fileio.md @@ -4,7 +4,7 @@ > ![icon-note.gif](public_sys-resources/icon-note.gif) **说明：** > 本模块首批接口从API version 6开始支持。后续版本的新增接口，采用上角标单独标记接口的起始版本。 - +> 本模块自API 9开始废弃，建议使用[@ohos.file.fs](./js-apis-file-fs.md)替代。 ## 导入模块 diff --git a/zh-cn/application-dev/reference/apis/js-apis-statfs.md b/zh-cn/application-dev/reference/apis/js-apis-statfs.md index e6f51899a61edfee7487cb373eb85e1394f4fb99..e1f3fcc2ef36ca5d36c9abf448b0984bf7b63805 100644 --- a/zh-cn/application-dev/reference/apis/js-apis-statfs.md +++ b/zh-cn/application-dev/reference/apis/js-apis-statfs.md @@ -4,6 +4,7 @@ > ![icon-note.gif](public_sys-resources/icon-note.gif) **说明：** > 本模块首批接口从API version 8开始支持。后续版本的新增接口，采用上角标单独标记接口的起始版本。 +> 本模块自API 9开始废弃，建议使用[@ohos.file.statvfs](./js-apis-file-statvfs.md)替代。 ## 导入模块 diff --git a/zh-cn/application-dev/reference/errorcodes/errorcode-filemanagement.md b/zh-cn/application-dev/reference/errorcodes/errorcode-filemanagement.md index 7aa2737352a8f203cf7c169df3aab22b7225a1a2..d9af0b188582db333768b05a65c43b5a46ca303f 100644 --- a/zh-cn/application-dev/reference/errorcodes/errorcode-filemanagement.md +++ b/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); +} +```