全部产品
云市场
云游戏

页面注册

更新时间:2019-09-09 15:14:14

Page(object: Object)

/pages 目录的 .js 文件中定义 Page(),用于注册一个小程序页面,接受一个 object 作为属性,用来指定页面的初始数据、生命周期回调、事件处理等信息。

以下为一个基本的页面代码:

  1. // pages/index/index.js
  2. Page({
  3. data: {
  4. title: "Alipay",
  5. },
  6. onLoad(query) {
  7. // 页面加载
  8. },
  9. onShow() {
  10. // 页面显示
  11. },
  12. onReady() {
  13. // 页面加载完成
  14. },
  15. onHide() {
  16. // 页面隐藏
  17. },
  18. onUnload() {
  19. // 页面被关闭
  20. },
  21. onTitleClick() {
  22. // 标题被点击
  23. },
  24. onPullDownRefresh() {
  25. // 页面被下拉
  26. },
  27. onReachBottom() {
  28. // 页面被拉到底部
  29. },
  30. onShareAppMessage() {
  31. // 返回自定义分享信息
  32. },
  33. // 事件处理函数对象
  34. events: {
  35. onBack() {
  36. console.log('onBack');
  37. },
  38. },
  39. // 自定义事件处理函数
  40. viewTap() {
  41. this.setData({
  42. text: 'Set data for update.',
  43. });
  44. },
  45. // 自定义事件处理函数
  46. go() {
  47. // 带参数的跳转,从 page/ui/index 的 onLoad 函数的 query 中读取 type
  48. my.navigateTo({url:'/page/ui/index?type=mini'});
  49. },
  50. // 自定义数据对象
  51. customData: {
  52. name: 'alipay',
  53. },
  54. });

页面生命周期

下图说明了页面 Page 对象的生命周期。

小程序主要靠视图线程(Webview)和应用服务线程(Worker)来控制管理。视图线程和应用服务线程同时运行。

  1. 应用服务线程启动后运行 app.onLauchapp.onShow 以完成 App 创建,再运行 page.onLoadpage.onShow 以完成 Page 创建,此时等待视图线程初始化完成通知。
  2. 视图线程初始化完成通知应用服务线程,应用服务线程将初始化数据发送给视图线程进行渲染,此时视图线程完成第一次数据渲染。
  3. 第一次渲染完成后视图线程进入就绪状态并通知应用服务线程,应用服务线程调用 page.onReady 函数并进入活动状态。
  4. 应用线程进入活动状态后每次数据修改将会通知视图线程进行渲染。
    • 当切换页面进入后台,应用线程调用 page.onHide 函数后,进入存活状态。
    • 页面返回到前台将调用 page.onShow 函数,进入活动状态。
    • 当调用返回或重定向页面后将调用 page.onUnload 函数,进行页面销毁。

object 属性说明

属性 类型 描述 最低版本
data Object | Function 初始数据或返回初始化数据的函数
events Object 事件处理函数对象 1.13.7
onLoad Function(query: Object) 页面加载时触发
onShow Function 页面显示时触发
onReady Function 页面初次渲染完成时触发
onHide Function 页面隐藏时触发
onUnload Function 页面卸载时触发
onShareAppMessage Function(options: Object) 点击右上角分享时触发
onTitleClick Function 点击标题触发
onOptionMenuClick Function 点击导航栏额外图标触发 1.3.0
onPopMenuClick Function 1.3.0
onPullDownRefresh Function({from: manual|code}) 页面下拉时触发
onPullIntercept Function 下拉中断时触发 1.11.0
onTabItemTap Function 点击tabItem时触发 1.11.0
onPageScroll Function({scrollTop}) 页面滚动时触发
onReachBottom Function 上拉触底时触发
其他 Any 开发者可以添加任意的函数或属性到 object 中,在页面的函数中可以用 this 来访问。

页面数据对象 data

通过设置 data 指定页面的初始数据。当 data 为对象时,被所有页面共享。即:当该页面回退后再次进入该页面时,会显示上次页面的数据,而非初始数据。对于这种情况,可以通过以下两种方式解决:

  • 设置 data 为不可变数据:

    1. Page({
    2. data: { arr:[] },
    3. doIt() {
    4. this.setData({arr: [...this.data.arr, 1]});
    5. },
    6. });
    说明:不要直接修改 this.data,这样做不仅无法改变页面的状态,还会造成数据不一致。

    例如以下错误示例:

    1. Page({
    2. data: { arr:[] },
    3. doIt() {
    4. this.data.arr.push(1); // 不要这么写!
    5. this.setData({arr: this.data.arr});
    6. }
    7. });
  • 设置 data 为页面独有数据(不推荐):
    1. Page({
    2. data() { return { arr:[] }; },
    3. doIt() {
    4. this.setData({arr: [1, 2, 3]});
    5. },
    6. });

生命周期函数

onLoad(query: Object)

页面加载时触发。一个页面只会调用一次。querymy.navigateTomy.redirectTo 中传递的 query 对象。

