---
title: Widget 卡片
summary: "介绍 Widget() 构造器的参数、生命周期回调及事件处理函数。"
questions:
  - Widget() 构造函数接受哪些参数？
  - Widget 有哪些生命周期回调函数？
  - Widget 与 Page 的生命周期有什么不同？
  - onRefresh 生命周期回调在什么场景下触发？
  - onThemeChange 回调的参数包含哪些信息？
  - Widget 初始数据 data 支持哪些数据类型？
  - onPageScroll 事件处理函数的参数包含什么信息？
  - 使用 Widget.prototype.setData 时有哪些注意事项？
---

## Widget(config: Object)

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

## 参数

| 属性          | 类型     | 默认值 | 必填 | 描述                                                                                  | 最低版本 |
| ------------- | -------- | ------ | ---- | ------------------------------------------------------------------------------------- | -------- |
| data          | Object   |        |      | Widget 的初始数据                                                                     |
| onLoad        | function |        |      | 生命周期回调—监听 Widget 加载, 可以在 onLoad 的参数中获取打开当前 Widget 路径中的参数 |
| onShow        | function |        |      | 生命周期回调—监听 Widget 显示                                                         |
| onReady       | function |        |      | 生命周期回调—监听 Widget 初次渲染完成                                                 |
| onHide        | function |        |      | 生命周期回调—监听 Widget 隐藏                                                         |
| onRefresh     | function |        |      | 生命周期回调—监听 Widget 重新加载更新, 常用于 App 下拉刷新                            |
| onUnload      | function |        |      | 生命周期回调—监听 Widget 卸载                                                         |
| onThemeChange | function |        |      | 生命周期回调-监听主题变化, 参数 `{ theme }`                                           |
| onPageScroll  | function |        |      | Widget 滚动触发事件的处理函数                                                         |

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

## Widget this 实例

### 属性

| 属性  | 类型   | 描述                 |
| ----- | ------ | -------------------- |
| route | String | 到当前 Widget 的路径 |
| data  | Object | Widget 数据          |

### 方法

| 方法名  | 参数             | 描述                       | 最低版本 |
| ------- | ---------------- | -------------------------- | -------- |
| setData | Object `newData` | 设置 data 并执行视图层渲染 |          |

## data

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

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

**示例代码**

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

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

## 生命周期

### onLoad(Object)

Widget 加载时触发。一个 Widget 只会调用一次，可以在 `onLoad` 的参数中获取打开当前 Widget 时传过来的参数。

**参数：**

Object: 打开当前 Widget 传的参数

### onShow()

Widget 显示/切入前台时触发。

### onReady()

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

**注意：** 对界面内容进行设置的 API，请在 onReady 之后进行。

### onHide()

Widget 隐藏/切入后台时触发。

### onRefresh()

Widget 重新加载更新。

### onUnload()

Widget 卸载时触发。

### onThemeChange(Object)

Widget 主题变化时触发。

**参数：**

| 属性  | 类型   | 说明         |
| ----- | ------ | ------------ |
| theme | String | 变化后的主题 |

## Widget 事件处理函数

### onPageScroll(Object object)

监听用户滑动页面事件。

#### 参数 Object object:

| 属性      | 类型   | 说明                                     |
| --------- | ------ | ---------------------------------------- |
| scrollTop | Number | Widget 在垂直方向已滚动的距离（单位 px） |

## Widget 中组件事件触发

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

**示例代码：**

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

```

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

## Widget.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 是无法改变 Widget 的状态的，还会造成数据不一致。**
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
//index.js
Widget({
  data: {
    text: 'This is widget data.',
  },
  onLoad: function (query) {
    // Do some initialize when widget load.
  },
  onShow: function () {
    // Do something when widget show.
  },
  onReady: function () {
    // Do something when widget ready.
  },
  onHide: function () {
    // Do something when widget hide.
  },
  onRefresh: function() {
    // Do something when widget onRefresh.
  },
  onUnload: function () {
    // Do something when widget close.
  },
  onPageScroll: function () {
    // Do something when widget Scroll.
  },
  // Event handler.
  viewTap: function () {
    this.setData(
      {
        text: 'Set some data for updating view.',
      },
      function () {
        // this is setData callback
      },
    );
  },
});
```