頁面

Page(Object object)

注册小程序中的一個頁面，接受一個Object類型參數，其指定頁面的初始數據、生命週期回檔、事件處理函數等。

參數

Object object

内容	類型	預設值	必填	說明
data	Object	-	-	頁面的初始數據
onLoad	Object	-	-	生命週期回檔—監聽頁面加載
onShow	Object	-	-	生命週期回檔—監聽頁面顯示
onReady	Object	-	-	生命週期回檔—監聽頁面初次渲染完成
onHide	Object	-	-	生命週期回檔—監聽頁面隱藏
onUnload	Object	-	-	生命週期回檔—監聽頁面卸載
onPullDownRefresh	Object	-	-	監聽用戶下拉動作
onReachBottom	Object	-	-	頁面上拉觸底事件的處理函數
onShareAppMessage	Object	-	-	用戶按一下右上角轉發
onPageScroll	Object	-	-	頁面滾動觸發事件的處理函數
onCustomBack	Object	-	-	開發者攔截頁面的默認返回時回檔
onTabItemTap	Object	-	-	當前是tab頁時，按一下tab時觸發
其他	any	-	-	開發者可以添加任意的函數或數據到Object參數中，在頁面的函數中用this可以訪問，這部分内容會在頁面實例創建時進行一次深拷貝

示例代碼：

//index.js
Page({
  data: {
    text: "This is page data.",
  },
  onLoad: function (options) {
    // Do some initialize when page load.
  },
  onShow: function () {
    // Do something when page show.
  },
  onReady: function () {
    // Do something when page ready.
  },
  onHide: function () {
    // Do something when page hide.
  },
  onUnload: function () {
    // Do something when page close.
  },
  onPullDownRefresh: function () {
    // Do something when pull down.
  },
  onReachBottom: function () {
    // Do something when page reach bottom.
  },
  onShareAppMessage: function () {
    // return custom share data when user share.
  },
  onPageScroll: function () {
    // Do something when page scroll
  },
  onResize: function () {
    // Do something when page resize
  },
  onTabItemTap(item) {
    console.log(item.index);
    console.log(item.pagePath);
    console.log(item.text);
  },
  // Event handler.
  viewTap: function () {
    this.setData(
      {
        text: "Set some data for updating view.",
      },
      function () {
        // this is setData callback
      }
    );
  },
  customData: {
    hi: "MINA",
  },
});

data

data是頁面第一次渲染使用的初始數據。

頁面加載時，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的參數中獲取打開當前頁面路徑中的參數。

參數

名稱	類型	說明
query	Object	打開當前頁面路徑中的參數

onShow()

頁面顯示/切入前臺時觸發

onReady()

頁面初次渲染完成時觸發，一個頁面只會調用一次，代表頁面已經準備妥當，可以和視圖層進行互動。

注意：對介面內容進行設定的API如wx.setNavigationBarTitle ，請在onReady之後進行，詳見生命週期

onHide()

頁面隱藏/切入後臺時觸發，如wx.navigateTo或底部tab切換到其他頁面，小程序切入後臺等。

onUnload()

頁面卸載時觸發，如wx.redirectTo 或 wx.wx.navigateBack到其他頁面時。

頁面事件處理函數

onPullDownRefresh()

監聽用戶下拉刷新事件。

需要在app.json的 window選項中或頁面配置中開啟enablePullDownRefresh；
可以通過 wx.startPullDownRefresh 觸發下拉刷新，調用後觸發下拉刷新動畫，效果與用戶手動下拉刷新一致；
當處理完數據重繪後， wx.startPullDownRefresh 可以停止當前頁面的下拉刷新。

onReachBottom()

監聽用戶上拉觸底事件

可以在app.json的 window 選項中或頁面配置中設定觸發距離onReachBottomDistance；
在觸發距離內滑動期間，本事件只會被觸發一次。

onPageScroll(Object object)

監聽用戶滑動頁面事件

參數 Object object

名稱	類型	說明
scrollTop	Number	頁面在垂直方向已滾動的距離（單位px）

TIP

請只在需要的時候才在page中定義此方法，不要定義空方法。以减少不必要的事件派發對渲染層-邏輯層通信的影響。
請避免在onPageScroll中過於頻繁的執行setData等引起邏輯層-渲染層通信的操作。尤其是每次傳輸大量數據，會影響通信耗時。

onShareAppMessage(Object object)

監聽用戶按一下頁面內轉發按鈕（ button 組件open-type='share'）或右上角選單'轉發'按鈕的行為，並自定義轉發內容。

TIP

只有定義了此事件處理函數，右上角選單才會顯示'轉發'按鈕。

參數Object object:

名稱	類型	說明
from	String	轉發事件來源 - button: 頁面內轉發按鈕； - menu：右上角轉發選單
target	Object	如果from值是button，則target是觸發這次轉發事件的button，否則為undefined
webViewUrl	String	頁面中包含 web-view 組件時，返回當前web-view的url
shareTarget	string	用戶按一下分享到哪裡

此事件處理函數需要return一個Object，用於自定義轉發內容，返回內容如下：

