Page
represents a page of application, and is used for page presentation and interaction. Each page corresponds to a subdirectory, which means that there are as many subdirectories as pages. It is also a constructor that is used to generate page instances.
Page initialization
When a page is initialized, you must provide data for rendering the page for the first time:
<view>{{title}}</view> <view>{{array[0].user}}</view>
Page({ data: { title: 'Alipay', array: [{user: 'li'}, {user: 'zhao'}] } })
When you define an interaction behavior, you must specify the response function in the page script:
<view onTap="handleTap">click me</view>
The above template defines that the
handleTap
method will be called when the user taps:Page({ handleTap() { console.log('yo! view tap!') } })
When you re-render a page, you must call
this.setData
method in the page script.<view>{{text}}</view> <button onTap="changeText"> Change normal data </button>
The above code specifies that the
changeText
method will be called when the user taps the button.Page({ data: { text: 'init data', }, changeText() { this.setData({ text: 'changed data' }) }, })
In the above code, calling the
this.setData
method in thechangeText
method will result in the page re-rendering.
Page()
Page()
accepts a object
as a parameter that specifies the page’s initial data, life-cycle function, event handler, and so on.
//index.js
Page({
data: {
title: "Alipay"
},
onLoad(query) {
// Page loading
},
onReady() {
// Page loading completed
},
onShow() {
// Page display
},
onHide() {
// Page hiding
},
onUnload() {
// Page closed
},
onTitleClick() {
// Title tapped
},
onPullDownRefresh() {
// Page pulled down
},
onReachBottom() {
// Page pulled to the bottom
},
onShareAppMessage() {
// Return to custom sharing information
},
viewTap() {
// Event handling
this.setData({
text: 'Set data for update.'
})
},
go() {
// A jump with parameters, reading xx from the query of onLoad function of page/index
my.navigateTo('/page/index?xx=1')
},
customData: {
hi: 'alipay'
}
})
In the above code, the parameter objects of the Page()
method are described as follows:
Attribute | Type | Description |
data | Object or Function | Initial data, or the function that returns initialized data |
onTitleClick | Function | Triggered after title is tapped |
onOptionMenuClick | Function | Supported by basic library 1.3.0+; triggered by tapping the navigation bar icon out of the grid, and can be determined by |
onPageScroll | Function({scrollTop}) | Triggered when the page scrolls |
onLoad | Function(query: Object) | Triggered when the page loads |
onReady | Function | Triggered when the first rendering of the page is completed |
onShow | Function | Triggered when the page is displayed |
onHide | Function | Triggered when the page is hidden |
onUnload | Function | Triggered when the page is unloaded |
onPullDownRefresh | Function | Triggered when the page is pulled down |
onReachBottom | Function | Triggered when the page reaches the bottom |
onShareAppMessage | Function | Triggered when the user taps the Share button in the top right corner |
Other | Any | The developers can add any functions or properties to the |
Note: In case data is an object, changing it in the page affects different instances of the page.
Lifecycle method
onLoad: Used on page loadding. It is only called once per page, and the query parameter is the
query
object passed inmy.navigateTo
andmy.redirectTo
.onShow: Used on page display. It is called every time a page is displayed.
onReady: Used when a page is rendered for the first time. It is only called once per page, indicating that a page is ready to interact with the view layer. If you need to configure interface, such as using
my.setNavigationBar
, do it afteronReady
.onHide: Used on page hiding. It is called when you use
my.navigateTo
to switch to other pages or usetab
to switch bottom tabs.onUnload: Used on page unloading. It is called when you use
my.redirectTo
ormy.navigateBack
to switch to other pages.
Event handler
onPullDownRefresh: Pull-to-refresh. To monitor the user’s pull-to-refresh event, you must enable
pullRefresh
in thewindow
option of app.json. When the data is refreshed,my.stopPullDownRefresh
can stop pull-to-refresh on the current page.onShareAppMessage: User sharing, see Share for more information.
Page.prototype.setData()
setData
function is used to send data from the logical layer to the view layer, and change the value of the corresponding this.data
at the meantime.
Note: Modifying this.data directly cannot change the page state, and will cause data inconsistency. Do not to set too much data at once.
setData
accepts an object as a parameter. The object’s key name key
can be specified flexibly in the form of a data path, such as array[2].message
and a.b.c.d
, and does not need to be predefined in this.data
.
Sample code
<view>{{text}}</view>
<button onTap="changeTitle"> Change normal data </button>
<view>{{array[0].text}}</view>
<button onTap="changeArray"> Change Array data </button>
<view>{{object.text}}</view>
<button onTap="changePlanetColor"> Change Object data </button>
<view>{{newField.text}}</view>
<button onTap="addNewKey"> Add new data </button>
Page({
data: {
text: 'test',
array: [{text: 'a'}],
object: {
text: 'blue'
}
},
changeTitle() {
// Incorrect! Do not modify the content in data directly
// this.data.text = 'changed data'
// Correct
this.setData({
text: 'ha'
})
},
changeArray() {
// Use data path to modify data directly
this.setData({
'array[0].text':'b'
})
},
changePlanetColor(){
this.setData({
'object.text': 'red'
});
},
addNewKey() {
this.setData({
'newField.text': 'c'
})
}
})
getCurrentPages()
getCurrentPages()
function is used to get the instance of the current page stack, which is given in the form of an array and in the order of the stack. The first element is the first page and the last element is the current page. The following code can be used to detect if the current page stack has a 5-level page depth.
if(getCurrentPages().length === 5) {
my.redirectTo('/xx');
} else {
my.navigateTo('/xx');
}
Note: Don’t try to modify the page stack, otherwise it will lead to routing and page status errors.
The framework maintains all current pages in the form of stack. When a route switch occurs, the page stack behaves as follows:
Routing method | Page stack behavior |
Initialization | A new page is pushed on to the stack |
Open a new page | A new page is pushed on to the stack |
Page redirection | The current page is popped off the stack while a new page is pushed on to the stack |
Page return | The current page is popped off the stack |
Tab switch | All the pages are popped off the stack, leaving only the new Tab page |
page.json
The window behavior of each page can be configured with the [page name].json
file.
The page configuration is much simpler than the app.json
global configuration, and only window
related configuration items can be set, so there is no need to write the window
key. Note that the page configuration will override the configuration items in the window
attribute of app.json
.
In addition, it also supports configuring navigation icons with optionMenu
, on which user taps, onOptionMenuClick
will be triggered.
File | Type | Required | Description |
optionMenu | Object | No | Supported by basic library 1.3.0+; can be used to set the navigation bar icons. Currently, it supports setting the icon attribute with a value of an icon URL (starting with https/http) or a base64 string. The recommended icon size is 30*30 px. |
For example:
{
"optionMenu": {
"icon": "https://img.alicdn.com/tps/i3/T1OjaVFl4dXXa.JOZB-114-114.png"
}
}
Page style
The root element in each page is page
, which can be used to set the height or background color.
page {
background-color: #fff;
}