From 4f26f8c0e86b8e317663957498b2ce137aec56a0 Mon Sep 17 00:00:00 2001 From: swx1134754 Date: Tue, 7 Mar 2023 19:06:43 +0800 Subject: [PATCH] md modify Signed-off-by: swx1134754 --- README_zh.md | 203 ++++++++++++++++++++++----------------------------- 1 file changed, 86 insertions(+), 117 deletions(-) diff --git a/README_zh.md b/README_zh.md index 72a398d75..abdb17ddd 100644 --- a/README_zh.md +++ b/README_zh.md @@ -13,11 +13,11 @@ ## 简介 -文件访问接口当前向应用程序提供用于的 IO 的 JS 接口。其具体包括用于管理文件的基本文件接口，用于管理目录的基本目录接口，用于获取文件信息的统计接口，用于流式读写文件的流式接口，以及接收 URI 而非绝对路径的沙盒接口。 +文件访问接口提供基础文件IO操作能力，其具体包括用于管理文件的基本文件接口，管理目录的基本目录接口，获取文件信息的统计接口，流式读写文件的流式接口，以及文件锁接口。 ### 系统架构 -文件访问接口仅面向应用提供本地 JS 文件接口，这些接口分别通过 FileIO 模块以及 File 模块提供。架构上，文件访问接口实现了自研的 LibN，其抽象了 NAPI 层接口，向文件访问接口提供包括基本类型系统、内存管理、通用编程模型在内的基本能力。本系统对外依赖 JS 开发框架提供将 JS 接口转换为 C++ 代码的能力，依赖用户程序框架提供应用相关目录，依赖 GLIBC Runtimes 提供 IO 能力。 +文件访问接口仅面向应用程序提供应用文件访问能力，其由ohos.file.fs模块、ohos.file.statvfs模块、ohos.file.hash模块、ohos.file.securityLabel模块和ohos.file.environment模块组成。架构上，文件访问接口实现了自研的 LibN，其抽象了 NAPI 层接口，向文件访问接口提供包括基本类型系统、内存管理、通用编程模型在内的基本能力。 **图 1** 文件访问接口架构图 ![](figures/file-api-架构图.png "file-api-架构图") @@ -62,101 +62,93 @@ foundation/filemanagement/file_api

基本文件接口

-

需要用户提供绝对路径或文件描述符（fd），提供创建、修改及访问文件，或修改文件权限的能力

+

需要用户提供沙箱路径或文件描述符（fd），提供创建、修改及访问文件的能力

-

@ohos.fileio

+

@ohos.file.fs

accessSync

-

chownSync

-

chmodSync

+

access

+

openSync

+

open

+

moveFileSync

+

moveFile

-

基本目录接口

+

获取目录项

-

需要用户提供绝对路径，提供读取目录及判断文件类型的能力

+

需要用户提供沙箱路径，提供读取目录及过滤目录文件的能力

-

@ohos.fileio

+

@ohos.file.fs

-

Dir.openDirSync

+

listFileSync

+

listFile

-

基本Stat接口

+

获取文件信息接口

-

需要用户提供绝对路径，提供包括文件大小、访问权限、修改时间在内的基本统计信息

+

需要用户提供沙箱路径，提供包括文件大小、访问权限、修改时间在内的基本统计信息

-

@ohos.fileio

+

@ohos.file.fs

-

Stat.statSync

+

statSync

+

stat

-

流式文件接口

+

流接口

-

需要用户提供绝对路径或文件描述符，提供流式读写文件的能力

+

需要用户提供沙箱路径或文件描述符，提供流式读写文件的能力

-

@ohos.fileio

+

@ohos.file.fs

-

Stream.createStreamSync

-

Stream.fdopenStreamSync

+

createStreamSync

+

createStream

+

fdopenStreamSync

+

fdopenStream

-

沙盒文件接口

+

文件锁接口

-

需要用户提供 URI，提供基本文件接口、基本目录接口及基本统计接口能力的子集能力，或这些能力的组合能力

+

提供文件阻塞式、非阻塞式施加共享锁或独占锁，及解锁的能力

-

@system.file

+

@ohos.file.fs

-

move

-

copy

-

list

+

lock

+

tryLock

+

unlock

-其中，沙盒文件接口所使用的 URI 具体可划分为三种类型： +open接口可以指定mode参数以打开相应功能权限，说明如下： -**表 2** URI类型表 +**表 2** OpenMode类型表 - - - - - - - - - - - - - - - - - - - - - - - -

目录类型

-

路径前缀

-

访问可见性

-

说明

-

临时目录

-

internal://cache/

-

仅本应用可见

-

可读写，随时可能清除，不保证持久性。一般用作下载临时目录或缓存目录。

-

应用私有目录

-

internal://app/

-

仅本应用可见

-

随应用卸载删除。

-

外部存储

-

internal://share/

-

所有应用可见

-

随应用卸载删除。其他应用在有相应权限的情况下可读写此目录下的文件。