名稱	類型	說明	預設值
title	string	轉發標題	當前小程序名稱
path	string	轉發路徑	當前頁面path，必須是以/開頭的完整路徑
imageUrl	string	自定義圖片路徑，可以是本地文件路徑、代碼包文件路徑或者網絡圖片路徑。支持PNG及JPG。顯示圖片長寬比是5:4	使用默認截圖
entryDataHash	string	監聽用戶按一下頁面內轉發按鈕，只有帶上該參數，才支持快速分享	-
shareType	string	指定分享的類型	"miniapp"

shareTarget參數說明：

當前取值	說明
0	從當前聊天視窗打開，快速分享到當前聊天視窗
1	從當前聊天視窗打開，快速分享到當前聊天視窗
2	分享到Luffa朋友圈
3	分享面板分享到最近聯絡人
4	分享到快捷分享好友列表

shareType參數說明：

用來指定分享的類型，現時分享有兩種，一種是分享小程序，另外一種是分享一張圖片。

值	說明
"miniapp"	以小程序的形式分享，title、path、imageUrl、entryDataHash參數會生效
"picture"	以圖片的形式分享，imageUrl、entryDataHash參數會生效

示例代碼：

Page({
  onShareAppMessage(res) {
    if (res.from === 'button') {
      // From the in-page forwarding button
      console.log(res.target)
    }
    return {
      title: 'Custom Forwarding Title',
      path: '/page/user?id=123'
    }
  }
})

onCustomBack()

監聽用戶返回上一頁事件

需要在app.json的 window選項中或頁面配置中開啟customNavigateBack。
按一下tabBar返回或手勢側滑或back鍵返回均會觸發該事件。

onTabItemTap(Object)

按一下tab時觸發

Object參數說明

參數名	類型	說明
index	String	被按一下tabItem的序號，從0開始
pagePath	String	被按一下tabItem的頁面路徑
text	String	被按一下tabItem的按鈕文字

示例代碼：

Page({
  onTabItemTap(item) {
    console.log(item.index)
    console.log(item.pagePath)
    console.log(item.text)
  }
})

組件事件處理函數

Page中還可以定義組件事件處理函數。在渲染層的組件中加入事件綁定，當事件被觸發時，就會執行Page中定義的事件處理函數。

<view bindtap="viewTap"> click me </view>

Page({
  viewTap: function() {
    console.log('view tap')
  }
})

Page.route

到當前頁面的路徑，類型為String

Page({
  viewTap: function() {
    console.log('view tap')
  }
})

Page.prototype.setData(Object data, Function callback)

setData函數用於將數據從邏輯層發送到渲染層（非同步），同時改變對應的this.data的值（同步）。

參數

欄位	類型	必填	描述
data	Object	是	此次要改變的數據
callback	Function	否	setData引起的介面更新渲染完畢後的回呼函數

Object以key: value的形式表示，將this.data中的key對應的值改變成value

其中key可以以數據路徑的形式給出，支持改變量組中的某一項或對象的某個内容，如array[2].message，a.b.c.d，並且不需要在this.data中預先定義。

TIP

直接修改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>

// index.js
Page({
  data: {
    text: 'init data',
    num: 0,
    array: [{text: 'init data'}],
    object: {
      text: 'init data'
    }
  },
  changeText: function() {
    // this.data.text = 'changed data' // Don't change this.data directly.
    // You should use setData
    this.setData({
      text: 'changed data'
    })
  },
  changeNum: function() {
    // Alternatively, you can modify this.data and then immediately set the modified field with setData.
    this.data.num = 1
    this.setData({
      num: this.data.num
    })
  },
  changeItemInArray: function() {
    // For object or array fields, you can modify a subfield directly under it, which is usually better than modifying the whole object or array.
    this.setData({
      'array[0].text':'changed data'
    })
  },
  changeItemInObject: function(){
    this.setData({
      'object.text': 'changed data'
    });
  },
  addNewField: function() {
    this.setData({
      'newField.text': 'new data'
    })
  }
})

PageObject[] getCurrentPages()

獲取當前頁面棧。數組中第一個元素為首頁，最後一個元素為當前頁面。

注意事項

不要嘗試修改頁面棧，會導致路由以及頁面狀態錯誤
不要在App.onLaunch的時候調用getCurrentPages（），此時page還沒有生成。

頁面 ​

Page(Object object) ​

參數 ​

Object object ​

data ​

生命週期回呼函數 ​

onLoad(Object query) ​

onShow() ​

onReady() ​

onHide() ​

onUnload() ​

頁面事件處理函數 ​

onPullDownRefresh() ​

onReachBottom() ​

onPageScroll(Object object) ​

onShareAppMessage(Object object) ​

onCustomBack() ​

onTabItemTap(Object) ​

Object參數說明 ​

組件事件處理函數 ​

Page.route ​

Page.prototype.setData(Object data, Function callback) ​

PageObject[] getCurrentPages() ​

注意事項 ​

頁面

Page(Object object)

參數

Object object

data

生命週期回呼函數

onLoad(Object query)

onShow()

onReady()

onHide()

onUnload()

頁面事件處理函數

onPullDownRefresh()

onReachBottom()

onPageScroll(Object object)

onShareAppMessage(Object object)

onCustomBack()

onTabItemTap(Object)

Object參數說明

組件事件處理函數

Page.route

Page.prototype.setData(Object data, Function callback)

PageObject[] getCurrentPages()

注意事項