支付宝小程序生命周期

Page(object: Object)

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

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

// pages/index/index.js
Page({
  data: {
    title: 'Alipay',
  },
  onLoad(query) {
    // 页面加载
  },
  onShow() {
    // 页面显示
  },
  onReady() {
    // 页面加载完成
  },
  onHide() {
    // 页面隐藏
  },
  onUnload() {
    // 页面被关闭
  },
  onTitleClick() {
    // 标题被点击
  },
  onPullDownRefresh() {
    // 页面被下拉
  },
  onReachBottom() {
    // 页面被拉到底部
  },
  onShareAppMessage() {
    // 返回自定义分享信息
  },
  // 事件处理函数对象
  events: {
    onBack() {
      console.log('onBack');
    },
  },
  // 自定义事件处理函数
  viewTap() {
    this.setData({
      text: 'Set data for update.',
    });
  },
  // 自定义事件处理函数
  go() {
    // 带参数的跳转，从 page/ui/index 的 onLoad 函数的 query 中读取 type
    my.navigateTo({ url: '/page/ui/index?type=mini' });
  },
  // 自定义数据对象
  customData: {
    name: 'alipay',
  },
});

object 属性说明

属性	类型	描述	最低版本
data	Object/Function	初始数据或返回初始化数据的函数。	-
options	Object	一些选项（介绍相关功能时会涉及到具体的配置项，这里暂不列举）。	2.8.1
observers	Object	数据变化观测器，用于监听 data 的变化，可查看 数据变化观测器。	2.8.1
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
onPullDownRefresh	Function({from: manual/code})	页面下拉时触发。	-
onTabItemTap	Function	点击 tabItem 时触发。	1.11.0
onPageScroll	Function({scrollHeight,scrollTop})	页面滚动时触发。	-
onReachBottom	Function	上拉触底时触发。	-
mixins	Array<String>	组件间代码复用机制。 只支持传入 Mixin() 实例。	2.8.5
其它	Any	可以添加任意的函数或属性到 object 中，在页面的函数中可以用 this 来访问。	-

页面数据对象 data

通过设置 data 指定页面的初始数据。

• data 可以被设置为对象类型，每个页面初始化时会 浅拷贝 该对象并作为当前页面的数据。
• data 也可以被设置为函数类型，每个页面初始化时会执行该函数，并将返回值作为当前页面的数据。

对象类型

Page({
  data: {
    arr: [],
  },
  doIt() {
    this.setData({
      arr: [...this.data.arr, 1],
    });
  },
});

在这种使用方式下，对 data 的原地修改会被保留下来，当页面推出再次进入该页面时，data 是被修改后的值。

函数类型

Page({
  data() {
    return {
      arr: [],
    };
  },
  doIt() {
    this.setData({
      arr: [1, 2, 3],
    });
  },
});

注意： 不要直接修改 this.data，无法改变页面的状态，还会造成数据不一致。例如：

Page({
  data: {
    arr: [],
  },
  doIt() {
    this.data.arr.push(1); // 不要这么写！
    this.setData({
      arr: this.data.arr,
    });
  },
});

页面生命周期

对于一个 page 实例来说，生命周期包含 onLoad、onShow、onReady、onHide、onUnload。分别在页面的启动过程的不同阶段，以及后续操作响应时触发，具体可以查看页面状态流转。

页面状态流转

• New：新创建的页面实例，未进行业务启动初始化。
• Inited：已完成业务启动过程 onLoad/onShow 初始化，已收集得到首屏需要的 data 数据，准备进行渲染。
• Readied：已完成首屏渲染。
• Hidden：监听到 离开页面的行为 而触发 onHide 进入离开状态。
• Unloaded：监听到 销毁页面的行为 而触发 onUnload 进入已销毁状态（该状态下所有 setData 操作无效）。

说明： onLoad、onReady、onUnload 只会被执行一次，而 onHide、onShow 则会执行多次。

生命周期函数方法

onLoad(query: Object)

页面初始化时触发。一个页面只会调用一次。 query 来源于 my.navigateTo 和 my.redirectTo 等接口 URL 字段的参数部份（例如：path?key1=value1&key2=value2）。基础库会将该部份字符串内容解析为 Object，解析规则可查看 小程序全局 / 页面参数设置以及解析细节。

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

onShow()

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

onReady()

