Skip to content

D
Docs

OpenHarmony / Docs
11 个月 前同步成功

通知 159
Star 292
Fork 28
D
Docs

体验新版 GitCode，发现更多精彩内容 >>

未验证 提交 e9e2bc1c 编写于 作者: O openharmony_ci 提交者： Gitee
浏览文件
操作

!20871 fs DOC 增加 randomAccessFile 

Merge pull request !20871 from yangjingbo/doc_add_randomAccess
上级 46d5dc82 a8733ce7
隐藏空白更改
内联 并排
Showing with 383 addition and 0 deletion
zh-cn/application-dev/reference/apis/js-apis-file-fs.md
浏览文件 @ e9e2bc1c
......@@ -2285,6 +2285,111 @@ mkdtempSync(prefix: string): string
let res = fs.mkdtempSync(pathDir + "/XXXXXX");
```
## fs.createRandomAccessFile<sup>10+</sup>
createRandomAccessFile(file: string|File, mode?: string): Promise&lt;RandomAccessFile&gt;
基于文件路径或文件对象创建RandomAccessFile文件对象，使用Promise异步回调。
**系统能力**：SystemCapability.FileManagement.File.FileIO
**参数：**
| 参数名 | 类型 | 必填 | 说明 |
| ------------ | ------ | ------ | ------------------------------------------------------------ |
| file | string\|[File](#file) | 是 | 文件的应用沙箱路径或已打开的File对象 |
| mode | number | 否 | 创建文件RandomAccessFile对象的[选项](#openmode)，仅当传入文件沙箱路径时生效，必须指定如下选项中的一个，默认以只读方式创建：<br/>-&nbsp;OpenMode.READ_ONLY(0o0)：只读创建。<br/>-&nbsp;OpenMode.WRITE_ONLY(0o1)：只写创建。<br/>-&nbsp;OpenMode.READ_WRITE(0o2)：读写创建。<br/>给定如下功能选项，以按位或的方式追加，默认不给定任何额外选项：<br/>-&nbsp;OpenMode.CREATE(0o100)：若文件不存在，则创建文件。<br/>-&nbsp;OpenMode.TRUNC(0o1000)：如果RandomAccessFile对象存在且以只写或读写的方式创建文件，则将其长度裁剪为零。<br/>-&nbsp;OpenMode.APPEND(0o2000)：以追加方式打开，后续写将追加到RandomAccessFile对象末尾。<br/>-&nbsp;OpenMode.NONBLOCK(0o4000)：如果path指向FIFO、块特殊文件或字符特殊文件，则本次打开及后续&nbsp;IO&nbsp;进行非阻塞操作。<br/>-&nbsp;OpenMode.DIR(0o200000)：如果path不指向目录，则出错。<br/>-&nbsp;OpenMode.NOFOLLOW(0o400000)：如果path指向符号链接，则出错。<br/>-&nbsp;OpenMode.SYNC(0o4010000)：以同步IO的方式创建RandomAccessFile对象。 |
**返回值：**
| 类型 | 说明 |
| --------------------------------- | --------- |
| Promise&lt;[RandomAccessFile](#randomaccessfile)&gt; | Promise对象。返回RandomAccessFile文件对象的结果。 |
**错误码：**
接口抛出错误码的详细介绍请参见[基础文件IO错误码](../errorcodes/errorcode-filemanagement.md#基础文件io错误码)。
**示例：**
```js
let filePath = pathDir + "/test.txt";
let file = fs.openSync(filePath, fs.OpenMode.CREATE | fs.OpenMode.READ_WRITE);
fs.createRandomAccessFile(file).then((randomAccessFile) => {
console.info("randomAccessFile fd: " + randomAccessFile.fd);
}).catch((err) => {
console.info("create randomAccessFile failed with error message: " + err.message + ", error code: " + err.code);
});
```
## fs.createRandomAccessFile<sup>10+</sup>
createRandomAccessFile(file: string|File, mode?: string, callback: AsyncCallback&lt;RandomAccessFile&gt;): void
基于文件路径或文件对象创建RandomAccessFile文件对象，使用callback异步回调。
**系统能力**：SystemCapability.FileManagement.File.FileIO
**参数：**
| 参数名 | 类型 | 必填 | 说明 |
| ------------ | ------ | ------ | ------------------------------------------------------------ |
| file | string\|[File](#file) | 是 | 文件的应用沙箱路径或已打开的File对象 |
| mode | number | 否 | 创建文件RandomAccessFile对象的[选项](#openmode)，仅当传入文件沙箱路径时生效，必须指定如下选项中的一个，默认以只读方式创建：<br/>-&nbsp;OpenMode.READ_ONLY(0o0)：只读创建。<br/>-&nbsp;OpenMode.WRITE_ONLY(0o1)：只写创建。<br/>-&nbsp;OpenMode.READ_WRITE(0o2)：读写创建。<br/>给定如下功能选项，以按位或的方式追加，默认不给定任何额外选项：<br/>-&nbsp;OpenMode.CREATE(0o100)：若文件不存在，则创建文件。<br/>-&nbsp;OpenMode.TRUNC(0o1000)：如果RandomAccessFile对象存在且以只写或读写的方式创建文件，则将其长度裁剪为零。<br/>-&nbsp;OpenMode.APPEND(0o2000)：以追加方式打开，后续写将追加到RandomAccessFile对象末尾。<br/>-&nbsp;OpenMode.NONBLOCK(0o4000)：如果path指向FIFO、块特殊文件或字符特殊文件，则本次打开及后续&nbsp;IO&nbsp;进行非阻塞操作。<br/>-&nbsp;OpenMode.DIR(0o200000)：如果path不指向目录，则出错。<br/>-&nbsp;OpenMode.NOFOLLOW(0o400000)：如果path指向符号链接，则出错。<br/>-&nbsp;OpenMode.SYNC(0o4010000)：以同步IO的方式创建RandomAccessFile对象。 |
| callback | AsyncCallback&lt;[RandomAccessFile](#randomaccessfile)&gt; | 是 | 异步创建RandomAccessFile对象之后的回调。 |
**错误码：**
接口抛出错误码的详细介绍请参见[基础文件IO错误码](../errorcodes/errorcode-filemanagement.md#基础文件io错误码)。
**示例：**
```js
let filePath = pathDir + "/test.txt";
let file = fs.openSync(filePath, fs.OpenMode.CREATE | fs.OpenMode.READ_WRITE);
fs.createRandomAccessFile(file, (err, randomAccessFile) => {
if (err) {
console.info("create randomAccessFile failed with error message: " + err.message + ", error code: " + err.code);
} else {
console.info("randomAccessFilefile fd: " + randomAccessFile.fd);
}
});
```
## fs.createRandomAccessFileSync<sup>10+</sup>
createRandomAccessFileSync(file: string|File, , mode?: string): RandomAccessFile
基于文件路径或文件对象创建RandomAccessFile文件对象。
**系统能力**：SystemCapability.FileManagement.File.FileIO
**参数：**
| 参数名 | 类型 | 必填 | 说明 |
| ------------ | ------ | ------ | ------------------------------------------------------------ |
| file | string\|[File](#file) | 是 | 文件的应用沙箱路径或已打开的File对象 |
| mode | number | 否 | 创建文件RandomAccessFile对象的[选项](#openmode)，仅当传入文件沙箱路径时生效，必须指定如下选项中的一个，默认以只读方式创建：<br/>-&nbsp;OpenMode.READ_ONLY(0o0)：只读创建。<br/>-&nbsp;OpenMode.WRITE_ONLY(0o1)：只写创建。<br/>-&nbsp;OpenMode.READ_WRITE(0o2)：读写创建。<br/>给定如下功能选项，以按位或的方式追加，默认不给定任何额外选项：<br/>-&nbsp;OpenMode.CREATE(0o100)：若文件不存在，则创建文件。<br/>-&nbsp;OpenMode.TRUNC(0o1000)：如果RandomAccessFile对象存在且以只写或读写的方式创建文件，则将其长度裁剪为零。<br/>-&nbsp;OpenMode.APPEND(0o2000)：以追加方式打开，后续写将追加到RandomAccessFile对象末尾。<br/>-&nbsp;OpenMode.NONBLOCK(0o4000)：如果path指向FIFO、块特殊文件或字符特殊文件，则本次打开及后续&nbsp;IO&nbsp;进行非阻塞操作。<br/>-&nbsp;OpenMode.DIR(0o200000)：如果path不指向目录，则出错。<br/>-&nbsp;OpenMode.NOFOLLOW(0o400000)：如果path指向符号链接，则出错。<br/>-&nbsp;OpenMode.SYNC(0o4010000)：以同步IO的方式创建RandomAccessFile对象。 |
**返回值：**
| 类型 | 说明 |
| ------------------ | --------- |
| [RandomAccessFile](#randomaccessfile) | 返回RandomAccessFile文件对象的结果。 |
**错误码：**
接口抛出错误码的详细介绍请参见[基础文件IO错误码](../errorcodes/errorcode-filemanagement.md#基础文件io错误码)。
**示例：**
```js
let filePath = pathDir + "/test.txt";
let file = fs.openSync(filePath, fileIO.OpenMode.CREATE | fileIO.OpenMode.READ_WRITE);
let randomaccessfile = fileIO.createRandomAccessFileSync(file);
```
## fs.createStream
createStream(path: string, mode: string): Promise&lt;Stream&gt;
......@@ -3273,6 +3378,284 @@ unlock(): void
console.log("unlock file successful");
```
## RandomAccessFile
随机读写文件流，在调用RandomAccessFile的方法前，需要先通过createRandomAccess()方法（同步或异步）来构建一个RandomAccessFile实例。
**系统能力**：SystemCapability.FileManagement.File.FileIO
### 属性
| 名称 | 类型 | 可读 | 可写 | 说明 |
| ----------- | ------ | ---- | ----- | ---------------- |
| fd | number | 是 | 否 | 打开的文件描述符。 |
| filePointer | number | 是 | 是 | RandomAccessFile对象的偏置指针。 |
### setFilePointer<sup>10+</sup>
setFilePointer(): void
设置文件偏置指针
**系统能力**：SystemCapability.FileManagement.File.FileIO
**错误码：**
接口抛出错误码的详细介绍请参见[基础文件IO错误码](../errorcodes/errorcode-filemanagement.md#基础文件io错误码)。
**示例：**
```js
let filePath = pathDir + "/test.txt";
let randomAccessFile = fs.createRandomAccessFileSync(filePath, fs.OpenMode.READ_WRITE | fs.OpenMode.CREATE);
randomAccessFile.setFilePointer(1);
```
### close<sup>10+</sup>
close(): void
同步关闭RandomAccessFile对象。
**系统能力**：SystemCapability.FileManagement.File.FileIO
**错误码：**
接口抛出错误码的详细介绍请参见[基础文件IO错误码](../errorcodes/errorcode-filemanagement.md#基础文件io错误码)。
**示例：**
```js
let filePath = pathDir + "/test.txt";
let randomAccessFile = fs.createRandomAccessFileSync(filePath, fs.OpenMode.READ_WRITE | fs.OpenMode.CREATE);
randomAccessFile.closeSync();
```
### write<sup>10+</sup>
write(buffer: ArrayBuffer|string, options?: { offset?: number; length?: number; encoding?: string; }): Promise&lt;number&gt;
将数据写入文件，使用Promise异步回调。
**系统能力**：SystemCapability.FileManagement.File.FileIO
**参数：**
| 参数名 | 类型 | 必填 | 说明 |
| ------- | ------------------------------- | ---- | ---------------------------------------- |
| buffer | ArrayBuffer\|string | 是 | 待写入文件的数据，可来自缓冲区或字符串。 |
| options | Object | 否 | 支持如下选项：<br/>-&nbsp;length，number类型，表示期望写入数据的长度。默认缓冲区长度。<br/>-&nbsp;offset，number类型，表示期望写入文件位置（基于当前filePointer加上offset的位置）。可选，默认从偏置指针（filePointer）开始写。<br/>-&nbsp;encoding，string类型，当数据是string类型时有效，表示数据的编码方式，默认&nbsp;'utf-8'。仅支持&nbsp;'utf-8'。|
**返回值：**
| 类型 | 说明 |
| --------------------- | -------- |
| Promise&lt;number&gt; | Promise对象。返回实际写入的长度。 |
**错误码：**
接口抛出错误码的详细介绍请参见[基础文件IO错误码](../errorcodes/errorcode-filemanagement.md#基础文件io错误码)。
**示例：**
```js
let filePath = pathDir + "/test.txt";
let file = fs.openSync(fpath, fs.OpenMode.CREATE | fs.OpenMode.READ_WRITE);
let randomaccessfile = fs.createRandomAccessFileSync(file);
let bufferLength = 4096;
randomaccessfile.write(new ArrayBuffer(bufferLength), { offset: 1, length: 5 }).then((bytesWritten) => {
console.info("randomAccessFile bytesWritten: " + bytesWritten);
}).catch((err) => {
console.info("create randomAccessFile failed with error message: " + err.message + ", error code: " + err.code);
});
```
### write<sup>10+</sup>
write(buffer: ArrayBuffer|string, options?: { offset?: number; length?: number; encoding?: string; }, callback: AsyncCallback&lt;number&gt;): void
将数据写入文件，使用callback异步回调。
**系统能力**：SystemCapability.FileManagement.File.FileIO
**参数：**
| 参数名 | 类型 | 必填 | 说明 |
| -------- | ------------------------------- | ---- | ------------------------------------------------------------ |
| buffer | ArrayBuffer\|string | 是 | 待写入文件的数据，可来自缓冲区或字符串。 |
| options | Object | 否 | 支持如下选项：<br/>-&nbsp;length，number类型，表示期望写入数据的长度。可选，默认缓冲区长度。<br/>-&nbsp;offset，number类型，表示期望写入文件位置（基于当前filePointer加上offset的位置）。可选，默认从偏置指针（filePointer）开始写。<br/>-&nbsp;encoding，string类型，当数据是string类型时有效，表示数据的编码方式，默认&nbsp;'utf-8'。仅支持&nbsp;'utf-8'。|
| callback | AsyncCallback&lt;number&gt; | 是 | 异步写入完成后执行的回调函数。 |
**错误码：**
接口抛出错误码的详细介绍请参见[基础文件IO错误码](../errorcodes/errorcode-filemanagement.md#基础文件io错误码)。
**示例：**
```js
let filePath = pathDir + "/test.txt";
let randomAccessFile = fs.createRandomAccessFileSync(file);
let bufferLength = 4096;
randomAccessFile.write(new ArrayBuffer(bufferLength), { offset: 1 }, function(err, bytesWritten) {
if (err) {
console.info("write failed with error message: " + err.message + ", error code: " + err.code);
} else {
if (bytesWritten) {
console.info("write succeed and size is:" + bytesWritten);
}
}
});
```
### writeSync<sup>10+</sup>
writeSync(buffer: ArrayBuffer|string, options?: { offset?: number; length?: number; encoding?: string; }): number
以同步方法将数据写入文件。
**系统能力**：SystemCapability.FileManagement.File.FileIO
**参数：**
| 参数名 | 类型 | 必填 | 说明 |
| ------- | ------------------------------- | ---- | ---------------------------------------- |
| buffer | ArrayBuffer\|string | 是 | 待写入文件的数据，可来自缓冲区或字符串。 |
| options | Object | 否 | 支持如下选项：<br/>-&nbsp;length，number类型，表示期望写入数据的长度。可选，默认缓冲区长度。<br/>-&nbsp;offset，number类型，表示期望写入文件位置（基于当前filePointer加上offset的位置）。可选，默认从偏置指针（filePointer）开始写。<br/>-&nbsp;encoding，string类型，当数据是string类型时有效，表示数据的编码方式，默认&nbsp;'utf-8'。仅支持&nbsp;'utf-8'。|
**返回值：**
| 类型 | 说明 |
| ------ | -------- |
| number | 实际写入的长度。 |
**错误码：**
接口抛出错误码的详细介绍请参见[基础文件IO错误码](../errorcodes/errorcode-filemanagement.md#基础文件io错误码)。
**示例：**
```js
let filePath = pathDir + "/test.txt";
let randomaccessfile= fs.createRandomAccessFileSync(filePath,"r+");
let bytesWritten = randomaccessfile.writeSync("hello, world", {offset: 5, length: 5, encoding :'utf-8'});
```
### read<sup>10+</sup>
read(buffer: ArrayBuffer, options?: { offset?: number; length?: number; }): Promise&lt;number&gt;
从文件读取数据，使用Promise异步回调。
**系统能力**：SystemCapability.FileManagement.File.FileIO
**参数：**
| 参数名 | 类型 | 必填 | 说明 |
| ------- | ----------- | ---- | ---------------------------------------- |
| buffer | ArrayBuffer | 是 | 用于读取文件的缓冲区。 |
| options | Object | 否 | 支持如下选项：<br/>-&nbsp;length，number类型，表示期望读取数据的长度。可选，默认缓冲区长度。<br/>-&nbsp;offset，number类型，表示期望读取文件位置（基于当前filePointer加上offset的位置）。可选，默认从偏置指针（filePointer）开始读。 |
**返回值：**
| 类型 | 说明 |
| ---------------------------------- | ------ |
| Promise&lt;number&gt; | Promise对象。返回读取的结果。 |
**错误码：**
接口抛出错误码的详细介绍请参见[基础文件IO错误码](../errorcodes/errorcode-filemanagement.md#基础文件io错误码)。
**示例：**
```js
let filePath = pathDir + "/test.txt";
let file = fs.openSync(filePath, fs.OpenMode.CREATE | fs.OpenMode.READ_WRITE);
let randomaccessfile = fs.createRandomAccessFileSync(file);
let bufferLength = 4096;
randomaccessfile.read(new ArrayBuffer(bufferLength), { offset: 1, length: 5 }).then((readLength) => {
console.info("randomAccessFile readLength: " + readLength);
}).catch((err) => {
console.info("create randomAccessFile failed with error message: " + err.message + ", error code: " + err.code);
});
```
### read<sup>10+</sup>
read(buffer: ArrayBuffer, options?: { position?: number; offset?: number; length?: number; }, callback: AsyncCallback&lt;number&gt;): void
从文件读取数据，使用callback异步回调。
**系统能力**：SystemCapability.FileManagement.File.FileIO
**参数：**
| 参数名 | 类型 | 必填 | 说明 |
| -------- | ---------------------------------------- | ---- | ---------------------------------------- |
| buffer | ArrayBuffer | 是 | 用于读取文件的缓冲区。 |
| options | Object | 否 | 支持如下选项：<br/>-&nbsp;length，number类型，表示期望读取数据的长度。可选，默认缓冲区长度。<br/>-&nbsp;offset，number类型，表示期望读取文件位置（基于当前filePointer加上offset的位置）。可选，默认从偏置指针（filePointer）开始读. |
| callback | AsyncCallback&lt;number&gt; | 是 | 异步从流文件读取数据之后的回调。 |
**错误码：**
接口抛出错误码的详细介绍请参见[基础文件IO错误码](../errorcodes/errorcode-filemanagement.md#基础文件io错误码)。
**示例：**
```js
let filePath = pathDir + "/test.txt";
let file = fs.openSync(filePath, fs.OpenMode.CREATE | fs.OpenMode.READ_WRITE);
let randomaccessfile = await fileIO.createRandomAccessFile(file);
let length = 20;
randomaccessfile.read(new ArrayBuffer(length), { offset: 1, length: 5 }, function (err, readLength) {
if (err) {
console.info("read failed with error message: " + err.message + ", error code: " + err.code);
} else {
if (readLength) {
console.info("read succeed and size is:" + readLength);
}
}
});
```
### readSync<sup>10+</sup>
readSync(buffer: ArrayBuffer, options?: { offset?: number; length?: number; }): number
以同步方法从文件读取数据。
**系统能力**：SystemCapability.FileManagement.File.FileIO
**参数：**
| 参数名 | 类型 | 必填 | 说明 |
| ------- | ----------- | ---- | ---------------------------------------- |
| buffer | ArrayBuffer | 是 | 用于读取文件的缓冲区。 |
| options | Object | 否 | 支持如下选项：<br/>-&nbsp;length，number类型，表示期望读取数据的长度。可选，默认缓冲区长度。<br/>-&nbsp;offset，number类型，表示期望读取文文件位置（基于当前filePointer加上offset的位置）。可选，默认从偏置指针（filePointer）开始读。<br/> |
**返回值：**
| 类型 | 说明 |
| ------ | -------- |
| number | 实际读取的长度。 |
**错误码：**
接口抛出错误码的详细介绍请参见[基础文件IO错误码](../errorcodes/errorcode-filemanagement.md#基础文件io错误码)。
**示例：**
```js
let filePath = pathDir + "/test.txt";
let file = fs.openSync(filePath, fileIO.OpenMode.CREATE | fileIO.OpenMode.READ_WRITE);
let randomaccessfile = fs.createRandomAccessFileSync(file);
let length = 4096;
let readLength = randomaccessfile.readSync(new ArrayBuffer(length));
```
## Watcher<sup>10+</sup>
文件目录变化监听对象。由createWatcher接口获得。
......
Markdown is supported
0% 或 .
You are about to add 0 people to the discussion. Proceed with caution.
先完成此消息的编辑！
想要评论请 注册 或