更新记录

1.0.1（2026-07-02）

1.0.1 (2026-07-02)

新增功能

• 初始版本发布，支持 Android 和 iOS 平台文件选择
• 支持单文件和多文件选择模式
• 支持 MIME 类型过滤（图片、PDF、视频、音频、文档等）
• 支持通配符匹配（如 image/*）
• 返回完整文件信息（文件名、路径、大小、MIME 类型、扩展名）
• 文件自动缓存到应用沙盒目录

平台兼容性

uni-app(4.0)

azp-filePicker

uni-app x 原生文件选择 UTS 插件，支持单文件/多文件选择，支持 MIME 类型过滤。

支持平台

• Android
• iOS

功能特性

• 支持单文件、多文件选择
• 支持 MIME 类型过滤（图片、PDF、视频、音频、文档等）
• 支持通配符匹配（如 image/*）
• 返回完整文件信息（文件名、路径、大小、MIME 类型、扩展名）
• 文件自动缓存到应用沙盒目录
• 纯原生实现，离线运行，无网络依赖

安装

将 azp-filePicker 目录复制到项目的 uni_modules 下即可。

API

pickFiles(options, callback)

打开系统文件选择器，选择文件后通过回调返回结果。

参数

options (FilePickerOptions)

callback ((result: FilePickerResult) => void)

文件选择完成后的回调函数。

返回值

FilePickerResult

FileInfo

使用示例

基础用法 - 选择单个文件

import { pickFiles, FilePickerOptions, FilePickerResult } from '@/uni_modules/azp-filePicker
'

const options: FilePickerOptions = {
  multiple: false,
  maxCount: 1,
  mimeTypes: [] as string[]  // 不限类型
}

pickFiles(options, (result: FilePickerResult) => {
  if (result.code === 1) {
    const file = result.files[0]
    console.log(`文件名: ${file.name}, 大小: ${file.size}, 路径: ${file.path}`)
  } else if (result.code === 0) {
    console.log('用户取消选择')
  } else {
    console.error('选择失败:', result.msg)
  }
})

选择图片文件

const options: FilePickerOptions = {
  multiple: false,
  maxCount: 1,
  mimeTypes: ['image/*'] as string[]
}

pickFiles(options, (result: FilePickerResult) => {
  if (result.code === 1) {
    const file = result.files[0]
    console.log(`选择了图片: ${file.name}, 类型: ${file.type}`)
  }
})

多选文件（最多 5 个）

const options: FilePickerOptions = {
  multiple: true,
  maxCount: 5,
  mimeTypes: [] as string[]
}

pickFiles(options, (result: FilePickerResult) => {
  if (result.code === 1) {
    for (let i = 0; i < result.files.length; i++) {
      const file = result.files[i]
      console.log(`文件 ${i + 1}: ${file.name} (${file.size} bytes)`)
    }
  }
})

指定多种 MIME 类型

// 仅允许选择图片和 PDF
const options: FilePickerOptions = {
  multiple: false,
  maxCount: 1,
  mimeTypes: ['image/*', 'application/pdf'] as string[]
}

pickFiles(options, (result: FilePickerResult) => {
  if (result.code === 1) {
    console.log('选择了文件:', result.files[0].name)
  }
})

选择文档类型文件

const options: FilePickerOptions = {
  multiple: false,
  maxCount: 1,
  mimeTypes: [
    'application/pdf',
    'application/msword',
    'application/vnd.openxmlformats-officedocument.wordprocessingml.document',
    'application/vnd.ms-excel',
    'application/vnd.openxmlformats-officedocument.spreadsheetml.sheet'
  ] as string[]
}

pickFiles(options, (result: FilePickerResult) => {
  if (result.code === 1) {
    console.log('选择了文档:', result.files[0].name)
  }
})

常用 MIME 类型参考

平台要求

HBuilderX 版本要求：^3.6.0

权限说明

本插件调用系统原生文件选择器，无需额外申请存储权限。

• Android：使用 ACTION_OPEN_DOCUMENT，由系统文件选择器代理访问文件，无需 READ_EXTERNAL_STORAGE 权限。
• iOS：使用 UIDocumentPickerViewController，通过安全作用域机制访问文件，无需额外权限配置。

完整类型定义

/** 文件信息 */
type FileInfo = {
  name: string        // 文件名
  path: string        // 本地缓存路径
  size: number        // 文件大小（字节）
  type: string        // MIME 类型
  extension: string   // 文件扩展名（含点，如 .pdf）
}

/** 文件选择结果 */
type FilePickerResult = {
  code: number        // 1=成功, 0=用户取消, -1=失败
  msg: string         // 结果描述
  files: FileInfo[]   // 选中的文件列表
}

/** 文件选择选项 */
type FilePickerOptions = {
  multiple: boolean     // 是否多选
  maxCount: number      // 最大选择数量（多选时生效）
  mimeTypes: string[]   // 允许的 MIME 类型，空数组表示所有类型
}

/** 打开文件选择器 */
type PickFiles = (
  options: FilePickerOptions,
  callback: (result: FilePickerResult) => void
) => void

实现原理

Android

• 通过 Intent.ACTION_OPEN_DOCUMENT 调起系统文件选择器。
• 使用 ContentResolver 查询文件名和大小。
• 通过 NIO FileChannel 将文件复制到应用缓存目录 file_picker_cache/。
• 多选时设置 EXTRA_ALLOW_MULTIPLE，并在回调中对 MIME 类型进行二次过滤。

iOS

• 通过 UIDocumentPickerViewController（Import 模式）调起系统文件选择器。
• 使用 NSURL.resourceValuesForKeys 获取文件大小。
• 通过 UTTypeCopyPreferredTagWithClass 获取 MIME 类型。
• 使用安全作用域（startAccessingSecurityScopedResource）访问文件，并复制到缓存目录。

注意事项

1. 返回的 path 为文件在应用缓存目录中的副本路径，原始文件不会被修改。
2. 缓存文件不会自动清理，如需释放空间请自行管理缓存目录。
3. 多选模式下，maxCount 用于限制最大选择数量；单选模式下该值不生效。
4. mimeTypes 为空数组时，不限制文件类型，可选择任意文件。
5. Android 端多选时使用通配符 MIME 类型，插件内部会进行二次过滤以确保类型匹配。
6. 部分 Android 定制 ROM 的文件选择器 UI 可能不同，但功能一致。
7. iOS 模拟器中文件选择器可能无法正常工作，请在真机上测试。

版本记录

许可证

详见 license 文件。