註冊小程序中的一個頁面。接受一個 Object 類型參數,其指定頁面的初始數據、生命周期回調、事件處理函數等。
參數Object object屬性類型默認值必填說明dataObjectPage({ data: { text: "This is page data." }, onLoad: function(options) { }, onShow: function() { }, onReady: function() { }, onHide: function() { }, onUnload: function() { }, onPullDownRefresh: function() { }, onReachBottom: function() { }, onShareAppMessage: function () { }, onPageScroll: function() { }, onResize: function() { }, onTabItemTap(item) { console.log(item.index) console.log(item.pagePath) console.log(item.text) }, viewTap: function() { this.setData({ text: 'Set some data for updating view.' }, function() { }) }, customData: { hi: 'MINA' }})datadata 是頁面第一次渲染使用的初始數據。
頁面加載時,data 將會以JSON字符串的形式由邏輯層傳至渲染層,因此data中的數據必須是可以轉成JSON的類型:字符串,數字,布爾值,對象,數組。
渲染層可以通過 WXML 對數據進行綁定。
示例代碼:
在開發者工具中預覽效果
<view>{{text}}</view><view>{{array[0].msg}}</view>
Page({ data: { text: 'init data', array: [{msg: '1'}, {msg: '2'}] }})生命周期回調函數生命周期的觸發以及頁面的路由方式詳見
onLoad(Object query)頁面加載時觸發。一個頁面只會調用一次,可以在 onLoad 的參數中獲取打開當前頁面路徑中的參數。
參數:
名稱類型說明queryObject打開當前頁面路徑中的參數onShow()頁面顯示/切入前臺時觸發。
onReady()頁面初次渲染完成時觸發。一個頁面只會調用一次,代表頁面已經準備妥當,可以和視圖層進行交互。
注意:對界面內容進行設置的 API 如wx.setNavigationBarTitle,請在onReady之後進行。詳見生命周期
onHide()頁面隱藏/切入後臺時觸發。如 wx.navigateTo 或底部 tab 切換到其他頁面,小程序切入後臺等。
onUnload()頁面卸載時觸發。如wx.redirectTo或wx.navigateBack到其他頁面時。
頁面事件處理函數onPullDownRefresh()監聽用戶下拉刷新事件。
需要在app.json的window選項中或頁面配置中開啟enablePullDownRefresh。
可以通過wx.startPullDownRefresh觸發下拉刷新,調用後觸發下拉刷新動畫,效果與用戶手動下拉刷新一致。
當處理完數據刷新後,wx.stopPullDownRefresh可以停止當前頁面的下拉刷新。
onReachBottom()監聽用戶上拉觸底事件。
onPageScroll(Object object)監聽用戶滑動頁面事件。
參數 Object object:
屬性類型說明scrollTopNumber頁面在垂直方向已滾動的距離(單位px)注意:請只在需要的時候才在 page 中定義此方法,不要定義空方法。以減少不必要的事件派發對渲染層-邏輯層通信的影響。 注意:請避免在 onPageScroll 中過於頻繁的執行 setData 等引起邏輯層-渲染層通信的操作。尤其是每次傳輸大量數據,會影響通信耗時。
onAddToFavorites(Object object)本接口為 Beta 版本,安卓 7.0.15 版本起支持,暫只在安卓平臺支持監聽用戶點擊右上角菜單「收藏」按鈕的行為,並自定義收藏內容。
參數 Object object:
參數類型說明webviewUrlString頁面中包含web-view組件時,返回當前web-view的url此事件處理函數需要 return 一個 Object,用於自定義收藏內容:
欄位說明默認值title自定義標題頁面標題或帳號名稱imageUrl自定義圖片,顯示圖片長寬比為 1:1頁面截圖query自定義query欄位當前頁面的query示例代碼
Page({ onAddToFavorites(res) { console.log('WebviewUrl: ', res.webviewUrl) return { title: '自定義標題', imageUrl: 'http://demo.png', query: 'name=xxx&age=xxx', } }})onShareAppMessage(Object object)監聽用戶點擊頁面內轉發按鈕(button 組件 open-type="share")或右上角菜單「轉發」按鈕的行為,並自定義轉發內容。
注意:只有定義了此事件處理函數,右上角菜單才會顯示「轉發」按鈕
參數 Object object:
參數類型說明最低版本fromString轉發事件來源。
button:頁面內轉發按鈕;
menu:右上角轉髮菜單1.2.4targetObject如果 from 值是 button,則 target 是觸發這次轉發事件的 button,否則為 undefined1.2.4webViewUrlString頁面中包含web-view組件時,返回當前web-view的url1.6.4此事件處理函數需要 return 一個 Object,用於自定義轉發內容,返回內容如下:
自定義轉發內容 基礎庫 2.8.1 起,分享圖支持雲圖片。
欄位說明默認值最低版本title轉發標題當前小程序名稱
path轉發路徑當前頁面 path ,必須是以 / 開頭的完整路徑
imageUrl自定義圖片路徑,可以是本地文件路徑、代碼包文件路徑或者網絡圖片路徑。支持PNG及JPG。顯示圖片長寬比是 5:4。使用默認截圖1.5.0示例代碼
在開發者工具中預覽效果
Page({ onShareAppMessage: function (res) { if (res.from === 'button') { // 來自頁面內轉發按鈕 console.log(res.target) } return { title: '自定義轉發標題', path: '/page/user?id=123' } }})onShareTimeline()基礎庫 2.11.3 開始支持,低版本需做兼容處理。本接口為 Beta 版本,暫只在 Android 平臺支持,詳見分享到朋友圈 (Beta)監聽右上角菜單「分享到朋友圈」按鈕的行為,並自定義發享內容。
注意:只有定義了此事件處理函數,右上角菜單才會顯示「分享到朋友圈」按鈕
自定義轉發內容
事件處理函數返回一個 Object,用於自定義分享內容,不支持自定義頁面路徑,返回內容如下:
欄位說明默認值最低版本title自定義標題,即朋友圈列表頁上顯示的標題當前小程序名稱
query自定義頁面路徑中攜帶的參數,如 path?a=1&b=2 的 「?」 後面部分當前頁面路徑攜帶的參數
imageUrl自定義圖片路徑,可以是本地文件或者網絡圖片。支持 PNG 及 JPG,顯示圖片長寬比是 1:1。默認使用小程序 Logo
onResize(Object object)基礎庫 2.4.0 開始支持,低版本需做兼容處理。小程序屏幕旋轉時觸發。詳見 響應顯示區域變化
onTabItemTap(Object object)基礎庫 1.9.0 開始支持,低版本需做兼容處理。點擊 tab 時觸發
Object 參數說明:
參數類型說明最低版本indexString被點擊tabItem的序號,從0開始1.9.0pagePathString被點擊tabItem的頁面路徑1.9.0textString被點擊tabItem的按鈕文字1.9.0示例代碼:
Page({ onTabItemTap(item) { console.log(item.index) console.log(item.pagePath) console.log(item.text) }})組件事件處理函數Page 中還可以定義組件事件處理函數。在渲染層的組件中加入事件綁定,當事件被觸發時,就會執行 Page 中定義的事件處理函數。
示例代碼:
在開發者工具中預覽效果
<view bindtap="viewTap"> click me </view>
Page({
Page.route基礎庫 1.2.0 開始支持,低版本需做兼容處理。
viewTap: function() {
console.log('view tap')
}
})到當前頁面的路徑,類型為String。
Page({
Page.prototype.setData(Object data, Function callback)
onShow: function() {
console.log(this.route)
}
})setData 函數用於將數據從邏輯層發送到視圖層(異步),同時改變對應的 this.data 的值(同步)。
參數說明欄位類型必填描述最低版本dataObject是這次要改變的數據
callbackFunction否setData引起的界面更新渲染完畢後的回調函數1.5.0Object 以 key: value 的形式表示,將 this.data 中的 key 對應的值改變成 value。
其中 key 可以以數據路徑的形式給出,支持改變數組中的某一項或對象的某個屬性,如 array[2].message,a.b.c.d,並且不需要在 this.data 中預先定義。
注意:
直接修改 this.data 而不調用 this.setData 是無法改變頁面的狀態的,還會造成數據不一致。
僅支持設置可 JSON 化的數據。
單次設置的數據不能超過1024kB,請儘量避免一次設置過多的數據。
請不要把 data 中任何一項的 value 設為 undefined ,否則這一項將不被設置並可能遺留一些潛在問題。
示例代碼:
在開發者工具中預覽效果
<!--index.wxml--><view>{{text}}</view><button bindtap="changeText"> Change normal data </button><view>{{num}}</view><button bindtap="changeNum"> Change normal num </button><view>{{array[0].text}}</view><button bindtap="changeItemInArray"> Change Array data </button><view>{{object.text}}</view><button bindtap="changeItemInObject"> Change Object data </button><view>{{newField.text}}</view><button bindtap="addNewField"> Add new data </button>
Page({ data: { text: 'init data', num: 0, array: [{text: 'init data'}], object: { text: 'init data' } }, changeText: function() { this.setData({ text: 'changed data' }) }, changeNum: function() { this.data.num = 1 this.setData({ num: this.data.num }) }, changeItemInArray: function() { this.setData({ 'array[0].text':'changed data' }) }, changeItemInObject: function(){ this.setData({ 'object.text': 'changed data' }); }, addNewField: function() { this.setData({ 'newField.text': 'new data' }) }})頁面間通信基礎庫 2.7.3 開始支持,低版本需做兼容處理。如果一個頁面由另一個頁面通過 wx.navigateTo 打開,這兩個頁面間將建立一條數據通道:
這兩個 EventChannel 對象間可以使用 emit 和 on 方法相互發送、監聽事件。
PageObject[] getCurrentPages()獲取當前頁面棧。數組中第一個元素為首頁,最後一個元素為當前頁面。
注意: