@cordova-ohos/cordova-plugin-filepath
v1.6.1
Published
Cordova File Path Plugin
Readme
cordova-plugin-filepath
本项目基于 [email protected] 开发，本文档重点阐述其在 OpenHarmony（OHOS）系统中的具体应用。
简介
cordova-plugin-filepath 是专为 Cordova 应用设计的文件路径转换插件，核心解决移动平台下文件 URL 与真实文件路径的转换难题。在 Cordova 应用开发中，通过系统 API（如文件选择器、相机）获取的文件 URL 格式往往不便于直接使用，该插件提供简单易用的 API，可将这些特殊格式的文件 URL 转换为应用可直接访问的沙箱路径，同时也支持将沙箱路径反向转换为平台特定的 URL，适配多平台差异，本文档重点说明其在 OHOS 系统中的应用方法。
支持平台
Android：API 21 及以上
iOS：11.0 及以上
OHOS：5.0 及以上
下载安装
通过 Cordova CLI 或 Ionic CLI 即可快速安装插件，支持从 npm 仓库或 GitCode 仓库获取，适配 OHOS 平台安装需求。
从 npm 安装（推荐）
# 安装 hcordova 命令化工具
npm install -g hcordova
# Cordova CLI 全平台安装插件
hcordova plugin add cordova-plugin-filepath
指定平台安装 ohos
仅为 OHOS 平台安装插件（指定版本示例）：
# 仅安装到 OHOS 平台
hcordova plugin add cordova-plugin-filepath --platform ohos
# 仅安装到 OHOS 平台，指定 1.0.0 版本
hcordova plugin add [email protected] --platform ohos
从 GitCode 仓库安装
仅为 OHOS 平台安装开发版本插件：
# 仅安装到 OHOS 平台，安装开发版本
hcordova plugin add https://gitcode.com/CPF-Cordova/cordova-plugin-filepath.git --platform ohos
# 指定标签/分支安装
hcordova plugin add https://gitcode.com/CPF-Cordova/cordova-plugin-filepath.git@develop --platform ohos
离线安装（本地包）
适用于无网络环境，先下载插件包到本地，再执行离线安装：
# 下载插件包到本地（示例路径：~/Downloads/cordova-plugin-filepath）
# 执行离线安装
hcordova plugin add ~/Downloads/cordova-plugin-filepath --platform ohos安装后验证
安装完成后，可通过以下命令验证插件是否成功添加到项目中：
# 查看已安装的插件列表，若包含本插件 ID 则表示插件已成功安装
hcordova plugin list卸载
# Cordova CLI 全平台卸载
hcordova plugin remove cordova-plugin-filepath
# 指定 OHOS 平台卸载
hcordova plugin remove cordova-plugin-filepath --platform ohos
约束与限制
平台版本约束：需符合各平台最低版本要求（Android API 21+、iOS 11.0+、OHOS 5.0+），低于该版本可能出现功能异常
URL 格式要求：需传入系统 API（如文件选择器、相机）返回的标准文件 URL，非标准格式 URL 可能导致转换失败
兼容性
支持：
| 项目 | 版本/信息 | |-----|--------| | SDK | API12+ | | IDE | DevEco Studio: 5.0+ | | ROM | 5.1+ | | Emulator | OpenHarmony 6.0+ |
在以下版本中已测试通过：
| 项目 | 版本/信息 | |-----|--------| | @cordova-ohos/ohos | 14.0.1-ohos-14.0.1 | | SDK | 5.0.0(12) | | IDE | DevEco Studio: 6.0.13.200 | | ROM | 5.1.0.120 SP3 | | Emulator | OpenHarmony 6.0.1(21) |
使用示例
以下提供 OHOS 平台常用使用示例，结合媒体选择插件获取文件 URI，实现路径转换功能，可直接复制到项目中调试使用，所有示例均需在 deviceready 事件触发后执行。
示例：文件 URI 转沙箱路径
结合 MediaPicker 插件选择图片获取 URI，通过插件 API 将 URI 转换为应用可直接访问的沙箱路径，包含成功与失败回调处理。
function selectPhotoUri() {
// 需 MediaPicker 插件配合
var cameraOptions = { quality: 25,mediaType: Camera.MediaType.PICTURE };// see cordova camera docs
var args = {
'selectMode': 101, // 101=picker image and video , 100=image , 102=video
'maxSelectCount': 1 // default 40 (Optional)
};
// 选择一个图片获取 uri
MediaPicker.getMedias(args, function(medias) {
if(medias.length > 0) {
window.FilePath.resolveNativePath(medias[0].uri, function(filePath) {
document.getElementById("uriPath").innerHTML = "uri:"+medias[0].uri;
document.getElementById("filePath").innerHTML = "path:"+filePath;
}, function(error) {
document.getElementById("filePath").innerHTML = JSON.stringify(error);
});
}
}, function(e) { console.log(e) }, cameraOptions);
}
使用说明
本插件核心功能为文件 URL 与沙箱路径的双向转换，适配 OHOS 平台特性，提供两种调用方式（Promise 方式、回调函数方式），核心 API 及使用说明如下。
核心 API 说明
插件核心 API 为 window.FilePath.resolveNativePath，用于实现文件 URL 与沙箱路径的转换，支持 Promise 和回调函数两种调用方式，满足不同开发习惯需求。
方法签名
// 回调函数方式
window.FilePath.resolveNativePath(url, successCallback, errorCallback)
参数说明
| 参数名 | 类型 | 说明 | |---|---|---| | url | string | 必填，系统 API（如文件选择器、相机）返回的文件 URL，需为平台标准格式 | | successCallback | Function | 可选（回调方式必填），转换成功回调，参数为 filePath（字符串类型，转换后的沙箱路径） | | errorCallback | Function | 可选（回调方式必填），转换失败回调，参数为 error（对象类型，包含错误信息） |
返回值说明
- 回调函数方式：无返回值，通过 successCallback 和 errorCallback 处理转换结果
目录结构
cordova-plugin-filepath/
├── src/ # 源代码目录
│ └── main/ # 主要源代码
│ └── cpp/ # C++ 原生代码
│ └── file/ # 文件模块
│ ├── FilePath.cpp # 文件路径处理功能的 C++ 实现
│ └── FilePath.h # 文件路径处理功能的头文件
├── www/ # Web 资源目录
│ └── FilePath.js # JavaScript 文件路径接口（Cordova 桥接层）
├── .gitignore # Git 忽略文件配置
├── LICENSE # 项目开源许可证
├── OAT.xml # OpenHarmony 审核配置文件
├── package.json # Node.js 包配置
├── plugin.xml # Cordova 插件描述文件（核心配置）
└── README.md # 项目说明文档贡献代码
使用过程中发现任何问题都可以提 Issue ，当然也非常欢迎发 PR 共建。
许可证
本插件基于 Apache License 开源，详见 LICENSE 文件。
官方资源
Android 和 iOS：cordova-plugin-filepath 官方指南
GitCode 仓库：CPF-Cordova/cordova-plugin-filepath