uni.chooseImage(options) @chooseimage

展示全部

# uni.chooseImage(options)

从本地相册选择图片或使用相机拍照

# chooseImage 兼容性

Web	微信小程序	Android	iOS
4.0	4.41	3.9	4.11

# 参数

名称

类型

必填

默认值

兼容性

描述

options

ChooseImageOptions

是

名称

类型

必备

默认值

兼容性

描述

pageOrientation

string

否

屏幕方向。默认为page.json中的pageOrientation。

合法值	兼容性	描述
auto	-	自动
portrait	-	竖屏显示
landscape	-	横屏显示

albumMode

string

否

"custom"

图片选择模式

合法值	兼容性	描述
custom	-	自定义媒体选择器
system	-	系统媒体选择器

count

number

否

最多可以选择的图片张数，app端不限制，微信小程序最多可支持20个。

sizeType

Array<string>

否

['original','compressed']

original 原图，compressed 压缩图，默认二者都有

sourceType

Array<string>

否

['album','camera']

album 从相册选图，camera 使用相机，默认二者都有

extension

Array<string>

否

根据文件拓展名过滤，每一项都不能是空字符串。默认不过滤。仅H5支持

crop

ChooseImageCropOptions

否

图像裁剪参数，设置后 sizeType 失效。

名称	类型	必备	默认值	兼容性	描述
width	number	是	-	-	裁剪的宽度，单位为px，用于计算裁剪宽高比。
height	number	是	-	-	裁剪的高度，单位为px，用于计算裁剪宽高比。
quality	number	否	80	-	取值范围为1-100，数值越小，质量越低（仅对jpg格式有效）。默认值为80。
resize	boolean	否	-	-	是否将width和height作为裁剪保存图片真实的像素值。默认值为true。注：设置为false时在裁剪编辑界面显示图片的像素值，设置为true时不显示。

success

(callback: ChooseImageSuccess) => void

否

成功则返回图片的本地文件路径列表 tempFilePaths

fail

(callback: IMediaError) => void

否

接口调用失败的回调函数

complete

(callback: any) => void

否

接口调用结束的回调函数（调用成功、失败都会执行）

# ChooseImageSuccess 的属性值

名称

类型

必备

默认值

兼容性

描述

errSubject

string

是

调用API的名称

errMsg

string

是

描述信息

tempFilePaths

Array<string>

是

图片的本地文件路径列表

tempFiles

Array<ChooseImageTempFile>

是

图片的本地文件列表

名称	类型	必备	默认值	兼容性	描述
path	string	是	-	-	本地文件路径
size	number	是	-	-	本地文件大小，单位：B
name	string	否	-	-	包含扩展名的文件名称，仅H5支持
type	string	否	-	-	文件类型，仅H5支持

# IMediaError 的属性值

名称

类型

必备

默认值

兼容性

描述

errCode

number

是

错误码

合法值	兼容性	描述
1101001	-	用户取消
1101002	-	urls至少包含一张图片地址
1101003	-	文件不存在
1101004	-	图片加载失败
1101005	-	未获取权限
1101006	-	图片或视频保存失败
1101007	-	图片裁剪失败
1101008	-	拍照或录像失败
1101009	-	图片压缩失败
1101010	-	其他错误

errSubject

string

是

统一错误主题（模块）名称

data

any

否

错误信息中包含的数据

cause

Error

否

源错误信息，可以包含多个错误，详见SourceError

errMsg

string

是

# 参见

# 示例

hello uni-app x

Template

Script

