@capacitor-ohos/filesystem

v8.0.1

Published

14 days ago

The Filesystem API provides a NodeJS-like API for working with files on the device.

Downloads

135

0High
0Medium
0Low

luqi_tan

capacitor plugin native

@capacitor/filesystem

本项目基于 @capacitor/[email protected] 开发。

简介

@capacitor/filesystem是capacitor生态系统中的核心插件，提供完善的文件API，支持对设备本地文件系统中的文件和目录进行读写操作，为跨平台应用开发提供设备差异化适配能力，兼容Android、iOS等主流移动平台及浏览器环境中使用，本文档只说明在OpenHarmony系统中的使用。

API允许对设备本地文件系统中的文件和目录进行读写操作。

支持平台

OpenHarmony：5.0+

下载安装

通过命令行或手动引入即可快速安装插件，支持从npm仓库获取。

命令行安装（推荐）

安装hionic CLI：

npm install -g hionic

以下两种方式中任选其一即可，无需重复操作：

npm安装：

# 安装插件
npm i @capacitor/filesystem

# 同步插件
hionic sync

hionic CLI安装：

hionic plugin add @capacitor/filesystem

手动引入安装

根据插件源码中 plugin.xml 配置在项目中引入插件：

1. 添加插件配置

根据 plugin.xml 的 config-json 项，通过 target 字段找到 entry 模块中 capacitor.plugins.json 文件，并根据 param 标签添加配置如下：

{
  "pkg": "@capacitor/filesystem",
  "classpath": "Filesystem"
}

2. 修改 CMake 配置

根据 plugin.xml 的 CMakeLists 项，通过 modules-name 字段找到模块 capacitor，路径为 target 字段的 CMakeLists.txt 文件，并根据 param 标签添加 add_subdirectory 和 target_link_libraries 如下：

#START_ADD_SUBDIRECTORY
// ...
add_subdirectory(Filesystem)
// ...
#END_ADD_SUBDIRECTORY

// ...

target_link_libraries(capacitor PUBLIC
  "-Wl,--whole-archive"
  // ...
  Filesystem
  // ...
  "-Wl,--no-whole-archive"
)

3. 复制源码文件

根据 plugin.xml 的 source-file 项，根据 src 字段找到需要复制的文件，并根据 modules-name 字段和 target-dir 字段找到文件复制的具体模块和目录：

将源码中src/main/cpp/Filesystem目录下的Filesystem.h、Filesystem.cpp、CMakeLists.txt文件引入到capacitor模块中src/main/cpp/Filesystem目录下。

将源码中src/main/ets/components/Filesystem目录下的FilesystemAction.ets文件引入到capacitor模块中src/main/ets/components/Filesystem目录下。

4. 添加 ArkTS 配置

在capacitor模块的build-profile.json5文件中，buildOption/arkOptions/runtimeOnly/sources配置项数组中加入步骤 3 中拷贝的 ets 文件路径：

{
  "buildOption": {
    "arkOptions": {
      "runtimeOnly": {
        "sources": [
          "./src/main/ets/components/Filesystem/FilesystemAction.ets"
        ]
      }
    }
  }
}

卸载

# 卸载 filesystem 插件
hionic plugin remove @capacitor/filesystem

约束与限制

兼容性

在以下版本中已测试通过：

capacitor: 8.0.0-ohos-8.0.0; SDK: 5.0.5(17); IDE: DevEco Studio: 6.0.0; ROM: 5.1.0.150;

权限要求

OpenHarmony手机设备不支持公共目录访问，默认使用filesDir目录，该目录读写无需额外申请权限，权限检查与申请接口默认返回granted。

使用示例

示例1：读取文件内容

import { Filesystem, Directory, Encoding } from "@capacitor/filesystem";

const handleReadFile = async () => {
  try {
    const result = await Filesystem.readFile({
      path: 'test.txt',
      directory: Directory.Cache,
      encoding: Encoding.UTF8
    });
    console.log('文件读取成功:', result.data);
  } catch (error) {
    const errorMsg = error instanceof Error ? error.message : String(error);
    console.error('读取文件失败:', errorMsg);
  }
};