属性 类型 描述 最低版本
query Object 打开当前页面路径中的参数。

onShow()

页面显示/切入前台时触发。

onReady()

页面初次渲染完成时触发。一个页面只会调用一次,代表页面已经准备妥当,可以和视图层进行交互。

对界面的设置,如 my.setNavigationBar,需在 onReady 之后设置。

onHide()

页面隐藏/切入后台时触发。如 my.navigateTo 到其他页面或底部 tab 切换等。

onUnload()

页面卸载时触发。如 my.redirectTomy.navigateBack 到其他页面等。

页面事件处理函数

onShareAppMessage(options: Object)

点击右上角通用菜单中的分享按钮时或点击页面内分享按钮时触发。详见 分享

onTitleClick()

点击标题触发。

onOptionMenuClick()

点击右上角菜单按钮时触发。

onPopMenuClick()

点击右上角通用菜单按钮时触发。

onPullDownRefresh({from: manual | code})

下拉刷新时触发。需要先在 app.jsonwindow 选项中开启 pullRefresh 。当处理完数据刷新后,my.stopPullDownRefresh 可以停止当前页面的下拉刷新。

onPullIntercept()

下拉中断时触发。

onTabItemTap(object: Object)

点击tabItem时触发。

属性 类型 描述 最低版本
from String 点击来源
pagePath String 被点击 tabItem 的页面路径
text String 被点击 tabItem 的按钮文字
index Number 被点击 tabItem 的序号,从 0 开始

onPageScroll({scrollTop})

页面滚动时触发。scrollTop 为页面滚动距离。

onReachBottom()

上拉触底时触发。

events

说明:为了使代码更加简洁,提供了新的事件处理对象 events。原同名事件跟直接在 page 实例上暴露的事件函数等价。events 从 1.13.7 开始支持。
事件 类型 描述 最低版本
onBack Function 页面返回时触发 1.13.7
onKeyboardHeight Function 键盘高度变化时触发 1.13.7
onOptionMenuClick Function 点击右上角菜单按钮触发 1.13.7
onPopMenuClick Function 点击右上角通用菜单按钮触发 1.13.7
onPullIntercept Function 下拉截断时触发 1.13.7
onPullDownRefresh Function({from: manual|code}) 页面下拉时触发 1.13.7
onTitleClick Function 点击标题触发 1.13.7
onTabItemTap Function 点击且切换tabItem后触发 1.13.7
beforeTabItemTap Function 点击但切换tabItem前触发 1.13.7

示例代码:

  1. Page({
  2. data: {
  3. text: 'This is page data.'
  4. },
  5. onLoad(){
  6. // 设置自定义菜单
  7. my.setCustomPopMenu({
  8. menus:[
  9. {name: '菜单1', menuIconUrl: 'https://menu1'},
  10. {name: '菜单2', menuIconUrl: 'https://menu2'},
  11. ],
  12. })
  13. },
  14. events:{
  15. onBack(){
  16. // 页面返回时触发
  17. },
  18. onKeyboardHeight(e){
  19. // 键盘高度变化时触发
  20. console.log('键盘高度:', e.height)
  21. },
  22. onOptionMenuClick(){
  23. // 点击右上角菜单按钮触发
  24. },
  25. onPopMenuClick(e){
  26. // 点击右上角通用菜单中的自定义菜单按钮触发
  27. console.log('用户点击自定义菜单的索引', e.index)
  28. console.log('用户点击自定义菜单的name', e.name)
  29. console.log('用户点击自定义菜单的menuIconUrl', e.menuIconUrl)
  30. },
  31. onPullIntercept(){
  32. // 下拉截断时触发
  33. },
  34. onPullDownRefresh(e){
  35. // 页面下拉时触发。e.from 的值是 “code” 时表示 startPullDownRefresh 触发的事件;值是 “manual” 时表示用户下拉触发的下拉事件
  36. console.log('触发下拉刷新的类型', e.from)
  37. my.stopPullDownRefresh()
  38. },
  39. onTitleClick(){
  40. // 点击标题触发
  41. },
  42. onTabItemTap(e){
  43. // e.from 是点击且切换 tabItem 后触发,值是 “user” 时表示用户点击触发的事件;值是 “api” 时表示 switchTab 触发的事件
  44. console.log('触发tab变化的类型)', e.from)
  45. console.log('点击的tab对应页面的路径', e.pagePath)
  46. console.log('点击的tab的文字', e.text)
  47. console.log('点击的tab的索引', e.index)
  48. },
  49. beforeTabItemTap(){
  50. // 点击但切换 tabItem 前触发
  51. },
  52. }
  53. })

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

setData 会将数据从逻辑层发送到视图层,同时改变对应的 this.data 的值。

参数说明:

事件 类型 描述 最低版本
data Object 待改变的数据
callback Function 回调函数,在页面渲染更新完成之后执行。 使用 my.canIUse('page.setData.callback') 做兼容性处理。详见 1.7.0

