图片需要上传?推荐uni-cdn,帮你节省至少30%的 CDN 费用!详情

# uni.chooseImage(OBJECT)

Choose an image from your local photo album or take a photo with your camera.

If the App side needs a richer camera camera API (such as directly calling the front camera), refer to plus.camera

_WeChat MiniApp starts from the basic library 2.21.0, wx.chooseImage stop maintenance, Please use [uni.chooseMedia]( https://uniapp.dcloud.net.cn/api/media/video.html#choosemedia ) instead. _

OBJECT parameter description

Parameter Name Type Required Description Platform Difference Description
count Number No The maximum number of pictures that can be selected, the default is 9 See the description below
sizeType Array<String> No original image, compressed image, both are available by default App, WeChat MiniApp, Alipay MiniApp, Baidu MiniApp
extension Array<String> No Filter according to the file extension, and each item cannot be an empty string. No filtering by default. H5(HBuilder X2.9.9+)
sourceType Array<String> No album selects pictures from the album, camera uses the camera, both are available by default. If you want to directly open the camera or directly select the album, please use only one option
crop Object No Image cropping parameter, sizeType will be invalid after setting App 3.1.19+
success Function Yes If successful, return the local file path list of the image tempFilePaths
fail Function No Callback function for interface call failure MiniApp, App
complete Function No The callback function of the end of the interface call (it will be executed when the call succeeds or fails)

crop parameter description

Parameter Name Type Required Description Platform Difference Description
quality Number No The value range is 1-100, the smaller the value, the lower the quality (only valid for jpg format). The default value is 80.
width Number Yes the width of the clipping, in px, used to calculate the cropping aspect ratio.
height Number Yes the height of the clipping, in px, used to calculate the clipping aspect ratio.
resize Boolean No Whether to use width and height as cropping to save the real pixel value of the picture. The default value is true. Note: When set to false, the pixel value of the picture will be displayed on the crop editing interface, and when set to true, it will not be displayed

Tips

  • The performance of the count value on the H5 platform is based on the browser's own specification. Judging from the results of the current test, only single-choice/multiple-choice can be limited, and the number cannot be limited. Also, few actual mobile browsers support multiple selections.
  • The value of sourceType on the H5 platform varies depending on the browser. Generally, the use of albums cannot be restricted, and some browsers cannot restrict the use of cameras.
  • You can use the user authorization API to determine whether the user has granted the application permission to access the photo album or camera [https://uniapp.dcloud.io/api/other/authorize](https://uniapp.dcloud.io/api/other /authorize)
  • If you need to select non-media files on the App side, you can search [file selection](https://ext.dcloud.net.cn/search?q=%E6%96%87%E4%BB%B6%E9 in the plug-in market %80%89%E6%8B%A9), where Native.js can be used on the Android side without native plug-ins, while native plug-ins are required on the iOS side.
  • 选择照片大多为了上传,uni ui封装了更完善的uni-file-picker组件,文件选择、上传到uniCloud的免费存储和cdn中,一站式集成。强烈推荐使用。
  • App上有时会遇到图片旋转90度问题,插件市场有解决方案:图片旋转
  • 微信小程序在2023年10月17日之后,使用API需要配置隐私协议
  • 在部分低端机如红米上拍照闪退,拍照调用的是系统相机,当系统内存不足,rom为了给相机activity分配内存而把app的主activity回收了。遇到此问题建议使用nvue页面并内嵌的自定义相机的原生或uts插件。相关分析报告详见

注:文件的临时路径,在应用本次启动期间可以正常使用,如需持久保存,需在主动调用 uni.saveFile,在应用下次启动时才能访问得到。

success return parameter description

Parameter Type Description
tempFilePaths Array<String> List of local file paths of images
tempFiles Array<Object>, Array<File> The local file list of the picture, each item is a File object

File object structure is as follows

Parameter Type Description
path String local file path
size Number Local file size, unit: B
name String The file name including the extension, only supported by H5
type String file type, only supported by H5

example

uni.chooseImage({
	count: 6, //默认9
	sizeType: ['original', 'compressed'], //可以指定是原图还是压缩图,默认二者都有
	sourceType: ['album'], //从相册选择
	success: function (res) {
		console.log(JSON.stringify(res.tempFilePaths));
	}
});

# uni.previewImage(OBJECT)

preview picture.

OBJECT parameter description

Parameter Name Type Required Description Platform Difference Description
current String/Number 详见下方说明 详见下方说明
showmenu Boolean 是否显示长按菜单,默认值为 true 微信小程序2.13.0
urls Array<String> Yes A list of image links to be previewed
indicator String No Image indicator style, possible values: "default" - dot indicator at the bottom; "number" - number indicator at the top; "none" - no indicator. App
loop Boolean No Whether the preview can be looped, the default value is false App
longPressActions Object No Long press the picture to display the action menu, if not filled, the default is Save Album App 1.9.5+
success Function No Callback function for successful interface call
fail Function No Callback function for interface call failure
complete Function No The callback function of the end of the interface call (it will be executed when the call succeeds or fails)

current parameter description

1.9.5+ supports uploading image index value in urls

current is the link/index value of the currently displayed image, if it is left blank or the filled value is invalid, it will be the first one of urls. App platform is between 1.9.5 and 1.9.8, current is required. If you do not fill in, an error will be reported

Note, when there are duplicate image links in urls:

  • 传链接,预览结果始终显示该链接在 urls 中第一次出现的位置。
  • 传索引值,在微信/百度/抖音小程序平台,会过滤掉传入的 urls 中该索引值之前与其对应图片链接重复的值。其它平台会保留原始的 urls 不会做去重处理。

for example:

A set of images [A, B1, C, B2, D], where the image links of B1 and B2 are the same.

  • 传 B2 的链接,预览的结果是 B1,前一张是 A,下一张是 C。
  • 传 B2 的索引值 3,预览的结果是 B2,前一张是 C,下一张是 D。此时在微信/百度/抖音小程序平台,最终传入的 urls 是 [A, C, B2, D],过滤掉了与 B2 重复的 B1。

longPressActions parameter description

Parameter Type Required Description
itemList Array<String> Yes Array of text for the button
itemColor String No The text color of the button, in string format, the default is "#000000"
success Function No Callback function for successful interface call, see return parameter description for details
fail Function No Callback function for interface call failure
complete Function No The callback function for the end of the interface call (it will be executed when the call succeeds or fails)

success return parameter description

Parameter Type Description
index Number The index value when the user presses the picture for a long time
tapIndex Number The index value of the user tapped button list

example

// Select 6 pictures from the album
uni.chooseImage({
	count: 6,
	sizeType: ['original', 'compressed'],
	sourceType: ['album'],
	success: function(res) {
		// preview picture
		uni.previewImage({
			urls: res.tempFilePaths,
			longPressActions: {
				itemList: ['发送给朋友', '保存图片', '收藏'],
				success: function(data) {
					console.log('选中了第' + (data.tapIndex + 1) + '个按钮,第' + (data.index + 1) + '张图片');
				},
				fail: function(err) {
					console.log(err.errMsg);
				}
			}
		});
	}
	});

TIPS

  • On the non-H5 side, previewImage is implemented natively, and the interface customization flexibility is low.
  • The plug-in market has a front-end implementation of previewImage, whose performance is lower than that of the native implementation, but the interface can be defined at will; the plug-in market also has a native previewImage plug-in suitable for the App side, which provides more functions.

# uni.closePreviewImage(OBJECT)

Close the preview image.

App H5 微信小程序 支付宝小程序 百度小程序 抖音小程序 飞书小程序 QQ小程序 快手小程序 京东小程序
(3.2.15+) (3.2.15+) x x x x x x x x

OBJECT parameter description

Parameter Name Type Required Description
success Function No Callback function for successful interface call
fail Function No Callback function for interface call failure
complete Function No The callback function for the end of the interface call (it will be executed when the call succeeds or fails)

# uni.getImageInfo(OBJECT)

Get image information.

To obtain network picture information under the MiniApp, you need to configure the download domain name whitelist first to take effect.

Platform Difference Description

App H5 微信小程序 支付宝小程序 百度小程序 抖音小程序、飞书小程序 QQ小程序 快手小程序 京东小程序

OBJECT parameter description

Parameter Name Type Required Description
src String Yes the path of the image, which can be a relative path, a temporary file path, a storage file path, or a network image path
success Function No Callback function for successful interface call
fail Function No Callback function for interface call failure
complete Function No The callback function for the end of the interface call (it will be executed when the call succeeds or fails)

success return parameter description

Parameter Name Type Description Platform Difference Description
width Number image width, unit px
height Number image height, unit px
path String Returns the local path of the image
orientation String Returns the orientation of the image, see the table below for valid values App, MiniApp, Jingdong MiniApp
type String The format of the returned image App, MiniApp, Jingdong MiniApp

orientation parameter description

enum value description
up default
down 180 degree rotation
left rotate 90 degrees counterclockwise
right rotate 90 degrees clockwise
up-mirrored Same as up, but flipped horizontally
down-mirrored same as down, but flipped horizontally
left-mirrored same as left, but flipped vertically
right-mirrored Same as right, but flipped vertically

example

uni.chooseImage({
	count: 1,
	sourceType: ['album'],
	success: function (res) {
		uni.getImageInfo({
			src: res.tempFilePaths[0],
			success: function (image) {
				console.log(image.width);
				console.log(image.height);
			}
		});
	}
});

# uni.saveImageToPhotosAlbum(OBJECT)

Save the picture to the system album.

Platform Difference Description

App H5 微信小程序 支付宝小程序 百度小程序 抖音小程序、飞书小程序 QQ小程序 快手小程序 京东小程序
x

OBJECT parameter description

Parameter Name Type Required Description
filePath String Yes The image file path, which can be a temporary file path or a permanent file path, does not support the network image path
success Function No Callback function for successful interface call
fail Function No Callback function for interface call failure
complete Function No The callback function for the end of the interface call (it will be executed when the call succeeds or fails)

success return parameter description

parameter name type description
path String The path of the image saved to the album, only supported by App 3.0.5+
errMsg String call result

Notice

  • You can use the user authorization API to determine whether the user has granted the app the access to the photo album https://uniapp.dcloud.io/api/other/authorize
  • H5没有API可触发保存到相册行为,下载图片时浏览器会询问图片存放地址。
  • 微信小程序在2023年10月17日之后,使用API需要配置隐私协议

Example code:

uni.chooseImage({
	count: 1,
	sourceType: ['camera'],
	success: function (res) {
		uni.saveImageToPhotosAlbum({
			filePath: res.tempFilePaths[0],
			success: function () {
				console.log('save success');
			}
		});
	}
});

# uni.compressImage(OBJECT)

Compressed image interface, optional compression quality

Platform Difference Description

App H5 微信小程序 支付宝小程序 百度小程序 抖音小程序、飞书小程序 QQ小程序 快手小程序 京东小程序
x √(base library version>=3.110.3)

OBJECT parameter description

Property Type Default Required Description Platform Difference Description
src String Yes Image path, image path, can be relative path, temporary file path, storage file path
quality Number 80 No Compression quality, ranging from 0 to 100, the smaller the value, the lower the quality and the higher the compression rate (only valid for jpg)
width String auto No Scale the width of the picture, support pixel value (such as "100px"), percentage (such as "50%"), automatic calculation (such as "auto", that is, zoom according to the width and the width of the source image Scale calculation, if width is not set, the source image width will be used) App 3.0.0+
height String auto 缩放图片的高度,支持像素值(如"100px")、百分比(如"50%")、自动计算(如"auto",即根据height与源图高的缩放比例计算,若未设置height则使用源图高度) App 3.0.0+
compressedWidth Number - 压缩后图片的宽度,单位为px,若不填写则默认以 compressedHeight 为准等比缩放 微信小程序2.26.0 +
compressedHeight Number - 压缩后图片的高度,单位为px,若不填写则默认以 compressedWidth 为准等比缩放 微信小程序2.26.0 +
rotate Number 0 No Rotation degree, range 0~360 App 3.0.0+
success Function No Callback function for successful interface call
fail Function No Callback function for interface call failure
complete Function No The callback function for the end of the interface call (it will be executed when the call succeeds or fails)

success return parameter description

Property Type Description
tempFilePath String Temporary file path of the compressed image

Example code:

uni.compressImage({
  src: '/static/logo.jpg',
  quality: 80,
  success: res => {
    console.log(res.tempFilePath)
  }
})