媒体 – 第 19 页 – 微信小程序开发指南

wx.saveMediaToPhotosAlbum(Object object)

基础库 3.17.2 开始支持，低版本需做兼容处理。

以 Promise 风格调用：支持

用户授权：需要 scope.writePhotosAlbum

微信小程序插件：支持，需要微信小程序基础库版本不低于 3.17.2

微信 Windows 版：支持

微信 Mac 版：支持

微信鸿蒙 OS 版：支持

功能描述

保存图片或视频到系统相册。支持同时保存图片或视频。其中视频支持 mp4 视频格式。

参数

Object object

属性类型默认值必填说明

filePaths Array.<String> 否图片或视频的路径数组，可以是临时文件路径或本地路径

mediaTypes Array.<String> 否指定保存的媒体类型数组，仅支持 ‘image’ 和 ‘video’

合法值	说明
image	图片
video	视频

success function 否接口调用成功的回调函数

fail function 否接口调用失败的回调函数

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

示例代码

wx.saveMediaToPhotosAlbum({
  filePaths: ['wxfile://xxx'],
  mediaTypes: ['image', 'video'],
  success (res) {
    console.log(res.errMsg)
  }
})

保存视频到系统相册

基础库 1.2.0 开始支持，低版本需做兼容处理。

以 Promise 风格调用：支持

用户授权：需要 scope.writePhotosAlbum

微信小程序插件：支持，需要微信小程序基础库版本不低于 1.9.6

微信 Windows 版：支持

微信 Mac 版：支持

微信鸿蒙 OS 版：支持

功能描述

保存视频到系统相册。支持mp4视频格式。

参数

Object object

属性	类型	必填	说明
filePath	string	是	视频文件路径，可以是临时文件路径也可以是永久文件路径 (本地路径)
success	function	否	接口调用成功的回调函数
fail	function	否	接口调用失败的回调函数
complete	function	否	接口调用结束的回调函数（调用成功、失败都会执行）

示例代码

wx.saveVideoToPhotosAlbum({
  filePath: 'wxfile://xxx',
  success (res) {
    console.log(res.errMsg)
  }
})

wx.chooseImage(Object object)

从基础库 2.21.0 开始，本接口停止维护，请使用 wx.chooseMedia 代替

以 Promise 风格调用：支持

微信小程序插件：支持，需要微信小程序基础库版本不低于 1.9.6

微信 Windows 版：支持

微信 Mac 版：支持

微信鸿蒙 OS 版：支持

功能描述

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

参数

Object object

属性类型默认值必填说明

count number 9 否最多可以选择的图片张数

sizeType Array.<string> [‘original’, ‘compressed’] 否所选的图片的尺寸

合法值	说明
original	原图
compressed	压缩图

sourceType Array.<string> [‘album’, ‘camera’] 否选择图片的来源

合法值	说明
album	从相册选图
camera	使用相机

success function 否接口调用成功的回调函数

fail function 否接口调用失败的回调函数

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

object.success 回调函数

参数

Object res

属性类型说明最低版本

tempFilePaths Array.<string> 图片的本地临时文件路径列表 (本地路径)

tempFiles Array.<Object> 图片的本地临时文件列表 1.2.0

	结构属性	类型	说明
	path	string	本地临时文件路径 (本地路径)
	size	number	本地临时文件大小，单位 B

wx.chooseImage({
  count: 1,
  sizeType: ['original', 'compressed'],
  sourceType: ['album', 'camera'],
  success (res) {
    // tempFilePath可以作为img标签的src属性显示图片
    const tempFilePaths = res.tempFilePaths
  }
})

wx.chooseMessageFile(Object object)

基础库 2.5.0 开始支持，低版本需做兼容处理。

以 Promise 风格调用：支持

微信小程序插件：不支持

微信 Windows 版：支持

微信 Mac 版：支持

微信鸿蒙 OS 版：支持

功能描述

从客户端会话选择文件。

参数

Object object

属性类型默认值必填说明最低版本

count number 是最多可以选择的文件个数，可以 0～100

type string ‘all’ 否所选的文件的类型

合法值	说明
all	从所有文件选择
video	只能选择视频文件
image	只能选择图片文件
file	可以选择除了图片和视频之外的其它的文件

extension Array.<string> 否根据文件拓展名过滤，仅 type==file 时有效。每一项都不能是空字符串。默认不过滤。 2.6.0

success function 否接口调用成功的回调函数

fail function 否接口调用失败的回调函数

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

object.success 回调函数

参数

Object res

属性类型说明

tempFiles Array.<Object> 返回选择的文件的本地临时文件对象数组