<template>
  <!-- #ifdef APP -->
  <scroll-view class="page-scroll-view">
  <!-- #endif -->
    <view>
      <page-head :title="title"></page-head>
      <view class="uni-common-mt">
        <view class="uni-list">
          <view class="uni-list-cell cell-pd">
            <view class="uni-list-cell-left uni-label">
              图片来源
            </view>
            <view class="uni-list-cell-right" @click="chooseImageSource">
              <text class="click-t">{{sourceType[sourceTypeIndex]}}</text>
            </view>
          </view>

          <view class="uni-list-cell cell-pd">
            <view class="uni-list-cell-left uni-label">
              图片质量
            </view>
            <view class="uni-list-cell-right" @click="chooseImageType">
              <text class="click-t">{{sizeType[sizeTypeIndex]}}</text>
            </view>
          </view>

          <view class="uni-list-cell cell-pd">
            <view class="uni-list-cell-left uni-label">
              数量限制
            </view>
            <view class="uni-list-cell-right">
              <input class="click-t" :value="countIndex+1" type="number" :maxlength="1" @confirm="chooseImageCount"
                confirm-type="done" />
            </view>
          </view>
          <!-- #ifdef APP -->
          <view class="uni-list-cell cell-pd">
            <view class="uni-list-cell-left uni-label">
              屏幕方向
            </view>
            <view class="uni-list-cell-right" @click="chooseOrientationType">
              <text class="click-t">{{orientationType[orientationTypeIndex]}}</text>
            </view>
          </view>
          <!-- #endif -->
          <!-- #ifdef APP-ANDROID -->
          <view class="uni-list-cell cell-pd">
            <view class="uni-list-cell-left uni-label">
              相册模式
            </view>
            <view class="uni-list-cell-right" @click="albumModeChange">
              <text class="click-t">{{albumModeType[albumModeTypeIndex]}}</text>
            </view>
          </view>
          <!-- #endif -->
          <view class="uni-list-cell cell-pd">
            <view class="uni-list-cell-left uni-label">
              图像裁剪
            </view>
            <view class="uni-list-cell-right">
              <switch :checked="isCrop" @change="switchCrop"></switch>
            </view>
          </view>
          <view ref="cropOptionNode" class="crop-option"
            :style="{'height':isCrop?'200px':'0px','margin-bottom':isCrop?'11px':'0px'}">
            <view class="uni-list-cell cell-pd">
              <view class="uni-list-cell-left item_width">
                图片质量(%)
              </view>
              <view class="uni-list-cell-right">
                <input :value="cropPercent" @confirm="cropPercentConfim" type="number" maxlength="-1" />
              </view>
            </view>
            <view class="uni-list-cell cell-pd">
              <view class="uni-list-cell-left item_width">
                裁剪宽度(px)
              </view>
              <view class="uni-list-cell-right">
                <input :value="cropWidth" @confirm="cropWidthConfim" type="number" maxlength="-1" />
              </view>
            </view>
            <view class="uni-list-cell cell-pd">
              <view class="uni-list-cell-left item_width">
                裁剪高度(px)
              </view>
              <view class="uni-list-cell-right">
                <input :value="cropHeight" @confirm="cropHeightConfim" type="number" maxlength="-1" />
              </view>
            </view>
            <view class="uni-list-cell cell-pd">
              <view class="uni-list-cell-left item_width">
                保留原宽高
              </view>
              <view class="uni-list-cell-right">
                <switch :checked="cropResize" @change="cropResizeChange"></switch>
              </view>
            </view>
          </view>
        </view>

        <view class="uni-list list-pd" style="padding: 15px;">
          <view class="uni-flex" style="margin-bottom: 10px;">
            <view class="uni-list-cell-left">点击可预览选好的图片</view>
            <view style="margin-left: auto;">
              <text class="click-t">{{imageList.length}}/{{countIndex+1}}</text>
            </view>
          </view>
          <view class="uni-flex" style="flex-wrap: wrap;">
            <view v-for="(image,index) in imageList" :key="index" class="uni-uploader__input-box" style="border: 0;">
              <image style="width: 104px; height: 104px;" :src="image" :data-src="image" @tap="previewImage(index)">
              </image>
              <image src="/static/plus.png" class="image-remove" @click="removeImage(index)"></image>
            </view>
            <image class="uni-uploader__input-box" @tap="chooseImage" src="/static/plus.png"></image>
          </view>
        </view>
      </view>
    </view>
  <!-- #ifdef APP -->
  </scroll-view>
  <!-- #endif -->
