uni-app 媒體之圖片的使用

uni.chooseImage(OBJECT)

從本地相冊選擇圖片或使用相機拍照。

App端如需要更豐富的相機拍照API（如直接調用前置攝像頭），參考plus.camera

OBJECT 參數說明

參數名	類型	必填	說明	平台差異說明
count	Number	否	最多可以選擇的圖片張數，默認9	見下方說明
sizeType	Array	否	original 原圖，compressed 壓縮圖，默認二者都有	App、微信小程序、支付寶小程序、百度小程序
extension	Array	否	根據文件拓展名過濾，每一項都不能是空字符串。默認不過濾。	H5(HBuilder X2.9.9+)
sourceType	Array	否	album 從相冊選圖，camera 使用相機，默認二者都有。如需直接開相機或直接選相冊，請只使用一個選項
success	Function	是	成功則返回圖片的本地文件路徑列表 tempFilePaths
fail	Function	否	接口調用失敗的回調函數	小程序、App
complete	Function	否	接口調用結束的回調函數（調用成功、失敗都會執行）

Tips

• count 值在 H5 平台的表現，基於瀏覽器本身的規范。目前測試的結果來看，只能限制單選/多選，並不能限制數量。並且，在實際的手機瀏覽器很少有能夠支持多選的。
• sourceType 在H5端對應input的capture屬性，設置為['album']無效，依然可以使用相機。
• 可以通過用戶授權API來判斷用戶是否給應用授予相冊或攝像頭的訪問權限https://uniapp.dcloud.io/api/other/authorize
• App端如需選擇非媒體文件，可在插件市場搜索文件選擇，其中Android端可以使用Native.js，無需原生插件，而iOS端需要原生插件。
• 選擇照片大多為了上傳，uni ui封裝了更完善的uni-file-picker組件，文件選擇、上傳到uniCloud的免費存儲和cdn中，一站式集成。強烈推薦使用。

注：文件的臨時路徑，在應用本次啟動期間可以正常使用，如需持久保存，需在主動調用 uni.saveFile，在應用下次啟動時才能訪問得到。

success 返回參數說明

參數	類型	說明
tempFilePaths	Array	圖片的本地文件路徑列表
tempFiles	Array	圖片的本地文件列表，每一項是一個 File 對象

File 對象結構如下

參數	類型	說明
path	String	本地文件路徑
size	Number	本地文件大小，單位：B
name	String	包含擴展名的文件名稱，僅H5支持
type	String	文件類型，僅H5支持

示例

uni.chooseImage({
    count: 6, //默認9
    sizeType: ['original', 'compressed'], //可以指定是原圖還是壓縮圖，默認二者都有
    sourceType: ['album'], //從相冊選擇
    success: function (res) {
        console.log(JSON.stringify(res.tempFilePaths));
    }
});

uni.previewImage(OBJECT)

預覽圖片。

OBJECT 參數說明

參數名	類型	必填	說明	平台差異說明
current	String/Number	詳見下方說明	詳見下方說明
urls	Array	是	需要預覽的圖片鏈接列表
indicator	String	否	圖片指示器樣式，可取值："default" - 底部圓點指示器； "number" - 頂部數字指示器； "none" - 不顯示指示器。	App
loop	Boolean	否	是否可循環預覽，默認值為 false	App
longPressActions	Object	否	長按圖片顯示操作菜單，如不填默認為保存相冊	App 1.9.5+
success	Function	否	接口調用成功的回調函數
fail	Function	否	接口調用失敗的回調函數
complete	Function	否	接口調用結束的回調函數（調用成功、失敗都會執行）

current 參數說明

1.9.5+ 支持傳圖片在 urls 中的索引值

current 為當前顯示圖片的鏈接/索引值，不填或填寫的值無效則為 urls 的第一張。App平台在 1.9.5至1.9.8之間，current為必填。不填會報錯

注意，當 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	是	按鈕的文字數組
itemColor	String	否	按鈕的文字顏色，字符串格式，默認為"#000000"
success	Function	否	接口調用成功的回調函數，詳見返回參數說明
fail	Function	否	接口調用失敗的回調函數
complete	Function	否	接口調用結束的回調函數（調用成功、失敗都會執行）

success 返回參數說明

參數	類型	說明
index	Number	用戶長按圖片的索引值
tapIndex	Number	用戶點擊按鈕列表的索引值

示例