结构属性

类型

说明

path

string

本地临时文件路径 (本地路径)

size

number

本地临时文件大小，单位 B

name

string

选择的文件名称

type

string

选择的文件类型

合法值	说明
video	选择了视频文件
image	选择了图片文件
file	选择了除图片和视频的文件

time

number

选择的文件的会话发送时间，Unix时间戳，工具暂不支持此属性

wx.chooseMessageFile({
  count: 10,
  type: 'image',
  success (res) {
    // tempFilePath可以作为img标签的src属性显示图片
    const tempFilePaths = res.tempFiles
  }
})

wx.compressImage(Object object)

基础库 2.4.0 开始支持，低版本需做兼容处理。

以 Promise 风格调用：支持

微信小程序插件：支持，需要微信小程序基础库版本不低于 2.12.0

微信鸿蒙 OS 版：支持

功能描述

压缩图片接口，可选压缩质量。iOS 仅支持压缩 JPG 格式图片。

参数

Object object

属性	类型	默认值	必填	说明	最低版本
src	string		是	图片路径，图片的路径，支持本地路径、代码包路径
quality	number	80	否	压缩质量，范围0～100，数值越小，质量越低，压缩率越高（仅对jpg有效）。
compressedWidth	number		否	压缩后图片的宽度，单位为px，若不填写则默认以compressedHeight为准等比缩放。	2.26.0
compressedHeight	number		否	压缩后图片的高度，单位为px，若不填写则默认以compressedWidth为准等比缩放	2.26.0
success	function		否	接口调用成功的回调函数
fail	function		否	接口调用失败的回调函数
complete	function		否	接口调用结束的回调函数（调用成功、失败都会执行）

object.success 回调函数

参数

Object res

属性	类型	说明
tempFilePath	string	压缩后图片的临时文件路径 (本地路径)

示例代码

wx.compressImage({
  src: '', // 图片路径
  quality: 80 // 压缩质量
})

wx.cropImage(Object object)

基础库 2.26.0 开始支持，低版本需做兼容处理。

以 Promise 风格调用：不支持

微信小程序插件：不支持

微信鸿蒙 OS 版：支持

功能描述

裁剪图片接口

参数

Object object

属性

类型

默认值

必填

说明

src

string

是

图片路径，图片的路径，支持本地路径、代码包路径

cropScale

string

是

裁剪比例

合法值	说明
16:9	宽高比为16比9
9:16	宽高比为9比16
4:3	宽高比为4比3
3:4	宽高比为3比4
5:4	宽高比为5比4
4:5	宽高比为4比5
1:1	宽高比为1比1

success

function

否

接口调用成功的回调函数

fail

function

否

接口调用失败的回调函数

complete

function

否

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

object.success 回调函数

参数

Object res

属性	类型	说明
tempFilePath	string	编辑后图片的临时文件路径 (本地路径)

示例代码

wx.cropImage({
  src: '', // 图片路径
  cropScale: '16:9', // 裁剪比例
})

wx.editImage(Object object)

基础库 2.22.0 开始支持，低版本需做兼容处理。

以 Promise 风格调用：不支持

微信小程序插件：不支持

微信鸿蒙 OS 版：支持

功能描述

编辑图片接口

参数

Object object

属性	类型	必填	说明
src	string	是	图片路径，图片的路径，支持本地路径、代码包路径
success	function	否	接口调用成功的回调函数
fail	function	否	接口调用失败的回调函数
complete	function	否	接口调用结束的回调函数（调用成功、失败都会执行）

object.success 回调函数

参数

Object res

属性	类型	说明
tempFilePath	string	编辑后图片的临时文件路径 (本地路径)

示例代码

wx.editImage({
  src: '', // 图片路径
})

wx.getImageInfo(Object object)

以 Promise 风格调用：支持

微信小程序插件：支持，需要微信小程序基础库版本不低于 1.9.6

微信 Windows 版：支持

微信 Mac 版：支持

微信鸿蒙 OS 版：支持

功能描述

获取图片信息。网络图片需先配置download域名才能生效。

参数

Object object

属性	类型	必填	说明
src	string	是	图片的路径，支持网络路径、本地路径、代码包路径
success	function	否	接口调用成功的回调函数
fail	function	否	接口调用失败的回调函数
complete	function	否	接口调用结束的回调函数（调用成功、失败都会执行）

object.success 回调函数

参数

Object res

属性

类型

说明

最低版本

width

number

图片原始宽度，单位px。不考虑旋转。

height

number

图片原始高度，单位px。不考虑旋转。

path

string

图片的本地路径

orientation

