更新记录

1.0.0（2026-07-03）

file-picker-uts 文件选择器

跨平台原生文件选择插件，支持 Android 和 iOS，基于 UTS 开发。

简介

file-picker-uts 是一个专为 uni-app x / uni-app 设计的原生文件选择插件。它调用系统原生的文件管理器来选择文件，支持单选、多选以及文件类型过滤。

平台兼容性

平台兼容性

uni-app(5.14)

file-picker-uts 文件选择器

跨平台原生文件选择插件，支持 Android 和 iOS，基于 UTS 开发。

简介

file-picker-uts 是一个专为 uni-app x / uni-app 设计的原生文件选择插件。它调用系统原生的文件管理器来选择文件，支持单选、多选以及文件类型过滤。

平台兼容性

API 接口

chooseFile(options, onSuccess, onCancel)

打开系统文件选择器进行文件选择。

参数说明：

FilePickerOptions 参数说明：

FilePickerResult 返回值说明：

使用示例

基本使用

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

// 选择单个 PDF 或 DOC 文件
chooseFile(
  {
    extension: ['.pdf', '.doc', '.docx'],
    count: 1
  },
  (result) => {
    if (result.success) {
      console.log('选择的文件路径:', result.paths);
      // 可以使用 uni.uploadFile 上传文件
    }
  },
  () => {
    console.log('用户取消了选择');
  }
);

结合 hook 使用（推荐）

你可以自行封装一个统一的 useMediaPicker hook，以便同时处理图片、视频和普通文件的选择。

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

export function pickFile() {
  return new Promise((resolve) => {
    // #ifndef MP-WEIXIN
    chooseFile(
      { extension: [], count: 5 },
      (result) => {
        resolve(result.paths);
      },
      () => {
        resolve(null);
      }
    );
    // #endif

    // #ifdef MP-WEIXIN
    uni.chooseMessageFile({
      count: 5,
      type: 'file',
      success: (res) => {
        resolve(res.tempFiles.map(f => f.path));
      },
      fail: () => resolve(null)
    });
    // #endif
  });
}

注意事项

1. 文件路径：插件返回的路径为复制到应用沙盒缓存目录的临时路径，可以直接用于 uni.uploadFile 等 API，应用重启或清理缓存时可能会被系统回收。
2. iOS 平台：内部默认获取了 TopViewController 来弹出 UIDocumentPickerViewController，如果当前页面有复杂的 presentedViewController 层级，可能会有轻微延迟动画，插件内已做了兼容处理。
3. Android 平台：多选文件的后缀名过滤，某些定制的 Android 系统文件管理器可能不支持 MIME 类型过滤，此时会退化为可选所有文件。