-
+| 名称 | 类型 | 值 | 说明 | +| ---- | ------ |---- | ------- | +| 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的方式打开文件。 | + +文件过滤配置项类型，支持listFile接口使用，说明如下： + +**表 3** Filter + +| 名称 | 类型 | 说明 | +| ----------- | --------------- | ------------------ | +| suffix | Array<string> | 文件后缀名完全匹配，各个关键词OR关系。 | +| displayName | Array<string> | 文件名模糊匹配，各个关键词OR关系。 | +| mimeType | Array<string> | mime类型完全匹配，各个关键词OR关系。 | +| fileSizeOver | number | 文件大小匹配，大于等于指定大小的文件。 | +| lastModifiedAfter | number | 文件最近修改时间匹配，在指定时间点及之后的文件。 | +| excludeMedia | boolean | 是否排除Media中已有的文件。 | ### 使用说明 @@ -166,19 +158,16 @@ foundation/filemanagement/file_api 名称包含 Sync 的接口实现为同步模型。用户在调用这些接口的时候，将同步等待，直至执行完成，执行结果以函数返回值的形式返回。 - 下例以只读的方式打开一个文件流，接着试图读取其中前 4096 个字节并将之转换为 UTF-8 编码的字符串，最后关闭该文件流。 + 下例以只读的方式打开一个文件，接着试图读取其中前 4096 个字节，最后关闭该文件。 ``` - import fileio from '@ohos.fileio'; + import fs from '@ohos.file.fs'; try { - var ss = fileio.createStreamSync("tmp", "r") - buf = new ArrayBuffer(4096) - ss.readSync(buf) - console.log(String.fromCharCode.apply(null, new Uint8Array(buf))) - ss.closeSync() - } - catch (e) { + let file = fs.openSync("test.txt", fs.OpenMode.READ_ONLY); + let readlen = fs.readSync(file.fd, new ArrayBuffer(4096)); + fs.closeSync(file); + } catch (e) { console.log(e); } ``` @@ -186,66 +175,46 @@ foundation/filemanagement/file_api - 异步编程模型：Promise - @ohos.fileio 模块中，名称不含 Sync 的接口，在不提供最后一个函数型参数 callback 的时候，即实现为 Promsie 异步模型。Promise 异步模型是 OHOS 标准异步模型之一。用户在调用这些接口的时候，接口实现将异步执行任务，同时返回一个 promise 对象，其代表异步操作的结果。在返回的结果的个数超过一个时，其以对象属性的形式返回。 + @ohos.file.fs 模块中，名称不含 Sync 的接口，在不提供最后一个函数型参数 callback 的时候，即实现为 Promsie 异步模型。Promise 异步模型是 OHOS 标准异步模型之一。用户在调用这些接口的时候，接口实现将异步执行任务，同时返回一个 promise 对象，其代表异步操作的结果。在返回的结果的个数超过一个时，其以对象属性的形式返回。 - 下例通过 Promise 链依次完成：以只读方式打开文件流、尝试读取文件前 4096 个字节、显示读取内容的长度，最后关闭文件。 + 下例通过 Promise 链依次完成：以只读方式打开文件，尝试读取文件前 4096 个字节，最后关闭文件。 ``` - import fileio from '@ohos.fileio'; + import fs from '@ohos.file.fs'; try { - let openedStream - fileio.createStream("test.txt", "r") - .then(function (ss) { - openedStream = ss; - return ss.read(new ArrayBuffer(4096)) - }) - .then(function (res) { - console.log(res.bytesRead); - console.log(String.fromCharCode.apply(null, new Uint8Array(res.buffer))) - return openedStream.close() - }) - .then(function (undefined) { - console.log("Stream is closed") - }) - .catch(function (e) { - console.log(e) - }) + let file = await fs.open("test.txt", fs.OpenMode.READ_ONLY); + fs.read(file.fd, new ArrayBuffer(4096)) + .then((readLen) => { + fs.closeSync(file); + }); } catch (e) { - console.log(e) + console.log(e); } ``` - 异步编程模型：Callback - @ohos.fileio 模块中，名字不含 Sync 的接口，在提供最后一个函数性参数 callback 的时候，即实现为 Callback 异步模型。Callback 异步模型是 OHOS 标准异步模型之一。用户在调用这些接口的时候，接口实现将异步执行任务。任务执行结果以参数的形式提供给用户注册的回调函数。这些参数的第一个是 Error 或 undefined 类型，分别表示执行出错与正常。 + @ohos.file.fs 模块中，名字不含 Sync 的接口，在提供最后一个函数性参数 callback 的时候，即实现为 Callback 异步模型。Callback 异步模型是 OHOS 标准异步模型之一。用户在调用这些接口的时候，接口实现将异步执行任务。任务执行结果以参数的形式提供给用户注册的回调函数。这些参数的第一个是 Error 或 undefined 类型，分别表示执行出错与正常。 - 下例异步创建文件流，并在文件流的回调函数中异步读取文件的前 4096 字节，接着在读取文件的回调函数中异步关闭文件。 + 下例以只读方式打开文件，并在文件的回调函数中异步读取文件的前 4096 字节，最后关闭文件。 ``` - import fileio from '@ohos.fileio'; + import fs from '@ohos.file.fs'; try { - fileio.createStream("./testdir/test_stream.txt", "r", function (err, ss) { - if (!err) { - ss.read(new ArrayBuffer(4096), {}, function (err, buf, readLen) { - if (!err) { - console.log('readLen: ' + readLen) - console.log('data: ' + String.fromCharCode.apply(null, new Uint8Array(buf))) - } else { - console.log('Cannot read from the stream ' + err) - } - ss.close(function (err) { - console.log(`Stream is ${err ? 'not' : ''}closed`) - }); - }) - } else { - console.log('Cannot open the stream ' + err) + fs.open("test.txt", fs.OpenMode.READ_ONLY, (err, file) => { + if(err) { + console.log('file is not open'); } - }) + fs.read(file.fd, new ArrayBuffer(4096)) + .then((readLen) => { + fs.closeSync(file); + }); + }); } catch (e) { - console.log(e) + console.log(e); } ``` -- Gitee