@wisdomgarden/cloak-plugin-filesystem

v0.0.1

Published

2 days ago

A Filesystem Plugin of Cloak framework(A Hybrid Development Framework for HarmonyOS)

Downloads

中文版 | English Version

Filesystem 插件

用于在 Cloak 应用中读写文件、管理目录。读写范围限于应用自己的沙箱，不需要申请任何权限。

安装

ohpm install @wisdomgarden/cloak-plugin-filesystem

# 可选，用于 TypeScript 类型
npm install @wisdomgarden/cloak-plugin-filesystem

在 EntryAbility.ets 中注册：

import { CloakPluginFilesystem } from '@wisdomgarden/cloak-plugin-filesystem';

onCreate(want: Want, launchParam: AbilityConstant.LaunchParam): void {
  const cloak = new Cloak(this);
  cloak.addPlugins([
    // ... 其他插件
    new CloakPluginFilesystem()
  ]);
}

使用方法

const fs = Cloak.plugins.Filesystem;

// 写文本，recursive 让缺失的父目录自动补上
const { uri } = await fs.writeFile({
  path: 'notes/hello.txt',
  data: 'hello',
  directory: 'DATA',
  encoding: 'utf8',
  recursive: true,
});

// 读回来
const { data } = await fs.readFile({ path: 'notes/hello.txt', directory: 'DATA', encoding: 'utf8' });

// 方法返回的 uri 是绝对沙箱路径，回传时不要再带 directory，否则会被拼到基准目录后面
const info = await fs.stat({ path: uri });

// 不传 encoding 时，data 按 base64 处理，可用于图片等二进制
await fs.writeFile({ path: 'photo.png', data: base64String, directory: 'CACHE' });

// 列目录
const { files } = await fs.readdir({ path: 'notes', directory: 'DATA' });

// 失败时 reject 一个带 code 的错误
try {
  await fs.readFile({ path: 'nope.txt', directory: 'DATA', encoding: 'utf8' });
} catch (e) {
  console.error(e.code, e.message); // OS-PLUG-FILE-0008 ...
}

API

方法失败时 reject 的错误见错误码。

readFile

readFile(options: ReadFileOptions): Promise<ReadFileResult>;

读取文件内容。

| 参数 | 类型 | 必填 | 说明 | |---|---|---|---| | options | ReadFileOptions | 是 | 读取参数 |

返回值：Promise<ReadFileResult>

writeFile

writeFile(options: WriteFileOptions): Promise<WriteFileResult>;

写入文件，已存在则整体覆盖。

| 参数 | 类型 | 必填 | 说明 | |---|---|---|---| | options | WriteFileOptions | 是 | 写入参数 |

返回值：Promise<WriteFileResult>

appendFile

appendFile(options: AppendFileOptions): Promise<void>;

追加到文件末尾，文件不存在则创建，父目录必须已存在。

| 参数 | 类型 | 必填 | 说明 | |---|---|---|---| | options | AppendFileOptions | 是 | 追加参数 |

返回值：Promise<void>

deleteFile

deleteFile(options: DeleteFileOptions): Promise<void>;

删除文件。只能删文件，删目录用 rmdir。

| 参数 | 类型 | 必填 | 说明 | |---|---|---|---| | options | DeleteFileOptions | 是 | 删除参数 |

返回值：Promise<void>

mkdir

mkdir(options: MkdirOptions): Promise<void>;

| 参数 | 类型 | 必填 | 说明 | |---|---|---|---| | options | MkdirOptions | 是 | 建目录参数 |

返回值：Promise<void>

rmdir

rmdir(options: RmdirOptions): Promise<void>;

删除目录。只能删目录，删文件用 deleteFile。

| 参数 | 类型 | 必填 | 说明 | |---|---|---|---| | options | RmdirOptions | 是 | 删目录参数 |

返回值：Promise<void>

readdir

readdir(options: ReaddirOptions): Promise<ReaddirResult>;

列出目录下的直接子项，不递归。

| 参数 | 类型 | 必填 | 说明 | |---|---|---|---| | options | ReaddirOptions | 是 | 列目录参数 |

返回值：Promise<ReaddirResult>

stat

stat(options: StatOptions): Promise<StatResult>;

查询文件或目录的信息。

| 参数 | 类型 | 必填 | 说明 | |---|---|---|---| | options | StatOptions | 是 | 查询参数 |

返回值：Promise<StatResult>

getUri

getUri(options: GetUriOptions): Promise<GetUriResult>;

把路径解析成完整 uri，不校验文件是否存在。

| 参数 | 类型 | 必填 | 说明 | |---|---|---|---| | options | GetUriOptions | 是 | 解析参数 |

返回值：Promise<GetUriResult>

toSandboxPath

toSandboxPath(options: ToSandboxPathOptions): ToSandboxPathResult;

把本插件返回的 uri 转成纯沙箱路径，getUri 的逆操作，不校验文件是否存在。

