微信小程序 頁(yè)面

Page(Object object)

注冊(cè)小程序中的一個(gè)頁(yè)面。接受一個(gè) Object 類型參數(shù)，其指定頁(yè)面的初始數(shù)據(jù)、生命周期回調(diào)、事件處理函數(shù)等。

參數(shù)

Object object

示例代碼

//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 是頁(yè)面第一次渲染使用的初始數(shù)據(jù)。

頁(yè)面加載時(shí)，data 將會(huì)以JSON字符串的形式由邏輯層傳至渲染層，因此data中的數(shù)據(jù)必須是可以轉(zhuǎn)成JSON的類型：字符串，數(shù)字，布爾值，對(duì)象，數(shù)組。

渲染層可以通過 WXML 對(duì)數(shù)據(jù)進(jìn)行綁定。

示例代碼：

在開發(fā)者工具中預(yù)覽效果

<view>{{text}}</view>
<view>{{array[0].msg}}</view>

Page({
  data: {
    text: 'init data',
    array: [{msg: '1'}, {msg: '2'}]
  }
})

生命周期回調(diào)函數(shù)

生命周期的觸發(fā)以及頁(yè)面的路由方式詳見

onLoad(Object query)

頁(yè)面加載時(shí)觸發(fā)。一個(gè)頁(yè)面只會(huì)調(diào)用一次，可以在 onLoad 的參數(shù)中獲取打開當(dāng)前頁(yè)面路徑中的參數(shù)。

參數(shù)：

onShow()

頁(yè)面顯示/切入前臺(tái)時(shí)觸發(fā)。

onReady()

頁(yè)面初次渲染完成時(shí)觸發(fā)。一個(gè)頁(yè)面只會(huì)調(diào)用一次，代表頁(yè)面已經(jīng)準(zhǔn)備妥當(dāng)，可以和視圖層進(jìn)行交互。

注意：對(duì)界面內(nèi)容進(jìn)行設(shè)置的 API 如wx.setNavigationBarTitle，請(qǐng)?jiān)趏nReady之后進(jìn)行。詳見生命周期

onHide()

頁(yè)面隱藏/切入后臺(tái)時(shí)觸發(fā)。 如 wx.navigateTo 或底部 tab 切換到其他頁(yè)面，小程序切入后臺(tái)等。

onUnload()

頁(yè)面卸載時(shí)觸發(fā)。如wx.redirectTo或wx.navigateBack到其他頁(yè)面時(shí)。

頁(yè)面事件處理函數(shù)

onPullDownRefresh()

監(jiān)聽用戶下拉刷新事件。

• 需要在app.json的window選項(xiàng)中或頁(yè)面配置中開啟enablePullDownRefresh。
• 可以通過wx.startPullDownRefresh觸發(fā)下拉刷新，調(diào)用后觸發(fā)下拉刷新動(dòng)畫，效果與用戶手動(dòng)下拉刷新一致。
• 當(dāng)處理完數(shù)據(jù)刷新后，wx.stopPullDownRefresh可以停止當(dāng)前頁(yè)面的下拉刷新。

onReachBottom()

監(jiān)聽用戶上拉觸底事件。

• 可以在app.json的window選項(xiàng)中或頁(yè)面配置中設(shè)置觸發(fā)距離onReachBottomDistance。
• 在觸發(fā)距離內(nèi)滑動(dòng)期間，本事件只會(huì)被觸發(fā)一次。

onPageScroll(Object object)

監(jiān)聽用戶滑動(dòng)頁(yè)面事件。

參數(shù) Object object:

注意：請(qǐng)只在需要的時(shí)候才在 page 中定義此方法，不要定義空方法。以減少不必要的事件派發(fā)對(duì)渲染層-邏輯層通信的影響。 注意：請(qǐng)避免在 onPageScroll 中過于頻繁的執(zhí)行 setData 等引起邏輯層-渲染層通信的操作。尤其是每次傳輸大量數(shù)據(jù)，會(huì)影響通信耗時(shí)。

onAddToFavorites(Object object)

本接口為 Beta 版本，安卓 7.0.15 版本起支持，暫只在安卓平臺(tái)支持

監(jiān)聽用戶點(diǎn)擊右上角菜單“收藏”按鈕的行為，并自定義收藏內(nèi)容。

參數(shù) Object object:

此事件處理函數(shù)需要 return 一個(gè) Object，用于自定義收藏內(nèi)容：

示例代碼

Page({
  onAddToFavorites(res) {
    // webview 頁(yè)面返回 webviewUrl
    console.log('WebviewUrl: ', res.webviewUrl)
    return {
      title: '自定義標(biāo)題',
      imageUrl: 'http://demo.png',
      query: 'name=xxx&age=xxx',
    }
  }
})

onShareAppMessage(Object object)

監(jiān)聽用戶點(diǎn)擊頁(yè)面內(nèi)轉(zhuǎn)發(fā)按鈕（button 組件 open-type="share"）或右上角菜單“轉(zhuǎn)發(fā)”按鈕的行為，并自定義轉(zhuǎn)發(fā)內(nèi)容。

注意：只有定義了此事件處理函數(shù)，右上角菜單才會(huì)顯示“轉(zhuǎn)發(fā)”按鈕

參數(shù) Object object:

此事件處理函數(shù)需要 return 一個(gè) Object，用于自定義轉(zhuǎn)發(fā)內(nèi)容，返回內(nèi)容如下：

自定義轉(zhuǎn)發(fā)內(nèi)容 基礎(chǔ)庫(kù) 2.8.1 起，分享圖支持云圖片。

示例代碼

在開發(fā)者工具中預(yù)覽效果

