uni-app
uni-app x
uniCloud
HBuilder
uni 小程序 sdk
uni-app x
uni-app
uni-app x
uniCloud
HBuilder
uni 小程序 sdk
简体中文
API
uni.chooseImage(options)
chooseImage 兼容性
参数
ChooseImageSuccess 的属性值
IMediaError 的属性值
参见
示例
通用类型
GeneralCallbackResult
Tips

# uni.chooseImage(options)

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

# chooseImage 兼容性

Web Android iOS
4.0 3.9 4.11

# 参数

名称 类型 必填 默认值 兼容性 描述
options ChooseImageOptions 是 - - -
名称 类型 必备 默认值 兼容性 描述
pageOrientation string 否 -
屏幕方向。默认为page.json中的pageOrientation。
合法值 兼容性 描述
auto - 自动
portrait - 竖屏显示
landscape - 横屏显示
albumMode string 否 "custom"
图片选择模式
合法值 兼容性 描述
custom - 自定义媒体选择器
system - 系统媒体选择器
count number 否 9 - 最多可以选择的图片张数，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

扫码体验（手机浏览器跳转到App直达页）

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 是 - - 错误信息

# Tips

  • 本API会自动申请摄像头和相册权限，如需手动获取app是否拥有摄像头和相册权限，参考 uni.getAppAuthorizeSetting
  • app端拍照和相册选择会在应用沙盒目录的cache目录产生临时文件，位置详见。
  • app端如需主动删除临时文件，使用uni.getFileSystemManager。
  • albumMode的system属性打开的是系统的图片选择器；custom属性打开的是uni-app x提供的图片选择器。
  • 当设置albumMode为system时，可以正常上架google play。同时需要在manifest.json中将<uses-permission android:name="android.permission.READ_MEDIA_IMAGES" />和<uses-permission android:name="android.permission.READ_MEDIA_VIDEO" />权限移除。配置方式参考移除Android权限.
  • 系统图片选择器的sizeType仅支持设置['original']或['compressed']。在Android 11及以上的系统中，设置system调用的是系统的照片选择器，低于android 11的系统中会调用系统的文件选择器。
  • 由于受google play 照片和视频权限政策的影响，使用uni.chooseImage在上架google play时需要提交一份声明以获得试用的资格，谷歌允许延长声明的提交时间到2025年1月22日。遇到此问题可以使用插件uni-chooseSystemMedia。
本页导读
uni.chooseImage(options)
chooseImage 兼容性
参数
ChooseImageSuccess 的属性值
IMediaError 的属性值
参见
示例
通用类型
GeneralCallbackResult
Tips