只有把路径交给 cloak 插件之外的东西时才需要它 —— 本插件和 FileTransfer 的 path 参数两种形态都收。转换必须在原生侧做：鸿蒙的 uri 把包名放在 authority 上（file://<bundleName>/data/...，不是 iOS/Android 的 file:///），JS 侧剥前缀拿不到路径；解析交给系统的 fileUri.FileUri，uri 里若有百分号转义也一并还原。

纯字符串变换，同步返回，不是 Promise。

| 参数 | 类型 | 必填 | 说明 | |---|---|---|---| | options | ToSandboxPathOptions | 是 | 待转换的 uri |

返回值：ToSandboxPathResult

rename

rename(options: RenameOptions): Promise<void>;

重命名或移动文件、目录。目标是已存在的文件时覆盖，是目录时失败；源与目标的类型必须一致；目标的父目录必须已存在。

| 参数 | 类型 | 必填 | 说明 | |---|---|---|---| | options | RenameOptions | 是 | 源与目标路径 |

返回值：Promise<void>

copy

copy(options: CopyOptions): Promise<CopyResult>;

复制文件或目录。目标是已存在的文件时覆盖，是目录时失败；源与目标的类型必须一致；目标的父目录必须已存在。

| 参数 | 类型 | 必填 | 说明 | |---|---|---|---| | options | CopyOptions | 是 | 源与目标路径 |

返回值：Promise<CopyResult>

接口

ReadFileOptions

| 字段 | 类型 | 必填 | 默认值 | 说明 | |---|---|---|---|---| | path | string | 是 | — | 要读取的文件，相对 directory 的路径；不传 directory 时为绝对沙箱路径 | | directory | Directory | 否 | — | 从哪个基准目录下读取 | | encoding | Encoding | 否 | — | 读取用的编码，不传则按二进制读出并返回 base64 | | offset | number | 否 | 0 | 从文件头跳过的字节数，负数报错 | | length | number | 否 | — | 从 offset 起最多读取的字节数，非正数表示读到末尾；剩余不足时只返回剩下的部分 |

ReadFileResult

| 字段 | 类型 | 说明 | |---|---|---| | data | string | 文件内容，encoding 为 utf8 时是文本，否则是 base64 |

WriteFileOptions

| 字段 | 类型 | 必填 | 默认值 | 说明 | |---|---|---|---|---| | path | string | 是 | — | 要写入的文件，相对 directory 的路径；不传 directory 时为绝对沙箱路径 | | data | string | 是 | — | 写入的内容，encoding 为 utf8 时是文本，否则必须是合法 base64，可以带 data:<type>;base64, 前缀 | | directory | Directory | 否 | — | 写到哪个基准目录下 | | encoding | Encoding | 否 | — | 写入用的编码，不传则把 data 按 base64 解码后写入 | | recursive | boolean | 否 | false | 父目录缺失时是否自动创建 |

WriteFileResult

| 字段 | 类型 | 说明 | |---|---|---| | uri | string | 写入文件的完整 uri，以 file:// 开头 |

AppendFileOptions

| 字段 | 类型 | 必填 | 说明 | |---|---|---|---| | path | string | 是 | 要追加的文件，相对 directory 的路径；不传 directory 时为绝对沙箱路径 | | data | string | 是 | 追加的内容，encoding 为 utf8 时是文本，否则必须是合法 base64，可以带 data:<type>;base64, 前缀 | | directory | Directory | 否 | 追加到哪个基准目录下的文件 | | encoding | Encoding | 否 | 追加用的编码，不传则把 data 按 base64 解码后追加 |

DeleteFileOptions

| 字段 | 类型 | 必填 | 说明 | |---|---|---|---| | path | string | 是 | 要删除的文件，相对 directory 的路径；不传 directory 时为绝对沙箱路径 | | directory | Directory | 否 | 从哪个基准目录下删除 |

MkdirOptions

| 字段 | 类型 | 必填 | 默认值 | 说明 | |---|---|---|---|---| | path | string | 是 | — | 要创建的目录，相对 directory 的路径；不传 directory 时为绝对沙箱路径 | | directory | Directory | 否 | — | 在哪个基准目录下创建 | | recursive | boolean | 否 | false | 是否逐级创建缺失的父目录 |

RmdirOptions

| 字段 | 类型 | 必填 | 默认值 | 说明 | |---|---|---|---|---| | path | string | 是 | — | 要删除的目录，相对 directory 的路径；不传 directory 时为绝对沙箱路径 | | directory | Directory | 否 | — | 从哪个基准目录下删除 | | recursive | boolean | 否 | false | 是否连同目录里的内容一起删除 |

ReaddirOptions

| 字段 | 类型 | 必填 | 说明 | |---|---|---|---| | path | string | 是 | 要列出的目录，相对 directory 的路径；不传 directory 时为绝对沙箱路径 | | directory | Directory | 否 | 列哪个基准目录下的内容 |

ReaddirResult

| 字段 | 类型 | 说明 | |---|---|---| | files | FileInfo[] | 目录下的直接子项，空目录返回空数组 |

FileInfo