示例2：写入文件内容

import { Filesystem, Directory, Encoding } from "@capacitor/filesystem";

const handleWriteFile = async () => {
  try {
    const result = await Filesystem.writeFile({
      path: 'test.txt',
      data: '这是一个测试文件内容！',
      directory: Directory.Cache,
      encoding: Encoding.UTF8
    });
    console.log('文件写入成功:', result);
  } catch (error) {
    const errorMsg = error instanceof Error ? error.message : String(error);
    console.error('文件写入失败:', errorMsg);
  }
};

示例3：删除文件

import { Filesystem, Directory } from "@capacitor/filesystem";

const handleDeleteFile = async () => {
  try {
    const result = await Filesystem.deleteFile({
      path: 'test.txt',
      directory: Directory.Cache
    });
    console.log('文件删除成功:', result);
  } catch (error) {
    const errorMsg = error instanceof Error ? error.message : String(error);
    console.error('删除文件失败:', errorMsg);
  }
};

示例4：创建目录

import { Filesystem, Directory } from "@capacitor/filesystem";

const handleMkdir = async () => {
  try {
    const result = await Filesystem.mkdir({
      path: 'test_dir',
      directory: Directory.Cache
    });
    console.log('目录创建成功:', result);
  } catch (error) {
    const errorMsg = error instanceof Error ? error.message : String(error);
    console.error('创建目录失败:', errorMsg);
  }
};

示例5：获取文件信息

import { Filesystem, Directory } from "@capacitor/filesystem";

const handleStat = async () => {
  try {
    const result = await Filesystem.stat({
      path: 'test.txt',
      directory: Directory.Cache
    });
    console.log('文件信息获取成功:', result);
  } catch (error) {
    const errorMsg = error instanceof Error ? error.message : String(error);
    console.error('获取文件信息失败:', errorMsg);
  }
};

使用说明

Filesystem是插件导出对象，可直接导入使用，导入后即可调用插件提供的所有方法，调用便捷高效，所有API均基于Promise实现，支持异步调用。

| 方法名 | 返回类型 | 描述 | 备注 | |-------------------------------------------------------------------------------------------------------------------------------------------------|--------------------------------------------------------------|---------------|-----------------------------------------------------------------------------------| | checkPermissions() | Promise<PermissionStatus> | 检查读写权限 | OpenHarmony phone设备不支持公共目录访问,不支持目录默认使用filesDir,filesDir读写无需额外申请权限,因此接口返回均为granted | | requestPermissions() | Promise<PermissionStatus> | 请求读写权限 | OpenHarmony phone设备不支持公共目录访问,不支持目录默认使用filesDir,filesDir读写无需额外申请权限,因此接口返回均为granted | | readFile(options: ReadFileOptions) | Promise<ReadFileResult> | 读取文件 | | | readFileInChunks(options: ReadFileInChunksOptions, callback: ReadFileInChunksCallback) | Promise<CallbackID> | 分块读取文件 | 仅原生平台支持 | | writeFile(options: WriteFileOptions) | Promise<WriteFileResult> | 写入文件 | OpenHarmony仅支持utf-8编码 | | appendFile(options: AppendFileOptions) | Promise<void> | 向文件追加内容 | OpenHarmony仅支持utf-8编码 | | deleteFile(options: DeleteFileOptions) | Promise<void> | 删除文件 | | | mkdir(options: MkdirOptions) | Promise<void> | 创建目录 | | | rmdir(options: RmdirOptions) | Promise<void> | 删除目录 | | | readdir(options: ReaddirOptions) | Promise<ReaddirResult> | 列出目录中的文件 | | | getUri(options: GetUriOptions) | Promise<GetUriResult> | 获取文件/目录的完整URI | | | stat(options: StatOptions) | Promise<StatResult> | 返回文件信息 | | | rename(options: RenameOptions) | Promise<void> | 重命名文件或目录 | | | copy(options: CopyOptions) | Promise<CopyResult> | 复制文件或目录 | | | downloadFile(options: DownloadFileOptions) | Promise<DownloadFileResult> | 下载文件 | 7.1.0后已弃用，OpenHarmony未实现,请使用@capacitor/file-transfer插件 | | addListener('progress', listenerFunc: ProgressListener) | Promise<PluginListenerHandle> | 添加下载进度监听器 | 7.1.0后已弃用，OpenHarmony未实现,请使用@capacitor/file-transfer插件 | | removeAllListeners() | Promise<void> | 移除所有监听器 | 7.1.0后已弃用，OpenHarmony未实现,请使用@capacitor/file-transfer插件 |