// 從相冊選擇6張圖
uni.chooseImage({
    count: 6,
    sizeType: ['original', 'compressed'],
    sourceType: ['album'],
    success: function(res) {
        // 預覽圖片
        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

• 在非H5端，previewImage是原生實現的，界面自定義靈活度較低。
• 插件市場有前端實現的previewImage，性能低於原生實現，但界面可隨意定義；插件市場也有適於App端的previewImage原生插件，提供了更多功能。

uni.getImageInfo(OBJECT)

獲取圖片信息。

小程序下獲取網絡圖片信息需先配置download域名白名單才能生效。

平台差異說明

App	H5	微信小程序	支付寶小程序	百度小程序	字節跳動小程序	QQ小程序
√	√	√	√	√	√	√

OBJECT 參數說明

參數名	類型	必填	說明
src	String	是	圖片的路徑，可以是相對路徑，臨時文件路徑，存儲文件路徑，網絡圖片路徑
success	Function	否	接口調用成功的回調函數
fail	Function	否	接口調用失敗的回調函數
complete	Function	否	接口調用結束的回調函數（調用成功、失敗都會執行）

success 返回參數說明

參數名	類型	說明	平台差異說明
width	Number	圖片寬度，單位px
height	Number	圖片高度，單位px
path	String	返回圖片的本地路徑
orientation	String	返回圖片的方向，有效值見下表	App、小程序
type	String	返回圖片的格式	App、小程序

orientation 參數說明

枚舉值	說明
up	默認
down	180度旋轉
left	逆時針旋轉90度
right	順時針旋轉90度
up-mirrored	同up，但水平翻轉
down-mirrored	同down，但水平翻轉
left-mirrored	同left，但垂直翻轉
right-mirrored	同right，但垂直翻轉

示例

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)

保存圖片到系統相冊。

平台差異說明

App	H5	微信小程序	支付寶小程序	百度小程序	字節跳動小程序	QQ小程序
√	x	√	√	√	√	√

OBJECT 參數說明

參數名	類型	必填	說明
filePath	String	是	圖片文件路徑，可以是臨時文件路徑也可以是永久文件路徑，不支持網絡圖片路徑
success	Function	否	接口調用成功的回調函數
fail	Function	否	接口調用失敗的回調函數
complete	Function	否	接口調用結束的回調函數（調用成功、失敗都會執行）

success 返回參數說明

參數名	類型	說明
path	String	保存到相冊的圖片路徑，僅 App 3.0.5+ 支持
errMsg	String	調用結果

注意

• 可以通過用戶授權API來判斷用戶是否給應用授予相冊的訪問權限https://uniapp.dcloud.io/api/other/authorize
• H5沒有API可觸發保存到相冊行為，下載圖片時瀏覽器會詢問圖片存放地址。

示例代碼：

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

uni.compressImage(OBJECT)

壓縮圖片接口，可選壓縮質量

平台差異說明

App	H5	微信小程序	支付寶小程序	百度小程序	字節跳動小程序	QQ小程序
√	x	√	√	√(基礎庫版本>=3.110.3)	√	√

OBJECT 參數說明

屬性	類型	默認值	必填	說明	平台差異說明
src	String		是	圖片路徑，圖片的路徑，可以是相對路徑、臨時文件路徑、存儲文件路徑
quality	Number	80	否	壓縮質量，范圍0～100，數值越小，質量越低，壓縮率越高（僅對jpg有效）
width	String	auto	否	縮放圖片的寬度，支持像素值（如"100px"）、百分比（如"50%"）、自動計算（如"auto"，即根據height與源圖高的縮放比例計算，若未設置height則使用源圖高度）	App 3.0.0+
height	String	auto	否	縮放圖片的高度，支持像素值（如"100px"）、百分比（如"50%"）、自動計算（如"auto"，即根據height與源圖高的縮放比例計算，若未設置height則使用源圖高度）	App 3.0.0+
success	Function		否	接口調用成功的回調函數
fail	Function		否	接口調用失敗的回調函數
complete	Function		否	接口調用結束的回調函數（調用成功、失敗都會執行）

success 返回參數說明

屬性	類型	說明
tempFilePath	String	壓縮后圖片的臨時文件路徑

示例代碼：

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

例：選擇本地的圖片並預覽

<template>
	<view>
		<button type="primary" @click="chooseImg">打開圖片</button>
		<image v-for="item in imgArr" :src="item" @click="previewImg(item)"></image>
	</view>
</template>

<script>
	export default {
		data() {
			return {
				imgArr: []
			}
		},
		methods: {
			chooseImg() {
				//選擇圖片
				uni.chooseImage({
					count: 5,
					success: res => {
						this.imgArr = res.tempFilePaths
					}
				})
			},

			previewImg(current) {
				//預覽圖片
				uni.previewImage({
					current,
					urls: this.imgArr,
					loop: true,
					indicator: 'default'
				})
			}
		},

	}
</script>
<style>
</style>

效果