QinJs 官网 | QinJs 官网

qin.chooseImage(OBJECT)

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

微信小程序从基础库 2.21.0 开始， wx.chooseImage 停止维护，请使用 qin.chooseMedia 代替。

OBJECT 参数说明

参数名	类型	必填	说明	平台差异说明
count	Number	否	最多可以选择的图片张数，默认9	见下方说明
sizeType	Array<String>	否	original 原图，compressed 压缩图，默认二者都有	微信小程序、支付宝小程序
extension	Array<String>	否	根据文件拓展名过滤，每一项都不能是空字符串。默认不过滤。	H5
sourceType	Array<String>	否	album 从相册选图，camera 使用相机，默认二者都有。如需直接开相机或直接选相册，请只使用一个选项
crop	Object	否	图像裁剪参数，设置后 sizeType 失效
success	Function	是	成功则返回图片的本地文件路径列表 tempFilePaths
fail	Function	否	接口调用失败的回调函数	小程序、App
complete	Function	否	接口调用结束的回调函数（调用成功、失败都会执行）

crop 参数说明

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

注意

count 值在 H5 平台的表现，基于浏览器本身的规范。目前测试的结果来看，只能限制单选/多选，并不能限制数量。并且，在实际的手机浏览器很少有能够支持多选的。
sourceType 值在 H5 平台根据浏览器的不同而表现不同，一般不可限制仅使用相册，部分浏览器也无法限制是否使用相机。
可以通过用户授权 API 来判断用户是否给应用授予相册或摄像头的访问权限https://uniapp.dcloud.io/api/other/authorize
文件的临时路径，在应用本次启动期间可以正常使用，如需持久保存，需在主动调用 qin.saveFile，在应用下次启动时才能访问得到。

success 返回参数说明

参数	类型	说明
tempFilePaths	Array<String>	图片的本地文件路径列表
tempFiles	Array<Object>、Array<File>	图片的本地文件列表，每一项是一个 File 对象

File 对象结构如下

参数	类型	说明
path	String	本地文件路径
size	Number	本地文件大小，单位：B
name	String	包含扩展名的文件名称，仅H5支持
type	String	文件类型，仅 H5 支持

示例

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

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

qin.previewImage

预览图片。

OBJECT 参数说明

参数名	类型	必填	说明
current	String/Number	详见下方说明	详见下方说明
urls	Array<String>	是	需要预览的图片链接列表
loop	Boolean	否	是否可循环预览，默认值为 false
longPressActions	Object	否	长按图片显示操作菜单，如不填默认为保存相册
success	Function	否	接口调用成功的回调函数
fail	Function	否	接口调用失败的回调函数
complete	Function	否	接口调用结束的回调函数（调用成功、失败都会执行）

current 参数说明

1.9.5+ 支持传图片在 urls 中的索引值

current 为当前显示图片的链接/索引值，不填或填写的值无效则为 urls 的第一张。

注意，当 urls 中有重复的图片链接时：

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

举例说明：

一组图片 [A, B1, C, B2, D]，其中 B1 与 B2 的图片链接是一样的。

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

longPressActions 参数说明

参数	类型	必填	说明
itemList	Array<String>	是	按钮的文字数组
itemColor	String	否	按钮的文字颜色，字符串格式，默认为"#000000"
success	Function	否	接口调用成功的回调函数，详见返回参数说明
fail	Function	否	接口调用失败的回调函数
complete	Function	否	接口调用结束的回调函数（调用成功、失败都会执行）

success 返回参数说明

参数	类型	说明
index	Number	用户长按图片的索引值
tapIndex	Number	用户点击按钮列表的索引值

示例

// 从相册选择6张图
qin.chooseImage({
  count: 6,
  sizeType: ['original', 'compressed'],
  sourceType: ['album'],
  success: (theRes) => {
    // 预览图片
    qin.previewImage({
      urls: theRes.tempFilePaths,
      longPressActions: {
        itemList: ['发送给朋友', '保存图片', '收藏'],
        success: (theData) => {
          console.log('选中了第' + (theData.tapIndex + 1) + '个按钮,第' + (theData.index + 1) + '张图片');
        },
        fail: (theError) => {
          console.log(theError.errMsg);
        },
      },
    });
  },
});

// 从相册选择6张图
qin.chooseImage({
  count: 6,
  sizeType: ['original', 'compressed'],
  sourceType: ['album'],
  success: (theRes) => {
    // 预览图片
    qin.previewImage({
      urls: theRes.tempFilePaths,
      longPressActions: {
        itemList: ['发送给朋友', '保存图片', '收藏'],
        success: (theData) => {
          console.log('选中了第' + (theData.tapIndex + 1) + '个按钮,第' + (theData.index + 1) + '张图片');
        },
        fail: (theError) => {
          console.log(theError.errMsg);
        },
      },
    });
  },
});

注意

在非 H5 端， previewImage 是原生实现的，界面自定义灵活度较低。
插件市场有前端实现的 previewImage ，性能低于原生实现，但界面可随意定义。

qin.closePreviewImage

关闭预览图片。

H5	微信小程序	小红书小程序	抖音小程序	快手小程序
√	x	x	x	x

OBJECT 参数说明

参数名	类型	必填	说明
success	Function	否	接口调用成功的回调函数
fail	Function	否	接口调用失败的回调函数
complete	Function	否	接口调用结束的回调函数（调用成功、失败都会执行）