| 字段 | 类型 | 必填 | 说明 | |---|---|---|---| | name | string | 是 | 文件或目录名，不含路径 | | type | 'file' \| 'directory' | 是 | 是文件还是目录 | | size | number | 是 | 文件字节数，目录为 0 | | ctime | number | 否 | 创建时间，毫秒时间戳，鸿蒙上恒有值 | | mtime | number | 是 | 最后修改时间，毫秒时间戳 | | uri | string | 是 | 完整 uri，以 file:// 开头 |

StatOptions

| 字段 | 类型 | 必填 | 说明 | |---|---|---|---| | path | string | 是 | 要查询的文件或目录，相对 directory 的路径；不传 directory 时为绝对沙箱路径 | | directory | Directory | 否 | 查哪个基准目录下的路径 |

GetUriOptions

| 字段 | 类型 | 必填 | 说明 | |---|---|---|---| | path | string | 是 | 要解析的路径，相对 directory 的路径；不传 directory 时为绝对沙箱路径 | | directory | Directory | 否 | 相对哪个基准目录解析 |

GetUriResult

| 字段 | 类型 | 说明 | |---|---|---| | uri | string | 解析出的完整 uri，以 file:// 开头 |

ToSandboxPathOptions

| 字段 | 类型 | 必填 | 说明 | |---|---|---|---| | uri | string | 是 | 待转换的 uri。已经是纯路径的值原样返回，可以重复传 |

ToSandboxPathResult

| 字段 | 类型 | 说明 | |---|---|---| | path | string | 解码后的纯沙箱绝对路径，fileIo 和其他 cloak 插件都收这个 |

CopyOptions

| 字段 | 类型 | 必填 | 说明 | |---|---|---|---| | from | string | 是 | 已存在的文件或目录，相对 directory 的路径；不传 directory 时为绝对沙箱路径 | | to | string | 是 | 目标文件或目录，相对 toDirectory 的路径；不传 toDirectory 与 directory 时为绝对沙箱路径 | | directory | Directory | 否 | from 所在的基准目录 | | toDirectory | Directory | 否 | to 所在的基准目录，不传则与 directory 相同 |

CopyResult

| 字段 | 类型 | 说明 | |---|---|---| | uri | string | 新路径的完整 uri，以 file:// 开头 |

类型别名

StatResult

FileInfo

RenameOptions

CopyOptions

枚举

Encoding

| 成员 | 值 | 说明 | |---|---|---| | UTF8 | 'utf8' | 按文本读写 |

错误码

所有方法失败时 reject 一个 PluginError：code 见下表，message 是可读的失败原因，含出错的方法名与路径。

| code | 说明 | |---|---| | OS-PLUG-FILE-0005 | 必填参数缺失，如没传 path、writeFile 没传 data | | OS-PLUG-FILE-0006 | 路径非法：不传 directory 时 path 不是绝对沙箱路径 | | OS-PLUG-FILE-0007 | 没有权限 | | OS-PLUG-FILE-0008 | 文件或目录不存在，也包括 copy / rename 的源不存在 | | OS-PLUG-FILE-0009 | 操作不被支持：directory / encoding 取值超出支持范围；对目录调 readFile / writeFile / appendFile / deleteFile；对文件调 rmdir / readdir / mkdir；copy / rename 的源与目标一个是文件一个是目录 | | OS-PLUG-FILE-0010 | 目标目录已存在：mkdir 的目标，或 copy / rename 目录时的目标 | | OS-PLUG-FILE-0011 | 父目录不存在：mkdir / writeFile 未传 recursive: true，或 appendFile / copy / rename 的目标父目录缺失 | | OS-PLUG-FILE-0012 | rmdir 的目标目录非空，且未传 recursive: true | | OS-PLUG-FILE-0013 | 其余失败，例如 data 不是合法 base64，message 里带原始错误信息 |

关于 Cloak

Cloak 是专为 HarmonyOS 设计的混合开发框架，类似 Cordova 和 Capacitor，但具备 更轻量、更高性能 的特性。

该框架可将 Web 应用快速转换为原生应用，同时通过插件机制访问 HarmonyOS 原生能力。

核心特性

快速打包：将 H5 应用快速编译为 HarmonyOS 应用。
原生能力访问：通过插件机制调用原生接口。
WebView 支持：提供高性能 WebView 容器，确保 H5 应用流畅运行。
插件开发：支持开发者自定义插件以扩展原生功能。

更多关于 Cloak 框架信息，请查看: https://github.com/WisdomGardenInc/Cloak

Published

Vulnerabilities

Links

Maintainers

Keywords

Readme

Filesystem 插件

安装

使用方法

API

readFile

writeFile

appendFile

deleteFile

mkdir

rmdir

readdir

stat

getUri

toSandboxPath

rename

copy

接口

ReadFileOptions

ReadFileResult

WriteFileOptions

WriteFileResult

AppendFileOptions

DeleteFileOptions

MkdirOptions

RmdirOptions

ReaddirOptions

ReaddirResult

FileInfo

StatOptions

GetUriOptions

GetUriResult

ToSandboxPathOptions

ToSandboxPathResult

CopyOptions

CopyResult

类型别名

StatResult

RenameOptions

枚举

Directory

Encoding

错误码

关于 Cloak

核心特性