Register Page (Object object)

For each page in a mini program, it needs to be registered in the corresponding .js file to specify the page's initial data, lifecycle callbacks, event handling functions, and more.

Parameters

Object object

Property	Type	Default	Required	Description	Minimum Version
data	Object		Yes	Initial data for the page	1.0.0
onLoad	function		Yes	Lifecycle callback - Page load	1.0.0
onShow	function		Yes	Lifecycle callback - Page show	1.0.0
onReady	function		Yes	Lifecycle callback - Page ready	1.0.0
onHide	function		Yes	Lifecycle callback - Page hide	1.0.0
onUnload	function		Yes	Lifecycle callback - Page unload	1.0.0
onPullDownRefresh	function		Yes	Listen for user pull-down action	1.0.0
onReachBottom	function		Yes	Page pull-up event handler	1.0.0
onPageScroll	function		Yes	Page scroll event handler	1.0.0

Example Code

// index.js
Page({
  data: {
    text: 'This is page data.',
  },
  onLoad: function (options) {
    // Executed when the page is created
  },
  onShow: function () {
    // Executed when the page is shown in the foreground
  },
  onReady: function () {
    // Executed when the page is first rendered
  },
  onHide: function () {
    // Executed when the page goes from the foreground to the background
  },
  onUnload: function () {
    // Executed when the page is destroyed
  },
  onPullDownRefresh: function () {
    // Executed when pull-down refresh is triggered
  },
  onReachBottom: function () {
    // Executed when the page reaches the bottom
  },
  // Event handling function
  viewTap: function () {
    this.setData(
      {
        text: 'Set some data for updating view.',
      },
      function () {
        // This is the setData callback
      }
    );
  },
  // Custom data
  customData: {
    hi: 'MINA',
  },
});

data

data is the initial data used when rendering the page for the first time. When the page loads, data is passed from the logic layer to the rendering layer in the form of a JSON string. Therefore, the data in data must be of types that can be converted to JSON: strings, numbers, booleans, objects, and arrays.

The rendering layer can bind data using DLT.

Example Code:

<!--pages/index/index.dlt-->
<view>{{text}}</view>
<view>{{array[0].msg}}</view>

// pages/index/index.js
Page({
  data: {
    text: 'init data',
    array: [{ msg: '1' }, { msg: '2' }],
  },
});

Lifecycle Callback Functions

The trigger of the lifecycle and the page's routing.

onLoad(Object query)

Triggered when the page loads. This is only called once for a page, and you can obtain the parameters passed in the current page's path in the onLoad parameters.

Parameter Object query

Name	Type	Description
query	Object	Parameters in the current page's path

onShow()

Triggered when the page is shown or when it switches between the foreground and background.

onReady()

Triggered when the page's initial rendering is complete. This is called once for a page and means that the page is ready to interact with the view layer.

Note: For APIs that modify the interface content, such as dlt.setNavigationBarTitle, please perform them after onReady.

onHide()

Triggered when the page is hidden or switches to the background. This can happen when using dlt.navigateTo or when switching to another page using the bottom tab.
Special note: On a very small number of phones, when the page enters the background, it will be quickly destroyed by the system, causing some of the logic in onHide() to not be fully executed.

onUnload()

Triggered when the page is unloaded, such as when using dlt.redirectTo or dlt.navigateBack to go to another page.

Page Event Handling Functions

onPullDownRefresh()

Listens for the user's pull-down refresh action.

This needs to be enabled in app.json under the window option or in the page configuration. You can trigger the pull-down refresh using dlt.startPullDownRefresh, which displays the pull-down refresh animation. When you've finished refreshing the data, you can stop the pull-down refresh with dlt.stopPullDownRefresh.

onReachBottom()

Listens for the user's pull-up event.

You can set the triggering distance in app.json under the window option or in the page configuration using onReachBottomDistance. Within the set distance, this event is only triggered once.

onPageScroll(Object object)

Listens for the user's page scroll event.

Parameter Object object

Property	Type	Description
scrollTop	Number	The vertical scroll distance of the page (in px).

Note: Only define this method in the page when it's necessary. Avoid defining empty methods to reduce unnecessary event dispatching and its impact on communication between the rendering layer and logic layer. Avoid executing setData too frequently within onPageScroll, especially when transmitting large amounts of data, as it can affect communication performance.