qin.getImageInfo

获取图片信息。

小程序下获取网络图片信息需先配置 download 域名白名单才能生效。

平台差异说明

H5	微信小程序	小红书小程序	抖音小程序	快手小程序
√	√	√	√	√

OBJECT 参数说明

参数名	类型	必填	说明
src	String	是	图片的路径，可以是相对路径，临时文件路径，存储文件路径，网络图片路径
success	Function	否	接口调用成功的回调函数
fail	Function	否	接口调用失败的回调函数
complete	Function	否	接口调用结束的回调函数（调用成功、失败都会执行）

success 返回参数说明

参数名	类型	说明	平台差异说明
width	Number	图片宽度，单位 px
height	Number	图片高度，单位 px
path	String	返回图片的本地路径
orientation	String	返回图片的方向，有效值见下表	小程序
type	String	返回图片的格式	小程序

orientation 参数说明

枚举值	说明
up	默认
down	180 度旋转
left	逆时针旋转 90 度
right	顺时针旋转 90 度
up-mirrored	同 up ，但水平翻转
down-mirrored	同 down ，但水平翻转
left-mirrored	同 left ，但垂直翻转
right-mirrored	同 right ，但垂直翻转

示例

qin.chooseImage({
  count: 1,
  sourceType: ['album'],
  success: (theRes) => {
    qin.getImageInfo({
      src: theRes.tempFilePaths[0],
      success: (theImage) => {
        console.log(theImage.width);
        console.log(theImage.height);
      },
    });
  },
});

qin.chooseImage({
  count: 1,
  sourceType: ['album'],
  success: (theRes) => {
    qin.getImageInfo({
      src: theRes.tempFilePaths[0],
      success: (theImage) => {
        console.log(theImage.width);
        console.log(theImage.height);
      },
    });
  },
});

qin.saveImageToPhotosAlbum

保存图片到系统相册。

平台差异说明

H5	微信小程序	小红书小程序	抖音小程序	快手小程序
x	√	√	√	√

OBJECT 参数说明

参数名	类型	必填	说明
filePath	String	是	图片文件路径，可以是临时文件路径也可以是永久文件路径，不支持网络图片路径
success	Function	否	接口调用成功的回调函数
fail	Function	否	接口调用失败的回调函数
complete	Function	否	接口调用结束的回调函数（调用成功、失败都会执行）

success 返回参数说明

参数名	类型	说明
errMsg	String	调用结果

注意

可以通过用户授权API来判断用户是否给应用授予相册的访问权限https://uniapp.dcloud.io/api/other/authorize
H5 没有 API 可触发保存到相册行为，下载图片时浏览器会询问图片存放地址。

示例代码：

qin.chooseImage({
  count: 1,
  sourceType: ['camera'],
  success: (theRes) => {
    qin.saveImageToPhotosAlbum({
      filePath: theRes.tempFilePaths[0],
      success: () => {
        console.log('save success');
      },
    });
  }
});

qin.chooseImage({
  count: 1,
  sourceType: ['camera'],
  success: (theRes) => {
    qin.saveImageToPhotosAlbum({
      filePath: theRes.tempFilePaths[0],
      success: () => {
        console.log('save success');
      },
    });
  }
});

qin.compressImage

压缩图片接口，可选压缩质量

平台差异说明

H5	微信小程序	小红书小程序	抖音小程序	快手小程序
x	√	√	√	√

OBJECT 参数说明

属性	类型	默认值	必填	说明	平台差异说明
src	String		是	图片路径，图片的路径，可以是相对路径、临时文件路径、存储文件路径
quality	Number	80	否	压缩质量，范围 0～100 ，数值越小，质量越低，压缩率越高（仅对 jpg 有效）
width	String	auto	否	缩放图片的宽度，支持像素值（如 "100px" ）、百分比（如 "50%" ）、自动计算（如 "auto" ，即根据 width 与源图宽的缩放比例计算，若未设置width则使用源图宽度）
height	String	auto	否	缩放图片的高度，支持像素值（如 "100px" ）、百分比（如 "50%" ）、自动计算（如"auto"，即根据 height 与源图高的缩放比例计算，若未设置 height 则使用源图高度）
compressedWidth	Number	-	否	压缩后图片的宽度，单位为 px ，若不填写则默认以 compressHeight 为准等比缩放	微信小程序 2.26.0 +
compressHeight	Number	-	否	压缩后图片的高度，单位为 px ，若不填写则默认以 compressedWidth 为准等比缩放	微信小程序 .26.0 +
rotate	Number	0	否	旋转度数，范围 0～360
success	Function		否	接口调用成功的回调函数
fail	Function		否	接口调用失败的回调函数
complete	Function		否	接口调用结束的回调函数（调用成功、失败都会执行）

success 返回参数说明

属性	类型	说明
tempFilePath	String	压缩后图片的临时文件路径

示例代码：

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

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

qin.chooseImage(OBJECT) ​

qin.previewImage ​

qin.closePreviewImage ​

qin.getImageInfo ​

qin.saveImageToPhotosAlbum ​

qin.compressImage ​

qin.chooseImage(OBJECT)

qin.previewImage

qin.closePreviewImage

qin.getImageInfo

qin.saveImageToPhotosAlbum

qin.compressImage