页面运行机制 -凯发app官方网站

更新时间：2024-08-02 11:29:27

订阅更新

我的文档

设置

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');

object 属性说明

属性	类型	描述	最低版本
data	object/function	初始数据或返回初始化数据的函数。	-
options	object	一些选项（介绍相关功能时会涉及到具体的配置项，这里暂不列举）。	2.8.1
observers	object	数据变化观测器，用于监听 data 的变化，可查看数据变化观测器。	2.8.1
events	object	事件处理函数对象。
onload	function(query: object)	页面加载时触发。	-
onshow	function	页面显示时触发。	-
onready	function	页面初次渲染完成时触发。	-
onhide	function	页面隐藏时触发。	-
onunload	function	页面卸载时触发。	-
onshareappmessage	function(options: object)	点击右上角分享时触发。	-
ontitleclick	function	点击标题触发。	-
onoptionmenuclick	function	点击导航栏额外图标触发。
onpulldownrefresh	function({from: manual /code })	页面下拉时触发。	-
ontabitemtap	function	点击 tabitem 时触发。
onpagescroll	function({scrollheight,scrolltop})	页面滚动时触发。	-
onreachbottom	function	上拉触底时触发。	-
mixins	array	组件间代码复用机制。只支持传入 mixin() 实例。	2.8.5
其它	any	可以添加任意的函数或属性到 object 中，在页面的函数中可以用 this 来访问。	-

页面数据对象 data

通过设置

data

指定页面的初始数据。

●

data

可以被设置为对象类型，每个页面初始化时会

浅拷贝

该对象并作为当前页面的数据。

●

data

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

对象类型

在这种使用方式下，对

data

的原地修改会被保留下来，当页面推出再次进入该页面时，

data

是被修改后的值。

函数类型

注意：

不要直接修改

this.data

，无法改变页面的状态，还会造成数据不一致。例如：

页面生命周期

对于一个 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 函数，设置该页面的分享信息。

开发者可通过传入参数自定义小程序分享内容（例如：标题、描述、图片），用户通过点击或者复制分享的内容可以快速打开小程序，进入指定页面。目前支持的分享渠道有：支付宝朋友动态、支付宝好友、钉钉、新浪微博、微信、qq。

●

每个 page 页面的右上角菜单中默认有

按钮；

onshareappmessage

函数只自定义分享的内容，不影响分享功能。

●

用户点击分享按钮的时候会调用。

●

此事件需要返回一个对象（object）类型，用于自定义分享内容。

●

分享图片中的二维码的有效期为 60 天，若需要长期有效的二维码，请登录

我的应用

> 进入小程序应用详情页 >

小程序码

中生成。

●

小程序在 1.1.0 版本中开始支持 open-type 为 share 的按钮触发分享。

●

从基础库

1.24.13

、

2.6.7

版本开始支持

async

写法，可通过

my.caniuse('page.onshareappmessage.async')

检测是否支持。

应用场景

用户点击右上角的选项按钮可以分享小程序，用户点击分享后出现若干分享的选项。

根据用户选择的不同渠道，出现不同的分享形式。

效果实例

右上角触发分享效果：

按钮触发分享方式效果：

示例代码

右上角触发分享示例代码：

按钮触发分享方式示例代码：

入参

入参是

object

类型，参数如下：

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

返回值

onshareappmessage

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

属性	类型	必填	描述	最低版本
title	string	是	自定义分享标题。	-
desc	string	否	自定义分享描述：由于分享到微博只支持最大长度 140 个字，因此建议长度不要超过该限制。	-
path	string	是	自定义分享页面的路径，path 中的自定义参数可在小程序生命周期的 onload 方法中获取（参数传递遵循 http get 的传参规则）。	-
content	string	否	自定义吱口令文案，最多 28 个字符。
bgimgurl	string	否	自定义分享预览大图，建议尺寸 750x825，支持：网络图片路径；不支持：base64。
scimgurl	string	否	自定义社交图片链接，作为分享到支付宝好友时的主体图片。建议尺寸 376x330。客户端 10.2.50 开始支持。可通过 my.caniuse('page.onshareappmessage.return.scimgurl') 进行检测。支持：网络图片路径；不支持：base64。	2.7.13
imageurl	string	否	自定义分享小图 icon 元素，支持：网络图片路径；不支持：base64。
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

配置对象中新增以

为前缀的事件会引入潜在的问题（可能造成业务逻辑的错误触发），因此除上述基础事件外，新增的事件统一收敛到

page.events

对象中定义和管理。出于向前兼容考虑，之前的所有事件一般会在

page.onxx

和

page.events.onxx

均支持。

自基础库

2.8.6

开始，支持在

component

通过 rootevents 参数在组件中监听组件所在页面的生命周期函数以及页面事件处理函数。component

rootevents

支持的事件列表与 page.events 相同。

注意：

●

page.events

从基础库

开始支持。

●

component.rootevents

从基础库

2.8.6

开始支持。

●

请正确区分页面事件函数与

events

内同名事件函数的基础库版本要求。

●

onshareappmessage

只支持在page对象内定义，不支持在

page.events

component.rootevents

内定义。

以下是 page.events / component

rootevents

支持的事件函数列表：

事件	类型	描述	page支持	page.events支持	component.rootevents支持
onload	function(query: object)	页面加载时触发。	是		否
onshow	function	页面显示时触发。	是		2.8.6
onready	function	页面初次渲染完成时触发。	是		2.8.6
onhide	function	页面隐藏时触发。	是		2.8.6
onunload		页面卸载时触发。	是	2.8.5	2.8.6
ontitleclick	function	点击标题触发。	是		2.8.6
onoptionmenuclick	function	点击导航栏额外图标触发。			2.8.6
onpulldownrefresh	function({from: manual /code })	页面下拉时触发。	是		2.8.6
onpagescroll	function({scrollheight,scrolltop})	页面滚动时触发。	是		2.8.6
onreachbottom	function	上拉触底时触发。	是		2.8.6
ontabitemtap	function	点击非当前 tabitem 后触发。			2.8.6
beforetabitemtap	function	点击非当前 tabitem 前触发。	否		2.8.6
onkeyboardheight	function	键盘高度变化时触发。	否		2.8.6
onback	function	导航栏左侧返回按钮(以及 android 系统返回键）被点击时触发。	否		2.8.6
onresize	function({size: {windowwidth: number, windowheight: number}})	window 尺寸改变时触发。	否		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') 做兼容性处理，可查看。

$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	在此回调函数中的数据操作会被批量更新。

示例代码

●

本示例中每次点击按钮，页面的

counter

会加 2。

●

将

setdata

放在 this.$batchedupdates 中，这样尽管有多次

setdata

，但是却只有一次数据的传输。

createselectorquery

创建

selectorquery 对象实例

，查找定义在页面 .axml 中的节点。支持基础库

2.7.4

及以上版本。可用性判断：

与

my.createselectorquery

的区别是：

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

createintersectionobserver

创建

intersectionobserver 对象实例

，检测定义在页面 .axml 中的节点。支持基础库

2.7.4

及以上版本。

native 渲染引擎

：暂不支持。

可用性判断：

与

my.createintersectionobserver

的区别是：

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