更新记录

1.0.3（2026-03-18）

  • 修复 Android 端部分文件 type 为空导致 image/* 误判 INVALID_TYPE 的问题（增加扩展名 MIME 兜底匹配）。
  • 优化 Android 原生返回文件名提取逻辑，避免出现 raw:/... 全路径作为 name。
  • 新增数量限制错误码 COUNT_EXCEEDED，多选超过 maxCount 时直接报错，不再静默截断。
  • 增强 accept 到平台过滤参数的映射（MIME/通配符 -> 扩展名），提升多端前置过滤效果。
  • 调整示例页 API 的 accept 为 image/*，便于直接验证类型过滤能力。
  • 新增 filename 选项，支持统一重命名返回结果中的文件名（多选自动追加序号）。
  • 调整发布配置：统一为 component-vue，并补充 uni-app x 平台支持声明。
  • 补齐 utssdk/index.uts 规则：增加 accept/maxCount/maxSize/filename 校验与标准错误码映射，提升 uni-app x 实际可用性。
  • 增强 UTS 元数据映射：补充 type/lastModified 兜底与平台 source 标识（uts-android/uts-ios/uts-harmony）。
  • 增强 UTS 选择器前置过滤：accept 自动映射为 extension 参数，减少不符合类型文件被选中。
  • 新增 UTS 单选快捷入口 pickFileNative，并导出 FILE_PICKER_ERROR_CODES_NATIVE 供业务侧复用。
  • 新增 UTS 平台后处理钩子（Android/iOS/Harmony），按平台补齐 name/type/lastModified 并统一兜底。

平台兼容性

uni-app(4.84)

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

uni-app x(4.84)

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

lizhao-choose-file

通用文件选择插件（uni_modules）。

  • 支持 API + 组件双形态
  • 支持 Vue2 / Vue3
  • 覆盖 H5（Chrome / Safari）、微信小程序、app-vue、app-nvue、Android、iOS、鸿蒙
  • 提供统一返回字段与统一错误码
  • 提供 uni-app x UTS 侧能力（accept/maxCount/maxSize/filename 规则对齐）

安装

将本插件放入项目：

uni_modules/lizhao-choose-file

使用方式

1) API

import { pickFile, pickFiles } from '@/uni_modules/lizhao-choose-file/index.js'

const file = await pickFile({
  accept: '.pdf,.doc,.docx',
  maxSize: 10 * 1024 * 1024
})

const files = await pickFiles({
  accept: 'image/*,.pdf',
  multiple: true,
  maxCount: 3,
  maxSize: 10 * 1024 * 1024,
  filename: 'upload-file'
})

2) 组件

<template>
  <lizhao-choose-file
    accept="image/*,.pdf"
    :multiple="true"
    :max-count="3"
    :max-size="10485760"
    @success="onSuccess"
    @cancel="onCancel"
    @error="onError"
    @change="onChange"
  />
</template>

API 说明

pickFile(options): Promise<PickedFile | null>

单文件选择。

pickFiles(options): Promise<PickedFile[]>

多文件选择。

UTS (uni-app x) 入口

  • pickFilesNative(options, success, fail)
  • pickFileNative(options, success, fail)
  • FILE_PICKER_ERROR_CODES_NATIVE

PickOptions

参数 类型 必填 说明
accept string 否 文件类型过滤，默认 */*。支持如 .pdf,.docx、image/*。
multiple boolean 否 是否允许多选，默认 false。
maxCount number 否 最大可选数量，默认 1。当 multiple=false 时按单选处理。
maxSize number 否 单个文件最大体积（字节），默认 0 表示不限制。
readAs 'path' \| 'arrayBuffer' \| 'base64' 否 读取结果类型，默认 path。非 H5 平台会按端能力自动降级。
filename string 否 指定重命名文件名。单选直接使用该名称；多选自动追加序号（如 file_1.pdf）。未带扩展名时保留原扩展名。

PickedFile

参数 类型 必填 说明
name string 是 文件名。
size number 是 文件大小（字节）。
type string 是 MIME 类型或平台返回类型。
path string 是 文件路径（通常为临时路径）。
url string 是 可用于预览的地址（如 H5 的 blob: URL）。
lastModified number 是 最近修改时间戳（毫秒）。
source string 是 数据来源平台标识。
ext string 是 文件扩展名（不含点或按实现返回）。
data ArrayBuffer \| string 否 当 readAs 可用且平台支持时返回文件内容。

错误码

错误码 含义 常见触发场景 建议处理
USER_CANCEL 用户主动取消选择 在选择器中点击返回/取消，或未选中文件就退出 视为正常交互，提示“已取消”即可
PERMISSION_DENIED 文件访问权限被拒绝 系统权限未授权，或平台侧拒绝访问文件 引导用户开启权限后重试
UNSUPPORTED 当前平台能力不支持 运行环境缺少对应 API（如 plus.android / uni.chooseFile 不可用） 做能力降级，或提示当前端暂不支持
COUNT_EXCEEDED 选择数量超过 maxCount 限制 多选时实际选中文件数大于 maxCount 提示用户减少选择数量后重试
INVALID_TYPE 文件类型不符合 accept 规则 选择的文件后缀/MIME 不在允许范围内 提示用户选择符合规则的文件类型
SIZE_EXCEEDED 文件大小超过 maxSize 限制 单文件体积超出配置上限 提示用户更换或压缩文件
UNKNOWN 未归类的异常 底层 API 异常、平台差异或未命中的错误分支 记录日志并提示用户重试

组件 Props / Events

Props

参数 类型 必填 说明
accept string 否 文件类型过滤规则，默认 */*。
multiple boolean 否 是否多选，默认 false。
maxCount number 否 最大可选数量，默认 1。
maxSize number 否 单文件体积上限（字节），默认 0 不限制。
filename string 否 指定重命名文件名，行为与 API 的 filename 一致。
disabled boolean 否 是否禁用组件交互。
auto boolean 否 是否自动触发选择流程（按组件实现生效）。

