---
title:  Miniapp Card
---

##  Miniapp Card(config: Object)

During the registration of a  Miniapp Card, an `Object` parameter is used to specify the initial data, lifecycle callbacks, event handler functions, and other required data of the  Miniapp Card.

## Parameter

| Property      | Type     | Default value | Required | Description                                                                                                                 | Minimum version |
| ------------- | -------- | ------------- | -------- | --------------------------------------------------------------------------------------------------------------------------- | --------------- |
| data          | Object   |               |          | The initial data of the  Miniapp Card.                                                                                             |
| onLoad        | function |               |          | The lifecycle callback to invoke when the  Miniapp Card is loaded. onLoad(Object query), The `query` parameter contains page data. |
| onShow        | function |               |          | The lifecycle callback to invoke when the  Miniapp Card is displayed.                                                              |
| onReady       | function |               |          | The lifecycle callback to invoke when the  Miniapp Card is initially rendered.                                                     |
| onHide        | function |               |          | The lifecycle callback to invoke when the  Miniapp Card is hidden.                                                                 |
| onRefresh     | function |               |          | The lifecycle callback to invoke when the  Miniapp Card is onRefresh.                                                              |
| onUnload      | function |               |          | The lifecycle callback to invoke when the  Miniapp Card is unloaded.                                                               |
| onThemeChange | function |               |          | The lifecycle callback to theme changes, parameters `{ theme }`                                                             |
| onPageScroll  | function |               |          | The handler function to invoke when users scroll the  Miniapp Card and trigger an event.                                           |

You can access the generated  Miniapp Card instance by using the `this` keyword in the methods and lifecycle functions of the  Miniapp Card.

## Widget this instance

### Property

| Property | Type   | Description                     |
| -------- | ------ | ------------------------------- |
| route    | String | The path to the current  Miniapp Card. |
| data     | Object | The data of the  Miniapp Card.         |

### Methods

| Method name | Parameter        | Description                           | Minimum version |
| ----------- | ---------------- | ------------------------------------- | --------------- |
| setData     | Object `newData` | Sets data and renders the view layer. |                 |

## data

`data` is the **initial data** that is used to initially render the  Miniapp Card.

To load a  Miniapp Card, `data` is passed from the logic layer to the rendering layer in the `JSON` string format. Therefore, `data` must be in a format that you can convert to `JSON` type, such as a string, number, Boolean value, object, or array.

**Example**

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

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

## Lifecycle

### onLoad(Object)

Triggered when a  Miniapp Card is loaded. This function can be called only once for each  Miniapp Card. In `onLoad`, you can get the parameter used in the path for opening the current  Miniapp Card.

**parameters**

Object: The parameter used in the path for opening the current  Miniapp Card.

### onShow()

Triggered when a  Miniapp Card is displayed or switches to the foreground.

### onReady()

Triggered when a  Miniapp Card is initially rendered. This function is called only once for each  Miniapp Card, and indicates that the  Miniapp Card is ready to interact with the view layer.

**Note**: Make the API requests to set UI content only after `onReady` is called.

### onHide()

Triggered when a  Miniapp Card is hidden or switches to the background.

### onRefresh()

Widget reload update.

### onUnload()

Triggered when a  Miniapp Card is unloaded.

### onThemeChange(Object)

Widget 主题变化时触发。

**parameters：**

| Property | Type   | Description   |
| -------- | ------ | ------------- |
| theme    | String | Changed theme |

## Widget event handlers

### onPageScroll(Object object)

Listens for the event in which users swipe a page.

#### Object object

| Property  | Type   | Description                                                             |
| --------- | ------ | ----------------------------------------------------------------------- |
| scrollTop | Number | The vertical distance in which a  Miniapp Card is scrolled. Unit: pixels (px). |

## Component event triggered in  Miniapp Card

You can define a component event handler in `Widget`. [Bind an event](/en/miniapp/develop/miniapp/framework/event/interaction) with the rendering component. When the event is triggered, the event handler defined in `Widget` is executed.

**Example:**

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

```

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

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

The `setData` function is used to asynchronously transmit data from the logic layer to the view layer, and synchronously change the value of `this.data`.

**Parameters**
| Parameter | Type | Required | Description | Minimum version |
| ----------------------------------- | ------------ | ---- | ---- | --- |
| data | Object | Yes | The data to be modified. | --- |
| callback | Function | No | The callback to invoke when page rendering is triggered and finished by `setData`. | |

`Object` is expressed in the format of `key: value`. In `this.data`, the value of `key` is changed to the specified `value`.

You can set `key` to a data path, and modify an item of an array or an object property, such as `array[2].message` and `a.b.c.d`. You do not need to predefine `this.data`.

Things to note:

1. **If you modify `this.data` but do not call `this.setData`, the  Miniapp Card status cannot be changed and data inconsistency might occur.**
2. You can only set data content that can be serialized, including: `String`, `Number`, `Boolean`, `Null`, `undefined`, `Object`, and `Array`. Other data types will be ignored.
3. Up to 1024 KB of data can be set in each call. We recommend that you do not set an excessive amount of data.
4. Do not set any `value` in `data` to `undefined`. Otherwise, this item will not be set, and certain potential problems might arise.

## Example

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

```js
//index.js
Widget({
  data: {
    text: 'This is  Miniapp Card data.',
  },
  onLoad: function (query) {
    // Initialized when the  Miniapp Card is loaded.
  },
  onShow: function () {
    // Do something when the  Miniapp Card is displayed.
  },
  onReady: function () {
    // Do something when the  Miniapp Card is ready.
  },
  onHide: function () {
    // Do something when the  Miniapp Card is hidden.
  },
  onRefresh: function() {
    // Do something when  Miniapp Card onRefresh.
  },
  onUnload: function () {
    // Do something when the  Miniapp Card is closed.
  },
  onPageScroll: function () {
    // Do something when the  Miniapp Card is scrolled.
  },
  // Event handler.
  viewTap: function () {
    this.setData(
      {
        text: 'Set some data for updating view.',
      },
      function () {
        // this is setData callback
      },
    );
  },
});
```