Component Event Handling Functions

In Page, you can also define component event handling functions. Add event bindings in the component in the rendering layer, and when the event is triggered, it will execute the event handling function defined in Page.

Example Code:

<view bindtap="viewTap"> click me </view>

// pages/index/index.js

Page({
  viewTap: function () {
    console.log('view tap');
  },
});

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

The setData function is used to send data from the logic layer to the view layer (asynchronously) while changing the corresponding values in this.data (synchronously).

Parameter Description

Field	Type	Required	Description
data	Number	Yes	The data to be changed this time	1.0.0
callback	Function	No	A callback function executed after setData causes the view to be

updated and rendered | 3.10.0 |

Object is represented as key: value, which changes the value of key in this.data to value. key can be quite flexible, and it is given in the form of a data path. It supports changing a specific item in an array or a property of an object, such as array[2].message, a.b.c.d, etc. These must be pre-defined in this.data.

Note:

1. Directly modifying this.data without calling this.setData will not change the page's state and may lead to data inconsistencies.
2. Only supports setting data that can be JSON-serialized.
3. Please try to avoid setting too much data at once.
4. Do not set any value in data to undefined, as it will not be set and may leave potential issues.

<!-- pages/index/index.dlt -->
<view>{{text}}</view>
<button bind:tap="changeText">Change normal data</button>
<view>{{num}}</view>
<button bind:tap="changeNum">Change normal num</button>
<view>{{array[0].text}}</view>
<button bind:tap="changeItemInArray">Change Array data</button>
<view>{{object.text}}</view>
<button bind:tap="changeItemInObject">Change Object data</button>
<view>{{newField.text}}</view>
<button bind:tap="addNewField">Add new data</button>

// pages/index/index.js
Page({
  data: {
    text: 'init data',
    num: 0,
    array: [{ text: 'init data' }],
    object: {
      text: 'init data',
    },
  },
  changeText: function () {
    // this.data.text = 'changed data' // Do not directly modify this.data
    // Use setData instead
    this.setData({
      text: 'changed data',
    });
  },
  changeNum: function () {
    // Alternatively, you can modify this.data and immediately use setData to set the modified field
    this.data.num = 1;
    this.setData({
      num: this.data.num,
    });
  },
  changeItemInArray: function () {
    // For object or array fields, you can directly modify a subfield, which is often better than modifying the entire object or array
    this.setData({
      'array[0].text': 'changed data',
    });
  },
  changeItemInObject: function () {
    this.setData({
      'object.text': 'changed data',
    });
  },
  addNewField: function () {
    this.setData({
      'newField.text': 'new data',
    });
  },
});

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

The spliceData function is used to send data from the logic layer to the view layer (asynchronously) while changing the corresponding values in this.data (synchronously). spliceData is also used to send data from the logic layer to the view layer. However, compared to setData, spliceData has higher performance when dealing with long lists.

Note: spliceData is only supported from version 3.9.0 onwards. You can use dlt.canIUse('page.spliceData') for compatibility.

Object is represented as key: value, which changes the value of key in this.data to value. key can be quite flexible, and it is given in the form of a data path, e.g., array[2].message, a.b.c.d. These must be pre-defined in this.data. value is an array in the format [start, deleteCount, ...items], where the first element is the starting position of the operation, the second element is the number of elements to delete, and the remaining elements are the items to insert. This corresponds to the splice method of arrays in ES5.

Parameter Description

Field	Type	Required	Description
data	Number	Yes	The data to be changed this time	3.9.0
callback	Function	No	A callback function executed after spliceData causes the view to be updated and rendered	3.10.0

<!-- pages/index/index.dlt -->
<button bind:tap="spliceDataFun"> splice new data </view>
<view class="spliceData">
  <view s-for="(item, index) in a.b" :key="index" class="spliceData-item">
    {{item}}
  </view>
</view>

Page({
  data: {
    a: {
      b: [1, 2, 3, 4],
    },
  },
  spliceDataFun() {
    this.spliceData({ 'a.b': [1, 0, 5, 6] }, () => {
      // Callback is supported only in versions 3.10.0 and later
      console.log('new data is: ', this.data.a.b);
    });
  },
});