# uts-file

**Repository Path**: liujuna/uts-file

## Basic Information

- **Project Name**: uts-file
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-07-04
- **Last Updated**: 2026-07-04

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# file-picker-uts 文件选择器

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

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

## 平台兼容性
| 平台 | 支持度 | 备注 |
| --- | --- | --- |
| Android | 🟢 支持 | 调用原生系统文件选择器 |
| iOS | 🟢 支持 | 调用 UIDocumentPickerViewController |
| 微信小程序 | ➖ 不支持 | 可回退使用 wx.chooseMessageFile |

## API 接口

### chooseFile(options, onSuccess, onCancel)

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

**参数说明：**

| 参数名 | 类型 | 必填 | 描述 |
| --- | --- | --- | --- |
| options | FilePickerOptions | 是 | 配置选项 |
| onSuccess | Function | 是 | 成功回调，返回 FilePickerResult |
| onCancel | Function | 是 | 用户取消回调 |

**FilePickerOptions 参数说明：**

| 属性名 | 类型 | 默认值 | 描述 |
| --- | --- | --- | --- |
| extension | String[] | `[]` | 允许选择的文件类型扩展名数组，如 `['.pdf', '.doc']`。传空数组表示不限制。 |
| count | Number | `1` | 最大选择数量。大于1时开启多选。 |
| onLog | Function | `null` | 原生底层日志回调，用于调试。 |

**FilePickerResult 返回值说明：**

| 属性名 | 类型 | 描述 |
| --- | --- | --- |
| success | Boolean | 是否选择成功 |
| paths | String[] | 选择的文件绝对路径数组（临时文件路径） |

## 使用示例

### 基本使用

```javascript
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，以便同时处理图片、视频和普通文件的选择。

```javascript
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 类型过滤，此时会退化为可选所有文件。