小程序原生 API

微信原生 API

1. API 基礎

小程序開發框架提供豐富的微信原生 API，可以方便的調起微信提供的能力，如獲取用戶信息，本地存儲，支付功能等，幾乎所有小程序的 API 都掛載在 wx 對象底下，例如：wx.chooseMedia()、wx.request(), wx 對象實際上就是小程序的宿主環境微信所提供的全局對象

通常，在小程序 API 有以下幾種類型：

事件監聽 API：約定以 on 開頭 API 用來監聽某個事件是否觸發，例如：wx.onThemeChange()
同步 API：約定以 Sync 結尾的 API 都是同步 API，例如：wx.setStorageSync()
異步 API：大多數 API 都是異步 API，例如：wx.setStorage()

異步 API 支持 callback & Promise 兩種調用方式：

當接口參數 Object 對象中不包含 success/fail/complete 時將默認返回 Promise
部分接口如 request, uploadFile 本身就有返回值，因此不支持 Promise 風格的調用方式，它們的 promisify 需要開發者自行封裝。

小程序 API 介紹

微信小程序 API 文檔

2. 網絡請求

知識點：

在微信小程序中，如果需要發起 HTTPS 網絡請求需要使用：wx.request()，語法如下：

wx.request({// 接口地址，僅為示例，并非真實的接口地址url: 'example.php',// 請求的參數data: { x: '' },// 請求方式method: 'GET|POST|PUT|DELETE',success (res) {console.log(res.data)},fail(err) {console.log(err)}
})

注意：wx.request() 請求的域名需要在小程序管理平臺進行配置，如果小程序正式版使用wx.request請求未配置的域名，在控制臺會有相應的報錯。

這時候就需要在小程序管理后臺進行設置請求的域名，打開微信公眾后臺：點擊左側開發 → 開發管理 → 開發設置 → 服務器域名。域名只支持 https 而且要求已備案

但一般我們在開發階段時，處于開發階段的服務器接口可能還沒部署到對應的域名下，經常會通過另一個域名來進行開發調試，考慮到這一點，為了方便開發者進行開發調試，開發者工具、小程序的開發版和小程序的體驗版在某些情況下允許 wx.request 請求任意域名 (只適用于開發環境，只能在小程序開發者工具中生效)，在開發工具中設置步驟如下：

將 不校驗合法域名、web-view (業務域名)、TLS版本以及HTTPS證書 勾選上：

📌 注意事項：

? 這兩種方式只適用于開發者工具、小程序的開發版和小程序的體驗版

? 項目上線前必須在小程序管理平臺進行合法域名的配置

落地代碼：

Page({// 頁面的初始數據data: {},// 獲取數據getPostInfo() {wx.request({url: 'https://jsonplaceholder.typicode.com/posts/1',method: 'GET',success(res) {console.log(res)},fail(err) {console.log(err)}})},// coding...
}

3. 界面交互

小程序還提供了一些用于界面交互的 API，如消息提示框、模態對話框、 loading 提示框等等

3.1 loading 提示框

知識點：

小程序提供了一些用于界面交互的 API，例如： loading 提示框、消息提示框、模態對話框等 API。

loading 提示框常配合網絡請求來使用，用于增加用戶體驗，對應的 API 有兩個：

wx.showLoading 顯示加載提示框
wx.hideLoading 隱藏加載提示框

語法如下：

wx.showLoading({title: '提示內容', // 提示的內容mask: true, // 是否顯示透明蒙層，防止觸摸穿透success() {}, // 接口調用成功的回調函數fail() {} // 接口調用失敗的回調函數
})

官方文檔：

wx.showLoading 官方文檔

wx.hideLoading 官方文檔

落地代碼：

Page({data: {list: []},// 獲取數據getData () {+     // 顯示 loading 提示框
+     wx.showLoading({
+       // 用來顯示提示的內容
+       // 提示的內容不會自動換行，如果提示的內容比較多，因為在同一行展示
+       // 多出來的內容就會被隱藏
+       title: '數據加載中...',
+       // 是否展示透明蒙層，防止觸摸穿透
+       mask: true
+     })// 如果需要發起網絡請求，需要使用 wx.request APIwx.request({// 接口地址url: 'https://gmall-prod.atguigu.cn/mall-api/index/findBanner',// 請求方式method: 'GET',// 請求參數data: {},// 請求頭header: {},// API 調用成功以后，執行的回調success: (res) => {// console.log(res)if (res.data.code === 200) {this.setData({list: res.data.data})}},// API 調用失敗以后，執行的回調fail: (err) => {console.log(err)},// API 不管調用成功還是失敗以后，執行的回調complete: (res) => {// console.log(res)+         // 關掉 loading 提示框
+         // hideLoading 和 showLoading 必須結合、配對使用才可以
+         wx.hideLoading()}})}})