页面初次渲染完成时触发。 一个页面只会调用一次，代表页面已经准备妥当，可以和视图层进行交互。 对界面的设置，如 my.setNavigationBar 请在 onReady 之后设置。

onHide()

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

onUnload()

页面卸载时触发。 如 my.redirectTo 或 my.navigateBack 到其它页面等。

页面事件处理函数

onShareAppMessage(options: Object)

在 Page 中定义 onShareAppMessage 函数，设置该页面的分享信息。

入参

入参是 Object 类型，参数如下：

参数	类型	描述	最低版本
from	String	触发来源。 button：页面分享按钮触发。 menu：右上角分享按钮触。 code：执行 my.showSharePanel 触发。	1.10.0
target	Object	如果 from 值为 button，则 target 为触发这次分享的 button，否则为 undefined。	1.10.0
webViewUrl	String	页面中包含 web-view 组件时，返回当前 web-view 的 URL。	1.6.0

返回值

onShareAppMessage 执行后必须返回一个分享对象，用于自定义分享内容。

属性	类型	必填	描述	最低版本
title	String	是	自定义分享标题。	-
desc	String	否	自定义分享描述：由于分享到微博只支持最大长度 140 个字，因此建议长度不要超过该限制。	-
path	String	是	自定义分享页面的路径，path 中的自定义参数可在小程序生命周期的 onLoad 方法中获取（参数传递遵循 http get 的传参规则）。	-
content	String	否	自定义吱口令文案，最多 28 个字符。	1.7.0
bgImgUrl	String	否	自定义分享预览大图，建议尺寸 750x825，支持：网络图片路径；不支持：base64。	1.9.0
scImgUrl	String	否	自定义社交图片链接，作为分享到支付宝好友时的主体图片。建议尺寸 376x330。 客户端 10.2.50 开始支持。 可通过 my.canIUse('page.onShareAppMessage.return.scImgUrl') 进行检测。 支持：网络图片路径；不支持：base64。	2.7.13
imageUrl	String	否	自定义分享小图 icon 元素， 支持：网络图片路径；不支持：base64。	1.4.0
searchTip	String	否	生成分享截图的搜索引导，设置该参数后，会在分享图片中增加上支付宝搜“设置关键字”的内容，设置关键字不能超过 5 个字。	-
success	Function	否	分享成功后回调。	1.4.0
fail	Function	否	分享失败后回调。	1.4.0

success 回调函数

属性	类型	描述
channelName	String	分享所选择的渠道。
shareResult	Boolean	分享是否成功。

onTitleClick()

点击标题时触发。

onOptionMenuClick()

点击导航栏额外图标触发。

onPullDownRefresh({from: manual|code})

监听该页面的用户下拉刷新事件。

需要在 app.json 的 window 选项 中开启 "allowsBounceVertical": "YES" 且在页面的 json 文件中设置 "pullRefresh": true，页面才允许用户触发下拉刷新。

from 的值为 code 表示 startPullDownRefresh 触发的事件； 为 manual 表示用户下拉触发的下拉事件。

注意：安卓客户端 10.5.6 版本之前，安卓环境下通过代码和手势触发下拉刷新的结果都是 manual。建议在调用 my.startPullDownRefresh() 方法时，设置一个标志来区分这两种触发方式，并在若干毫秒后自动清除该标志。

onTabItemTap(object: Object)

目标页面监听 tabBar 的点击事件，切换 tabItem 时触发。

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

注意：首次打开目标页面时，onTabItemTap 会在目标页面 onShow 后触发。重新回到目标页面时，onTabItemTap 会在目标页面 onShow 前触发。

onPageScroll(object: Object)

页面滚动时触发。

属性	类型	描述
scrollTop	Number	页面滚动距离。
scrollHeight	Number	页面内容高度。

onReachBottom()

上拉触底时触发。 onReachBottom()是在上拉触底时才会触发，如果页面已经在页面底部继续上拉是不会再次触发。可以配合 my.pageScrollTo 向上滚动一点位置或者在底部增加数据等方式让页面不是处在底部位置达到可以连续上拉触发 onReachBottom()的效果。

events

在 Page 配置对象中新增以 on 为前缀的事件会引入潜在的问题（可能造成业务逻辑的错误触发），因此除上述基础事件外，新增的事件统一收敛到 Page.events 对象中定义和管理。出于向前兼容考虑，之前的所有事件一般会在 Page.onXX 和 Page.events.onXX 均支持。

