---
name: "chooseMedia"
mode: "kit"
versionRequirements:
  - { name: "BaseKit", version: "2.5.0" }
  - { name: "@ray-js/ray", version: "0.5.9" }
platform:
  - "iOS"
  - "Android"
async: true
title: "chooseMedia - 拍摄或从手机相册中选择图片或视频"
---

## chooseMedia

> [VERSION] BaseKit >= 2.5.0 | @ray-js/ray >= 0.5.9

> [PLATFORM] iOS, Android

> ⚡ **支持 Promise 调用** — 不传 success / fail / complete 回调时，该方法返回 Promise。

### 描述

拍摄或从手机相册中选择图片或视频 权限：[scope.camera, scope.writePhotosAlbum]

### 参数

| 属性 | 类型 | 必填 | 默认值 | 最低版本 | 描述 |
| --- | --- | --- | --- | --- | --- |
| `count` | `number` | 否 | `9` | `2.5.0` | 最多可以选择的文件数。 注意：Android13以上的版本，使用的是系统图片选择器，该字段不生效 |
| `mediaType` | `string` | 否 | `"image"` | `2.5.0` | 选择类型, 默认图片 'image' 只能拍摄图片或从相册选择图片 'video' 只能拍摄视频或从相册选择视频 |
| `sourceType` | `string[]` | 否 | `["album", "camera"]` | `2.5.0` | 图片和视频选择的来源, 默认['album', 'camera'] 'album' 从相册选择 'camera' 	使用相机拍摄 |
| `maxDuration` | `number` | 否 | `10` | `2.5.0` | 拍摄视频最长拍摄时间，单位秒。默认10s 时间范围为 3s 至 60s 之间。不限制相册。 |
| `isFetchVideoFile` | `boolean` | 否 | `true` | `3.14.2` | 该参数只对iOS有效 是否拷贝视频： 默认true，拷贝视频，返回视频拷贝地址，返回视频封面地址 false，不拷贝视频，返回视频相册中的地址，返回视频封面图地址 |
| `isClipVideo` | `boolean` | 否 | `false` | `3.14.2` | 该参数只对iOS有效 相册选择的视频是否需要裁剪 默认为false, 不裁剪视频 |
| `maxClipDuration` | `number` | 否 | `60` | `3.14.2` | 视频最长剪辑时间，单位秒。默认60s 需要设置isClipVideo为true才生效 时间范围为 60s 至 600 之间。 选择视频的时长小于15s不裁剪 |
| `isGetAlbumFileName` | `boolean` | 否 | `false` | `3.14.2` | 该参数只对iOS有效 选择导出的文件名称，和相册中文件的名称一致 默认为false, 使用每次文件名称唯一 |
| `isClipVideoAndroid` | `boolean` | 否 | `true` | `3.35.1` | 该参数只对Android有效 芯图定制 后续 isClipVideo合并 相册选择的视频是否需要裁剪 默认为true, 裁剪视频，与原业务表现一致 |
| `complete` | `() => void` | 否 | - | - | 接口调用结束的回调函数（调用成功、失败都会执行） |
| `success` | `(params: Object) => void` ↓见下方 | 否 | - | - | 接口调用成功的回调函数 |
| `fail` | `(params: Object) => void` ↓见下方 | 否 | - | - | 接口调用失败的回调函数 |

#### success 回调参数

| 属性 | 类型 | 最低版本 | 描述 |
| --- | --- | --- | --- |
| `type` | `string` | `3.2.6` | 文件类型 'image' 图片 'video' 视频 |
| `tempFiles` | `TempMediaFileCB[]` | `3.2.6` | 本地临时文件列表 |

#### fail 回调参数

| 属性 | 类型 | 描述 |
| --- | --- | --- |
| `errorMsg` | `string` | 错误信息 |
| `errorCode` | `string \| number` | 错误码 |
| `innerError` | `Object` | 错误扩展 |

##### fail(params).innerError 的属性

| 属性 | 类型 | 描述 |
| --- | --- | --- |
| `errorCode` | `string \| number` | 错误扩展码 |
| `errorMsg` | `string` | 错误扩展信息 |


### 引用对象

##### `interface` TempMediaFileCB

| 属性 | 类型 | 最低版本 | 描述 |
| --- | --- | --- | --- |
| `tempFilePath` | `string` | `3.2.6` | 本地临时文件路径 (本地路径) |
| `size` | `number` | `3.2.6` | 本地临时文件大小，单位 B |
| `duration` | `number` | `3.2.6` | 视频的时间长度 |
| `height` | `number` | `3.2.6` | 视频的高度 |
| `width` | `number` | `3.2.6` | 视频的宽度 |
| `thumbTempFilePath` | `string` | `3.2.6` | 视频缩略图临时文件路径 |
| `fileType` | `string` | `3.2.6` | 文件类型 'image' 	图片 'video' 	视频 |
| `originalVideoPath` | `string` | `3.14.2` | 相册原始视频地址 |


### 示例代码

#### Demo

```tsx
import { chooseMedia } from '@ray-js/ray'

// 拍摄或选择图片/视频（会拉起系统选择器，需手动选择）
chooseMedia({
  count: 1,
  mediaType: "image",
  sourceType: ["album", "camera"],
  maxDuration: 10,
  success: data => console.log("已选：", data.type, data.tempFiles),
  fail: error => console.error(error),
});
```