All Products
Document Center


Last Updated: Feb 05, 2021

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:

    1. <view>{{title}}</view>
    2. <view>{{array[0].user}}</view>
    1. Page({
    2. data: {
    3. title: 'Alipay',
    4. array: [{user: 'li'}, {user: 'zhao'}]
    5. }
    6. })
  • When you define an interaction behavior, you must specify the response function in the page script:

    1. <view onTap="handleTap">click me</view>

    The above template defines that the handleTap method will be called when the user taps:

    1. Page({
    2. handleTap() {
    3. console.log('yo! view tap!')
    4. }
    5. })
  • When you re-render a page, you must call this.setData method in the page script.

    1. <view>{{text}}</view>
    2. <button onTap="changeText"> Change normal data </button>

    The above code specifies that the changeText method will be called when the user taps the button.

    1. Page({
    2. data: {
    3. text: 'init data',
    4. },
    5. changeText() {
    6. this.setData({
    7. text: 'changed data'
    8. })
    9. },
    10. })

    In the above code, calling the this.setData method in the changeText method will result in the page re-rendering.


Page() accepts a object as a parameter that specifies the page’s initial data, life-cycle function, event handler, and so on.

  1. //index.js
  2. Page({
  3. data: {
  4. title: "Alipay"
  5. },
  6. onLoad(query) {
  7. // Page loading
  8. },
  9. onReady() {
  10. // Page loading completed
  11. },
  12. onShow() {
  13. // Page display
  14. },
  15. onHide() {
  16. // Page hiding
  17. },
  18. onUnload() {
  19. // Page closed
  20. },
  21. onTitleClick() {
  22. // Title tapped
  23. },
  24. onPullDownRefresh() {
  25. // Page pulled down
  26. },
  27. onReachBottom() {
  28. // Page pulled to the bottom
  29. },
  30. onShareAppMessage() {
  31. // Return to custom sharing information
  32. },
  33. viewTap() {
  34. // Event handling
  35. this.setData({
  36. text: 'Set data for updat.'
  37. })
  38. },
  39. go() {
  40. // A jump with parameters, reading xx from the query of onLoad function of page/index
  41. my.navigateTo('/page/index?xx=1')
  42. },
  43. customData: {
  44. hi: 'alipay'
  45. }
  46. })

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 my.canIUse('page.onOptionMenuClick')
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 object parameter, which can be accessed through this in the page function.

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 in my.navigateTo and my.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 after onReady.
  • onHide: Used on page hiding. It is called when you use my.navigateTo to switch to other pages or use tab to switch bottom tabs.
  • onUnload: Used on page unloading. It is called when you use my.redirectTo or my.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 the window 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.


setData function is used to send data from the logical layer to the view layer, and change the value of the corresponding at the meantime.


  • Modifying 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

Sample code

  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>
  1. Page({
  2. data: {
  3. text: 'test',
  4. array: [{text: 'a'}],
  5. object: {
  6. text: 'blue'
  7. }
  8. },
  9. changeTitle() {
  10. // Incorrect! Do not modify the content in data directly
  11. // = 'changed data'
  12. // Correct
  13. this.setData({
  14. text: 'ha'
  15. })
  16. },
  17. changeArray() {
  18. // Use data path to modify data directly
  19. this.setData({
  20. 'array[0].text':'b'
  21. })
  22. },
  23. changePlanetColor(){
  24. this.setData({
  25. 'object.text': 'red'
  26. });
  27. },
  28. addNewKey() {
  29. this.setData({
  30. 'newField.text': 'c'
  31. })
  32. }
  33. })


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.

  1. if(getCurrentPages().length === 5) {
  2. my.redirectTo('/xx');
  3. } else {
  4. my.navigateTo('/xx');
  5. }

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


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:

  1. {
  2. "optionMenu": {
  3. "icon": ""
  4. }
  5. }

Page style

The root element in each page is page, which can be used to set the height or background color.

  1. page {
  2. background-color: #fff;
  3. }