{"_id":"@cordova-ohos/cordova-plugin-filepath","_rev":"3-b97aa990c75e5bf55a7f188c5bb83f5f","name":"@cordova-ohos/cordova-plugin-filepath","dist-tags":{"latest":"1.6.1"},"versions":{"1.6.0":{"name":"@cordova-ohos/cordova-plugin-filepath","version":"1.6.0","keywords":["cordova","filepath","ecosystem:cordova","cordova-openharmony"],"author":{"name":"Huawei Device, Inc. Ltd. and","email":"马弓手"},"license":"Apache-2.0","_id":"@cordova-ohos/cordova-plugin-filepath@1.6.0","maintainers":[{"name":"luqi_tan","email":"295099422@qq.com"},{"name":"wanpengsz","email":"wanpengsz@163.com"},{"name":"xkh111","email":"xukaihui11@163.com"}],"bugs":{"url":"https://gitcode.com/OpenHarmony-Cordova/cordova-plugin-filepath/issues"},"dist":{"shasum":"9944a2076adaa497056004039c4a541d3a1457a5","tarball":"https://registry.npmjs.org/@cordova-ohos/cordova-plugin-filepath/-/cordova-plugin-filepath-1.6.0.tgz","fileCount":8,"integrity":"sha512-dtP5KVWT+Y5Mbb7Zbk1NffyKkUz+KBuLZr8lEkExGbnLkNAxPW6Z6rnPxC2lKRMNzFrQjm3Q3ow2I7pUoX7qRQ==","signatures":[{"sig":"MEQCIENVKsuBmj382KZgAtSwpdjUQ9iHLLXGkRVy/KLdtIgTAiBVA2255w7mn6m9O7LNG5nETZIZkK5F+qS/01j7co6mxg==","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":27616},"cordova":{"id":"cordova-plugin-filepath","platforms":["ohos"]},"engines":{"cordovaDependencies":{"1.6.0":{"hcordova":">=1.0.0","@cordova-ohos/ohos":">=2.0.0"}}},"gitHead":"3f95984017df2efd34ef10539329d993df6a07cb","_npmUser":{"name":"wanpengsz","email":"wanpengsz@163.com"},"repository":{"url":"gitcode:OpenHarmony-Cordova/cordova-plugin-filepath","type":"git"},"_npmVersion":"9.6.2","description":"Cordova File Path Plugin","directories":{},"_nodeVersion":"20.16.0","_hasShrinkwrap":false,"_npmOperationalInternal":{"tmp":"tmp/cordova-plugin-filepath_1.6.0_1773992392835_0.15819225241134172","host":"s3://npm-registry-packages-npm-production"}},"1.6.1":{"name":"@cordova-ohos/cordova-plugin-filepath","version":"1.6.1","description":"Cordova File Path Plugin","cordova":{"id":"cordova-plugin-filepath","platforms":["ohos"]},"repository":{"type":"git","url":"gitcode:CPF-Cordova/cordova-plugin-filepath"},"bugs":{"url":"https://gitcode.com/CPF-Cordova/cordova-plugin-filepath/issues"},"keywords":["cordova","filepath","ecosystem:cordova","cordova-openharmony"],"engines":{"cordovaDependencies":{"1.6.1":{"@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-filepath@1.6.1","gitHead":"1688f3492b58a7c378abac7b2dc9e121134aec92","_nodeVersion":"22.0.0","_npmVersion":"10.5.1","dist":{"integrity":"sha512-eJBwbDTvCRBqnVIPe1TVj6f/4zJR8sS/sH5SGWEheTf+4Lfi5MBF2CWBznjDbXlC0nC8Jv6wkw+BC/FWVryaBA==","shasum":"8bba79fb1bcb57a6147475668d1c4d3cf21f3bf3","tarball":"https://registry.npmjs.org/@cordova-ohos/cordova-plugin-filepath/-/cordova-plugin-filepath-1.6.1.tgz","fileCount":9,"unpackedSize":43670,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEYCIQDnKkplp9Og1BBIBxAp1E2QU+gPtGB5L1D4zZ2aj1IKPwIhALKRR1obkzv6QSx3Ccz3AAPrzlkN4RR2O1RdbcPq8p1E"}]},"_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-filepath_1.6.1_1785146497558_0.5820861353544204"},"_hasShrinkwrap":false}},"time":{"created":"2026-03-20T07:39:52.357Z","modified":"2026-07-27T10:01:38.086Z","1.6.0":"2026-03-20T07:39:52.961Z","1.6.1":"2026-07-27T10:01:37.721Z"},"bugs":{"url":"https://gitcode.com/CPF-Cordova/cordova-plugin-filepath/issues"},"author":{"name":"Huawei Device, Inc. Ltd. and","email":"马弓手"},"license":"Apache-2.0","keywords":["cordova","filepath","ecosystem:cordova","cordova-openharmony"],"repository":{"type":"git","url":"gitcode:CPF-Cordova/cordova-plugin-filepath"},"description":"Cordova File Path 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-filepath</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-filepath@1.6.0](https://www.npmjs.com/package/cordova-plugin-filepath/v/1.6.0) 开发，本文档重点阐述其在 OpenHarmony（OHOS）系统中的具体应用。\r\n\r\n- [cordova-plugin-filepath](#cordova-plugin-filepath)\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    - [示例：文件 URI 转沙箱路径](#示例文件-uri-转沙箱路径)\r\n  - [使用说明](#使用说明)\r\n    - [核心 API 说明](#核心-api-说明)\r\n      - [方法签名](#方法签名)\r\n      - [参数说明](#参数说明)\r\n      - [返回值说明](#返回值说明)\r\n  - [目录结构](#目录结构)\r\n  - [贡献代码](#贡献代码)\r\n  - [许可证](#许可证)\r\n  - [官方资源](#官方资源)\r\n\r\n\r\n## 简介\r\n\r\ncordova-plugin-filepath 是专为 Cordova 应用设计的文件路径转换插件，核心解决移动平台下文件 URL 与真实文件路径的转换难题。在 Cordova 应用开发中，通过系统 API（如文件选择器、相机）获取的文件 URL 格式往往不便于直接使用，该插件提供简单易用的 API，可将这些特殊格式的文件 URL 转换为应用可直接访问的沙箱路径，同时也支持将沙箱路径反向转换为平台特定的 URL，适配多平台差异，本文档重点说明其在 OHOS 系统中的应用方法。\r\n\r\n## 支持平台\r\n\r\n- **Android**：API 21 及以上\r\n\r\n- **iOS**：11.0 及以上\r\n\r\n- **OHOS**：5.0 及以上\r\n\r\n## 下载安装\r\n\r\n通过 Cordova CLI 或 Ionic CLI 即可快速安装插件，支持从 npm 仓库或 GitCode 仓库获取，适配 OHOS 平台安装需求。\r\n\r\n### 从 npm 安装（推荐）\r\n\r\n```bash\r\n# 安装 hcordova 命令化工具\r\nnpm install -g hcordova\r\n\r\n# Cordova CLI 全平台安装插件\r\nhcordova plugin add cordova-plugin-filepath\r\n\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-filepath --platform ohos\r\n\r\n# 仅安装到 OHOS 平台，指定 1.0.0 版本\r\nhcordova plugin add cordova-plugin-filepath@1.0.0 --platform ohos\r\n\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-filepath.git --platform ohos\r\n\r\n# 指定标签/分支安装\r\nhcordova plugin add https://gitcode.com/CPF-Cordova/cordova-plugin-filepath.git@develop --platform ohos\r\n\r\n```\r\n\r\n### 离线安装（本地包）\r\n\r\n适用于无网络环境，先下载插件包到本地，再执行离线安装：\r\n\r\n```bash\r\n# 下载插件包到本地（示例路径：~/Downloads/cordova-plugin-filepath）\r\n# 执行离线安装\r\nhcordova plugin add ~/Downloads/cordova-plugin-filepath --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-filepath \r\n\r\n# 指定 OHOS 平台卸载\r\nhcordova plugin remove cordova-plugin-filepath --platform ohos\r\n\r\n```\r\n\r\n## 约束与限制\r\n\r\n- 平台版本约束：需符合各平台最低版本要求（Android API 21+、iOS 11.0+、OHOS 5.0+），低于该版本可能出现功能异常\r\n\r\n- URL 格式要求：需传入系统 API（如文件选择器、相机）返回的标准文件 URL，非标准格式 URL 可能导致转换失败\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以下提供 OHOS 平台常用使用示例，结合媒体选择插件获取文件 URI，实现路径转换功能，可直接复制到项目中调试使用，所有示例均需在 `deviceready` 事件触发后执行。\r\n\r\n### 示例：文件 URI 转沙箱路径\r\n\r\n结合 MediaPicker 插件选择图片获取 URI，通过插件 API 将 URI 转换为应用可直接访问的沙箱路径，包含成功与失败回调处理。\r\n\r\n```javascript\r\nfunction selectPhotoUri() {\r\n    // 需 MediaPicker 插件配合\r\n    var cameraOptions = { quality: 25,mediaType: Camera.MediaType.PICTURE };// see cordova camera docs\r\n    var args = {\r\n        'selectMode': 101, // 101=picker image and video , 100=image , 102=video\r\n        'maxSelectCount': 1 // default 40 (Optional)\r\n    };\r\n\r\n    // 选择一个图片获取 uri\r\n    MediaPicker.getMedias(args, function(medias) {\r\n        if(medias.length > 0) {\r\n            window.FilePath.resolveNativePath(medias[0].uri, function(filePath) {\r\n                document.getElementById(\"uriPath\").innerHTML = \"uri:\"+medias[0].uri;\r\n                document.getElementById(\"filePath\").innerHTML = \"path:\"+filePath;\r\n            }, function(error) {\r\n                document.getElementById(\"filePath\").innerHTML = JSON.stringify(error);\r\n            });\r\n        }\r\n    }, function(e) { console.log(e) }, cameraOptions);\r\n}\r\n\r\n```\r\n\r\n## 使用说明\r\n\r\n本插件核心功能为文件 URL 与沙箱路径的双向转换，适配 OHOS 平台特性，提供两种调用方式（Promise 方式、回调函数方式），核心 API 及使用说明如下。\r\n\r\n### 核心 API 说明\r\n\r\n插件核心 API 为 `window.FilePath.resolveNativePath`，用于实现文件 URL 与沙箱路径的转换，支持 Promise 和回调函数两种调用方式，满足不同开发习惯需求。\r\n\r\n#### 方法签名\r\n\r\n```javascript\r\n\r\n// 回调函数方式\r\nwindow.FilePath.resolveNativePath(url, successCallback, errorCallback)\r\n\r\n```\r\n\r\n#### 参数说明\r\n\r\n| **参数名** | **类型** | **说明** |\r\n|---|---|---|\r\n| url | string | 必填，系统 API（如文件选择器、相机）返回的文件 URL，需为平台标准格式 |\r\n| successCallback | Function | 可选（回调方式必填），转换成功回调，参数为 filePath（字符串类型，转换后的沙箱路径） |\r\n| errorCallback | Function | 可选（回调方式必填），转换失败回调，参数为 error（对象类型，包含错误信息） |\r\n#### 返回值说明\r\n\r\n- 回调函数方式：无返回值，通过 successCallback 和 errorCallback 处理转换结果\r\n\r\n## 目录结构\r\n\r\n```\r\ncordova-plugin-filepath/\r\n├── src/                          # 源代码目录\r\n│   └── main/                     # 主要源代码\r\n│       └── cpp/                  # C++ 原生代码\r\n│           └── file/             # 文件模块\r\n│               ├── FilePath.cpp  # 文件路径处理功能的 C++ 实现\r\n│               └── FilePath.h    # 文件路径处理功能的头文件\r\n├── www/                          # Web 资源目录\r\n│   └── FilePath.js               # JavaScript 文件路径接口（Cordova 桥接层）\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-filepath/issues) ，当然也非常欢迎发 [PR](https://gitcode.com/CPF-Cordova/cordova-plugin-filepath/pulls) 共建。\r\n\r\n## 许可证\r\n\r\n本插件基于 **Apache License** 开源，详见 [LICENSE](LICENSE) 文件。\r\n\r\n## 官方资源\r\n\r\n- Android 和 iOS：[cordova-plugin-filepath 官方指南](https://www.npmjs.com/package/cordova-plugin-filepath)\r\n\r\n- GitCode 仓库：[CPF-Cordova/cordova-plugin-filepath](https://gitcode.com/CPF-Cordova/cordova-plugin-filepath)\r\n","readmeFilename":"README.md"}