---
title: Page
summary: "介绍 Page() 构造器的参数、生命周期回调、事件处理及 setData 数据通信方法。"
questions:
  - Page() 构造函数接受哪些参数？
  - 页面实例 this 上有哪些属性和方法？
  - 页面初始数据 data 支持哪些数据类型？
  - onLoad 生命周期回调的参数是什么？如何获取页面路径中的参数？
  - onReady 生命周期与 onShow 有什么区别？
  - onResize 回调的参数包含哪些字段？
  - 如何在页面中开启和使用下拉刷新功能？
  - setData 方法的 key 支持哪些数据路径格式？
  - 使用 setData 时有哪些注意事项和限制？
  - 如何通过 getOpenerEventChannel 实现页面间的数据通信？
---

## Page(config: Object)

注册小程序中的一个页面。接受一个 `Object` 类型参数，其指定页面的初始数据、生命周期回调、事件处理函数等。

## 参数

| 属性              | 类型     | 默认值 | 必填 | 描述                              | 最低版本 |
| ----------------- | -------- | ------ | ---- | --------------------------------- | -------- |
| data              | Object   |        |      | 页面的初始数据                    |
| onLoad            | function |        |      | 生命周期回调—监听页面加载         |
| onShow            | function |        |      | 生命周期回调—监听页面显示         |
| onReady           | function |        |      | 生命周期回调—监听页面初次渲染完成 |
| onHide            | function |        |      | 生命周期回调—监听页面隐藏         |
| onResize          | function |        |      | 生命周期回调—监听页面尺寸变化     |
| onUnload          | function |        |      | 生命周期回调—监听页面卸载         |
| onReachBottom     | function |        |      | 页面上拉触底事件的处理函数        |
| onPullDownRefresh | function |        |      | 监听用户下拉动作                  |

生成的页面实例可以在页面的方法、生命周期函数中通过 `this` 访问。

## 页面 this 实例

### 属性

| 属性    | 类型   | 描述                 |
| ------- | ------ | -------------------- |
| route   | String | 到当前页面的路径     |
| options | Object | 路由跳转时传递的参数 |
| data    | Object | 页面数据             |

### 方法

| 方法名                | 参数              | 描述                                                               | 最低版本 |
| --------------------- | ----------------- | ------------------------------------------------------------------ | -------- |
| setData               | Object `newData`  | 设置 data 并执行视图层渲染                                         |          |
| selectComponent       | String `selector` | 使用选择器选择组件实例节点，返回匹配到的第一个组件实例对象         |          |
| selectAllComponents   | String `selector` | 使用选择器选择组件实例节点，返回匹配到的全部组件实例对象组成的数组 |          |
| getOpenerEventChannel |                   | 获得一个 EventChannel 对象                                         |          |

## data

`data` 是页面第一次渲染使用的**初始数据**。

页面加载时，`data` 将会以 `JSON` 字符串的形式由逻辑层传至渲染层，因此 `data` 中的数据必须是可以转成 `JSON` 的类型：字符串，数字，布尔值，对象，数组。

**示例代码**

```xml
<view>{{text}}</view>
<view>{{array[0].msg}}</view>
```

```js
Page({
  data: {
    text: 'init data',
    array: [{ msg: '1' }, { msg: '2' }],
  },
});
```

## 生命周期

### onLoad(query: Object)

页面加载时触发。一个页面只会调用一次，可以在 `onLoad` 的参数中获取打开当前页面路径中的参数。

**参数：**

| 名称  | 类型   | 说明                     |
| ----- | ------ | ------------------------ |
| query | Object | 打开当前页面路径中的参数 |

```js
ty.navigateTo({
  url: 'hello/index?id=1',
});
```

```js
// hello/index.js
Page({
  onLoad(query) {
    // query = { id: 1 }
  },
});
```

### onShow()

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

### onReady()

页面初次渲染完成时触发。一个页面只会调用一次，代表页面已经准备妥当，可以和视图层进行交互。

**注意：** 对界面内容进行设置的 API 如 [ty.setNavigationBarTitle](/cn/miniapp/develop/miniapp/api/ui/navigation-bar/setNavigationBarTitle)，请在 onReady 之后进行。

### onHide()

页面隐藏/切入后台时触发。 如 [ty.navigateTo](/cn/miniapp/develop/miniapp/api/route/navigateTo) 或底部 `tab` 切换到其他页面，小程序切入后台等。

### onResize(options: Object)

屏幕尺寸变化时触发。

**options 字段说明**

| 名称              | 类型   | 说明                   |
| ----------------- | ------ | ---------------------- |
| type              | string | `portrait` `landscape` |
| size.windowWidth  | Number | 屏幕宽度, 单位 px      |
| size.windowHeight | Number | 屏幕高度, 单位 px      |

```js
Page({
  onResize: function (options) {
    console.log(options.type);
    console.log(options.size.windowWidth);
    console.log(options.size.windowHeight);
  },
});
```

### onUnload()

页面卸载时触发。如 [ty.redirectTo](/cn/miniapp/develop/miniapp/api/route/redirectTo) 或 [ty.navigateBack](/cn/miniapp/develop/miniapp/api/route/navigateBack) 到其他页面时。

