更新记录

1.0.0（2026-01-22）

1.发布新版本android 文件选择器

平台兼容性

uni-app

uni-app x

xueqiu-file-selector 文件选择器

一个功能强大的 uni-app 文件选择器插件，支持系统文件选择器和自定义文件浏览器两种模式。

功能特点

• 支持单选/多选文件
• 支持按文件类型筛选（图片、视频、音频、文档等）
• 自定义文件浏览器界面，带复选框，操作更便捷
• 支持文件搜索
• 支持多种排序方式（时间、名称、大小、类型）
• 图片缩略图预览
• 点击预览图片、视频、音频
• 自动扫描 Download 目录及子文件夹

平台支持

兼容性

uni-app 版本要求

Android 版本要求

HBuilderX 版本要求

• 最低版本：HBuilderX 3.6.0+
• 推荐版本：HBuilderX 4.0+ (更好的 UTS 支持)

注意事项

1. UTS 插件需要 HBuilderX 3.6.0 及以上版本才能使用
2. 由于插件包含 AndroidManifest.xml 权限配置，需要打包自定义基座才能正常运行
3. 标准基座无法使用本插件的权限功能

安装方式

将 xueqiu-file-selector 文件夹复制到项目的 uni_modules 目录下。

使用前配置

1. 添加页面配置

在 pages.json 中添加以下页面：

{
  "pages": [
    // ... 其他页面
    {
      "path": "pages/file-browser-page",
      "style": {
        "navigationBarTitleText": "选择文件",
        "navigationStyle": "custom"
      }
    },
    {
      "path": "pages/video-preview",
      "style": {
        "navigationBarTitleText": "视频预览",
        "navigationStyle": "custom"
      }
    }
  ]
}

2. 复制必要页面文件

将以下文件复制到项目 pages 目录：

• pages/file-browser-page.vue - 文件浏览器页面
• pages/video-preview.vue - 视频预览页面

3. 打包自定义基座

由于插件需要存储权限，首次使用需要打包自定义基座：

HBuilderX → 运行 → 运行到手机或模拟器 → 制作自定义调试基座

基础用法

方式一：系统文件选择器

import { selectFiles } from '@/uni_modules/xueqiu-file-selector'

// 单选文件
selectFiles({
  multiple: false,
  success: (res) => {
    console.log('选择的文件:', res.files)
  },
  fail: (err) => {
    console.error('选择失败:', err)
  }
})

// 多选文件
selectFiles({
  multiple: true,
  maxCount: 5,
  success: (res) => {
    console.log('选择的文件:', res.files)
  }
})

// 只选择图片
selectFiles({
  fileTypes: ['image/*'],
  multiple: true,
  success: (res) => {
    console.log('选择的图片:', res.files)
  }
})

// 只选择视频
selectFiles({
  fileTypes: ['video/*'],
  success: (res) => {
    console.log('选择的视频:', res.files)
  }
})

// 选择文档文件
selectFiles({
  fileTypes: [
    'application/pdf',
    'application/msword',
    'application/vnd.openxmlformats-officedocument.wordprocessingml.document',
    'application/vnd.ms-excel',
    'application/vnd.openxmlformats-officedocument.spreadsheetml.sheet',
    'text/plain'
  ],
  multiple: true,
  success: (res) => {
    console.log('选择的文档:', res.files)
  }
})

方式二：自定义文件浏览器

自定义文件浏览器提供更好的用户体验，支持复选框直接选择、搜索、排序、预览等功能。

// 打开自定义文件浏览器
uni.navigateTo({
  url: '/pages/file-browser-page',
  events: {
    selectFiles: (data) => {
      console.log('选择的文件:', data.files)
      // 处理选择的文件
      data.files.forEach(file => {
        console.log('文件名:', file.name)
        console.log('文件路径:', file.path)
        console.log('文件大小:', file.size)
        console.log('文件类型:', file.type)
      })
    }
  }
})

API 参数说明

selectFiles(options)

返回结果 FileSelectResult

FileInfo 文件信息

自定义文件浏览器功能

文件类型筛选

顶部标签栏支持按类型筛选：

• 全部 - 显示所有文件
• 文档 - 显示 PDF、Word、Excel、TXT 等文档文件
• 图片 - 显示 JPG、PNG、GIF 等图片文件
• 视频 - 显示 MP4、AVI、MKV 等视频文件
• 音频 - 显示 MP3、WAV、FLAC 等音频文件

排序功能

支持四种排序方式：

• 时间 - 按修改时间排序（默认，最新的在前）
• 名称 - 按文件名字母排序
• 大小 - 按文件大小排序
• 类型 - 按文件类型排序

搜索功能

在搜索框输入关键词，点击搜索按钮即可搜索文件名。

预览功能

• 图片：点击缩略图可全屏预览
• 视频：点击图标跳转到视频播放页面
• 音频：点击图标直接播放

选择文件

• 点击文件信息区域或右侧复选框选择/取消选择文件
• 底部显示已选择数量
• 点击"确定"按钮返回选择结果

常见 MIME 类型

图片

• image/* - 所有图片
• image/jpeg - JPG/JPEG
• image/png - PNG
• image/gif - GIF
• image/webp - WebP

视频

• video/* - 所有视频
• video/mp4 - MP4
• video/x-matroska - MKV
• video/quicktime - MOV

音频

• audio/* - 所有音频
• audio/mpeg - MP3
• audio/wav - WAV
• audio/flac - FLAC

文档

• application/pdf - PDF
• application/msword - DOC
• application/vnd.openxmlformats-officedocument.wordprocessingml.document - DOCX
• application/vnd.ms-excel - XLS
• application/vnd.openxmlformats-officedocument.spreadsheetml.sheet - XLSX
• text/plain - TXT

压缩文件

• application/zip - ZIP
• application/x-rar-compressed - RAR
• application/x-7z-compressed - 7Z

其他

• application/vnd.android.package-archive - APK
• */* - 所有文件

权限说明

插件会自动申请以下权限：

Android 12 及以下

• READ_EXTERNAL_STORAGE - 读取外部存储

Android 13 及以上

• READ_MEDIA_IMAGES - 读取图片
• READ_MEDIA_VIDEO - 读取视频
• READ_MEDIA_AUDIO - 读取音频

注意事项

1. 首次使用需要打包自定义基座
2. 系统文件选择器多选需要长按进入多选模式
3. 自定义文件浏览器默认扫描最多 100 个文件
4. 自定义文件浏览器会优先显示 Download 目录的文件
5. 排序功能对返回结果生效，不影响系统选择器界面

更新日志

v1.0.0

• 初始版本
• 支持系统文件选择器
• 支持自定义文件浏览器
• 支持文件搜索、排序、预览