Events

参数 类型 必填 说明
success (files: PickedFile[]) => void 否 选择成功时触发，返回文件数组。
cancel (err: { code: string; message?: string }) => void 否 用户取消选择时触发。
error (err: { code: string; message?: string }) => void 否 选择失败或校验失败时触发。
change (files: PickedFile[]) => void 否 文件结果变化时触发（可用于统一监听）。

能力边界说明

  • H5 使用 input[type=file]，支持 Chrome/Safari。
  • 微信小程序优先使用 uni.chooseMessageFile，按 accept 推断 type（file/image/video）。
  • H5 端 path/url 返回 blob: 临时对象 URL（用于预览与统一字段，不是持久化磁盘路径）。
  • App-Android 在 APP-PLUS 下优先使用系统文档选择器（ACTION_OPEN_DOCUMENT）。
  • 其他非 H5 端优先走平台能力，当前实现默认回退到 uni.chooseFile。
  • 部分端只返回 url 或临时路径，不保证一定能得到可长期持久化的本地绝对路径。
  • readAs=arrayBuffer/base64 主要在 H5 端可直接得到完整结果，其他端按能力降级。
  • filename 重命名当前作用于返回结果中的 name/ext 字段，不会修改源文件本体路径。

重命名示例（iOS 中文名上传场景）

const file = await pickFile({
  accept: '.pdf,.doc,.docx',
  filename: 'upload-file'
})
// 例如原文件名是 “测试文档.docx”，返回后 name 会变为 “upload-file.docx”

发布前你需要替换

  • 目录名中的 lizhao（作者ID）
  • package.json 中 id、displayName、作者信息
  • license 中版权人

参考

  • https://uniapp.dcloud.net.cn/plugin/publish.html
  • https://uniapp.dcloud.net.cn/api/media/file?id=choosefile

隐私、权限声明

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

无

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

无

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

无

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

暂无用户评论。