更新记录

1.0.0（2026-07-20）

首发：uni-app x 文件选择器。

整页选择器 openFilePicker：分类 tab/搜索/排序/目录导航/多选上限/图片缩略图懒加载/权限被拒自动降级系统选择器
系统选择器 chooseFileSystem：无需存储权限，选中自动拷入应用目录返回可读真实路径，回传自带真实类型识别
增值 API：detectFileType 文件头真实类型识别（防改扩展名伪装，office 容器家族不误报）/scanDirectory 大目录秒扫/makeThumbnail 缩略图
端：Android（设备端到端实测）+ H5；iOS 原生桥与产物已随包就绪，适配下版本解锁

平台兼容性

uni-app x(5.14)

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

nex-filepicker 文件选择器（缩略图 + 类型识别）

uni-app x 专为新一代项目打造的文件选择器：整页浏览器 UI + 图片缩略图 + 真实类型识别（防改扩展名伪装）+ 大目录秒级扫描。Android / iOS / H5 三端可用，开箱即用。

为什么选它

uni-app x 原生支持：市面同类插件多为旧体系（不支持 uni-app x）；本插件为 uni-app x 而生。
整页选择器开箱即用：分类 tab（图片/视频/音频/文档/压缩包）、搜索、排序（名称/大小/时间）、多选上限、图片缩略图，一行代码唤起。
真实类型识别：读取文件头二进制特征识别真实格式——用户把 .exe 改成 .jpg 也能识破，做上传安全校验的刚需。
大目录秒扫：原生高性能遍历，只取元信息不读文件内容，万级文件目录秒级返回。
系统选择器兜底：不想用自绘界面？chooseFileSystem 直调系统文件选择器（无需任何存储权限）。

快速上手

1. 注册选择器页面（使用整页 openFilePicker 时必需；只用 chooseFileSystem 可跳过）

在项目 pages.json 的 pages 数组加入：

{
  "path": "uni_modules/nex-filepicker/pages/browser/browser",
  "style": { "navigationBarTitleText": "选择文件" }
}

2. 唤起选择

import { openFilePicker, chooseFileSystem } from '@/uni_modules/nex-filepicker'

// 整页选择器：多选图片，最多 3 张
const res = await openFilePicker({ types: ['image'], multiple: true, maxCount: 3, maxSize: 0 })
if (!res.cancelled) {
  console.log(res.files) // [{ path, name, size, mtime, mimeType, realType, ... }]
}

// 系统选择器：单选任意文件（无需权限）
const res2 = await chooseFileSystem({ types: [], multiple: false, maxCount: 0, maxSize: 0 })

3. 增值 API 独立可用

import { detectFileType, scanDirectory, makeThumbnail, getDefaultRoot } from '@/uni_modules/nex-filepicker'

// 真实类型识别：realType 与 mimeType 不符且 confident=true ⇒ 扩展名被伪装
const t = detectFileType('/storage/emulated/0/Download/photo.jpg')
// { realType: "image/png", mimeType: "image/jpeg", confident: true }

// 大目录秒扫（只出元信息）。types 逗号分隔（空串=全部），返回 ScanResult，取 .entries
const list = scanDirectory(getDefaultRoot(), 'image', 'size', true, false).entries

// 缩略图（保比例 PNG base64，直接给 <image> 的 src 拼 data URL）
const b64 = makeThumbnail(list[0].path, 96)

API

API	说明
`openFilePicker(options)`	唤起整页选择器，Promise 回传 `{ files, cancelled }`；取消不 reject
`chooseFileSystem(options)`	直调系统选择器（无需存储权限），选中文件自动拷贝进应用目录、返回可直接读的真实路径
`detectFileType(path)`	文件头真实类型识别，返回 `{ realType, mimeType, confident }`
`detectFileTypeFromBytes(header, ext)`	从字节识别（H5 端唯一识别形态；App 端已有字节时免落盘）
`scanDirectory(path, types, sortBy, desc, recursive)`	目录扫描排序（名称/大小/时间、类型过滤、可递归）。`types` 逗号分隔分组（空串=全部），返回 `ScanResult`（取 `.entries` 拿 `FileEntry[]`）
`makeThumbnail(path, maxSize)`	生成保比例缩略图（PNG base64）
`requestPermission(types)`	按类型申请读权限（详见下方平台说明）
`getDefaultRoot()`	自绘浏览器默认根目录

FilePickerOptions：types（image/video/audio/document/archive 分组，空=全部）、multiple、maxCount（0=不限）、maxSize（字节，0=不限）、startPath?。

FileEntry：path（真实绝对路径）、name、size、mtime（秒）、mimeType（类型分组）、realType（识别出的真实类型）、isDir、thumbnail?。

平台说明（如实标注）

端	能力
Android	整页自绘浏览可遍历外部存储（Android 11+ 受系统分区存储策略限制，`Android/data` 等少数系统目录不可读——各家文件管理器同此限制）；媒体缩略/浏览按需申请分媒体权限；`chooseFileSystem` 走系统 SAF 无需任何权限
iOS	`openFilePicker` 由系统文件选择器承载（iOS 正统选择体验：可访问文件 App / iCloud Drive 全部内容），选中自动拷入沙盒返回可读路径并自带类型识别；`scanDirectory`/`makeThumbnail` 作用于沙盒内文件；相册类建议配合系统相册选择使用。最低 iOS 14
H5	`openFilePicker`/`chooseFileSystem` 走浏览器原生文件对话框（`path` 为 blob URL）；`detectFileTypeFromBytes` 类型识别全量可用；目录扫描/路径缩略图不适用于浏览器环境

我们不宣称 iOS 可全盘浏览——那是系统沙盒不允许的（这也是同类插件都仅 Android 的原因之一）。选择本插件前请确认以上边界符合你的场景。

常见问题

openFilePicker 立即返回 cancelled？ 多半是 browser 页未在 pages.json 注册（见快速上手第 1 步）。
Android 13+ 弹了权限框拒绝后还能用吗？ 能——页面会提示改走「系统选择器」（SAF 无需权限）。
realType 为空串？ 表示未做文件头确认（如无头可读），此时以扩展名 mimeType 为准。

版本

见 changelog。问题反馈请在插件市场提问。