cordova-plugin-filepath

本项目基于 cordova-plugin-filepath@1.6.0 开发，本文档重点阐述其在 OpenHarmony（OHOS）系统中的具体应用。

• cordova-plugin-filepath
  • 简介
  • 支持平台
  • 下载安装
    • 从 npm 安装（推荐）
    • 指定平台安装 ohos
    • 从 GitCode 仓库安装
    • 离线安装（本地包）
    • 安装后验证
    • 卸载
  • 约束与限制
    • 兼容性
  • 使用示例
    • 示例：文件 URI 转沙箱路径
  • 使用说明
    • 核心 API 说明
      • 方法签名
      • 参数说明
      • 返回值说明
  • 目录结构
  • 贡献代码
  • 许可证
  • 官方资源

简介

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 cordova-plugin-filepath@1.0.0 --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