Page({
  onShareAppMessage: function (res) {
    if (res.from === 'button') {
      // 來(lái)自頁(yè)面內(nèi)轉(zhuǎn)發(fā)按鈕
      console.log(res.target)
    }
    return {
      title: '自定義轉(zhuǎn)發(fā)標(biāo)題',
      path: '/page/user?id=123'
    }
  }
})

onShareTimeline()

基礎(chǔ)庫(kù) 2.11.3 開始支持，低版本需做兼容處理。

本接口為 Beta 版本，暫只在 Android 平臺(tái)支持，詳見分享到朋友圈 (Beta)

監(jiān)聽右上角菜單“分享到朋友圈”按鈕的行為，并自定義發(fā)享內(nèi)容。

注意：只有定義了此事件處理函數(shù)，右上角菜單才會(huì)顯示“分享到朋友圈”按鈕

自定義轉(zhuǎn)發(fā)內(nèi)容

事件處理函數(shù)返回一個(gè) Object，用于自定義分享內(nèi)容，不支持自定義頁(yè)面路徑，返回內(nèi)容如下：

onResize(Object object)

基礎(chǔ)庫(kù) 2.4.0 開始支持，低版本需做兼容處理。

小程序屏幕旋轉(zhuǎn)時(shí)觸發(fā)。詳見 響應(yīng)顯示區(qū)域變化

onTabItemTap(Object object)

基礎(chǔ)庫(kù) 1.9.0 開始支持，低版本需做兼容處理。

點(diǎn)擊 tab 時(shí)觸發(fā)

Object 參數(shù)說(shuō)明：

示例代碼：

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

組件事件處理函數(shù)

Page 中還可以定義組件事件處理函數(shù)。在渲染層的組件中加入事件綁定，當(dāng)事件被觸發(fā)時(shí)，就會(huì)執(zhí)行 Page 中定義的事件處理函數(shù)。

示例代碼：

在開發(fā)者工具中預(yù)覽效果

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

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

Page.route

基礎(chǔ)庫(kù) 1.2.0 開始支持，低版本需做兼容處理。

到當(dāng)前頁(yè)面的路徑，類型為String。

Page({
  onShow: function() {
    console.log(this.route)
  }
})

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

setData 函數(shù)用于將數(shù)據(jù)從邏輯層發(fā)送到視圖層（異步），同時(shí)改變對(duì)應(yīng)的 this.data 的值（同步）。

參數(shù)說(shuō)明

Object 以 key: value 的形式表示，將 this.data 中的 key 對(duì)應(yīng)的值改變成 value。

其中 key 可以以數(shù)據(jù)路徑的形式給出，支持改變數(shù)組中的某一項(xiàng)或?qū)ο蟮哪硞€(gè)屬性，如 array[2].message，a.b.c.d，并且不需要在 this.data 中預(yù)先定義。

注意：

1. 直接修改 this.data 而不調(diào)用 this.setData 是無(wú)法改變頁(yè)面的狀態(tài)的，還會(huì)造成數(shù)據(jù)不一致。
2. 僅支持設(shè)置可 JSON 化的數(shù)據(jù)。
3. 單次設(shè)置的數(shù)據(jù)不能超過1024kB，請(qǐng)盡量避免一次設(shè)置過多的數(shù)據(jù)。
4. 請(qǐng)不要把 data 中任何一項(xiàng)的 value 設(shè)為 undefined ，否則這一項(xiàng)將不被設(shè)置并可能遺留一些潛在問題。

示例代碼：

在開發(fā)者工具中預(yù)覽效果

<!--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' // 不要直接修改 this.data
    // 應(yīng)該使用 setData
    this.setData({
      text: 'changed data'
    })
  },
  changeNum: function() {
    // 或者，可以修改 this.data 之后馬上用 setData 設(shè)置一下修改了的字段
    this.data.num = 1
    this.setData({
      num: this.data.num
    })
  },
  changeItemInArray: function() {
    // 對(duì)于對(duì)象或數(shù)組字段，可以直接修改一個(gè)其下的子字段，這樣做通常比修改整個(gè)對(duì)象或數(shù)組更好
    this.setData({
      'array[0].text':'changed data'
    })
  },
  changeItemInObject: function(){
    this.setData({
      'object.text': 'changed data'
    });
  },
  addNewField: function() {
    this.setData({
      'newField.text': 'new data'
    })
  }
})

頁(yè)面間通信

基礎(chǔ)庫(kù) 2.7.3 開始支持，低版本需做兼容處理。

如果一個(gè)頁(yè)面由另一個(gè)頁(yè)面通過 wx.navigateTo 打開，這兩個(gè)頁(yè)面間將建立一條數(shù)據(jù)通道：

• 被打開的頁(yè)面可以通過 this.getOpenerEventChannel() 方法來(lái)獲得一個(gè) EventChannel 對(duì)象；
• wx.navigateTo 的 success 回調(diào)中也包含一個(gè) EventChannel 對(duì)象。

這兩個(gè) EventChannel 對(duì)象間可以使用 emit 和 on 方法相互發(fā)送、監(jiān)聽事件。

PageObject[] getCurrentPages()

獲取當(dāng)前頁(yè)面棧。數(shù)組中第一個(gè)元素為首頁(yè)，最后一個(gè)元素為當(dāng)前頁(yè)面。

注意：

• 不要嘗試修改頁(yè)面棧，會(huì)導(dǎo)致路由以及頁(yè)面狀態(tài)錯(cuò)誤。
• 不要在 App.onLaunch 的時(shí)候調(diào)用 getCurrentPages()，此時(shí) page 還沒有生成。