Objectkey: value 的形式表示,将 this.data 中的 key 对应的值改变成 value。其中 key 可以非常灵活,以数据路径的形式给出,如 array[2].messagea.b.c.d,可以不需要在 this.data 中预先定义。

使用过程中,需要注意以下几点:

  • 直接修改 this.data 无效,不仅无法改变页面的状态,还会造成数据不一致。
  • 仅支持设置可 JSON 化的数据。
  • 尽量避免一次设置过多的数据。
  • 不要把 data 中任何一项的 value 设为 undefined ,否则这一项将不被设置并可能遗留一些潜在问题。

示例代码:

  1. <view>{{text}}</view>
  2. <button onTap="changeTitle"> Change normal data </button>
  3. <view>{{array[0].text}}</view>
  4. <button onTap="changeArray"> Change Array data </button>
  5. <view>{{object.text}}</view>
  6. <button onTap="changePlanetColor"> Change Object data </button>
  7. <view>{{newField.text}}</view>
  8. <button onTap="addNewKey"> Add new data </button>
  9. <view>hello: {{name}}</view>
  10. <button onTap="changeName"> Chane name </button>
  1. Page({
  2. data: {
  3. text: 'test',
  4. array: [{text: 'a'}],
  5. object: {
  6. text: 'blue',
  7. },
  8. name: 'taobao',
  9. },
  10. changeTitle() {
  11. // 错误!不要直接去修改 data 里的数据
  12. // this.data.text = 'changed data'
  13. // 正确
  14. this.setData({
  15. text: 'ha',
  16. });
  17. },
  18. changeArray() {
  19. // 可以直接使用数据路径来修改数据
  20. this.setData({
  21. 'array[0].text': 'b',
  22. });
  23. },
  24. changePlanetColor(){
  25. this.setData({
  26. 'object.text': 'red',
  27. });
  28. },
  29. addNewKey() {
  30. this.setData({
  31. 'newField.text': 'c',
  32. });
  33. },
  34. changeName() {
  35. this.setData({
  36. name: 'alipay',
  37. }, () => { // 接受传递回调函数
  38. console.log(this); // this 当前页面实例
  39. this.setData({ name: this.data.name + ', ' + 'welcome!'});
  40. });
  41. },
  42. });

Page.prototype.$spliceData(data: Object, callback: Function)

说明$spliceData 自 1.7.2 之后才支持,可以使用 my.canIUse(‘page.\$spliceData’) 做兼容性处理。详情参见 小程序基础库说明

spliceData 同样用于将数据从逻辑层发送到视图层,但是相比于 setData,在处理长列表的时候,其具有更高的性能。

参数说明:

事件 类型 描述 最低版本
data Object 待改变的数据
callback Function 回调函数,在页面渲染更新完成之后执行。

Objectkey: value 的形式表示,将 this.data 中的 key 对应的值改变成 value。其中:

  • key 可以非常灵活,以数据路径的形式给出,如 array[2].messagea.b.c.d,可以不需要在 this.data 中预先定义。
  • value 为一个数组(格式为:[start, deleteCount, …items]), 数组的第一个元素为操作的起始位置,第二个元素为删除的元素的个数,剩余的元素均为插入的数据。对应 es5 中数组的 splice 方法。

示例代码:

  1. <!-- pages/index/index.axml -->
  2. <view class="spliceData">
  3. <view a:for="{{a.b}}" key="{{item}}" style="border:1px solid red">
  4. {{item}}
  5. </view>
  6. </view>
  1. // pages/index/index.js
  2. Page({
  3. data: {
  4. a: {
  5. b: [1,2,3,4],
  6. },
  7. },
  8. onLoad(){
  9. this.$spliceData({ 'a.b': [1, 0, 5, 6] });
  10. },
  11. });

页面输出:

  1. 1
  2. 5
  3. 6
  4. 2
  5. 3
  6. 4

Page.prototype.$batchedUpdates(callback: Function)

批量更新数据。

说明$spliceData 自 1.14.0 之后才支持,可以使用 my.canIUse(‘page.\$batchedUpdates’) 做兼容性处理。详情参见 小程序基础库说明

参数说明:

事件 类型 描述 最低版本
callback Function 在此回调函数中的数据操作会被批量更新。

示例代码:

  1. // pages/index/index.js
  2. Page({
  3. data: {
  4. counter: 0,
  5. },
  6. plus() {
  7. setTimeout(() => {
  8. this.$batchedUpdates(() => {
  9. this.setData({
  10. counter: this.data.counter + 1,
  11. });
  12. this.setData({
  13. counter: this.data.counter + 1,
  14. });
  15. });
  16. }, 200);
  17. },
  18. });
  1. <!-- pages/index/index.axml -->
  2. <view>{{counter}}</view>
  3. <button onTap="plus">+2</button>

在上方示例代码中:

  • 每次点击按钮,页面的 counter 会加 2。
  • setData 放在 this.$batchedUpdates 中,这样尽管有多次 setData,但是却只有一次数据的传输。