項目六uni-app常用API

項目六uni-app常用API

項目任務(wù)：任務(wù)1API概述任務(wù)2網(wǎng)絡(luò)類API任務(wù)3頁面和路由類API任務(wù)4數(shù)據(jù)緩存類API任務(wù)5位置類API任務(wù)6設(shè)備類API任務(wù)7界面類API任務(wù)8用戶登錄API任務(wù)9綜合案例01任務(wù)1API概述

任務(wù)1API概述

uni-app的API由兩部分組成，分別是標(biāo)準(zhǔn)ECMAScript的JSAPI和uni自身擴展的API。其中，標(biāo)準(zhǔn)ECMAScript的JSAPI是最基礎(chǔ)的JS，不包括額外的擴展對象。uni自身擴展的API是對ECMAScript的擴展，在ECMAScript的基礎(chǔ)上擴展出uni對象，uni對象內(nèi)部封裝了很多API，這些API支持Web端和非Web端（App和小程序端）平臺運行。uni-app的API通常以uni.開頭，且命名與小程序保持兼容。這些API總體上包括基礎(chǔ)API、網(wǎng)絡(luò)API、頁面路由API、數(shù)據(jù)緩存API、位置API、媒體API、設(shè)備API、文件API和界面等。uni-app的API使用非常簡單，以最常見的網(wǎng)絡(luò)請求API為例，一個基本的uni-appAPI寫法如下。

任務(wù)1API概述uni.request({

url:"/request",//非真實接口地址，僅作為模擬

success:(res)=>{

console.log(res.data);

},

fail:(err)=>{

console.log(err);

},

complete:()=>{

console.log(‘請求完成’);

},});

其中，通過url屬性設(shè)置請求URL，請求成功進入success回調(diào)函數(shù)處理，在success回調(diào)函數(shù)內(nèi)部可通過res.data獲取響應(yīng)數(shù)據(jù)。請求失敗進入fail回調(diào)函數(shù)處理，在fail回調(diào)函數(shù)內(nèi)部可通過err參數(shù)獲取失敗信息。無論請求是成功還是失敗，在請求結(jié)束后都會進入complete回調(diào)函數(shù)處理，在complete回調(diào)函數(shù)內(nèi)部可進行釋放資源等工作。如未特殊約定，所有uni-app的API接口都接受一個OBJECT作為參數(shù)。OBJECT中可以指定success，fail，complete回調(diào)來接收接口調(diào)用結(jié)果。

任務(wù)1API概述

除了上述寫法外，uni-app的部分API還支持使用Promise化寫法。Promise化寫法有Vue2和Vue3兩個版本，這里只針對Vue3版本做介紹。Vue3版本的Promise化寫法統(tǒng)一使用then和catch方法作為回調(diào)函數(shù)。調(diào)用成功進入then方法執(zhí)行，調(diào)用失敗進入catch方法執(zhí)行。//使用Promise化寫法，then和catch方法作為回調(diào)uni

.request({

url:"/request",

//非真實接口地址，僅作為模擬

})

.then((res)=>{

//此處的res參數(shù)，與上述success回調(diào)中的res參數(shù)一致

console.log(res.data);

})

.catch((err)=>{

//此處的err參數(shù)，與上述fail回調(diào)中的err參數(shù)一致

console.error(err);

});

任務(wù)1API概述

何時使用Promise化寫法，uni-app約定如下規(guī)則。

1.所有同步API方法，即方法名末尾以sync結(jié)束的。統(tǒng)一不采用Promise化寫法。例如uni.getSystemInfoSync()

2.所有API方法名以create開頭的方法如uni.createMapContext()，不采用Promise化寫法。

3.所有API方法名以manager結(jié)束的方法如uni.getBackgroundAudioManager()，不采用Promise化寫法。

4.對于異步API方法，且沒有返回對象的，使用時如果不傳入success、fail、complete等回調(diào)參數(shù)，必須使用Promise化寫法。

5.對于異步API方法，且有返回對象的，如果需要獲取返回對象，不能使用Promise化寫法。必須至少傳入success、fail、complete等回調(diào)參數(shù)中的一項才能獲取返回對象。02任務(wù)2網(wǎng)絡(luò)類API

6.2.1request網(wǎng)絡(luò)請求request網(wǎng)絡(luò)請求API用于前后端的數(shù)據(jù)交互，作用類似于Vue中的axios組件。request主要參數(shù)參數(shù)名類型是否必填默認(rèn)值說明urlString是

設(shè)置后端服務(wù)器接口地址dataObject/String/ArrayBuffer否

設(shè)置請求參數(shù)headerObject否1設(shè)置請求頭，請求頭中不能設(shè)置Referer屬性。App、Web端的請求頭會自動帶上cookie，且Web端cookie不可手動修改methodString否GET設(shè)置請求方法，有效值為GET、POST、PUT、DELETE等，有效值必須大寫timeoutNumber否60000設(shè)置超時時間，單位msdataTypeString否json設(shè)置響應(yīng)數(shù)據(jù)返回格式，如果值為json，會對響應(yīng)數(shù)據(jù)進行一次JSON.parse操作，否則不會進行JSON.parse操作responseTypeString否text設(shè)置響應(yīng)的數(shù)據(jù)類型。有效值為text、arraybuffersslVerifyBoolean否true設(shè)置是否驗證ssl證書，僅安卓App端支持withCredentialsBoolean否false設(shè)置跨域請求時是否攜帶憑證cookies，僅Web端支持successFunction否

收到開發(fā)者服務(wù)器成功返回的回調(diào)函數(shù)failFunction否

接口調(diào)用失敗的回調(diào)函數(shù)completeFunction否

接口調(diào)用結(jié)束的回調(diào)函數(shù)，調(diào)用成功、失敗都會執(zhí)行

6.2.1request網(wǎng)絡(luò)請求

在API請求時，如果是真機測試環(huán)境下，url地址必須使用HTTPS域名地址，且需配置域名白名單，否則不能正常獲取數(shù)據(jù)。配置步驟為：進入微信小程序官網(wǎng)（/）并登錄，在首頁中服務(wù)器域名一欄配置“request合法域名”。

