更新记录

1.0.0（2026-10-13）

  • 首次发布。
  • 新增 chooseFile 文件选择接口，支持选择任意文件并返回详细信息。
  • 返回信息包含：名称、扩展名、MIME 类型、大小、文件分类、图片宽高、视频时长、最后修改时间。
  • 支持多选，count 控制数量，超出部分自动截断。
  • 支持 Android / iOS / Web / HarmonyOS 四端。
  • 统一错误码：9011001 参数错误、9011002 用户取消、9011003 读取文件信息失败、9011004 不支持的文件类型、9011005 平台不支持。

平台兼容性

uni-app(5.0)

Vue2 Vue3 Chrome Safari app-vue app-nvue Android iOS 鸿蒙
√ √ √ √ √ √ √ √ √
微信小程序 支付宝小程序 抖音小程序 百度小程序 快手小程序 京东小程序 鸿蒙元服务 QQ小程序 飞书小程序 小红书小程序 快应用-华为 快应用-联盟
× × - - - - - - - - - -

uni-app x(5.0)

Chrome Safari Android iOS 鸿蒙 微信小程序
√ √ √ √ √ ×

其他

多语言 暗黑模式 宽屏模式 蒸汽模式
× × × √

hy-file-picker 文件选择器

跨平台文件选择 UTS 插件，基于各端原生能力实现文件选择，并返回名称、扩展名、MIME 类型、大小、文件分类、图片宽高、音视频时长、最后修改时间等详细信息，同一套 API 适配 Android / iOS / Web / HarmonyOS。

平台支持

平台 支持 实现方式
Android √ ACTION_OPEN_DOCUMENT（SAF）+ ContentResolver + BitmapFactory / MediaMetadataRetriever
iOS √ UIDocumentPickerViewController + UniformTypeIdentifiers + AVFoundation
Web √ input[type=file] + Image / video / audio
HarmonyOS √ DocumentViewPicker + @ohos.file.fs + ImageSource / AVMetadataExtractor

小程序端暂不支持。 iOS 需在 macOS 环境下编译验证。

安装

将 hy-file-picker 目录放入项目的 uni_modules 下即可，无需手动注册（uni_modules 自动引入）。

使用

uni-app x

import { chooseFile } from '@/uni_modules/hy-file-picker'

chooseFile({
  count: 1,
  type: 'all',
  success: (res) => {
    console.log('选择成功', res.tempFilePaths, res.files)
  },
  fail: (err) => {
    console.error('选择失败', err.errCode, err.errMsg)
  },
  complete: (res) => {
    console.log('调用结束', res)
  }
})

uni-app (Vue2 / Vue3)

import { chooseFile } from '@/uni_modules/hy-file-picker'

chooseFile({
  count: 1,
  type: 'all',
  success(res) {},
  fail(err) {},
  complete(res) {}
})

API

chooseFile(options)

拉起系统文件选择器选择文件。

参数 类型 必填 说明
count number 否 最多可选文件数量，默认 1；大于 1 时支持多选。系统文件选择器（鸿蒙除外）不提供数量硬限制，超出部分自动截断，仅返回前 count 个
type string 否 文件类型过滤，可选 'all'（默认）/ 'image' / 'video' / 'audio' / 'file'
extensions string[] 否 扩展名过滤（不含点，如 ['pdf','docx']），默认不限制。仅 Android / Web 平台支持，其他平台忽略
success function 否 成功回调
fail function 否 失败回调
complete function 否 结束回调（成功、失败均执行）

成功回调 res

字段 类型 说明
tempFilePaths string[] 所选文件的路径数组
files FileInfo[] 所选文件的详细信息数组

FileInfo

字段 类型 说明
name string 文件名（含扩展名），如 report.pdf
path string 文件路径。App / 鸿蒙为应用缓存目录下的本地绝对路径；Web 为 objectURL（blob: 开头）
size number 文件大小，单位字节
extension string 扩展名（不含点，小写），如 pdf；无扩展名为空字符串
mimeType string MIME 类型，如 application/pdf；未知为空字符串
type string 文件分类：image / video / audio / file
isDirectory boolean 是否为目录（当前选择结果均为 false）
width number 图片宽度（px），非图片为 0
height number 图片高度（px），非图片为 0
duration number 音视频时长（秒），非音视频为 0
lastModified number 最后修改时间（时间戳，毫秒），无法获取为 0

错误码

errCode 说明
9011001 参数错误
9011002 用户取消选择
9011003 读取文件信息失败
9011004 不支持的文件类型
9011005 当前平台不支持该能力

注意事项

  • App / 鸿蒙端会将选中文件复制到应用缓存目录，path 返回该缓存文件的本地绝对路径，如需长期保留请自行转存。
  • extensions 仅 Android / Web 平台生效；iOS 通过扩展名推断 UTType 过滤，鸿蒙通过后缀名过滤（能力受系统限制）。
  • count 为期望的最大数量：系统文件选择器（鸿蒙除外）不提供数量硬限制，若用户选择的文件数量超过 count，插件仅返回前 count 个，其余自动忽略。
  • Web 端用户取消时会触发 cancel 事件（现代浏览器支持），部分旧浏览器可能无回调。
  • 未配置鸿蒙应用包名与签名证书时，仅能编译打包，无法安装到设备运行。

更新日志

见 changelog.md

隐私、权限声明

1. 本插件需要申请的系统权限列表：

无

2. 本插件采集的数据、发送的服务器地址、以及数据用途说明：

插件不采集任何数据

3. 本插件是否包含广告，如包含需详细说明广告表达方式、展示频率：

无

评论列表 撰写评论 向官方投诉

暂无用户评论。