uni-app 網絡請求

uni.request(OBJECT)

https://uniapp.dcloud.io/api/request/request?id=request

發起網絡請求。

在各個小程序平台運行時，網絡相關的 API 在使用前需要配置域名白名單。

OBJECT 參數說明

參數名	類型	必填	默認值	說明	平台差異說明
url	String	是		開發者服務器接口地址
data	Object/String/ArrayBuffer	否		請求的參數	App（自定義組件編譯模式）不支持ArrayBuffer類型
header	Object	否		設置請求的 header，header 中不能設置 Referer。	App、H5端會自動帶上cookie，且H5端不可手動修改
method	String	否	GET	有效值詳見下方說明
timeout	Number	否	60000	超時時間，單位 ms	H5(HBuilderX 2.9.9+)、APP(HBuilderX 2.9.9+)、微信小程序（2.10.0）、支付寶小程序
dataType	String	否	json	如果設為 json，會嘗試對返回的數據做一次 JSON.parse
responseType	String	否	text	設置響應的數據類型。合法值：text、arraybuffer	App和支付寶小程序不支持
sslVerify	Boolean	否	true	驗證 ssl 證書	僅App安卓端支持（HBuilderX 2.3.3+）
withCredentials	Boolean	否	false	跨域請求時是否攜帶憑證（cookies）	僅H5支持（HBuilderX 2.6.15+）
firstIpv4	Boolean	否	false	DNS解析時優先使用ipv4	僅 App-Android 支持 (HBuilderX 2.8.0+)
success	Function	否		收到開發者服務器成功返回的回調函數
fail	Function	否		接口調用失敗的回調函數
complete	Function	否		接口調用結束的回調函數（調用成功、失敗都會執行）

method 有效值

必須大寫，有效值在不同平台差異說明不同。

method	App	H5	微信小程序	支付寶小程序	百度小程序	字節跳動小程序
GET	√	√	√	√	√	√
POST	√	√	√	√	√	√
PUT	√	√	√	x	√	√
DELETE	√	√	√	x	√	x
CONNECT	x	√	√	x	x	x
HEAD	x	√	√	x	√	x
OPTIONS	√	√	√	x	√	x
TRACE	x	√	√	x	x	x

success 返回參數說明

參數	類型	說明
data	Object/String/ArrayBuffer	開發者服務器返回的數據
statusCode	Number	開發者服務器返回的 HTTP 狀態碼
header	Object	開發者服務器返回的 HTTP Response Header
cookies	Array.<string>	開發者服務器返回的 cookies，格式為字符串數組

data 數據說明

最終發送給服務器的數據是 String 類型，如果傳入的 data 不是 String 類型，會被轉換成 String。轉換規則如下：

• 對於 GET 方法，會將數據轉換為 query string。例如 { name: 'name', age: 18 } 轉換后的結果是 name=name&age=18。
• 對於 POST 方法且 header['content-type'] 為 application/json 的數據，會進行 JSON 序列化。
• 對於 POST 方法且 header['content-type'] 為 application/x-www-form-urlencoded 的數據，會將數據轉換為 query string。

示例

uni.request({
    url: 'https://www.example.com/request', //僅為示例，並非真實接口地址。
    data: {
        text: 'uni.request'
    },
    header: {
        'custom-header': 'hello' //自定義請求頭信息
    },
    success: (res) => {
        console.log(res.data);
        this.text = 'request success';
    }
});

返回值

如果希望返回一個 requestTask 對象，需要至少傳入 success / fail / complete 參數中的一個。例如：

var requestTask = uni.request({
    url: 'https://www.example.com/request', //僅為示例，並非真實接口地址。
    complete: ()=> {}
});
requestTask.abort();

如果沒有傳入 success / fail / complete 參數，則會返回封裝后的 Promise 對象：Promise 封裝

通過 requestTask，可中斷請求任務。

requestTask 對象的方法列表

方法	參數	說明
abort		中斷請求任務
offHeadersReceived		取消監聽 HTTP Response Header 事件，僅微信小程序平台支持，文檔詳情
onHeadersReceived		監聽 HTTP Response Header 事件。會比請求完成事件更早，僅微信小程序平台支持，文檔詳情

示例

const requestTask = uni.request({
    url: 'https://www.example.com/request', //僅為示例，並非真實接口地址。
    data: {
        name: 'name',
        age: 18
    },
    success: function(res) {
        console.log(res.data);
    }
});

// 中斷請求任務
requestTask.abort();

Tips

• 請求的 header 中 content-type 默認為 application/json。
• 避免在 header 中使用中文，或者使用 encodeURIComponent 進行編碼，否則在百度小程序報錯。（來自：快狗打車前端團隊）
• 網絡請求的 超時時間 可以統一在 manifest.json 中配置 networkTimeout。
• H5 端本地調試需注意跨域問題，參考：調試跨域問題解決方案
• 注意由於百度小程序iOS客戶端，請求失敗時會進入fail回調，需要針對百度增加相應的處理以解決該問題。
• 注意小程序端不支持自動保持 cookie，服務器應避免驗證 cookie。如果服務器無法修改，也可以使用一些模擬手段，比如這樣的工具https://github.com/charleslo1/weapp-cookie 可以請求時帶上 cookie 並將響應的 cookie 保存在本地。
• H5端 cookie 受跨域限制（和平時開發網站時一樣），舊版的 uni.request 未支持 withCredentials 配置，可以直接使用 xhr 對象或者其他類庫。
• 根據 W3C 規范，H5 端無法獲取 response header 中 Set-Cookie、Set-Cookie2 這2個字段，對於跨域請求，允許獲取的 response header 字段只限於“simple response header”和“Access-Control-Expose-Headers”（詳情）
• uni-app 插件市場有flyio、axios等三方封裝的攔截器可用
• 低版本手機自身不支持 ipv6，如果服務器僅允許 ipv6，會導致老手機無法正常運行或訪問速度非常慢
• localhost、127.0.0.1等服務器地址，只能在電腦端運行，手機端連接時不能訪問。請使用標准IP並保證手機能連接電腦網絡
• debug 模式，安卓端暫時無法獲取響應頭，url中含有非法字符（如未編碼為%20的空格）時會請求失敗
• iOS App第一次安裝啟動后，會彈出是否允許聯網的詢問框，在用戶點擊同意前，調用聯網API會失敗。請注意判斷這種情況。比如官方提供的新聞模板示例（HBuilderX新建項目可選擇），會判斷如果無法聯網，則提供一個錯誤頁，提示用戶設置網絡及下拉刷新重試。
• 良好體驗的App，還會判斷當前是否處於飛行模式（參考）、是wifi還是3G（參考）
• 部分安卓設備，真機運行或debug模式下的網速，低於release模式很多。
• 使用一些比較小眾的證書機構（如：CFCA OV OCA）簽發的 ssl 證書在安卓設備請求會失敗，因為這些機構的根證書不在系統內置根證書庫，可以更換其他常見機構簽發的證書（如：Let's Encrypt），或者配置 sslVerify 為 false 關閉 ssl 證書驗證（不推薦）。
• 單次網絡請求數據量建議控制在50K以下（僅指json數據，不含圖片），過多數據應分頁獲取，以提升應用體驗。

示例：發送get請求

<template>
	<view>

		<button @click="get()">點擊發送get請求</button>
	</view>
</template>

<script>
	export default {
		methods: {
			get() {
				uni.request({
					url: "http://www.my.com/test520",
					success(res) {
						console.log(res)
					}
				})
			}
		}
	}
</script>
<style>
</style>