## 页面事件处理函数

### onPullDownRefresh()

监听用户下拉刷新事件。

- 需要在`app.json`的[window](/cn/miniapp/develop/miniapp/framework/app/app-json#window)选项中或页面配置中开启`enablePullDownRefresh`。
- 可以通过[ty.startPullDownRefresh](/cn/miniapp/develop/miniapp/api/ui/container/startPullDownRefresh)触发下拉刷新，调用后触发下拉刷新动画，效果与用户手动下拉刷新一致。
- 当处理完数据刷新后，[ty.stopPullDownRefresh](/cn/miniapp/develop/miniapp/api/ui/container/stopPullDownRefresh)可以停止当前页面的下拉刷新。

### onReachBottom()

监听用户上拉触底事件。

- 可以在`app.json`的[window](/cn/miniapp/develop/miniapp/framework/app/app-json#window)选项中或页面配置中设置触发距离`onReachBottomDistance`。
- 在触发距离内滑动期间，本事件只会被触发一次。

## 页面中组件事件触发

`Page` 中还可以定义组件事件处理函数。在渲染层的组件中加入[事件绑定](/cn/miniapp/develop/miniapp/framework/event/interaction)，当事件被触发时，就会执行 `Page`中定义的事件处理函数。

**示例代码：**

```xml
<view bind:tap="viewTap"> click me </view>

```

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

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

`setData` 函数用于将数据从逻辑层发送到视图层（异步），同时改变对应的 `this.data` 的值（同步）。

参数：
| 参数 | 类型 | 必填 | 说明 | 最低版本 |
| ----------------------------------- | ------------ | -- | -- | --- |
| data | Object | 是| 这次要改变的数据 | |
| callback | Function | 否 | setData 引起的界面更新渲染完毕后的回调函数 | |

`Object` 以 `key: value` 的形式表示，将 `this.data` 中的 `key` 对应的值改变成 `value`。

其中 `key` 可以以数据路径的形式给出，支持改变数组中的某一项或对象的某个属性，如 `array[2].message`，`a.b.c.d`，并且不需要在 this.data 中预先定义。

注意：

1. **直接修改 this.data 而不调用 this.setData 是无法改变页面的状态的，还会造成数据不一致。**
2. 仅支持设置可序列化的数据内容: `String` `Number` `Boolean` `Null` `undefined` `Object` `Array`，其他类型将会被忽略。
3. 单次设置的数据不能超过 1024kB，请尽量避免一次设置过多的数据。
4. 请不要把 data 中任何一项的 `value` 设为 `undefined` ，否则这一项将不被设置并可能遗留一些潜在问题。

示例代码：

```xml
<view>{{text}}</view>
<button bind:tap="changeText"> Change normal data </button>
```

```js
Page({
  data: {
    text: 'init data',
  },
  changeText: function () {
    this.setData({
      text: 'changed data',
    });
  },
});
```

## Page.prototype.getOpenerEventChannel

如果一个页面由另一个页面通过 [ty.navigateTo](/cn/miniapp/develop/miniapp/api/route/navigateTo) 打开，这两个页面间将建立一条数据通道：

- 被打开的页面可以通过 `this.getOpenerEventChannel()` 方法来获得一个 `EventChannel` 对象；
- [ty.navigateTo](/cn/miniapp/develop/miniapp/api/route/navigateTo) 的 `success` 回调中也包含一个 `EventChannel` 对象。

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

```js
// pages/previous/index.js
Page({
  onLoad: function () {
    // 打开新页面，并传递数据
    ty.navigateTo({
      url: '/pages/home/index',
      events: { // 仅当设置了 events 时，才会创建 EventChannel
        // 监听被打开页面传递的数据
        acceptFromOpenerPage: (data) => {
          console.log(data);
        },
      },
      success: (eventChannel) => {
        // 通过 EventChannel 向被打开的页面发送数据
        eventChannel.emit('sendToOpenerPage', { data: 'Hello from previous page!' });
      },
    });
  },
});
```

```js
// pages/home/index.js
Page({
  onLoad: function () {
    // 获取打开当前页面的 EventChannel
    const eventChannel = this.getOpenerEventChannel();
    if (eventChannel) {
      // 监听来自上一个页面传递的数据
      eventChannel.on('sendToOpenerPage', (data) => {
        console.log(data);
        eventChannel.emit('acceptFromOpenerPage', { data: 'Hello from home page!' });
      });
    }
  }
});
```

## 示例代码

```js
//index.js
Page({
  data: {
    text: 'This is page data.',
  },
  onLoad: function (query) {
    // Do some initialize when page load.
  },
  onShow: function () {
    // Do something when page show.
  },
  onReady: function () {
    // Do something when page ready.
  },
  onHide: function () {
    // Do something when page hide.
  },
  onUnload: function () {
    // Do something when page close.
  },
  onPullDownRefresh: function () {
    // Do something when pull down.
  },
  onReachBottom: function () {
    // Do something when page reach bottom.
  },
  // Event handler.
  viewTap: function () {
    this.setData(
      {
        text: 'Set some data for updating view.',
      },
      function () {
        // this is setData callback
      },
    );
  },
});
```