6.2.1request網(wǎng)絡(luò)請求

如果是在微信開發(fā)者工具中，url地址可以使用使用HTTP/HTTPS域名地址，不需配置域名白名單，只需要勾選“不校驗合法域名、web-view（業(yè)務(wù)域名）、TLS版本以及HTTPS證書”選項即可。

6.2.1request網(wǎng)絡(luò)請求

requestAPI對于最終發(fā)送給服務(wù)器的請求數(shù)據(jù)data統(tǒng)一使用String類型，如果傳入的不是String類型，也會被強制轉(zhuǎn)換成String類型，具體轉(zhuǎn)換規(guī)則如下。

1.對于GET方法，會將數(shù)據(jù)轉(zhuǎn)換為querystring。例如請求數(shù)據(jù){name:'name',age:18}轉(zhuǎn)換后的結(jié)果是name=name&age=18。

2.對于POST方法且請求頭content-type屬性為application/json的請求數(shù)據(jù)，會自動進行JSON序列化處理。

3.對于POST方法且請求頭content-type屬性為application/x-www-form-urlencoded的請求數(shù)據(jù)，會將數(shù)據(jù)自動轉(zhuǎn)換為querystring。

請求成功success回調(diào)函數(shù)返回參數(shù)如下。請求失敗fail回調(diào)函數(shù)內(nèi)部可通過errCode參數(shù)獲取失敗狀態(tài)碼，errMsg獲取具體的失敗信息。參數(shù)類型說明dataObject/String/ArrayBuffer后端服務(wù)器接口返回數(shù)據(jù)statusCodeNumber后端服務(wù)器接口返回的HTTP狀態(tài)碼headerObject后端服務(wù)器接口返回的響應(yīng)頭cookiesArray.<string>后端服務(wù)器接口返回的cookies，格式為字符串?dāng)?shù)組

6.2.1request網(wǎng)絡(luò)請求requestAPI的非Promise化寫法使用示例如下，默認(rèn)請求方式是GET，可省略method屬性。uni.request({

url:'/request',//僅為示例，并非真實接口地址

data:{

name:'name',

age:18

},

header:{

'custom-header':'hello'//自定義請求頭信息

},

success:(res)=>{

if(res.data.code==200)

console.log(res.data.data);

}})

6.2.1request網(wǎng)絡(luò)請求

如果是POST請求，需在代碼中配置method:'POST'，并根據(jù)后端服務(wù)器的content-type值配置content-type屬性。uni.request({

url:'/request',//僅為示例，并非真實接口地址

method:'POST',

data:{

name:'name',

age:18

},

header:{

'custom-header':'hello'//自定義請求頭信息

'content-type':'application/json'

},

success:(res)=>{

if(res.data.code==200)

console.log(res.data.data);

}})

