更新记录

1.0.0（2026-04-12）

• 首次发布
• 支持 H5、微信小程序
• 提供统一 chooseFile（Promise + 回调重载）
• 用法与uni.chooseFile API保持一致
• 提供 App(Android/iOS/Harmony) 占位实现
• 提供统一错误规范

平台兼容性

uni-app(5.0)

uni-app x(5.0)

# cross-file-picker

跨端文件选择插件（UTS）。

## 功能说明

统一封装 `chooseFile`，按平台自动适配：

- **H5**：使用 `uni.chooseFile`
- **微信小程序**：
  - `type: 'all'` -> `wx.chooseMessageFile`
  - `type: 'image'` -> `uni.chooseImage`
  - `type: 'video'` -> `uni.chooseVideo`
- **App(Android / iOS / HarmonyOS)**：当前版本为占位实现（返回 `not implemented`）

---

## API

### `chooseFile(options)`

同名 `chooseFile` 同时支持两种风格：

1. Promise 风格
2. 回调风格（`success / fail / complete`）

---

## 参数

### ChooseFileOptions

| 参数 | 类型 | 默认值 | 必填 | 说明 |
|---|---|---:|---|---|
| count | number | 1 | 否 | 最多选择数量 |
| type | `'all' \| 'image' \| 'video'` | `'all'` | 否 | 选择类型 |
| extension | `string[]` | `[]` | 否 | 后缀过滤，如 `['.pdf','docx']` |

### extension 说明（重要）

`extension` 支持以下两种写法（都可以）：

- 带点：`['.pdf', '.docx']`
- 不带点：`['pdf', 'docx']`

插件内部会自动按平台适配：

- **H5**：自动转为带点格式（如 `.pdf`）
- **微信小程序**（`wx.chooseMessageFile`）：自动转为**不带点小写**（如 `pdf`）

你只需要按习惯传参即可。

---

## 返回结果

### ChooseFileResult

| 字段 | 类型 | 说明 |
|---|---|---|
| tempFilePaths | `string[]` | 临时文件路径数组 |
| tempFiles | `UTSFileItem[]` | 文件对象数组 |

### UTSFileItem

| 字段 | 类型 | 说明 |
|---|---|---|
| path | string | 本地临时路径 |
| size | number | 文件大小（字节） |
| name | string? | 文件名（部分平台支持） |
| type | string? | 文件类型（部分平台支持） |

---

## 使用示例

### Promise 风格

```ts
import { chooseFile } from '@/uni_modules/cross-file-picker/utssdk/index.uts'

const res = await chooseFile({
  count: 3,
  type: 'all',
  extension: ['.pdf', 'docx', '.xlsx']
})
console.log(res.tempFiles)

回调风格（官方同款）

import picker from '@/uni_modules/cross-file-picker/utssdk/index.uts'

picker.chooseFile({
  count: 2,
  type: 'all',
  extension: ['pdf', '.docx'],
  success(res) {
    console.log(res.tempFiles)
  },
  fail(err) {
    console.error(err)
  },
  complete(ret) {
    console.log(ret)
  }
})

错误规范

插件统一返回错误对象：

{
  errCode: number,
  errMsg: string,
  cause?: any
}

常见错误码：

• 1002 NOT_SUPPORTED
• 1006 SYSTEM_API_FAIL
• 1008 NOT_IMPLEMENTED

版本记录

见 changelog.md

License

MIT