自基础库 2.8.6 开始，支持在 Component 通过 rootEvents 参数在组件中监听组件所在页面的生命周期函数以及页面事件处理函数。Component.rootEvents 支持的事件列表与 Page.events 相同。

以下是 Page.events / Component.rootEvents 支持的事件函数列表：

事件	类型	描述	Page支持	Page.events支持	Component.rootEvents支持
onLoad	Function(query: Object)	页面加载时触发。	是	1.13.7	否
onShow	Function	页面显示时触发。	是	1.13.7	2.8.6
onReady	Function	页面初次渲染完成时触发。	是	1.13.7	2.8.6
onHide	Function	页面隐藏时触发。	是	1.13.7	2.8.6
onUnload		页面卸载时触发。	是	2.8.5	2.8.6
onTitleClick	Function	点击标题触发。	是	1.13.7	2.8.6
onOptionMenuClick	Function	点击导航栏额外图标触发。	1.3.0	1.13.7	2.8.6
onPullDownRefresh	Function({from: manual /code })	页面下拉时触发。	是	1.13.7	2.8.6
onPageScroll	Function({scrollHeight,scrollTop})	页面滚动时触发。	是	1.13.7	2.8.6
onReachBottom	Function	上拉触底时触发。	是	1.13.7	2.8.6
onTabItemTap	Function	点击非当前 tabItem 后触发。	1.11.0	1.13.7	2.8.6
beforeTabItemTap	Function	点击非当前 tabItem 前触发。	否	1.13.7	2.8.6
onKeyboardHeight	Function	键盘高度变化时触发。	否	1.13.7	2.8.6
onBack	Function	导航栏左侧返回按钮(以及 Android 系统返回键）被点击时触发。	否	1.13.7	2.8.6
onResize	Function({size: {windowWidth: number, windowHeight: number}})	window 尺寸改变时触发。	否	1.16.0	2.8.6
onSelectedTabItemTap	Function({pagePath, text,index})	点击当前 tabItem 后触发。	否	2.7.2	2.8.6
onShareAppMessage	Function(options: Object)	点击右上角分享。	是	否	否
beforeReload	Function(event: Object)	页面重载前触发。	否	2.8.9	2.8.9

beforeReload(event: Object)

页面重载前触发，常见于 WKWebView 崩溃与恢复。当页面发生重载时，现有的页面和自定义组件实例会被销毁，而后新建。通过此事件可以将一些销毁前的状态保存下来，传递给新建的页面和自定义组件。

属性	类型	描述
state	Object	重载状态对象。通过 this.getSavedReloadState 可获得。

说明：状态对象在页面及其自定义组件之间共享。如有特殊需求，请留意宿主小程序页面和插件自定义组件之间的数据隔离，或者同字段值被覆盖的可能性。

beforeTabItemTap()

点击非当前 tabItem 前触发。

onKeyboardHeight(object: Object)

键盘高度变化时触发。

属性	类型	描述
height	Number	键盘高度。

onBack()

导航栏左侧返回按钮(以及 Android 系统返回键）被点击时触发。

onResize(object: Object)

window 尺寸改变时触发。

属性	类型	描述
size	Object	window 尺寸。

size 属性说明

属性	类型	描述
windowWidth	Number	窗口宽度。
windowHeight	Number	窗口高度。

onSelectedTabItemTap(object: Object)

点击当前 tabItem 后触发。

属性	类型	描述
pagePath	String	被点击 tabItem 的页面路径。
text	String	被点击 tabItem 的按钮文字。
index	Number	被点击 tabItem 的序号，从 0 开始。

页面实例方法

setData(data: Object, callback: Function)

setData 会将数据从逻辑层发送到视图层，同时改变对应的 this.data 的值。 Object 以 key: value 的形式表示，将 this.data 中的 key 对应的值改变成 value。其中 key 可以非常灵活，以数据路径的形式给出，如 array[2].message、a.b.c.d，可以不需要在 this.data 中预先定义。

使用过程中，需要注意以下几点：

• 直接修改 this.data 无效，无法改变页面的状态，还会造成数据不一致。
• 仅支持设置可 JSON 化的数据。
• 请尽量避免一次设置过多的数据和频繁多次调用 setData()，两种情况都会影响性能。
• 请不要把 data 中任何一项的 value 设为 undefined ，否则这一项将不被设置并可能遗留一些潜在问题。

参数说明

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

$spliceData(data: Object, callback: Function)

说明：$spliceData 自 1.7.2 之后才支持，可以使用 my.canIUse('page.$spliceData') 做兼容性处理，可查看 兼容。

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

Object 以 key: value 的形式表示，将 this.data 中的 key 对应的值改变成 value。其中 key 可以非常灵活，以数据路径的形式给出，如 array[2].message、a.b.c.d，可以不需要在 this.data 中预先定义。value 为一个数组（格式：[start, deleteCount, ...items]）, 数组的第一个元素为操作的起始位置，第二个元素为删除的元素的个数，剩余的元素均为插入的数据。对应 es5 中数组的 splice 方法。

参数说明

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

$batchedUpdates(callback: Function)

批量更新数据。

说明：$batchedUpdates 自 1.14.0 之后才支持，可以使用 my.canIUse('page.$batchedUpdates') 做兼容性处理，可查看 兼容。

参数说明

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

createSelectorQuery

创建 SelectorQuery 对象实例，查找定义在页面 .axml 中的节点。支持基础库 2.7.4 及以上版本。可用性判断：

my.canIUse('page.createSelectorQuery');

与 my.createSelectorQuery 的区别是：

用法	select() 和 selectAll() 选择器语法	选择范围
my.createSelectorQuery	CSS 语法	所有渲染层上的节点。
this.createSelectorQuery	严格选择器语法，可查看 selector 语法。	仅所指页面或自定义组件的 .axml 中定义的节点。

createIntersectionObserver

创建 IntersectionObserver 对象实例，检测定义在页面 .axml 中的节点。支持基础库 2.7.4 及以上版本。可用性判断：

my.canIUse('page.createIntersectionObserver');

与 my.createIntersectionObserver 的区别是：

用法	relativeTo() 和 observe() 选择器语法	检测范围
my.createIntersectionObserver	CSS 语法	所有渲染层上的节点。
this.createIntersectionObserver	严格选择器语法，可查看 selector 语法。	仅所指页面或自定义组件的 .axml 中定义的节点。

createMediaQueryObserver

创建 MediaQueryObserver 对象实例，用于监听页面 media query 状态的变化。支持基础库 2.8.2 及以上版本。可用性判断：

my.canIUse('page.createMediaQueryObserver');

getOpenerEventChannel

基础库 2.7.7 起支持。如果一个页面由另一个页面通过 my.navigateTo 打开，这两个页面间将建立一条通信通道：

• 被打开的页面可以通过 this.getOpenerEventChannel() 方法来获得一个 EventChannel 对象。
• my.navigateTo 的 success 回调中也包含一个 EventChannel 对象。

这两个 EventChannel 对象间可以使用 emit 和 on 方法相互发送、监听事件。

getTabBar

获取自定义 tabBar 实例，参照 自定义 tabBar。基础库 2.7.20 起支持。

Page({
  onShow() {
    if (typeof this.getTabBar === 'function' && this.getTabBar()) {
      this.getTabBar().setData({
        selected: 0,
      });
    }
  },
});

hasMixin

检查页面是否具有 mixin。基础库 2.8.5 开始支持。

// 可用性判断
my.canIUse('page.hasMixin');

const mixin = Mixin({});
Page({
    mixins: [mixin],
  onReady() {
    console.log(this.hasMixin(mixin));
  }
})

setUpdatePerformanceListener

设置更新性能统计信息接收函数，详情可查看 获取更新性能统计信息。基础库 2.8.5 开始支持。

// 可用性判断
my.canIUse('page.setUpdatePerformanceListener');

Page({
  onLoad() {
    this.setUpdatePerformanceListener({withDataPaths: true}, (res) => {
      console.log(res)
    })
  }
})

getSavedReloadState

获取页面重载前的状态对象。详见 beforeReload 事件。

页面实例属性

route

Page 路径，对应 app.json 中配置的路径值，类型为 String。这是一个只读属性。

Page({
  onShow() {
    // 对应 app.json 中配置的路径值
    console.log(this.route);
  },
});

router

页面路由器对象，有 switchTab、 reLaunch 、redirectTo、 navigateTo、 navigateBack 五个方法。可以通过 this.pageRouter 或 this.router 获得当前页面的路由器对象。基础库 2.7.22 起支持。

属性	类型	说明
router	Object	相对于 this 指代的页面的 Router 对象
pageRouter	Object	相对于 this 指代的页面的 Router 对象