uni.chooseImage(options)

展示全部

# uni.chooseImage(options) GitCode GitHub

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

# chooseImage 兼容性

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

# 参数

名称

类型

必填

默认值

兼容性

描述

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

否

取值范围为1-100，数值越小，质量越低（仅对jpg格式有效）。默认值为80。

resize

boolean

否

是否将width和height作为裁剪保存图片真实的像素值。默认值为true。注：设置为false时在裁剪编辑界面显示图片的像素值，设置为true时不显示。

success

(callback: ChooseImageSuccess) => void

否

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

fail

(callback: ChooseImageFail) => 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支持

# ChooseImageFail 的属性值

名称

类型

必备

默认值

兼容性

描述

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 alpha分支，与最新HBuilderX Alpha版同步。与最新正式版同步的master分支示例另见

示例

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

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

        <view class="uni-list-cell cell-pd">
          <text class="uni-list-cell-left uni-label">
            数量限制
          </text>
          <view class="uni-list-cell-right">
            <input class="click-t" :value="count" type="number" :maxlength="1" @blur="chooseImageCount" />
          </view>
        </view>
        <!-- #ifdef APP-ANDROID || APP-IOS -->
        <view class="uni-list-cell cell-pd">
          <text class="uni-list-cell-left uni-label">
            屏幕方向
          </text>
          <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">
          <text class="uni-list-cell-left uni-label">
            相册模式
          </text>
          <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">
          <text class="uni-list-cell-left uni-label">
            图像裁剪
          </text>
          <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}}/{{count}}</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>
  <!-- #ifdef APP -->
  </scroll-view>
  <!-- #endif -->
</template>

<script>
  var sourceTypeArray = [
    ['camera'],
    ['album'],
    ['camera', 'album']
  ]
  var sizeTypeArray = [
    ['compressed'],
    ['original'],
    ['compressed', 'original']
  ]
  var orientationTypeArray = [
    'portrait',
    'landscape',
    'auto'
  ]
  var albumModeTypeArray = [
    "custom",
    "system"
  ]
  export default {
    data() {
      return {
        title: 'chooseImage',
        imageList: [] as Array<string>,
        sourceTypeIndex: 2,
        sourceType: ['拍照', '相册', '拍照或相册'],
        sizeTypeIndex: 2,
        sizeType: ['压缩', '原图', '压缩或原图'],
        orientationTypeIndex: 0,
        orientationType: ['竖屏', '横屏', '自动'],
        albumModeTypeIndex:0,
        albumModeType:["自定义相册","系统相册"],
        count: 9,
        isCrop: false,
        cropPercent: 80,
        cropWidth: 100,
        cropHeight: 100,
        cropResize: false
      }
    },
    onHide() {
      console.log("Page Hide");
    },
    onUnload() {
      this.imageList = [];
      this.sourceTypeIndex = 2
      this.sourceType = ['拍照', '相册', '拍照或相册']
      this.sizeTypeIndex = 2
      this.sizeType = ['压缩', '原图', '压缩或原图']
      this.orientationTypeIndex = 0
      this.orientationType = ['竖屏', '横屏', '自动']
    },
    methods: {
      cropHeightConfim(e : InputConfirmEvent) {
        let value = parseInt(e.detail.value)
        if (value > 0) {
          this.cropHeight = value
        } else {
          uni.showToast({
            position: "bottom",
            title: "裁剪高度需要大于0"
          })
        }
      },
      cropWidthConfim(e : InputConfirmEvent) {
        let value = parseInt(e.detail.value)
        if (value > 0) {
          this.cropWidth = value
        } else {
          uni.showToast({
            position: "bottom",
            title: "裁剪宽度需要大于0"
          })
        }
      },
      cropPercentConfim(e : InputConfirmEvent) {
        let value = parseInt(e.detail.value)
        if (value > 0 && value <= 100) {
          this.cropPercent = value
        } else {
          uni.showToast({
            position: "bottom",
            title: "请输入0~100之间的值"
          })
        }
      },
      albumModeChange(){
        uni.showActionSheet({
          itemList: this.albumModeType,
          success: (e) => {
            this.albumModeTypeIndex = e.tapIndex
          }
        })
      },
      cropResizeChange(e : UniSwitchChangeEvent) {
        this.cropResize = e.detail.value
      },
      switchCrop(e : UniSwitchChangeEvent) {
        this.isCrop = e.detail.value
      },
      removeImage(index : number) {
        this.imageList.splice(index, 1)
      },
      chooseImageSource() {
        uni.showActionSheet({
          itemList: ['拍照', '相册', '拍照或相册'],
          success: (e) => {
            this.sourceTypeIndex = e.tapIndex
          }
        })
      },
      chooseImageType() {
        uni.showActionSheet({
          itemList: ['压缩', '原图', '压缩或原图'],
          success: (e) => {
            this.sizeTypeIndex = e.tapIndex
          }
        })
      },
      chooseOrientationType(){
        uni.showActionSheet({
          itemList: ['竖屏', '横屏', '自动'],
          success: (e) => {
            this.orientationTypeIndex = e.tapIndex
          }
        })
      },
      chooseImageCount(event : InputBlurEvent) {
        let count = parseInt(event.detail.value)
        if (count < 0) {
          uni.showToast({
            position: "bottom",
            title: "图片数量应该大于0"
          })
          return
        }
        this.count = count
      },
      chooseImage: function () {
        if (this.imageList.length >= this.count) {
          uni.showToast({
            position: "bottom",
            title: `已经有 ${this.count} 张图片了，请删除部分图片之后重新选择`
          })
          return
        }
        uni.chooseImage({
          sourceType: sourceTypeArray[this.sourceTypeIndex],
          sizeType: sizeTypeArray[this.sizeTypeIndex],
          crop: this.isCrop ? { "quality": this.cropPercent, "width": this.cropWidth, "height": this.cropHeight, "resize": this.cropResize } as ChooseImageCropOptions : null,
          count: this.count - this.imageList.length,
          // #ifdef APP
          pageOrientation: orientationTypeArray[this.orientationTypeIndex],
          // #endif
          // #ifdef APP-ANDROID
          albumMode: albumModeTypeArray[this.albumModeTypeIndex],
          // #endif
          success: (res) => {
            this.imageList = this.imageList.concat(res.tempFilePaths);
            console.log("this.imageList: ",this.imageList)
          },
          fail: (err) => {
            console.log("err: ", JSON.stringify(err));
            uni.showToast({
              title:"choose image error.code:" + err.errCode+";message:"+err.errMsg,
              position:"bottom"
            })
          }
        })
      },
      previewImage: function (index : number) {
        uni.previewImage({
          current: index,
          urls: this.imageList
        })
      }
    }
  }
</script>

<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无法自定义，比如Android、iOS上无法添加“原图”选项。鸿蒙上系统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的系统中会调用系统的文件选择器。