6.2.1request網(wǎng)絡(luò)請求如果希望中斷請求，可采用如下寫法獲取一個RequestTask對象，并調(diào)用abort方法。varrequestTask=uni.request({ url:'/request',//僅為示例，并非真實接口地址。 complete:()=>{}})requestTask.abort()//中斷請求

下面以GET請求方式，對網(wǎng)絡(luò)開源接口：/try/ajax/json_demo.json，進行request網(wǎng)絡(luò)請求，演示request

API用法。該接口返回如下JSON格式的數(shù)據(jù)，使用多列選擇器對其中sites屬性的內(nèi)容進行展示。{

"name":"網(wǎng)站",

"num":3,

"sites":[

{"name":"Google","info":["Android","Google搜索","Google翻譯"]},

{"name":"Runoob","info":["菜鳥教程","菜鳥工具","菜鳥微信"]},

{"name":"Taobao","info":["淘寶","網(wǎng)購"]}

]}

6.2.1request網(wǎng)絡(luò)請求<template> <view> <pickermode="multiSelector":range="list"@change="pickerChange" range-key="name"@columnchange="columnChange"> <view>{{selectValue}}</view> </picker> </view></template><scriptsetup> import{onLoad}from'@dcloudio/uni-app' import{ref,reactive}from'vue'; letselectValue=ref("請選擇") lettotalData=reactive([]) letlist=reactive([]) onLoad((option)=>{ uni.request({ url:'/try/ajax/json_demo.json', success:(res)=>{ if(res.statusCode==200){ totalData=res.data.sites letarray1=[]//剩余代碼見下一頁

6.2.1request網(wǎng)絡(luò)請求 for(letindexinres.data.sites){ array1.push({id:index,name:res.data.sites[index].name}) } letarray2=[] for(letindexinres.data.sites[0].info){ array2.push({id:index,name:res.data.sites[0].info[index]}) } list.push(array1) list.push(array2) console.log(list); } } }) }) functioncolumnChange(e){ letcol=e.detail.column//獲取選擇的第幾列

letcolindex=e.detail.value//獲取選擇列值對應(yīng)的索引

if(col==0){ list.length=0 letarray1=[]//剩余代碼見下一頁

6.2.1request網(wǎng)絡(luò)請求 for(letindexintotalData){ array1.push({id:index,name:totalData[index].name}) } letarray2=[] for(letindexintotalData[colindex].info){ array2.push({id:index,name:totalData[colindex].info[index]}) } list.push(array1) list.push(array2)

} } functionpickerChange(e){ letindex1=e.detail.value[0]//獲取第一列變更值的索引

letindex2=e.detail.value[1]//獲取第二列變更值的索引

selectValue.value=list[0][index1].name+","+list[1][index2].name }</script><style></style>

6.2.1request網(wǎng)絡(luò)請求在微信開發(fā)者工具運行效果。

6.2.2uploadFile文件上傳

uploadFileAPI將本地資源上傳到開發(fā)者服務(wù)器，客戶端發(fā)起一個POST請求，其中content-type為multipart/form-data。uploadFile主要參數(shù)參數(shù)名類型是否必填說明urlString是設(shè)置后端服務(wù)器文件上傳的接口地址filesArray是（files和filePath選其一）設(shè)置需要上傳的文件列表。使用files時，filePath和name不生效，該參數(shù)僅App和Web端支持filePathString是（files和filePath選其一）設(shè)置要上傳文件資源的路徑fileTypeString支付寶小程序必填設(shè)置文件類型，image/video/audio，僅支付寶小程序，且必填。nameString是設(shè)置文件對應(yīng)的ke，開發(fā)者在服務(wù)器端通過這個key可以獲取到文件二進制內(nèi)容headerObject否設(shè)置HTTP請求頭，請求頭中不能設(shè)置ReferertimeoutNumber否設(shè)置超時時間，單位msformDataObject否設(shè)置HTTP請求中其他額外的formdatasuccessFunction否收到開發(fā)者服務(wù)器成功返回的回調(diào)函數(shù)，內(nèi)部可通過statusCode獲取HTTP狀態(tài)碼，通過data屬性獲取具體的返回數(shù)據(jù)failFunction否接口調(diào)用失敗的回調(diào)函數(shù)，內(nèi)部可通過errCode參數(shù)獲取失敗狀態(tài)碼，errMsg獲取具體的失敗信息completeFunction否接口調(diào)用結(jié)束的回調(diào)函數(shù)，調(diào)用成功、失敗都會執(zhí)行

6.2.2uploadFile文件上傳

files參數(shù)是一個file對象的數(shù)組。files內(nèi)部對象結(jié)構(gòu)參數(shù)名類型是否必填說明nameString否設(shè)置multipart提交時，表單的項目名，默認(rèn)為file，如果name不填或填的值相同，可能導(dǎo)致服務(wù)端讀取文件時只能讀取到一個文件fileFile否設(shè)置要上傳的文件對象，僅Web端支持uriString是設(shè)置文件本地地址

uploadFile

API使用時需注意以下幾點：

1.和requestAPI一樣，如果是真機測試環(huán)境下，url地址必須使用HTTPS域名地址，且需配置域名白名單，否則不能正常獲取數(shù)據(jù)。如果是在微信開發(fā)者工具中，url地址可以使用使用HTTP/HTTPS域名地址，不需配置域名白名單。

2.uploadFile

API在App端支持多文件上傳，而在微信小程序只支持單文件上傳。為支持跨端，建議多文件上傳時統(tǒng)一使用循環(huán)方式調(diào)用本API。

3.如需統(tǒng)一配置網(wǎng)絡(luò)請求的超時時間，可在manifest.json中配置networkTimeout屬性。

6.2.2uploadFile文件上傳

uploadFileAPI使用示例如下，可先通過uni.chooseImage等接口獲取到一個本地資源的臨時文件路徑后，再通過此接口將本地資源上傳到指定服務(wù)器。uni.chooseImage({ success:(chooseImageRes)=>{ consttempFilePaths=chooseImageRes.tempFilePaths; uni.uploadFile({ url:'/upload',//僅為示例，非真實的接口地址

filePath:tempFilePaths[0], name:'file', formData:{ 'user':'test' }, success:(uploadFileRes)=>{ console.log(uploadFileRes.data); } }); }})

6.2.2uploadFile文件上傳如果希望返回一個UploadTask對象，需要至少傳入success/fail/complete參數(shù)中的一個。varuploadTask=uni.uploadFile({ url:'/upload',//僅為示例，并非真實接口地址。 complete:()=>{}})通過UploadTask對象可以中斷上傳任務(wù)，監(jiān)聽上傳進度。UploadTask對象提供了如下一些方法。UploadTask對象方法方法名參數(shù)說明abort

中斷上傳任務(wù)onProgressUpdatecallback監(jiān)聽上傳進度條變化，內(nèi)部可通過progress屬性獲取上傳進度百分比，通過totalBytesSent屬性獲取已經(jīng)上傳的數(shù)據(jù)長度，通過totalBytesExpectedToSend屬性獲取預(yù)期需要上傳的數(shù)據(jù)總長度onHeadersReceivedcallback監(jiān)聽HTTPResponseHeader事件offProgressUpdatecallback取消監(jiān)聽上傳進度條變化事件offHeadersReceivedcallback取消監(jiān)聽HTTPResponseHeader事件

6.2.2uploadFile文件上傳使用uploadFileAPI來上傳圖片示例代碼。<template> <view> <buttontype="primary"size="mini"@click="uploadFile">上傳文件</button> </view></template><scriptsetup> functionuploadFile(){

//選擇文件

uni.chooseImage({ success:(chooseImageRes)=>{

//文件本地路徑列表tempFilePaths consttempFilePaths=chooseImageRes.tempFilePaths;

//for循環(huán)依次從tempFilePaths中獲取文件路徑上傳

for(letitemoftempFilePaths){ constuploadTask=uni.uploadFile({ url:'http://localhost:8080/upload',//僅為示例，非真實地址

filePath:item, name:'file',

//name的值要和后端接收參數(shù)名保持一致

formData:{ 'user':'test' },//剩余代碼見下一頁

6.2.2uploadFile文件上傳 success:(uploadFileRes)=>{ console.log(uploadFileRes.data); }, fail:(err)=>{ console.log(err.errMsg); } }); uploadTask.onProgressUpdate((res)=>{ console.log('上傳進度'+gress); console.log('已經(jīng)上傳的數(shù)據(jù)長度'+res.totalBytesSent); console.log('預(yù)期需要上傳的數(shù)據(jù)總長度'+

res.totalBytesExpectedToSend); }); } } }); }</script><style></style>

6.2.2uploadFile文件上傳@PostMapping("/upload'")@ResponseBodypublicStringupload(@RequestPart(value="file")MultipartFilefile)throwsIOException{ if(!file.isEmpty()){ //省略代碼，將文件寫到指定目錄 } return"success";}如使用SpringBoot做后端接收上傳的文件，后端可使用如下代碼實現(xiàn)。

6.2.3downloadFile文件下載

downloadFileAPI將文件資源從服務(wù)器下載到本地，客戶端直接發(fā)起一個HTTPGET請求，返回文件的本地臨時路徑。該臨時路徑在應(yīng)用本次啟動期間可以正常使用，如需持久保存，需在調(diào)用saveFile文件API將文件保存在本地，才能在應(yīng)用下次啟動時訪問得到。downloadFile主要參數(shù)參數(shù)名類型是否必填說明urlString是設(shè)置后端服務(wù)器文件下載的接口地址headerObject否設(shè)置HTTP請求頭，請求頭中不能設(shè)置ReferertimeoutNumber否設(shè)置超時時間，單位ms，H5、APP、微信小程序、支付寶小程序、抖音小程序、快手小程序filePathString否設(shè)置文件下載后存儲的本地路徑，小程序端支持（微信IOS小程序保存到相冊需要添加此字段才可以正常保存）successFunction否收到開發(fā)者服務(wù)器成功返回的回調(diào)函數(shù)，內(nèi)部可通過statusCode獲取HTTP狀態(tài)碼，通過tempFilePath屬性獲取下載成功后文件的臨時路徑failFunction否接口調(diào)用失敗的回調(diào)函數(shù)，內(nèi)部可通過errCode參數(shù)獲取失敗狀態(tài)碼，errMsg獲取具體的失敗信息completeFunction否接口調(diào)用結(jié)束的回調(diào)函數(shù)，調(diào)用成功、失敗都會執(zhí)行

6.2.3downloadFile文件下載

downloadFileAPI使用示例如下。uni.downloadFile({ url:'http://localhost:8080/download',//僅為示例，并非真實的資源

success:(res)=>{ if(res.statusCode===200){ console.log('下載成功'); console.log('文件臨時存儲路徑'+res.tempFilePath);

//通過文件臨時存儲路徑將文件保存本地

uni.saveFile({ tempFilePath:res.tempFilePath, success:function(res1){ console.log('文件保存本地路徑'+res1.savedFilePath); } }); } } fail:(err)=>{ console.log(err.errMsg); }})

6.2.3downloadFile文件下載

如果希望返回一個DownloadTask對象，可采用如下寫法，至少傳入success/fail/complete參數(shù)中的一個。vardownloadTask=uni.downloadFile({ url:'http://localhost:8080/download',//僅為示例，并非真實接口地址。

complete:()=>{}});

通過DownloadTask對象可取消下載任務(wù)，監(jiān)聽下載進度變化。DownloadTask對象常用方法如下。DownloadTask對象方法方法名參數(shù)說明abort

取消下載任務(wù)onProgressUpdatecallback監(jiān)聽下載進度條變化，內(nèi)部可通過progress屬性獲取下載進度百分比，通過totalBytesWritten屬性獲取已經(jīng)下載的數(shù)據(jù)長度，通過totalBytesExpectedToWrite屬性獲取預(yù)期需要下載的數(shù)據(jù)總長度onHeadersReceivedcallback監(jiān)聽HTTPResponseHeader事件offProgressUpdatecallback取消監(jiān)聽下載進度條變化事件offHeadersReceivedcallback取消監(jiān)聽HTTPResponseHeader事件

6.2.3downloadFile文件下載

DownloadTask對象使用示例如下。downloadTask.onProgressUpdate((res)=>{ console.log('下載進度'+gress); console.log('已經(jīng)下載的數(shù)據(jù)長度'+res.totalBytesWritten); console.log('預(yù)期需要下載的數(shù)據(jù)總長度'+res.totalBytesExpectedToWrite); //滿足測試條件，取消下載任務(wù)。 if(gress>50){ downloadTask.abort(); }})03任務(wù)3頁面和路由類API

6.3.1navigateTo路由API

navigateToAPI用于保留當(dāng)前頁面，跳轉(zhuǎn)到應(yīng)用內(nèi)的某個頁面，跳轉(zhuǎn)完畢后還可以使用navigateBack可以返回到原頁面。navigateTo主要參數(shù)參數(shù)名類型是否必填說明urlString是需要跳轉(zhuǎn)的應(yīng)用內(nèi)非tabBar的頁面的路徑，路徑后可以帶參數(shù)。參數(shù)與路徑之間使用?分隔，參數(shù)鍵與參數(shù)值用=相連，不同參數(shù)用&分隔；如'path?key=value&key2=value2'，path為下一個頁面的路徑，可在下一個頁面使用onLoad函數(shù)得到傳遞的參數(shù)animationTypeString否設(shè)置窗口顯示的動畫效果，默認(rèn)值為pop-in，僅App端支持animationDurationNumber否設(shè)置窗口動畫持續(xù)時間，單位為ms，默認(rèn)值為300，僅App端支持eventsObject否頁面間通信接口，用于監(jiān)聽被打開頁面發(fā)送到當(dāng)前頁面的數(shù)據(jù)successFunction否接口調(diào)用成功的回調(diào)函數(shù)，內(nèi)部可通過eventChannel屬性向被打開頁面?zhèn)魉蛿?shù)據(jù)failFunction否接口調(diào)用失敗的回調(diào)函數(shù)，內(nèi)部可通過errCode參數(shù)獲取失敗狀態(tài)碼，errMsg獲取具體的失敗信息completeFunction否接口調(diào)用結(jié)束的回調(diào)函數(shù)，調(diào)用成功、失敗都會執(zhí)行

6.3.1navigateTo路由API

success回調(diào)函數(shù)中的eventChannel屬性是一個EventChannel對象，用于頁面間事件通信和數(shù)據(jù)傳遞。EventChannel對象提供以下4個方法。EventChannel對象方法方法名說明emit(StringeventName,Anyargs)用于觸發(fā)一個事件。eventName為事件名稱，args為事件參數(shù)off(StringeventName,Functionfn)用于取消監(jiān)聽一個事件。給出第二個參數(shù)時，只取消給出的監(jiān)聽函數(shù)，否則取消所有監(jiān)聽函數(shù)。eventName為事件名稱，fn為事件監(jiān)聽函數(shù)on(stringeventName,functionfn)用于持續(xù)監(jiān)聽一個事件。eventName為事件名稱，fn為事件監(jiān)聽函數(shù)once(stringeventName,functionfn)用于監(jiān)聽一個事件一次，觸發(fā)后失效。eventName為事件名稱，fn為事件監(jiān)聽函數(shù)

6.3.1navigateTo路由API

在uniappdemo6項目pages/navigate-to目錄下新建一個navigate-to.vue頁面作為上一級頁面存在。<template> <view> <buttontype="primary"size="mini"@click="navigateTo">跳轉(zhuǎn)頁面</button> </view></template><scriptsetup> functionnavigateTo(){ //當(dāng)前頁面跳轉(zhuǎn)到test.vue頁面并傳遞參數(shù)

uni.navigateTo({ url:"../navigate-to/test?id=1&name=uniapp", events:{ //為指定事件添加監(jiān)聽器，獲取test.vue頁面?zhèn)魉偷疆?dāng)前頁面的數(shù)據(jù)

acceptDataFromOpenedPage:function(data){ console.log(data) }, //為指定事件添加監(jiān)聽器，獲取test.vue頁面?zhèn)魉偷疆?dāng)前頁面的數(shù)據(jù)

someEvent:function(data){ console.log(data) } },//剩余代碼見下一頁

6.3.1navigateTo路由API success:function(res){ //跳轉(zhuǎn)成功通過eventChannel向test.vue頁面?zhèn)魉蛿?shù)據(jù) res.eventChannel.emit('acceptDataFromOpenerPage',{ data:'datafromstarterpage', }) } }); }</script><style></style>

6.3.1navigateTo路由API

新建一個test.vue頁面作為下一級頁面存在。在其中輸入如下代碼控制從navigate-to頁面跳轉(zhuǎn)到test.vue頁面時互相傳遞參數(shù)。<template> <view> </view></template><scriptsetup> import{onLoad}from'@dcloudio/uni-app' import{getCurrentInstance}from'vue'; constinstance=getCurrentInstance().proxy consteventChannel=instance.getOpenerEventChannel() onLoad((option)=>{ console.log(option.id) console.log() eventChannel.emit('acceptDataFromOpenedPage',{ data:'datafromtestpage', }) eventChannel.emit('someEvent',{ data:'datafromtestpageforsomeEvent' });//剩余代碼見下一頁

6.3.1navigateTo路由API //監(jiān)聽acceptDataFromOpenerPage事件， //獲取上一頁面通過eventChannel傳送到當(dāng)前頁面的數(shù)據(jù) eventChannel.on('acceptDataFromOpenerPage',function(data){ console.log('acceptDataFromOpenerPage',data) }) })</script><style></style>

6.3.1navigateTo路由API

navigateTo

API使用時需注意以下幾點：

1.頁面跳轉(zhuǎn)路徑有層級限制，不能無限制跳轉(zhuǎn)新頁面。

2.如要跳轉(zhuǎn)到tabBar頁面路徑，只能使用switchTab跳轉(zhuǎn)。

3.url屬性指向的目標(biāo)頁面路徑必須是在pages.json里注冊的。

4.通過url有長度限制，如傳遞參數(shù)長度過長會失敗，可使用頁面通信API實現(xiàn)，頁面通信API將在后續(xù)內(nèi)容介紹。

5.通過url傳遞的參數(shù)出現(xiàn)空格等特殊字符時需要對參數(shù)使用encodeURIComponent進行編碼，例如跳轉(zhuǎn)test.vue頁面并傳遞item參數(shù)，可使用如下寫法。

在test.vue頁面接受參數(shù)時需使用decodeURIComponent解碼。url:"../navigate-to/test?item="+encodeURIComponent(JSON.stringify(item))onLoad:function(option){ constitem=JSON.parse(decodeURIComponent(option.item));}

6.3.2redirectTo路由API

redirectToAPI用于關(guān)閉當(dāng)前頁面，重定向跳轉(zhuǎn)到應(yīng)用內(nèi)的某個頁面，跳轉(zhuǎn)完畢后不能使用navigateBack可以返回到原頁面。redirectTo主要參數(shù)參數(shù)名類型是否必填說明urlString是需要跳轉(zhuǎn)的應(yīng)用內(nèi)非tabBar的頁面的路徑，路徑后可以帶參數(shù)。參數(shù)與路徑之間使用?分隔，參數(shù)鍵與參數(shù)值用=相連，不同參數(shù)用&分隔；如'path?key=value&key2=value2'，path為下一個頁面的路徑，可在下一個頁面使用onLoad函數(shù)得到傳遞的參數(shù)successFunction否接口調(diào)用成功的回調(diào)函數(shù)failFunction否接口調(diào)用失敗的回調(diào)函數(shù)，內(nèi)部可通過errMsg獲取具體的失敗信息completeFunction否接口調(diào)用結(jié)束的回調(diào)函數(shù)，調(diào)用成功、失敗都會執(zhí)行

6.3.2redirectTo路由APIredirectTo使用示例如下。uni.redirectTo({ url:'test?id=1', success:function(res){

})})

6.3.3reLaunch路由API

reLaunchAPI用于關(guān)閉所有頁面，打開到應(yīng)用內(nèi)的某個頁面，跳轉(zhuǎn)完畢后不能使用navigateBack可以返回到原頁面。reLaunch主要參數(shù)參數(shù)名類型是否必填說明urlString是需要跳轉(zhuǎn)的應(yīng)用內(nèi)非tabBar的頁面的路徑，路徑后可以帶參數(shù)。參數(shù)與路徑之間使用?分隔，參數(shù)鍵與參數(shù)值用=相連，不同參數(shù)用&分隔；如'path?key=value&key2=value2'，path為下一個頁面的路徑，可在下一個頁面使用onLoad函數(shù)得到傳遞的參數(shù)successFunction否接口調(diào)用成功的回調(diào)函數(shù)，內(nèi)部可通過errMsg獲取具體的失敗信息failFunction否接口調(diào)用失敗的回調(diào)函數(shù)completeFunction否接口調(diào)用結(jié)束的回調(diào)函數(shù)，調(diào)用成功、失敗都會執(zhí)行

6.3.3reLaunch路由API

reLaunch使用示例如下。uni.reLaunch({ url:'test?id=1', success:function(res){

})})

Web端調(diào)用uni.reLaunch之后之前頁面棧會銷毀，但是無法清空瀏覽器之前的歷史記錄，此時navigateBack不能返回，可通過點擊瀏覽器的返回按鈕或者調(diào)用history.back()導(dǎo)航到瀏覽器的歷史記錄頁面。

6.3.3reLaunch路由API

switchTabAPI用于跳轉(zhuǎn)到tabBar頁面，并關(guān)閉其他所有非tabBar頁面。switchTab主要參數(shù)參數(shù)名類型是否必填說明urlString是需要跳轉(zhuǎn)的tabBar頁面的路徑，需在pages.json文件的tabBar字段定義的頁面路由，路徑后不能帶參數(shù)successFunction否接口調(diào)用成功的回調(diào)函數(shù)failFunction否接口調(diào)用失敗的回調(diào)函數(shù)，內(nèi)部可通過errMsg獲取具體的失敗信息completeFunction否接口調(diào)用結(jié)束的回調(diào)函數(shù)，調(diào)用成功、失敗都會執(zhí)行

6.3.3reLaunch路由APIswitchTab使用示例如下。uni.switchTab({ url:'/pages/index/index'});同時pages.json文件中需進行如下tabBar配置。{

"tabBar":{

"list":[{

"pagePath":"pages/index/index",

"text":"首頁"

},{

"pagePath":"pages/other/other",

"text":"其他"

}]

}}

6.3.5navigateBack路由API

navigateBackAPI用于關(guān)閉當(dāng)前頁面，返回上一頁面或多級頁面。跳轉(zhuǎn)多級頁面可通過getCurrentPages()獲取當(dāng)前的頁面棧，決定需要返回幾層。navigateBack主要參數(shù)參數(shù)名類型是否必填說明deltaNumber否返回的頁面數(shù)，默認(rèn)值為1。如果delta大于現(xiàn)有頁面數(shù)，則返回到首頁animationTypeString否設(shè)置窗口關(guān)閉的動畫效果，默認(rèn)值為pop-out，僅App端支持animationDurationNumber否設(shè)置窗口關(guān)閉動畫持續(xù)時間，單位為ms，默認(rèn)值為300，僅App端支持successFunction否接口調(diào)用成功的回調(diào)函數(shù)failFunction否接口調(diào)用失敗的回調(diào)函數(shù)，內(nèi)部可通過errCode參數(shù)獲取失敗狀態(tài)碼，errMsg獲取具體的失敗信息completeFunction否接口調(diào)用結(jié)束的回調(diào)函數(shù)，調(diào)用成功、失敗都會執(zhí)行

6.3.5navigateBack路由API

通過navigateTo跳轉(zhuǎn)的頁面會被加入頁面棧，可以使用navigateBack返回。通過redirectTo跳轉(zhuǎn)的頁面不會加入頁面棧，不能使用navigateBack返回。

navigateBack使用示例如下。//此處是A頁面uni.navigateTo({ url:'B?id=1'})

//此處是B頁面uni.navigateTo({ url:'C?id=1'})

//在C頁面內(nèi)navigateBack，將返回A頁面uni.navigateBack({ delta:2})

6.3.6getCurrentPages頁面API

getCurrentPagesAPI用于獲取當(dāng)前頁面棧的實例，以數(shù)組形式按棧的順序給出，第一個元素為首頁實例，最后一個元素為當(dāng)前頁面實例。頁面跳轉(zhuǎn)時，getCurrentPages可用于上下級頁面互相訪問對方成員。每個頁面實例的屬性和方法如下。表6-14頁面實例的屬性和方法屬性/方法說明page.$getAppWebview()獲取當(dāng)前頁面的WebView對象實例，僅App端支持page.$vm當(dāng)前頁面的Vue實例page.route獲取當(dāng)前頁面的路由

這里在項目pages/get-currents目錄下新建pres.vue頁面作為上級頁面，新建get-currents.vue頁面作為下級頁面。輸入代碼在pres.vue頁面添加按鈕，單擊按鈕跳轉(zhuǎn)到get-currents.vue頁面。在get-currents.vue頁面中通過getCurrentPages訪問pres.vue頁面的變量和方法。

6.3.6getCurrentPages頁面API<template> <view> <buttontype="primary"size="mini"@click="navigateTo">跳轉(zhuǎn)頁面</button> </view></template><scriptsetup> lettitle="aaa" consttest=()=>{ console.log("test方法執(zhí)行") } constnavigateTo=()=>{ uni.navigateTo({ url:"/pages/get-currents/get-currents" }) } //暴露變量和方法，給下一級頁面get-currents.vue訪問

defineExpose({ test, title })</script><style></style>pres.vue

6.3.6getCurrentPages頁面API<template> <view> </view></template><scriptsetup> import{onLoad}from'@dcloudio/uni-app' onLoad((option)=>{ //獲取當(dāng)前頁面棧實例（此時最后一個元素為當(dāng)前頁）

constpages=getCurrentPages() //獲取上一級頁面Vue實例

constprevPage=pages[pages.length-2] //獲取上一級頁面title變量值

console.log(prevPage.$vm.title) //調(diào)用上一級頁面test方法

prevPage.$vm.test() })</script><style></style>get-currents.vue

6.3.7頁面通信API

頁面通信API允許用戶自定義一個全局事件，通過該事件可實現(xiàn)頁面之間的參數(shù)傳遞。頁面通信API包括$emit、$on、$once和$off四類。頁面通信API方法名說明$emit(StringeventName,Objectobject)觸發(fā)全局的自定義事件，附加參數(shù)都會傳給監(jiān)聽器回調(diào)函數(shù)。eventName為事件名稱，object為觸發(fā)事件攜帶的附加參數(shù)$off(StringeventName,Functioncallback)移除全局自定義事件監(jiān)聽器。eventName為事件名稱，callback為事件監(jiān)聽函數(shù)$on(stringeventName,functioncallback)監(jiān)聽全局的自定義事件，事件由$emit觸發(fā)，回調(diào)函數(shù)會接收事件觸發(fā)函數(shù)的傳入?yún)?shù)。eventName為事件名稱，callback為事件監(jiān)聽函數(shù)$once(stringeventName,functioncallback)監(jiān)聽全局的自定義事件，事件由$emit觸發(fā)，但僅觸發(fā)一次，在第一次觸發(fā)之后移除該監(jiān)聽器。eventName為事件名稱，callback為事件監(jiān)聽函數(shù)

6.3.7頁面通信API

$off的使用需注意以下幾點：

1.如果$off沒有傳入?yún)?shù)，則移除所有事件監(jiān)聽器。

2.如果只提供了事件名（eventName），則移除該事件名對應(yīng)的所有監(jiān)聽器。

3.如果同時提供了事件與回調(diào)函數(shù)，則只移除這個事件回調(diào)函數(shù)對應(yīng)的監(jiān)聽器。注意回調(diào)函數(shù)必須跟$on的回調(diào)函數(shù)保持一致，為同一個函數(shù)，才能生效。

4.$emit和$on屬于全局級別跨頁面、跨組件的傳參，接收端頁面接收數(shù)據(jù)后，要及時移除監(jiān)聽器。如使用$on監(jiān)聽，可在頁面onUnload周期使用$off移除監(jiān)聽器，或者在接收端使用$once監(jiān)聽一次。

這里在項目pages/emit目錄下新建emit.vue頁面作為上級頁面，新建emit-sub.vue頁面作為下級頁面。在emit.vue頁面中定義按鈕跳轉(zhuǎn)到emit-sub.vue頁面，并同時使用$emit向emit-sub.vue頁面?zhèn)鬟f數(shù)據(jù)，emit-sub.vue頁面使用$on監(jiān)聽接收傳遞過來的數(shù)據(jù)。

6.3.7頁面通信API<template> <view> <buttontype="primary"size="mini"@click="navigateTo">跳轉(zhuǎn)頁面</button> </view></template><scriptsetup> constnavigateTo=()=>{ uni.navigateTo({ url:"/pages/emit/emit-sub", success:(res)=>{ //先跳轉(zhuǎn)頁面，待emit-sub加載完畢后傳遞數(shù)據(jù)，否則接收不到數(shù)據(jù)

console.log("跳轉(zhuǎn)成功后，向emit-sub傳遞數(shù)據(jù)") uni.$emit("emit",{ data:1 }) } }) }</script><style></style>emit.vue

6.3.7頁面通信API<template> <view> 收到頁面emit傳遞的數(shù)據(jù):{{data}} </view></template><scriptsetup> import{onLoad,onUnload}from'@dcloudio/uni-app' import{ref}from'vue'; letdata=ref(0) onLoad((option)=>{ uni.$on("emit",(res)=>{ console.log('收到頁面emit傳遞的數(shù)據(jù):',res.data); data.value=res.data }) }) //頁面銷毀時移除監(jiān)聽 onUnload(()=>{ uni.$off("emit"); })</script><style></style>emit-sub.vue04任務(wù)4數(shù)據(jù)緩存類API

6.4.1setStorage類API

setStorage類API用于將數(shù)據(jù)存儲在本地緩存中指定的一個key中，如果該key值已存在，會覆蓋掉key中已存儲的內(nèi)容。setStorage類API分為同步和異步兩種，同步API名為setStorageSync，異步API名為setStorage。

setStorageSyncAPI只有兩個參數(shù)key和data。setStorageSync參數(shù)參數(shù)名類型是否必填說明keyString是本地緩存中的指定的keydataAny是需要存儲的內(nèi)容，只支持原生類型、及能夠通過JSON.stringify序列化的對象

6.4.1setStorage類API

setStorageAPI在setStorageSyncAPI基礎(chǔ)上新增了success、fail和complete三個異步回調(diào)函數(shù)作為參數(shù)。setStorage參數(shù)參數(shù)名類型是否必填說明keyString是本地緩存中的指定的

keydataAny是需要存儲的內(nèi)容，只支持原生類型、及能夠通過JSON.stringify序列化的對象successFunction否接口調(diào)用成功的回調(diào)函數(shù)，failFunction否接口調(diào)用失敗的回調(diào)函數(shù)completeFunction否接口調(diào)用結(jié)束的回調(diào)函數(shù)，調(diào)用成功、失敗都會執(zhí)行

注意：uni-、uni_、dcloud-、dcloud_為前綴的key，為系統(tǒng)保留關(guān)鍵前綴。在命名key時請避開這些前綴。

6.4.1setStorage類APIsetStorageSyncAPI使用示例如下。setStorageAPI使用示例如下。uni.setStorageSync('storage_key','hello');uni.setStorage({ key:'storage_key', data:'hello', success:function(){ console.log('success'); }})

6.4.2getStorage類API

getStorage類API用于從本地緩存中獲取指定key對應(yīng)的內(nèi)容。getStorage類API分為同步和異步兩種，同步API名為getStorageSync，異步API名為getStorage。

getStorageSyncAPI只有1個參數(shù)key，用于從本地緩存中讀取數(shù)據(jù)時指定key。

getStorageAPI在getStorageSyncAPI基礎(chǔ)上新增了success、fail和complete三個異步回調(diào)函數(shù)作為參數(shù)。getStorage參數(shù)參數(shù)名類型是否必填說明keyString是本地緩存中的指定的keysuccessFunction否接口調(diào)用成功的回調(diào)函數(shù)，可通過data屬性獲取key對應(yīng)的數(shù)據(jù)內(nèi)容failFunction否接口調(diào)用失敗的回調(diào)函數(shù)completeFunction否接口調(diào)用結(jié)束的回調(diào)函數(shù)，調(diào)用成功、失敗都會執(zhí)行

6.4.2getStorage類APIgetStorageSyncAPI使用示例如下。setStorageAPI使用示例如下。constvalue=uni.getStorageSync('storage_key');if(value){ console.log(value);}uni.getStorage({ key:'storage_key', success:function(res){ console.log(res.data); }})

6.4.3getStorageInfo類API

getStorageInfo類API獲取當(dāng)前本地緩存的相關(guān)信息，包括本地緩存的所有key、占用空間大小等。getStorageInfo類API分為同步和異步兩種，同步API名為getStorageInfoSync，異步API名為getStorageInfo。

getStorageInfoSyncAPI沒有輸入?yún)?shù)。返回值包括keys、currentSize和limitSize三個屬性。getStorageInfoSync返回值屬性參數(shù)名類型說明keysArray＜String＞獲取本地緩存中所有的keycurrentSizeNumber獲取本地緩存當(dāng)前占用的空間大小,單位為kblimitSizeFunction獲取本地緩存限制的空間大小,單位為kb

6.4.3getStorageInfo類API

getStorageAPI在getStorageSyncAPI基礎(chǔ)上新增了success、fail和complete三個異步回調(diào)函數(shù)作為參數(shù)。

getStorageInfoSyncAPI使用示例如下。constres=uni.getStorageInfoSync();console.log(res.keys);console.log(res.currentSize);console.log(res.limitSize);getStorageInfo

API使用示例如下。uni.getStorageInfo({ success:function(res){ console.log(res.keys); console.log(res.currentSize); console.log(res.limitSize); }})

6.4.4removeStorage和clearStorage類API

removeStorage和clearStorage類API都用于清除本地緩存。所不同的是removeStorage類API用于從本地緩存中移除指定key。clearStorage類API用于一次性清理本地數(shù)據(jù)緩存。

1.removeStorage類API

removeStorage類API分為同步和異步兩種，同步API名為removeStorageSync，異步API名為removeStorage。

removeStorageSyncAPI只有1個參數(shù)key，用于從本地緩存中移除數(shù)據(jù)時指定key。

removeStorageAPI在removeStorageSyncAPI基礎(chǔ)上新增了success、fail和complete三個異步回調(diào)函數(shù)作為參數(shù)。removeStorage參數(shù)參數(shù)名類型是否必填說明keyString是本地緩存中的指定的keysuccessFunction否接口調(diào)用成功的回調(diào)函數(shù)failFunction否接口調(diào)用失敗的回調(diào)函數(shù)completeFunction否接口調(diào)用結(jié)束的回調(diào)函數(shù)，調(diào)用成功、失敗都會執(zhí)行

6.4.4removeStorage和clearStorage類API

removeStorageSyncAPI使用示例如下。uni.removeStorageSync('storage_key');

removeStorageAPI使用示例如下。uni.removeStorage({ key:'storage_key', success:function(res){ console.log('success'); }})

2.clearStorage類API

clearStorage類API分為同步和異步兩種，同步API名為clearStorageSync，異步API名為clearStorage。

clearStorageSync和clearStorage都沒有參數(shù)，使用示例如下。uni.clearStorageSync();

//同步清理本地緩存uni.clearStorage();

//異步清理本地緩存05任務(wù)5位置類API

任務(wù)5位置類API

位置類API允許開發(fā)人員獲取當(dāng)前位置信息，用于地圖定位、查找附件人或店鋪、顯示詳細(xì)地址信息等。位置類API中最常用的就是getLocation。getLocation用于獲取當(dāng)前的地理位置和速度。getLocation參數(shù)參數(shù)名類型是否必填說明typeString否設(shè)置返回坐標(biāo)類型，有效值為wgs84（默認(rèn)值，返回GPS坐標(biāo)）和gcj02（返回國測局坐標(biāo)）。gcj02類型坐標(biāo)可直接用于uni.openLocation和map組件定位。App和Web端需配置定位SDK信息才可支持gcj02，小程序端可直接使用gcj02altitudeBoolean否設(shè)置獲取高度，默認(rèn)值為false,傳入true會返回高度信息，由于獲取高度需要較高精確度，會減慢接口返回速度。抖音小程序、飛書小程序、支付寶小程序不支持geocodeBoolean否設(shè)置是否解析地址信息，默認(rèn)值false。僅App平臺支持（安卓需指定type為gcj02并配置三方定位SDK）highAccuracyExpireTimeNumber否設(shè)置高精度定位超時時間(ms)，指定時間內(nèi)返回最高精度，該值3000ms以上高精度定位才有效果isHighAccuracyBoolean否設(shè)置是否開啟高精度定位successFunction否接口調(diào)用成功的回調(diào)函數(shù)failFunction否接口調(diào)用失敗的回調(diào)函數(shù)completeFunction否接口調(diào)用結(jié)束的回調(diào)函數(shù)，調(diào)用成功、失敗都會執(zhí)行

任務(wù)5位置類API

sucess回調(diào)函數(shù)返回參數(shù)如下。sucess回調(diào)函數(shù)返回參數(shù)參數(shù)名說明latitude獲取緯度，浮點數(shù)，范圍為-90~90，負(fù)數(shù)表示南緯longitude獲取經(jīng)度，浮點數(shù)，范圍為-180~180，負(fù)數(shù)表示西經(jīng)speed獲取速度，浮點數(shù)，單位m/saccuracy獲取位置的精確度altitude獲取高度，單位mverticalAccuracy獲取垂直精度，單位m（Android無法獲取，返回0）horizontalAccuracy獲取水平精度，單位maddress獲取詳細(xì)地址信息（僅App端支持，需配置geocode為true）

address詳細(xì)地址信息的有效字段包括：country（國家）、province（?。ity（市）、district（區(qū)縣）、street（街道）、streetNum（門牌號）、poiName（POI信息）、postalCode（郵編）、cityCode（城市代碼），如果其中某個字段無法獲取，則返回undefined。

任務(wù)5位置類API

使用getLocation之前需先在manifest.json的“源碼視圖”一欄進行如下黑體配置。否則會報錯：getLocation:failtheapineedtobedeclaredintherequiredPrivateInfosfieldinapp.json/ext.json。

/*小程序特有相關(guān)*/

"mp-weixin":{

"appid":"",

"setting":{

"urlCheck":false

},

"usingComponents":true,

"permission":{

"scope.userLocation":{

"desc":"獲取位置"

}

},

"requiredPrivateInfos":["getLocation"]

任務(wù)5位置類API

getLocation使用示例代碼如下，可獲取當(dāng)前位置經(jīng)緯度、高度、速度等信息。<template> <view> </view></template><scriptsetup> import{onLoad}from'@dcloudio/uni-app' onLoad((option)=>{ uni.getLocation({ type:"gcj02", success:function(res){ console.log(res.longitude) console.log(res.latitude) }, fail:(err)=>{ console.log(err.errMsg) } }) })</script><style></style>

任務(wù)5位置類API

下面結(jié)合地圖組件map使用getLocation獲取當(dāng)前坐標(biāo)并在地圖上標(biāo)記位置。<template> <view> <mapclass="map":markers="markers" :latitude="latitude":longitude="longitude"></map> </view></template>