数据结构

PermissionStatus

调用 checkPermissions 和 requestPermissions 方法时的返回对象。

| 属性 | 类型 | 描述 | |-----------------|-------------------|------| | publicStorage | PermissionState | 权限状态 |

ReadFileResult

调用 readFile 方法时的返回对象。

| 属性 | 类型 | 描述 | |--------|---------|-------| | data | string | Blob | 文件内容，返回base64 encoded 字符串 |

ReadFileOptions

调用 readFile 方法时的参数对象。

| 属性 | 类型 | 描述 | |-------------|-------------|-----------| | path | string | 要读取的文件路径 | | directory | Directory | 读取文件的目录 | | encoding | Encoding | 读取文件的编码格式 |

ReadFileInChunksOptions

调用 readFileInChunks 方法时的参数对象。

| 属性 | 类型 | 描述 | |-------------|----------|----------| | chunkSize | number | 分块大小（字节） |

WriteFileResult

调用 writeFile 方法时的返回对象。

| 属性 | 类型 | 描述 | |-------|----------|----------| | uri | string | 文件写入的URI |

WriteFileOptions

调用 writeFile 方法时的参数对象。

| 属性 | 类型 | 描述 | 备注 | |-------------|-------------|-----------------------------------------|------------------------------------------------------| | path | string | 要写入的文件路径 | | | data | string | Blob | 要写入的数据，OpenHarmony仅支持base64 encoded 字符串和 ArrayBuffer | | | directory | Directory | 存储文件的目录 | | | encoding | Encoding | 写入文件的编码格式，OpenHarmony仅支持Encoding.UTF8 | | | recursive | boolean | 是否创建缺失的父目录 | 默认false |

AppendFileOptions

调用 appendFile 方法时的参数对象。

| 属性 | 类型 | 描述 | |-------------|-------------|-----------------------------------------| | path | string | 要追加的文件路径 | | data | string | 要写入的数据 | | directory | Directory | 存储文件的目录 | | encoding | Encoding | 写入文件的编码格式，OpenHarmony仅支持Encoding.UTF8 |

DeleteFileOptions

调用 deleteFile 方法时的参数对象。

| 属性 | 类型 | 描述 | |-------------|-------------|----------| | path | string | 要删除的文件路径 | | directory | Directory | 删除文件的目录 |

MkdirOptions

调用 mkdir 方法时的参数对象。

| 属性 | 类型 | 描述 | 备注 | |-------------|-------------|------------|-----------| | path | string | 新目录的路径 | | | directory | Directory | 创建新目录的父目录 | | | recursive | boolean | 是否创建缺失的父目录 | 默认false |

RmdirOptions

调用 rmdir 方法时的参数对象。

| 属性 | 类型 | 描述 | 备注 | |-------------|-------------|------------|-----------| | path | string | 要删除的目录路径 | | | directory | Directory | 删除目录的父目录 | | | recursive | boolean | 是否递归删除目录内容 | 默认false |

ReaddirResult

调用 readdir 方法时的返回对象。

| 属性 | 类型 | 描述 | |---------|--------------|-------------| | files | FileInfo[] | 目录中的文件和目录列表 |

FileInfo

文件或目录的信息对象。

