{"_id":"@cordova-ohos/cordova-plugin-file","_rev":"5-a78f1544e9bae38c08976b96eb9a788f","name":"@cordova-ohos/cordova-plugin-file","dist-tags":{"latest":"8.1.4"},"versions":{"8.1.3":{"name":"@cordova-ohos/cordova-plugin-file","version":"8.1.3","keywords":["cordova","file","ecosystem:cordova","cordova-openharmony"],"author":{"name":"Huawei Device, Inc. Ltd. and","email":"马弓手"},"license":"Apache-2.0","_id":"@cordova-ohos/cordova-plugin-file@8.1.3","maintainers":[{"name":"luqi_tan","email":"295099422@qq.com"}],"bugs":{"url":"https://gitcode.com/OpenHarmony-Cordova/cordova-plugin-file/issues"},"dist":{"shasum":"582f297d26f1e5a5da273736b16509949e1c8640","tarball":"https://registry.npmjs.org/@cordova-ohos/cordova-plugin-file/-/cordova-plugin-file-8.1.3.tgz","fileCount":30,"integrity":"sha512-FimDktdt+LWQiH41BiS7Sl1pAZuMyZxTGhNZIud8/1fn+s/prKVamEDmx78dAWWSy989Z1gMZizbwle2qnCnXg==","signatures":[{"sig":"MEQCICOkr1HkMIF3cRSSM3OPReavH7z3x2tp/HvF6E22Y13hAiBYzMrWsFA58HPChb1WZtxKoXsaQzh2y589FxUmrQwyMQ==","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":153134},"cordova":{"id":"cordova-plugin-file","platforms":["ohos"]},"engines":{"cordovaDependencies":{"8.1.3":{"hcordova":">=1.0.0","@cordova-ohos/ohos":">=2.0.0"}}},"gitHead":"4b68855e022e67561b780934eb528326dbf2db2e","_npmUser":{"name":"luqi_tan","email":"295099422@qq.com"},"repository":{"url":"gitcode:OpenHarmony-Cordova/cordova-plugin-file","type":"git"},"_npmVersion":"10.5.1","description":"Cordova file Plugin","directories":{},"_nodeVersion":"22.0.0","_hasShrinkwrap":false,"_npmOperationalInternal":{"tmp":"tmp/cordova-plugin-file_8.1.3_1773827186725_0.050327910659301534","host":"s3://npm-registry-packages-npm-production"}},"8.1.4":{"name":"@cordova-ohos/cordova-plugin-file","version":"8.1.4","description":"Cordova file Plugin","cordova":{"id":"cordova-plugin-file","platforms":["ohos"]},"repository":{"type":"git","url":"gitcode:CPF-Cordova/cordova-plugin-file"},"bugs":{"url":"https://gitcode.com/CPF-Cordova/cordova-plugin-file/issues"},"keywords":["cordova","file","ecosystem:cordova","cordova-openharmony"],"engines":{"cordovaDependencies":{"8.1.4":{"@cordova-ohos/ohos":">=2.0.0","hcordova":">=1.0.0"}}},"author":{"name":"Huawei Device, Inc. Ltd. and","email":"马弓手"},"license":"Apache-2.0","_id":"@cordova-ohos/cordova-plugin-file@8.1.4","gitHead":"1ad1f11763c68e4f3eefca57aaf152b9d805ef33","_nodeVersion":"22.0.0","_npmVersion":"10.5.1","dist":{"integrity":"sha512-IDPIM5AnSCJQLgB+emfycZ//pATmsSJSd/DClj4+JpGSxRRbtbuh4ioV9YQbwtOe6h0jXH2SkTTbDHJW+3qaHw==","shasum":"37119204a01bd03591a8de1b6d00228fbd56ba22","tarball":"https://registry.npmjs.org/@cordova-ohos/cordova-plugin-file/-/cordova-plugin-file-8.1.4.tgz","fileCount":31,"unpackedSize":196776,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEQCICsJOrUg38xLOTTag9GBJpy/R570LESG4yIwS15SzlY7AiB10+qJtdXCBV5/Cdrrk/QMHePeLRGZ33KCmwYp7+uW1Q=="}]},"_npmUser":{"name":"luqi_tan","email":"295099422@qq.com"},"directories":{},"maintainers":[{"name":"luqi_tan","email":"295099422@qq.com"},{"name":"wanpengsz","email":"wanpengsz@163.com"},{"name":"xkh111","email":"xukaihui11@163.com"},{"name":"hcordova","email":"chenlihuiabc@163.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/cordova-plugin-file_8.1.4_1785140415539_0.36415879439995025"},"_hasShrinkwrap":false}},"time":{"created":"2026-03-18T09:46:26.581Z","modified":"2026-07-27T08:20:15.916Z","8.1.3":"2026-03-18T09:46:26.869Z","8.1.4":"2026-07-27T08:20:15.686Z"},"bugs":{"url":"https://gitcode.com/CPF-Cordova/cordova-plugin-file/issues"},"author":{"name":"Huawei Device, Inc. Ltd. and","email":"马弓手"},"license":"Apache-2.0","keywords":["cordova","file","ecosystem:cordova","cordova-openharmony"],"repository":{"type":"git","url":"gitcode:CPF-Cordova/cordova-plugin-file"},"description":"Cordova file Plugin","maintainers":[{"name":"luqi_tan","email":"295099422@qq.com"},{"name":"wanpengsz","email":"wanpengsz@163.com"},{"name":"xkh111","email":"xukaihui11@163.com"},{"name":"hcordova","email":"chenlihuiabc@163.com"}],"readme":"# <center>cordova-plugin-file</center>\r\n\r\n[![zh-CN](https://img.shields.io/badge/lang-中文-blue.svg)](README.md)\r\n[![en](https://img.shields.io/badge/lang-English-blue.svg)](README.en.md)\r\n\r\n本项目基于 [cordova-plugin-file@8.1.3](https://www.npmjs.com/package/cordova-plugin-file/v/8.1.3) 开发，本文档重点阐述其在 OpenHarmony（OHOS）系统中的具体应用。\r\n\r\n- [cordova-plugin-file](#cordova-plugin-file)\r\n  - [简介](#简介)\r\n  - [支持平台](#支持平台)\r\n  - [下载安装](#下载安装)\r\n    - [前提条件](#前提条件)\r\n    - [安装方式](#安装方式)\r\n    - [从 npm 安装（推荐）](#从-npm-安装推荐)\r\n    - [指定平台安装 ohos](#指定平台安装-ohos)\r\n    - [从 GitCode 仓库安装](#从-gitcode-仓库安装)\r\n    - [安装指定版本](#安装指定版本)\r\n    - [离线安装（本地包）](#离线安装本地包)\r\n    - [安装后验证](#安装后验证)\r\n    - [卸载](#卸载)\r\n    - [插件验证](#插件验证)\r\n  - [约束与限制](#约束与限制)\r\n    - [兼容性](#兼容性)\r\n    - [平台配置](#平台配置)\r\n  - [文件系统结构](#文件系统结构)\r\n    - [cordova.file 对象参考](#cordovafile-对象参考)\r\n    - [LocalFileSystem 常量参考](#localfilesystem-常量参考)\r\n  - [核心概念](#核心概念)\r\n    - [关键实体](#关键实体)\r\n    - [文件系统类型](#文件系统类型)\r\n  - [使用示例](#使用示例)\r\n    - [示例 1：文件系统初始化（请求持久化存储）](#示例-1文件系统初始化请求持久化存储)\r\n    - [示例 2：解析目录 URL（获取指定目录对象）](#示例-2解析目录-url获取指定目录对象)\r\n    - [示例 3：创建目录与列举目录内容](#示例-3创建目录与列举目录内容)\r\n    - [示例 4：创建文件并写入文本内容](#示例-4创建文件并写入文本内容)\r\n    - [示例 5：读取文件内容并解析](#示例-5读取文件内容并解析)\r\n    - [示例 6：删除文件与目录](#示例-6删除文件与目录)\r\n    - [示例 7：从 URL 下载并保存二进制文件（如图片）](#示例-7从-url-下载并保存二进制文件如图片)\r\n  - [使用说明](#使用说明)\r\n    - [核心 API 说明](#核心-api-说明)\r\n      - [1. 文件系统初始化 API](#1-文件系统初始化-api)\r\n        - [window.requestFileSystem(type, size, successCallback, errorCallback)](#windowrequestfilesystemtype-size-successcallback-errorcallback)\r\n        - [window.resolveLocalFileSystemURL(url, successCallback, errorCallback)](#windowresolvelocalfilesystemurlurl-successcallback-errorcallback)\r\n      - [2. 目录操作 API](#2-目录操作-api)\r\n        - [dirEntry.getDirectory(name, options, successCallback, errorCallback)](#direntrygetdirectoryname-options-successcallback-errorcallback)\r\n        - [dirEntry.createReader() → DirectoryReader.readEntries(successCallback, errorCallback)](#direntrycreatereader--directoryreaderreadentriessuccesscallback-errorcallback)\r\n        - [dirEntry.remove(successCallback, errorCallback)](#direntryremovesuccesscallback-errorcallback)\r\n      - [3. 文件操作 API](#3-文件操作-api)\r\n        - [dirEntry.getFile(name, options, successCallback, errorCallback)](#direntrygetfilename-options-successcallback-errorcallback)\r\n        - [fileEntry.createWriter(successCallback, errorCallback) → FileWriter.write(blob)](#fileentrycreatewritersuccesscallback-errorcallback--filewriterwriteblob)\r\n        - [fileEntry.file(successCallback, errorCallback) → FileReader.readAs\\*(file)](#fileentryfilesuccesscallback-errorcallback--filereaderreadasfile)\r\n        - [删除文件](#删除文件)\r\n    - [4. 错误处理](#4-错误处理)\r\n      - [`FileError` 错误码参考](#fileerror-错误码参考)\r\n      - [错误信息辅助函数](#错误信息辅助函数)\r\n  - [新增特性](#新增特性)\r\n  - [目录结构](#目录结构)\r\n  - [贡献代码](#贡献代码)\r\n  - [许可证](#许可证)\r\n  - [官方资源](#官方资源)\r\n\r\n\r\n## 简介\r\n\r\n`cordova-plugin-file` 是一款专为 Apache Cordova 应用设计的文件操作插件，提供完善的文件 API，支持对设备本地文件系统中的文件和目录进行读写、创建、删除、列举等各类操作。该插件遵循 [W3C File API 规范](https://www.w3.org/TR/FileAPI/)，并提供平台特定扩展以适配不同系统的文件系统特性，本文档主要说明该插件在 OpenHarmony（OHOS）系统中的应用。\r\n\r\n- 规范兼容：遵循 W3C File API 标准，降低开发者学习成本，适配多平台开发习惯\r\n\r\n- 功能全面：支持文件/目录的创建、读写、删除、列举等全场景操作，覆盖文本、二进制等多种数据格式\r\n\r\n- 平台适配：针对 OpenHarmony 系统特性优化，提供标准化目录访问方式，无需关注系统底层文件路径差异\r\n\r\n- 权限友好：OpenHarmony 沙箱文件读写无需额外申请权限，默认具备相关操作权限，简化集成流程\r\n\r\n- 错误可控：提供完善的错误处理机制，包含详细错误码及说明，便于问题排查\r\n\r\n## 支持平台\r\n\r\n- **Android**：支持主流版本，适配 Cordova 标准文件操作逻辑\r\n\r\n- **iOS**：支持主流版本，遵循 iOS 沙箱文件系统规范\r\n\r\n- **OHOS**：重点适配版本，本文档主要说明该平台使用\r\n\r\n## 下载安装\r\n\r\n通过 hcordova CLI 即可快速安装插件，支持全平台安装、指定 OpenHarmony 平台安装及从 GitCode 源码安装，安装前需确保满足前置环境要求并创建 Cordova 项目。\r\n\r\n### 前提条件\r\n\r\n在安装插件前，请确保开发环境满足以下基础要求：\r\n\r\n- 已安装 Node.js（v14.0.0 及以上）和 npm（v6.0.0 及以上），可通过 `node -v` 和 `npm -v` 命令验证版本。\r\n\r\n- 已全局安装 Cordova CLI（v10.0.0 及以上），若未安装，可执行命令：`npm install -g hcordova`\r\n\r\n- 已创建 Cordova 项目（若尚未创建，可通过 `hcordova create MyFileApp com.example.fileapp 文件操作示例应用` 命令快速创建项目）。\r\n\r\n### 安装方式\r\n\r\n### 从 npm 安装（推荐）\r\n\r\n```bash\r\n# 使用 hcordova CLI 安装\r\n# 安装 hcordova 命令化工具\r\nnpm install -g hcordova\r\n\r\n# 全平台安装插件（推荐稳定版）\r\nhcordova plugin add cordova-plugin-file\r\n```\r\n\r\n### 指定平台安装 ohos\r\n\r\n仅为 OHOS 平台安装插件：\r\n\r\n```bash\r\n# 仅安装到 OHOS 平台\r\nhcordova plugin add cordova-plugin-file --platform ohos\r\n```\r\n\r\n### 从 GitCode 仓库安装\r\n\r\n仅为 OHOS 平台安装插件（获取最新开发版）：\r\n\r\n```bash\r\n# 仅安装到 OHOS 平台\r\nhcordova plugin add https://gitcode.com/CPF-Cordova/cordova-plugin-file.git --platform ohos\r\n\r\n# 指定标签/分支安装\r\nhcordova plugin add https://gitcode.com/CPF-Cordova/cordova-plugin-file.git@develop --platform ohos\r\n```\r\n\r\n### 安装指定版本\r\n\r\n```bash\r\n# 仅安装到 OHOS 平台指定版本\r\nhcordova plugin add cordova-plugin-file@1.0.0 --platform ohos\r\n```\r\n\r\n### 离线安装（本地包）\r\n\r\n适用于无网络环境，先下载插件包到本地，再执行离线安装：\r\n\r\n```bash\r\n# 下载插件包到本地（示例路径：~/Downloads/cordova-plugin-file）\r\n# 执行离线安装\r\nhcordova plugin add ~/Downloads/cordova-plugin-file --platform ohos\r\n```\r\n\r\n### 安装后验证\r\n\r\n安装完成后，可通过以下命令验证插件是否成功添加到项目中：\r\n\r\n```bash\r\n# 查看已安装的插件列表，若包含本插件 ID 则表示插件已成功安装\r\nhcordova plugin list\r\n```\r\n\r\n\r\n### 卸载\r\n\r\n```bash\r\n# Cordova CLI 全平台卸载\r\nhcordova plugin remove cordova-plugin-file \r\n\r\n# 指定平台卸载\r\nhcordova plugin remove cordova-plugin-file --platform ohos\r\n\r\n```\r\n\r\n### 插件验证\r\n\r\n安装完成后，可通过以下命令验证插件是否成功添加到项目中：\r\n\r\n```bash\r\nhcordova plugin list\r\n\r\n```\r\n\r\n若输出结果包含 `cordova-plugin-file`，则表示插件已成功安装。\r\n\r\n## 约束与限制\r\n\r\n* 依赖插件：无强制依赖，插件集成后可直接使用，无需额外配置\r\n\r\n* 调用时机：所有 API 需在 `deviceready` 事件触发后调用，避免因原生接口未初始化导致错误\r\n\r\n* 路径规范：需使用插件提供的 `cordova.file` 常量或标准化 URL 访问目录，避免直接写死本地路径，确保跨平台兼容性\r\n\r\n* 目录操作：删除目录时，目录必须为空，否则会触发错误；移动目录仅支持同一文件系统内操作\r\n\r\n* 二进制操作：处理图片、视频等二进制文件时，需确保数据格式为 Blob 或 ArrayBuffer，避免格式错误\r\n\r\n* 存储配额：持久化存储虽可保留数据，但系统空间不足时可能被清理，建议重要数据做好备份\r\n\r\n### 兼容性\r\n\r\n支持：\r\n\r\n| 项目 | 版本/信息 |\r\n|-----|--------|\r\n| SDK | API12+ |\r\n| IDE | DevEco Studio: 5.0+ |\r\n| ROM | 5.1+ |\r\n| Emulator | OpenHarmony 6.0+ |\r\n\r\n在以下版本中已测试通过：\r\n\r\n| 项目 | 版本/信息 |\r\n|-----|--------|\r\n| @cordova-ohos/ohos | 14.0.1-ohos-14.0.1 |\r\n| SDK | 5.0.0(12) |\r\n| IDE | DevEco Studio: 6.0.13.200 |\r\n| ROM | 5.1.0.120 SP3 |\r\n| Emulator | OpenHarmony 6.0.1(21) |\r\n\r\n### 平台配置\r\n\r\n**权限设置**：\r\n\r\n* 在 OHOS 系统中，对沙箱文件的读写，无需申请额外权限，默认具备读写权限\r\n\r\n\r\n## 文件系统结构\r\n\r\n不同平台拥有独特的文件系统结构，该插件通过 `cordova.file` 对象提供标准化 URL，用于跨平台访问常用目录，无需关注各平台底层路径差异。以下是 OpenHarmony 系统中 `cordova.file` 对象对应的目录路径参考：\r\n\r\n### cordova.file 对象参考\r\n\r\n| **Cordova 目录常量** | **OpenHarmony 目录路径** |\r\n|---|---|\r\n| cordova.file.applicationDirectory | /data/storage/el2 |\r\n| cordova.file.applicationStorageDirectory | /data/storage/el2/base/files |\r\n| cordova.file.dataDirectory | /data/storage/el2/base/files |\r\n| cordova.file.cacheDirectory | /data/storage/el2/base/cache |\r\n| cordova.file.externalApplicationStorageDirectory | /data/storage/el2/base/files |\r\n| cordova.file.externalDataDirectory | /data/storage/el2/base/files |\r\n| cordova.file.externalRootDirectory | /data/storage/el2 |\r\n| cordova.file.tempDirectory | /data/storage/el2/base/temp |\r\n| cordova.file.syncedDataDirectory | /data/storage/el2/base/files |\r\n| cordova.file.documentsDirectory | /data/storage/el2/base/files |\r\n| cordova.file.sharedDirectory | /data/storage/el2/base/files |\r\n### LocalFileSystem 常量参考\r\n\r\n| **Cordova 目录常量** | **常量值** | **OpenHarmony 内部目录路径** |\r\n|---|---|---|\r\n| LocalFileSystem.TEMPORARY | 0 | /data/storage/el2/base/temp |\r\n| LocalFileSystem.PERSISTENT | 1 | /data/storage/el2/base/files |\r\n## 核心概念\r\n\r\n### 关键实体\r\n\r\n插件操作涉及多个核心实体，理解这些实体的作用是正确使用插件的基础：\r\n\r\n1. **FileSystem**：表示已挂载的文件系统，分为持久化存储和临时存储两种类型，提供根目录访问入口。\r\n\r\n2. **DirectoryEntry**：表示文件系统中的目录，提供创建、删除、列举子目录/文件等操作方法。\r\n\r\n3. **FileEntry**：表示文件系统中的文件，提供创建、删除、读写文件内容等操作方法。\r\n\r\n4. **File**：包含文件的元数据（如大小、类型、最后修改时间）和原始内容，是文件读取的核心对象。\r\n\r\n5. **FileWriter**：用于向 FileEntry 写入内容，支持追加、截断、定位等写入操作。\r\n\r\n6. **FileReader**：用于从 File 对象读取内容，支持文本、二进制、data URL 等多种读取格式。\r\n\r\n### 文件系统类型\r\n\r\n插件支持两种类型的文件系统，适用于不同的业务场景：\r\n\r\n- **LocalFileSystem.PERSISTENT**：持久化存储，应用重启、更新后数据仍会保留；OpenHarmony 平台无需用户授权，默认可访问。\r\n\r\n- **LocalFileSystem.TEMPORARY**：临时存储，系统空间不足时可能自动清理数据；无需授权，适用于临时文件存储（如缓存、临时下载文件）。\r\n\r\n## 使用示例\r\n\r\n### 示例 1：文件系统初始化（请求持久化存储）\r\n\r\n请求访问持久化文件系统，获取根目录用于后续操作，是大多数文件操作的前置步骤。\r\n\r\n```js\r\n// 请求持久化存储\r\nwindow.requestFileSystem(\r\n  LocalFileSystem.PERSISTENT,\r\n  0,\r\n  (fs) => {\r\n    console.log(`文件系统已打开：${fs.name}（根目录：${fs.root.fullPath}）`);\r\n    // 使用 fs.root（DirectoryEntry 对象）进行后续目录/文件操作\r\n  },\r\n  (error) => {\r\n    console.error(`打开文件系统失败：${getErrorMessage(error)}`);\r\n  }\r\n);\r\n```\r\n\r\n### 示例 2：解析目录 URL（获取指定目录对象）\r\n\r\n将 `cordova.file` 常量中的 URL 解析为 DirectoryEntry 对象，便于对指定目录进行操作。\r\n\r\n```js\r\n// 将数据目录 URL 解析为 DirectoryEntry 对象\r\nwindow.resolveLocalFileSystemURL(\r\n  cordova.file.dataDirectory,\r\n  (dirEntry) => {\r\n    console.log(`已解析目录：${dirEntry.name}（路径：${dirEntry.fullPath}）`);\r\n    // 可通过 dirEntry 进行目录操作（如创建子目录、创建文件）\r\n  },\r\n  (error) => {\r\n    console.error(`解析 URL 失败：${getErrorMessage(error)}`);\r\n  }\r\n);\r\n\r\n```\r\n\r\n### 示例 3：创建目录与列举目录内容\r\n\r\n在数据目录中创建子目录，并列举该目录下的所有文件和子目录。\r\n\r\n```js\r\n// 创建目录\r\nfunction createAppDirectory(directoryName) {\r\n  window.resolveLocalFileSystemURL(\r\n    cordova.file.dataDirectory,\r\n    (rootDir) => {\r\n      // 目录不存在时创建，存在时直接获取\r\n      rootDir.getDirectory(\r\n        directoryName,\r\n        { create: true, exclusive: false },\r\n        (newDir) => {\r\n          console.log(`目录已创建：${newDir.fullPath}`);\r\n          // 列举目录内容\r\n          listDirectoryContents(newDir.fullPath);\r\n        },\r\n        (error) => console.error(`创建目录失败：${getErrorMessage(error)}`)\r\n      );\r\n    },\r\n    (error) => console.error(`解析根目录失败：${getErrorMessage(error)}`)\r\n  );\r\n}\r\n\r\n// 列举目录内容\r\nfunction listDirectoryContents(directoryURL) {\r\n  window.resolveLocalFileSystemURL(\r\n    directoryURL,\r\n    (dirEntry) => {\r\n      const dirReader = dirEntry.createReader();\r\n      dirReader.readEntries(\r\n        (entries) => {\r\n          if (entries.length === 0) {\r\n            console.log(\"目录为空\");\r\n            return;\r\n          }\r\n          entries.forEach((entry) => {\r\n            const entryType = entry.isFile ? \"文件\" : \"目录\";\r\n            console.log(`${entry.name}（${entryType}）- 路径：${entry.fullPath}`);\r\n          });\r\n        },\r\n        (error) => console.error(`读取目录失败：${getErrorMessage(error)}`)\r\n      );\r\n    },\r\n    (error) => console.error(`解析目录失败：${getErrorMessage(error)}`)\r\n  );\r\n}\r\n\r\n// 使用：在数据目录中创建 \"app_data\" 目录并列举其内容\r\ncreateAppDirectory(\"app_data\");\r\n\r\n```\r\n\r\n### 示例 4：创建文件并写入文本内容\r\n\r\n在数据目录中创建文本文件，并写入 JSON 格式的用户偏好设置。\r\n\r\n```js\r\n// 写入文本文件\r\nfunction writeTextToFile(fileName, content) {\r\n  window.resolveLocalFileSystemURL(\r\n    cordova.file.dataDirectory,\r\n    (rootDir) => {\r\n      rootDir.getFile(\r\n        fileName,\r\n        { create: true, exclusive: false },\r\n        (fileEntry) => {\r\n          fileEntry.createWriter(\r\n            (fileWriter) => {\r\n              // 写入完成回调\r\n              fileWriter.onwriteend = () => {\r\n                console.log(`成功写入文件：${fileName}`);\r\n              };\r\n              // 写入错误回调\r\n              fileWriter.onerror = (error) => {\r\n                console.error(`写入失败：${getErrorMessage(error)}`);\r\n              };\r\n              // 将文本转换为 Blob（支持 UTF-8 编码）\r\n              const textBlob = new Blob([content], { type: \"text/plain;charset=utf-8\" });\r\n              fileWriter.write(textBlob);\r\n            },\r\n            (error) => console.error(`创建写入器失败：${getErrorMessage(error)}`)\r\n          );\r\n        },\r\n        (error) => console.error(`获取文件失败：${getErrorMessage(error)}`)\r\n      );\r\n    },\r\n    (error) => console.error(`解析根目录失败：${getErrorMessage(error)}`)\r\n  );\r\n}\r\n\r\n// 使用：将用户偏好设置写入 \"user_settings.txt\"\r\nconst userSettings = JSON.stringify({ theme: \"dark\", notifications: true }, null, 2);\r\nwriteTextToFile(\"user_settings.txt\", userSettings);\r\n\r\n```\r\n\r\n### 示例 5：读取文件内容并解析\r\n\r\n读取已创建的文本文件，并解析其中的 JSON 数据。\r\n\r\n```js\r\n// 读取文本文件\r\nfunction readTextFromFile(fileName) {\r\n  window.resolveLocalFileSystemURL(\r\n    cordova.file.dataDirectory + fileName,\r\n    (fileEntry) => {\r\n      fileEntry.file(\r\n        (file) => {\r\n          const fileReader = new FileReader();\r\n          fileReader.onloadend = () => {\r\n            const fileContent = fileReader.result;\r\n            console.log(`文件内容（${fileName}）：`, fileContent);\r\n            // 处理内容（如解析 JSON）\r\n            try {\r\n              const parsedData = JSON.parse(fileContent);\r\n              console.log(\"解析后的 JSON 数据：\", parsedData);\r\n            } catch (e) {\r\n              console.log(\"内容非 JSON 格式：\", fileContent);\r\n            }\r\n          };\r\n          fileReader.onerror = (error) => {\r\n            console.error(`读取失败：${getErrorMessage(error)}`);\r\n          };\r\n\r\n          // 以文本格式读取文件\r\n          fileReader.readAsText(file);\r\n        },\r\n        (error) => console.error(`访问文件失败：${getErrorMessage(error)}`)\r\n      );\r\n    },\r\n    (error) => console.error(`文件不存在：${getErrorMessage(error)}`)\r\n  );\r\n}\r\n\r\n// 使用：读取 \"user_settings.txt\" 文件\r\nreadTextFromFile(\"user_settings.txt\");\r\n\r\n```\r\n\r\n### 示例 6：删除文件与目录\r\n\r\n删除指定的文件和空目录，注意删除目录时需确保目录为空。\r\n\r\n```js\r\n// 删除文件\r\nfunction deleteFile(fileName) {\r\n  window.resolveLocalFileSystemURL(\r\n    cordova.file.dataDirectory + fileName,\r\n    (fileEntry) => {\r\n      fileEntry.remove(\r\n        () => console.log(`文件已删除：${fileName}`),\r\n        (error) => console.error(`删除文件失败：${getErrorMessage(error)}`)\r\n      );\r\n    },\r\n    (error) => console.error(`文件不存在：${getErrorMessage(error)}`)\r\n  );\r\n}\r\n\r\n// 删除空目录\r\nfunction deleteEmptyDirectory(directoryName) {\r\n  window.resolveLocalFileSystemURL(\r\n    cordova.file.dataDirectory + directoryName,\r\n    (dirEntry) => {\r\n      dirEntry.remove(\r\n        () => console.log(`目录已删除：${directoryName}`),\r\n        (error) => console.error(`删除目录失败：${getErrorMessage(error)}`)\r\n      );\r\n    },\r\n    (error) => console.error(`目录不存在：${getErrorMessage(error)}`)\r\n  );\r\n}\r\n\r\n// 使用：删除文件和空目录\r\ndeleteFile(\"old_logs.txt\");\r\ndeleteEmptyDirectory(\"old_data\");\r\n\r\n```\r\n\r\n### 示例 7：从 URL 下载并保存二进制文件（如图片）\r\n\r\n通过网络请求下载图片，将二进制数据保存到本地文件系统。\r\n\r\n```js\r\nfunction downloadFile(url, destinationFileName) {\r\n  // 显示加载指示器（可选）\r\n  console.log(`正在下载 ${url}...`);\r\n  fetch(url)\r\n    .then((response) => {\r\n      if (!response.ok) {\r\n        throw new Error(`HTTP 错误！状态码：${response.status}`);\r\n      }\r\n      return response.blob(); // 以 Blob 格式获取文件\r\n    })\r\n    .then((blob) => {\r\n      window.resolveLocalFileSystemURL(\r\n        cordova.file.dataDirectory,\r\n        (rootDir) => {\r\n          rootDir.getFile(\r\n            destinationFileName,\r\n            { create: true, exclusive: false },\r\n            (fileEntry) => {\r\n              fileEntry.createWriter(\r\n                (fileWriter) => {\r\n                  fileWriter.onwriteend = () => {\r\n                    console.log(`文件已下载至：${fileEntry.fullPath}`);\r\n                    // 隐藏加载指示器（可选）\r\n                  };\r\n                  fileWriter.onerror = (error) => {\r\n                    throw new Error(`写入文件失败：${getErrorMessage(error)}`);\r\n                  };\r\n                  fileWriter.write(blob);\r\n                },\r\n                (error) => console.error(`创建写入器失败：${getErrorMessage(error)}`)\r\n              );\r\n            },\r\n            (error) => console.error(`获取文件失败：${getErrorMessage(error)}`)\r\n          );\r\n        },\r\n        (error) => console.error(`解析目录失败：${getErrorMessage(error)}`)\r\n      );\r\n    })\r\n    .catch((error) => {\r\n      console.error(`下载失败：${error.message}`);\r\n      // 隐藏加载指示器（可选）\r\n    });\r\n}\r\n\r\n// 使用：下载图片并保存为 \"downloaded_image.jpg\"\r\ndownloadFile(\"https://example.com/image.jpg\", \"downloaded_image.jpg\");\r\n\r\n```\r\n\r\n## 使用说明\r\n\r\n### 核心 API 说明\r\n\r\n插件提供丰富的 API 用于文件系统操作，以下是核心 API 的详细说明，包含方法签名、参数说明及使用要点：\r\n\r\n#### 1. 文件系统初始化 API\r\n\r\n用于请求访问指定类型的文件系统，是所有文件操作的基础。\r\n\r\n##### window.requestFileSystem(type, size, successCallback, errorCallback)\r\n\r\n请求访问指定类型和大小的文件系统，成功后返回 FileSystem 对象。\r\n\r\n| **参数名** | **类型** | **说明** |\r\n|---|---|---|\r\n| type | 数字 | 文件系统类型，可选值：LocalFileSystem.PERSISTENT（1）、LocalFileSystem.TEMPORARY（0） |\r\n| size | 数字 | 配额大小（单位：字节），通常忽略此参数，默认传 0 即可 |\r\n| successCallback | 函数 | 成功时调用，参数为 FileSystem 对象，包含文件系统名称和根目录 |\r\n| errorCallback | 函数 | 失败时调用，参数为 FileError 对象，包含错误码和错误信息 |\r\n##### window.resolveLocalFileSystemURL(url, successCallback, errorCallback)\r\n\r\n将本地文件系统 URL（如 cordova.file 常量中的 URL）解析为 DirectoryEntry 或 FileEntry 对象。\r\n\r\n| **参数名** | **类型** | **说明** |\r\n|---|---|---|\r\n| url | 字符串 | 本地文件系统 URL，例如 cordova.file.dataDirectory、cordova.file.cacheDirectory |\r\n| successCallback | 函数 | 成功时调用，参数为 DirectoryEntry（目录）或 FileEntry（文件）对象 |\r\n| errorCallback | 函数 | 失败时调用，参数为 FileError 对象 |\r\n#### 2. 目录操作 API\r\n\r\n所有目录操作均通过 DirectoryEntry 对象的方法实现，核心方法如下：\r\n\r\n##### dirEntry.getDirectory(name, options, successCallback, errorCallback)\r\n\r\n创建或获取指定名称的子目录，成功后返回该目录的 DirectoryEntry 对象。\r\n\r\n| **参数名** | **类型** | **说明** |\r\n|---|---|---|\r\n| name | 字符串 | 要创建/获取的目录名称 |\r\n| options | 对象 | { create: 布尔值, exclusive: 布尔值 }；create：目录不存在时是否创建；exclusive：目录存在时是否报错 |\r\n| successCallback | 函数 | 成功时调用，参数为创建/获取到的 DirectoryEntry 对象 |\r\n| errorCallback | 函数 | 失败时调用，参数为 FileError 对象 |\r\n##### dirEntry.createReader() → DirectoryReader.readEntries(successCallback, errorCallback)\r\n\r\n创建目录读取器，用于列举目录下的所有文件和子目录。\r\n\r\n| **参数名** | **类型** | **说明** |\r\n|---|---|---|\r\n| successCallback | 函数 | 成功时调用，参数为 Entry 数组（包含目录下的文件和子目录） |\r\n| errorCallback | 函数 | 失败时调用，参数为 FileError 对象 |\r\n##### dirEntry.remove(successCallback, errorCallback)\r\n\r\n删除当前目录，注意：目录必须为空才能删除成功。\r\n\r\n| **参数名** | **类型** | **说明** |\r\n|---|---|---|\r\n| successCallback | 函数 | 删除成功时调用，无参数 |\r\n| errorCallback | 函数 | 删除失败时调用，参数为 FileError 对象（如目录非空会报错） |\r\n#### 3. 文件操作 API\r\n\r\n所有文件操作均通过 FileEntry 对象的方法实现，核心方法如下：\r\n\r\n##### dirEntry.getFile(name, options, successCallback, errorCallback)\r\n\r\n创建或获取指定名称的文件，成功后返回该文件的 FileEntry 对象。\r\n\r\n| **参数名** | **类型** | **说明** |\r\n|---|---|---|\r\n| name | 字符串 | 要创建/获取的文件名称 |\r\n| options | 对象 | { create: 布尔值, exclusive: 布尔值 }，与目录操作参数含义相同 |\r\n| successCallback | 函数 | 成功时调用，参数为创建/获取到的 FileEntry 对象 |\r\n| errorCallback | 函数 | 失败时调用，参数为 FileError 对象 |\r\n##### fileEntry.createWriter(successCallback, errorCallback) → FileWriter.write(blob)\r\n\r\n创建文件写入器，用于向文件写入内容（文本、二进制等）。\r\n\r\n| **参数名** | **类型** | **说明** |\r\n|---|---|---|\r\n| successCallback | 函数 | 成功时调用，参数为 FileWriter 对象，可通过其 write 方法写入内容 |\r\n| errorCallback | 函数 | 失败时调用，参数为 FileError 对象 |\r\n补充：FileWriter 常用事件\r\n\r\n- onwriteend：写入完成时触发\r\n\r\n- onerror：写入失败时触发\r\n\r\n##### fileEntry.file(successCallback, errorCallback) → FileReader.readAs\\*(file)\r\n\r\n获取文件对象，通过 FileReader 读取文件内容，支持多种读取格式。\r\n\r\n支持的读取格式：\r\n\r\n* `readAsText(file)`：以 UTF-8 文本格式读取\r\n\r\n* `readAsDataURL(file)`：以 base64 编码的 data URL 格式读取（适用于图片）\r\n\r\n* `readAsArrayBuffer(file)`：以二进制 ArrayBuffer 格式读取\r\n\r\n* `readAsBinaryString(file)`：以原始二进制字符串格式读取（已废弃）\r\n\r\n##### 删除文件\r\n\r\n`fileEntry.remove(successCallback, errorCallback)`\r\n\r\n\r\n### 4. 错误处理\r\n\r\n所有 API 方法失败时都会返回 `FileError` 对象，可通过 `code` 属性识别错误类型。\r\n\r\n#### `FileError` 错误码参考\r\n\r\n\r\n| 错误码常量 | 值 | 描述 |\r\n| --- | --- | --- |\r\n| `FileError.NOT_FOUND_ERR` | 1 | 文件或目录不存在 |\r\n| `FileError.SECURITY_ERR` | 2 | 安全限制（如权限不足） |\r\n| `FileError.ABORT_ERR` | 3 | 操作被用户或系统中止 |\r\n| `FileError.NOT_READABLE_ERR` | 4 | 文件或目录不可读 |\r\n| `FileError.ENCODING_ERR` | 5 | 编码错误（如 URL 格式无效） |\r\n| `FileError.NO_MODIFICATION_ALLOWED_ERR` | 6 | 不允许修改（如只读目录） |\r\n| `FileError.INVALID_STATE_ERR` | 7 | 状态无效（如向已关闭的 FileWriter 写入） |\r\n| `FileError.SYNTAX_ERR` | 8 | 语法错误（如文件名无效） |\r\n| `FileError.INVALID_MODIFICATION_ERR` | 9 | 修改无效（如跨文件系统移动目录） |\r\n| `FileError.QUOTA_EXCEEDED_ERR` | 10 | 存储配额超出 |\r\n\r\n#### 错误信息辅助函数\r\n\r\n```javascript\r\nfunction getErrorMessage(error) {\r\nconst errorMessages = {\r\n  1: \"文件或目录不存在\",\r\n  2: \"安全错误（权限不足）\",\r\n  3: \"操作已中止\",\r\n  4: \"文件/目录不可读\",\r\n  5: \"编码错误（URL 无效）\",\r\n  6: \"不允许修改（只读）\",\r\n  7: \"状态无效（如写入器已关闭）\",\r\n  8: \"语法错误（文件名无效）\",\r\n  9: \"修改无效（跨文件系统）\",\r\n  10: \"存储配额超出\"\r\n};\r\nreturn errorMessages[error.code] || `未知错误（错误码：${error.code}）`;\r\n}\r\n```\r\n\r\n## 新增特性\r\n\r\n无新增特性，保持原生插件核心功能，适配 OpenHarmony 平台运行需求。\r\n\r\n## 目录结构\r\n\r\n```\r\ncordova-plugin-file/\r\n├── src/                          # 源代码目录\r\n│   └── main/                     # 主要源代码\r\n│       └── cpp/                  # C++ 原生代码\r\n│           └── file/             # 文件模块\r\n│               ├── FileUtils.cpp # 文件操作功能的 C++ 实现\r\n│               └── FileUtils.h   # 文件操作功能的头文件\r\n├── www/                          # Web 资源目录\r\n│   ├── browser/                  # 浏览器相关资源\r\n│   ├── harmony/                  # OHOS 相关资源\r\n│   ├── isChrome.js               # Chrome 浏览器检测\r\n│   ├── DirectoryEntry.js         # 目录条目模型\r\n│   ├── DirectoryReader.js        # 目录读取器\r\n│   ├── Entry.js                  # 文件系统条目基类\r\n│   ├── File.js                   # 文件模型\r\n│   ├── FileEntry.js              # 文件条目模型\r\n│   ├── FileError.js              # 文件错误码定义\r\n│   ├── FileReader.js             # 文件读取器\r\n│   ├── FileSystem.js             # 文件系统模型\r\n│   ├── fileSystemPaths.js        # 文件系统路径配置\r\n│   ├── fileSystemsRoots.js       # 文件系统根目录配置\r\n│   ├── fileSystems.js            # 文件系统管理\r\n│   ├── FileUploadOptions.js      # 文件上传选项\r\n│   ├── FileUploadResult.js       # 文件上传结果\r\n│   ├── FileWriter.js             # 文件写入器\r\n│   ├── Flags.js                  # 文件操作标志位\r\n│   ├── LocalFileSystem.js        # 本地文件系统\r\n│   ├── Metadata.js               # 文件元数据模型\r\n│   ├── ProgressEvent.js          # 进度事件模型\r\n│   ├── requestFileSystem.js      # 请求文件系统\r\n│   └── resolveLocalFileSystemURI.js  # 解析本地文件系统 URI\r\n├── .gitignore                    # Git 忽略文件配置\r\n├── LICENSE                       # 项目开源许可证\r\n├── OAT.xml                       # OpenHarmony 审核配置文件\r\n├── package.json                  # Node.js 包配置\r\n├── plugin.xml                    # Cordova 插件描述文件（核心配置）\r\n└── README.md                     # 项目说明文档\r\n```\r\n\r\n## 贡献代码\r\n\r\n使用过程中发现任何问题都可以提 [Issue](https://gitcode.com/CPF-Cordova/cordova-plugin-file/issues) ，当然也非常欢迎发 [PR](https://gitcode.com/CPF-Cordova/cordova-plugin-file/pulls) 共建。\r\n\r\n## 许可证\r\n\r\n本插件基于 **Apache License 2.0** 开源，详见 [LICENSE](LICENSE) 文件。\r\n\r\n## 官方资源\r\n\r\n- Android 和 iOS：[cordova-plugin-file 官方指南](https://www.npmjs.com/package/cordova-plugin-file)\r\n\r\n- GitCode 仓库：[CPF-Cordova/cordova-plugin-file](https://gitcode.com/CPF-Cordova/cordova-plugin-file)\r\n","readmeFilename":"README.md"}