</template>



<style>
  .cell-pd {
    padding: 11px 15px;
  }

  .click-t {
    color: darkgray;
  }

  .list-pd {
    margin-top: 25px;
  }

  .uni-uploader__input-box {
    margin: 5px;
    width: 104px;
    height: 104px;
    border: 1px solid #D9D9D9;
  }

  .uni-uploader__input {
    position: absolute;
    z-index: 1;
    top: 0;
    left: 0;
    width: 100%;
    height: 100%;
    opacity: 0;
  }

  .image-remove {
    transform: rotate(45deg);
    width: 25px;
    height: 25px;
    position: absolute;
    top: 0;
    right: 0;
    border-radius: 13px;
    background-color: rgba(200, 200, 200, 0.8);
  }

  .item_width {
    width: 130px;
  }

  .crop-option {
    margin-left: 11px;
    margin-right: 11px;
    border-radius: 11px;
    background-color: #eee;
    transition-property: height, margin-bottom;
    transition-duration: 200ms;
  }
</style>

# 通用类型

# GeneralCallbackResult

名称

类型

必备

默认值

兼容性

描述

errMsg

string

是

错误信息

# 相册选择的2种方式

App平台的相册选择，有custom自定义方式和system系统方式。这2种方式有不少区别：

custom方式

app读取相册文件，所以app需要申请相册/本地文件访问权限。而google play目前仅对合理需要相册权限的应用才开放相册权限。如无法向google证明获取相册权限的合理性，则需要使用system方式。google play 政策详见：google play 照片和视频权限，使用custom方式在上架google play时需要提交一份声明以获得试用的资格，谷歌允许延长声明的提交时间到2025年1月22日。uni-app x的开发者可升级HBuilderX 4.41后使用system方式，而uni-app的开发者遇到此问题可以使用插件uni-chooseSystemMedia。
支持“原图”选项。
使用非原图，即压缩图片时，会在应用沙盒目录的cache目录产生临时文件（压缩后的图片），位置详见
在4.41以前，Android无论如何都会在应用沙盒目录的cache目录产生临时文件。从4.41起，chooseImage支持了contentURI，选择照片时如果不压缩图片，会返回contentURI，不再向cache目录写临时文件了。

system方式

使用系统选择器时，好处是不需要申请额外权限，它的模式类似于web浏览器中的input type=file，应用其实不具有本机文件访问能力，用户通过系统选择器把图片传给应用。
system方式无需特殊向google申明选择权限的必要性，即可正常上架google play。但注意同时需要在manifest.json中将<uses-permission android:name="android.permission.READ_MEDIA_IMAGES" />和<uses-permission android:name="android.permission.READ_MEDIA_VIDEO" />权限移除。配置方式参考移除Android权限。
界面ui无法自定义，比如想加一个“原图”选项，加不上去
界面ui的主题和国际化，跟随手机rom，而不是跟随app（假使App和Rom不一致）
因为不涉及压缩，所以也没有临时文件，不会在cache目录下生成临时文件。

# Tips

本API会自动申请摄像头、相册等相关权限，如需手动获取app是否拥有摄像头和相册权限，参考 uni.getAppAuthorizeSetting
app端拍照和部分情况下的相册选择会在应用沙盒目录的cache目录产生临时文件，位置详见。app端如需主动删除临时文件，使用uni.getFileSystemManager。
从HBuilderX4.41版起，uni.chooseImage在sourceType为['album']、albumMode为system、sizeType为['original']并且未设置crop时，支持返回Uri地址。
albumMode的system属性打开的是系统的图片选择器；custom属性打开的是uni-app x框架提供的图片选择器。
系统图片选择器的sizeType仅支持设置['original']或['compressed']。在Android 11及以上的系统中，设置system调用的是系统的照片选择器，低于android 11的系统中会调用系统的文件选择器。