string

拍照时设备方向

1.9.90

合法值	说明
up	默认方向（手机横持拍照），对应 Exif 中的 1。或无 orientation 信息。
up-mirrored	同 up，但镜像翻转，对应 Exif 中的 2
down	旋转180度，对应 Exif 中的 3
down-mirrored	同 down，但镜像翻转，对应 Exif 中的 4
left-mirrored	同 left，但镜像翻转，对应 Exif 中的 5
right	顺时针旋转90度，对应 Exif 中的 6
right-mirrored	同 right，但镜像翻转，对应 Exif 中的 7
left	逆时针旋转90度，对应 Exif 中的 8

type

string

图片格式

1.9.90

合法值	说明
unknown	未知格式
jpeg	jpeg压缩格式
png	png压缩格式
gif	gif压缩格式
tiff	tiff压缩格式

示例代码

在开发者工具中预览效果

wx.getImageInfo({
  src: 'images/a.jpg',
  success (res) {
    console.log(res.width)
    console.log(res.height)
  }
})

wx.chooseImage({
  success (res) {
    wx.getImageInfo({
      src: res.tempFilePaths[0],
      success (res) {
        console.log(res.width)
        console.log(res.height)
      }
    })
  }
})

wx.previewImage(Object object)

以 Promise 风格调用：支持

微信小程序插件：支持，需要微信小程序基础库版本不低于 1.9.6

微信 Windows 版：支持

微信 Mac 版：支持

微信鸿蒙 OS 版：支持

功能描述

在新页面中全屏预览图片。预览的过程中用户可以进行保存图片、发送给朋友等操作。

参数

Object object

属性	类型	默认值	必填	说明	最低版本
urls	Array.`<string>`		是	需要预览的图片链接列表。2.2.3 起支持云文件ID。
showmenu	boolean	true	否	是否显示长按菜单。	2.13.0
current	string	urls 的第一张	否	当前显示图片的链接
referrerPolicy	string	no-referrer	否	`origin`: 发送完整的referrer; `no-referrer`: 不发送。格式固定为 `https://servicewechat.com/{appid}/{version}/page-frame.html`，其中 {appid} 为微信小程序的 appid，{version} 为微信小程序的版本号，版本号为 0 表示为开发版、体验版以及审核版本，版本号为 devtools 表示为开发者工具，其余为正式版本；	2.13.0
success	function		否	接口调用成功的回调函数
fail	function		否	接口调用失败的回调函数
complete	function		否	接口调用结束的回调函数（调用成功、失败都会执行）

支持长按识别的码

类型	说明	最低版本
微信小程序码
微信个人码		2.18.0
企业微信个人码		2.18.0
普通群码	指仅包含微信用户的群	2.18.0
互通群码	指既有微信用户也有企业微信用户的群	2.18.0
公众号二维码		2.18.0

示例代码

wx.previewImage({
  current: '', // 当前显示图片的http链接
  urls: [] // 需要预览的图片http链接列表
})

wx.previewMedia(Object object)

基础库 2.12.0 开始支持，低版本需做兼容处理。

以 Promise 风格调用：支持

微信小程序插件：支持，需要微信小程序基础库版本不低于 2.15.0

微信鸿蒙 OS 版：支持

功能描述

预览图片和视频。

参数

Object object

属性类型默认值必填说明最低版本

sources Array.<Object> 是需要预览的资源列表

结构属性

类型

默认值

必填

说明

url

String

是

图片或视频的地址

type

String

image

否

资源的类型，默认为图片

合法值	说明
image	图片
video	视频

poster

string

否

视频的封面图片

current number 0 否当前显示的资源序号

showmenu boolean true 否是否显示长按菜单。 2.13.0

referrerPolicy string no-referrer 否 `origin`: 发送完整的referrer; `no-referrer`: 不发送。格式固定为 `https://servicewechat.com/{appid}/{version}/page-frame.html`，其中 {appid} 为微信小程序的 appid，{version} 为微信小程序的版本号，版本号为 0 表示为开发版、体验版以及审核版本，版本号为 devtools 表示为开发者工具，其余为正式版本； 2.13.0

success function 否接口调用成功的回调函数

fail function 否接口调用失败的回调函数

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

支持长按识别的码

类型	说明	最低版本
微信小程序码
微信个人码	不支持小游戏	2.18.0
企业微信个人码	不支持小游戏	2.18.0
普通群码	指仅包含微信用户的群，不支持小游戏	2.18.0
互通群码	指既有微信用户也有企业微信用户的群，不支持小游戏	2.18.0
公众号二维码	不支持小游戏	2.18.0