更新记录

0.1.2（2026-06-09）

改为unixppx示例，优化导出方法，优化微信小程序端校验

0.1.1（2026-06-08）

• 补充付费授权与平台编译限制说明
• 明确传统 uni-app 项目中，普通授权版仅支持 Android / iOS App，且需要先使用自定义基座
• 明确 uni-app x 与源码授权版不受上述限制

0.1.0（2026-06-08）

• 以独立实现方式重写 aw-choose-file 的 Web、Android、iOS、微信小程序四端能力
• 新增 uploadName、filename、cacheNameMode 能力，增强上传场景可控性
• 统一四端 extension 过滤语义与错误回调语义
• App 端默认输出 ASCII 缓存文件名，降低中文路径上传兼容问题
• 同步 uni-app Vue3 与 uni-app x 平台支持声明及说明文档

平台兼容性

uni-app(3.7.9)

uni-app x(3.7.9)

aw-choose-file 文件选择

aw-choose-file 用来补一件事情：把“选中文件”和“准备上传”这两个步骤接顺。

原生文件选择在不同平台下返回值并不完全一致，App 端有时还是系统临时 URI。这个插件会把选中的文件整理成一套统一结果，至少保证下面几件事：

• 业务层拿到的是可以直接继续使用的本地路径
• 返回 uploadName，方便上传时自己控制服务端文件名
• 默认生成 ASCII 缓存文件名，减少中文路径带来的兼容问题
• extension 过滤在 Web、Android、iOS、微信小程序四端行为一致

适用平台

• uni-app Vue3：Web / Android / iOS / 微信小程序
• uni-app x：Web / Android / iOS / 微信小程序

说明：iOS 当前已完成编译验证，但暂时没有苹果真机做完整回归测试。

授权与编译限制

由于 uni-app 官方对 UTS 付费加密插件的发布机制存在限制，请在接入前先区分“普通授权版”和“源码授权版”：

• 普通授权版：在传统 uni-app 项目中，仅支持 Android / iOS App 端使用
• 普通授权版：在传统 uni-app 项目中，如需使用 App 端能力，需要先制作并运行自定义基座
• 普通授权版：在传统 uni-app 项目中，H5 / 微信小程序 端不支持直接编译运行
• uni-app x：不受上述限制，可按插件声明的平台直接编译运行
• 源码授权版：不受加密云编译限制，uni-app 与 uni-app x 均可按源码方式接入

原因说明：

• UTS 付费加密插件在发行到 Web / 小程序 / 鸿蒙 等平台时，需要走云端编译
• 这条云端编译链路目前仅支持 uni-app x 项目，不支持传统 uni-app 项目
• 因此，传统 uni-app 项目下的普通授权版，实际只建议用于 Android / iOS App

如果你的项目是传统 uni-app，并且目标平台包含 H5 或 微信小程序，请优先购买 源码授权版，或直接在 uni-app x 项目中使用普通授权版

基本用法 可下载示例项目查看完整写法及功能体验

如果不想单独下载示例项目，也可以直接查看插件目录里的示例文件：

• components/aw-choose-file-demo-x.uvue：uni-app x 示例页
• components/aw-choose-file-demo.vue：uni-app Vue 示例页

import { chooseFile } from '@/uni_modules/aw-choose-file';

chooseFile({
  count: 1,
  type: 'file',
  extension: ['pdf'],
  filename: 'ceshi001',
  cacheNameMode: 'ascii',
  success(res) {
    const file = res.tempFiles[0];
    console.log(file.name);
    console.log(file.path);
    console.log(file.uploadName);
  },
});

返回字段

tempFiles 里的每一项包含这些字段：

• name：原始文件名
• path：插件生成的本地缓存路径
• uploadName：建议上传文件名
• extension：扩展名，不带 .
• size：文件大小，单位 B
• time：选择时间戳
• type：image / video / file

参数说明

• count：最多选择数量，默认 100
• type：all / image / video / file(file 不同平台不同表现，建议通过 extension 限制)
• extension：扩展名白名单，可写 pdf 或 .pdf
• filename：自定义缓存文件基础名；多文件时自动补序号
• cacheNameMode：ascii / original，默认 ascii
• success / fail / complete：标准回调

上传示例

如果项目使用 uniCloud.uploadFile，可以直接按下面这样接：

import { chooseFile } from '@/uni_modules/aw-choose-file';

chooseFile({
  count: 1,
  type: 'image',
  filename: 'cover',
  cacheNameMode: 'ascii',
  success: async (res) => {
    const file = res.tempFiles[0];
    const uploadRes = await uniCloud.uploadFile({
      filePath: file.path,
      cloudPath: `demo/aw-choose-file/${file.uploadName}`,
      fileType: file.type,
    });
    console.log(uploadRes.fileID);
  },
});

如果你需要在 uni-app x 页面里声明参数类型或文件列表类型，建议这样写：

import { chooseFile, type ChooseFileItem, type ChooseFileOption } from '@/uni_modules/aw-choose-file';

const options = {
  type: 'image',
  count: 9,
} as ChooseFileOption;

const tempFiles = ref<ChooseFileItem[]>([]);

这里的关键点只有两个：

• filePath 用插件返回的 path
• 云端文件名直接用插件返回的 uploadName

说明

• type: 'file' 表示排除图片和视频，仅保留普通文件（建议使用 extension 方式）
• Android 和 iOS 返回的是插件复制后的缓存路径，不直接把系统 URI 暴露给业务层
• 微信小程序通过 wx.chooseMessageFile 返回平台临时文件路径，并统一补齐 uploadName、extension、type
• 如果原始文件名包含中文或特殊字符，默认会转成适合上传的 ASCII 缓存文件名
• iOS 目录选择器依赖 deploymentTarget >= 11
• App 端会优先根据 type 和常见 extension 收窄系统选择器显示范围；不同机型、不同文件管理器的实际展示效果可能略有差异，所以插件仍会在选择完成后再做一次结果过滤
• 微信小程序只能从会话文件中选择，不支持像原生文件管理器那样任意浏览本地目录
• 传统 uni-app 项目使用普通授权版时，请不要把插件页中的 Web / 微信小程序 平台勾选直接理解为“加密版可直接在这些端运行”；这些平台在传统 uni-app 下受官方云编译限制
• 有任何问题都可以在聊天群里提问