更新记录

1.0.0（2026-07-13）

muhtar-file-picker

跨平台文件选择 UTS 插件。Android 和 iOS 均无需额外权限，使用系统原生文件选择器选取任意文件类型。

支持平台

安装

将 muhtar-file-picker 文件夹放入项目 uni_modules/ 目录下即可。

快速开始

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

// 选择任意文件（单选）
const file = await chooseFile({ maxCount: 1, type: 'all' })
if (file) {
  console.log('文件名:', file[0].name)
  console.log('路径:', file[0].tempFilePath)
  console.log('大小:', file[0].size)
  console.log('类型:', file[0].type)
}

API

chooseFile(options?)

选择文件（支持任意类型）

参数：

返回： Promise<FileResult[] | null>

• 选中文件返回 FileResult[]
• 取消或失败返回 null

chooseImage(maxCount?)

选择图片（快捷方法）

const files = await chooseImage(9)  // 最多选 9 张

chooseVideo(maxCount?)

选择视频（快捷方法）

const files = await chooseVideo(3)  // 最多选 3 个

类型定义

FileResult

type FileResult = {
  tempFilePath: string  // 文件临时路径 / URI
  name: string          // 文件名
  size: number          // 文件大小（字节）
  type: string          // MIME 类型
}

FilePickerOptions

type FilePickerOptions = {
  maxCount?: number
  type?: 'image' | 'video' | 'all'
}

完整示例

<template>
  <view>
    <button @click="pickFile">选择文件</button>
    <view v-for="(file, index) in files">
      <text>{{ file.name }} - {{ file.size }}B</text>
    </view>
  </view>
</template>

<script lang="uts">
import { chooseFile, FileResult } from '@/uni_modules/muhtar-file-picker'

export default {
  data() {
    return {
      files: new Array<FileResult>()
    }
  },
  methods: {
    async pickFile() {
      const result = await chooseFile({ maxCount: 5, type: 'all' })
      this.files = result ?? new Array<FileResult>()
    }
  }
}
</script>

注意事项

1. Android：底层使用 Intent.ACTION_OPEN_DOCUMENT，系统文件选择器，无需 READ_EXTERNAL_STORAGE 权限
2. iOS：使用 UIDocumentPickerViewController，系统文件选择器，无需额外权限
3. 返回的 tempFilePath 为临时路径，如需长期保存请复制到应用沙盒目录
4. iOS 上文件大小通过 NSFileManager 获取，Android 通过 ContentResolver 查询
5. iOS 上 MIME 类型通过文件扩展名推断

平台兼容性

uni-app x(4.0)

muhtar-file-picker

跨平台文件选择 UTS 插件。Android 和 iOS 均无需额外权限，使用系统原生文件选择器选取任意文件类型。

支持平台

安装

将 muhtar-file-picker 文件夹放入项目 uni_modules/ 目录下即可。

快速开始

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

// 选择任意文件（单选）
const file = await chooseFile({ maxCount: 1, type: 'all' })
if (file) {
  console.log('文件名:', file[0].name)
  console.log('路径:', file[0].tempFilePath)
  console.log('大小:', file[0].size)
  console.log('类型:', file[0].type)
}

API

chooseFile(options?)

选择文件（支持任意类型）

参数：

返回： Promise<FileResult[] | null>

• 选中文件返回 FileResult[]
• 取消或失败返回 null

chooseImage(maxCount?)

选择图片（快捷方法）

const files = await chooseImage(9)  // 最多选 9 张

chooseVideo(maxCount?)

选择视频（快捷方法）

const files = await chooseVideo(3)  // 最多选 3 个

类型定义

FileResult

type FileResult = {
  tempFilePath: string  // 文件临时路径 / URI
  name: string          // 文件名
  size: number          // 文件大小（字节）
  type: string          // MIME 类型
}

FilePickerOptions

type FilePickerOptions = {
  maxCount?: number
  type?: 'image' | 'video' | 'all'
}

完整示例

<template>
  <view>
    <button @click="pickFile">选择文件</button>
    <view v-for="(file, index) in files">
      <text>{{ file.name }} - {{ file.size }}B</text>
    </view>
  </view>
</template>

<script lang="uts">
import { chooseFile, FileResult } from '@/uni_modules/muhtar-file-picker'

export default {
  data() {
    return {
      files: new Array<FileResult>()
    }
  },
  methods: {
    async pickFile() {
      const result = await chooseFile({ maxCount: 5, type: 'all' })
      this.files = result ?? new Array<FileResult>()
    }
  }
}
</script>

注意事项

1. Android：底层使用 Intent.ACTION_OPEN_DOCUMENT，系统文件选择器，无需 READ_EXTERNAL_STORAGE 权限
2. iOS：使用 UIDocumentPickerViewController，系统文件选择器，无需额外权限
3. 返回的 tempFilePath 为临时路径，如需长期保存请复制到应用沙盒目录
4. iOS 上文件大小通过 NSFileManager 获取，Android 通过 ContentResolver 查询
5. iOS 上 MIME 类型通过文件扩展名推断

许可证

MIT