| 属性 | 类型 | 描述 | |---------|----------------------|-----------| | name | string | 文件或目录的名称 | | type | 'file'丨'directory' | 文件类型 | | size | number | 文件大小（字节） | | ctime | number | 创建时间（秒） | | mtime | number | 最后修改时间（秒） | | uri | string | 文件的URI |

ReaddirOptions

调用 readdir 方法时的参数对象。

| 属性 | 类型 | 描述 | |-------------|-------------|----------| | path | string | 要读取的目录路径 | | directory | Directory | 列出文件的目录 |

GetUriResult

调用 getUri 方法时的返回对象。

| 属性 | 类型 | 描述 | |-------|----------|--------| | uri | string | 文件的URI |

GetUriOptions

调用 getUri 方法时的参数对象。

| 属性 | 类型 | 描述 | |-------------|-------------|-------------| | path | string | 要获取URI的文件路径 | | directory | Directory | 获取文件的目录 |

StatOptions

调用 stat 方法时的参数对象。

| 属性 | 类型 | 描述 | |-------------|-------------|------------| | path | string | 要获取信息的文件路径 | | directory | Directory | 获取文件的目录 |

CopyOptions

调用 copy 方法时的参数对象。

| 属性 | 类型 | 描述 | |---------------|-------------|----------------------------------------| | from | string | 现有文件或目录的路径 | | to | string | 目标文件或目录的路径 | | directory | Directory | 包含现有文件或目录的目录 | | toDirectory | Directory | 包含目标文件或目录的目录，如果未提供则使用directory参数作为目标 |

CopyResult

调用 copy 方法时的返回对象。

| 属性 | 类型 | 描述 | |-------|----------|-----------| | uri | string | 文件复制后的URI |

DownloadFileResult

调用 downloadFile 方法时的返回对象。

| 属性 | 类型 | 描述 | |--------|----------|-------------------------------| | path | string | 文件下载到的路径 | | blob | Blob | 已下载文件的 Blob 数据。此属性仅在 Web 端可用 |

PluginListenerHandle

| 属性名 | 类型 | |--------|---------------------------| | remove | () => Promise<void> |

类型别名

PermissionState

'granted' | 'denied'

ReadFileInChunksCallback

接收从文件读取的块的回调，或出错时的错误。

(chunkRead: ReadFileResult | null, err?: any): void

CallbackID

string

StatResult

FileInfo

RenameOptions

CopyOptions

ProgressListener

接收进度事件的监听函数。

(progress: ProgressStatus): void

枚举

目录结构

|---- 目录
|     |---- src/main  # 插件的实现代码
|           |----cpp  # C++ 代码
|           |----ets   # ArkTS 代码
|     |---- README.md          # 说明文档
|     |---- package.json       # 配置文件
|     |---- plugin.xml       # 插件配置文件

贡献代码

使用过程中发现任何问题都可以提 Issue ，当然，也非常欢迎发 PR 共建。

许可证

本插件基于 MIT License 开源，详见 LICENSE 文件。

Published

Vulnerabilities

Links

Maintainers

Keywords

Readme

@capacitor/filesystem

简介

支持平台

下载安装

命令行安装（推荐）

手动引入安装

1. 添加插件配置

2. 修改 CMake 配置

3. 复制源码文件

4. 添加 ArkTS 配置

卸载

约束与限制

兼容性

权限要求

使用示例

示例1：读取文件内容

示例2：写入文件内容

示例3：删除文件

示例4：创建目录

示例5：获取文件信息

使用说明

数据结构

PermissionStatus

ReadFileResult

ReadFileOptions

ReadFileInChunksOptions

WriteFileResult

WriteFileOptions

AppendFileOptions

DeleteFileOptions

MkdirOptions

RmdirOptions

ReaddirResult

FileInfo

ReaddirOptions

GetUriResult

GetUriOptions

StatOptions

CopyOptions

CopyResult

DownloadFileResult

PluginListenerHandle

类型别名

PermissionState

ReadFileInChunksCallback

CallbackID

StatResult

RenameOptions

ProgressListener

枚举

Directory

目录结构

贡献代码

许可证