3.2 模態對話框以及消息提示框

知識點：

wx.showToast()：消息提示框用來根據用戶的某些操作來告知操作的結果，如退出成功給用戶提示，提示刪除成功等，語法如下：

wx.showToast({title: '標題', // 提示的內容duration: 2000, // 提示的延遲時間mask: true, // 是否顯示透明蒙層，防止觸摸穿透icon: 'success', // 	圖標success() {}, // 接口調用成功的回調函數fail() {} // 接口調用失敗的回調函數
})

wx.showModal() 模態對話框也是在項目中頻繁使用的一個小程序 API，通常用于向用戶詢問是否執行一些操作，例如：點擊退出登錄，顯示模態對話框，詢問用戶是否真的需要退出等等

wx.showModal({title: '提示', // 提示的標題content: '您確定執行該操作嗎？', // 提示的內容confirmColor: '#f3514f',// 接口調用結束的回調函數（調用成功、失敗都會執行）success({ confirm }) {confirm && consle.log('點擊了確定')}
})

官方文檔：

wx.showToast 官方文檔

wx.showModal 官方文檔

落地代碼：

Page({// coding...// 刪除商品async delHandler () {// showModal 顯示模態對話框const { confirm } = await wx.showModal({title: '提示',content: '是否刪除該商品 ?'})if (confirm) {// showToast 消息提示框wx.showToast({title: '刪除成功',icon: 'none',duration: 2000})} else {wx.showToast({title: '取消刪除',icon: 'error',duration: 2000})}}// coding...})

4. 本地存儲

小程序中也能夠像網頁一樣支持本地數據緩存，本地數據緩存是小程序存儲在當前設備上硬盤上的數據，本地數據緩存有非常多的用途，我們可以利用本地數據緩存來存儲用戶在小程序上產生的操作，在用戶關閉小程序重新打開時可以恢復之前的狀態。我們還可以利用本地緩存一些服務端非實時的數據提高小程序獲取數據的速度，在特定的場景下可以提高頁面的渲染速度，減少用戶的等待時間。其包含以下 8個主要的 API

同步 API	異步 API	作用
`wx.setStorageSync`	`wx.setStorage`	將數據存儲在本地緩存中指定的 key 中
`wx.getStorageSync`	`wx.getStorage`	從本地緩存中同步獲取指定 key 的內容
`wx.removeStorageSync`	`wx.removeStorage`	從本地緩存中移除指定 key
`wx.clearStorageSync`	`wx.clearStorageSync`	清理本地數據緩存

異步方式的 API，在調用的時候都需要傳入對象類型的參數

同步方式執行的 API 在使用時簡潔比較好，缺點是同步會阻塞程序執行，執行效率上相較異步版本要差一些。

📌 注意事項：

對象類型的數據，可以直接進行存儲，無需使用 JSON.stringify 轉換
對象類型的數據存的時候沒有使用轉換，因此獲取的時候也不需要使用 JSON.parse 轉換

落地代碼：

<button type="primary" bindtap="handler" size="mini" plain bindtap="setData">存儲數據
</button><button type="primary" bindtap="handler" size="mini" plain bindtap="getData">獲取數據
</button><button type="warn" bindtap="handler" size="mini" plain bindtap="delData">刪除數據
</button><button type="warn" bindtap="handler" size="mini" plain bindtap="clearData">移除數據
</button>

Page({// 將數據存儲到本地setStorage () {// 第一個參數：本地存儲中指定的 key// 第二個參數：需要存儲的數據// wx.setStorageSync('num', 1)// 在小程序中// 如果存儲的是對象類型數據，不需要使用 JSON.stringify 和 JSON.parse 進行轉換// 直接進行存儲和獲取即可// wx.setStorageSync('obj', { name: 'tom', age: 10 })// ------------------- 異步 API -------------------wx.setStorage({key: 'num',data: 1})wx.setStorage({key: 'obj',data: { name: 'jerry', age: 18 }})},// 獲取本地存儲的數據async getStorage () {// 從本地存儲的數據中獲取指定 key 的數據、內容// const num = wx.getStorageSync('num')// const obj = wx.getStorageSync('obj')// console.log(num)// console.log(obj)// ------------------- 異步 API -------------------const { data } = await wx.getStorage({key: 'obj'})console.log(data)},// 刪除本地存儲的數據removeStorage () {// 從本地移除指定 key 的數據、內容// wx.removeStorageSync('num')// ------------------- 異步 API -------------------wx.removeStorage({key: 'num'})},// 清空本地存儲的全部數據clearStorage () {// wx.clearStorageSync()// ------------------- 異步 API -------------------wx.clearStorage()},})

5. 路由與通信

知識點：

在小程序中實現頁面的跳轉，有兩種方式：

聲明式導航：navigator 組件
編程式導航：使用小程序提供的 API
- wx.navigateTo()：保留當前頁面，跳轉到應用內的某個頁面，但是不能跳到 tabbar 頁面
- wx.redirectTo()：關閉當前頁面，跳轉到應用內的某個頁面。但是不允許跳轉到 tabbar 頁面
- wx.switchTab()：跳轉到 tabBar 頁面，路徑后不能帶參數
- wx.navigateBack()：關閉當前頁面，返回上一頁面或多級頁面
路徑后可以帶參數，參數需要在跳轉到的頁面的 onLoad 鉤子函數中通過形參進行接收
- 參數與路徑之間使用 ? 分隔
- 參數鍵與參數值用 = 相連
- 不同參數用 & 分隔
- 例如 path?key=value&key2=value2

落地代碼：

Page({navigateTo() {// 保留當前頁面，跳轉到應用中其他頁面，不能跳轉到 tabBar 頁面wx.navigateTo({url: '/pages/list/list?id=1&name=tom'// url: '/pages/cate/cate'})},redirectTo() {// 關閉(銷毀)當前頁面，跳轉到應用中其他頁面，不能跳轉到 tabBar 頁面wx.redirectTo({url: '/pages/list/list?id=1&name=tom'// url: '/pages/cate/cate'})},switchTab() {// 跳轉到 tabBar 頁面，不能跳轉到 非 tabBar 頁面，路徑后面不能傳遞參數wx.switchTab({// url: '/pages/list/list'url: '/pages/cate/cate?id=1&name=tom'})},reLaunch() {// 關閉所有的頁面，然后跳轉到應用中某一個頁面wx.reLaunch({url: '/pages/list/list?id=1&name=tom'// url: '/pages/cate/cate?id=1&name=tom'})}})

// list.js
Page({navigateBack() {// 關閉當前頁面，返回上一頁或者返回多級頁面// 默認返回上一頁wx.navigateBack({delta: 1})},onLoad(options) {console.log(options)}})

6. 事件監聽-上拉加載更多

上拉加載是小程序中常見的一種加載方式，當用戶滑動頁面到底部時，會自動加載更多的內容，以便用戶繼續瀏覽

小程序中實現上拉加載的方式：

1.在 app.json 或者 page.json 中配置距離頁面底部距離： onReachBottomDistance；默認 50px

2.在頁面.js 中定義 onReachBottom 事件監聽用戶上拉加載

落地代碼：

<view wx:for="{{ numList }}" wx:key="*this">{{ item }}</view>

/* pages/market/market.wxss */view {height: 400rpx;display: flex;align-items: center;justify-content: center;
}view:nth-child(odd) {background-color: lightskyblue;
}view:nth-child(even) {background-color: lightsalmon;
}

Page({data: {numList: [1, 2, 3]},// 監聽用戶上拉加載onReachBottom() {// console.log('監聽用戶上拉加載')// 產品需求：// 當用戶上拉，需要數字進行累加// 當用戶上拉加載時，需要對數字進行累加，每次累加 3 個數字// 目前是 [1, 2, 3]，[1, 2, 3, 4, 5, 6]// 怎么進行追加 ？// 獲取目前數組中最后一項 n，n + 1, n + 2, n + 3wx.showLoading({title: '數據加載中...'})setTimeout(() => {// 獲取數組的最后一項const lastNum = this.data.numList[this.data.numList.length - 1]// 定義需要追加的元素const newArr = [lastNum + 1, lastNum + 2, lastNum + 3]this.setData({numList: [...this.data.numList, ...newArr]})wx.hideLoading()}, 1500)}})

7. 事件監聽-下拉刷新

下拉刷新是小程序中常見的一種刷新方式，當用戶下拉頁面時，頁面會自動刷新，以便用戶獲取最新的內容。

小程序中實現上拉加載更多的方式：

1.在 app.json 或者 page.json 中開啟允許下拉，同時可以配置窗口、loading 樣式等

2.在頁面.js 中定義 onPullDownRefresh 事件監聽用戶下拉刷新

落地代碼：

<view wx:for="{{ numList }}" wx:key="*this">{{ item }}</view>

/* pages/market/market.wxss */view {height: 400rpx;display: flex;align-items: center;justify-content: center;
}view:nth-child(odd) {background-color: lightskyblue;
}view:nth-child(even) {background-color: lightsalmon;
}

Page({data: {numList: [1, 2, 3]},// 監聽用戶上拉加載onReachBottom() {// coding...},// 監聽用戶下拉刷新onPullDownRefresh () {// console.log('監聽用戶下拉刷新')// 產品需求：// 當用戶上拉加載更多以后，如果用戶進行了下拉刷新// 需要將數據進行重置this.setData({numList: [1, 2, 3]})// 在下拉刷新以后，loading 效果有可能不會回彈回去if (this.data.numList.length === 3) {wx.stopPullDownRefresh()}}})

8. 增強 scroll-view

8.1 scroll-view 上拉加載

知識點：

bindscrolltolower：滾動到底部/右邊時觸發

lower-threshold：距底部/右邊多遠時，觸發 scrolltolower 事件

enable-back-to-top：讓滾動條返回頂部，iOS 點擊頂部狀態欄、安卓雙擊標題欄時，只支持豎向

落地代碼：

<scroll-viewclass="scroll-y"scroll-ylower-threshold="100"bindscrolltolower="getMore"enable-back-to-top
><view wx:for="{{ arr }}" wx:key="*this">{{ item }}</view></scroll-view>

// index.js
Page({data: {arr: [1, 2, 3]},// 上拉加載更多getMore() {wx.showLoading({title: '數據正在加載中...'})setTimeout(() => {// 記錄當前數組的最后一個元素let lastNum = this.data.arr[this.data.arr.length - 1]// 最后一個元素加 1lastNum++// 每次向數組中新增三項const newArr = [lastNum, lastNum + 1, lastNum + 2]this.setData({arr: [...this.data.arr, ...newArr]})// 數據返回，隱藏 Loadingwx.hideLoading()wx.showToast({title: '數字請求完畢，上滑繼續瀏覽',icon: 'none'})}, 1000)}
})

8.2 scroll-view 下拉刷新

知識點：

refresher-enabled：開啟自定義下拉刷新

refresher-default-style自定義下拉刷新默認樣式支持設置 black | white | none， none 表示不使用默認樣式

refresher-background：自定義下拉刷新區域背景顏色

bindrefresherrefresh：自定義下拉刷新狀態回調

refresher-triggered：設置當前下拉刷新狀態，(true 下拉刷新被觸發，false 表示下拉刷新未被觸發，用來關閉下拉效果)

落地代碼：

<scroll-viewclass="scroll-y"scroll-ylower-threshold="100"bindscrolltolower="getMore"enable-back-to-toprefresher-enabledrefresher-default-style="black"refresher-background="#f7f7f8"refresher-triggeredbindrefresherrefresh="onrefresh"refresher-triggered="{{ triggered }}"
><view wx:for="{{ arr }}" wx:key="*this">{{ item }}</view></scroll-view>

// index.js
Page({data: {triggered: false, // 控制 scroll-view 下拉刷新效果arr: [1, 2, 3]},// scroll-view 下拉刷新回調函數onrefresh() {wx.showLoading({title: '數據正在加載中...'})// 定時器模擬網絡請求，1 秒后數據返回setTimeout(() => {// 重置數據this.setData({arr: [1, 2, 3]})// 數據返回，隱藏 Loadingwx.hideLoading()wx.showToast({title: '下拉刷新完成，數據已重置...',icon: 'none'})// 數據返回，關閉 scroll-view 下拉刷新效果this.setData({triggered: false})}, 1000)}
})

8.3 增強 scroll-view 完整代碼

<scroll-viewscroll-yclass="scroll-y"lower-threshold="100"bindscrolltolower="getMore"enable-back-to-toprefresher-enabledrefresher-default-style="black"refresher-background="#f7f7f8"bindrefresherrefresh="refreshHandler"refresher-triggered="{{isTriggered}}"
><view wx:for="{{ numList }}" wx:key="*this">{{ item }}</view></scroll-view>

/* pages/index/index.wxss */.scroll-y {height: 100vh;background-color: #efefef;
}view {height: 500rpx;display: flex;align-items: center;justify-content: center;
}view:nth-child(odd) {background-color: skyblue;
} view:nth-child(even) {background-color: lightsalmon;
}

Page({data: {numList: [1, 2, 3],isTriggered: false},// 下拉刷新refreshHandler () {wx.showToast({title: '下拉刷新...'})setTimeout(() => {this.setData({numList: [1, 2, 3],isTriggered: false})}, 2000)},// scroll-view 上拉加載更多事件的事件處理函數getMore () {wx.showLoading({title: '數據加載中...'})setTimeout(() => {// 獲取數組的最后一項const lastNum = this.data.numList[this.data.numList.length - 1]// 定義需要追加的元素const newArr = [lastNum + 1, lastNum + 2, lastNum + 3]this.setData({numList: [...this.data.numList, ...newArr]})wx.hideLoading()}, 1500)}})