---
url: /guide/basic/intro.md
---
# 介绍 {#intro}

## Mpx是什么？ {#what-is-mpx}

Mpx是一款致力于提高小程序开发体验和开发效率的增强型小程序框架，通过Mpx，我们能够高效优雅地开发出具有极致性能的优质小程序应用，并将其输出到各大小程序平台、Web和React Native环境中运行。

Mpx的核心设计理念在于增强，这意味着Mpx是对小程序原生开发标准的补强和扩充，同时也兼容了原生开发标准。Mpx的一个设计理念在于尽可能地依赖小程序原生的自有能力，如路由系统，自定义组件，事件系统和slot等能力，因此用户在使用Mpx开发小程序时，需要对原生小程序开发有一定程度的掌握。所幸小程序开发本身并不困难，我们也会在本文档中对必要的原生小程序开发知识进行一定程度地说明。

微信小程序作为小程序的开山鼻祖，具有最完善的生态和最全面的特性支持，后来的所有小程序平台在技术方案和代码语法上都与微信小程序高度相似，Mpx目前完善支持了以微信小程序增强语法为base的跨平台输出能力，本文档在介绍原生小程序开发相关的部分时也会以微信小程序为例。

最后，Mpx是一个开发框架，不是组件库，这一点经常会有开发者搞混。Mpx兼容业内已有的小程序组件库，如vant/iview等，我们之后也会开源内部基于Mpx开发的跨端组件库。

## Mpx提供了哪些能力？ {#what-mpx-provides}

### 单文件开发(SFC) {#sfc}

Mpx使用类似Vue的单文件开发模式，小程序原本的template/js/style/json都可以写在单个的.mpx文件中，清晰便捷，详情查看[这里](sfc.md)

### 数据响应 {#data-reactivity}

数据响应是Mpx提供的核心增强能力，该能力主要受Vue的启发，主要包含数据赋值响应，watch api和computed计算属性等能力，关于该能力更详细的介绍可以查看[这里](reactive.md)

### 增强的模板语法 {#enhanced-template-syntax}

同样受到Vue的启发，Mpx提供了很多增强模板语法便于开发者方便快捷地进行视图开发，主要包含以下：

* [wx:style动态样式](class-style-binding.md#style-binding)
* [wx:class动态类名](class-style-binding.md#class-binding)
* [wx:model双向绑定](two-way-binding.md)
* [wx:model-prop双向绑定属性](two-way-binding.md#change-two-way-binding-event-prop)
* [wx:model-event双向绑定事件](two-way-binding.md#change-two-way-binding-event-prop)
* [wx:model-value-path双向绑定数据路径](two-way-binding.md#change-two-way-binding-path)
* [wx:model-filter双向绑定过滤器](two-way-binding.md#two-way-binding-filter)
* [wx:ref获取实例](refs.md)
* [wx:show隐藏显示](conditional-render.md)
* [component动态组件](component.md#dynamic-component)
* [事件处理内联传参](event.md)
* [模板条件编译](conditional-render.md)

### 极致性能 {#extreme-performance}

Mpx在性能上做到了极致，我们在框架中通过模板数据依赖收集进行了深度的setData优化，做到了程序上的最优，让用户能够专注于业务开发；

其次，Mpx的编译构建完全基于依赖收集，支持按需进行的npm构建，能够自动根据用户的分包配置抽离共用模块，确保用户最终产出项目的包体积最优；

最后，Mpx的运行时框架部分仅占用51KB；

Mpx和业内其他框架的运行时性能对比可以参考[这篇文章](https://github.com/hiyuki/mp-framework-benchmark/blob/master/README.md)

### 状态管理 {#state-management}

Mpx借鉴Vuex的设计实现一套与框架搭配使用的状态管理(store)工具，除了支持Vuex中已有的特性外，我们还创新地提出了一种多实例store的跨团队状态管理模式，我们在业务中实际使用后普遍认为该设计比原有的modules更加灵活方便，更多详情可以[查看这里](../advance/store.md)

在Mpx2.8版本中，我们引入了Vue3.0的组合式API开发模式，同时也将与之配套的Pinia状态管理库引入，用户可以在Mpx项目中使用Pinia进行状态管理，更多详情可以[查看这里](../advance/pinia.md)

### 编译构建 {#compile-build}

Mpx的编译构建以webpack为基础，针对小程序项目结构深度定制开发了一个webpack插件和一系列loaders，整个构建过程完全基于依赖收集按需打包，兼容大部分webpack自身能力及生态，此外Mpx的编译构建还支持以下能力：

* [npm构建](../advance/npm.md)
* [分包构建](../advance/subpackage.md)
* [分包异步化](../advance/async-subpackage.md)
* [包体积分析](../advance/size-report.md)
* [原生组件支持](../advance/progressive.md#native-integration)
* [原生能力兼容(custom-tab-bar/workers/云开发等)](../advance/ability-compatible.md)
* [小程序插件](../advance/plugin.md)
* [TypeScript支持](../advance/ts.md)
* [原子CSS](../advance/utility-first-css.md)
* [模板预编译](template.md#template-precompile)
* [CSS预处理](css.md)
* [静态资源处理](../advance/image-process.md)
* [资源路径获取](../advance/resource-resolve.md)
* [自定义输出路径](../advance/custom-output-path.md)
* [DllPlugin](../advance/dll-plugin.md)

### 跨平台能力 {#cross-platform-ability}

Mpx支持全部小程序平台(微信，支付宝，百度，头条，qq)的增强开发，同时支持将一份基于微信增强的业务源码输出到主流小程序平台、Web和React Native环境中运行，更多详情请[查看这里](../advance/platform.md)

### 完善的周边能力 {#complete-ecosystem}

除了上述的核心能力外，Mpx还提供了丰富的周边能力支持，主要包括以下能力：

* [脚手架工具](../advance/cli.md)
* [网络请求](../extend/fetch.md)
* [跨平台环境API](../../api-proxy/index.md)
* [I18n国际化](../advance/i18n.md)
* [webview桥](../extend/webview-bridge.md)
* [单元测试](../tool/unit-test.md)
* [E2E测试](../tool/e2e-test.md)

## 对比其他小程序框架 {#compare-other-frameworks}

目前业内的小程序框架主要分为两类，一类是以uniapp，taro2为代表的静态编译型框架，这类框架以静态编译为主要手段，将React和Vue开发的业务源码转换到小程序环境中进行适配运行。这类框架的主要优点在于web项目迁移方便，跨端能力较强。但是由于React/Vue等web框架的DSL与小程序本身存在较大差距，无法完善支持原web框架的全部能力，开发的时候容易踩坑。

另一类是以kbone，taro3为代表的运行时框架，这类框架利用小程序本身提供的动态渲染能力，在小程序中模拟出web的运行时环境，让React/Vue等框架直接在上层运行。这类框架的优点在于web项目迁移方便，且在web框架语法能力的支持上比静态编译型的框架要强很多，开发时遇到的坑也会少很多。但是由于模拟的web运行时环境带来了巨大的性能开销，这类框架并不适合用于大型复杂的小程序开发。

不同于上面两类框架，Mpx以小程序本身的DSL为基础，通过编译和运行时手段结合对其进行了一系列拓展增强，没有复杂庞大的转译和环境抹平，在提升用户开发体验和效率的同时，既能保障开发的稳定和可预期性，又能保障接近原生的良好性能，非常适合开发大型复杂的小程序应用。

在跨端方面，Mpx重点保障跨小程序平台的跨端能力，由于各家小程序标准具有很强的相似性，Mpx在进行跨端输出时，以静态编译为主要手段，辅以灵活便捷的条件编译，保障了跨端输出的性能和可用性。

---

---
url: /guide/basic/start.md
---
# 快速开始 {#quick-start}

## 安装脚手架 {#install-scaffold}

::: code-group

```sh [npm]
npm i -g @mpxjs/cli
```

```sh [pnpm]
pnpm add -g @mpxjs/cli
```

```sh [yarn]
yarn global add @mpxjs/cli
```

:::

> @mpxjs/cli 文档 https://github.com/mpx-ecology/mpx-cli

## 创建项目安装依赖 {#create-project-install-dep}

在当前目录下创建 mpx 项目。

```shell
mpx create mpx-project
```

也可以使用 npx 在不全局安装脚手架情况下创建项目。

```shell
npx @mpxjs/cli create mpx-project
```

执行命令后会弹出一系列问题进行项目初始配置，根据自身需求进行选择，完成后进入项目目录进行依赖安装。

```shell
npm install
```

> 创建`插件项目`由于微信限制必须填写插件的`AppID`，创建`普通项目`无强制要求。

补充提示：

* 推荐的 IDE 配置是 [VS Code](https://code.visualstudio.com) + [Mpx (Official)](https://marketplace.visualstudio.com/items?itemName=mpxjs.mpx-official) 扩展。如果使用其他编辑器，参考 [IDE 支持章节](ide.md)。

## 编译构建 {#compile-build}

相关命令

```json
{
  "serve": "mpx-cli-service serve", // 开发模式
  "build": "mpx-cli-service build" // 构建模式
}
```

使用 npm script 执行 mpx 的编译构建，在开发模式下我们执行 serve 命令，将项目源码构建输出到`dist/${平台目录}`下，并且监听源码的改动进行重新编译。

```shell
npm run serve
```

### CLI 命令 {#cli-commands}

#### build

```sh
用法：mpx-cli-service build [options]

选项:

  --targets    编译目标(默认值: wx)
  --mode       指定环境模式 development | production (默认值：production)
  --env        自定义 __mpx_env__
  --watch      监听文件变化
  --report     生成包分析报告
```

```sh
# 构建小程序，默认微信 {#build-miniprogram-wechat}
mpx-cli-service build --targets=wx,ali
```

**目前支持的平台**

| 平台   | target  |
| ------ | ------- |
| 微信   | wx      |
| 阿里   | ali     |
| 百度   | swan    |
| QQ     | qq      |
| 头条   | tt      |
| 浏览器 | web     |
| 快应用 | qa     |
| 安卓  | android |
| iOS | ios     |
| 鸿蒙  | harmony |

#### serve

```sh
用法：mpx-cli-service serve [options]

选项:

  --targets    编译到小程序目标(默认值: wx)
  --mode       指定环境模式 (默认值：production)
  --env        自定义 __mpx_env__
```

## 预览调试 {#preview-debug}

使用小程序开发者工具打开 dist 下对应平台的目录，对你的小程序进行预览、调试，详情可参考[小程序开发指南](https://developers.weixin.qq.com/miniprogram/dev/framework/quickstart/getstart.html)

> 开启小程序开发者工具的 watch 选项，配合 mpx 本身的 watch，能够得到很好的开发调试体验。

## 开始 code {#start-code}

在 Mpx 中，我们使用`@mpxjs/core`提供的 createApp、createPage 和 createComponent 函数（分别对应原生小程序中的 App、Page 和 Component）来创建 App、页面和组件，我们下面根据脚手架创建出的初始项目目录，进行简单的介绍。

进入 src/app.mpx，我们可以看到里面的结构和.vue 文件非常类似，三个区块分别对应了小程序中的 js/wxss/json 文件。

js 区块中调用 createApp 用于注册小程序，传入的配置可以参考[小程序 App 构造器](https://developers.weixin.qq.com/miniprogram/dev/reference/api/App.html)，由于 app.js 是小程序全局最早执行的 js 模块，一般 mpx 插件安装等初始化操作也在这里进行。

style 区块对应 app.wxss 定义了全局样式，可以自由使用 sass/less/stylus 等 css 预编译语言。

json 区块完全支持小程序原生的[app.json 配置](https://developers.weixin.qq.com/miniprogram/dev/reference/configuration/app.html)，还额外支持了[packages 多人合作](../advance/subpackage.md#packages)等增强特性。

```html
<script>
  import mpx, { createApp } from "@mpxjs/core"
  import apiProxy from "@mpxjs/api-proxy"

  mpx.use(apiProxy, {
    usePromise: true,
  })

  createApp({
    onLaunch() {},
  })
</script>

<style lang="stylus">
  .bold
    font-weight bold
</style>

<script type="application/json">
  {
    "pages": ["./pages/index"]
  }
</script>
```

进入 src/pages/index.mpx，可以看到同样是.vue 风格的单文件结构，比起上面的 app.mpx 多了一个 template 区块，用于定义页面模板，除了支持小程序本身的全部模块语法和指令外，mpx 还参考 vue 提供了大量[模板增强指令](../../api/directives.md)，便于用户更快速高效地进行界面开发。

在 js 中调用 createPage 创建页面时，除了支持原本小程序支持的[Page 配置](https://developers.weixin.qq.com/miniprogram/dev/reference/api/Page.html)外，我们还支持以[数据响应](reactive.md)为核心的一系列增强能力。

在 json 中，我们同样支持原生的[页面 json 配置](https://developers.weixin.qq.com/miniprogram/dev/reference/configuration/page.html)，此外，我们能够直接在`usingComponents`中填写 npm 地址引用 npm 包中的组件，mpx 组件和原生小程序组件均可引用，无需调用开发者工具 npm 编译，且能够通过依赖收集按需进行打包。

> 为了保障增强能力的完整性，在支持的平台中 Mpx 优先使用 Component 构造器创建页面，支持全部 Component 生命周期；在某些特殊情况下，你可以在[@mpxjs/webpack-plugin](../../api/compile.md#forceusepagector)中传入 forceUsePageCtor:true 配置来禁用掉这个行为。

```html
<template>
  <list></list>
</template>

<script>
  import { createPage } from "@mpxjs/core"

  createPage({
    onLoad() {},
    onReady() {},
  })
</script>

<style lang="stylus"></style>

<script type="application/json">
  {
    "usingComponents": {
      "list": "../components/list"
    }
  }
</script>
```

最后，我们进入 src/components/list.mpx 文件，可以看到其构成与页面文件十分相似，对于组件，Mpx 提供了和页面完全一致的增强能力

```html
<template>
  <view class="list">
    <view wx:for="{{listData}}" wx:key="index">{{item}}</view>
  </view>
</template>

<script>
  import { createComponent } from "@mpxjs/core"

  createComponent({
    data: {
      listData: ["手机", "电视", "电脑"],
    },
  })
</script>

<style lang="stylus">
  .list
    background-color red
</style>

<script type="application/json">
  {
    "component": true
  }
</script>
```

更多用法可以查看我们的官方实例：<https://github.com/didi/mpx/tree/master/examples/>

## 跨平台输出 {#cross-platform-output}

如果你选择的 base 平台为微信，mpx 提供了强大的跨平台输出能力，能够将你的小程序源码输出到目前业内的全部小程序平台(微信/支付宝/百度/头条/QQ)中和 web 平台中运行。

执行以下命令进行跨平台输出

```shell
npm run build:cross
```

关于跨平台能力的更多详情请查看[这里](../advance/platform.md)

---

---
url: /guide/basic/ide.md
---
# IDE 支持 {#ide-support}

## VS Code

推荐使用的 IDE 是 [VS Code](https://code.visualstudio.com)，配合官方维护的新版本 [**Mpx (Official)**](https://marketplace.visualstudio.com/items?itemName=mpxjs.mpx-official) 插件。该插件提供了语法高亮、TypeScript 支持，以及模板内表达式与组件 props 的智能提示，提供更好的开发体验。

::: tip 注意
Mpx (Official) 现在取代了我们过去提供的插件 [mpx](https://marketplace.visualstudio.com/items?itemName=pagnkelly.mpx)、[mpx-template-features](https://marketplace.visualstudio.com/items?itemName=wangshun.mpx-template-features)。历史插件将不再维护逐步废弃，请大家及时切换到新版插件。更多历史背景及功能差异请参考[说明](https://github.com/mpx-ecology/language-tools?tab=readme-ov-file#why-new-extension)。
:::

Mpx (Official) 插件一大亮点功能是为 `<template>` 模板中的变量支持 TS 智能提示，包括类型提示、类型检查、自动补全、定义跳转等等功能。如下图所示：

![模板类型提示演示1](../../assets/images/ide-mpx-official-demo-1.png)

![模板类型检查演示2](../../assets/images/ide-mpx-official-demo-2.png)

有关更多插件详细功能介绍和使用说明，请参阅我们的[插件文档](https://github.com/mpx-ecology/language-tools/wiki)。

## Open VSX 插件生态 IDE {#open-vsx-ide}

[Open VSX](https://open-vsx.org/) 是 Visual Studio Marketplace（VS Code 官方插件市场）的开源替代方案，可以为兼容 VS Code 的 IDE 提供插件市场支持。[Mpx (Official)](https://open-vsx.org/extension/mpxjs/mpx-official) 插件支持在 Open VSX 同步发版。

目前主流的 AI IDE 比如 [Cursor](https://cursor.com/cn)、[Trae](https://www.trae.cn)、[windsurf](https://windsurf.com/) 等等，基于都是 fork VS Code 开发，内部插件市场一般由 Open VSX 提供支持。如果您使用此类 IDE 或者其他支持 Open VSX 插件源的 IDE，可直接搜索安装 Mpx (Official)。

## IntelliJ

如果使用 IntelliJ 系 IDE 开发，可将 `.mpx` 后缀文件关联到 `vue` 模板类型，按 `vue` 模板解析。

![关联文件类型](../../assets/images/start-tips2.png)

但会报一个 `warning` 提示有重复的 `script` 标签，关闭该警告即可。

![关闭警告](../../assets/images/start-tips1.png)

---

---
url: /guide/basic/project-structure.md
---
# 项目结构 {#project-structure}

一个标准的 Mpx 项目由app、pages和components组成，其中app描述整体应用的行为，pages描述应用中的各个页面，components描述构成各个页面的可复用组件。

```text
├── src
│   ├── app.mpx             # 应用入口
│   ├── pages               # 页面目录
│   │   └── index.mpx
│   └── components          # 组件目录
│       └── list.mpx
```

## 页面注册 {#page-registration}

页面需要在 `app.mpx` 的 json 配置中通过 `pages` 字段进行注册。

```json
<script type="application/json">
  {
    "pages": [
      "./pages/index"
    ]
  }
</script>
```

## 组件注册 {#component-registration}

组件需要在页面或组件的 json 配置中通过 `usingComponents` 字段进行注册。

```json
<script type="application/json">
  {
    "usingComponents": {
      "list": "../components/list"
    }
  }
</script>
```

---

---
url: /guide/basic/app.md
---
# 创建 App {#create-app}

Mpx 应用需要在 `app.mpx` 中调用 `createApp` 方法注册App实例，绑定生命周期回调函数、错误监听和页面不存在监听函数等。

## createApp

`createApp` 是 Mpx 提供的用于注册小程序实例的方法，它接受一个 Object 类型的参数，指定小程序的生命周期回调等。

```html
<script>
  import { createApp } from '@mpxjs/core'

  createApp({
    onLaunch (options) {
      // Do something initial when launch.
      console.log('App Launch')
    },
    onShow (options) {
      // Do something when show.
      console.log('App Show')
    },
    onHide () {
      // Do something when hide.
      console.log('App Hide')
    },
    onError (msg) {
      console.log(msg)
    },
    globalData: 'I am global data'
  })
</script>

<script type="application/json">
  {
    "pages": [
      "./pages/index/index"
    ],
    "window": {
      "backgroundTextStyle": "light",
      "navigationBarBackgroundColor": "#fff",
      "navigationBarTitleText": "WeChat",
      "navigationBarTextStyle": "black"
    }
  }
</script>

<style>
  /* 全局样式 */
  page {
    background-color: #f8f8f8;
  }
</style>
```

### 生命周期 {#lifecycle}

* **onLaunch(Object object)**
  小程序初始化完成时触发，全局只触发一次。
  * `object` (Object): 启动参数

* **onShow(Object object)**
  小程序启动，或从后台进入前台显示时触发。
  * `object` (Object): 启动参数

* **onHide()**
  小程序从前台进入后台时触发。

* **onError(String error)**
  小程序发生脚本错误或 API 调用报错时触发。
  * `error` (String): 错误信息

* **onPageNotFound(Object object)**
  小程序要打开的页面不存在时触发。
  * `object` (Object): 页面不存在的详细信息

* **onUnhandledRejection(Object object)**
  小程序有未处理的 Promise 拒绝时触发。
  * `object` (Object): 拒绝的详细信息

* **onThemeChange(Object object)**
  系统切换主题时触发。
  * `object` (Object): 主题信息

## getApp

整个小程序只有一个 App 实例，是全部页面共享的。开发者可以通过 `getApp` 方法获取到全局唯一的 App 实例，获取 App 上的数据或调用开发者注册在 App 上的函数。

```js
// xxx.js
const appInstance = getApp()
console.log(appInstance.globalData) // I am global data
```

> **注意**
>
> * 不要在定义于 `App()` 内的函数中，或调用 `App` 前调用 `getApp()` ，使用 `this` 就可以拿到 app 实例。
> * 通过 `getApp()` 获取实例之后，不要私自调用生命周期函数。

## App 样式 {#app-style}

在 `app.mpx` 中定义的样式为全局样式，会作用于应用中的所有页面。

```html
<!-- app.mpx -->
<style>
  page {
    background-color: #f8f8f8;
    height: 100%;
    font-size: 32rpx;
    line-height: 1.6;
  }
</style>
```

> **注意**
>
> * 全局样式会影响所有页面，但页面局部样式（在页面的 `<style>` 中定义的样式）优先级高于全局样式。
> * 可以在 `page` 选择器中定义通用的背景色、字体等样式。

## App 配置 {#app-config}

Mpx 应用的全局配置位于 `app.mpx` 的 JSON 部分，对应用进行全局配置，决定页面文件的路径、窗口表现、设置网络超时时间、设置多 tab 等。

### 配置项 {#config-items}

| 属性 | 类型 | 必填 | 描述 |
| :--- | :--- | :--- | :--- |
| pages | String\[] | 是 | 页面路径列表 |
| window | Object | 否 | 全局的默认窗口表现 |
| tabBar | Object | 否 | 底部 tab 栏的表现 |
| networkTimeout | Object | 否 | 网络超时时间 |
| debug | Boolean | 否 | 是否开启 debug 模式，默认关闭 |
| subpackages | Object\[] | 否 | 分包结构配置 |
| preloadRule | Object | 否 | 分包预下载规则 |
| workers | String | 否 | Worker 代码放置的目录 |
| requiredBackgroundModes | String\[] | 否 | 需要在后台使用的能力，如「音乐播放」 |
| plugins | Object | 否 | 使用到的插件 |
| resizable | Boolean | 否 | iPad 小程序是否支持屏幕旋转 |
| usingComponents | Object | 否 | 全局自定义组件配置 |
| permission | Object | 否 | 小程序接口权限相关设置 |
| sitemapLocation | String | 是 | 指明 sitemap.json 的位置 |
| style | String | 否 | 指定使用升级后的weui样式 |
| useExtendedLib | Object | 否 | 指定需要引用的扩展库 |
| entranceDeclare | Object | 否 | 微信消息用小程序打开 |
| darkmode | Boolean | 否 | 小程序支持 DarkMode |
| themeLocation | String | 否 | 指明 theme.json 的位置 |
| lazyCodeLoading | String | 否 | 配置自定义组件代码按需注入 |
| singlePage | Object | 否 | 单页模式相关配置 |

### pages

用于指定小程序由哪些页面组成，每一项都对应一个页面的 路径（含文件名） 信息。文件名不需要写文件后缀，Mpx 会自动去寻找对应位置的 .mpx 文件进行处理。

**注意**：

1. 数组的第一项代表小程序的初始页面（首页）。
2. 小程序中新增/减少页面，都需要对 pages 数组进行修改。

```json
{
  "pages": [
    "pages/index/index",
    "pages/logs/logs"
  ]
}
```

### window

用于设置应用的状态栏、导航条、标题、窗口背景色。

| 属性 | 类型 | 默认值 | 描述 |
| :--- | :--- | :--- | :--- |
| navigationBarBackgroundColor | HexColor | #000000 | 导航栏背景颜色 |
| navigationBarTextStyle | String | white | 导航栏标题、状态栏颜色，仅支持 black / white |
| navigationBarTitleText | String |  | 导航栏标题文字内容 |
| navigationStyle | String | default | 导航栏样式，仅支持 default / custom |
| backgroundColor | HexColor | #ffffff | 窗口的背景色 |
| backgroundTextStyle | String | dark | 下拉 loading 的样式，仅支持 dark / light |
| enablePullDownRefresh | Boolean | false | 是否开启全局的下拉刷新 |
| onReachBottomDistance | Number | 50 | 页面上拉触底事件触发时距页面底部距离，单位为 px |

```json
{
  "window": {
    "navigationBarBackgroundColor": "#ffffff",
    "navigationBarTextStyle": "black",
    "navigationBarTitleText": "微信接口功能演示",
    "backgroundColor": "#eeeeee",
    "backgroundTextStyle": "light"
  }
}
```

### tabBar

如果当前应用是一个多 tab 应用（客户端窗口的底部或顶部有 tab 栏可以切换页面），可以通过 tabBar 配置项指定 tab 栏的表现，以及 tab 对应的页面的路径。

| 属性 | 类型 | 必填 | 默认值 | 描述 |
| :--- | :--- | :--- | :--- | :--- |
| color | HexColor | 是 | | tab 上的文字默认颜色 |
| selectedColor | HexColor | 是 | | tab 上的文字选中时的颜色 |
| backgroundColor | HexColor | 是 | | tab 的背景色 |
| borderStyle | String | 否 | black | tabbar 上边框的颜色， 仅支持 black / white |
| list | Array | 是 | | tab 的列表，详见 list 属性说明，最少 2 个、最多 5 个 tab |
| position | String | 否 | bottom | tabBar 的位置，仅支持 bottom / top |
| custom | Boolean | 否 | false | 自定义 tabBar |

**list 接受一个数组，只能配置最少 2 个、最多 5 个 tab。tab 按数组的顺序排序，每个项都是一个对象，其属性值如下：**

| 属性 | 类型 | 必填 | 描述 |
| :--- | :--- | :--- | :--- |
| pagePath | String | 是 | 页面路径，必须在 pages 中存在 |
| text | String | 是 | tab 上按钮文字 |
| iconPath | String | 否 | 图片路径，icon 大小限制为 40kb，建议尺寸为 81px \* 81px，不支持网络图片 |
| selectedIconPath | String | 否 | 选中时的图片路径，icon 大小限制为 40kb，建议尺寸为 81px \* 81px，不支持网络图片 |

```json
{
  "tabBar": {
    "list": [
      {
        "pagePath": "pages/index/index",
        "text": "首页"
      },
      {
        "pagePath": "pages/logs/logs",
        "text": "日志"
      }
    ]
  }
}
```

更多配置详情请参考[微信小程序全局配置](https://developers.weixin.qq.com/miniprogram/dev/reference/configuration/app.html)。

---

---
url: /guide/basic/page.md
---
# 创建页面 {#create-page}

对于 Mpx 项目中的每个页面，都需要在对应的 `.mpx` 文件中进行定义，指定页面的初始数据、生命周期回调、事件处理函数等，并且在 `app.mpx` 中通过 `pages` 数组进行注册。

```html
<!-- app.mpx -->
<script type="application/json">
  {
    "pages": [
      "./pages/index",
      "./pages/second"
    ]
  }
</script>
```

## 页面模板 {#page-template}

页面模板的写法与组件模板相同，具体可参考[模版语法](template.md)。页面模板与页面数据结合后生成的节点树，将被渲染到页面上。

## 页面构造 {#page-constructor}

`createPage` 是 Mpx 提供的用于构造页面的方法，它接受一个 Object 类型的参数，指定页面的初始数据、生命周期回调、事件处理函数等。

```html


<script>
  import { createPage } from '@mpxjs/core'

  createPage({
    data: {
      text: 'Init Data'
    },
    onLoad (options) {
      // Do some initialize when page load.
      console.log('Page Load')
    },
    onReady () {
      // Do something when page ready.
      console.log('Page Ready')
    },
    onShow () {
      // Do something when page show.
      console.log('Page Show')
    },
    onHide () {
      // Do something when page hide.
      console.log('Page Hide')
    },
    onUnload () {
      // Do something when page close.
      console.log('Page Unload')
    },
    onPullDownRefresh () {
      // Do something when pull down.
      console.log('Pull Down Refresh')
    },
    onReachBottom () {
      // Do something when page reach bottom.
      console.log('Reach Bottom')
    },
    onShareAppMessage () {
      // return custom share data when user share.
      console.log('Share App Message')
      return {
        title: 'My Mpx Page'
      }
    },
    methods: {
      // 自定义方法
      changeText () {
        this.text = 'Changed Data'
      }
    }
  })
</script>

<script type="application/json">
  {
    "navigationBarTitleText": "首页",
    "usingComponents": {}
  }
</script>

<style>
  .container {
    padding: 20px;
  }
</style>
```

### 页面构造选项 {#page-constructor-options}

Mpx 中页面的构造选项与组件高度一致，支持 `data`、`computed`、`watch`、`methods` 等选项。

| 选项 | 说明 | 详细介绍 |
| :--- | :--- | :--- |
| data | 页面的初始数据 | [data](component.md#data) |
| computed | 计算属性，用于声明依赖于其他数据的计算属性 | [computed](component.md#computed) |
| watch | 侦听器，用于监听数据的变化并执行相应的回调 | [watch](component.md#watch) |
| methods | 页面方法，包括事件响应函数和任意的自定义方法 | [methods](component.md#methods) |
| provide / inject | 依赖注入，用于跨层级组件分发数据 | [provide / inject](./component.md#provide-inject) |
| setup | 组合式 API 入口，返回页面所需的数据和方法 | [setup](component.md#setup) |

> **注意**
>
> * Mpx 底层默认使用 Component 构造器创建页面，因此自定义方法需要放置在 `methods` 选项中，这与原生小程序 Page 构造器直接挂载在配置对象下不同。
> * Mpx 对 `data` 进行了响应式处理，直接修改 `this.text = 'xxx'` 即可驱动视图更新，无需调用 `this.setData`。

### 页面生命周期 {#page-lifecycle}

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

* **onShow()**
  页面显示/切入前台时触发。

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

* **onHide()**
  页面隐藏/切入后台时触发。

* **onUnload()**
  页面卸载时触发。

* **onPullDownRefresh()**
  监听用户下拉刷新事件。

* **onReachBottom()**
  监听用户上拉触底事件。

* **onShareAppMessage(Object object)**
  监听用户点击页面内转发按钮（button 组件 open-type="share"）或右上角菜单“转发”按钮的行为，并自定义转发内容。

* **onPageScroll(Object object)**
  监听用户滑动页面事件。

* **onResize(Object object)**
  页面尺寸改变时触发。

* **onTabItemTap(Object object)**
  当前是 tab 页时，点击 tab 时触发。

### 页面实例方法 {#page-instance-methods}

页面实例除了具备组件实例的大部分方法外，还具有一些特有的属性和方法。

| 方法/属性 | 说明 | 详细介绍 |
| :--- | :--- | :--- |
| route | 当前页面的路径，类型为 String | - |
| getPageId | 返回页面标识符 | [getPageId](component.md#getpageid) |
| selectComponent | 使用选择器选择组件实例节点 | [selectComponent](component.md#selectcomponent) |
| selectAllComponents | 使用选择器选择组件实例节点，返回全部匹配节点 | [selectAllComponents](component.md#selectallcomponents) |
| createSelectorQuery | 创建一个 SelectorQuery 对象 | [createSelectorQuery](component.md#createselectorquery) |
| createIntersectionObserver | 创建一个 IntersectionObserver 对象 | [createIntersectionObserver](component.md#createintersectionobserver) |
| $watch | 动态创建一个侦听器 | [$watch](component.md#watch) |
| $forceUpdate | 强制更新视图 | [$forceUpdate](component.md#forceupdate) |
| $nextTick | 延迟到下次 DOM 更新循环之后执行 | [$nextTick](component.md#nexttick) |
| $set | 向响应式对象中添加一个 property | [$set](component.md#set) |
| $delete | 删除对象的 property | [$delete](component.md#delete) |

## 页面样式 {#page-style}

页面样式主要用于控制页面内的元素外观，在 Mpx 中，样式直接编写在 `.mpx` 单文件中的 `<style>` 标签内。

### 全局样式与局部样式 {#global-and-local-style}

定义在 `app.mpx` 的 `<style>` 标签中的样式为全局样式，作用于每一个页面。在页面的 `.mpx` 文件中 `<style>` 标签定义的样式为局部样式，只作用于当前页面，并会覆盖全局样式中相同的选择器。

```html
<!-- app.mpx -->
<style>
  .container {
    padding: 20px;
  }
</style>

<!-- page.mpx -->
<style>
  .container {
    padding: 10px; /* 覆盖全局样式 */
  }
</style>
```

### 样式导入 {#style-import}

可以使用 `@import` 语句导入外联样式表。

```html
<style>
  @import './common.wxss';
  
  .page-container {
    background-color: #f8f8f8;
  }
</style>
```

## 页面配置 {#page-config}

`app.json` 中的部分配置，也支持对单个页面进行配置，可以在页面对应的 `<script type="application/json">` 块中来对本页面的表现进行配置。

页面中配置项在当前页面会覆盖 `app.json` 中相同的配置项（样式相关的配置项属于 `app.json` 中的 `window` 属性，但这里不需要额外指定 `window` 字段）。

### 配置项 {#config-items}

| 属性 | 类型 | 默认值 | 描述 |
| :--- | :--- | :--- | :--- |
| navigationBarBackgroundColor | HexColor | #000000 | 导航栏背景颜色，如 #000000 |
| navigationBarTextStyle | string | white | 导航栏标题、状态栏颜色，仅支持 black / white |
| navigationBarTitleText | string | | 导航栏标题文字内容 |
| navigationStyle | string | default | 导航栏样式，仅支持 default/custom |
| backgroundColor | HexColor | #ffffff | 窗口的背景色 |
| backgroundTextStyle | string | dark | 下拉 loading 的样式，仅支持 dark / light |
| enablePullDownRefresh | boolean | false | 是否开启当前页面下拉刷新 |
| onReachBottomDistance | number | 50 | 页面上拉触底事件触发时距页面底部距离，单位为px |
| disableScroll | boolean | false | 设置为 true 则页面整体不能上下滚动 |
| usingComponents | Object | 否 | 页面自定义组件配置 |

### 配置示例 {#config-example}

```html
<script type="application/json">
  {
    "navigationBarBackgroundColor": "#ffffff",
    "navigationBarTextStyle": "black",
    "navigationBarTitleText": "微信接口功能演示",
    "backgroundColor": "#eeeeee",
    "backgroundTextStyle": "light"
  }
</script>
```

更多配置项细节请参考[小程序页面配置](https://developers.weixin.qq.com/miniprogram/dev/reference/configuration/page.html)

---

---
url: /guide/basic/component.md
---
# 创建组件 {#create-component}

在 Mpx 中也可以使用类似 Vue 中的单文件自定义组件，我们可以在每个组件内封装自定义内容和逻辑。

在 Mpx 中自定义组件，语法默认以微信小程序为基准，与此同时，Mpx 额外提供的数据响应和模版增强语法等一系列增强能力都可以在自定义组件中使用。

> 作为参考，原生小程序自定义组件的规范详情查看[这里](https://developers.weixin.qq.com/miniprogram/dev/reference/api/Component.html)，但在 Mpx 中自定义组件所支持的属性和功能还需以当前文档为准。

## 创建与使用 {#create-and-use}

使用 [createComponent](../../api/global-api.md#createcomponent) 方法创建自定义组件，在父组件/页面中通过 `usingComponents` 注册使用。

```html
<!--组件 components/list.mpx-->
<template>
  <view>组件名称: {{ name }}</view>
</template>
<script>
  import { createComponent } from '@mpxjs/core'
  createComponent({
    data: {
      name: 'list',
    },
  })
</script>

<!--页面 index.mpx-->
<template>
  <view>
    <list></list>
  </view>
</template>
<script>
  import { createPage } from '@mpxjs/core'
  createPage({})
</script>
<script type="application/json">
  {
    "usingComponents": {
      "list": "components/list"
    }
  }
</script>
```

## 组件模板 {#component-template}

组件模板的写法与页面模板相同，具体可参考[模版语法](template.md)。组件模板与组件数据结合后生成的节点树，将被插入到组件的引用位置上。

### 组件模板的 slot {#component-template-slot}

在组件模板中可以包含 slot 节点，用于承载组件使用者提供的模板结构。

默认情况下，一个组件模板中只能有一个 slot 。需要使用多 slot 时，可以在组件 js 中声明启用。

此时，可以在这个组件模板中使用多个 slot ，以不同的 name 来区分。

使用时，用 slot 属性来将节点插入到不同的 slot 上。

```html
<!-- 组件模板 -->
<!-- components/mySlot.mpx -->
<template>
  <view>
    <view>这是组件模板</view>
    <slot name="slot1"></slot>
    <slot name="slot2"></slot>
  </view>
  <template>
    <script>
      import { createComponent } from '@mpxjs/core'

      createComponent({
        options: {
          multipleSlots: true, // 启用多slot支持
        },
      })
    </script></template
  ></template
>
```

> 注意：使用多个 slot 时，需要在组件选项中开启 `multipleSlots: true`。

使用组件时：

```html
<!-- index.mpx -->
<template>
  <view>
    <my-slot>
      <view slot="slot1">我是slot1中的内容</view>
      <view slot="slot2">我是slot2中的内容</view>
    </my-slot>
  </view>
</template>

<script type="application/json">
  {
    "usingComponents": {
      "my-slot": "components/mySlot"
    }
  }
</script>
```

更多关于插槽的使用细节可查看[微信小程序官方文档](https://developers.weixin.qq.com/miniprogram/dev/framework/custom-component/wxml-wxss.html)。

### 动态组件 {#dynamic-component}

Mpx 中提供了使用方法类似于 Vue 的动态组件能力，这是一个基于 wx:if 实现的语法。通过对 `is` 属性进行动态绑定，可以实现在同一个挂载点切换多个组件，前提需要动态切换的组件已经在全局或者组件中完成注册。

使用示例如下：

```html
<view>
  <!-- current为组件名称字符串，可选范围为局部注册的自定义组件和全局注册的自定义组件 -->
  <!-- 当 `current`改变时，组件也会跟着切换  -->
  <component is="{{current}}"></component>
</view>

<script>
  import { createComponent } from '@mpxjs/core'
  createComponent({
    data: {
      current: 'test',
    },
    ready() {
      setTimeout(() => {
        this.current = 'list'
      }, 3000)
    },
  })
</script>

<script type="application/json">
  {
    "usingComponents": {
      "list": "../components/list",
      "test": "../components/test"
    }
  }
</script>
```

## 组件构造 {#component-construction}

下面详细介绍 `createComponent` 所支持的构造选项。

### data

组件的内部数据，和 properties 一同用于组件的模板渲染。

```ts
interface ComponentOptions {
  data?: object | (() => object)
}
```

data 可以是一个函数返回一个普通 JavaScript 对象，也可以是一个普通 JavaScript 对象。

关于 data 的响应式特性及详细使用，请参考 [data](reactive.md#data)。

### properties

用于声明组件接收的外部属性。属性的类型可以为 String、Number、Boolean、Object、Array 其一，也可以为 null 表示不限制类型。

```ts
type PropType =
  | StringConstructor // String
  | NumberConstructor // Number
  | BooleanConstructor // Boolean
  | ObjectConstructor // Object
  | ArrayConstructor // Array;
  | null // null

interface ComponentOptions {
  properties?: {
    [key: string]: PropOptions | PropType
  }
}

interface PropOptions {
  type: PropType // type 为必填项
  value?: any
  optionalTypes?: PropType[] // 属性的类型（可以指定多个）
  observer?: string | ((newVal: any, oldVal: any) => void)
}
```

properties 定义包含以下选项：

* **`type`**: 必填，属性的类型
* **`optionalTypes`**: 可选，属性的类型（可以指定多个）
* **`value`**: 可选，属性的初始值
* **`observer`**: 可选，属性值变化时的回调函数

> **注意：**
>
> 1. 属性名应避免以 data 开头，例如 data-xyz="" 会被作为节点 dataset 来处理
> 2. 在组件定义和使用时，属性名和 data 字段相互间都不能冲突

关于 properties 的响应式特性及详细使用，请参考 [properties](reactive.md#properties)。

### computed

用于声明基于现有数据的计算属性。

```ts
type ComputedGetter<T> = () => T
type ComputedSetter<T> = (value: T) => void

interface WritableComputedOptions<T> {
  get: ComputedGetter<T>
  set: ComputedSetter<T>
}

// 计算属性可以是函数或对象
type ComputedOption<T> = ComputedGetter<T> | WritableComputedOptions<T>

// 组件选项的接口
interface ComponentOptions {
  computed?: {
    [K: string]: ComputedOption<any>
  }
}
```

该选项接收一个对象，其中键是计算属性的名称，值是一个计算属性 getter，或一个具有 get 和 set 方法的对象 (用于声明可写的计算属性)。

关于 computed 的缓存特性及详细使用，请参考 [计算属性 (Computed)](reactive.md#computed)。

### watch

用于对响应性数据变化调用的侦听回调。

```ts
// flush 选项的可选值类型
type FlushMode = 'sync' | 'post' | 'pre'

interface ComponentOptions {
  watch?: {
    [key: string]: WatchOption | WatchCallback | string
  }
}

type WatchCallback = (newValue: any, oldValue: any) => void

interface WatchOption {
  handler: WatchCallback | string
  immediate?: boolean // 是否立即执行
  deep?: boolean // 是否深度监听
  flush?: FlushMode // 回调的执行时机
}
```

watch 选项用于监听数据的变化并执行相应的回调函数。支持以下功能：

* 监听单个或多个数据源
* 深度监听（deep）
* 立即执行（immediate）
* 执行时机控制（flush）
  * `'sync'`: 同步执行，立即触发回调
  * `'post'`: 视图更新后执行（默认值）
  * `'pre'`: 视图更新前执行

关于 watch 的详细使用及异步更新策略，请参考 [侦听器 (Watch)](reactive.md#watch)。

### methods

用于声明组件的方法。

```ts
interface ComponentOptions {
  methods?: {
    [key: string]: (...args: any[]) => any
  }
}
```

methods 选项用于声明组件实例可以访问的方法。所有方法的 this 上下文会自动绑定为组件实例。

```js
createComponent({
  methods: {
    handleClick() {
      // 访问数据
      console.log(this.message)
      // 调用其他方法
      this.otherMethod()
    },
    otherMethod() {
      // ...
    },
  },
})
```

### provide / inject

`provide` 和 `inject` 提供了一种跨层级组件分发数据的方法。

父组件作为依赖提供者，其后代组件（无论层级多深）都可以注入该依赖。

```js
// 父组件
createComponent({
  data: {
    s: 'foo'
  },
  provide() {
    return {
      s: this.s
    }
  }
})

// 后代组件
createComponent({
  inject: ['s'],
  ready() {
    console.log(this.s) // "foo"
  }
})
```

详情请查看[依赖注入](../advance/provide-inject.md)

### mixins

一个包含组件选项对象的数组，这些选项都将被混入到当前组件的实例中。

详情请查看[mixins](../advance/mixin.md)

### setup

`setup` 函数在组件创建时执行，返回组件所需的数据和方法，是组合式 API 的核心。

```js
import { createComponent, ref, onMounted, onUnmounted } from '@mpxjs/core'

createComponent({
  properties: {
    user: String,
  },
  setup(props) {
    const repositories = ref([])
    const getUserRepositories = async () => {
      repositories.value = await fetchUserRepositories(props.user)
    }

    // 注册生命周期钩子
    onMounted(() => {
      console.log('Component mounted.')
      getUserRepositories()
    })

    onUnmounted(() => {
      console.log('Component unmounted.')
    })

    return {
      repositories,
      getUserRepositories,
    }
  },
})
```

详情请查看[组合式 API](../composition-api/composition-api.md)

### relations

用于定义组件间的关系，支持父子、祖孙等关系，实现组件间的通信与控制。

该特性 base 微信小程序平台，在 Mpx 中使用该特性需要注意，输出微信小程序平台时能力完全支持，跨端输出其他平台时受制于平台底层能力，无法完全做抹平支持。

| 平台         | 支持情况 | 说明                                        |
| ------------ | -------- | ------------------------------------------- |
| 微信小程序   | 完全支持 | 完全支持 relations 能力                     |
| 支付宝小程序 | 部分支持 | 部分支持，不支持 linkChanged 和 target 能力 |
| 百度小程序   | 不支持   | 不支持使用 relations                        |
| QQ 小程序    | 完全支持 | 完全支持 relations 能力                     |
| 字节小程序   | 部分支持 | 部分支持，不支持 linkChanged 能力           |
| Web          | 部分支持 | 部分支持，不支持 linkChanged 和 target 能力 |
| RN           | 不支持   | 不支持使用 relations                        |

因此需要注意，在使用 realtions 能力跨平台时需要做好平台条件编译。

```ts
interface RelationOption {
  type: 'parent' | 'child' | 'ancestor' | 'descendant' // 关系类型
  linked?: (target: any) => void // 关系建立时的回调
  linkChanged?: (target: any) => void // 关系变化时的回调
  unlinked?: (target: any) => void // 关系解除时的回调
  target?: string // 关联的 behavior
}

interface ComponentOptions {
  relations?: {
    [componentPath: string]: RelationOption
  }
}
```

relations 支持以下功能：

* 定义组件间的层级关系
* 监听关系的生命周期
* 获取关联的组件实例
* 关联使用相同 behavior 的组件

详情可参考[微信小程序-relations](https://developers.weixin.qq.com/miniprogram/dev/framework/custom-component/relations.html)

```js
// custom-ul 组件
import { createComponent } from '@mpxjs/core'
createComponent({
  relations: {
    './custom-li': {
      type: 'child', // 关联的目标节点应为子节点
      linked(target) {
        // 每次有 custom-li 被插入时执行
        console.log('li linked', target)
      },
      unlinked(target) {
        // 每次有 custom-li 被移除时执行
        console.log('li unlinked', target)
      },
    },
  },
})

// custom-li 组件
import { createComponent } from '@mpxjs/core'
createComponent({
  relations: {
    './custom-ul': {
      type: 'parent', // 关联的目标节点应为父节点
      linked(target) {
        // 每次被插入到 custom-ul 时执行
        console.log('ul linked', target)
      },
    },
  },
})
```

### options

开启组件的部分特性时需要设置的选项，例如 virtualHost 、 multipleSlots 之类特性。

```ts
interface ComponentOptions {
  options?: {
    virtualHost?: boolean // 设置组件是否为虚拟节点
    styleIsolation?:
      | 'isolated'
      | 'apply-shared'
      | 'shared'
      | 'page-isolated'
      | 'page-apply-shared'
      | 'page-shared' // 设置样式隔离选项
    multipleSlots?: boolean // 启用多 slot 支持
    addGlobalClass?: boolean // 允许组件的样式影响到外部
  }
}
```

options 支持以下配置：

* **virtualHost**: 设置组件是否存在实体 Host 根节点
* **styleIsolation**: 设置组件样式隔离选项
* **multipleSlots**: 是否启用多 slot 支持，仅微信和 QQ 需要配置
* **addGlobalClass**: 是否允许组件的样式影响外部

但需要注意的是，此处的 options 配置为 base 微信小程序的语法特性，在跨端输出其他平台时，由于依赖平台底层能力支持与否，因此无法做到全部功能抹平。

| 选项           | 微信 | 支付宝   | 百度 | QQ  | 字节 | Web      | RN       | 说明                                                                                                                                                                                                  |
| -------------- | ---- | -------- | ---- | --- | ---- | -------- | -------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| virtualHost    | ✓    | 依赖编译 | ✗    | ✓   | ✓    | 依赖编译 | 依赖编译 | Mpx 跨端输出支付宝、web 和 RN 时需要通过[autoVirtualHostRules 编译配置](../../api/compile.md#autovirtualhostrules)控制在编译时模拟实现该行为                                             |
| styleIsolation | ✓    | 依赖编译 | ✗    | ✓   | ✗    | 依赖编译 | ✗        | 微信默认开启样式隔离，输出支付宝和 web 可以通过[autoScopeRules 编译配置](../../api/compile.md#autoscoperules)或在 style 标签中添加 scoped 属性模拟实现样式隔离，输出 RN 目前强制样式隔离 |
| multipleSlots  | ✓    | -        | -    | ✓   | -    | -        | -        | 目前仅微信和 QQ 使用多个 slot 需要配置 multipleSlots，其他平台默认支持使用多 slot                                                                                                                     |

> **注意：**
> virtualHost 在支付宝平台默认为 false
> options 中的特性以微信小程序为 base，随着微信小程序的持续迭代，此处列出的特性可能会存在部分缺失。

### 生命周期 {#lifecycle}

在 Mpx 内组件生命周期可以使用[框架内置生命周期](框架内置生命周期)，也可以使用以微信原生 base 的生命周期，在使用微信原生 base 的生命周期时，在跨平台输出时，框架会对生命周期进行映射抹平，将不同小程序平台的生命周期转换映射为内置生命周期后再进行统一的驱动，以抹平不同小程序平台生命周期钩子的差异。

在选项式 API 中，可以使用微信 base 或者 Mpx 框架暴露的内置生命周期。

微信原生生命周期：

| 生命周期 | 说明                         |
| -------- | ---------------------------- |
| created  | 在组件实例初始化完成时调用   |
| attached | 在组件挂载开始之前调用       |
| ready    | 在组件在视图层布局完成后调用 |
| detached | 在组件实例销毁时调用         |

在组合式 API 中，需要使用框架暴露的统一的[生命周期钩子](../../api/composition-api.md#lifecycle-hooks)

### 页面生命周期 {#page-lifecycle}

组件中访问页面生命周期

在选项式中可以直接使用 pageLifetimes.show 之类的配置：

| 生命周期 | 说明                     |
| -------- | ------------------------ |
| show     | 组件所在页面显示         |
| hide     | 组件所在页面隐藏         |
| resize   | 组件所在页面尺寸发生变化 |

在组合式 API 中，需要使用框架暴露的 onShow、onHide、onResize，详情可[查看](../../api/composition-api.md#lifecycle-hooks)

## 组件实例方法 {#component-instance-methods}

### triggerEvent

触发事件，参见[组件间通信与事件](https://developers.weixin.qq.com/miniprogram/dev/framework/custom-component/events.html)。

```ts
interface ComponentInstance {
  triggerEvent(
    name: string,
    detail?: object,
    options?: {
      bubbles?: boolean
      composed?: boolean
      capturePhase?: boolean
    }
  ): void
}
```

### getPageId

返回页面标识符（一个字符串），可以用来判断几个自定义组件实例是不是在同一个页面内。

```ts
interface ComponentInstance {
  getPageId(): string
}
```

### selectComponent

使用选择器选择组件实例节点，返回匹配到的第一个组件实例对象。

```ts
interface ComponentInstance {
  selectComponent(selector: string): object
}
```

### selectAllComponents

使用选择器选择组件实例节点，返回匹配到的全部组件实例对象组成的数组

```ts
interface ComponentInstance {
  selectAllComponents(selector: string): object[]
}
```

### createSelectorQuery

创建一个 SelectorQuery 对象，选择器选取范围为这个组件实例内。

```ts
interface ComponentInstance {
  createSelectorQuery(): SelectorQuery
}
```

### createIntersectionObserver

创建一个 IntersectionObserver 对象，选择器选取范围为这个组件实例内。

```ts
interface ComponentInstance {
  createIntersectionObserver(options?: {
    thresholds?: number[]
    initialRatio?: number
    observeAll?: boolean
  }): IntersectionObserver
}
```

### $watch

用于动态地创建一个侦听器，返回一个取消观察函数。

详细用法请参考 [实例方法 $watch](reactive.md#instance-method-watch)。

### $forceUpdate

无视数据响应特性强制更新视图，输出小程序时支持传入 data 参数，精确控制底层 setData 发送的数据。

```ts
interface ComponentInstance {
  $forceUpdate(data?: Record<string, any>): void
}
```

### $nextTick

将回调延迟到下次 DOM 更新循环之后执行。在修改数据之后立即使用它，然后等待 DOM 更新。

详细用法请参考 [异步更新队列](reactive.md#async-update-queue)。

### $set

向响应式对象中添加一个 property，并确保这个新 property 同样是响应式的，且触发视图更新。

详细用法请参考 [检测变化的注意事项 - 对象](reactive.md#objects)。

### $delete

删除对象的 property。如果对象是响应式的，确保删除能触发更新视图。

详细用法请参考 [检测变化的注意事项 - 对象](reactive.md#objects)。

## 组件样式 {#component-style}

组件对应 wxss 文件的样式，只对组件模板内的节点生效。编写组件样式时，需要注意以下几点：

* 组件和引用组件的页面不能使用 id 选择器（#a）、属性选择器（\[a]）和标签名选择器，请改用 class 选择器。
* 组件和引用组件的页面中使用后代选择器（.a .b）在一些极端情况下会有非预期的表现，如遇，请避免使用。
* 子元素选择器（.a>.b）只能用于 view 组件与其子节点之间，用于其他组件可能导致非预期的情况。
* 继承样式，如 font 、 color ，会从组件外继承到组件内。
* 除继承样式外， app.wxss 中的样式、组件所在页面的的样式对自定义组件无效（除非更改组件样式隔离选项）。

```css
#a {
} /* 在组件中不能使用 */
[a] {
} /* 在组件中不能使用 */
button {
} /* 在组件中不能使用 */
.a > .b {
} /* 除非 .a 是 view 组件节点，否则不推荐使用 */
```

除此以外，组件可以指定它所在节点的默认样式，使用 :host 选择器。

```css
/* 组件 custom-component.wxss */
:host {
  color: yellow;
}
```

### 外部样式类 {#external-style-class}

有时，组件希望接受外部传入的样式类。此时可以在 Component 中用 externalClasses 定义段定义若干个外部样式类。

这个特性可以用于实现类似于 view 组件的 hover-class 属性：页面可以提供一个样式类，赋予组件的 hover-class ，这个样式类本身定义在页面中而非组件中。

```ts
interface ComponentOptions {
  externalClasses?: string[]
}
```

externalClasses 支持以下功能：

* 定义多个外部样式类
* 在组件 template 中使用外部样式类，同时支持在同一个节点上使用多个外部样式类

```html
<template>
  <!-- 组件 custom-component.mpx -->
  <view class="my-class"> 外部传入的样式类 </view>
  <view class="other-class"> 另一个外部传入的样式类 </view>
</template>
<script>
  // 组件 custom-component.js
  import { createComponent } from '@mpxjs/core'

  createComponent({
    externalClasses: ['my-class', 'other-class'],

    options: {
      styleIsolation: 'isolated',
    },
  })
</script>
```

使用组件：

```html
<!-- 页面 page.mpx -->
<!-- 单个样式类 -->
<custom-component my-class="red-text" />

<!-- 多个样式类（需要基础库 2.7.1 以上） -->
<custom-component my-class="red-text large-text" />

<!-- 动态样式类 -->
<custom-component my-class="{{isActive ? 'active' : ''}}" />
```

```css
/* 页面 page style */
.red-text {
  color: red;
}

.large-text {
  font-size: 20px;
}

.active {
  background: #f0f0f0;
}
```

关于 externalclasses 的更多描述也可以查看[微信小程序-外部样式类](https://developers.weixin.qq.com/miniprogram/dev/framework/custom-component/wxml-wxss.html#%E5%A4%96%E9%83%A8%E6%A0%B7%E5%BC%8F%E7%B1%BB)

> **注意：**
>
> * 该功能默认在微信小程序可用，在跨平台输出时，需要在 @mpxjs/webpack-plugin 中配置相关的 externalClasses, 否则跨平台时该能力不生效，具体配置请[查看](../../api/compile.md#externalclasses)。

## 组件配置 {#component-config}

在组件的 `json` 文件中，可以配置以下字段：

| 属性              | 类型    | 必填 | 描述                                     |
| :---------------- | :------ | :--- | :--------------------------------------- |
| component         | Boolean | 是   | 声明这是一个自定义组件，必须设为 true    |
| usingComponents   | Object  | 否   | 引用自定义组件，组件名为键，值为组件路径 |
| componentGenerics | Object  | 否   | 组件泛型（抽象节点）声明                 |

### componentGenerics

组件泛型（抽象节点）用于在组件中声明一个节点，其对应的实际组件由组件的使用者决定。这使得组件可以接受不同的子组件，增强了组件的复用性。

#### 在组件中使用 {#use-in-component}

首先，在组件的 JSON 中声明抽象节点：

```json
{
  "componentGenerics": {
    "selectable": true
  }
}
```

其中 `"selectable"` 是抽象节点的名称。

然后，在组件模板中直接使用该名称：

```html
<!-- components/selectable-group.mpx -->
<view>
  <label>请选择</label>
  <selectable disabled="{{false}}"></selectable>
</view>
```

#### 使用包含抽象节点的组件 {#use-component-with-abstract-node}

在使用该组件的页面或父组件中，需要通过 `generic:xxx="yyy"` 属性来指定具体的组件：

```html
<!-- pages/index.mpx -->
<selectable-group generic:selectable="custom-radio" />
```

注意：

1. `custom-radio` 必须在当前页面的 JSON `usingComponents` 中注册。
2. `generic:xxx` 的值只能是静态字符串，不支持数据绑定。

#### 指定默认组件 {#specify-default-component}

可以在声明抽象节点时指定一个默认组件，当使用者未指定具体组件时，将使用默认组件：

```json
{
  "componentGenerics": {
    "selectable": {
      "default": "path/to/default/component"
    }
  }
}
```

---

---
url: /guide/basic/single-file.md
---
# 单文件开发 {#single-file-development}

小程序规范中每个页面和组件都是由四个文件描述组成的，wxml/js/wxss/json，分别描述了组件/页面的视图模板，执行逻辑，样式和配置，由于这四个部分彼此之间存在相关性，比如模板中的组件需要在json中注册，数据需要在js中定义，这种离散的文件结构在实际开发的时候体验并不理想；受Vue单文件开发的启发，Mpx也提供了类似的单文件开发模式，拓展名为.mpx。

从下面的简单例子可以看出，.mpx中的四个区块分别对应了原生规范中的四个文件，Mpx在执行编译构建时会通过内置的`mpx-loader`收集依赖，并将.mpx的文件转换输出为原生规范中的四个文件。

```html
<!--对应wxml文件-->
<template>
  <list></list>
</template>
<!--对应js文件-->
<script>
  import { createPage } from '@mpxjs/core'

  createPage({
    onLoad () {
    },
    onReady () {
    }
  })
</script>
<!--对应wxss文件-->
<style lang="stylus">
</style>
<!--对应json文件-->
<script type="application/json">
  {
    "usingComponents": {
      "list": "../components/list"
    }
  }
</script>
```

---

---
url: /guide/basic/reactive.md
---
# 数据响应 {#reactivity}

Mpx 的核心特性之一是其非侵入性的响应式系统。数据模型仅仅是普通的 JavaScript 对象。而当你修改它们时，视图会进行更新。这使得状态管理非常简单直接。

Mpx 参考了 Vue 2 的设计，在内部实现了一套精简高效的数据响应系统。

## 响应式原理 {#reactivity-principle}

当你把一个普通的 JavaScript 对象传入 Mpx 实例作为 `data` 选项，Mpx 将遍历此对象所有的属性，并使用 [Object.defineProperty](https://developer.mozilla.org/zh-CN/docs/Web/JavaScript/Reference/Global_Objects/Object/defineProperty) 把这些属性全部转为 getter/setter。

这些 getter/setter 对用户来说是不可见的，但是在内部它们让 Mpx 追踪依赖，在属性被访问和修改时通知变更。

每个组件实例都对应一个 **watcher** 实例，它会在组件渲染的过程中把“接触”过的数据属性记录为依赖。之后当依赖项的 setter 触发时，会通知 watcher，从而使它关联的组件重新渲染。

## data

* **类型**：`Object | Function`

`data` 选项用于声明组件的初始响应式数据。

`data` 可以是一个普通 JavaScript 对象，也可以是一个返回对象的函数。

```js
createComponent({
  // 方式一：使用对象
  data: {
    message: 'Hello'
  }
})

createComponent({
  // 方式二：使用函数
  data() {
    return {
      message: 'Hello'
    }
  }
})
```

### 响应式代理 {#reactive-proxy}

Mpx 会递归地将 `data` 的 property 转换为 getter/setter，从而让 `data` 的 property 能够响应数据变化。对象必须是纯粹的对象 (含有零个或多个的 key/value 对)。

实例创建之后，可以通过 `this.key` 直接访问 `data` 中的数据，也可以通过 `this.key = value` 修改数据。

```js
createComponent({
  data: {
    a: 1
  },
  ready() {
    console.log(this.a) // 1
    this.a = 2
    console.log(this.a) // 2
  }
})
```

> **注意**：
> 只有当实例被创建时就已经存在于 `data` 中的 property 才是**响应式**的。也就是说，如果你在 `data` 中没有声明 `b`，然后通过 `this.b = 'hi'` 来添加它，那么对 `b` 的改动将不会触发任何视图更新。

## properties

`properties` 选项用于定义组件的对外属性，与微信小程序原生组件的 `properties` 定义类似。

与 `data` 类似，Mpx 也会对 `properties` 进行响应式处理，将其代理到组件实例上。这意味着你可以直接通过 `this.propertyName` 访问这些属性，它们同样遵循响应式规则，可以作为计算属性的依赖或被侦听器监听。

```js
createComponent({
  properties: {
    title: {
      type: String,
      value: 'Default Title'
    }
  },
  computed: {
    upperTitle() {
      return this.title.toUpperCase()
    }
  },
  watch: {
    title(newVal, oldVal) {
      console.log('Title changed:', newVal)
    }
  },
  ready() {
    // 与访问 data 数据一样，可以直接通过 this 访问 properties
    console.log(this.title)
  }
})
```

## 计算属性 (Computed) {#computed}

对于任何复杂逻辑，你都应当使用**计算属性**。计算属性是基于它们的响应式依赖进行缓存的。只在相关响应式依赖发生改变时它们才会重新求值。这就意味着只要 `message` 还没有发生改变，多次访问 `reversedMessage` 计算属性会立即返回之前的计算结果，而不必再次执行函数。

### 基础用法 {#computed-basic-usage}

最常见的用法是提供一个 getter 函数：

```js
createComponent({
  data: {
    message: 'Hello'
  },
  computed: {
    // 计算属性的 getter
    reversedMessage: function () {
      // `this` 指向组件实例
      return this.message.split('').reverse().join('')
    }
  }
})
```

### Computed Setter {#computed-setter}

计算属性默认只有 getter，不过在需要时你也可以提供一个 setter：

```js
createComponent({
  data: {
    firstName: 'Foo',
    lastName: 'Bar'
  },
  computed: {
    fullName: {
      // getter
      get() {
        return this.firstName + ' ' + this.lastName
      },
      // setter
      set(newValue) {
        var names = newValue.split(' ')
        this.firstName = names[0]
        this.lastName = names[names.length - 1]
      }
    }
  }
})
// 运行 this.fullName = 'John Doe' 时，setter 会被调用，
// this.firstName 和 this.lastName 也会相应地被更新。
```

## 侦听器 (Watch) {#watch}

虽然计算属性在大多数情况下更合适，但有时也需要一个自定义的侦听器。这就是为什么 Mpx 通过 `watch` 选项提供了一个更通用的方法，来响应数据的变化。当需要在数据变化时执行异步或开销较大的操作时，这个方式是最有用的。

### 基础用法 {#watch-basic-usage}

```js
createComponent({
  data: {
    question: '',
  },
  watch: {
    // 只要 question 发生改变，这个函数就会执行
    question(newQuestion, oldQuestion) {
      console.log('new question is: ' + newQuestion)
    }
  }
})
```

### 侦听器选项 {#watch-options}

除了直接传入回调函数外，`watch` 还支持对象格式，提供更丰富的选项控制。

#### immediate

如果需要在侦听器创建时立即触发回调，可以设置 `immediate: true`。

```js
watch: {
  question: {
    handler(newQuestion, oldQuestion) {
      console.log('new question is: ' + newQuestion)
    },
    immediate: true
  }
}
```

#### deep

默认情况下，侦听器只监听数据本身的引用变化。如果需要监听对象内部值的变化（嵌套监听），需要设置 `deep: true`。

```js
createComponent({
  data: {
    user: {
      name: 'John',
      age: 20
    }
  },
  watch: {
    user: {
      handler(val) {
        console.log('user changed')
      },
      deep: true
    }
  }
})
```

> **注意**：`deep` 选项会递归遍历所有嵌套属性，开销较大，请按需使用。

#### flush

`flush` 选项用于控制回调的触发时机。

* `'post'` (默认): 在视图更新之后触发。
* `'sync'`: 同步触发，在数据变化时立即执行。
* `'pre'`: 在视图更新之前触发。

```js
watch: {
  count: {
    handler(val) {
      console.log('count changed')
    },
    flush: 'sync'
  }
}
```

### 监听多路径 {#watch-multi-path}

Mpx 支持在 watch 的 key 中使用逗号分隔的字符串来同时监听多个数据源。当其中任意一个数据源发生变化时，回调函数都会被执行。

此外，你也可以监听嵌套路径，或者传入一个数组来同时执行多个回调：

```js
watch: {
  // 监听多个数据源
  'a, b': function (val, oldVal) {
    console.log('a or b changed')
  },
  // 监听嵌套路径
  'user.name': function (val) {
    console.log('user.name changed')
  },
  // 多个回调
  count: [
    'methodName', // 方法名
    function (val) {
      console.log('callback 2')
    }
  ]
}
```

### 实例方法 $watch {#instance-method-watch}

除了在组件选项中定义 `watch`，你还可以使用组件实例方法 `this.$watch` 动态创建一个侦听器：

```js
// 键路径
this.$watch('a.b.c', function (newVal, oldVal) {
  // 做点什么
})

// 函数
this.$watch(
  function () {
    return this.a + this.b
  },
  function (newVal, oldVal) {
    // 做点什么
  }
)
```

`$watch` 返回一个取消观察函数，用来停止触发回调：

```js
var unwatch = this.$watch('a', cb)
// 之后取消观察
unwatch()
```

## 异步更新队列 {#async-update-queue}

可能你还没有注意到，Mpx 在更新视图时是**异步**的。只要侦听到数据变化，Mpx 将开启一个队列，并缓冲在同一事件循环中发生的所有数据变更。如果同一个 watcher 被多次触发，只会被推入到队列中一次。这种在缓冲时去除重复数据对于避免不必要的计算和视图更新是非常重要的。然后，在下一个的事件循环“tick”中，Mpx 刷新队列并执行实际 (已去重的) 工作。

例如，当你设置 `vm.someData = 'new value'`，该组件不会立即重新渲染。当刷新队列时，组件会在下一个事件循环“tick”中更新。如果你想基于更新后的 DOM 状态来做点什么，这就可能会有些棘手。为了在数据变化之后等待 Mpx 完成更新，可以在数据变化之后立即使用 `this.$nextTick(callback)`。这样回调函数将在更新完成后被调用。

```js
createComponent({
  methods: {
    updateMessage () {
      this.message = '已更新'
      // 此时视图尚未更新
      this.$nextTick(function () {
        // 此时视图已更新
        console.log('视图已更新')
      })
    }
  }
})
```

## 检测变化的注意事项 {#change-detection-caveats}

由于 JavaScript 的限制，Mpx **不能检测**数组和对象的变化。尽管如此，我们还是有一些办法来回避这些限制并保证它们的响应性。

### 对象 {#objects}

Mpx 无法检测 property 的添加或移除。由于 Mpx 会在初始化实例时对 property 执行 getter/setter 转化，所以 property 必须在 `data` 对象上存在才能让 Mpx 将它转换为响应式的。

```js
createComponent({
  data: {
    a: 1
  },
  ready() {
    // `this.a` 是响应式的
    this.a = 2
    // `this.b` 是非响应式的
    this.b = 2
  }
})
```

对于已经创建的实例，Mpx 不允许动态添加根级别的响应式 property。但是，可以使用 `this.$set(object, propertyName, value)` 方法向嵌套对象添加响应式 property。

```js
// this.$set(object, key, value)
this.$set(this.someObject, 'b', 2)
```

您还可以使用 `this.$delete(object, propertyName)` 方法来删除对象的 property，如果对象是响应式的，确保删除能触发更新视图。

```js
// this.$delete(object, key)
this.$delete(this.someObject, 'b')
```

### 数组 {#arrays}

Mpx 不能检测以下数组的变动：

1. 当你利用索引直接设置一个 array item 时，例如：`vm.items[indexOfItem] = newValue`
2. 当你修改数组的长度时，例如：`vm.items.length = newLength`

为了解决第一类问题，你可以使用：

```js
// Mpx.set
this.$set(this.items, indexOfItem, newValue)
// Array.prototype.splice
this.items.splice(indexOfItem, 1, newValue)
```

为了解决第二类问题，你可以使用 `splice`：

```js
this.items.splice(newLength)
```

## 示例 {#example}

下面是一个相对完整的数据响应示例：

```html
<template>
  <view>
    <view>Num: {{num}}</view>
    <view>Minus num: {{mnum}}</view>
    <view>Num plus: {{nump}}</view>
    <view>{{info.name}}</view>
    <view wx:if="{{info.age}}">{{info.age}}</view>
  </view>
</template>

<script>
  import { createComponent } from '@mpxjs/core'

  createComponent({
    // data中定义的数据会在初始化时进行数据响应处理
    data: {
      num: 1,
      info: {
        name: 'test'
      }
    },
    // 配置中直接定义watch
    watch: {
      num (val) {
        console.log(val)
      }
    },
    // 定义计算属性，模板中可以直接访问
    computed: {
      mnum () {
        return -this.num
      },
      nump: {
        get () {
          return this.num + 1
        },
        // 支持计算属性的setter
        set (val) {
          this.num = val - 1
        }
      }
    },
    ready () {
      // 使用实例方法定义watch，可以传递追踪函数更加灵活
      this.$watch(() => {
        return this.nump - this.mnum
      }, (val) => {
        console.log(val)
      })
      // 每隔一秒进行一次更新，相关watcher会被触发，视图也会发生更新
      setInterval(() => {
        this.num++
      }, 1000)
      // 使用$set新增响应属性，视图同样能够得到更新
      setTimeout(() => {
        this.$set(this.info, 'age', 23)
      }, 1000)
    }
  })
</script>
```

---

---
url: /guide/basic/lifecycle.md
---
# Mpx 生命周期 {#lifecycle}

Mpx 作为跨端小程序框架，提供了一套统一的生命周期系统，抹平不同小程序平台生命周期的差异。本章节详细介绍 Mpx 中的各种生命周期钩子及其使用方法。

## 生命周期概述 {#lifecycle-overview}

Mpx 的生命周期体系包含以下几个层面：

* **组件生命周期**：组件实例的创建、挂载、更新、销毁过程
* **页面生命周期**：页面的加载、显示、隐藏、卸载过程
* **应用生命周期**：应用的启动、显示、隐藏、错误处理等
* **SSR 生命周期**：服务端渲染特有的生命周期钩子

## 生命周期体系概览 {#lifecycle-system-overview}

Mpx 提供了两套生命周期使用方式：

* **选项式 API**：使用原生小程序生命周期或框架内置生命周期常量
* **组合式 API**：使用统一的 Vue 风格生命周期钩子

### 生命周期对应关系 {#lifecycle-mapping}

| 框架内置生命周期 | 选项式 API 用法 | 组合式 API 钩子 | 微信原生生命周期 |
|:--------------|:-------------|:-------------|:-------------|
| BEFORECREATE | 页面: onLoad 组件：attached | - (可直接在 setup 中编写） | 页面: onLoad 组件：attached|
| CREATED | 页面: onLoad 组件：attached  | - (可直接在 setup 中编写） | 页面: onLoad 组件：attached |
| BEFOREMOUNT | 页面：onReady 组件：ready | onBeforeMount | 页面：onReady 组件：ready |
| MOUNTED | 页面：onReady 组件：ready | onMounted | 页面：onReady 组件：ready |
| BEFOREUPDATE | - | onBeforeUpdate | - |
| UPDATED | - | onUpdated | - |
| BEFOREUNMOUNT |  页面：onUnload  组件：detached | onBeforeUnmount |  页面：onUnload  组件：detached|
| UNMOUNTED |  页面：onUnload  组件：detached | onUnmounted |  页面：onUnload  组件：detached|
| ONSHOW | onShow | onShow | onShow |
| ONHIDE | onHide | onHide | onHide |
| ONRESIZE | onResize | onResize | onResize |
| SERVERPREFETCH | serverPrefetch | onServerPrefetch | - |

> **说明**：
>
> * 选项式 API 主要使用原生小程序生命周期（如 `attached`、`ready`、`detached`）
> * 也可以使用框架内置生命周期常量（如 `[CREATED]() {}`、`[MOUNTED]() {}` ）来保持跨平台一致性
> * 组合式 API 提供了统一的 Vue 风格生命周期钩子

## Options 语法（选项式 API） {#options-api}

选项式 API 支持两种生命周期写法：

1. **原生小程序生命周期**：直接使用各平台的原生生命周期名称
2. **框架内置生命周期常量**：使用统一的框架内置生命周期常量

### 组件生命周期 {#component-lifecycle}

**原生小程序生命周期：**

* `created` - 组件实例刚被创建时执行，此时不能调用 setData
* `attached` - 组件实例进入页面节点树时执行
* `ready` - 组件在视图层布局完成后执行
* `detached` - 组件实例被从页面节点树移除时执行
* `pageLifetimes.show` - 组件所在页面显示时执行
* `pageLifetimes.hide` - 组件所在页面隐藏时执行

**示例：**

```js
import { createComponent } from '@mpxjs/core'

createComponent({
  data: {
    message: 'Hello Mpx'
  },
  
  // 微信小程序原生组件生命周期
  created() {
    console.log('组件实例刚被创建')
    // 此时不能调用 setData，通常用于给组件 this 添加一些自定义属性字段
  },
  
  attached() {
    console.log('组件实例进入页面节点树时')
    // 可以访问 data，相当于 Vue 的 created + mounted
    console.log(this.data.message) // 'Hello Mpx'
  },
  
  ready() {
    console.log('组件在视图层布局完成后')
    // 可以访问 DOM 元素，类似 Vue 的 mounted
  },
  
  detached() {
    console.log('组件实例被从页面节点树移除时')
    // 清理定时器、事件监听器等，类似 Vue 的 beforeUnmount
  },
  pageLifetimes: {
    // 在组件中监听页面生命周期
    show() {
      console.log('组件所在页面被展示时')
    },
  
    hide() {
      console.log('组件所在页面被隐藏时')
    }
  }
})
```

**组件生命周期常量：**

* `BEFORECREATE` - 实例初始化之后，数据观测初始化之前同步调用
* `CREATED` - 实例创建完成，数据观测已完成
* `BEFOREMOUNT` - 挂载开始之前被调用
* `MOUNTED` - 实例被挂载后调用
* `BEFOREUPDATE` - 数据更新时调用，发生在视图更新之前
* `UPDATED` - 数据更新导致的重新渲染和更新完毕之后被调用
* `BEFOREUNMOUNT` - 实例销毁之前调用
* `UNMOUNTED` - 实例销毁后调用

**示例：**

```js
import { createComponent, CREATED, MOUNTED, BEFOREUNMOUNT } from '@mpxjs/core'

createComponent({
  data: {
    timer: null
  },
  
  [CREATED]() {
    console.log('组件创建完成')
    // 初始化数据
  },
  
  [MOUNTED]() {
    console.log('组件挂载完成')
    // 启动定时器
    this.timer = setInterval(() => {
      console.log('定时任务执行')
    }, 1000)
  },
  
  [BEFOREUNMOUNT]() {
    console.log('组件即将销毁')
    // 清理定时器
    if (this.timer) {
      clearInterval(this.timer)
      this.timer = null
    }
  }
})
```

### 页面生命周期 {#page-lifecycle}

* `onLoad` - 页面加载时触发，只会调用一次
* `onReady` - 页面初次渲染完成时触发，只会调用一次
* `onShow` - 页面显示/切入前台时触发
* `onHide` - 页面隐藏/切入后台时触发
* `onUnload` - 页面卸载时触发
* `onResize` - 监听页面尺寸变化

**示例：**

```js
import { createPage, ONLOAD, ONSHOW, ONHIDE } from '@mpxjs/core'

createPage({
  data: {
    userInfo: null
  },
  
  // 使用原生页面生命周期
  onLoad(options) {
    console.log('页面加载', options)
    // 获取页面参数，初始化数据
  },
  
  onShow() {
    console.log('页面显示')
    // 页面显示时的逻辑
  },
  
  onHide() {
    console.log('页面隐藏')
    // 页面隐藏时的逻辑
  },
  
  onReady() {
    console.log('页面初次渲染完成')
    // 可以进行 DOM 操作
  },
  
  onUnload() {
    console.log('页面卸载')
    // 清理资源
  },
})
```

**页面生命周期常量：**

* `ONLOAD` - 页面加载
* `ONSHOW` - 页面显示
* `ONHIDE` - 页面隐藏
* `ONRESIZE` - 页面尺寸变化

**示例：**

```js
import { createPage, ONLOAD, ONSHOW, ONHIDE, ONRESIZE } from '@mpxjs/core'

createPage({
  data: {
    userInfo: null
  },
  
  // 使用框架内置生命周期常量
  [ONLOAD](options) {
    console.log('使用内置常量 - 页面加载', options)
    // 获取页面参数，初始化数据
  },
  
  [ONSHOW]() {
    console.log('使用内置常量 - 页面显示')
    // 页面显示时的逻辑
  },
  
  [ONHIDE]() {
    console.log('使用内置常量 - 页面隐藏')
    // 页面隐藏时的逻辑
  },
  
  [ONRESIZE](res) {
    console.log('使用内置常量 - 页面尺寸变化', res)
    // 处理页面尺寸变化
  }
})
```

### 应用生命周期 {#app-lifecycle}

应用生命周期用于 App 实例：

**原生应用生命周期：**

* `onLaunch` - 应用初始化完成时触发，全局只触发一次
* `onShow` - 应用启动，或从后台进入前台显示时触发
* `onHide` - 应用从前台进入后台时触发
* `onError` - 应用发生脚本错误或 API 调用报错时触发

**示例：**

```js
import { createApp } from '@mpxjs/core'

createApp({
  // 应用生命周期
  onLaunch(options) {
    console.log('应用启动', options)
    // 应用初始化
  },
  
  onShow(options) {
    console.log('应用显示', options)
    // 应用从后台进入前台显示
  },
  
  onHide() {
    console.log('应用隐藏')
    // 应用从前台进入后台
  },
  
  onError(error) {
    console.log('应用错误', error)
    // 应用发生脚本错误或 API 调用报错时触发
  }
})
```

**注意：** 应用生命周期暂不支持框架内置生命周期常量，只能使用原生小程序应用生命周期。

## Setup 语法（组合式 API） {#setup-api}

组合式 API 使用统一的 Vue 风格生命周期钩子。

### 组件/页面通用生命周期 {#component-page-common-lifecycle}

**组件和页面都可用的生命周期钩子：**

* `onBeforeMount` - 挂载开始之前被调用
* `onMounted` - 被挂载后调用
* `onBeforeUpdate` - 数据更新时调用
* `onUpdated` - 数据更新导致的重新渲染后调用
* `onBeforeUnmount` - 在卸载实例之前调用
* `onUnmounted` - 卸载实例后调用
* `onShow` - 页面显示/切入前台时触发
* `onHide` - 页面隐藏/切入后台时触发
* `onResize` - 页面尺寸变化时触发

> **注意**：`setup` 函数本身相当于 `beforeCreate` + `created`，可以直接在其中编写初始化逻辑。

**示例：**

```js
import { 
  createComponent, 
  onBeforeMount,
  onMounted, 
  onBeforeUpdate,
  onUpdated, 
  onBeforeUnmount,
  onUnmounted,
  onShow,
  onHide,
  onResize
} from '@mpxjs/core'

createComponent({
  setup() {
    console.log('setup 执行 - 相当于 beforeCreate + created')
    
    // 组件挂载前
    onBeforeMount(() => {
      console.log('组件即将挂载')
    })
    
    // 组件挂载后
    onMounted(() => {
      console.log('组件已挂载')
      // 可以访问 DOM 元素和 refs
    })
    
    // 数据更新前
    onBeforeUpdate(() => {
      console.log('数据即将更新')
    })
    
    // 数据更新后
    onUpdated(() => {
      console.log('数据更新完成')
      // 注意：onUpdated 不保证所有子组件都重新渲染完毕
      // 如果需要等待整个视图渲染完毕，使用 nextTick
    })
    
    // 组件卸载前
    onBeforeUnmount(() => {
      console.log('组件即将卸载')
      // 清理定时器、事件监听器等
    })
    
    // 组件卸载后
    onUnmounted(() => {
      console.log('组件已卸载')
    })
    
    // 页面相关生命周期（组件中监听页面的生命周期）
    onShow(() => {
      console.log('页面显示时，组件需要处理的逻辑')
    })
    
    onHide(() => {
      console.log('页面隐藏时，组件需要处理的逻辑')
    })
    
    onResize((res) => {
      console.log('页面尺寸变化时，组件需要处理的逻辑', res)
    })
    
    return {
      // 暴露给模板的数据和方法
    }
  }
})
```

### 页面特有生命周期 {#page-specific-lifecycle}

**仅页面可用的生命周期钩子：**

* `onLoad` - 页面加载时触发，接收页面参数

**示例：**

```js
import { 
  createPage,
  onLoad,
  // 其他通用生命周期钩子请参考上面的"组件页面通用生命周期"部分
} from '@mpxjs/core'

createPage({
  setup() {
    // 页面特有生命周期
    onLoad((options) => {
      console.log('页面加载', options)
      // 处理页面参数
    })
    
    return {}
  }
})
```

### 应用生命周期 {#app-lifecycle-1}

**注意：** 应用实例暂不支持 setup 语法，只能使用选项式 API。

## SSR 生命周期 {#ssr-lifecycle}

Mpx 2.9+ 版本提供了专门的 [web SSR](../advance/ssr.md)（服务端渲染）生命周期钩子：

### 通用生命周期 {#common-lifecycle}

**[serverPrefetch](../advance/ssr.md#serverprefetch) / [SERVERPREFETCH](../advance/ssr.md#serverprefetch)**

> 可在应用/页面/组件中使用，仅在服务端执行

用于服务端数据预取，支持两种定义方式：

**选项式 API：**

```js
import { createPage, SERVERPREFETCH } from '@mpxjs/core'
import useStore from '../store/index'

createPage({
  data: {
    articleList: []
  },
  
  // 方式1：使用方法名
  serverPrefetch() {
    const store = useStore(this.$pinia)
    return store.fetchArticleList(this.$route.query.category)
      .then(data => {
        this.articleList = data
      })
  },
  
  // 方式2：使用内置生命周期常量（等价于上面）
  // [SERVERPREFETCH]() {
  //   // 与 serverPrefetch 完全等价
  // }
})
```

**组合式 API：**

```js
import { createPage, onServerPrefetch, ref } from '@mpxjs/core'
import useStore from '../store/index'

createPage({
  setup() {
    const articleList = ref([])
    const store = useStore()
    
    onServerPrefetch(() => {
      return store.fetchArticleList()
        .then(data => {
          articleList.value = data
        })
    })
    
    return { articleList }
  }
})
```

### 应用生命周期 {#app-lifecycle-2}

**应用级别的 SSR 生命周期钩子：**

* [`onAppInit`](../advance/ssr.md#onappinit) - 应用初始化（服务端和客户端都执行）
* [`onSSRAppCreated`](../advance/ssr.md#onssrappcreated) - 应用创建完成（仅服务端执行）

```js
// app.mpx
import { createApp } from '@mpxjs/core'
import { createPinia } from '@mpxjs/pinia'

createApp({
  // 应用初始化，创建全局状态管理实例
  onAppInit() {
    const pinia = createPinia()
    return { pinia }
  },
  
  // 应用创建完成，进行路由匹配和状态同步
  onSSRAppCreated({ app, router, pinia, context }) {
    return router.push(context.url).then(() => {
      context.state = { pinia: pinia.state.value }
      return app
    })
  }
})
```

## 最佳实践 {#best-practice}

### 1. 选择合适的生命周期 {#choose-lifecycle}

#### 选项式 API（原生小程序生命周期） {#options-api-native}

```js
// ✅ 正确：在 attached 中初始化数据
attached() {
  this.fetchUserInfo()
}

// ✅ 正确：在 ready 中操作 DOM
ready() {
  // 操作组件节点
  this.createSelectorQuery().select('.chart').boundingClientRect().exec()
}

// ✅ 正确：在 detached 中清理资源
detached() {
  clearInterval(this.timer)
  // 移除事件监听，定时器等
}
```

#### 组合式 API（Vue 风格生命周期） {#setup-api-vue}

```js
// ✅ 正确：在 setup 中初始化数据，onMounted 中操作 DOM
setup() {
  // 数据初始化可以直接在 setup 中进行
  const userInfo = ref(null)
  
  onMounted(() => {
    // DOM 操作
  })
  
  onBeforeUnmount(() => {
    // 清理资源
    clearInterval(timer)
  })
}
```

---

---
url: /guide/basic/template.md
---
# 模板语法 {#template-syntax}

Mpx中的模板语法以小程序模板语法为基础，支持小程序的全部模板语法，同时提供了一系列增强的模板指令及语法。

小程序原生模板语法请参考[这里](https://developers.weixin.qq.com/miniprogram/dev/reference/wxml/)

Mpx提供的增强指令语法如下：

* [wx:style动态样式](class-style-binding.md#style-binding)
* [wx:class动态类名](class-style-binding.md#class-binding)
* [wx:model双向绑定](two-way-binding.md)
* [wx:model-prop双向绑定属性](two-way-binding.md#change-two-way-binding-event-prop)
* [wx:model-event双向绑定事件](two-way-binding.md#change-two-way-binding-event-prop)
* [wx:model-value-path双向绑定数据路径](two-way-binding.md#change-two-way-binding-path)
* [wx:model-filter双向绑定过滤器](two-way-binding.md#two-way-binding-filter)
* [wx:ref获取实例](refs.md)
* [wx:show隐藏显示](conditional-render.md)
* [component动态组件](component.md#dynamic-component)
* [事件处理内联传参](event.md)
* [模板条件编译](template.md)

下面是使用了模板增强语法的一个简单实例，许多在原生小程序上很繁琐的模板描述在增强语法的帮助下变得清晰简洁：

```html
<template>
  <!--动态样式-->
  <view class="container" wx:style="{{dynamicStyle}}">
    <!--数据绑定-->
    <view class="title">{{title}}</view>
    <!--计算属性数据绑定-->
    <view class="title">{{reversedTitle}}</view>
    <view class="list">
      <!--循环渲染，动态类名，事件处理内联传参-->
      <view wx:for="{{list}}" wx:key="id" class="list-item" wx:class="{{ {active:item.active} }}"
            bindtap="handleTap(index)">
        <view>{{item.content}}</view>
        <!--循环内部双向数据绑定-->
        <input type="text" wx:model="{{list[index].content}}"/>
      </view>
    </view>
    <!--自定义组件获取实例，双向绑定，自定义双向绑定属性及事件-->
    <custom-input wx:ref="ci" wx:model="{{customInfo}}" wx:model-prop="info" wx:model-event="change"/>
    <!--动态组件，is传入组件名字符串，可使用的组件需要在json中注册，全局注册也生效-->
    <component is="{{current}}"></component>
    <!--显示/隐藏dom-->
    <view class="bottom" wx:show="{{showBottom}}">
      <!--模板条件编译，__mpx_mode__为框架注入的环境变量，条件判断为false的模板不会生成到dist-->
      <view wx:if="{{__mpx_mode__ === 'wx'}}">wx env</view>
      <view wx:if="{{__mpx_mode__ === 'ali'}}">ali env</view>
    </view>
  </view>
</template>

<script>
  import { createPage } from '@mpxjs/core'

  createPage({
    data: {
      // 动态样式和类名也可以使用computed返回
      dynamicStyle: {
        fontSize: '16px',
        color: 'red'
      },
      title: 'hello world',
      list: [
        {
          content: '全军出击',
          id: 0,
          active: false
        },
        {
          content: '猥琐发育，别浪',
          id: 1,
          active: false
        }
      ],
      customInfo: {
        title: 'test',
        content: 'test content'
      },
      current: 'com-a',
      showBottom: false
    },
    computed: {
      reversedTitle () {
        return this.title.split('').reverse().join('')
      }
    },
    handleTap (index) {
      // 处理函数直接通过参数获取当前点击的index，清晰简洁
      this.list[index].active = !this.list[index].active
    }
  })
</script>

<script type="application/json">
  {
    "usingComponents": {
      "custom-input": "../components/custom-input",
      "com-a": "../components/com-a",
      "com-b": "../components/com-b"
    }
  }
</script>
```

## 模板预编译 {#template-precompile}

Mpx还支持开发者使用插值语法与小程序不冲突第三方的模板引擎语法来编写template，如pug：

```html
<template lang="pug">
  view(class="list")
    view(class="list-item") red
    view(class="list-item") blue
    view(class="list-item") green
</template>
```

---

---
url: /guide/basic/data-binding.md
---
# 数据绑定 {#data-binding}

Mpx遵循了微信小程序的数据绑定规则，支持在模版中使用`{{}}`绑定数据。
使用示例:

```html
<template>
    <view>{{ message }}</view>
</template>

<script>
    import { createComponent } from '@mpxjs/core'

    createComponent({
    data: {
        message: 'Hello Mpx!'
    }
    })
</script>
```

## 可选链表达式 {#optional-chaining}

Mpx在基础数据绑定的基础上增强支持了可选链`?.`能力，用法和JS可选链基本一致，可以在任意被`{{}}`所包裹的数据绑定表达式中使用。

> 实现原理是在编译时将使用`?.`的部分转化为`wxs`函数调用，运行时通过`wxs`访问变量属性，模拟出可选链的效果。

使用示例：

```html
  <template>
    <view wx:if="{{ a?.b }}">{{ a?.c + a?.d }}</view>
    <view wx:for="{{ a?.d || [] }}"></view>
    <view>{{ a?.d ? 'a' : 'b' }}</view>
    <view>{{ a?.g[e?.d] }}</view>
  </template>

  <script>
    import { createComponent } from '@mpxjs/core'

    createComponent({
      data: {
        a: {
            b: true,
            c: 123,
            g: {
                d: 321
            }
        },
        e: {
            d: 'd'
        }
      }
    })
  </script>
```

---

---
url: /guide/basic/class-style-binding.md
---
# 类名样式绑定 {#class-style-binding}

Mpx利用wxs完整实现了Vue中的类名样式绑定，性能优良且没有任何使用限制（很多小程序框架基于字符串解析来实现该能力，只支持在模板上写简单的字面量，大大限制了使用场景）

## 类名绑定 {#class-binding}

类名绑定的增强指令是wx:class，可以与普通的class属性同时存在，在视图渲染中进行合成。

### 对象语法 {#object-syntax}

wx:class中传入对象，key值为类名，value值控制该类名是否生效。

```html
<template>
  <!--支持传入对象字面量，此处视图的class="outer active"-->
  <view class="outer" wx:class="{{ {active:active, disabled:disabled} }}">
    <!--直接直接传入对象数据，此处视图的class="inner selected"-->
    <view class="inner" wx:class="{{innerClass}}"></view>
  </view>
</template>

<script>
  import { createPage } from '@mpxjs/core'

  createPage({
    data: {
      active: true,
      disable: false,
      innerClass: {
        selected: true
      }
    }
  })
</script>
```

### 数组语法 {#array-syntax}

wx:class中传入字符串数组，字符串为类名。

```html
<template>
  <!--支持传入数组字面量，此处视图的class="outer active danger"-->
  <view class="outer" wx:class="{{ ['active', 'danger'] }}">
    <!--直接直接传入数组数据，此处视图的class="inner selected"-->
    <view class="inner" wx:class="{{innerClass}}"></view>
  </view>
</template>

<script>
  import { createPage } from '@mpxjs/core'

  createPage({
    data: {
      innerClass: ['selected']
    }
  })
</script>
```

## 样式绑定 {#style-binding}

样式的增强指令是wx:style，可以与普通的style属性同时存在，在视图渲染中进行合成。

### 对象语法 {#object-syntax-1}

wx:style中传入用样式对象，带有横杠的样式名可以用驼峰写法来代替

```html
<template>
  <!--支持传入对象字面量，模板会显得杂乱，此处视图的style="color:red;font-size:16px;font-weight:bold;"-->
  <view style="color:red;" wx:style="{{ {fontSize:'16px', fontWeight:'bold'} }}">
    <!--更好的方式是直接传入对象数据，此处视图的style="color:blue;font-size:14px;"-->
    <view wx:style="{{innerStyle}}"></view>
  </view>
</template>

<script>
  import { createPage } from '@mpxjs/core'

  createPage({
    data: {
      innerStyle: {
        color: 'blue',
        fontSize: '14px'
      }
    }
  })
</script>
```

### 数组语法 {#array-syntax-1}

wx:style同样支持传入数组将多个样式合成应用到视图上

```html
<template>
  <!--此处视图的style="color:blue;font-size:14px;background-color:red;"-->
  <view wx:style="{{ [baseStyle, activeStyle] }}">

  </view>
</template>

<script>
  import { createPage } from '@mpxjs/core'

  createPage({
    data: {
      baseStyle: {
        color: 'blue',
        fontSize: '14px'
      },
      activeStyle:{
        backgroundColor: 'red'
      }
    }
  })
</script>
```

---

---
url: /guide/basic/conditional-render.md
---
# 条件渲染 {#conditional-render}

Mpx中的条件渲染与原生小程序中完全一致，详情可以查看[这里](https://developers.weixin.qq.com/miniprogram/dev/reference/wxml/conditional.html)

简单示例如下:

```html
<template>
  <view class="container">
    <!-- 通过 wx:if 的语法来控制需要渲染的元素 -->
    <view wx:if="{{ score > 90 }}"> A </view>
    <view wx:elif="{{ score > 60 }}"> B </view>
    <view wx:else> C </view>

    <!-- 通过 wx:show 来控制元素的显示隐藏-->
    <view wx:show="{{ score > 90 }}"> very good! <view>
  </view>
</template>

<script>
  import { createPage } from '@mpxjs/core'

  createPage({
    data: {
      score: 80
    }
  })
</script>
```

---

---
url: /guide/basic/list-render.md
---
# 列表渲染 {#list-render}

Mpx中的列表渲染与原生小程序中完全一致，详情可以查看[这里](https://developers.weixin.qq.com/miniprogram/dev/reference/wxml/list.html)

> 值得注意的是wx:key与Vue中的key属性的区别，不能使用数据绑定，只能传递普通字符串将数组item中的对应属性作为key，或者传入保留关键字\*this将item本身作为key

下面是简单示例：

```html
<template>
  <!-- 使用数组中元素的 id属性/保留关键字*this 作为key值  -->
  <view wx:for="{{titleList}}" wx:key="id">
    <!-- item 默认代表数组的当前项 -->
    <view>{{item.id}}: {{item.name}}</view>
  </view>
</template>

<script>
  import { createPage } from '@mpxjs/core'

  createPage({
    data: {
      titleList: [
        { id: 1, name: 'A' },
        { id: 2, name: 'B' },
        { id: 3, name: 'C' }
      ]
    }
  })
</script>
```

## 特殊处理 {#special-handling}

当列表中一些需要特殊二次处理的数据，可参考下列两种方式

### computed方式 {#computed-way}

```html
<template>
  <!-- 使用数组中元素的 id属性/保留关键字*this 作为key值  -->
  <view wx:for="{{refactorTitleList}}" wx:key="id">
    <!-- item 默认代表数组的当前项 -->
    <view>{{item.id}}: {{item.name}}</view>
    <!-- bad方式 不可用computed或methods中方法处理 -->
    <!-- <view>{{item.id}}: {{format(item.name)}}</view> -->
  </view>
</template>

<script>
  import { createPage } from '@mpxjs/core'

  createPage({
    data: {
      titleList: [
        { id: 1, name: 'A' },
        { id: 2, name: 'B' },
        { id: 3, name: 'C' }
      ],
      nameMap: {
        '1': 'mpx'
      }
    },
    computed: {
      refactorTitleList () {
        return this.titleList.map(item => {
          // 列表中需要特殊处理的数据可在computed中处理好再渲染
          item.name = this.nameMap[item.id] ? this.nameMap[item.id] : item.name
          return item
        })
      }
    }
  })
</script>
```

### wxs方式 {#wxs-method}

```html
<template>
  <wxs module="foo">
    var formatName = function (item, nameMap) {
      // 这里区别string和number
      var id = ''+item.id
      if(nameMap[id]){
        return nameMap[id];
      }
      return item.name;
    }
    module.exports = {
      formatName: formatName
    };
  </wxs>
  <!-- 使用数组中元素的 id属性/保留关键字*this 作为key值  -->
  <view wx:for="{{titleList}}" wx:key="id">
    <!-- item 默认代表数组的当前项 -->
    <view>{{item.id}}: {{foo.formatName(item, nameMap)}}</view>
  </view>
</template>

<script>
  import { createPage } from '@mpxjs/core'

  createPage({
    data: {
      titleList: [
        { id: 1, name: 'A' },
        { id: 2, name: 'B' },
        { id: 3, name: 'C' }
      ],
      nameMap: {
        '1': 'mpx'
      }
    }
  })
</script>
```

---

---
url: /guide/basic/event.md
---
# 事件处理 {#event-handling}

Mpx 在事件处理上基于原生小程序，支持原生小程序的全部事件处理技术规范，在此基础上新增了事件处理内联传参的增强机制。

## 事件分类 {#event-classification}

事件分为冒泡事件和非冒泡事件：

1. 冒泡事件：当一个组件上的事件被触发后，该事件会向父节点传递
2. 非冒泡事件：当一个组件上的事件被触发后，该事件不会向父节点传递

常用事件如下:

| 事件类型    | 触发条件                                                       |
| ----------- | -------------------------------------------------------------- |
| touchstart  | 手指触摸动作开始                                               |
| touchmove   | 手指触摸后移动                                                 |
| touchcancel | 手指触摸动作被打断，如来电提醒，弹窗                           |
| touchend    | 手指触摸动作结束                                               |
| tap         | 手指触摸后马上离开                                             |
| longpress   | 手指触摸后，超过 350ms 再离开，推荐使用 longpress 代替 longtap |
| longtap     | 手指触摸后，超过 350ms 再离开                                  |

## 事件绑定方式 {#event-binding}

### 基础绑定 {#basic-binding}

事件绑定的写法同组件的属性，以 key、value 的形式：

1. `bind` 绑定：

```html
<view bindtap="handleTap">点击事件</view>
<!-- 也可以写成 -->
<view bind:tap="handleTap">点击事件</view>
```

2. `catch` 绑定（阻止冒泡）：

```html
<view catchtap="handleTap">阻止冒泡的点击事件</view>
<!-- 也可以写成 -->
<view catch:tap="handleTap">阻止冒泡的点击事件</view>
```

### 捕获阶段绑定 {#capture-binding}

捕获阶段位于冒泡阶段之前，且在捕获阶段中，事件到达节点的顺序与冒泡阶段恰好相反。需要在捕获阶段监听事件时，可以采用 `capture-bind`、`capture-catch` 关键字：

```html
<view capture-bind:tap="handleCapture">捕获阶段事件</view>
<view capture-catch:tap="handleCaptureAndStop">捕获阶段且停止传递</view>
```

### 动态事件绑定 {#dynamic-event-binding}

```html
<!-- 支持传入动态数据 -->
<view wx:for="{{items}}" bindtap="handleTap_{{index}}"> {{item}}</view>

<script>
  import { createComponent } from '@mpxjs/core'
  createComponent({
    data: {
      items: ['Item 1', 'Item 2', 'Item 3', 'Item 4']
    },
    methods: {
      const handleTap_0 = (event) => {
        console.log('Tapped on item 1')
      },

      const handleTap_1 = (event) => {
        console.log('Tapped on item 2')
      },

      const handleTap_2 = (event) => {
        console.log('Tapped on item 3')
      },

      const handleTap_3 = (event) => {
        console.log('Tapped on item 4')
      }
    }
  })
</script>
```

## 事件对象 {#event-object}

当事件回调触发时，会收到一个事件对象，它的详细属性如下：

| 属性           | 类型    | 说明                                         |
| -------------- | ------- | -------------------------------------------- |
| type           | String  | 事件类型                                     |
| timeStamp      | Integer | 事件生成时的时间戳                           |
| target         | Object  | 触发事件的组件的一些属性值集合               |
| currentTarget  | Object  | 当前组件的一些属性值集合                     |
| detail         | Object  | 额外的信息                                   |
| touches        | Array   | 触摸事件，当前停留在屏幕中的触摸点信息的数组 |
| changedTouches | Array   | 触摸事件，当前变化的触摸点信息的数组         |

### Target 和 CurrentTarget {#target-and-currenttarget}

* `target` 是触发事件的源组件
* `currentTarget` 是事件绑定的当前组件

两者都具备以下属性：
| 属性 | 类型 | 说明 |
|------|------|------|
| id | String | 元素的 id 属性 |
| dataset | Object | 包含所有以 data- 开头的自定义属性的对象集合，dataset 属性会自动将 data- 后面的属性名转换为驼峰命名。 例如：data-user-name 会变成 dataset.userName |

```html
<!-- 点击 inner-view 时 -->
<view id="outer-view" bindtap="handleTap">
  outer-view
  <view id="inner-view"> inner-view </view>
</view>
```

上述示例中，点击 inner-view 时：

* `e.target.id` 为 inner-view
* `e.currentTarget.id` 为 outer-view

### touches 和 changedTouches {#touches-and-changedtouches}

touches 数组中每个元素包含以下属性
| 属性 | 说明 |
|------|------|
| identifier | 触摸点的标识符 |
| pageX, pageY | 距离文档左上角的距离 |
| clientX, clientY | 距离页面可显示区域左上角的距离 |

### detail

自定义事件所携带的数据，如表单组件的提交事件会携带用户的输入，媒体的错误事件会携带错误信息等。点击事件的 detail 带有的 x, y 同 pageX, pageY 代表距离文档左上角的距离。

## 事件参数传递 {#event-param-passing}

Mpx 提供了比原生小程序更强大的事件传参能力，支持以下几种传参方式：

### 基础传参 {#basic-param-passing}

使用data-\*属性进行事件传参

```html
<!--通过dataset进行事件传参-->
<view data-name="basic" bindtap="handleTap">基础传参</view>

<script>
  import { createComponent } from '@mpxjs/core'
  createComponent({
    methods: {
      handleTap(e) {
        console.log('name:', e.target.dataset.name)
      }
    }
  })
</script>
```

### 模板内联传参 {#template-inline-param-passing}

Mpx增强语法，支持在模板中使用方法调用的形式直接传递参数，方便简洁。参数支持传递字面量、组件数据以及 for 作用域下的 item/index。

```html
<!-- 传递字面量 -->
<view bindtap="handleTapInline('inline')">内联传参</view>

<!-- 传递组件数据 -->
<view bindtap="handleTapInline(text)">{{text}}</view>

<!-- 传递 for 作用域下的 item -->
<view wx:for="{{items}}" bindtap="handleTapInline(item)">{{item}}</view>

<script>
  import { createComponent } from '@mpxjs/core'
  createComponent({
    data: {
      text: 'dynamic text',
      items: ['Item 1', 'Item 2', 'Item 3', 'Item 4']
    },
    methods: {
      handleTapInline(params) {
        console.log('params:', params)
      }
    }
  })
</script>
```

#### 内联传参中访问 event 对象 {#use-event-object}

```html
<!-- 获取 event 对象 -->
<view bindtap="handleTapInlineWithEvent($event, 'inline')">获取event对象</view>

<script>
  import { createComponent } from '@mpxjs/core'
  createComponent({
    methods: {
      handleTapInlineWithEvent(event, params) {
        console.log('event:', event)
        console.log('params:', params)
      }
    }
  })
</script>
```

## Mpx 事件代理 {#event-proxy-enhancement}

在 Mpx 中，当使用了事件内联传参、`wx:model` 双向绑定等框架增强特性时，Mpx 会自动使用事件代理的方式进行事件绑定。在这种模式下，除了触发用户绑定的事件处理函数外，还会调用 `mpx.config.proxyEventHandler` 全局事件处理函数。

此外，Mpx 也支持通过添加 `.proxy` 修饰符来强行使用事件代理模式。当你希望通过 `proxyEventHandler` 全局拦截某些普通事件时，可以使用该方式强制开启事件代理。

示例：

```html
<!-- 强制开启事件代理 -->
<view bindtap.proxy="handleTap">代理事件</view>
```

当点击时，除了执行 `handleTap`，还会触发 `Mpx.config.proxyEventHandler(event, componentIns)`。

更多细节见 [proxyEventHandler](../../api/app-config.md#proxyeventhandler)。

---

---
url: /guide/basic/two-way-binding.md
---
# 双向绑定 {#two-way-binding}

Mpx针对表单组件提供了`wx:model`双向绑定指令，类似于`v-model`，该指令是一个语法糖指令，监听了组件抛出的输入事件并对绑定的数据进行更新，默认情况下会监听表单组件的`input`事件，并将`event.detail.value`中的数据更新到组件的`value`属性上。

简单实用示例如下：

```html
<view>
  <input type="text" wx:model="{{message}}"/>
  <!--view中的文案会随着用户对输入框进行输入而实时更新-->
  <view>{{message}}</view>
</view>
```

## 对自定义组件使用 {#use-on-custom-component}

对自定义组件使用双向绑定时用法与原生小程序组件完全一致

```html
<view>
  <custom-input type="text" wx:model="{{message}}"/>
  <!--此处的文案会随着输入框输入实时更新-->
  <view>{{message}}</view>
</view>
```

## 更改双向绑定的监听事件及数据属性 {#change-two-way-binding-event-prop}

如前文所述，`wx:model`指令默认监听组件抛出的`input`事件，并将声明的数据绑定到组件的`value`属性上，该行为在一些原生组件和自定义组件上并不成立，因为这些组件可能不存在`input`事件或`value`属性。对此，我们提供了`wx:model-event`和`wx:model-prop`指令来修改双向绑定的监听事件和数据属性，使用示例如下：

```html
<view>
  <!--原生组件picker中没有input事件，通过wx:model-event指令将双向绑定监听事件改为change事件-->
  <picker mode="selector" range="{{countryRange}}" wx:model="{{country}}" wx:model-event="change">
    <view class="picker">
      当前选择: {{country}}
    </view>
  </picker>
  <!--通过wx:model-event和wx:model-prop将该自定义组件的双向绑定监听事件和数据属性修改为customInput/customValue-->
  <custom-input wx:model="{{message}}" wx:model-event="customInput" wx:model-prop="customValue"/>
  <view>{{message}}</view>
</view>
```

## 更改双向绑定事件数据路径 {#change-two-way-binding-path}

Mpx中双向绑定默认使用event对象中的`event.detail.value`作为用户输入来更新组件数据，该行为在一些原生组件和自定义组件中也不成立，例如vant中的field输入框组件，用户的输入直接存储在`event.detail`当中，当然用户也可以将其存放在detail中的其他数据路径下，对此，我们提供了`wx:model-value-path`指令让用户声明在事件当中应该访问的数据路径。

由于小程序triggerEvent的Api设计，事件的用户数据都只能存放在`event.detail`中，因此`wx:model-value-path`的值都是相对于`event.detail`的数据路径，我们支持两种形式进行声明：

* 一种是点语法，如传入`current.value`时框架会从`event.detail.current.value`中取值作为用户输入，为空字符串时`wx:model-value-path=""`代表直接使用`event.detail`作为用户输入；
* 第二种是数组字面量的JSON字符串，如`["current", "value"]`与上面的`current.value`等价，传入`[]`时与上面的空字符串等价。

使用示例如下：

```html
<view>
  <!--wx:model-value-path传入[]直接使用event.detail作为用户输入，使vant-field中双向绑定能够生效-->
  <van-field wx:model="{{username}}" wx:model-value-path="[]" label="用户名" placeholder="请输入用户名"/>
</view>
```

## 双向绑定过滤器 {#two-way-binding-filter}

用户可以使用`wx:model-filter`指令定义双向绑定过滤器，在修改数据之前对用户输入进行过滤，来实现特定的效果，框架内置了`trim`过滤器对用户输入进行trim操作，传入其他字符串时会使用当前组件中的同名方法作为自定义过滤器，使用示例如下：

```html
<view>
  <!--以下示例中，用户输入的首尾空格将被过滤-->
  <input wx:model="{{message}}" wx:model-filter="trim"/>
  <view>{{message}}</view>
</view>
```

---

---
url: /guide/basic/refs.md
---
# 获取组件实例/节点信息 {#get-component-instance-node-info}

微信小程序中原生提供了`selectComponent/SelectorQuery.select`方法获取自定义组件实例和wxml节点信息，但是该api使用起来不太方便，并且不具备平台无关性，我们提供了增强指令`wx:ref`用于获取组件实例及节点信息，该指令的使用方式同vue中的ref类似，在模板中声明了`wx:ref`后，在组件ready后用户可以通过`this.$refs`获取对应的组件实例或节点查询对象(NodeRefs)，调用响应的组件方法或者获取视图节点信息。

> `wx:ref`其实也是模板编译和运行时注入结合实现的语法糖，本质还是通过原生小程序平台提供的能力进行获取，其实现的主要意义在于抹平跨平台差异以及提升用户的使用体验。

简单的使用示例如下：

```html
  <template>
    <view class="container">
      <!-- my-header 为一个组件，组件内部定义了一个 show 方法 -->
      <my-header wx:ref="myHeader"></my-header>
      <view wx:ref="content"></view>
    </view>
  </template>

  <script>
    import { createComponent } from '@mpxjs/core'

    createComponent({
      ready() {
        // 通过 this.$refs 获取view的节点查询对象
        this.$refs.content.fields({size: true},function (res){
          // res 就是我们要拿到的节点大小
        }).exec()
        // 通过 this.$refs 可直接获取组件实例
        this.$refs.myHeader.show()  // 拿到组件实例，调用组件内部的方法
      }
    })
  </script>
```

## 在列表渲染中使用`wx:ref` {#use-wx-ref-in-list}

在列表渲染中定义的`wx:ref`存在多个实例/节点，Mpx会在模板编译中判断某个`wx:ref`是否存在于列表渲染`wx:for`中，是的情况下在注入`this.$refs`时会通过`selectAllComponents/SelectQuery.selectAll`方法获取组件实例数组或数组节点查询对象，确保开发者能拿到列表渲染中所有的组件实例/节点信息。

使用示例如下：

```html
<template>
  <view>
    <!-- list 组件 -->
    <list wx:ref="list" wx:for="{{listData}}" data="{{item.name}}" wx:key="id"></list>
    <!-- view 节点 -->
    <view wx:ref="test" wx:for="{{listData}}" wx:key="id">{{item.name}}</view>
  </view>
</template>

<script>
  import { createComponent } from '@mpxjs/core'

  createComponent({
    data: {
      listData: [
        {id: 1, name: 'A'},
        {id: 2, name: 'B'},
        {id: 3, name: 'C'},
      ]
    },
    ready () {
      // 通过 this.$refs.list 获取的是组件实例的数组
      this.$refs.list.forEach(item => {
        // 对每一个组件实例的操作...
      })
      // 通过 this.$refs.test 获取的是节点查询对象，通过相关的方法操作节点
      this.$refs.test.fields({size: true}, function (res) {
        // 此处拿到的 res 是一个数组，包含了列表渲染中的所有节点的大小信息
      }).exec()
    }
  })
</script>

```

---

---
url: /guide/basic/css.md
---
# 样式定义 {#style-definition}

## 基础语法 {#basic-syntax}

Mpx 中的样式定义遵循 WXSS (WeiXin Style Sheets) 规范，WXSS 具有 CSS 大部分特性，同时为了更适合开发微信小程序，对 CSS 进行了扩充以及修改。

### 尺寸单位 {#size-units}

`rpx`（responsive pixel）: 可以根据屏幕宽度进行自适应。规定屏幕宽为 750rpx。如在 iPhone6 上，屏幕宽度为 375px，共有 750 个物理像素，则 750rpx = 375px = 750物理像素，1rpx = 0.5px = 1物理像素。

**设备 rpx 换算 px (屏幕宽度/750)**

| 设备 | rpx换算px (屏幕宽度/750) | px换算rpx (750/屏幕宽度) |
| :--- | :--- | :--- |
| iPhone5 | 1rpx = 0.42px | 1px = 2.34rpx |
| iPhone6 | 1rpx = 0.5px | 1px = 2rpx |
| iPhone6 Plus | 1rpx = 0.552px | 1px = 1.81rpx |

> **建议**：开发微信小程序时设计师可以用 iPhone6 作为视觉稿的标准。

### 样式导入 {#style-import}

使用 `@import` 语句可以导入外联样式表，`@import` 后跟需要导入的外联样式表的相对路径，用 `;` 表示语句结束。

```css
/** common.wxss **/
.small-p {
  padding:5px;
}
```

```css
/** app.wxss **/
@import "common.wxss";
.middle-p {
  padding:15px;
}
```

### 选择器 {#selectors}

目前支持的选择器有：

| 选择器 | 样例 | 样例描述 |
| :--- | :--- | :--- |
| .class | .intro | 选择所有拥有 class="intro" 的组件 |
| #id | #firstname | 选择拥有 id="firstname" 的组件 |
| element | view | 选择所有 view 组件 |
| element, element | view, checkbox | 选择所有文档的 view 组件和所有的 checkbox 组件 |
| ::after | view::after | 在 view 组件后边插入内容 |
| ::before | view::before | 在 view 组件前边插入内容 |

> **注意**
>
> * 当需要跨端输出 React Native 时，仅支持类选择器（.class）。

## CSS 预编译 {#css-precompile}

Mpx 支持 CSS 预编译处理，你可以通过在 style 标签上设置 `lang` 属性，来指定使用的 CSS 预处理器，此外需要在对应的 webpack 配置文件中
加入对应的 loader 配置

```html
<!-- 使用 stylus -->
<style lang="stylus">
  .nav
    width 100px
    height 80px
    color #f90
    &:hover
      background-color #f40
      color #fff
</style>

// getRules 配置文件
rules: [
    {
        test: /\.styl(us)?$/,
        use: [
            MpxWebpackPlugin.wxssLoader(),
            'stylus-loader'
        ]
    }
]
```

```html
<!-- 使用 sass  -->
<style lang="scss">
  .nav {
    width: 100px;
    height: 80px;
    color: #f90
    &:hover {
      background-color: #f40;
      color: #fff
    }
  }
</style>

// getRules 配置文件
rules: [
    {
        test: /\.scss$/,
        use: [
            'css-loader',
            'sass-loader'
        ]
    }
]
```

```html
<!-- 使用 less -->
<style lang="less">
  .size {
    width: 100px;
    height: 80px
  }
  .nav {
    .size();
    color: #f90;
    &:hover {
      background-color: #f40;
      color: #fff
    }
  }
</style>

// getRules 配置文件
rules: [
    {
        test: /\.less$/,
        use: [
            'css-loader',
            'less-loader'
        ]
    }
]

```

## 公共样式复用 {#common-style-reuse}

为了达到最大限度的样式复用，Mpx 提供了以下两种方式实现公共样式抽离，但是最终打包的效果有所区别。

```styl
// styles/mixin.styl
.header-styl
  width 100%
  height 100px
  background-color #f00
```

### style src 复用 {#style-src-reuse}

通过给 style 标签添加 src 属性引入外部样式，最终公共样式代码只会打包一份。

```html
<!-- index.mpx -->
<style lang="stylus" src="../styles/common.styl"></style>
```

```html
<!-- list.mpx -->
<style lang="stylus" src="../styles/common.styl"></style>
```

Mpx 将 common.styl 中的代码经过 loader 编译后生成一份单独的 wxss 文件，这样既实现了样式抽离，又能节省打包后的代码体积。

### @import 复用 {#import-reuse}

如果指定 style 标签的 lang 属性并且使用 @import 导入样式，那么这个文件经过对应的 loader 处理之后的内容会重复打包到引用它的文件目录下，并不会抽离成单独的文件，这样无形中增加了代码体积。

```html
<!-- index.mpx -->
<style lang="stylus">
  @import "../styles/mixin.styl"
</style>
```

```html
<!-- list.mpx -->
<style lang="less">
  @import "../styles/mixin.less";
</style>
```

如果导入的是一份 css 文件，则最终打包后的效果与 style src 一致。

```styl
// styles/mixin.css
.header-css {
  width: 100%;
  height: 100px;
  background-color: #f00;
}
```

```html
<!-- index.mpx -->
<style>
  @import "../styles/mixin.css";
</style>
```

```html
<!-- list.mpx -->
<style>
  @import "../styles/mixin.css";
</style>
```

对于多个页面或组件公用的样式，建议使用 style src 形式引入，避免一份样式被内联打成多份，同时还能使用 less、scss 等提升编码效率。

## CSS 压缩 {#css-compress}

在 production 模式下，框架默认会使用 [`cssnano`](https://www.cssnano.cn/) 对 css 内容进行压缩。

框架默认内置 cssnano 的 default 预设，默认配置为：

```js
cssnanoConfig = {
  preset: ['cssnano-preset-default', minimizeOptions.optimisation || {}]
}
```

以上配置为框架内置，开发者无需手动配置。

如果你想要使用 cssnano advanced 预设，则需要在 wxssLoader 中传入配置开启

```js
{
  test: /\.(wxss|acss|css|qss|ttss|jxss|ddss)$/,
  use: [
    MpxWebpackPlugin.wxssLoader({
      minimize: {
        advanced: true, // 使用 cssnano advanced preset
        optimisation: {
          'autoprefixer': true,
          'discardUnused': true,
          'mergeIdents': true
        }
      }
    })
  ]
},
```

同时也需要安装 advanced 依赖：

```bash
npm i -D cssnano-preset-advanced
```

optimisation 配置可以点击[详情](https://www.cssnano.cn/docs/what-are-optimisations/)查看更多配置项。

## 原子类 {#utility-class}

Mpx 框架内置了基于 [unocss](https://unocss.dev/) 的原子类支持，让小程序开发也能使用原子类。用户可以在 Mpx 页面/组件模板中直接使用一些预定义的基础样式类，诸如 `flex`，`pt-4`，`text-center` 和 `rotate-90` 等，对样式进行组合定义。

### 简单示例 {#simple-example}

```html
<view class="container">
  <view class="flex">
    <view class="py-8 px-8 inline-flex mx-auto bg-white rounded-xl shadow-md">
      <view class="text-center">
        <view class="text-base text-black font-semibold mb-2">
          Erin Lindford
        </view>
        <view class="text-gray-500 font-medium pb-3">
          Product Engineer
        </view>
        <view
          class="mt-2 px-4 py-1 text-sm text-purple-600 font-semibold rounded-full border border-solid border-purple-200">
          Message
        </view>
      </view>
    </view>
  </view>
</view>
```

更多详细用法请查看[使用原子类](../advance/utility-first-css.md)。

---

---
url: /guide/advance/store.md
---
# 状态管理（store） {#store}

Mpx 参考 vuex 设计实现了外部状态管理系统（store），其中的概念与 api 与 vuex 保持一致，为了更好地支持状态模块管理和跨团队合作场景，我们提出多实例 store 作为 vuex 中 modules 的替代方案，该方案在模块拆分及合并上的灵活性远高于 modules。

## 介绍 {#intro}

`Store` 是一个全局状态管理容器，能够轻松实现复杂场景下的组件通信需求，store 与简单的全局状态对象主要有以下两点不同：

1. Store 中存放的状态是响应式的。当用户将 store 中的状态注入到组件以后，若 store 中状态发生变化，那么对应的组件也会得到更新。

2. 你不能直接改变 store 中的状态。改变 store 中的状态的唯一途径是显式地提交变更（commit mutation），这种方式能使整个应用中的状态变更变得可回朔可追踪，同时也更加安全。

### 创建 store {#create-store}

让我们来创建一个简单 store。创建过程直截了当，仅需要提供一个初始 state 对象和一些 mutation 方法，并调用 Mpx 暴露的 `createStore` 方法进行创建：

```js
import {createStore} from '@mpxjs/core'

const store = createStore({
  state: {
    count: 0
  },
  mutations: {
    increment (state) {
      state.count++
    }
  }
})

export default store
```

现在，你可以通过 store.state 来获取状态对象，以及通过 store.commit 方法触发状态变更：

```js
store.commit('increment')
console.log(store.state.count) // 1
```

接下来，我们将会更深入地探讨一些 store 的核心概念。让我们先从 [State](#state) 开始。

## State

State 存放了 store 中的原始状态数据，可以通过 `store.state` 进行访问。

### 在组件中获取 state {#get-state-in-component}

Mpx 在小程序组件中实现了数据响应，而刚才提到 store 中的状态也是响应式的，组件中获取 store 状态最简单的方法就是建立一个计算属性，在计算属性中访问 store 中需要的状态数据并返回：

```js
// store.js
import {createStore, createComponent} from '@mpxjs/core'

const store = createStore({
  state: {
    count: 0
  },
  mutations: {
    increment (state) {
      state.count++
    }
  }
})

createComponent({
  computed: {
    count () {
      return store.state.count
    }
  }
})
```

当 store.state.count 发生变化时, 组件中访问了 count 计算属性的 watcher 将得到响应。

> 于 vuex 中的不同的地方在于，vuex 奉行`单一状态树`，一个应用当中只存在一个 store 示例，用户能够在组件中通过`this.$store`隐式地访问到当前应用的 store；而 Mpx 当中为了追求灵活便捷的状态模块化管理及跨团队合作的能力，支持了多实例 store，用户需要显式地引入 store 实例，并通过计算属性将其注入到组件当中。

### MapState 辅助函数 {#map-state-helper}

当一个组件需要获取多个状态时候，将这些状态都声明为计算属性会有些重复和冗余。为了解决这个问题，我们可以使用 `mapState` 辅助函数帮助我们生成计算属性

```js
import store from '../store'
import {createComponent} from '@mpxjs/core'

createComponent({
  computed: store.mapState({
    // 箭头函数可使代码更简练
    count: state => state.count,

    // 传字符串参数 'count' 等同于 state => state.count
    countAlias: 'count',

    // 为了能够使用 `this` 获取局部状态，必须使用常规函数
    countPlusLocalState (state) {
      return state.count + this.localCount
    }
  })
})
```

当映射的计算属性的名称与 state 的子节点名称相同时，我们也可以给 mapState 传一个字符串数组。

```js
import store from '../store'
import {createComponent} from '@mpxjs/core'

createComponent({
  computed: store.mapState([
    // 映射 this.count 为 store.state.count
    'count'
  ])
})
```

### 对象展开运算符 {#object-spread-operator}

MapState 函数返回的是一个对象。我们如何将它与局部计算属性混合使用呢？通常，我们需要使用一个工具函数将多个对象合并为一个，以使我们可以将最终对象传给 computed 属性。但是自从有了[对象展开运算符](https://github.com/sebmarkbage/ecmascript-rest-spread)，我们可以极大地简化写法：

```js
import store from '../store'
import {createComponent} from '@mpxjs/core'

createComponent({
  computed: {
    localComputed () { /* ... */ },
    // 使用对象展开运算符将 mapState 返回的对象合并到计算属性中
    ...store.mapState([
      'count',
      // ...
    ])
  }
})
```

> 使用 store 并不意味着你需要将所有的状态放入 store。如果有些状态严格属于单个组件，最好将其放到组件内部的 data 当中。

## Getter

有时候我们需要从 state 中派生出一些状态，例如经过过滤的列表：

```js
createComponent({
  computed: {
    doneTodos () {
      return store.state.todos.filter(todo => todo.done)
    }
  }
})
```

如果有多个组件需要用到此属性，我们要么复制这个函数，或者抽取到一个共享函数然后在多处导入它，无论哪种方式都不是很理想。

这个时候我们可以在 store 中定义 `getter` 来完成这个功能，getter 可以简单认为是 store 中的计算属性。同计算属性一样，getter 的返回值会根据它的依赖被缓存起来，只有当它的依赖发生变化时才会被重新计算。

Getter 接受 state 作为第一个参数：

```js
import {createStore} from '@mpxjs/core'

const store = createStore({
  state: {
    todos: [
      { id: 1, text: 'sth1', done: true },
      { id: 2, text: 'sth2', done: false }
    ]
  },
  getters: {
    doneTodos: state => {
      return state.todos.filter(todo => todo.done)
    }
  }
})

export default store
```

定义好的 getter 可以通过 `store.getters` 访问：

```js
store.getters.doneTodos // -> [{ id: 1, text: '...', done: true }]
```

Getter 也可以接受其他 getters 作为第二个参数, rootState作为第三个参数，rootState是模块化中引入的概念，之后会详细介绍：

```js
getters: {
  // ...
  doneTodosCount: (state, getters, rootState) => {
    return getters.doneTodos.length
  }
}
```

```js
store.getters.doneTodosCount // -> 1
```

我们采用与state类似的方法将其注入到组件中进行访问：

```js
computed: {
  doneTodosCount () {
    return store.getters.doneTodosCount
  }
}
```

### MapGetters 辅助函数 {#map-getters-helper}

`MapGetters` 的作用与使用方法同上面提到的 `mapState` 高度类似，唯一的区别在于 mapGetters 用于映射 store 中的 getter：

```js
import store from '../store'
import {createComponent} from '@mpxjs/core'

createComponent({
  // ...
  computed: {
    // 使用对象展开运算符将 getter 混入 computed 对象中
    ...store.mapGetters([
      'doneTodosCount',
      'anotherGetter',
      // ...
    ])
  }
})
```

如果你想将一个 getter 在组件中映射为另一个名字，使用对象形式：

```js
store.mapGetters({
  // 映射 this.doneCount 为 store.getters.doneTodosCount
  doneCount: 'doneTodosCount'
})
```

## Mutation

更改 store 中的状态的唯一方法是提交 mutation。Mutation 非常类似于事件：每个 mutation 都有一个字符串的**类型（type）** 和 一个**回调函数（handler）**。这个回调函数就是我们实际进行状态更改的地方，它接受 state 作为第一个参数：

```js
import {createStore} from '@mpxjs/core'

const store = createStore({
  state: {
    count: 1
  },
  mutations: {
    increment (state) {
      // 变更状态
      state.count++
    }
  }
})

export default store
```

当你需要触发某个 mutation 时，你需要使用对应的 `type` 调用 `store.commit` 方法，就像触发某个事件一样：

```js
store.commit('increment')
```

### 提交载荷（Payload） {#commit-payload}

你可以向 `store.commit` 传入额外的参数，作为 mutation 的**载荷（payload）**：

```js
// ...
mutations: {
  increment (state, n) {
    state.count += n
  }
}
```

```js
store.commit('increment', 10)
```

在大多数情况下，载荷应该是一个对象，这样可以包含多个字段并且增强 mutation 的可读性：

```js
// ...
mutations: {
  increment (state, payload) {
    state.count += payload.amount
  }
}
```

```js
store.commit('increment', {
  amount: 10
})
```

### Mutation 必须是同步函数 {#mutation-sync}

一条重要的原则就是要记住 **mutation 必须是同步函数**

### 在组件中提交 Mutation {#commit-mutation-in-component}

你可以在组件中使用 `store.commit('increment')` 提交 mutation，或者使用 `store.mapMutations` 辅助函数将组件中名为 `increment` 的 `method` 映射为 `store.commit('increment')` 调用。

```js
import { createComponent } from '@mpxjs/core'
import store from '../store'

createComponent({
  // ...
  methods: {
    ...store.mapMutations([
      // 将 this.increment() 映射为 store.commit('increment')
      'increment', 
       // mapMutations 也支持载荷：将 this.incrementBy(amount) 映射为 store.commit('incrementBy', amount)
      'incrementBy'
    ]),
    // mapMutations同样支持传入对象形式的参数进行别名映射
    ...store.mapMutations({
      // 将 this.add() 映射为 store.commit('increment')
      add: 'increment'
    })
  }
})
```

## Action

Action 类似于 mutation，不同在于：

* Action 不能直接变更状态，但是可以提交 mutation 进行状态变更
* Action 可以包含任意异步操作

让我们来创建一个简单的 action：

```js
import {createStore} from '@mpxjs/core'

const store = createStore({
  state: {
    count: 0
  },
  mutations: {
    increment (state) {
      state.count++
    }
  },
  actions: {
    increment (context) {
      context.commit('increment')
    }
  }
})

export default store
```

Action 函数接受一个 `context` 对象，因此你可以调用 `context.commit` 提交一个 mutation，调用 `context.dispatch` 触发其他的 action 调用，或者通过 `context.rootState`、`context.state` 和 `context.getters` 来获取全局state、局部state 和 全局 getters。

实践中，我们会经常用到 ES2015 的[参数解构](https://github.com/lukehoban/es6features#destructuring)来简化代码：

```js
actions: {
  increment ({ commit }) {
    commit('increment')
  }
}
```

### 调用 action {#dispatch-action}

Action 可以通过 `store.dispatch` 方法进行调用：

```js
store.dispatch('increment')
```

乍一眼看上去感觉多此一举，我们直接分发 mutation 岂不更方便？实际上并非如此，还记得 **mutation 必须同步执行**这个限制么？Action 就不受约束！我们可以在 action 内部执行**异步**操作：

```js
actions: {
  incrementAsync ({ commit }) {
    setTimeout(() => {
      commit('increment')
    }, 1000)
  }
}
```

Action 同样支持载荷：

```js
// 调用载荷
store.dispatch('incrementAsync', {
  amount: 10
})
```

来看一个更加实际的购物车示例，涉及到**调用异步 API** 和**提交多个 mutation**：

```js
actions: {
  checkout ({ commit, state }, products) {
    // 把当前购物车的物品备份起来
    const savedCartItems = [...state.cart.added]
    // 发出结账请求，然后乐观地清空购物车
    commit(types.CHECKOUT_REQUEST)
    // 购物 API 接受一个成功回调和一个失败回调
    shop.buyProducts(
      products,
      // 成功操作
      () => commit(types.CHECKOUT_SUCCESS),
      // 失败操作
      () => commit(types.CHECKOUT_FAILURE, savedCartItems)
    )
  }
}
```

注意我们进行了一系列异步操作，并且通过提交 mutation 来记录 action 产生的副作用（即状态变更）。

### 在组件中调用 Action {#dispatch-action-in-component}

你可以在组件中使用 `store.dispatch('increment')` 进行 action 调用，或者使用 `store.mapActions` 辅助函数将组件中名为 `increment` 的 `method` 映射为 `store.dispatch('increment')`：

```js
import { createComponent } from '@mpxjs/core'
import store from '../store'

createComponent({
  // ...
  methods: {
    ...store.mapActions([
      // 将 this.increment() 映射为 store.dispatch('increment')
      'increment', 
      // mapActions 也支持载荷：将 this.incrementBy(amount) 映射为 store.dispatch('incrementBy', amount)
      'incrementBy'
    ]),
    // mapActions 同样支持传入对象形式的参数进行别名映射
    ...store.mapActions({
      // 将 this.add() 映射为 store.dispatch('increment')
      add: 'increment' 
    })
  }
})
```

### 组合 Action {#compose-action}

Action 通常是异步的，那么如何知道 action 什么时候结束呢？更重要的是，我们如何才能组合多个 action，以处理更加复杂的异步流程？

在 Mpx 中，action 永远返回一个 Promise，你可以在定义 action 手动返回一个 Promise，即使你没有这样做，框架也会对你 action 的返回值进行 `Promise.resolve(returned)` 包装，确保你可以使用 Promise 的方式处理多个 action 之间的异步组合：

```js
actions: {
  actionA ({ commit }) {
    return new Promise((resolve, reject) => {
      setTimeout(() => {
        commit('someMutation')
        resolve()
      }, 1000)
    })
  }
}
```

现在你可以通过 `then` 方法获取 `actionA` 执行完毕的时机：

```js
store.dispatch('actionA').then(() => {
  // ...
})
```

在另外一个 action 中也可以通过这种方式进行一系列异步调用：

```js
actions: {
  // ...
  actionB ({ dispatch, commit }) {
    return dispatch('actionA').then(() => {
      commit('someOtherMutation')
    })
  }
}
```

如果我们利用 [async / await](https://tc39.github.io/ecmascript-asyncawait/)，我们能够更方便地对一系列异步操作进行组合：

```js
// 假设 getData() 和 getOtherData() 返回的是 Promise

actions: {
  async actionA ({ commit }) {
    commit('gotData', await getData())
  },
  async actionB ({ dispatch, commit }) {
    await dispatch('actionA') // 等待 actionA 完成
    commit('gotOtherData', await getOtherData())
  }
}
```

## Modules

> Mpx 虽然支持了 modules，但并不推荐使用。在 Mpx 中，我们更推荐使用[多实例模式](#multi-instance-store)进行对应用状态进行模块划分

在 Mpx 中，modules 的设计与 vuex 中基本保持一致，在 createStore 中将子模块配置传入 modules 配置项中即可使用：

```js
import {createStore} from '@mpxjs/core'

const moduleA = {
  state: { ... },
  mutations: { ... },
  actions: { ... },
  getters: { ... }
}

const moduleB = {
  state: { ... },
  mutations: { ... },
  actions: { ... }
}

const store = createStore({
  modules: {
    moduleA,
    moduleB
  }
})

store.state.moduleA // -> moduleA 的状态
store.state.moduleB // -> moduleB 的状态

export default store
```

> Mpx 并未实现 vuex 中的命名空间，除 state 外的所有属性（getters / mutations / actions）将被平铺展开到根 store 的对应空间下。在多实例 store 中，我们的实现方式则与命名空间高度相似。

### 模块的局部状态 {#module-local-state}

对于模块内部的 mutation 和 getter，接收的第一个参数是模块的局部状态对象。

```js
const moduleA = {
  state: { count: 0 },
  mutations: {
    increment (state) {
      // 这里的 state 对象是模块的局部状态
      state.count++
    }
  },
  getters: {
    doubleCount (state) {
      return state.count * 2
    }
  }
}
```

对于模块内部的 action，局部状态通过 `context.state` 访问，根状态则通过 `context.rootState` 访问：

```js
const moduleA = {
  // ...
  actions: {
    incrementIfOddOnRootSum ({ state, commit, rootState }) {
      if ((state.count + rootState.count) % 2 === 1) {
        commit('increment')
      }
    }
  }
}
```

对于模块内部的 getter，根状态能通过第三个参数访问：

```js
const moduleA = {
  // ...
  getters: {
    sumWithRootCount (state, getters, rootState) {
      return state.count + rootState.count
    }
  }
}
```

### 模块在组件中的引入方式 {#module-import-in-component}

```js
const store = createStore({
  modules: {
    a: {
      state: {
        name: 1
      },
      getters: {
        getName: s => s.name
      }
    },
    b: moduleB
  }
})

createComponent({
  // 我们支持了多种方式引入子模块中的 state
  computed: {
    // 通过函数引入
    ...store.mapState({
      nameA: state => state.a.name
    }),
    // 通过路径字符串引入
    ...store.mapState({
      nameA2: 'a.name'
    }),
    // 通过传入模块路径引入
    ...store.mapState('a', ['name']),
    // 对于 getters / mutations / actions，由于我们没有实现 namespace，子模块当中定义的 getters / mutations / actions 都能在根空间下直接访问，正常调用映射方法即可
    ...store.mapGetters('getName')
  }
})
```

## 多实例 store {#multi-instance-store}

在 Mpx 中，我们允许在一个应用下创建多个 store 实例，进行模块化分布式的数据管理，同时提供了 deps 声明模块依赖的机制，让用户自由组合多个 store 实例并基于这些已有的 store 创建新的继承 store。在实际业务使用中，我们发现多实例模式的灵活性远高于 module，更加适合跨团队合作当中的数据管理。

使用多实例 store 的方式非常简单，你只需要多次调用 `createStore` api 创建出多个 store 示例，并分别将其注入到组件中即可使用，简单示例如下：

```js
import { createComponent, createStore } from '@mpxjs/core'

const storeA = createStore({
  state: {
    countA: 0
  },
  mutations: {
    incrementA (state) {
      state.countA++
    }
  }
})

const storeB = createStore({
  state: {
    countB: 0
  },
  mutations: {
    incrementB (state) {
      state.countB++
    }
  }
})

createComponent({
  computed: {
    // ...
    ...storeA.mapState(['countA']),
    ...storeB.mapState(['countB'])
  },
  methods: {
    // ...
    ...storeA.mapMutations(['incrementA']),
    ...storeB.mapMutations(['incrementB'])
  }
})
```

> 可以看到 Mpx 中的 map 辅助方法都挂载在 store 实例上，正是为了支持多实例 store 的实现

### 合并继承多实例 store {#merge-inherit-store}

在实际的跨团队业务当中，我们既希望不同团队间的数据管理尽量解耦，也希望一些共同的部分能够复用，这就要求我们的 store 实例可以以某种方式组合起来使用，我们提供了 deps 能来实现多实例 store 的合并与继承。

承接上面的示例，我们基于 storeA 和 storeB 创建一个新的 storeC，在 storeC 当中可以定义自身的独立状态，也能基于 storeA 和 storeB 进行状态衍生：

```js
import { createComponent, createStore } from '@mpxjs/core'

const storeA = createStore({
  state: {
    countA: 0
  },
  mutations: {
    incrementA (state) {
      state.countA++
    }
  }
})

const storeB = createStore({
  state: {
    countB: 0
  },
  mutations: {
    incrementB (state) {
      state.countB++
    }
  }
})

const storeC = createStore({
  state: {
    countC: 0
  },
  getters: {
    abc (state) {
      // 此处 state.storeA 指向了原始的 storeA.state
      return state.storeA.countA + state.storeB.countB + state.countC
    }
  },
  mutations: {
    incrementC (state) {
      state.countC++
    }
  },
  actions: {
    incrementB ({ commit }) {
      // storeC内部也可以通过命名空间路径的方式提交 storeB 的 mutation
      commit('storeB.incrementB')
    }
  },
  // 此处 deps 声明了 storeC 的依赖，依赖中的 state / getters / mutations / actions 都会以 deps 中的 key 为命名空间存放在 storeC 对应的域下
  deps: {
    storeA,
    storeB
  }
})

// 通过继承合并得到的 storeC，我们可以完整访问其依赖 storeA / storeB
createComponent({
  computed: {
    // ...
    // 使用路径字符串或函数映射，可以看出和 modules 中 mapState 的方式非常类似
    ...storeC.mapState({
      countA: 'storeA.countA',
      countA2: state => state.storeA.countA
    }),
    // 传入命名空间参数映射 storeB 中的 countB
    ...storeC.mapState('storeB', ['countB']),
    // 映射基于 storeA/B/C 衍生得到的 getters
    ...storeC.mapGetters(['abc'])
  },
  methods: {
    // ...
    // mutation不支持函数映射
    // 下面代码以三种方式分别映射了increment、incrementB和incrementC
    ...storeC.mapMutations({
      incrementA: 'storeA.incrementA'
    }),
    ...storeC.mapMutations('storeB', ['incrementB']),
    ...storeC.mapMutations(['incrementC'])
  }
})
```

> 简单来讲，作为 deps 的 store 会以注册在 deps 中的 key 值作为命名空间，将其原始的 state / getters / mutations / actions 存放在新生成 store 对应的域下，便于新 store 对其进行访问并衍生出新的数据或操作，如上述示例中，storeA.state 会存放在 storeC.state.storeA 中，对于 getters / mutations / actions 亦然。

## 在 Typescript 中使用 store {#use-store-in-ts}

Mpx 自 2.2 版本开始支持 Typescript，为了更好地支持 store 中的类型推导，我们针对 Typescript 环境提供了变种的 store api `createStoreWithThis` 进行 store 创建，该 api 最主要的变化在于定义 getters，mutations 和 actions 时，自身的 state，getters 等属性不再通过参数传入，而是会挂载到函数的执行上下文 `this` 当中，通过 this.state 或 this.getters 的方式进行访问，简单的使用示例如下：

```js
const store = createStoreWithThis({
  state: {
    aa: 1,
    bb: 2
  },
  getters: {
    cc() {
      // 使用 this.state 访问 state
      return this.state.aa + this.state.bb
    }
  },
  actions: {
    doSth3() {
      // 使用 this.getters 访问 getter
      console.log(this.getters.cc)
      return false
    }
  }
})
```

详细的使用方式及推导规则请查看 [Typescript 支持](../tool/ts.md)章节。

## 在组合式 API 中使用 store {#use-store-in-composition-api}

Mpx 自 2.8 版本完整支持了组合式 API 的开发方式，虽然在组合式 API 中我们首推使用 [pinia](pinia.md) 作为外部状态管理方案，不过旧的 store 在组合式 API 中仍然可以使用，我们提供了新的 `mapStateToRefs` 和 `mapGettersToRefs` 便于用户在组合式 API 中访问 `state` 和 `getters`，而对于 `mutations` 和 `actions`，用户可以直接调用 store 实例上的 `commit` 和 `dispatch` 方法进行调用，或者使用原有的 `map*` API 进行映射访问，简单使用示例如下：

```js
import { createPage, createStoreWithThis, watchEffect } from '@mpxjs/core'

const store = createStoreWithThis({
  state: {
    count: 123
  },
  getters: {
    doubleCount () {
      return this.state.count * 2
    }
  },
  mutations: {
    addCount () {
      this.state.count++
    },
    subCount () {
      this.state.count--
    }
  }
})

createPage({
  setup () {
    const { count } = store.mapStateToRefs(['count'])
    const { doubleCount } = store.mapGettersToRefs(['doubleCount'])
    const { addCount } = store.mapMutations(['addCount'])

    watchEffect(() => {
      console.log(count.value, doubleCount.value)
    })

    return {
      count,
      doubleCount,
      addCount,
      subCount () {
        // 两种方式均可以进行 mutations 调用，actions 同理
        store.commit('subCount')
      }
    }
  }
})
```

---

---
url: /guide/advance/pinia.md
---
# 状态管理（pinia） {#pinia}

Mpx 参考 [Pinia](https://pinia.vuejs.org/) 设计实现了一套外部状态逻辑管理系统（pinia），允许跨页面/组件共享状态，其中的概念与 api 与 Pinia 保持一致，同时支持在 Mpx 组合式 API（Composition API）和选项式 API（Options API）模式下使用。

## 介绍 {#intro}

`pinia` 是一个状态管理容器，可支持复杂场景下的组件通信机制，与`Vuex`状态管理不同之处在于：

1. mutations 不再存在，使用 actions 来支持应用中状态的同步和异步变更。

2. 动态创建 store，使用`useStore`实现运行时动态创建 store。

3. 扁平架构，不再有 modules 嵌套结构，支持不同 store 之间的交叉组合方式使用。

### 创建 pinia {#create-pinia}

首先在应用中调用`createPinia`方法来创建全局 pinia 实例。

```js
// app.mpx
import mpx from '@mpxjs/core'
import { createPinia } from '@mpxjs/pinia'

const pinia = createPinia()
```

如果你的应用需要输出 Web 并使用 SSR 渲染模式，请将 pinia 的创建放在 `onAppInit` 钩子中执行并返回。

```js
// app.mpx

import mpx, { createApp } from '@mpxjs/core'
import { createPinia } from '@mpxjs/pinia'

createApp({
  // ...
  onAppInit () {
    const pinia = createPinia()
    return {
      pinia
    }
  }
})
```

### 创建 store {#create-store}

然后调用`defineStore`方法，传入 store 唯一标识（id），来创建一个 store，支持 Setup 和 Options 两种风格的 store。

#### Setup store

与组合式 API 的 setup 函数类似，我们可以传入一个函数，该函数定义了一些响应式属性和方法，并返回一个带有我们想暴露出去的属性和方法的对象。

```js
// setup.js
import { defineStore } from '@mpxjs/pinia'
import { ref, computed } from '@mpxjs/core'

export const useSetupStore = defineStore('setup', () => {
  const count = ref(0)
  const name = ref('pinia')
  const myName = computed(() => {
    return name.value
  })
  function increment() {
    count.value++
  }
  return { count, name, myName, increment }
})
```

在 Setup Store 中：

* `ref()` 就是 `state` 属性
* `computed()` 就是 `getters`
* `function()` 就是 `actions`

#### Options store

```js
// options.js
import { defineStore } from '@mpxjs/pinia'
import { ref } from '@mpxjs/core'

export const useOptionsStore = defineStore('options', {
  state : () => {
    return {
      count: 0,
      name: 'pinia'
    }
  },
  getters: {
    myName(state) {
      return state.name
    }
  },
  actions: {
    increment () {
      this.$patch((state) => {
        state.count++
      })
    }
  }
})
```

### 使用 store {#use-store}

在选项式 API 中使用，如果你不能使用组合式 API，但你可以使用 `computed`, `methods`, '...'，那你可以使用 `mapState()`, `mapActions()` 辅助函数
来将 `state`, `getter`, `action` 等映射到你的组件中。

无论是 optionsStore、还是 setupStore，我们都可以在选项式组件中使用，且使用方式并无差异，下方例子我们统一使用 useSetupStore 来作为示范例

```js
import { createComponent } from '@mpxjs/core'
import { storeToRefs, mapState, mapActions } from '@mpxjs/pinia'
import { useOptionsStore } from 'xxx/options'
import { useSetupStore } from 'xxx/setup'


// 选项式API（Options API）风格下通过mapHelper函数使用
createComponent({
  computed: {
    // 可以访问组件中的 this.name
    // 此处与直接从 useSetupStore 中读取的数据相同
    ...mapState(useSetupStore, ['name', 'count']),
    // 也可以将state修改别名，例如将name 注册为 otherName
    ...mapState(useSetupStore, {
      otherName: 'name',
      // 也可以写一个函数来获取对 useSetupStore 的访问权
      double: store => store.count * 2,
      // 也可以通过访问 `this` 拿到数据
      magicValue() {
        return this.count + this.double
      }
    }),
    // 在pinia中，getter 也是通过 mapState 来进行映射
    ...mapState(useSetupStore, ['myName'])
  },
  methods: {
    ...mapActions(useSetupStore, ['increment']),
    // 也可以将其注册问题 this.setupIncrement 方法
    ...mapActions(useSetupStore, {
      setupIncrement: 'increment'
    })
  }
})
```

**注意：** 在 `pinia` 中，getter 也是通过 mapState 来进行映射

在组合式API (Setup API) 风格下使用

```js
import { useSetupStore } from 'xxx/setup'
import { storeToRefs, mapState, mapActions } from '@mpxjs/pinia'

createComponent({
  setup (props, context) {
    const setupStore = useSetupStore()
    setupStore.count = 2
    // 作为 store 的一个属性，我们可以直接访问任何 getter(与 state )
    setupStore.myName // pinia

    function onIncrementClick() {
      // 调用 action 方法
      setupStore.increment()
      console.log('New Count:', setupStore.count)
    }
    return {
      onIncrementClick,
      ...storeToRefs(setupStore)
    }
  }
})
```

> 注意：在组合式 API（Setup API）模式下，直接解构获取到的 store 数据会失去响应性，需要通过 storeToRefs 方法处理赋予数据响应性。另外`storeToRefs`方法只会返回 state 或 getter。

## 使用插件 {#use-plugin}

Mpx pinia 支持使用插件扩展当前 store 实例的功能，用法如下：

```js
// onStoreAction.js，订阅所有store实例的方法
export const onStoreAction: context => {
  context.store.$onAction((
    {
      name,
      store,
      args,
      after,
      onError
    }) => {
      after(name => {
        console.error('after', name, store, args)
      })

      onError(error => {
        console.log('onError', error)
      })
    }, false)
}

// app.mpx
import mpx from '@mpxjs/core'
import { createPinia } from '@mpxjs/pinia'
import { onStoreAction } from 'xxx/onStoreAction'

const pinia = createPinia()
pinia.use(onStoreAction)
```

---

---
url: /guide/advance/provide-inject.md
---
# 依赖注入（Provide/Inject） {#provide-inject}

## 适用场景 {#usage-scenarios}

通常情况下，从父组件向子组件传递数据时，我们会使用 props 向下传递。如果在一颗组件层级嵌套很深的组件树中，某个深层的子组件依赖一个较远的祖先组件中的部分数据。在这种情况下，如果仅使用 props 则必须将其沿着组件链路逐级传递下去，这就是 **prop 逐级透传（prop-drilling）** 问题。

使用 `provide` 和 `inject` 可以帮助我们解决这一麻烦问题：一个父组件相对于其所有的后代组件，会作为**依赖提供者**。任何后代的组件树，无论层级有多深，都可以**注入**由父组件提供给整条链路的依赖。

![组件间 provide-inject 示意图](https://s3-gz01.didistatic.com/packages-mait/img/bLipGWmlcm1732166788438.png)

## Provide 提供 {#provide}

### 组合式语法 {#composition-syntax}

在组合式语法中，需要使用到 `provide()` 函数，`provide()` 函数接收两个必填参数：

1. 第一个参数表示**注入名**，是一个字符串或者 `Symbol`。后代组件会用注入名来查找期望注入的值，一个组件可以多次调用 `provide()`，使用不同的注入名，注入不同的依赖值。使用 `Symbol` 作为注入名时，只能使用组合式语法而非选项式语法。
2. 第二个参数表示**提供值**，值可以是任意类型，包括响应式的状态，比如一个 `ref`、`reactive` 或者 `computed` 计算值。

```ts
<script setup>
import { computed, provide, ref } from '@mpxjs/core'

// 静态数据
provide(/* 注入名 */ 'message', /* 值 */ 'hello!')

// 使用 Symbol 作为注入名
const key = Symbol()
provide(key, 'hello!')

// 响应式数据
const count = ref(1)
const double = computed(() => count.value * 2)
provide('count', count)
provide('double', double)

</script>
```

### 选项式语法 {#options-syntax}

选项式语法的 `setup()` 中，用法和组合式 API 一致。另外针对选项式语法，我们也提供了 `provide` 选项，它是**一个对象或返回一个对象的函数**。

对于 `provide` 对象上的每一个属性，后代组件会用其 key 为注入名查找期望注入的值，属性的值就是要提供的数据。

如果我们需要提供依赖当前组件实例的状态 (比如在 `data` 属性中定义的数据)，那么需要使用函数形式的 `provide` 选项。需要注意的是，这 **并不会** 使注入保持响应性，如果需要保证注入方和供给方之间的响应性链接，我们需要使用 `computed()` 函数提供一个计算属性。

```ts{17}
<script>
import { createComponent, computed } from '@mpxjs/core'

createComponent({
  data: {
    count: 1,
  },
  // 1. 静态数据可以选择直接使用对象形式
  provide: {
    message: 'hello'
  },
  // 2. 选择使用函数的形式，可以访问到 `this`
  provide() {
    return {
      count: this.count
      // 显式提供一个计算属性
      message: computed(() => this.count * 2)
    }
  }
})
</script>
```

### 应用级顶层 provide {#app-level-provide}

前面介绍的是在一个组件中提供依赖，我们还可以在整个应用层面提供依赖，这样整个应用中所有组件都可以使用。

```ts
import { createApp } from '@mpxjs/core'

createApp({
  // 应用层 provide
  provide() {
    return {
      'appMessage': 'provide from App scope!'
    }
  }
})
```

## Inject 注入 {#inject}

### 组合式语法 {#composition-syntax-1}

`inject()` 函数最多接收三个参数：

* 第一个参数必填，表示**注入名**，字符串类型。
* 第二个参数可选，表示**默认值**。
  * 如果在注入一个值时不确定是否有提供者，那么应该声明一个默认值。如果既没有提供者也没有默认值，则会抛出一个运行时警告。
* 第三个参数可选，表示**是否将默认值视为工厂函数**，布尔类型。
  * 某些场景下，默认值可能需要通过调用一个函数或初始化一个类来生成，或者某些非基础类型数据创建开销比较大，请使用工厂函数来创建默认值。

```ts
<script setup>
import { inject } from '@mpxjs/core'

// 注入 message 依赖
const value = inject('message')
// 创建默认值
const value = inject('message', 'default value')
// 使用工厂函数创建默认值
const value = inject('key', () => new ExpensiveClass(), true)
</script>
```

如果提供的值是一个 ref，注入进来的会是该 ref 对象，而不会自动解包为其内部的值。这使得注入方能够通过 ref 对象和提供方保持响应性链接。

### 选项式语法 {#options-syntax-1}

选项式语法的 `setup()` 中，用法和组合式 API 一致。另外针对选项式语法，我们也提供了 `inject` 选项，它是**一个数组或一个对象**。

1. **数组**形式使用。数组中的每一项对应一个注入名，注入的属性会以同名的 key 暴露到组件实例上。如下示例中，注入名 `"message"` 在注入后以 `this.message` 的形式暴露。另外，`inject` 会在组件自身的状态**之前**被解析，意味着你可以在 `data()` 中访问到注入的属性。

```ts{6}
<script>
import { createComponent } from '@mpxjs/core'

createComponent({
  // 数组形式使用 `inject` 选项
  inject: ['message', 'count'],
  data() {
    return {
      // 可以在 `data()` 中访问到注入的属性
      fullMessage: this.message,
      fullCount: this.count
    }
  }
})
</script>
```

2. **对象**形式使用。相比数组形式，对象形式支持注入**别名**和**默认值**。如下示例，通过 `from` 属性指定原注入名，通过 `default` 属性指定默认值。

```ts
<script>
import { createComponent } from '@mpxjs/core'

createComponent({
  inject: {
    myCount: 'count', // 按注入名 'count' 注入
    message: {
      from: 'message', // 'message' 是原注入名，当与原注入名同名时，这个属性是可选的
      default: 'default value' // 默认值
    },
    user: { // 与原注入名 'user' 同名
      default: () => ({ name: 'Wang' }) // 使用工厂函数创建默认值
    }
  }
})
</script>
```

## 避免注入名潜在冲突 {#avoid-injection-name-conflict}

如果你正在构建大型的应用，包含非常多的依赖提供，那么随处定义的注入名容易存在潜在的同名冲突。在 Mpx 实现中，同名的注入名会覆盖之前已有的注入名对应的提供值。

针对大型应用的最佳实践，我们通常推荐在一个单独的文件中导出这些注入名，可以结合业务模块功能来统一注入名的命名和管理规范。*以下示例仅供参考，具体实现请依据自身实际场景确定。*

```ts
/** 推荐创建一个单独的文件来管理和导出注入名 */

// 1. 使用枚举类型
export const InjectionKeys = {
  user: 'user',
  auth: 'auth',
  product: 'product',
}

// 2. 按业务模块功能划分命名，不容易命名冲突，可读性高
export const InjectionKeys = {
  user: {
    service: 'user:service',
    store: 'user:store',
  },
  auth: {
    service: 'auth:service',
    token: 'auth:token',
  },
  product: {
    list: 'product:list',
    details: 'product:details',
  },
}

// 3. 使用 Symbol 创建唯一注入名，或再结合命名空间
export const InjectionKeys = {
  user: Symbol('user'),
  auth: Symbol('auth'),
  product: Symbol('product'),
}

// 4. 自行实现类似 Symbol polyfill 的命名生成函数
export const createInjectionKey = (module, key) => `${module}:${key}`
export const InjectionKeys = {
  user: createInjectionKey('user', 'service'),
  auth: createInjectionKey('auth', 'token'),
  product: createInjectionKey('product', 'list'),
}
```

## TS 类型支持 {#ts-support}

直接使用字符串注入 key 时，注入值的类型默认推导会是 `unknown`，需要通过泛型参数显式声明。因为无法保证运行时一定存在这个 provide，所以推导类型也可能是 `undefined`。当声明一个默认值后，这个 `undefined` 类型就可以成功被移除。

```ts twoslash
import { inject } from '@mpxjs/core'

const foo1 = inject('foo') // 类型：unknown
const foo2 = inject<string>('foo') // 类型：string | undefined
const foo3 = inject<string>('foo', 'default value') // 类型：string ✅
```

当然，如果你已经确定注入名肯定被提供了，也可以强制断言。

```ts twoslash
import { inject } from '@mpxjs/core'

const foo = inject('foo') as string
```

如果使用 `Symbol` 作为注入名，可以使用我们提供的 `InjectionKey` 泛型接口，使用它对注入名进行注解或者断言后，可以用来在不同组件之间同步注入值的类型。建议将注入 key 放在单独文件，这样方便在多个组件中导入使用。

```ts{4} twoslash
// @errors: 2345 1146 1005
import { provide, inject } from '@mpxjs/core'
import type { InjectionKey } from '@mpxjs/core'

export const key: InjectionKey<string> = Symbol() // 类型注解
// const key = Symbol() as InjectionKey<string> // 类型断言写法等效

provide(key, 'foo') // ✅
provide(key, 123) // 提供值应当为字符串类型

const foo1 = inject(key) // ✅ foo1: string | undefined
const foo2 = inject(key, 'default value') // ✅ foo2: string
const foo3 = inject(key, 123) // 默认值应当为字符串类型
```

> 👀 鼠标悬浮到上面代码可以查看具体 TS 类型

## 跨端差异 {#cross-platform-diff}

* Mpx 输出 **Web** 端，使用规则与 Vue 一致，`provide/inject` 的生效范围严格遵行父子组件关系，只有父组件可以成功向子孙组件提供依赖。
* Mpx 输出 **RN** 端，框架内部基于 React 的 `useContext` 钩子来转换实现，表现和 Web 端一致。
* Mpx 输出 **小程序** 端同样遵循类似 Vue 的父子组件关系，但是在 `slot` 场景下小程序表现会和 Web、RN 端略有差异。举个例子，如下代码所示：在组件 A 的 `template` 模板中包含子组件 B，然后组件 B 通过 `slot` 包含子组件 C，组件 B 和 C 都定义在组件 A 的模板中。该场景下：在 Web 端，组件 A 是 B 的父组件，B 是 C 的父组件，所以 A 和 B 都可以向 C 提供依赖。但在小程序端，B 和 C 的父组件都是 A，组件 B 不能再向 C 提供依赖。这个跨端差异或者说“副作用”可以理解成：Web 端是基于“节点树”，即虚拟组件节点纬度，而小程序的父子组件关系是基于“组件树”，即组件模板维度，也就是说当前组件的创建者（在 WXML/AXML 模板中定义了此组件的组件）才是它的父组件。

```html
<!-- ComponentA -->
<template>
  <view>组件 A</view>
  <ComponentB>
    <ComponentC></ComponentC>
  </ComponentB>
</template>

<!-- ComponentB -->
<template>
  <view>
    <view>组件 B</view>
    <slot></slot>
  </view>
</template>
```

---

---
url: /guide/advance/mixin.md
---
# 使用 mixin {#use-mixin}

Mpx 提供了一套完善的 mixin 机制，有人可能要问，原生小程序中已经支持了 behaviors，为何我们还需要提供 mixin 呢？主要有以下两点原因：

1. Behaviors 是平台限度的，只有在部分小程序平台中可以使用，而且内置 behaviors 承载了除了 mixin 外的其他功能，框架提供的 mixin 是一个与平台无关的基础能力；
2. Behaviors 只有组件支持使用，页面不支持，而且只支持局部声明，框架提供的 mixin 与组件页面无关，且支持全局 mixin 声明。

## 局部 Mixin {#local-mixin}

`App`、`Page`、`Component` 接收 mixins 参数,参数格式为\[Mixin1(Object),Mixin2(Object)]

> Mixin 混合实例对象可以像正常的实例对象一样包含选项，相同选项将进行逻辑合并。举例：如果 mixin1 包含一个钩子 ready,而创建组件 Component 也有一个钩子 ready，两个函数将被调用。 Mixin 钩子按照传入顺序(数组顺序)依次调用，并在调用组件自身的钩子之前被调用。

```js
// mixin.js
export default {
  data: {
    list: {
      'phone': '手机',
      'tv': '电视',
      'computer': '电脑'
    }
  },
  ready () {
    console.log('mixins ready:', this.list.phone)
  }
}
```

```html
<template>
  <view class="list">
    <view wx:for="{{list}}" wx:key="index">{{item}}</view>
  </view>
</template>

<script>
  import { createComponent } from '@mpxjs/core'
  import mixins from '../common/mixins'

  createComponent({
    mixins: [mixins],
    data: {
      list: ['手机', '电视', '电脑']
    },
    ready () {
      console.log('component ready:', this.list.phone)
    }
  })
</script>
```

```shell
// 输出结果为
mixins ready: 手机
component ready: 手机
```

## 全局 Mixin {#global-mixin}

Mpx 中可以使用 `mpx.injectMixins` 方法配置全局 mixin，能够按照 App / 组件 / 页面维度自由配置，简单示例如下：

```js
import mpx from '@mpxjs/core'

// 第一个参数为 mixins，可以混入任意配置，第二个参数为混入生效范围，可传递 'app' / 'page' / 'component' 字符串或由其组成的数组
mpx.injectMixins([
  {
    data: {
      customData: '123'
    }
  }
], ['page'])

// mpx.mixin 为 mpx.injectMixins 的别名，混入单个 mixin 时可以直接传递对象，生效范围可传递字符串
mpx.mixin({
  methods: {
    useCustomData () {
      console.log(this.customData)
    }
  }
}, 'component')

// 当未传递生效范围时默认为全局生效，对 app / page / component 都生效
mpx.mixin({
  computed: {
    processedCustomData () {
      return this.customData + '321'
    }
  }
})
```

---

---
url: /guide/advance/npm.md
---
# 使用npm {#use-npm}

Mpx项目中用户能够方便自然地引用 npm 资源，像 web 开发中一样

在 Mpx 中使用 npm，通过 Webpack 插件在编译时将引用的 npm 包输出为小程序文件，所以 Mpx 的构建产物不需要在开发工具再次进行 npm 构建。

## 下载npm包 {#download-npm-package}

在项目 package.json 所在的目录中执行命令安装项目 npm 包

```js
npm install
```

在项目中安装某个第三方 npm 包

```js
npm install mpx-ui
```

如若之前未接触过 npm，请翻阅 [官方 npm 文档](https://docs.npmjs.com/about-npm/index.html) 进行学习。

## 引用npm模块 {#import-npm-module}

直接使用模块路径引用，可以直接通过 ES6 的 import 语法来引用 JS 文件，并且无需额外执行npm构建

```js
import { createPage } from '@mpxjs/core'
```

## 引用npm组件/页面 {#import-npm-component-page}

在页面 script 标签中的 json 对象中使用 usingComponents 引入第三方组件，直接使用模块路径引用

```js
<script type="application/json">
  {
    "usingComponents": {
      "mpx-button": "mpx-ui/src/components/button"
    }
  }
</script>
```

在 app.mpx 中的 script 标签中的 pages/packages/subPackages 中都可以声明引用 npm 包页面

示例:

```js
<script type="application/json">
  {
    "pages": [
      "@someGroup/someNpmPackage/pages/view/index.mpx"
    ]
  }
</script>
```

以上这种写法为避免和本地页面路径冲突，Mpx 会将路径进行 hash 化处理，所以使用页面时要在路径后添加 ?resovle 标识符，编译时会被处理成正确的、完整的绝对路径。

```js
import packageIndexPage from '@someGroup/someNpmPackage/pages/view/index.mpx?resolve'

mpx.navigateTo({
  url: packageIndexPage
})
```

如果你觉得上述引用 npm 包页面的方式太繁琐，我们也提供了另一种 page 声明方式，可以让你自定义页面路径

```js
// 声明
{
  "pages": [
    {
      "src": "@someGroup/someNpmPackage/pages/view/index.mpx",
      "path": "pages/somNpmPackage/index" // 注意保持 path 的唯一性
    }
  ]
}

// 使用
// 可以直接使用你自己声明的 path
mpx.navigateTo({
  url: '/pages/somNpmPackage/index'
})
```

同理，我们在使用 subPackages 分包时也可以使用 pages 对象的方式

```js
"subPackages": [
  {
    "root": "test",
    "pages": [
       {
         "src": "@someGroup/someNpmPackage/pages/view/index.mpx",
         "path": "pages/somNpmPackage/index" // 注意保持 path 的唯一性
       }
    ]
  }
]
// 使用
mpx.navigateTo({
  url: '/test/pages/somNpmPackage/index'
})
```

同时使用 Mpx 引用npm组件/页面时包体积比原生中的 npm 规范更优，好处有：

Mpx npm构建的优势主要有两点：1. 按需构建；2. 支持分包

* 小程序的 npm 规范场景下，组件库需声明miniprogram\_dist目录，执行构建npm命令，将整个miniprogram\_dist中的代码copy到项目的miniprogram\_npm目录下。而 Mpx 的 npm 包引用，借助 Webpack 强大的构建分析能力，loader 在解析 json 中的 pages 域和 usingComponents 域中的路径时，通过动态创建 entry 的方式把这些文件添加进来，同时按需加载被确切使用的文件，降低包体积，借助  CommonsChunkPlugin/SplitChunksPlugin 的能力将复用的 js 模块抽出到一个外部公用的 bundle 中。

* 原生小程序的构建中，所有的 npm 模块都会输出到主包中，Mpx 在编译中，还会进行分包处理，对组件和静态资源，根据用户的分包配置，串行对主包和各个分包进行构建，标记出每个组件及静态资源的归属，根据小程序资源访问策略将其输出到主包或者分包中。

所以使用 Mpx 框架开发小程序，可以享受最舒适最自然最好用的 npm 机制，详细原理介绍请移步[Mpx编译构建原理](../understand/compile.md)

## 兼容原生小程序路径规范 {#compatible-native-path}

组件或者页面的引入有绝对路径和相对路径，或者引入 npm 第三方包，原生小程序中，我们通过相对路径引入一个组件时

```js
{
  "usingComponents": {
    "component-tag-name": "path/to/the/custom/component"
  }
}
```

这种路径形式在 webpack 路径规范中会被当成 npm 包路径来处理，所以要对原生小程序的路径规范做下兼容。

Mpx 提供了两种路径规范的配置模式可供大家选择，具体的使用方式为：

```js
// vue.config.js
module.exports = defineConfig({
  pluginOptions: {
    mpx: {
      plugin: {
         resolveMode: 'webpack'
      }
    }
  }
})
```

在 MpxWebpackPlugin 插件中设置 resolveMode 项，默认值为 webpack，可选值有 webpack/native，推荐使用 webpack 模式，更舒服一些，配置项为 webpack 时，json 中的 pages/usingComponents 等需要写相对路径，但是也可以直接写 npm 包路径。例如：

```js
{
  "usingComponents": {
    "component-tag-name": "./path/to/the/custom/component", // 内部组件路径
    "mpx-button": "mpx-ui/src/components/button" // npm 包路径
  }
}
```

如果希望使用类似小程序原始那种"绝对路径"，可以将 resolveMode 设置为 native，但是 npm 路径需要在前面加一个~，类似 webpack 的样式引入规范，同时必须配合 projectRoot 参数提供项目根目录地址。

resolveMode 为 native 时的使用示例：

```js
// vue.config.js
module.exports = defineConfig({
  pluginOptions: {
    mpx: {
      plugin: {
        resolveMode: 'native',
        // 当resolveMode为native时可通过该字段指定项目根目录
        projectRoot: path.resolve(__dirname, '../src')
      }
    }
  }
})

// 项目page.mpx
{
  "usingComponents": {
    "mpx-button": "~mpx-ui/src/components/button", // npm 包路径
    "component-tag-name": "path/to/the/custom/component" // 内部组件路径
  }
}
```

---

---
url: /guide/advance/subpackage.md
---
# 使用分包 {#use-subpackage}

作为一个对 performance 极度重视的框架，分包作为提升小程序体验的重要能力，框架对各种类型的分包能力进行了完善支持。

> 分包是小程序平台提供的原生能力，mpx是对该能力做了部分加强，目前各大主流小程序平台都已支持分包，且框架在可能的情况下进行了抹平。

> 使用分包一定要记得阅读下面的[分包注意事项](#subpackage-notes)

## 原生语法注册分包 {#native-syntax-register-subpackage}

Mpx 支持小程序原生语法注册分包，并且在框架层面对不同平台的的差异进行了抹平，我们以微信小程序原生语法注册分包为例。

```json
{
  "pages": [
    "pages/index/index"
  ],
  "subPackages": [
    {
      "root": "test",
      "pages": [
        "pages/other/other",
        "pages/other/other2"
      ]
    }
  ]
}
```

## packages 语法注册分包 {#packages-syntax-subpackage}

Mpx 提供 packages 语法来对小程序的主包页面和分包划分能力进行增强，使用 packages 语法可以灵活的对业务进行拆分，允许以 npm 包的形式进行
主包页面和分包注册，且分包名和页面路径可自定义，十分有利于大型多团队开发的项目维护。

### 使用方法 {#usage}

Mpx 拓展了 app.json 的语法，新增了 packages 域，用来声明依赖的 packages，packages 可嵌套依赖。

#### 注册主包页面 {#register-main-package-page}

首先我们介绍下 packages 注册主包页面的用法，在 packages 中直接配置资源路径，Mpx 会去读取该资源中 json 区块中的 pages 属性，合并到主包页面配置中。

```html
// @file src/app.mpx
<script type="application/json">
  {
    "pages": [
      "./pages/index/index"
    ],
    "packages": [
      "{npmPackage || relativePathToPackage}/index"
    ]
  }
</script>

// @file src/packages/index.mpx
// 注意确保页面路径的唯一性
<script type="application/json">
  {
    "pages": [
      "./pages/other/other",
      "./pages/other/other2"
    ]
  }
</script>
```

打包结果：dist/app.json

```json
{
  "pages": [
    "pages/index/index",
    "pages/other/other",
    "pages/other/other2"
  ]
}
```

#### 注册分包 {#register-subpackage}

Mpx 会将 packages 域下的路径带 root 为 key 的 query 解析注册为分包，使用 packages 语法注册分包，只需要在 packages 中配置资源路径添加 `root=xxx`，root的值即为分包名。

```html
// @file src/app.mpx
<script type="application/json">
  {
    "pages": [
      "./pages/index/index"
    ],
    "packages": [
      "{npmPackage || relativePathToPackage}/index?root=test"
    ]
  }
</script>

// @file src/packages/index.mpx (子包的入口文件)
<script type="application/json">
  {
    "pages": [
      "./pages/other/other",
      "./pages/other/other2"
    ]
  }
</script>
```

打包结果：dist/app.json

```json
{
  "pages": [
    "pages/index/index"
  ],
  "subPackages": [
    {
      "root": "test",
      "pages": [
        "pages/other/other",
        "pages/other/other2"
      ]
    }
  ]
}
```

由上可见，经过我们的编译过程，packages 中注册的页面可按照原始的路径被合并入主包页面或注册为分包，
这样开发者可以不用考虑自己在被依赖时页面路径是怎么样的，也可以直接将调试用的app.mpx作为依赖入口直接暴露出去，
对于主app的开发者来说也不需要了解依赖内部的细节，只需要在packages中声明自己所需的依赖即可。

### 注意事项 {#notes}

* 依赖的开发者在自己的入口 app.mpx 中注册页面时对于本地页面一定要使用相对路径进行注册，否则在主app中进行编译时会找不到对应的页面
* 不管是用 json 还是 mpx 格式定义 package 入口，编译时永远只会解析 json 且只会关注 json 中的 pages 和 packages 域，其余所有东西在主app编译时都会被忽略
* 由于我们是将 packages 中注册的页面按照原始的路径合并到主 app 当中，有可能会出现路径名冲突。\
  这种情况下编译会报出响应错误提示用户解决冲突，为了避免这种情况的发生，依赖的提供者最好将自己内部的页面放置在能够描述依赖特性的子文件夹下。

例如一个包叫login，建议包内页面文件目录为：

```
project
│   app.mpx  
└───pages
    └───login
        │   page1.mpx
        │   page2.mpx
        │   ...
```

## 独立分包 {#independent-subpackage}

Mpx目前已支持独立分包构建，使用 [packages](#packages) 语法声明分包时只需要在后面添加 `independent=true` query 即可，同时也支持原生语法声明。
如下方示例声明 packageA 分包为独立分包

**示例：**

```json5
// src/app.mpx 文件中 json 块

// Mpx packages 方式
{
  "packages": [
    "packageA/app.mpx?root=packageA&independent=true"
  ]
}
```

```json5
// 微信原生方式
{
  "subpackages": [
    {
      "root": "packageA",
      "pages": [
        "pages/index"
      ],
      "independent": true
    },
  ]
}
```

需要注意的是，由于独立分包可以独立于主包和其他分包运行，从独立分包页面进入小程序时，主包中的相应初始化逻辑并不会执行，如果独立分包中多个页面需要某种通用初始化逻辑时就无法优雅的实现，
Mpx框架针对独立分包场景提供了独立分包初始化逻辑执行能力。

对于使用 packages 方式声明的独立分包，默认将 .mpx 文件自身的 script 块作为初始化逻辑执行。

```html
<!--src/packagesA/app.mpx，packageA 独立分包入口文件-->
<script>
import mpx from '@mpxjs/core'
import apiProxy from '@mpxjs/api-proxy'

mpx.use(apiProxy, { usePromise: true }) 
if (isIndependent) {
    // do some in independent package
} else {
    // do some not independent package
}
</script>

<script type="application/json">
{
  "pages": [
    "./pages/index"
  ]
}
</script>
```

上方代码中 独立分包 packageA 的入口文件 app.mpx 中的 script block 代码会默认在独立分包初始化时执行，Mpx 同时提供了全局变量 `isIndependent` 标识当前代码执行环境是否为独立分包来进行特定逻辑区分

如果你不想走这个默认的初始化逻辑执行规则，想自定义一个 js 文件存储当前独立分包的初始化逻辑，我们支持 independent 配置项直接配置为初始化逻辑文件地址

```json5
// src/app.mpx 文件中 json 块
// Mpx packages 方式
{
  "packages": [
    "packageA/app.mpx?root=packageA&independent=./common" // 路径上下文为 packageA 文件夹
  ]
}
```

```json5
// 微信原生方式
{
  "subpackages": [
    {
      "root": "packageA",
      "pages": [
        "pages/index"
      ],
      "independent": "./common" // 路径上下文为 packageA 文件夹
    },
  ]
}
```

```js
// src/pacakgeA/common.js
import mpx from '@mpxjs/core'
import apiProxy from '@mpxjs/api-proxy'

mpx.use(apiProxy, { usePromise: true })
if (isIndependent) {
    // do some in independent package
} else {
    // do some not independent package
}
```

注意上方配置 independent 为初始化逻辑文件地址时，路径相对地址上下文为 packageA

## 分包预下载 {#subpackage-preload}

分包预下载是在 json中 新增一个 preloadRule 字段，mpx 打包时候会原封不动把这个部分放到 app.json 中，所以只需要按照 [微信小程序官方文档 - 分包预下载](https://developers.weixin.qq.com/miniprogram/dev/framework/subpackages/preload.html) 或者 [支付宝小程序官方文档 - 分包预下载](https://opendocs.alipay.com/mini/framework/subpackages) 配置即可。

**示例：**

```html
// @file src/app.mpx
<script type="application/json">
  {
    "pages": [
      "./pages/index/index"
    ],
    "packages": [
      "{npmPackage || relativePathToPackage}/index?root=xxx"
    ],
    "preloadRule": {
      "pages/index": {
        "network": "all",
        "packages": ["important"]
      },
      "sub1/index": {
        "packages": ["hello", "sub3"]
      }
    }
  }
</script>

// @file src/packages/index.mpx (子包的入口文件)
<script type="application/json">
  {
    "pages": [
      "./pages/other/other",
      "./pages/other/other2"
    ]
  }
</script>
```

打包结果：dist/app.json

```json
{
  "pages": [
    "pages/index/index"
  ],
  "subPackages": [
    {
      "root": "xxx",
      "pages": [
        "pages/other/other",
        "pages/other/other2"
      ]
    }
  ],
  "preloadRule": {
    "pages/index": {
      "network": "all",
      "packages": ["important"]
    },
    "sub1/index": {
      "packages": ["hello", "sub3"]
    }
  }  
}
```

## 分包注意事项 {#subpackage-notes}

当我们使用分包加载时，依赖包内的跳转路径需注意，比如要跳转到other2页面

* 不用分包时会是：/pages/other/other2
* 使用分包后应为：/test/pages/other/other2

即前面会多?root={rootKey}的rootKey这一层

为了解决这个问题，有三种方案：

* import的时候在最后加'?resolve', 例如: `import testPagePath from '../pages/testPage.mpx?resolve'` , 编译时就会把它处理成正确的完整的绝对路径。

* 使用相对路径跳转。

* 定死使用的分包路径名，直接写/{rootKey}/pages/xxx （极度不推荐，尤其在分包可能被多方引用的情况时）

这里我们建议使用第一种方式。

---

---
url: /guide/advance/async-subpackage.md
---
# 分包异步化 {#subpackage-async}

> 在小程序中，不同的分包对应不同的下载单元；因此，除了非独立分包可以依赖主包外，分包之间不能互相使用自定义组件或进行 require。
> 「分包异步化」特性将允许通过一些配置和新的接口，使部分跨分包的内容可以等待下载后异步使用，从而一定程度上解决这个限制。

具体功能介绍和功能目的可 [点击查看](https://developers.weixin.qq.com/miniprogram/dev/framework/subpackages/async.html), Mpx对于分包异步化功能进行了完整支持。

当前 Mpx 框架默认支持以下平台的分包异步化能力：

* 微信小程序
* 支付宝小程序
* 字节小程序
* Web
* RN

在非上述平台，异步分包代码会默认降级。

## 跨分包自定义组件引用 {#cross-subpackage-component}

> 一个分包使用其他分包的自定义组件时，由于其他分包还未下载或注入，其他分包的组件处于不可用的状态。通过为其他分包的自定义组件设置 占位组件，
> 我们可以先渲染占位组件作为替代，在分包下载完成后再进行替换。

在 Mpx 中使用跨分包自定义组件引用通过?root声明组件所属异步分包即可使用，示例如下：

```html
<!--/packageA/pages/index.mpx-->
// 这里在分包packageA中即可异步使用分包packageB中的hello组件
<script type="application/json">
  {
    "usingComponents": {
      "hello": "../../packageB/components/hello?root=packageB",
      "simple-hello": "../components/hello"
    },
    "componentPlaceholder": {
      "hello": "simple-hello"
    }
  }
</script>
```

* 注意项：目前该能力已在微信、支付宝、Web和RN环境下支持，其他环境下框架将进行自动降级。

## 跨分包 JS 代码引用 {#cross-subpackage-js}

> 一个分包中的代码引用其它分包的代码时，为了不让下载阻塞代码运行，我们需要异步获取引用的结果

在 Mpx 中跨分包异步引用 JS 代码时，**需要在引用的 JS 路径后拼接 JS 模块所在的分包名**，此外由于 **require** 不能传入多个参数的限制，在Mpx中无法使用回调函数的
风格跨分包 JS 代码引用，只能使用 Promise 风格。

示例如下：

```js
// subPackageA/index.js
// 或者使用 Promise 风格的调用
require.async('../commonPackage/index.js?root=subPackageB').then(pkg => {
  pkg.getPackageName() // 'common'
})
```

* 注意项：目前该能力仅微信平台下支持，其他平台下框架将会自动降级

## 跨分包 Store 引用 {#cross-subpackage-store}

在 Mpx 中如果想要跨分包异步引用 Store 代码，分为三个步骤

* 页面或父组件在 `created` 钩子加载异步 Store
* 异步 Store 加载完成后再渲染使用异步 Store 的组件
* 子组件在框架内部生命周期 `BEFORECREATE` 钩子中动态注入 computed 和 methods

```html
<!--pages/index/index.mpx-->
<template>
  <store-list wx:if="{{showStoreList}}"></store-list>
</template>

<script>
  import { createPage } from '@mpxjs/core'
  createPage({
    data: {
      showStoreList: false
    },
    created () {
      require.async('../subpackages/sub2/store?root=sub2').then(store => {
        getApp().asyncStore.sub2 = store.default
        // 当异步 Store 加载完成后再渲染使用异步 Store 的组件
        this.showStoreList = true
      })
    }
  })
</script>

<!-- 子组件:store-list -->
<script>
  import { createComponent, BEFORECREATE } from '@mpxjs/core'
  createComponent({
    // 在 BEFORECREATE 钩子中动态注入 options
    [BEFORECREATE] () {
      // 获取异步 Store实例
      const subStore = getApp().asyncStore.sub2
      // computed 中 mapState、mapGetters 替换为 mapStateToInstance、mapGettersToInstance，最后一个参数必须传当前 component 实例 this
      subStore.mapStateToInstance(['pagename'], this)
      subStore.mapGettersToInstance(['pageDataGetter'], this)
      // methods 中 mapActions、mapMutations 替换为 mapMutationsToInstance、mapActionsToInstance，最后一个参数必须传当前 component 实例 this
      subStore.mapMutationsToInstance(['updatePageData'], this)
      subStore.mapActionsToInstance(['updatePageName'], this)
    }
  })
</script>
```

---

---
url: /guide/advance/i18n.md
---
# 国际化i18n {#i18n}

Mpx 支持国际化 i18n，使用方式及支持能力与 vue-i18n 非常接近。

Mpx 自带 i18n 能力，无需额外安装插件。由于小程序模板中的 i18n 函数是通过 wxs 编译注入进行实现，我们需要将 i18n 配置传入到 MpxWebpackPlugin 中来使 i18n 生效，这是与 vue-i18n 最大的区别。

## 开启 i18n {#enable-i18n}

I18n 配置传入到 MpxWebpackPlugin 选项中即可生效，额外支持 messagesPath 配置，通过模块路径传入语言集，其余配置参考 vue-i18n。

由于小程序的双线程特性，在选项式 API 场景下，默认情况下模板中调用的 i18n 函数由 wxs 实现，而 js 中调用的 i18n 函数由 js 实现，该设计能够将视图层和逻辑层之间的通信开销降至最低，得到最优的性能表现，但是由于 wxs 和 js 之间无法共享数据，在最终的编译产物中语言集会同时存在于 js 和 wxs 当中，对包体积产生负面影响。

为了平衡上述影响，自2.6.56版本之后我们新增了编译配置项 `i18n.useComputed` ，改配置项开启的情况下对于模板中的 i18n 调用将不再使用 wxs 实现，而是通过在 computed 进行实现，语言集将只存在于 js 逻辑层当中，对于节省了包体积的同时双线程通信成本也会增加，用时间换空间，具体是否开启可以根据实际项目的使用情况及资源瓶颈由开发者自行决定，
另外需要注意的是，**在 Mpx 组合式 API 场景下 i18n 仅支持通过 computed 实现**。

> 开启 `i18n.useComputed` 配置时，由于 computed 技术架构的限制，i18n 函数无法对模板循环渲染中的 `item` 或 `index` 生效。

```js
// vue.config.js
module.exports = defineConfig({
  pluginOptions: {
    mpx: {
      plugin: {
        i18n: {
          locale: 'en-US',
          // messages既可以通过对象字面量传入，也可以通过messagesPath指定一个js模块路径，在该模块中定义配置并导出，dateTimeFormats/dateTimeFormatsPath和numberFormats/numberFormatsPath同理
          messages: {
            'en-US': {
              message: {
                hello: '{msg} world'
              }
            },
            'zh-CN': {
              message: {
                hello: '{msg} 世界'
              }
            }
          },
          useComputed: false // 默认 false,  此开关将模板中的 i18n 函数注入 computed，在包体积空间紧张的情况下可以使用
          // messagesPath: path.resolve(__dirname, '../src/i18n.js')
        }
      }
    }
  }
})
```

## 选项式 API 中使用 {#options-api-usage}

同 vue-i18n，在组件中直接调用翻译函数使用，由于 wxs 执行环境的限制，目前 js 中支持了 vue-i18n 中 $t/$tc/$te 翻译函数，$d/$n 暂不支持，详细使用方法可参考 vue-i18n。

此外类似于 vue-i18n，在组件模板的 Mustache 插值中直接调用翻译函数。

```html
<template>
    <view>
        <view wx:if="{{isMessageExist}}">{{ $t('message.hello', { msg: 'hello' }) }}</view>
    </view>
</template>
<script>
    createComponent({
        ready () {
            console.log(this.$t('message.hello', { msg: 'hello' }))
        },
        computed: {
            isMessageExist () {
                return this.$te('message.hello')
            }
        }
    })
</script>
```

## 在组合式 API 中使用 {#composition-api-usage}

在组合式 API setup 中，`this` 不是该活跃实例的引用，为了继续使用 i18n 的相关能力，我们需要一个新的方法来替代 `this`
，这里 Mpx 提供 `useI18n` 方法支持对 i18n 相关功能的使用。

### 开始使用 {#start-using}

同 vue-i18n, **useI18n** 返回一个 i18n 实例，该实例提供文案翻译 API 例如 **t** 方法，相较于选项式 API 中的翻译方法，在组合式 API 中有部分变化。

1. 翻译方法 $t/t 和 $tc/tc，在组合式 API 中统一使用翻译方法 t
2. 翻译方法 $te/te，在组合式 API 中统一使用 te
3. 翻译方法 $tm/tm，在组合式 API 中统一使用 tm

`useI18n` 方法的执行必须在 `setup` 中的顶层。

i18n 同时也支持传入参数，例如 `locale` 和 `fallbackLocale`，
关于实例的更多信息可移步API章节 [查看](../../api/extend.md#usei18n)

在不给 `useI18n` 传入任何参数时，i18n 实例的上下文将是全局作用域，即翻译函数 `t` 引用的文案来源是我们在 `MpxWebpackPlugin`
中配置的文案。

通过在 **setup** 中返回翻译函数 **t**，我们可以在模版中直接使用它:

```html
<template>
    <view>{{t("message.hello")}}</view>
</template>
```

```js
import {createComponent, useI18n} from '@mpxjs/core'

createComponent({
  setup(props, context) {
    const { t } = useI18n() // 从返回中解构出 t 方法
    return {
      t
    } // 将 t 方法返回挂载到渲染实例
  }
})
```

**注意事项：**

组合式 API 中，Mpx 在编译时对模版进行 ast 遍历分析，检测到对应的翻译函数 t/tc/te 后，将其转换为 computed 方法注入，computed 中调用 setup 中返回的 t 方法进行文案获取，由此引申出来两个注意项：

1.不可对从 **useI18n** 中解构出的 **t** 方法进行重命名，否则模版中将无法正确获取文案。

下方即为错误示例：

```html
<template>
    <view>{{t1('message.hello')}}</view>
</template>
<script>
    import {createComponent, useI18n} from '@mpxjs/core'
    createComponent({
        setup() {
            const {t: t1} = useI18n()
            return {
                t1
            }
        }
    })
</script>
```

2.模版中的 t/tc/te 方法都是使用 computed 实现，由于 computed 技术架构的限制，i18n 函数无法对模板循环渲染中的 `item` 或 `index` 生效。

例如下方示例将会报错 computed 中找不到 item

```html
<template>
    <!--tc方法使用 computed 实现，最终将无法正确获取item-->
    <view wx:for="{{listData}}" wx:key="index">{{tc('message.hello', {msg: item})}}</view>
</template>
<script>
    import {createComponent, ref, useI18n} from '@mpxjs/core'
    createComponent({
        setup() {
            const listData = ref([1,2,3])
            const {tc} = useI18n()
            return {
                tc,
                listData
            }
        }
    })
</script>
```

## 作用域 {#scope}

在 Mpx 组合式 API 中，`useI18n` 返回的 i18n 实例默认是指向全局作用域，文案来源即为 `MpxWebpackPlugin` 中配置的 messages。

如果需要在组合式 API 中使用本地作用域，需要给 `useI18n` 传入响应的配置项，`useI18n` 将根据传入的 locale、messages 等配置项来生成一个全新的
i18n 实例，该实例的文案源即为用户传入的 `messages`。

```html
<template>
    <!--将展示本地作用域中的文案 哈喽-->
    <view>{{t('message.hello')}}</view>
</template>
<script>
    import {createPage, useI18n} from '@mpxjs/core'
    createPage({
        setup() {
            const { t } = useI18n({
                locale: 'en-US',
                messages: {
                    'en-US': {
                        message: {
                            hello: '哈喽'
                        }
                    }
                }
            })
            return {
                t
            }
        }
    })
</script>
```

**注意事项：**

在给 `useI18n` 传参时，若只传入 `messages` 属性，则 `locale` 会自动 fallback 到全局 locale，修改 `useI18n` 返回的 `locale` ref 值将改变本地作用域  locale。

若只传入 `locale` 属性，不传入 `messages`，则会自动 fallback 到全局 `locale` 和 `messages`，且修改 `useI18n` 返回的 `locale` 对**全局和本地都不会起作用**，
因此建议不要单独传入 `locale` 属性，若想使用本地 i18n 实例，则必须传入 `messages` 属性。

在 Mpx 选项式 API 中，i18n 实例仅有全局 global i18n 实例，所有 i18n 翻译方法 $t/$tc/$te/$tm 的执行上下文都为全局作用域。

```html
<template>
    <view>{{$t('message.hello')}}</view>
</template>
<script>
    import {createPage} from '@mpxjs/core'
    createPage({
        onLoad() {
            console.log(this.$i18n)
            /**
             * locale 全局 locale
             * fallbackLocale 全局兜底 locale
             */
        },
        computed: {
            name() {
                // 作用域为 global scope
                return this.$t('message.name')
            }
        }
    })
</script>
```

## 动态变更locale {#dynamic-change-locale}

在 Mpx 组合式 API 中，你可以通过修改 `useI18n` 返回的 `locale` 来更换局部或全局语言，或者更改 mpx.i18n 中的 locale 属性更换全局语言集，并自动更新视图。

* 变更全局 locale

```js
import mpx, { createComponent, useI18n } from '@mpxjs/core'

createComponent({
  setup () {
    // 局部locale变更，生效范围为当前组件内
    const {t, locale} = useI18n()
    setTimeout(() => {
      // 全局locale变更，生效范围为项目全局，locale 是一个 ref 变量
      locale.value = 'zh-CN'
      // 或者通过mpx.i18n来修改，也能起到全局locale修改作用
      mpx.i18n.locale = 'zh-CN'
    }, 1000)
    return {
        t
    }  
  }
})
```

**注意：** 这里通过 mpx.i18n 修改 locale 时，为和 vue3 保持一直，需要通过 global 属性来获取 locale，同时 locale 也是一个 ref 变量，需要使用 `.value` 来修改。

* 变更局部 locale

```js
import mpx, { createComponent, useI18n } from '@mpxjs/core'

createComponent({
  setup () {
    // 局部locale变更，生效范围为当前组件内
    const {t, locale} = useI18n({
        locale: 'en-US',
        messages: {
            'en-US': {
                message: {
                    hello: 'hello'
                }
            },
            'zh-CN': {
                message: {
                    hello: '你好'
                }
            }
        }
    })
    setTimeout(() => {
      // 局部locale变更，生效范围为当前组件/页面，locale 是一个 ref 变量
      locale.value = 'zh-CN'
    }, 1000)
    return {
        t
    }  
  }
})
```

在选项式 API 中，仅支持修改全局 locale, 不支持修改局部 locale。

在 Vue3 中，选项式 API 中直接修改 this.$i18n.locale 无任何作用，这里为和 Vue3 拉齐建议使用 mpx.i18n 来进行 locale 修改。

```js
import mpx, { createComponent } from '@mpxjs/core'

createComponent({
  ready () {
      // 修改全局 locale
      mpx.i18n.locale = 'en-US'
  }
})
```

## 动态更新语言集 {#dynamic-update-language-set}

在组合式 API 中默认支持动态更新语言集。

在选项式 API 中，当模板中没有使用 i18n 函数或开启了 `i18n.useComputed` 配置时, 可以对语言集进行动态更新。

我们提供了 `mergeLocaleMessage` 对语言集进行动态扩展，`setLocaleMessage` 对语言集进行覆盖更新。

使用方式如下：

```html
<template>
    <!--2 秒之后展示 哈喽-->
    <view>{{t('message.hello')}}</view>
    <!--1秒之后展示 hello1, 2秒之后展示为 恭喜你-->
    <view>{{t('message.hello1')}}</view>
</template>
<script>
    import mpx, { createComponent, useI18n} from '@mpxjs/core'

    createComponent({
        setup () {
            const { t, mergeLocaleMessage, setLocaleMessage } = useI18n()
            setTimeout(() => {
                // 新增一门语言或针对特定语言更新语言集
                mergeLocaleMessage('en-US', {
                    message: {
                        hello1: 'hello1',
                    }
                })
            }, 1000)
            setTimeout(() => {
                setLocaleMessage('en-US', {
                    message: {
                        hello: '哈喽',
                        hello1: '恭喜你'
                    }
                })
            }, 2000)
            return { t }
        }
    })
</script>
```

同理我们在选项式 API 中可以使用 `mpx.i18n.global.mergeLocaleMessage`, `mpx.i18n.global.setLocaleMessage` 方法来动态更新或扩展语言集。

## 平台支持 {#platform-support}

目前支持业内所有小程序平台(微信/支付宝/qq/百度/头条)。

在输出 web 时，构建会自动引入 vue-i18n 并进行安装配置，无需修改任何代码即可按照预期正常工作。

---

---
url: /guide/advance/size-report.md
---
# 包体积分析 {#bundle-size-analysis}

目前业内主流小程序平台都对小程序的代码包设置了严格的体积限制，微信是单包 2MB，总包 16MB，支付宝是单包 2MB，总包 8MB；包体积作为有限的资源，在小程序业务开发中异常重要，特别对于像滴滴出行这样的大型复杂业务。

Mpx 在包体积控制上做了很多工作，主要包括：

* [完善的分包支持](./subpackage.md#分包)
* [基于依赖声明的按需构建](npm.md)
* [图像资源处理](image-process.md)
* [公共样式复用](../basic/css.md#common-style-reuse)

此外由于 Mpx 的编译构建完全基于 webpack，也能够直接复用webpack生态自带的代码压缩，模块复用，tree shaking，side effects 等能力对代码体积进行优化。

但是系统能做的工作终究有限，在一些人为不规范操作的影响下，最终输出的项目依然可能存在大量优化空间，比如在业务中不会被调用但无法被 tree shaking / side effects 移除的代码，因为 npm 依赖版本不统一造成的重复依赖，未经压缩的图像静态资源等，在大型项目中，这些问题想要被发现会非常困难，因此我们非常需要一个体积分析工具来管控项目体积和发现隐藏的体积问题。

## 与 webpack-bundle-analyzer 的区别 {#diff-webpack-bundle-analyzer}

`webpack-bundle-analyzer` 提供了非常完善的体积分析和可视化展示能力，但是在 Mpx 构建输出小程序场景下，其所提供的能力还是有所缺失：

* 只能对 js 资源进行模块体积分析，而小程序的输出中包含了大量的非 js 静态资源，如 wxss / wxml / json 等，这些资源的体积都不会被统计分析；
* 没有针对某个分包进行体积分析的能力，由于小程序中存在对单一分包的体积限制，我们的体积往往会集中在主包和主要业务分包中，以分包维度进行体积分析的能力非常必要；
* 无法以特定的输入范围为维度进行体积的统计分析，这个能力诉求更多地出现在跨团队合作的复杂小程序当中，如滴滴出行。在这种场景下，接入合作的各方会更加关注己方引入的体积，并进行针对性地优化。

由于上述原因，我们提供了`@mpxjs/size-report`插件提供包体积分析能力，弥补了 `webpack-bundle-analyzer` 的能力缺失，为业务提供了便捷准确的包体积管控优化抓手。

## 使用方法 {#usage}

#### 安装插件 {#install-plugin}

```
npm i @mpxjs/size-report --save-dev
```

#### 配置插件 {#config-plugin}

在项目 webpack.config 文件中配置使用 `@mpxjs/size-report` 插件即可使用，简单示例如下：

```js
// vue.config.js
const MpxSizeReportPlugin = require('@mpxjs/size-report')
module.exports = defineConfig({
  configureWebpack() {
    return {
      plugins: [
        new MpxSizeReportPlugin(
          {
              // 本地可视化服务相关配置
              server: {
                  enable: true, // 是否启动本地服务，非必填，默认 true
                  autoOpenBrowser: true, // 是否自动打开可视化平台页面，非必填，默认 true
                  port: 0, // 本地服务端口，非必填，默认 0(随机端口)
                  host: '127.0.0.1', // 本地服务host，非必填
              },
              // 体积报告生成后输出的文件地址名，路径相对为 dist/wx 或者 dist/ali
              filename: '../report.json',
              // 配置阈值，此处代表总包体积阈值为 16MB，分包体积阈值为 2MB，超出将会触发编译报错提醒，该报错不阻断构建
              threshold: {
                  size: '16MB',
                  packages: '2MB'
              },
              // 配置体积计算分组，以输入分组为维度对体积进行分析，当没有该配置时结果中将不会包含分组体积信息
              groups: [
                  {
                      // 分组名称
                      name: 'vant',
                      // 配置分组 entry 匹配规则，小程序中所有的页面和组件都可被视为 entry，如下所示的分组配置将计算项目中引入的 vant 组件带来的体积占用
                      entryRules: {
                          include: '@vant/weapp'
                      }
                  },
                  {
                      name: 'pageGroup',
                      // 每个分组中可分别配置阈值，如果不配置则表示
                      threshold: '500KB',
                      entryRules: {
                          include: ['src/pages/index', 'src/pages/user']
                      }
                  },
                  {
                      name: 'someSdk',
                      entryRules: {
                          include: ['@somegroup/someSdk/index', '@somegroup/someSdk2/index']
                      },
                      // 有的时候你可能希望计算纯 js 入口引入的体积（不包含组件和页面），这种情况下需要使用 noEntryRules
                      noEntryRules: {
                          include: 'src/lib/sdk.js'
                      }
                  }
              ],
              // 是否收集页面维度体积详情，默认 false
              reportPages: true,
              // 是否收集资源维度体积详情，默认 false
              reportAssets: true,
              // 是否收集冗余资源，默认 false
              reportRedundance: true,
              // 展示某些分包资源的引用来源信息，默认为 []
              showEntrysPackages: ['main']
          }
      )
      ]
    }
  }
})
```

参考上述示例进行配置后，构建代码后，dist 目录下会产出 report.json 文件，里边是项目的具体体积信息，关于输入 json 的简单示例如下：

```html
{
    // 项目体积概要，大部分情况下，我们只需要看这部分就足够了
    "sizeSummary": {
        // 分组体积概要，与上述配置文件中的 groups 对应
        "groups": [
            {
                "name": "vant",
                // 只有该分组包含的模块体积
                "selfSize": "164.75KiB",
                "selfSizeInfo": {
                  // 该分组所占 shansong
                  "shansong": "164.75KiB"
                },
                "sharedSize": "885.68KiB",
                "sharedSizeInfo": {
                  "main": "885.68KiB"
                }
            },
        ],
        // 项目各个分包以及主包体积概要
        "sizeInfo": {
            "main": "1000KiB",
            "fenbao1": "200kiB"
        },
        // 项目总体积
        "totalSize": "13468.85KiB",
        // 项目静态资源总体积
        "staticSize": "4880.58KiB",
        // 项目chunk 文件总体积
        "chunkSize": "8587.70KiB",
        // 非依赖项体积大小
        "copySize": "1KiB"
    },
    // 分组资源详细体积
    "groupsSizeInfo": [
        {
            "name": "groupOne",
            // group 自身包含的 module 详情列表
            "selfEntryModules": [],
            // group 与其他group 共有的 module 详情列表
            "sharedEntryModules": [],
            // 自身包含 module 体积
            "selfSize": "",
            // 自身包含 module 体积详情
            "selfSizeInfo": {
                "main": {},
                "homepage": {}
            },
            // 与其他 group 共有 module 体积
            "sharedSize": "",
            // 与其他 group 共有 module 体积详情
            "sharedSizeInfo": {
                "main": {},
                "homepage": {}
            },

        }
    ],
    // 项目资源详细体积报告
    "assetsSizeInfo": {
        "assets": [{
            // 资源类型
            "type": "chunk",
            "name": "test",
            // 分包名
            "packageName": "main",
            "size": "",
            "modules": []
        }]
    }
}
```

与此同时，如果你开启了本地可视化平台服务，可以直接通过可视化平台查看项目体积构成。默认开启自动打开平台网页或者手动打开后，整体页面展示如下图：

[![size-report](https://gift-static.hongyibo.com.cn/static/kfpub/3547/feat1.png)](https://mpxjs.cn)

可视化平台中包含三部分功能，第一个体积分析如上图所示，主要是展示整体项目的体积总览，以及 group 体积列表和分包体积列表。

第二个功能是体积详情模块，在该模块中，可以最小颗粒度的查看包体积构成，通过 table 表格的层层展开可看到每个 group 中包含的分包，点击分包可看到该分包包含的静态资源和 js 模块详细列表，同时聚合模式可将分散的模块整合为具体的npm包名，方便宏观查看。此外为了方便用户定向查看某个特定资源的分布情况，列表上方可进行资源路径/名称搜索，该搜索支持模糊匹配，搜索结果为该资源在项目中 group 和 分包的分布情况。

[![size-report](https://gift-static.hongyibo.com.cn/static/kfpub/3547/feat2.png)](https://mpxjs.cn)

第三个功能为体积对比功能，这里主要进行项目不同版本之间的体积大小变化比较，体积对比依赖插件生成的json文件，通过该功能，可具体的分析出包体积具体增大的group，分包，以及模块，给包体积优化提供定向目标。

[![size-report](https://gift-static.hongyibo.com.cn/static/kfpub/3547/feat3.png)](https://mpxjs.cn)

## 业务实践 {#business-practice}

目前 sizeReport 工具在滴滴出行小程序, 花小猪, 青桔骑行, 特惠出行小程序以及一部分外部小程序中使用。

在滴滴出行小程序中，配置使用 @mpxjs/size-report 插件后使包体积管控和优化更加工程化：

* 在 sizeReport 检测结果文件中，通过对 groupsSizeInfo 和 assetsSizeInfo 中assets 与 module 体积分析，我们发现了部分体积较大图片文件和css资源，通过将图片存 CDN 和删除冗余文件；

* 基于各小程序平台对小程序总包，主包，分包有大小限制的原则，给各接入方配置了主包和首页分包体积大小占比阈值，在构建时检测到包体积超过阈值时，抛出 error 阻断构建，开发者可通过 size-report.json 中详细的包体积分析准确的找到体积变动点。

## 总结 {#summary}

Mpx sizeReport 工具对小程序体积计算有更细微(模块级别)的体积展示。 更加适合小程序开发场景的包体积分析。

---

---
url: /guide/advance/perf.md
---
# RN 运行时按需测速 {#rn-runtime-perf-probe}

Mpx 跨端输出 React Native 时，运行时核心组件（`mpx-view` / `mpx-text` / `mpx-simple-view` / `mpx-simple-text` 等）以及 `useTransformStyle` / `__getStyle` 等公共函数是高频热路径。Hermes Profiler / Flipper 难以直接表达 Mpx 自身的逻辑分段，`@mpxjs/perf` 提供可按构建关闭、关闭态零残留的显式性能探针。

## 三类统计能力 {#statistics}

| 统计类型 | API | 输出 | 典型用途 |
| --- | --- | --- | --- |
| 区段聚类统计 | `aggrStart` / `aggrEnd` | `Map<string, AggrResult>` | 高频 render、hook、函数的 count/sum/avg/max |
| 区段序列统计 | `traceStart` / `traceEnd` | `TraceTimeline` | 模块火焰图、嵌套调用 profile、异步区段瀑布图 |
| 点序列统计 | `mark` | `MarkTimeline` | 数据就绪、首次渲染、页面可交互等里程碑 |

`start/end` 控制整个录制窗口，Reporter 在窗口结束时同步收到三类结果。聚类统计不保留逐次样本，适合高频热路径；trace 和 mark 会保留事件对象，只适合有限插桩点和诊断窗口。

## 设计原则 {#design-principles}

`@mpxjs/perf` 采用「编译期常量开关 + 运行时探针实现 + tree-shaking 兜底」三层结构：

1. `MpxWebpackPlugin` 通过 `DefinePlugin` 注入 `__mpx_perf__` 和分组常量。
2. 探针调用直接包在 `if (__mpx_perf_framework__)` / `if (__mpx_perf_user__)` 字面量条件里。
3. Terser 消除关闭分组的调用点，webpack tree-shaking 继续剔除失活的实现模块。

关闭态产物中不会保留探针实现、名称字符串或模块依赖。

::: warning 该方案不支持线上动态开关
线上开关意味着探针字节必须进入产物，与关闭态零残留目标冲突。线上诊断需重新构建一个开启探针的内测包。
:::

## 配置入口 {#config}

在 `mpx.config.js` 的 `pluginOptions.mpx.plugin` 下配置 `perf`：

```js
const { defineConfig } = require('@vue/cli-service')

module.exports = defineConfig({
  pluginOptions: {
    mpx: {
      plugin: {
        perf: {
          enable: !!process.env.MPX_PERF,
          probes: ['framework', 'user']
        }
      }
    }
  }
})
```

### 配置项说明 {#config-options}

| 字段 | 类型 | 说明 |
| --- | --- | --- |
| `enable` | `boolean` | 总开关。`false` 或不传时整套探针关闭。 |
| `probes` | `string[]` | 当前支持 `'framework'` / `'user'`。空数组等价于关闭，未知分组会在编译期报错。 |

| 分组 | 控制对象 | 典型用途 |
| --- | --- | --- |
| `framework` | 框架内建探针，如 `view:render:*` / `getStyle:*` | 调试 Mpx 框架自身渲染性能 |
| `user` | 业务自定义探针 | 定位业务流程和函数耗时 |

两个分组独立 DCE，但共享同一个录制窗口和 Reporter。

## 录制窗口 {#recording-window}

```ts
import { start, end } from '@mpxjs/perf'

router.beforeEnter('/goods/:id', () => {
  if (__mpx_perf__) {
    start({
      markLimit: 2048,
      traceLimit: 4096
    })
  }
})

router.beforeLeave('/goods/:id', () => {
  if (__mpx_perf__) end()
})
```

```ts
interface PerfStartOptions {
  markLimit?: number
  traceLimit?: number
}
```

* `markLimit` 是 `MarkTimeline` 的总事件上限，包含 start/end 边界，默认 1024，必须是不小于 2 的整数。
* `traceLimit` 是 trace 区段上限，默认 1024，必须是非负整数；传 `0` 可关闭当前窗口的 trace 存储。
* 无效值回退为 1024。
* 录制中重复调用 `start(options)` 保持幂等，不清空数据，也不修改当前容量。
* 新窗口重新读取配置，不继承上一窗口的自定义容量。

`start()` 自动生成 `{ name: 'start', start: 0, timestamp: startedAt }`，`end()` 自动生成同结构的 end 边界。即使没有显式探针，完整窗口也会触发 Reporter。

## 区段聚类统计 {#aggregate}

聚类 API 将同名样本实时合并为 `{ count, sum, avg, max }`，不保存逐次耗时。

### id 模式 {#aggregate-id}

默认 id 模式支持嵌套、乱序结束和同名并发，也是同步高频路径的首选：

```ts
import { aggrStart, aggrEnd } from '@mpxjs/perf'

function expensiveCompute (data) {
  let id = -1
  if (__mpx_perf_user__) id = aggrStart('myBiz:list:filter')
  const result = data.filter(/* ... */).sort(/* ... */)
  if (__mpx_perf_user__) aggrEnd(id)
  return result
}
```

未录制时 `aggrStart(name)` 返回 `-1` 且不读取时钟。录制中使用数组槽位和 free list，稳态零对象、零闭包分配。

### name 模式 {#aggregate-name}

开始和结束不方便传递 id 时，显式传入 `useName: true`：

```ts
if (__mpx_perf_user__) aggrStart('goods:request', true)

loadPageData().finally(() => {
  if (__mpx_perf_user__) aggrEnd('goods:request')
})
```

name 模式允许在录制窗口外保存起点，只有 `aggrEnd(name)` 发生在录制中时样本才会进入结果。后一次同名 start 会覆盖前一次起点，同名并发必须改用 id 模式。

## 区段序列统计 {#trace}

trace 保存每次区段的开始位置和持续时长，可还原模块火焰图或异步瀑布图：

```ts
import { traceStart, traceEnd } from '@mpxjs/perf'

let appId = -1
let routerId = -1
if (__mpx_perf_user__) {
  appId = traceStart('module:app')
  routerId = traceStart('module:router')
}

if (__mpx_perf_user__) {
  traceEnd(routerId, { moduleId: 42 })
  traceEnd(appId, { moduleId: 1 })
}
```

trace 在 start 时预留事件位置，在 end 时回填 `duration` / `info`，因此嵌套区段始终按 start 顺序输出。未完成区段在窗口结束时从 `events` 移除，并计入 `incomplete`。

跨作用域且不方便传递 id 时可以使用 name 模式：

```ts
if (__mpx_perf_user__) traceStart('request:goods', true)

loadPageData().finally(() => {
  if (__mpx_perf_user__) {
    traceEnd('request:goods', { status: 'fulfilled' })
  }
})
```

trace 必须在录制窗口中 start。name 模式同名覆盖时，被覆盖的旧区段会计入 `incomplete`；同名并发、递归和严格嵌套必须使用 id 模式。上一窗口未消费的旧 id 不能结束下一窗口的新事件。

## 点序列统计 {#mark}

`mark(name, info?)` 记录瞬时里程碑，不产生聚合桶：

```ts
import { mark } from '@mpxjs/perf'

if (__mpx_perf_user__) {
  mark('goods:data-ready', {
    source: 'cache',
    itemCount: 20
  })
}
```

同名 mark 仍是多条独立事件。`info` 按引用保存，不复制、不校验、不序列化；建议只传小型、可序列化的诊断字段，不要传组件实例、完整 props、响应体或大数组。

## 数据结构 {#data-types}

```ts
interface AggrResult {
  count: number
  sum: number
  avg: number
  max: number
}

interface MarkEvent {
  name: string
  start: number
  timestamp: number
  info?: unknown
}

interface MarkTimeline {
  events: MarkEvent[]
  dropped: number
}

interface TraceEvent {
  name: string
  start: number
  timestamp: number
  duration: number
  info?: unknown
}

interface TraceTimeline {
  events: TraceEvent[]
  dropped: number
  incomplete: number
}
```

`start` 是相对当前录制窗口起点的毫秒偏移。`timestamp` 是 `performance.now()`、Hermes `nativePerformanceNow()` 或 `Date.now()` 返回的原始值，不保证是 Unix epoch；同一运行环境和窗口中的值可以直接比较。

mark 和 trace 使用独立容量。达到上限后只增加对应 `dropped`，不保存事件、时间、name 或 info。mark 始终为 end 边界预留最后一个位置。

## Reporter {#reporter}

```ts
type Reporter = (
  aggregates: Map<string, AggrResult>,
  marks?: MarkTimeline,
  traces?: TraceTimeline
) => void
```

通过正常 `start/end` 完成的窗口始终传入 marks 和 traces；后两个参数保持可选，兼容旧的一、二参数 Reporter 和外部手动调用。

```ts
import { setReporter } from '@mpxjs/perf'
import type {
  AggrResult,
  MarkTimeline,
  TraceTimeline
} from '@mpxjs/perf'

if (__mpx_perf__) {
  setReporter((
    aggregates: Map<string, AggrResult>,
    marks?: MarkTimeline,
    traces?: TraceTimeline
  ) => {
    MyAPM.report('mpx_perf_aggregates', aggregates)
    if (marks) MyAPM.report('mpx_perf_marks', marks)
    if (traces) MyAPM.report('mpx_perf_traces', traces)
  })
}
```

全局 Reporter 和 `end(localReporter)` 传入的局部 Reporter 会依次收到同一份 Map、marks 和 traces 引用。不要直接修改；需要改写时自行复制。

::: warning 注册时机
`setReporter` 必须直接放在 `if (__mpx_perf__)` 中，确保自定义函数和闭包也能在关闭态被 DCE。
:::

### Console Reporter {#console-reporter}

默认 `consoleReporter` 分别输出 aggregates、traces 和 marks。`createConsoleReporter({ sortBy, filter, header })` 可定制：

* `sortBy` 只影响 aggregates。
* `filter` 同时作用于 aggregate、trace 和显式 mark，内建 start/end 不会隐藏。
* trace 和 mark 保持原始顺序。
* 仅有事件包含 info 时显示 info 列。
* mark dropped、trace dropped 和 trace incomplete 分别提示。
* info 的 JSON 格式化失败不会中断业务或其他统计输出。

### Chrome Trace 对接 {#chrome-trace}

`TraceEvent` 可映射为 Chrome Trace / Perfetto Complete Event：

```ts
const chromeEvents = traces.events.map(event => ({
  name: event.name,
  ph: 'X',
  ts: event.timestamp * 1000,
  dur: event.duration * 1000,
  args: event.info
}))
```

核心包不内置文件写入或格式转换器，业务 Reporter 可按需补充 `pid` / `tid` / `cat` 等字段。MarkEvent 可用同一 `timestamp * 1000` 规则映射为 Instant Event。

## API 参考 {#api}

| API | 说明 |
| --- | --- |
| `aggrStart(name, useName?)` | 默认返回数字 id；传 `true` 改用 name 配对。 |
| `aggrEnd(idOrName)` | 完成区段并实时聚合；无效或重复目标安全 noop。 |
| `traceStart(name, useName?)` | 默认返回数字 id；传 `true` 改用 name 配对。 |
| `traceEnd(idOrName, info?)` | 完成 trace 并保存可选 info。 |
| `mark(name, info?)` | 追加独立、有序的点事件。 |
| `start(options?)` | 创建录制窗口和三类容器；重复 start 幂等。 |
| `end(reporter?)` | 关闭窗口，回填 avg、压缩未完成 trace 并触发 Reporter。 |
| `setReporter(r)` / `clearReporter()` | 替换或清空全局 Reporter。 |
| `createConsoleReporter(opts?)` | 创建可配置的 Console Reporter。 |
| `consoleReporter` | 默认 Reporter。 |

### 旧 API 兼容 {#legacy-api}

| 旧 API | 内部映射 | 兼容语义 |
| --- | --- | --- |
| `scopeStart(name)` | `aggrStart(name)` | 返回 id；未录制返回 `-1`。 |
| `scopeEnd(id)` | `aggrEnd(id)` | 负 id 和重复结束安全 noop。 |
| `measureStart(name)` | `aggrStart(name, true)` | 后一次同名 start 覆盖前一次。 |
| `measureEnd(name)` | `aggrEnd(name)` | 命中后消费起点。 |

四个旧函数继续导出且没有移除版本，但新代码优先使用 `aggrStart/aggrEnd`。聚合结果类型已由 `AggResult` 更名为 `AggrResult`，不保留旧类型别名；`MarkEvent.at` 已更名为 `start`，并新增 `timestamp` / `info`。

## 内置框架探针事件 schema {#schema}

现有框架探针继续通过兼容的 `scopeStart/scopeEnd` 采集同步 render 聚合耗时。

### `mpx-view` {#schema-view}

| 事件名 | 覆盖代码段 |
| --- | --- |
| `view:render:total` | 整个 `forwardRef` 回调 |
| `view:render:props` | `splitProps` + 解构 + `useHover` |
| `view:render:style` | `useTransformStyle` + `splitStyle` + 布局和动画 Hook |
| `view:render:innerProps` | `useInnerProps` |
| `view:render:createElement` | `wrapWithChildren` + `createElement` 收尾 |

### `mpx-simple-view` {#schema-simple-view}

| 事件名 | 覆盖代码段 |
| --- | --- |
| `simple-view:render:total` | 整个函数 |
| `simple-view:render:style` | `splitProps` + `splitStyle` + 样式变换 |
| `simple-view:render:innerProps` | `useInnerProps` |
| `simple-view:render:createElement` | `wrapChildren` + `createElement` 收尾 |

### `mpx-text` {#schema-text}

| 事件名 | 覆盖代码段 |
| --- | --- |
| `text:render:total` | 整个 `forwardRef` 回调 |
| `text:render:props` | 文本上下文 + props 合并 |
| `text:render:style` | 样式转换、继承与拆分 |
| `text:render:innerProps` | `useInnerProps` |
| `text:render:createElement` | `decode` + `wrapChildren` + `createElement` 收尾 |

### `mpx-simple-text` {#schema-simple-text}

| 事件名 | 覆盖代码段 |
| --- | --- |
| `simple-text:render:total` | 整个函数 |
| `simple-text:render:style` | 文本上下文、样式和 props 合并 |
| `simple-text:render:innerProps` | `useInnerProps` |
| `simple-text:render:createElement` | `wrapChildren` + `createElement` 收尾 |

### `@mpxjs/core: __getStyle` {#schema-getstyle}

| 事件名 | 覆盖代码段 |
| --- | --- |
| `getStyle:total` | 整个 `__getStyle` 函数 |
| `getStyle:class` | class 解析与样式查找 |
| `getStyle:style` | 静态/动态 style 解析与转换 |

## 性能影响评估 {#perf-impact}

| 能力 | 未录制 | 录制中 |
| --- | --- | --- |
| aggr id 模式 | 状态判断后返回 `-1` | 数组槽位 + free list；稳态零对象、零闭包分配 |
| aggr name 模式 | 保存 name 起点 | Map set/get/delete；只保留聚合桶 |
| trace | 状态判断后 noop | 每个被接受区段一个事件对象和一条进行中映射，默认最多 1024 条 |
| mark | 状态判断后 noop | 每个显式 mark 一个事件对象，默认最多 1022 条，加边界后最多 1024 条 |

::: tip 聚合与事件序列的取舍
高频 render 和函数耗时使用 aggr；需要火焰图或逐区段瀑布图时使用 trace；里程碑使用 mark。trace/mark 不能替代渲染循环中的聚类统计。
:::

## 与现有工具的关系 {#vs-others}

* **Hermes Profiler**：提供 JS 函数级采样；trace 提供 Mpx 业务语义明确的区段序列，两者可使用相同 performance 时钟对照分析。
* **Perfetto / Chrome Trace**：Perf 的 trace 是稳定数据源，业务 Reporter 负责转换和补充进程、线程、分类字段。
* **业务 APM**：Perf 不替代 APM，只提供聚合、区段和里程碑数据。

## Terser / Babel 兼容性约束 {#terser-babel}

* 最终构建依赖 `@mpxjs/perf` 的 `dist/index.js` 保留顶层三元、`sideEffects: false` 与使用方 Terser 完成 DCE。
* 探针调用必须直接置于 `if (__mpx_perf_framework__)` / `if (__mpx_perf_user__)` 字面量条件内。
* 接入方需保留默认 Terser 的 `dead_code` / `conditionals` 优化。
* Babel 不应提前破坏 `__mpx_perf__ ? impl.x : noop.x` 顶层三元结构。

---

---
url: /guide/advance/image-process.md
---
# 图像资源处理 {#image-processing}

> Mpx在小程序开发中提供了很好的图像资源处理能力，让开发者可以愉快地在项目中使用图片。

## 图像资源引入有三种方式 {#three-ways-to-import-images}

1. Template 中通过 image src 指定图像资源
   * 直接指定图像的远程资源地址
   * 资源为本地路径，若配置 publicPath，则 publicPath 与 webpack loader 中配置的 name 进行拼接
2. Style 中通过 src 指定图像资源
3. Style 中通过 class 指定图像资源

Wxss文件中只能用 CDN 地址或 Base64, 针对第二、三种方式引入的资源，可以通过配置决定使用 CDN 还是 Base64，且 Mpx 中图像资源处理会优先检查 Base64，具体配置参数如下：

* publicPath：资源存放 CDN 地址，可选
* limit: 资源大小限制，可根据资源的大小判断走 Base64 还是 CDN， 可选
* publicPathScope: 限制输出 CDN 图像资源的范围，可选 styleOnly、all，默认为 styleOnly。（图像引用方式分两大类 Template, Style）
* outputPathCDN: 设置 CDN 图像对应的本地相对地址（相对于当前编译输出目录的地址，如 dist,或者 dist/wx），可写脚本将本地图像批量上传到 CDN

## Base64 图像资源 {#base64-image}

图像转 Base64的两种方式:

* 未配置 publicPath
* 配置了 publicPath，且用户未自定义图像处理 fallback query，且未配置 limit 或图像资源未超过 limit 的限制时

```js
// webpack.config.js 配置,未配置 publicPath 必走 Base64
const webpackConfig = {
  module: {
    rules: [{
      test: /\.(png|jpe?g|gif|svg)$/,
      loader: MpxWebpackPlugin.urlLoader({
        name: 'img/[name][hash].[ext]'
      })
    }]
  }
}
```

::: tip @mpxjs/cli 3.x 版本配置如下

```js
// vue.config.js
const { defineConfig } = require('@vue/cli-service')
module.exports = defineConfig({
  pluginOptions: {
    mpx: {
      urlLoader: {
        name: 'img/[name][hash].[ext]'
      }
    }
  }
})
```

:::

```css
<style>
  .logo {
    background-image: url('~images/logo.png');
  }
</style>
```

## CDN 图像资源 {#cdn-image}

```js
// webpack.config.js 配置
const webpackConfig = {
  module: {
    rules: [{
      test: /\.(png|jpe?g|gif|svg)$/,
      loader: MpxWebpackPlugin.urlLoader({
        name: 'img/[name][hash].[ext]',
        // CDN 地址
        publicPath: 'http://a.com/',
        limit: '1024' // Base64 的最大长度，超过则走 CDN 
      })
    }]
  }
}
```

::: tip @mpxjs/cli 3.x 版本配置如下

```js
// vue.config.js
const { defineConfig } = require('@vue/cli-service')
module.exports = defineConfig({
  pluginOptions: {
    mpx: {
      urlLoader: {
        name: 'img/[name][hash].[ext]',
        // CDN 地址
        publicPath: 'http://a.com/',
        limit: '1024' // Base64 的最大长度，超过则走 CDN 
      }
    }
  }
})
```

:::

## CDN 图像资源输出本地目录，用户自行批量上传到CDN服务器 {#cdn-image-local-output}

```js
// webpack.config.js 配置
const webpackConfig = {
  module: {
    rules: [{
      test: /\.(png|jpe?g|gif|svg)$/,
      loader: MpxWebpackPlugin.urlLoader({
          name: 'img/[name][hash].[ext]',
          publicPath: 'http://a.com',
          limit: 100,
          publicPathScope: 'styleOnly',
          outputPathCDN: './cdnImages'
      })
    }]
  }
}
```

::: tip @mpxjs/cli 3.x 版本配置如下

```js
// vue.config.js
const { defineConfig } = require('@vue/cli-service')
module.exports = defineConfig({
  pluginOptions: {
    mpx: {
      urlLoader: {
        name: 'img/[name][hash].[ext]',
        publicPath: 'http://a.com',
        limit: 100,
        publicPathScope: 'styleOnly',
        outputPathCDN: './cdnImages'
      }
    }
  }
})
```

:::

> 备注:\
> 图像默认编译后会输出到 img 目录下, 当设置 outputPathCDN 后，输出的本地图像地址为 outputPathCDN + img/图像.png\
> CDN 文件地址为 publicPath + img/图像.png，所以当使用脚本上传到 CDN 时，路径要带上 img

## 用户自定义图像处理方式 {#custom-image-processing}

```js
// webpack.config.js 配置
const webpackConfig = {
  module: {
    rules: [{
      test: /\.(png|jpe?g|gif|svg)$/,
      loader: MpxWebpackPlugin.urlLoader({
        name: 'img/[name][hash].[ext]',
        // CDN 地址
        publicPath: 'http://a.com/',
        limit: '1024' // Base64 的最大长度，超过则走 CDN,
        fallback: 'file-loader' // 默认走 file-loader
      })
    }]
  }
}
```

::: tip @mpxjs/cli 3.x 版本配置如下

```js
// vue.config.js
const { defineConfig } = require('@vue/cli-service')
module.exports = defineConfig({
  pluginOptions: {
    mpx: {
      urlLoader: {
        name: 'img/[name][hash].[ext]',
        // CDN 地址
        publicPath: 'http://a.com/',
        limit: '1024' // Base64 的最大长度，超过则走 CDN,
        fallback: 'file-loader' // 默认走 file-loader
      }
    }
  }
})
```

:::

```css
/*不走 Base64 的情况下*/
<style>
  .logo2 {
    background-image: url('~images/logo.png?fallback=true');
  }
</style>
```

---

---
url: /guide/advance/progressive.md
---
# 原生渐进迁移 {#native-progressive-migration}

**已有项目** 期望接入 Mpx，可根据项目或人力情况选择如何迁移，Mpx 不要求用户一次性用上框架的所有东西。

1. 项目初始期：可以考虑一次性转为 Mpx，此时迁移成本比较低
2. 项目成熟期：若人力有限，可选择逐步将原生小程序转为Mpx，而且 **`不需要对原有代码做全局重写`**。可参考此demo：[Mpx渐进接入demo](https://github.com/didi/mpx/tree/master/examples/mpx-progressive)。
   * 可以保持原有代码不变，新的组件、页面期望使用 Mpx 某些特性时才引入 Mpx。（推荐新模块引 Mpx，老模块逐步迁移 Mpx）
   * 用 Mpx 编写新的页面、组件，再局部导出对应的页面、组件，反向应用到现有的原生小程序项目中。见[导出原生](#导出原生)一节。(建议优先考虑老项目渐进改为 Mpx，而不是反向 Mpx 输出原生小程序的模式)

## 原生接入 {#native-integration}

有些时候，我们需要在`Mpx`工程中使用原生小程序组件:

* 通过`npm`引用安装第三包
* 将第三方包源码拷贝到本地`src`目录下

> 注：Mpx并不限制第三方包的格式。开发者可以自己参考小程序官方的[开发第三方自定义组件](https://developers.weixin.qq.com/miniprogram/dev/framework/custom-component/trdparty.html)

### 原理 {#principle}

根据`unsingComponents`中设定的路径，`Mpx`会去查找包入口的js文件。然后提取入口文件所在的**目录**中的`js` `json` `wxss` `wxml`进行编译

编译带来的好处是，常规的拷贝操作，会造成组件内部的依赖缺失，以及冗余代码被打包。而执行了编译，使得`Mpx`可以精确的收集依赖，这表现在：

* `js`文件中的依赖也会被打包，没有被加载的依赖库不会打包，减小体积
* `json`文件的`usingComponents`会被解析，因此原生组件内部可以再引用其他原生组件，甚至是mpx组件
* `wxss`中引用外部样式
* `wxml`中的图片资源会被打包

> 例如:使用第三方组件库时，很多组件可能并未使用，如果按照官方给出的组件库使用方式，会将整个组件库放进项目。\
> 而采用Mpx这种方式则只会引入使用了的组件，所以如果你喜欢vant的按钮，iview的输入框，ColorUI的布局，欢迎尝试mpx。\
> （本段内容具有时效性，未来微信可能会有优化，毕竟一开始微信连npm都不支持）

### 例子 {#example}

**文件目录**

```
node_modules
|-- npm-a-wx-component // npm安装
|   --package.json
|   --src
|     --index.js
|     --index.json
|     --index.wxss
|     --index.wxml
|-- npm-b-wx-component // npm安装
|   --package.json
|   --src
|     --index.js
|     --index.json
|     --index.wxss
|     --index.wxml
component
│-- container.mpx 
│-- com-a.mpx 
|-- src-wx-component // 手动拷贝
|  --index.js
|  --index.json
|  --index.wxss
|  --index.wxml

```

**container.mpx**

```html
<template>
  <view>
    <!-- mpx组件 -->
    <com-a></com-a>
    <!-- npm安装的原生组件 -->
    <npm-a-wx-component></npm-a-wx-component>
    <!-- 手动拷贝到工程的原生组件 -->
    <src-wx-component></src-wx-component>
  </view>
</template>

<script type="application/json">
  "usingComponents": {
    "com-a": "./com-a",
    "npm-a-wx-component": "npm-a-wx-component",
    "src-wx-component": "./src-wx-component"
  }
</script>
```

**node\_modules/npm-a-wx-component/src/index.wxml**

```html
<template>
  <view>
    <view>this is a native component</view>
    <!-- 原生组件内部使用原生组件 -->
    <npm-b-wx-component></npm-b-wx-component>
  </view>
</template>
```

**node\_modules/npm-a-wx-component/src/index.json**

```json
{
  "usingComponents": {
    "npm-b-wx-component": "npm-b-wx-component"
  }
}
```

## 原生page支持 {#native-page-support}

原生自定义组件的支持已经基本能保证第三方 UI 库和 Mpx 的完美结合，但如果是用户存在已经开发好的小程序，在后续的迭代中发现了 Mpx 想使用，就需要用户手工将4个文件变成 Mpx 文件，这不够友好。

Mpx 提供了对原生页面的支持，允许项目中存在原生小程序文件（wxml,js,json,wxss）和 Mpx 文件，两者可以混合使用，通过 webpack 的构建将两者完美混合在一起生成最终的 dist。

使用方式和组件相似。

## 原生导出 {#native-export}

通过导出原生能力，你可以将一个 Mpx 项目融回到原生小程序项目中。有两种做法：

* 一是局部导出部分页面、组件
* 二是完整导出一个 Mpx 项目。

### 导出部分页面/组件 {#export-partial-page-component}

使用 Mpx 开发的页面/组件也可以局部导出为纯粹的普通的原生小程序页面/组件，整合到已有的原生小程序中。

1. 修改 webpack config 中 entry 一项，将 app 改为对应的页面/组件即可。

在路径后追加 ?isPage 来声明独立页面构建，构建产物为该页面的独立原生代码,在路径后追加 ?isComponent 来声明独立组件构建，构建产物为该组件的独立原生代码。

请参考下面的例子，`注意resolve时候最后的query不可以省略，一定要按正确的类型声明这是一个组件or页面。`

例子：

```js
// 
module.exports = merge(baseWebpackConfig, {
  name: 'main-compile',
  // entry point of our application
  entry: {
    // 此处以mpx脚手架生成的项目为例
    
    // before
    // app: resolveSrc('app.mpx')
    
    // after，这里"pages/dindex"代表将原页面导出到output目录下的pages目录，文件名改为dindex.*
    'pages/dindex': resolveSrc('./pages/index.mpx?isPage'), // ?后标识导出类型
    'components/dlist': resolveSrc('./components/list.mpx?isComponent')
  }
})
```

2. 执行 webpack 打包命令
3. 拷贝打包后 dist 里所有文件到原生微信小程序项目根目录即可正常工作。

### 完整导出 {#full-export}

举例：假如我们使用 Mpx 开发了一个完整的项目，这个项目可能包含多个页面，这些页面组合完成一个完整的功能。一般可能是公共需求，比如登录/用户中心等公共模块

如果其它接入方想复用这一公共模块，考虑有以下两种情形

* 接入方也是 Mpx 框架开发的项目，直接迁移
* 接入方是原生开发，这时我们希望能将整个项目完整导出成原生，并让接入方顺利使用。

> 其实观察下 Mpx 项目的打包结构，结构是非常简单的，页面/组件都很规矩地放在对应文件夹里的，所以删掉app.json/app.js/app.wxss/project.config.json几个文件后直接整个拷贝即可。

完整导出整个项目的做法可以是这样：

1. 确认页面路径不要冲突，一般这种公共模块项目，路径上就不要占据`/pages/index/index`，页面路径Mpx是不会修改的，所以定一个`/pages/{模块名}/{页面名}`就好。

2. app.\*的内容都要删掉的，所以全局样式都应该写在独立的文件中（wxss），全局配置有什么特殊的要告知接入方（json），因为App.js会被舍弃，所以入口js要抽出来(js)。

3. 如果有要导出的入口文件，需要给output增加配置：

```js
// webpack.conf
module.exports = {
  entry: {
    app: resolveSrc('app.mpx'),
    index: resolveSrc('index.js') // 导出的入口文件，若没有可不写
  },
  output: {
    libraryTarget: 'commonjs2',
    libraryExport: 'default' // 若export default导出需要写这个,module.exports可省略
  },
  // ... 略
}
```

4. 整个复制进**接入方**的项目里，注册对应的页面，然后就可以正常使用了！

---

---
url: /guide/advance/ability-compatible.md
---
# 原生能力兼容 {#native-ability-compatible}

## custom-tab-bar

Mpx 支持微信小程序原生自定义 tabbar ，关于自定义 tabbar 的详情请查看[这里](https://developers.weixin.qq.com/miniprogram/dev/framework/ability/custom-tabbar.html)

在 Mpx 中使用自定义 tabbar ，需要在 app.mpx 的 json 部分的 tabBar 配置里的 `custom` 为 true 。

```js
// app.mpx
<script type="application/json">
{
  "tabBar": {
    "custom": true,
    "color": "#000000",
    "selectedColor": "#000000",
    "backgroundColor": "#000000",
    "list": [{
      "pagePath": "./page/component/index",
      "text": "组件"
    }, {
      "pagePath": "./page/API/index",
      "text": "接口"
    }]
  },
  "usingComponents": {}
}
</script>
```

在 src 目录下创建 custom-tab-bar 目录，包含 index.mpx 文件，可以在该 index.mpx 文件中编写自定义 tabbar 的模板、js、样式和 json 部分，同时也支持原生写法。

## workers

Mpx 完全支持小程序原生的 worker ，需要在 app.mpx 文件中的 json 部分声明 worker 的目录，Mpx 会将其对应目录进行打包，输出到目标代码目录中。

```js
<script type="application/json">
{
  // 指定 worker 的目录
  "workers": "workers"
}
</script>
```

更多详情可查看[这里](https://developers.weixin.qq.com/miniprogram/dev/framework/workers.html)

## 云开发 {#cloud-development}

Mpx 支持微信小程序提供的原生云开发能力。如果需要在项目中使用云开发的能力，可以通过 Mpx 脚手架工具在初始化项目时选择支持云开发。如果需要支持云开发能力，在项目初始化时需要选择是微信平台下，且不能支持跨平台开发。如下图所示：

![云开发](https://gift-static.hongyibo.com.cn/static/kfpub/3547/cloud_v2.png)

更多关于云开发相关可查看[这里](https://developers.weixin.qq.com/miniprogram/dev/wxcloud/basis/getting-started.html)

## useExtendedLib

Mpx 对于引入扩展库做了相关处理，可以在 app.mpx 中配置使用的扩展库，目前支持 weui 。

```html
<script type="application/json">
  {
    "useExtendedLib": {
      "weui": true
    }
  }
</script>
```

还需要在 Mpx 的配置文件配置 `externals` 属性，来指定外部依赖，这样 Mpx 在进行打包时，会将其当做外部依赖进行打包。

```js
module.exports = {
  // ...
  externals: [ 'weui' ]
}
```

---

---
url: /guide/advance/plugin.md
---
# 小程序插件 {#miniprogram-plugin}

插件，是可被添加到小程序内直接使用的功能组件，是对一组 js 接口、自定义组件或页面的封装，。开发者可以像开发小程序一样开发一个插件，供其他小程序使用。同时，小程序开发者可直接在小程序内使用插件，无需重复开发，但是在使用第三那个插件时，无法看到插件的代码。插件适合用来封装自己的功能或服务，提供给第三方小程序进行展示和使用。

开发小程序插件，大致要经过 开通插件功能，填写开发信息，提交审,发布，管理插件使用申请。同时在原生小程序使用插件，要先发出插件申请，等待使用申请通过，插件所有者还可以进行拒绝。
原生小程序开发插件请移步：

* [微信小程序插件开发](https://developers.weixin.qq.com/miniprogram/dev/framework/plugin/development.html)
* [支付宝小程序插件开发](https://opendocs.alipay.com/mini/plugin/create-plugin)

新建插件类型的项目后，如果创建示例项目，则项目中将包含三个目录：

* plugin 目录：插件代码目录。
* miniprogram 目录：放置一个小程序，用于调试插件。
* doc 目录：用于放置插件开发文档。

，插件会同时有多个线上版本，由使用插件的小程序决定具体使用的版本号。

### 如何编写一个插件 {#how-to-write-plugin}

推荐使用 mpx 官方脚手架 @mpxjs/cli 创建一个小程序插件项目来快速的进入插件开发阶段，首先全局安装 @mpxjs/cli

```sh
npm i -g @mpxjs/cli
```

然后使用 cli 初始化项目

```sh
mpx create <project-name>
? 请选择小程序项目所属平台（目前仅微信下支持跨平台输出） wx
? 是否需要跨小程序平台 No
? 是否需要使用小程序云开发能力 No
? 是否是个插件项目?（不清楚请选 No ！什么是插件项目请看微信官方文档！） Yes
? 是否需要typescript No
? 项目描述 A mpx project
? 请输入小程序的Appid touristappid
```

**文件目录**

```
  src
  |-- miniprogram // 目录：放置一个小程序，用于调试插件。
  |   --pages
  |   --app.mpx // 引入插件调试
  |-- plugin // 目录：插件代码目录
  |   --components // 插件组件
  |     -- list.mpx // 插件提供的列表组件
  |   --plugin.json // 插件配置文件
```

我们在 plugin/components/list.mpx 中开发插件中的列表组件，开发完成后，在plugin.json中我们向使用者小程序开放的所有自定义组件、页面和 js 接口，格式如下：

**代码示例：**

```html
{
  "publicComponents": {
    "list": "./components/list" // 使用mpx 中的webpack 路径引入规范
  },
  "pages": {
    "hello-page": "./pages/hello-page"
  }
}
```

运行 **npm run build/serve** 构建小程序产物，在 dist 文件夹下，生成最终的小程序插件产物，使用微信开发者工具，打开代码片段菜单栏，选择插件模式，打开 dist 文件夹。

我们可以像小程序一样预览和上传，但插件没有体验版，同时我们通常将 miniprogram 下的代码当做使用插件的小程序代码，来进行插件的调试和测试。

在开发完插件之后，我们可以上传插件代码，在小程序管理后台进行提交发布审核，审核通过后，就可以提供给第三方小程序使用我们的插件了。

使用 mpx 开发插件的优势相似于使用 mpx 开发小程序项目，可以使用 mpx 的各种增强特性以及跨平台输出的特性，提高开发效率和插件性能。

---

---
url: /guide/advance/custom-output-path.md
---
# 自定义路径 {#custom-path}

Mpx在构建时，如果引用的页面不存在于当前 app.mpx 所在的上下文中，例如存在于 npm 包中，为避免和本地声明的其他 page 路径冲突，Mpx 会对页面路径进行 hash 化处理，
同时处理组件路径时也会添加 hash 防止路径名冲突，hash 化处理后最终的文件名是 name+hash+ext 的格式

与此同时，部分开发者希望能够对最终输出的页面路径和组件路径能够自定义，Mpx 对此也提供了相应的配置和Api来支持用户自定义路径

> **注意**：该能力仅在输出小程序时生效

## 页面路径映射 {#page-path-mapping}

针对 Mpx 对 json 中非当前上下文的页面路径 hash 化的特性，如果为提升可读性需要避免路径 hash 化，可以使用该特性，具体为在
json 中配置 pages 时，数组中支持放入 Object，对象中传入两个字段，src 字段表示页面地址，path 字段表示自定义页面路径

* **示例**:

object风格的页面声明

```json5
{
  // 主包中的声明
  "pages": [
    {
      "src": "@someGroup/someNpmPackage/pages/view/index.mpx",
      "path": "pages/somNpmPackage/index" // 注意保持 path 的唯一性
    }
  ],
  // 分包中的声明
  "subPackages": [
    {
      "root": "test",
      "pages": [
         {
           "src": "@someGroup/someNpmPackage/pages/view/test.mpx",
           "path": "pages/somNpmPackage/test" // 注意保持 path 的唯一性
         }
      ]
    }
  ]
}
```

使用声明中配置的页面路径进行跳转

```js
mpx.navigateTo({
  url: '/pages/somNpmPackage/index'
})

mpx.navigateTo({
  url: '/test/pages/somNpmPackage/test'
})
```

## 自定义产物路径 {#custom-output-path}

Mpx 框架 webpack-plugin 也提供了 customOutputPath 方法可以让用户进行页面和组件路径的自定义，
可使用该方法对**非原生组件和非当前文件context的页面**输出路径进行自定义

需要注意的是，该方法需要具有**稳定性和唯一性**，即同样的输入不管什么时候执行都要有同样的返回以及不同的的输入一定会得到不同的输出。

* **示例**：

```js
// vue.config.js
module.exports = defineConfig({
  pluginOptions: {
    mpx: {
      plugin: {
         customOutputPath: (type, name, hash, ext, resourcePath) => {
          // type: 资源类型(page | component | static)
          // name: 资源原有文件名
          // hash: 8位长度的hash串
          // ext: 文件后缀(.js｜ .wxml | .json 等)
          // resourcePath: 资源路径

          // 输出示例： pages/testax34dde3/index.js
          return path.join(type + 's', name + hash, 'index' + ext)
        }
      }
    }
  }
})
```

基于上方示例，你可以根据需要进行路径定制化，例如缩短hash、使用012代替文件名等各种自定义路径

---

---
url: /guide/advance/utility-first-css.md
---
# 使用原子类 {#use-utility-class}

原子类(utility-first CSS)是近几年流行起来的一种全新的样式开发方式，在前端社区内取得了良好的口碑，越来越多的主流网站也基于原子类进行开发，我们耳熟能详的有[Github](https://github.com/)，[OpenAI](https://openai.com/)，[Netflix](https://top10.netflix.com/)
和[NASA官网](https://www.jpl.nasa.gov/)
等。使用原子类离不开原子类框架的支持，常用的原子类框架有 [Tailwindcss](https://tailwindcss.com/)、[Windicss](https://windicss.org/)
和 [Unocss](https://unocss.dev/) 等，而在 **Mpx2.9** 以后，我们在框架中内置了基于 unocss
的原子类支持，让小程序开发也能使用原子类。对项目进行简单配置开启原子类支持后，用户就可以在 Mpx
页面/组件模板中直接使用一些预定义的基础样式类，诸如flex，pt-4，text-center 和 rotate-90 等，对样式进行组合定义，并且在 Mpx 支持的所有小程序平台和 web 平台中正常运行，下面是一个简单示例：

```html

<view class="container">
  <view class="flex">
    <view class="py-8 px-8 inline-flex mx-auto bg-white rounded-xl shadow-md">
      <view class="text-center">
        <view class="text-base text-black font-semibold mb-2">
          Erin Lindford
        </view>
        <view class="text-gray-500 font-medium pb-3">
          Product Engineer
        </view>
        <view
          class="mt-2 px-4 py-1 text-sm text-purple-600 font-semibold rounded-full border border-solid border-purple-200">
          Message
        </view>
      </view>
    </view>
  </view>
</view>
```

通过这种方式，我们在不编写任何自定义样式代码的情况下得到了一张简单的个人卡片，实际渲染效果如下：

![utility-css-demo](https://dpubstatic.udache.com/static/dpubimg/Or3aaN-mmxV8pK-LmEVPm_demo.png)

相较于传统的自定义类编写样式的方式，使用原子类能给你带来以下这些好处：

* **不用再烦恼于为自定义类取类名**，传统样式开发中，我们仅仅是为某个元素定义样式就需要绞尽脑汁发明一些抽象的类名，还得提防类名冲突，使用原子类可以完全将你从这种琐碎无趣的工作中解放；
* **停止css体积的无序增长**，传统样式开发中，css体积会随着你的迭代不断增长，而在原子类中，一切样式都可以复用，你几乎不需要编写新的css；
* **让调整样式变得更加安全**，传统css是全局的，当你修改某个样式时无法保障其不会破坏其他地方的样式，而你在模板中使用的原子类是本地的，你完全不用担心修改它会影响其他地方。

而相较于使用内联样式，原子类也有一些重要的优势：

* **约束下的设计**，使用内联样式时，里面的每一个数值都是魔法数字(magic number)
  ，而通过原子工具类，你可以选择一些符合预定义设计规范的样式，便于构筑具有视觉一致性的UI；
* **响应式设计**，你无法在内联样式中使用媒体查询，然而通过原子类框架中提供的响应式工具，你可以轻而易举地构建出响应式界面；
* **Hover、focus和其他状态**，使用内联样式无法定义特定状态下的样式，如hover和focus，通过原子类框架的状态变量能力，我们可以轻松为这些状态定义样式。

看到这里相信你已经迫不及待地想要在 Mpx 中体验原子类开发了吧，可以根据下面的指南开启你的原子类之旅。

## 原子类环境配置 {#compile-config}

如果你想在新项目中使用原子类，可以使用最新版本的 `@mpxjs/cli` 创建项目，在 prompt 中选择使用原子类，就可以在新创建的项目模版中直接使用 unocss 的原子类，关于可使用的工具类可参考 [unocss 交互示例](https://unocss.dev/interactive/)及本指南下方的[工具类支持范围](#工具类支持范围)。

> 与 web 中使用 unocss 不同，在 Mpx 中使用 unocss 不需要显式引入虚拟模块 `import 'uno.css'` 来承载生成的样式内容，这是由于在
> Mpx 中，我们充分考虑到小程序分包架构的特殊性和主包体积的重要性，结合 Mpx
> 强大的分包构建能力，对生成的原子工具类的使用情况进行分析，将其自动注入到合适的主包或者分包中，来达到全局体积分配的最优（在没有内容冗余的情况下尽可能输出到分包）。

对于使用 `@mpxjs/cli@3.0` 新版脚手架创建的项目，可以在项目初始化时选择`需要使用原子类`
选项，或在已有项目下执行`mpx add @mpxjs/vue-cli-plugin-mpx-utility-first-css`以激活原子类相关编译配置。

对于使用旧版脚手架创建的项目，可以通过修改项目编译配置以激活原子类支持：

1. 安装相关依赖：

```json5
{
  //...
  "devDependencies": {
    "@mpxjs/unocss-base": '^2.9.0',
    "@mpxjs/unocss-plugin": '^2.9.0'
  }
}
```

2. 新建uno.config.js，基础配置内容如下：

```js
const { defineConfig } = require('unocss')
const presetMpx = require('@mpxjs/unocss-base')

module.exports = defineConfig({
  presets: [
    presetMpx()
  ]
})
```

3. 注册`MpxUnocssPlugin`，在`build/getPlugins`中添加如下代码：

```js
const MpxUnocssPlugin = require('@mpxjs/unocss-plugin')
// ...
plugins.push(new MpxUnocssPlugin())
```

即可在项目模版中使用基于`unocss`的原子类功能，`unocss`默认的preset兼容`tailwindcss`/`windicss`
，可以通过查阅[tailwindcss文档](https://tailwindcss.com/docs/installation)、[windicss文档](https://windicss.org/utilities/general/colors.html)或[unocss可交互文档](https://unocss.dev/interactive/)进行探索使用。

关于`uno.config.js`可用配置项及`@mpxjs/unocss-plugin`及`@mpxjs/unocss-base`的配置项请参考[API文档](../../api/compile.md#mpxunocssplugin-配置)。

### vscode插件支持 {#vscode-plugin-support}

1. 安装 [unocss 官方插件](https://unocss.dev/integrations/vscode)。
2. 修改 VSCode 设置中的 `unocss.languageIds` 选项（或者直接修改 VSCode JSON 配置文件），添加 "mpx"，实现智能提示等功能。

> *使用最新版本 [@mpxjs/cli](../basic/start.md#install-scaffold) 脚手架创建的项目会自动生成，可忽略这一步。*

```json
// .vscode/settings.json
{
  "unocss.languageIds": [
    "mpx"
  ]
}
```

3. 修改 `uno.config.js` 支持 Mpx 预设。

> *使用 [@mpxjs/cli](../basic/start.md#install-scaffold) 脚手架创建的项目会自动生成，可忽略这一步。*

```js
// uno.config.js
const { defineConfig } = require('unocss')
const presetMpx = require('@mpxjs/unocss-base')

const { defineConfig } = require("unocss")
const presetMpx = require("@mpxjs/unocss-base")

module.exports = defineConfig({
  content: {
    pipeline: {
      include: [/\.mpx($|\?)/],
    },
  },
  presets: [presetMpx()],
})
```

## 功能支持范围 {#config-supports}

我们支持了`unocss`大部分的配置项及功能，并针对小程序技术规范提供了一些额外的功能支持，如分包输出和样式隔离等功能，以下为详细功能支持范围。

| 功能                | 支持度  | 备注                                                        |
|:------------------|:-----|:----------------------------------------------------------|
| Load Config       | 支持   | 支持windi默认的全部配置文件路径，并支持在plugin options中手动传入配置对象或配置文件路径     |
| Rules             | 支持   |                                                           |
| Shortcuts         | 支持   |                                                           |
| Theme             | 支持   |                                                           |
| Variants          | 支持   |                                                           |
| Extractors        | 不支持  |                                                           |
| Transformers      | 部分支持 | 内建支持variant groups、directives和alias，不支持自定义transformers    |
| Preflights        | 支持   | 支持内建和自定义preflight配置                                       |
| Presets           | 支持   |                                                           |
| Safelist          | 支持   | 支持全局配置和模版注释语法局部配置声明safelist                               |
| Value Auto-infer  | 支持   |                                                           |
| Variant Groups    | 支持   |                                                           |
| Directives        | 支持   |                                                           |
| Alias             | 支持   |                                                           |
| Attributify Mode  | 不支持  | 小程序模版不支持不识别的自定义属性                                         |
| Responsive Design | 支持   |                                                           |
| Dark Mode         | 支持   |                                                           |
| Important Prefix  | 支持   |                                                           |
| Layers Ordering   | 支持   |                                                           |
| 分包输出/公共样式抽离       | 支持   | 可通过设置`@mpxjs/unocss-plugin`配置项`minCount`决定公共样式范围          |
| 组件分包异步/组件样式隔离     | 支持   | 可通过全局配置和模版注释语法局部配置`styleIsolation='isolated'`支持相关场景的原子类使用 |
| Rpx样式单位           | 支持   |                                                           |
| 小程序类名特殊字符转义       | 支持   | 静态类名和动态类名均以支持                                             |
| 跨平台输出             | 支持   | 支持输出Mpx已支持的所有小程序平台及Web                                    |

## 工具类可用范围 {#utility-supports}

经过我们的详细测试，大部分`unocss`
提供的工具类都能在小程序环境下正常工作，但是也有部分工具类由于小程序底层环境差异无法正常运行，以下是详细的测试结果，参考[windicss文档](https://windicss.org/utilities/general/colors.html)
进行分类组织。

### General

| 功能         | 支持度  | 备注                                  |
|:-----------|:-----|:------------------------------------|
| Colors     | 支持   |                                     |
| Typography | 部分支持 | 不支持子项：Font Variant Numeric Tab Size |
| SVG        | 不支持  | 小程序不支持svg标签                         |
| Variants   | 部分支持 | 不支持子项：Child Selectors，因为小程序不支持\*选择器  |

### Accessibility

| 功能             | 支持度 | 备注 |
|:---------------|:----|:---|
| Screen Readers | 支持  |    |

### Animations

| 功能          | 支持度 | 备注 |
|:------------|:----|:---|
| Animation   | 支持  |    |
| Transforms  | 支持  |    |
| Transitions | 支持  |    |

### Backgrounds

| 功能                    | 支持度 | 备注                      |
|:----------------------|:----|:------------------------|
| Background Attachment | 支持  |                         |
| Background Clip       | 支持  |                         |
| Background Color      | 支持  |                         |
| Background Opacity    | 支持  | 需要和Background Color一起使用 |
| Background Position   | 支持  |                         |
| Background Repeat     | 支持  |                         |
| Background Size       | 支持  |                         |
| Background Origin     | 支持  |                         |
| Gradient Direction    | 支持  |                         |
| Gradient From         | 支持  |                         |
| Gradient Via          | 支持  |                         |
| Gradient To           | 支持  |                         |
| Background Blend Mode | 支持  |                         |

### Behaviors

| 功能                   | 支持度  | 备注                                                   |
|:---------------------|:-----|:-----------------------------------------------------|
| Box Decoration Break | 支持   |                                                      |
| Image Rendering      | 部分支持 | image-render-edge 真机不支持                              |
| Listings             | 支持   |                                                      |
| Overflow             | 支持   |                                                      |
| Overscroll Behavior  | 支持   |                                                      |
| Placeholder          | 不支持  | 微信小程序 input 需要通过 placeholder-style 设置 placeholder 样式 |

### Borders

| 功能                | 支持度 | 备注              |
|:------------------|:----|:----------------|
| Border Radius     | 支持  |                 |
| Border Width      | 支持  |                 |
| Border Color      | 支持  |                 |
| Border Opacity    | 支持  |                 |
| Border Style      | 支持  |                 |
| Divider Width     | 不支持 | 小程序不支持生成的css选择器 |
| Divider Color     | 不支持 | 小程序不支持生成的css选择器 |
| Divider Opacity   | 不支持 | 小程序不支持生成的css选择器 |
| Divider Style     | 不支持 | 小程序不支持生成的css选择器 |
| Outline           | 支持  |                 |
| Outline Solid     | 支持  |                 |
| Outline Dotted    | 支持  |                 |
| Ring Width        | 支持  |                 |
| Ring Color        | 支持  |                 |
| Ring Opacity      | 支持  |                 |
| Ring Offset Width | 支持  |                 |
| Ring Offset Color | 支持  |                 |

### Effects

| 功能             | 支持度 | 备注 |
|:---------------|:----|:---|
| Box Shadow     | 支持  |    |
| Opacity        | 支持  |    |
| Mix Blend Mode | 支持  |    |

### Filters

| 功能              | 支持度 | 备注 |
|:----------------|:----|:---|
| Filter          | 支持  |    |
| Backdrop Filter | 支持  |    |

### Interactivity

| 功能              | 支持度 | 备注          |
|:----------------|:----|:------------|
| Accent Color    | 不支持 | 小程序不支持生成的样式 |
| Appearance      | 不支持 | 小程序不支持生成的样式 |\
| Cursor          | 不支持 | 小程序不支持生成的样式 |\
| Caret           | 不支持 | 小程序不支持生成的样式 |\
| Pointer Events  | 支持  |             |\
| Resize          | 不支持 | 小程序不支持生成的样式 |\
| Scroll Behavior | 不支持 | 小程序不支持生成的样式 |\
| Touch Action    | 支持  |             |\
| User Select     | 不支持 | 小程序不支持生成的样式 |\
| Will Change     | 不支持 | 小程序不支持生成的样式 |

### Layout

| 功能          | 支持度  | 备注                             |
|:------------|:-----|:-------------------------------|
| Columns     | 支持   |                                |
| Container   | 支持   |                                |
| Display     | 支持   |                                |
| Flex        | 支持   |                                |
| Grid        | 支持   |                                |
| Positioning | 部分支持 | 小程序图片设置object-fit 无效，可使用mode代替 |
| Sizing      | 支持   |                                |
| Spacing     | 部分支持 | Space Between小程序不支持生成的css选择器   |
| Tables      | 部分支持 | 小程序不支持部分table样式                |

## 小程序原子类使用注意点 {#attentions}

小程序由于底层环境差异，我们在支持和使用原子类时有一些特殊的注意点。

### 特殊字符转义 {#escape}

基于`unocss`的原子类支持`value auto-infer`（值自动推导），可以在模版中根据相关规则书写灵活的自定义值原子类，如`p-5px bg-[hsl(211.7,81.9%,69.6%)]`等，针对原子类中出现的`[` `(` `,`等特殊字符，在web中会通过转义字符`\`进行转义，由于小程序环境下不支持css选择器中出现`\`转义字符，我们内置支持了一套不带`\`的转义规则对这些特殊字符进行转义，同时替换模版和css文件中的类名，内建的默认转义规则如下：

```js
const escapeMap = {
    '(': '_pl_',
    ')': '_pr_',
    '[': '_bl_',
    ']': '_br_',
    '{': '_cl_',
    '}': '_cr_',
    '#': '_h_',
    '!': '_i_',
    '/': '_s_',
    '.': '_d_',
    ':': '_c_',
    ',': '_2c_',
    '%': '_p_',
    '\'': '_q_',
    '"': '_dq_',
    '+': '_a_',
    $: '_si_',
    // unknown用于兜底不在上述范围中未知的转义字符
    unknown: '_u_'
  }
```

与此同时，用户也可以通过传递`@mpxjs/unocss-plugin`的[`escapeMap`配置项](../../api/compile.md#escapemap)来覆盖内建的转义规则。

### 原子类分包输出 {#subpackage}

在web中，原子类会被全部打包输出单个样式文件，一般会放置在顶层样式表中以供全局访问，但在小程序中这种全量的输出策略并不是最优的，主要原因在于小程序中可供全局访问的主包体积存在**2M大小限制**，主包体积十分紧缺珍贵，Mpx在构建输出时遵循着分包优先的原则，尽可能充分利用分包体积从而减少对主包体积的占用，再进行原子类产物输出时，我们也遵循了相同的原则。

在Mpx中，我们在收集原子类时同时记录了每个原子类的引用分包，在收集结束后根据每个原子类的分包引用数量决定该原子类应该输出到主包还是分包当中，我们在`@mpxjs/unocss-plugin`中提供了[`minCount`配置项](../../api/compile.md#mincount)来决定分包的输出规则，该配置项的默认值为2，即当一个原子类被2个或以上分包引用时，会被作为公共原子类抽取到主包中，否则输出到所属分包中，这也是全局最优的策略。当我们想要让原子类输出产物更少地占用主包体积时，我们也可以将`minCount`值调大，让原子类抽取到主包的条件更加苛刻，不过这样也会伴随着原子类分包冗余的增加。

`unocss.config.js`配置中定义的`safelist`原子类默认会输出到主包，为了组件局部使用的`safelist`有输出到分包的机会，我们在模版中提供了[`注释配置`](../../api/compile.md#commentconfig)（comments config），灵感来源于`webpack`中的魔法注释（magic comments），用户可以在组件模版中通过`注释配置`声明当前组件所需的`safelist`，对应的原子类也会根据上述的规则输出到主包或分包中，使用示例如下：

```html
<template>
    <!-- mpx_config_safelist: 'text-red-500 bg-blue-500' -->
    <!-- 动态样式中可以使用text-red-500和bg-blue-500原子类 -->
    <view wx:class="{{classObj}}">test</view>
    <!-- ... -->
</template>
```

### 样式隔离与组件分包异步 {#style-isolation}

在小程序中，自定义组件的样式默认是隔离的，web中通过全局样式访问原子类的方式不再生效，不过由于小程序提供了[样式隔离配置](https://developers.weixin.qq.com/miniprogram/dev/framework/custom-component/wxml-wxss.html#%E7%BB%84%E4%BB%B6%E6%A0%B7%E5%BC%8F%E9%9A%94%E7%A6%BB)，我们可以将该组件样式隔离配置调整为`apply-shared`来获取页面或app中定义的原子类，但是当我们在使用传统类名和原子类混合开发或者迁移原子类的过程中，我们往往希望保留原本自定义组件的样式隔离。

针对这种情况，我们在`@mpxjs/unocss-plugin`中提供了[`styleIsolation`配置项](../../api/compile.md#styleisolation)，可选设置为`isolated`|`apply-shared`，当设置为`isolated`时每个组件都会通过`@import`独立引用主包或者分包的原子类样式文件，因此不会受到样式隔离的影响；当设置为`apply-shared`时，只有app和分包页面会引用对应的原子类样式文件，自定义组件需要通过配置样式隔离为`apply-shared`使原子类生效。

在组件分包异步的情况下对应组件即使将样式隔离配置为`apply-shared`的情况下，`@mpxjs/unocss-plugin`也需要将`styleIsolation`设置为`isolated`才能正常工作，原因在于组件分包异步的情况下，组件被其他分包的页面所引用渲染，由于上述原子类样式分包输出的规则，其他分包的页面中可能并不包含当前组件所需的原子类，只有在`isolated`模式下由组件自身引用所需的原子类样式才能保证正常work，类似于`safelist`，我们也提供了[`注释配置`](../../api/compile.md#commentconfig)的方式对组件的`styleIsolation`模式进行局部配置，示例如下：

```html
<template>
    <!-- mpx_config_styleIsolation: 'isolated' -->
    <!-- 当前组件会直接引用对应主包或分包的原子类样式 -->
     <view class="@dark:(text-white bg-dark-500)">
    <!-- ... -->
</template>
```

---

---
url: /guide/advance/ssr.md
---
# SSR

近些年来，SSR/SSG 由于其良好的首屏展现速度和SEO友好性逐渐成为主流的技术规范，但过去 Mpx 对 SSR 的支持不完善，使用 Mpx 开发的跨端页面一直无法享受到 SSR 带来的性能提升，在 2.9 版本中，我们对 Mpx 输出 web 流程进行了大量适配改造，解决了 SSR 中常见的内存泄漏、跨请求状态污染和数据预请求等问题，完整支持了基于 Vue 和 Pinia 的 SSR 技术方案。

## 配置使用 SSR {#ssr-config}

在 Vue SSR 项目中，我们一般需要提供 server entry 和 client entry 两个文件作为 webpack 的构建入口，然后通过 webpack 构建出 server bundle 和 client bundle。在用户访问页面时，在服务端使用 server bundle 渲染出 HTML 字符串，作为静态页面发送到客户端，然后在客户端使用 client bundle 通过水合（hydration）对静态页面进行激活，实现可交互效果，下图展示了 Vue SSR 的大致流程。

![Vue SSR流程](https://img-hxy021.didistatic.com/static/webappstatic/do1_kWBH7L8mTgpHeKsBKp85)

Mpx SSR 核心基于 Vue SSR 实现，大致流程思路与 Vue 一致，不过为了保持与小程序代码的兼容性，在配置使用上有一些改动差异，下面我们详细展开介绍：

### 构建server/client bundle {#build-server-client-bundle}

SSR项目中，我们需要分别构建出 server bundle 和 client bundle，对于不同环境的产物构建，我们需要进行不同的配置。
在 Vue 中，我们需要提供 `entry-server.js` 和 `entry-client.js` 两个文件分别作为 server 和 client 的构建入口，与 Vue 不同，在 Mpx 中我们通过编译处理与运行时增强生命周期实现了使用 `app.mpx` 作为统一构建入口，无需区分 server 和 client。

#### 服务端构建配置 {#server-build-config}

服务端配置中除了将 entry 制定为 `app.mpx` 及其它基础配置外，最重要的是安装 `vue-server-renderer` 包中提供的  `server-plugin` 插件，该插件能够构建产出 `vue-ssr-server-bundle.json` 文件供 `renderer` 后续消费。

```js
// webpack.server.config.js
const VueSSRServerPlugin = require('vue-server-renderer/server-plugin')

module.exports = merge(baseConfig, {
  // 将 entry 指向项目的 app.mpx 文件
  entry: './app.mpx',
  // ...
  plugins: [
   // 产出 `vue-ssr-server-bundle.json`
    new VueSSRServerPlugin()
  ]
})
```

更加详细的配置说明可参考 [Vue SSR的服务端配置](https://v2.ssr.vuejs.org/guide/build-config.html#server-config)

#### 客户端构建配置 {#client-build-config}

类似服务端构建配置，在客户端构建中我们需要使用 `vue-server-renderer` 包中 `client-plugin` 插件来帮助我们生成客户端环境的资源清单 `vue-ssr-client-manifest.json`，并供 `renderer` 后续消费。

```js
// webpack.client.config.js
const VueSSRClientPlugin = require('vue-server-renderer/client-plugin')

module.exports = merge(baseConfig, {
  // 将 entry 指向项目的 app.mpx 文件
  entry: './app.mpx',
  // ...
  plugins: [
    // 产出 `vue-ssr-client-manifest.json`。
    new VueSSRClientPlugin()
  ]
})
```

更加详细的配置说明可参考 [Vue SSR的客户端配置](https://v2.ssr.vuejs.org/guide/build-config.html#client-config)

### 准备页面模版 {#prepare-page-template}

SSR 渲染中，我们创建 `renderer` 需要一个页面模板，简单的示例如下：

```html
<!DOCTYPE html>
<html lang="en">
  <head><title>Hello</title></head>
  <body>
    <!--vue-ssr-outlet-->
  </body>
</html>
```

与 CSR 渲染模版不同，SSR 渲染模版中需要提供一个特殊的 `<!--vue-ssr-outlet-->`注释，标记 SSR 渲染产物的插入位置，如使用 `@mpxjs/cli` 脚手架创建 SSR 项目，该模版已经内置于脚手架中。

### 集成启动 SSR 服务 {#integrate-ssr-server}

当我们准备好页面模版和双端构建产物后，我们就可以创建 `renderer` 并与 Node 服务进行集成，启动 SSR 服务，下面以 `express` 为例：

```js
//server.js
const app = require('express')()
const { createBundleRenderer } = require('vue-server-renderer')
// 通过 vue-server-renderer/server-plugin 生成的文件
const serverBundle = require('../dist/server/vue-ssr-server-bundle.json')
// 通过 vue-server-renderer/client-plugin 生成的文件
const clientManifest = require('../dist/client/vue-ssr-client-manifest.json')
 // 页面模版文件
const template = require('fs').readFileSync('../src/index.template.html', 'utf-8')
// 创建 renderer 渲染器
const renderer = createBundleRenderer(serverBundle, {
    runInNewContext: false,
    template,
    clientManifest,
});
// 注册启动 SSR 服务
app.get('*', (req, res) => {
  const context = { url: req.url }
  renderer.renderToString(context, (err, html) => {
  	if (err) {
  	  res.status(500).end('Internal Server Error')
      return
    }
  	res.end(html);
  })
})
app.listen(8080)
```

## SSR 生命周期 {#ssr-lifecycle}

在 Mpx 2.9 的版本中，我们提供了三个全新用于 SSR 的生命周期，分别是`onAppInit`、`serverPrefetch` 和 `onSSRAppCreated`，以统一服务端与客户端的构建入口，下面展开介绍：

### onAppInit

> 该生命周期仅可在 App 中使用

在 SSR 中用户每发出一个请求，我们都会为其生成一个新的应用实例，`onAppInit` 生命周期会在应用创建 `new Vue(...)` 前被调用，其执行的返回结果会被合并到创建应用的 `options` 中

很常见的使用场景在于返回新的全局状态管理实例，Mpx 中提供了 `@mpxjs/pinia` 作为全局状态管理工具，我们可以在 `onAppInit` 中返回全新的 `pinia` 示例避免产生跨请求状态污染，示例如下：

```js
// app.mpx
import mpx, { createApp } from '@mpxjs/core'
import { createPinia } from '@mpxjs/pinia'

createApp({
  // ...
  onAppInit () {
    const pinia = createPinia()
    return {
      pinia
    }
  }
})
```

> SSR 中仅支持使用 `@mpxjs/pinia` 作为状态管理工具，`@mpxjs/store` 暂不支持

### serverPrefetch

> 该生命周期可在 App/Page/Component 中使用，只在服务端渲染时执行

当我们需要在 SSR 使用数据预拉取时，可以使用这个生命周期进行，使用方法与 Vue 一致, 示例如下：

选项式 API：

```js
import { createPage } from '@mpxjs/core'
import useStore from '../store/index'

createPage({
  //...
  serverPrefetch () {
    const query = this.$route.query
    const store = useStore(this.$pinia)
    // return the promise from the action, fetch data and update state
    return store.fetchData(query)
  }
})
```

组合式 API：

```js
import { onServerPrefetch, getCurrentInstance, createPage } from '@mpxjs/core'
import useStore from '../store/index'

createPage({
  setup () {
    const store = userStore()
    onServerPrefetch(() => {
      const query = getCurrentInstance().proxy.$route.query
      // return the promise from the action, fetch data and update state
      return store.fetchData(query)
    })
  }
})
```

关于数据预拉取更详细的说明可以查看[这里](https://v2.ssr.vuejs.org/guide/data.html)。

### onSSRAppCreated

> 该生命周期仅可在 App 中使用，只在服务端渲染时执行

在 Vue SSR 项目中，我们会在 `entry-server.js` 中导出一个工厂函数，在该函数中实现创建应用实例、路由匹配和状态同步等逻辑，并返回应用实例 `app`。

在 Mpx SSR 中，我们将这部分逻辑整合在 `onSSRAppCreated` 中执行，该生命周期执行时用户可以从参数中获取应用实例 `app`、路由实例 `router`、数据管理实例 `pinia` 和 SSR 上下文 `context`，在完成必要的操作后，该生命周期需要返回一个 `resolve(app)` 的 promise。

通常我们会在 `onSSRAppCreated` 中进行路由路径设置和数据预拉取后的状态同步工作，示例如下：

```js
// app.mpx
createApp({
    // ...,
    onSSRAppCreated ({ pinia, router, app, context }) {
      return new Promise((resolve, reject) => {
        // 设置服务端路由路径
        router.push(context.url)
        router.onReady(() => {
          // 应用完成渲染时执行
          context.rendered = () => {
            // 将服务端渲染后得到的 pinia.state 同步到 context.state 中，
            // context.state 会被自动序列化并通过 `window.__INITIAL_STATE__`
            // 注入到 HTML 中，并在客户端运行时再读取同步
            context.state = pinia.state.value
          }
          // 返回应用程序实例
          resolve(app)
        }, reject)
      })
    }
})
```

上述示例代码等价于 Vue 中的 `entry-server.js`

```js
// entry-server.js
import { createApp } from './app'

export default context => {
  return new Promise((resolve, reject) => {
    const { app, router, store } = createApp()
    router.push(context.url)
    router.onReady(() => {
      // This `rendered` hook is called when the app has finished rendering
      context.rendered = () => {
        // After the app is rendered, our store is now
        // filled with the state from our components.
        // When we attach the state to the context, and the `template` option
        // is used for the renderer, the state will automatically be
        // serialized and injected into the HTML as `window.__INITIAL_STATE__`.
        context.state = store.state
      }
      resolve(app)
    }, reject)
  })
}
```

如用户没有配置 onSSRAppCreated，框架内部会执行兜底逻辑，以保障 SSR 的正常运行。

## 其他注意事项 {#other-notes}

1. Mpx SSR 渲染支持 i18n 的功能，但为了防止内存泄漏，当前 i18n 实例不会随着每次请求而重新创建，这是由于 Vue2.x 版本插件机制的设计缺陷所造成的，因此在使用 i18n 进行 SSR 时可能会产生跨请求状态污染的问题，这个问题会在未来 Mpx 输出 web 切换为 Vue3 后完全解决。

2. 在服务端渲染阶段，对于 global 全局对象访问修改，如\_\_mpx, \_\_mpxRouter, \_\_mpxPinia 都可能导致全局状态污染，所以在服务端渲染阶段请尽量避免进行相关操作；对于存在全局访问修改的方法，如 getApp(), getCurrentPages() 等在服务端渲染中被调用时，会产生相关报错提示。

3. 由于服务器无法收到 URL 中的 hash 信息，使用 SSR 时需要通过修改 `mpx.config.webRouteConfig` 将路由模式设置成 `history` 模式。

---

---
url: /guide/advance/cli.md
---
# 脚手架工具 {#cli}

Mpx 提供了一个基于 [@vue/cli](https://cli.vuejs.org/zh/) 的脚手架工具 `@mpxjs/cli`，用于快速初始化和管理 Mpx 项目。它继承了 Vue CLI 的强大功能，如零配置原型开发、插件系统、图形化界面等，并针对小程序开发进行了深度定制。

## 安装 {#install}

请确保你的环境中有 Node.js (>= 10)。

```bash
# 全局安装 @mpxjs/cli
npm install -g @mpxjs/cli
```

## 初始化项目 {#create}

使用 `create` 命令创建一个新项目：

```bash
mpx create my-project
```

在创建过程中，CLI 会通过交互式问答引导你配置项目：

1. **项目描述/作者**：基础元信息。
2. **跨平台支持**：选择是否需要支持 支付宝/百度/头条/QQ 等小程序平台，以及 Web 和 React Native 平台。
3. **TypeScript**：是否使用 TypeScript 进行开发。
4. **CSS 预处理器**：选择 Stylus, Less 或 Sass。
5. **Linter / Formatter**：选择 ESLint 配置。
6. **测试支持**：是否需要单元测试 (Jest) 或 E2E 测试。
7. **云开发**：是否使用微信云开发。

初始化完成后，进入项目目录并安装依赖：

```bash
cd my-project
npm install
```

## 常用命令 {#commands}

### 开发模式 {#serve}

启动开发服务器，监听文件变化并自动重新构建：

```bash
npm run serve
```

默认情况下，构建产物会输出到 `dist/wx` 目录（以微信小程序为例）。你可以使用微信开发者工具打开该目录进行预览和调试。

如果你需要调试其他平台，可以使用对应的 script，例如：

```bash
npm run serve:ali  # 支付宝小程序
npm run serve:swan # 百度小程序
npm run serve:tt   # 字节跳动小程序
npm run serve:web  # Web 平台
```

### 生产构建 {#build}

构建用于生产环境的代码（压缩、混淆、去除冗余代码等）：

```bash
npm run build
```

同样支持不同平台的构建命令：

```bash
npm run build:ali
npm run build:web
# ...
```

### 审查项目配置 {#inspect}

查看项目最终生成的 webpack 配置：

```bash
npm run inspect
```

## 配置文件 {#config}

由于 `@mpxjs/cli` 是基于 Vue CLI 的，项目的主要配置文件为根目录下的 `vue.config.js`。你可以在这里配置 webpack、Mpx 插件选项等。

### 示例配置

```javascript
// vue.config.js
module.exports = {
  outputDir: `dist/${process.env.MPX_CURRENT_TARGET_MODE || 'wx'}`,
  pluginOptions: {
    mpx: {
      // Mpx 插件配置
      srcMode: 'wx', // 源码模式，默认为 wx
      plugin: {
        // mpx-webpack-plugin 配置
        hackResolve: true
      },
      loader: {
        // mpx-loader 配置
      }
    }
  },
  configureWebpack: {
    // 自定义 webpack 配置
    resolve: {
      alias: {
        '@': 'src'
      }
    }
  }
}
```

## 插件系统 {#plugins}

`@mpxjs/cli` 使用了 Vue CLI 的插件架构。这意味着你可以使用现有的 Vue CLI 插件，也可以使用 Mpx 专属插件。

在项目初始化时选择的特性（如 TypeScript、Transpilation 等）都是以插件的形式注入到项目中的。

更多关于插件开发的文档，请参考 [Vue CLI 插件开发指南](https://cli.vuejs.org/zh/dev-guide/plugin-dev.html)。

## 旧版迁移 {#migration}

如果你之前使用的是 `mpx init` (基于 `mpx-cli` 2.x 或更早版本)，建议升级到新的 `@mpxjs/cli`。

1. 卸载旧版：`npm uninstall -g mpx-cli`
2. 安装新版：`npm install -g @mpxjs/cli`
3. 新版使用 `mpx create` 代替 `mpx init`。

## 参考文档 {#reference}

* [@mpxjs/cli GitHub 仓库](https://github.com/mpx-ecology/mpx-cli)
* [Vue CLI 官方文档](https://cli.vuejs.org/zh/)

---

---
url: /guide/cross-platform/basic.md
---
# 跨端输出配置 {#cross-platform-output-config}

Mpx以微信增强DSL为基础，支持跨端输出至多端小程序、web和客户端，包括支付宝、百度、抖音、京东、QQ等多端小程序平台，基于Vue的web平台，和基于react-native的ios、android及鸿蒙平台。

## 跨端输出配置 {#cross-platform-output-config-1}

配置mpx进行跨端输出十分简单，找到项目构建的webpack配置，在@mpxjs/webpack-plugin的配置参数中设置mode和srcMode参数即可。

```javascript
new MpxwebpackPlugin({
  // mode为mpx编译的目标平台，可选值有(wx|ali|swan|qq|tt|jd|web|ios|android|harmony)
  mode: 'ali',
  // srcMode为mpx编译的源码平台，目前仅支持wx   
  srcMode: 'wx'
})
```

对于使用 @mpxjs/cli 创建的项目，可以通过在 `npm script` 当中定义 `targets` 来设置编译的目标平台，多个平台标识以`,`分隔。

```javascript
// 项目 package.json
{
  "script": {
    "build:cross": "mpx-cli-service build --targets=wx,ali,ios,android"
  }
}
```

## 支持的平台 {#supported-platforms}

### 小程序平台 {#miniprogram-platform}

* 微信小程序 (wx)
* 支付宝小程序 (ali)
* 百度小程序 (swan)
* QQ小程序 (qq)
* 抖音小程序 (tt)
* 京东小程序 (jd)

### Web平台 {#web-platform}

* 基于Vue的Web应用 (web)

### 客户端平台 {#client-platform}

* iOS应用 (ios)
* Android应用 (android)
* 鸿蒙应用 (harmony)

## 构建命令 {#build-command}

### 单平台构建 {#single-platform-build}

```bash
# 构建微信小程序 {#build-wechat-miniprogram}
npm run build:wx

# 构建支付宝小程序 {#build-alipay-miniprogram}
npm run build:ali

# 构建Web应用 {#build-web-app}
npm run build:web

# 构建iOS应用 {#build-ios-app}
npm run build:ios
```

### 多平台构建 {#multi-platform-build}

```bash
# 构建所有支持的平台 {#build-all-platforms}
npm run build:cross

# 构建指定的多个平台 {#build-specific-platforms}
mpx-cli-service build --targets=wx,ali,web
```

## 项目结构 {#project-structure}

跨端项目的典型目录结构：

```
src/
├── components/          # 公共组件
├── pages/              # 页面文件
├── utils/              # 工具函数
├── styles/             # 样式文件
├── app.mpx             # 应用入口
└── app.json            # 应用配置
```

## 下一步 {#next-step}

* [条件编译机制](conditional.md) - 了解如何处理平台差异
* [平台差异处理](./differences.md) - 掌握差异抹平技巧

---

---
url: /guide/cross-platform/conditional.md
---
# 条件编译机制 {#conditional-compile-mechanism}

Mpx跨端输出时在框架内针对不同平台的差异进行了大量的转换抹平工作，但框架能做的工作始终是有限的，对于框架无法抹平的部分我们会在编译和运行时进行报错提示，同时提供了完善的跨平台条件编译机制，便于用户自行进行差异化处理，该能力也能够用于实现区分平台进行业务逻辑实现。

Mpx中我们支持了几种维度的条件编译，分别是文件维度、区块维度、代码维度和属性维度，其中，文件维度和区块维度主要用于处理一些大块的平台差异性逻辑，而代码维度和属性维度主要用于处理一些局部简单的平台差异。

## 文件维度条件编译 {#file-conditional-compile}

文件维度条件编译简单的来说就是文件为维度进行跨平台差异代码的编写，例如在微信->支付宝的项目中存在一个业务地图组件map.mpx，由于微信和支付宝中的原生地图组件标准差异非常大，无法通过框架转译方式直接进行跨平台输出，这时你可以在相同的位置新建一个map.ali.mpx，在其中使用支付宝的技术标准进行开发，编译系统会根据当前编译的mode来加载对应模块，当mode为ali时，会优先加载map.ali.mpx，反之则会加载map.mpx。

### 文件命名规则 {#file-naming-rule}

```
原文件名.平台标识.扩展名
```

支持的平台标识：

* `wx` - 微信小程序
* `ali` - 支付宝小程序
* `swan` - 百度小程序
* `qq` - QQ小程序
* `tt` - 抖音小程序
* `jd` - 京东小程序
* `web` - Web平台
* `ios` - iOS平台
* `android` - Android平台
* `harmony` - 鸿蒙平台

### 示例 {#example}

```
components/
├── map.mpx              # 默认实现
├── map.ali.mpx          # 支付宝专用实现
├── map.web.mpx          # Web专用实现
└── map.ios.mpx          # iOS专用实现
```

### RN平台文件兜底逻辑 {#rn-platform-fallback}

在RN平台（即mode为 ios/android/harmony）中，文件维度的条件编译存在一个兜底逻辑：

* 当编译目标为 `harmony` 平台时，如果找不到 `.harmony.mpx` 文件，会自动兜底查找 `.ios.mpx` 文件
* 当编译目标为 `android` 平台时，如果找不到 `.android.mpx` 文件，也会自动兜底查找 `.ios.mpx` 文件

因此，在开发RN跨端应用时，可以只编写一份 `index.ios.mpx` 文件，它将同时适用于iOS、Android和鸿蒙平台，除非你需要为特定平台提供不同实现。

### 与webpack alias结合使用 {#webpack-alias-usage}

文件维度条件编译能够与webpack alias结合使用，对于npm包的文件我们并不方便在原本的文件位置创建.ali的条件编译文件，但我们可以通过webpack alias在相同位置创建一个`虚拟的`.ali文件，并将其指向项目中的其他文件位置。

```js
// 对于npm包中的文件依赖
import npmModule from 'somePackage/lib/index'

// 配置以下alias后，当mode为ali时，会优先加载项目目录中定义的projectRoot/somePackage/lib/index文件
// vue.config.js
module.exports = defineConfig({
  configureWebpack() {
    return {
      resolve: {
        alias: {
          'somePackage/lib/index.ali': path.resolve(__dirname, 'src/adapters/ali/somePackage-index.js')
        }
      }
    }
  }
})
```

## 区块维度条件编译 {#block-conditional-compile}

在.mpx单文件中一般存在template、js、stlye、json四个区块，mpx的编译系统支持以区块为维度进行条件编译，只需在区块标签中添加`mode`属性定义该区块的目标平台即可，示例如下：

```html
<!--编译mode为ali时使用如下区块-->
<template mode="ali">
<!--该区块中的所有代码需采用支付宝的技术标准进行编写-->
  <view>支付宝环境</view>
</template>

<!--其他编译mode时使用如下区块-->
<template>
  <view>其他环境</view>
</template>
```

## 代码维度条件编译 {#code-conditional-compile}

代码维度条件编译主要用于处理一些局部简单的平台差异，用户可以在js代码和template插值中访问`__mpx_mode__`获取当前编译mode，进行平台差异逻辑编写。

除了 `__mpx_mode__` 这个默认插值以外，有别的环境变量需要的话可以在mpx.plugin.conf.js里通过defs进行配置。

### JS代码条件编译 {#js-conditional-compile}

```js
if(__mpx_mode__ === 'ali') {
  // 执行支付宝环境相关逻辑
} else {
  // 执行其他环境相关逻辑
}
```

#### async/await 注意事项 {#async-await-notes}

在使用条件编译时，如果涉及到 async/await 语法，需要注意以下问题：

有些开发者会编写如下代码，但会发现编译时 false block 内的模块也会被加载解析：

```js
async function someMethod() { 
  if (__mpx_mode__ === 'ios' || __mpx_mode__ === 'android') { 
    return {} 
  } else{ 
    const mod = await require.async('./index.js?root=main') 
    console.log('mod', mod) 
  } 
} 
```

这是因为经过babel处理之后，async/await 会被处理为 @babel/runtime-corejs3/regenerator 的 switch 语法，从而导致静态分析删除代码失效，false block 内的模块被正常加载索引：

```js
function _someMethod() { 
  _someMethod = _asyncToGenerator(/*#__PURE__*/_regeneratorRuntime.mark(function _callee() { 
    var mod; 
    return _regeneratorRuntime.wrap(function _callee$(_context) { 
      while (1) switch (_context.prev = _context.next) { 
        case 0: 
          if (!(__mpx_mode__ === 'ios' || __mpx_mode__ === 'android')) { 
            _context.next = 4; 
            break; 
          } 
          return _context.abrupt("return", {}); 
        case 4: 
          if (!(__mpx_mode__ === 'ali')) { 
            _context.next = 9; 
            break; 
          } 
          _context.next = 7; 
          return require.async('./index.js?root=main'); 
        case 7: 
          mod = _context.sent; 
          console.log('mod', mod); 
        case 9: 
        case "end": 
          return _context.stop(); 
      } 
    }, _callee); 
  })); 
  return _someMethod.apply(this, arguments); 
} 
```

遇到这种情况，可以修改为 if block 整体包裹 async await 语句，或者使用 Promise：

```js
function someMethod() { 
  if (__mpx_mode__ === 'ios' || __mpx_mode__ === 'android') { 
    return {} 
  } else if (__mpx_mode__ === 'ali') { 
    let mod = {} 
    (async () => { 
      mod = await require.async('./index.js?root=main') 
    })(); 
    console.log('mod', mod) 
  } 
}
```

### 模板条件编译 {#template-conditional-compile}

```html
<!--此处的__mpx_mode__不需要在组件中声明数据，编译时会基于当前编译mode进行替换-->
<view wx:if="{{__mpx_mode__ === 'ali'}}">支付宝环境</view>
<view wx:else>其他环境</view>
```

### JSON条件编译 {#json-conditional-compile}

注意，这个依赖JSON的动态方案，得通过name="json"这种方式来编写，其实写的是js代码，最终module.exports导出一个可json化的对象即可：

```html
<script name="json">
const pages = __mpx_mode__ === 'wx' ? [
  'main/xxx',
  'sub/xxx'
] : [
  'test/xxx'
] // 可以为不同环境动态书写配置
module.exports = {
  usingComponents: {
    aComponents: '../xxxxx' // 可以打注释 xxx组件
  }
}
</script>
```

### 样式条件编译 {#style-conditional-compile}

```css
/*
  @mpx-if (__mpx_env__ === 'someEvn')
*/
  /* @mpx-if (__mpx_mode__ === 'wx') */
  .backColor {
    background: green;
  }
  /*
    @mpx-elif (__mpx_mode__ === 'qq')
  */
  .backColor {
    background: black;
  }
  /* @mpx-endif */

  /* @mpx-if (__mpx_mode__ === 'swan') */
  .backColor {
    background: cyan;
  }
  /* @mpx-endif */
  .textSize {
    font-size: 18px;
  }
/*
  @mpx-else
*/
.backColor {
  /* @mpx-if (__mpx_mode__ === 'swan') */
  background: blue;
  /* @mpx-else */
  background: red;
  /* @mpx-endif */
}
/*
  @mpx-endif
*/
```

## 属性维度条件编译 {#attr-conditional-compile}

属性维度条件编译允许用户在组件上使用 `@` 和 `|` 符号来指定某个节点或属性只在某些平台下有效。

对于同一个 button 组件，微信小程序支持 `open-type="getUserInfo"`，但是支付宝小程序支持 `open-type="getAuthorize" `。如果不使用任何维度的条件编译，则在编译的时候会有警告和报错信息。

比如业务中需要通过 button 按钮获取用户信息，虽然可以使用代码维度条件编译来解决，但是增加了很多代码量：

```html
<button
  wx:if="{{__mpx_mode__ === 'wx' || __mpx_mode__ === 'swan'}}"
  open-type="getUserInfo"
  bindgetuserinfo="getUserInfo">
  获取用户信息
</button>

<button
  wx:elif="{{__mpx_mode__ === 'ali'}}"
  open-type="getAuthorize"
  scope="userInfo"
  onTap="onTap">
  获取用户信息
</button>
```

而用属性维度的编译则方便很多：

```html
<button
  open-type@wx|swan="getUserInfo"
  bindgetuserinfo@wx|swan="getUserInfo"
  open-type@ali="getAuthorize"
  scope@ali="userInfo"
  onTap@ali="onTap">
  获取用户信息
</button>
```

属性维度的编译也可以对整个节点进行条件编译，例如只想在支付宝小程序中输出某个节点：

```html
<view @ali>this is view</view>
```

需要注意使用上述用法时，节点自身在构建时框架不会对节点属性进行平台语法转换，但对于其子节点，框架并不会继承父级节点 mode，会进行正常跨平台语法转换。

```html
<!--错误示例-->
<view @ali bindtap="otherClick">
    <view bindtap="someClick">tap click</view>
</view>
<!--srcMode 为 wx 跨端输出 ali 结果为-->
<view @ali bindtap="otherClick">
    <view onTap="someClick">tap click</view>
</view>
```

上述示例为错误写法，假如srcMode为微信小程序，用上述写法构建输出支付宝小程序时，父节点 bindtap 不会被转为 onTap，在支付宝平台执行时事件会无响应。

正确写法如下：

```html
<!--正确示例-->
<view @ali onTap="otherClick">
    <view bindtap="someClick">tap click</view>
</view>
<!--输出 ali 产物-->
<view @ali onTap="otherClick">
    <view onTap="someClick">tap click</view>
</view>
```

有时开发者期望使用 @ali 这种方式仅控制节点的展示，保留节点属性的平台转换能力，为此 Mpx 实现了一个隐式属性条件编译能力

```html
<!--srcMode为 wx，输出 ali 时，bindtap 会被正常转换为 onTap-->
<view @_ali bindtap="someClick">test</view>
```

在对应的平台前加一个\_，例如@\_ali、@\_swan、@\_tt等，使用该隐式规则仅有条件编译能力，节点属性语法转换能力依旧。

有时候我们不仅需要对节点属性进行条件编译，可能还需要对节点标签进行条件编译。

为此，我们支持了一个特殊属性 `mpxTagName`，如果节点存在这个属性，我们会在最终输出时将节点标签修改为该属性的值，配合属性维度条件编译，即可实现对节点标签进行条件编译，例如在百度环境下希望将某个 view 标签替换为 cover-view，我们可以这样写：

```html
<view mpxTagName@swan="cover-view">will be cover-view in swan</view>
```

## 通过 env 实现自定义目标环境的条件编译{#use-env}

除了基于平台标识（mode）的条件编译外，Mpx 还支持通过自定义环境变量（env）实现在不同业务环境下编译产出不同的代码。这使得我们可以在同一平台下为不同的业务场景提供差异化实现。

### 配置自定义环境变量 {#config-custom-env-vars}

在实例化 MpxWebpackPlugin 时，通过配置 env 参数来指定目标环境：

```javascript
// vue.config.js
module.exports = defineConfig({
  pluginOptions: {
    mpx: {
      srcMode: 'wx', // srcMode为mpx编译的源码平台，目前仅支持wx
      plugin: {
        env: "didi" // env为mpx编译的目标环境，需自定义
      }
    }
  }
})
```

### 文件维度条件编译与 env {#file-conditional-compile-env}

在文件维度条件编译中，可以结合 mode 和 env 来命名文件，编译系统会根据当前编译的 mode 和 env 来加载对应模块。

例如，在一个微信转支付宝的项目中，如果地图组件在不同业务环境中也有差异，可以创建如下文件：

```
components/
├── map.mpx              # 默认实现
├── map.ali.mpx          # 支付宝通用实现
└── map.ali.qingju.mpx   # 支付宝青桔业务环境实现
```

加载优先级如下：

* 当 mode 为 ali，env 为 qingju 时，优先加载 map.ali.qingju.mpx
* 如果找不到特定 env 的文件，则加载 map.ali.mpx
* 如果都找不到，则加载默认的 map.mpx

### 区块维度条件编译与 env {#block-conditional-compile-env}

在 .mpx 单文件的区块中，可以同时使用 `mode` 和 `env` 属性来定义条件编译，优先级从高到低如下：

```html
<!--编译mode为ali且env为didi时使用，优先级最高-->
<template mode="ali" env="didi">
  <view>支付宝滴滴环境专用模板</view>
</template>

<!--编译mode为ali时使用-->
<template mode="ali">
  <view>支付宝通用模板</view>
</template>

<!--编译env为didi时使用-->
<template env="didi">
  <view>滴滴业务环境通用模板</view>
</template>

<!--其他环境使用-->
<template>
  <view>默认模板</view>
</template>
```

注意：如果定义了多个具有相同 mode 和 env 的区块，默认会使用最后一个。

### 代码维度条件编译与 env {#code-conditional-compile-env}

在代码中，可以通过访问 `__mpx_env__` 获取当前编译环境，与 `__mpx_mode__` 的用法相同：

```js
if (__mpx_env__ === 'didi') {
  // 滴滴业务环境相关逻辑
} else if (__mpx_env__ === 'qingju') {
  // 青桔业务环境相关逻辑
} else {
  // 其他业务环境逻辑
}
```

### 属性维度条件编译与 env {#attr-conditional-compile-env}

env 属性维度条件编译使用 `:` 符号与 mode 进行组合，格式为 `attr@mode:env:env|mode:env`。当只有 env 条件时，需要添加 `:` 前缀，如 `attr@:env`。

```html
<!-- 仅在 env 为 didi 时生效的属性 -->
<button open-type@:didi="getUserInfo">获取用户信息</button>

<!-- 在 mode 为 wx 且 env 为 didi 或 qingju 时生效的属性 -->
<button open-type@wx:didi:qingju="getUserInfo">获取用户信息</button>

<!-- 仅在 env 为 didi 时显示的节点 -->
<view @:didi>仅在滴滴业务环境显示</view>

<!-- 在 env 为 didi 时改变节点标签 -->
<view mpxTagName@:didi="cover-view">在滴滴业务环境中变为 cover-view</view>
```

当只声明了 env 而没有声明 mode 时，跨平台输出时框架会对节点属性进行正常转换：

```html
<!--srcMode为wx，跨平台输出ali时，bindtap会被转为onTap-->
<view @:didi bindtap="someClick">this is a view component</view>
<view bindtap@:didi="someClick">this is a view component</view>
```

通过结合使用 mode 和 env 的条件编译，我们可以更精细地控制代码在不同平台和不同业务环境下的行为，实现真正的一套代码多端多环境运行。

---

---
url: /guide/rn/start.md
---
# 快速开始 {#quick-start}

Mpx 可通过输出为 React Native 代码实现直接在 iOS、Android 中作为 App 运行。

### 1. 创建新项目 {#create-new-project}

```sh
# 使用 Mpx CLI 创建支持 RN 的项目 {#create-rn-project-cli}
npx @mpxjs/cli@latest create my-rn-app

# 选择包含 React Native 支持的模板 {#select-rn-template}
# ? 是否需要输出react-native Yes {#output-rn-yes}
```

> \[!tip] 注意
>
> 框架仅负责将 Mpx 项目输出为 React Native 代码，而后 React Native 代码的编译构建完全由 React Native 项目完成。
>
> 选择 “是否需要输出 react-native” 后，默认 Mpx 项目将包含一个由 `@react-native-community/cli` 创建的名为 ReactNativeProject 的 React Native 项目，以便用于对 React Native 代码的开发调试和编译。

### 2. 项目结构 {#project-structure}

```sh
my-rn-app/
├── src/                    # 源码目录
│   ├── pages/              # 页面目录
│   ├── components/         # 组件目录
│   ├── utils/              # 工具函数
│   ├── store/              # 状态管理
│   ├── app.mpx             # 应用入口
│   └── app.json            # 应用配置
├── ReactNativeProject/     # React Native 项目目录
│   ├── android/            # Android 项目
│   ├── ios/                # iOS 项目
│   ├── index.js            # RN 入口文件(同时也是Mpx的输出产物)
│   └── package.json        # RN 依赖
├── dist/                   # 编译输出
│   └── react-native/       # RN 编译结果
└── mpx.config.js           # 构建配置
```

### 3. 开发调试 {#dev-debug}

::: code-group

```sh [iOS]
# 运行 IOS 应用 {#run-ios}
npm run serve:ios
```

```sh [Android]
# 运行 Android 应用 {#run-android}
npm run serve:android
```

:::

### 4. 构建 {#build}

::: code-group

```sh [iOS]
# 编译到 IOS {#build-ios}
npm run build:ios
```

```sh [Android]
# 编译到 Android {#build-android}
npm run build:android
```

:::

---

---
url: /guide/rn/component.md
---
# 组件使用与开发 {#component-usage-development}

本节提供 Mpx RN 环境下的组件支持说明，详细列出了支持的基础组件及其可用属性、方法，以及自定义组件的相关配置。

### 目录概览 {#directory-overview}

* #### 基础组件

**容器组件**：[view](#view) · [scroll-view](#scroll-view) · [swiper](#swiper) · [swiper-item](#swiper-item) · [movable-area](#movable-area) · [movable-view](#movable-view) · [root-portal](#root-portal) · [sticky-section](#sticky-section) · [sticky-header](#sticky-header) · [cover-view](#cover-view)

**媒体组件**：[image](#image) · [video](#video) · [canvas](#canvas)

**表单组件**：[input](#input) · [textarea](#textarea) · [button](#button) · [checkbox](#checkbox) · [checkbox-group](#checkbox-group) · [radio](#radio) · [radio-group](#radio-group) · [switch](#switch) · [picker](#picker) · [picker-view](#picker-view) · [picker-view-column](#picker-view-column) · [form](#form) · [label](#label)

**基础组件**：[text](#text) · [icon](#icon) · [progress](#progress) · [navigator](#navigator) · [rich-text](#rich-text) · [cover-image](#cover-image)

**其他组件**：[web-view](#web-view)

* #### 自定义组件

[组件属性配置](#component-props-config) · [生命周期钩子](#lifecycle-hooks) · [实例属性和方法](#instance-props-methods)

### 使用原则 {#usage-principles}

> \[!important] 重要说明
>
> * **支持范围**：仅支持文档中明确列出的组件和属性
> * **平台特性**：某些属性和功能仅在 RN 环境下可用
> * **性能考量**：按需开启高级功能，避免不必要的性能开销

## 基础组件 {#basic-components}

目前 Mpx 输出 React Native 仅支持以下组件，文档中未提及的组件以及组件属性即为不支持，具体使用范围可参考如下文档

### 基础组件通用属性 {#basic-component-common-props}

| 属性名                   | 类型     | 默认值         | 说明                                                       |
| ----------------------- | ------- | ------------- | ---------------------------------------------------------- |
| enable-offset		  | boolean  |     `false`    | 设置是否要获取组件的布局信息，若设置了该属性，会在 e.target 中返回组件的 offsetLeft、offsetWidth 信息|
| enable-var	  | boolean  |     `true`    | 默认支持使用 css variable，若想关闭该功能可设置为 false |
| enable-text-pass-through | boolean | `false` | RN 环境特有属性，开启文本样式和文本属性透传上下文，请在动态添加文本样式或文本属性时开启 |
| parent-width		  | number  |         | 父组件宽度，主要用于百分比计算的场景，如 width: calc(100% - 20px)，需要在外部传递父组件的宽度|
| parent-height		  | number  |         | 父组件高度，主要用于百分比计算的场景，如 height: calc(100% - 20px),需要在外部传递父组件的高度|

以上基础组件的通用属性仅在 React Native 环境中支持。在跨平台输出到小程序或 Web 时，这些属性将无法使用。

由于 view、text、scroll-view、image 和 input 组件都是基于 React Native 原生组件实现的，因此这些组件默认继承原生组件支持的属性。

与微信小程序一致，React Native 输出支持只传递属性名不传递属性值的布尔写法，例如 `<scroll-view scroll-y />` 等价于 `<scroll-view scroll-y="{{ true }}" />`。

### view

视图容器。
属性

| 属性名                   | 类型     | 默认值         | 说明                                                       |
| ----------------------- | ------- | ------------- | ---------------------------------------------------------- |
| hover-class	             | string  |         | 指定按下去的样式类。 |
| hover-start-time   | number  |     `50`    | 按住后多久出现点击态，单位毫秒|
| hover-stay-time	  | number  |     `400`    | 手指松开后点击态保留时间，单位毫秒	 |
| animation | object  |   | 传递动画的实例， 可配合mpx.createAnimation方法一起使用|
| enable-background		  | boolean  |     `false `   |  RN环境特有属性，是否要开启background-image、background-size和background-position的相关计算或渲染，请根据实际情况开启 |
| enable-animation | boolean  | `false`  | RN环境特有属性，开启要开启动画渲染，请根据实际情况开启 |
| enable-fast-image | boolean  | `false`  | RN环境特有属性，开启后将使用 react-native-fast-image 进行图片渲染，请根据实际情况开启 |
| is-simple | -  | -  | RN环境特有标记，设置后将使用简单版本的 view 组件渲染，该组件不包含 css var、calc、ref 等拓展功能，但性能更优，请根据实际情况设置 |

事件

| 事件名           | 说明                |
| ----------------| ------------------ |
| transitionend| 动画结束时触发,`event.detail = { elapsedTime, finished, current }`     |

> \[!tip] 注意
>
> * 如果从未使用背景图、动图或动画，请不要开启`enable-background`、`enable-animation`或`enable-fast-image`属性，会有一定的性能消耗。
> * 若开启`enable-background`需要给当前 view 组件设置一个唯一 key。
> * `background-image`、`background-size`、`background-position` 等背景图相关 css 属性，仅 view 组件支持
> * 出于性能考虑，view 的样式增强能力（如 `enable-background`、`enable-animation`）采用按需启用策略。view 组件仅在**首次**渲染时检测样式并决定是否开启对应能力。由于 React Hooks 的一致性约束，增强能力无法在后续更新阶段再动态启用，因此当组件生命周期内**可能**使用相关能力时，需在首次渲染时**显式声明**启用，比如 `enable-animation="{{ true }}"`。

### text

文本。

属性

| 属性名                   | 类型     | 默认值         | 说明                                                       |
| ----------------------- | ------- | ------------- | ---------------------------------------------------------- |
| user-select             | boolean  | `false`       | 文本是否可选。 |
| selectable              | boolean  | `false`       | 文本是否可选。该属性已废弃，请使用 user-select |
| decode                  | boolean  | `false`       | 是否解码 |
| is-simple               | -  | -  | RN环境特有标记，设置后将使用简单版本的 text 组件渲染，该组件不包含 css var、calc、ref 等拓展功能，但性能更优，请根据实际情况设置 |

> \[!tip] 注意
>
> * 未包裹 text 标签的文本，会自动包裹 text 标签。
> * text 组件开启 enable-offset 后，offsetLeft、offsetWidth 获取时机仅为组件首次渲染阶段

### scroll-view

可滚动视图区域。

属性

| 属性名                   | 类型     | 默认值     | 说明                                               |
| ----------------------- | ------- | --------- | -------------------------------------------------- |
| scroll-x                | boolean | `false`   | 允许横向滚动 |
| scroll-y                | boolean | `false`   | 允许纵向滚动  |
| upper-threshold         | number  | `50`      | 距顶部/左边多远时(单位 px),触发 scrolltoupper 事件      |
| lower-threshold         | number  | `50`      | 距底部/右边多远时(单位 px),触发 scrolltolower 事件      |
| scroll-top              | number  | `0`       | 设置纵向滚动条位置                                    |
| scroll-left             | number  | `0`       | 设置横向滚动条位置                                    |
| scroll-with-animation   | boolean | `false`   | 在设置滚动条位置时使用动画过渡                          |
| enable-back-to-top      | boolean | `false`   | 点击状态栏的时候视图会滚动到顶部，仅 iOS环境支持                      |
| enhanced                | boolean | `false`   | scroll-view 组件功能增强                             |
| bounces                | boolean | `true`   | iOS 下 scroll-view 边界弹性控制 (同时开启 enhanced 属性后生效)                          |
| refresher-enabled       | boolean | `false`   | 开启自定义下拉刷新，iOS 下需要把 enhanced 和 bounces 都设置为 true                               |
| refresher-threshold     | number  | `45`      | 设置自定义下拉刷新阈值                                  |
| scroll-into-view	        | boolean | `false` | 值应为某子元素id（id不能以数字开头）    |\
| scroll-into-view-offset	        | number | `0` | 跳转到 scroll-into-view 目标节点时的额外偏移                       |
| refresher-default-style | string  | `'black'` | 设置下拉刷新默认样式,支持 `black`、`white`、`none`，仅安卓支持 |
| refresher-background    | string  | `'#fff'`  | 设置自定义下拉刷新背景颜色，仅安卓支持                         |
| refresher-triggered     | boolean | `false`   | 设置当前下拉刷新状态,true 表示已触发               |
| paging-enabled          | number  | `false`   | 分页滑动效果 (同时开启 enhanced 属性后生效)，当值为 true 时，滚动条会停在滚动视图的尺寸的整数倍位置  |
| show-scrollbar          | number  | `true`   | 滚动条显隐控制 (同时开启 enhanced 属性后生效)|
| enable-trigger-intersection-observer  |  boolean   |  `false`    | RN环境特有属性，是否开启intersection-observer |
| simultaneous-handlers  | array\<object>  |    `[]`    | RN环境特有属性，主要用于组件嵌套场景，允许多个手势同时识别和处理并触发，这个属性可以指定一个或多个手势处理器，处理器支持使用 this.$refs.xxx 获取组件实例来作为数组参数传递给 scroll-view 组件 |
| wait-for  |  array\<object>  |  `[]`    | RN环境特有属性，主要用于组件嵌套场景，允许延迟激活处理某些手势，这个属性可以指定一个或多个手势处理器，处理器支持使用 this.$refs.xxx 获取组件实例来作为数组参数传递给 scroll-view 组件 |
| scroll-event-throttle  |  number   |  `0`   | RN环境特有属性，控制 scroll 事件触发频率 |
| enable-sticky  |  boolean   |  `false`   | RN环境特有属性，当使用 sticky 组件时，需要手动将此属性设置为 true |

事件

| 事件名           | 说明                |
| ----------------| ------------------ |
| dragstart| 滑动开始事件，同时开启 enhanced 属性后生效|
| dragging| 滑动事件，同时开启 enhanced 属性后生效 |
| dragend| 滑动结束事件，同时开启 enhanced 属性后生效 |
| scrolltoupper   | 滚动到顶部/左边触发 |
| scrolltolower   | 滚动到底部/右边触发 |
| scroll          | 滚动时触发         |
| scrollend | 滚动结束时触发         |
| refresherrefresh| 自定义下拉刷新被触发 |

> \[!tip] 注意
>
> * 若使用 scroll-into-view 属性，需要 id 对应的组件节点添加 wx:ref 标记，否则无法正常滚动。另外组件节点需要是内置基础组件，自定义组件暂不支持。
> * simultaneous-handlers 为 RN 环境特有属性，具体含义可参考[react-native-gesture-handler](https://docs.swmansion.com/react-native-gesture-handler/docs/fundamentals/gesture-composition/#simultaneouswithexternalgesture)
> * wait-for  为 RN 环境特有属性，具体含义可参考[react-native-gesture-handler](https://docs.swmansion.com/react-native-gesture-handler/docs/fundamentals/gesture-composition/#requireexternalgesturetofail)
> * scroll-view 组件在滚动过程中，不会触发其自身或子组件的 touchend 事件响应，这是 RN 底层实现导致的问题，手势系统识别当前是 scroll-view 的滚动，就会取消掉 touchend 事件的响应。
> * 安卓上如果触发了 scroll-view 组件默认的下拉刷新，binddragend可能不触发，只会触发 binddragstart

### swiper

滑块视图容器。

属性

| 属性名                   | 类型     | 默认值              | 说明                                 |
| ----------------------- | ------- | ------------------  | ------------------------------------|
| indicator-dots          | boolean | `false`             | 是否显示面板指示点                     |
| indicator-color         | color   | `rgba(0, 0, 0, .3)` | 指示点颜色                            |
| indicator-active-color  | color   | `#000000`           | 当前选中的指示点颜色                   |
| indicator-width         | number  |                     | 指示点宽度             |
| indicator-height        | number  |                     | 指示点高度             |
| indicator-spacing       | number  |                     | 指示点间距             |
| indicator-radius        | number  |                     | 指示点圆角             |
| indicator-margin        | number  |                     | 指示点外边距           |
| autoplay                | boolean | `false`             | 是否自动切换                          |
| current                 | number  | `0`                 | 当前所在滑块的 index                  |
| interval                | number  | `5000`              | 自动切换时间间隔                       |
| duration                | number  | `500`               | 滑动动画时长                          |
| circular                | boolean | `false`             | 是否采用衔接滑动                       |
| vertical                | boolean | `false`             | 滑动方向是否为纵向                      |
| previous-margin         | string  | `0`                 | 前边距，可用于露出前一项的一小部分，接受px |
| next-margin             | string  | `0`                 | 后边距，可用于露出后一项的一小部分，接受px |
| scale                   | boolean  | `false`            | 滑动时是否开启前后元素缩小,默认是缩放0.7倍, 暂不支持自定义 |
| easing-function         | string  | `linear`      | 支持 linear、easeInCubic、easeOutCubic、easeInOutCubic|
| simultaneous-handlers              | array\<object>|   `[]`          | RN环境特有属性，主要用于组件嵌套场景，允许多个手势同时识别和处理并触发，这个属性可以指定一个或多个手势处理器，处理器支持使用 this.$refs.xxx 获取组件实例来作为数组参数传递给 swiper 组件|
| wait-for              | array\<object>|   `[]`          | RN环境特有属性，主要用于组件嵌套场景，允许延迟激活处理某些手势，这个属性可以指定一个或多个手势处理器，处理器支持使用 this.$refs.xxx 获取组件实例来作为数组参数传递给 swiper 组件|
| disableGesture              | boolean|   `false`       |  RN 环境特有属性，禁用 swiper 滑动手势。若开启用户无法通过手势滑动 swiper，只能通过开启 autoPlay 进行自动轮播|

事件

| 事件名           | 说明                |
| ----------------| ------------------ |
| change| current 改变时会触发 change 事件，`event.detail = {current, source}`|

### swiper-item

仅可放置在swiper组件中，宽高自动设置为100%。

属性

| 属性名                   | 类型     | 默认值              | 说明                                 |
| ----------------------- | ------- | ------------------  | ------------------------------------|
| item-id                 | string  |             | 该 swiper-item 的标识符                  |

### movable-area

movable-view的可移动区域。

### movable-view

可移动的视图容器，在页面中可以拖拽滑动。movable-view 必须在 movable-area 组件中，并且必须是直接子节点，否则不能移动。

属性

| 属性名 | 类型             | 默认值 | 说明                                                                                                  |
| ------ | ---------------- | ------ | ----------------------------------------------------------------------------------------------------- |
| direction   | string           |   `none`     | 目前支持 all、vertical、horizontal、none  |
| inertia   | boolean          |   `false`     | movable-view是否带有惯性  |
| out-of-bounds   | boolean          |   `false`     | 超过可移动区域后，movable-view是否还可以移动  |
| x   | number |      | 定义x轴方向的偏移  |
| y  | number  |        | 定义y轴方向的偏移 |
| disabled  | boolean  |    `false`   | 是否禁用 |
| animation  | boolean  |    `true`   | 是否使用动画	 |
| damping   | number   |    `20`      | 阻尼系数，用于控制x或y改变时的动画和过界回弹的动画，值越大移动越快 |
| friction  | number   |    `2`       | 摩擦系数，用于控制惯性滑动的动画，值越大摩擦力越大，滑动越快停止 |
| simultaneous-handlers  | array\<object>  |   `[]`   | RN 环境特有属性，主要用于组件嵌套场景，允许多个手势同时识别和处理并触发，这个属性可以指定一个或多个手势处理器，处理器支持使用 this.$refs.xxx 获取组件实例来作为数组参数传递给 movable-view 组件 |
| wait-for  |  array\<object>  |  `[]`    |  RN 环境特有属性，主要用于组件嵌套场景，允许延迟激活处理某些手势，这个属性可以指定一个或多个手势处理器，处理器支持使用 this.$refs.xxx 获取组件实例来作为数组参数传递给 movable-view 组件 |
| disable-event-passthrough | boolean  |  `false`   | RN 环境特有属性，有时候我们希望movable-view 在水平方向滑动，并且竖直方向的手势也希望被 movable-view 组件消费掉，不被其他组件响应，可以将这个属性设置为true） |

事件

| 事件名     | 说明                                                         |
| ---------- | ------------------------------------------------------------ |
| change     | 拖动过程中触发，`event.detail = {x, y, source}`              |
| htouchmove | 初次手指触摸后横向移动时触发，支持使用 `catch` 阻止事件冒泡 |
| vtouchmove | 初次手指触摸后纵向移动时触发，支持使用 `catch` 阻止事件冒泡 |

> \[!tip] 注意
>
> * simultaneous-handlers 为 RN 环境特有属性，具体含义可参考[react-native-gesture-handler](https://docs.swmansion.com/react-native-gesture-handler/docs/fundamentals/gesture-composition/#simultaneouswithexternalgesture)
> * wait-for  为 RN 环境特有属性，具体含义可参考[react-native-gesture-handler](https://docs.swmansion.com/react-native-gesture-handler/docs/fundamentals/gesture-composition/#requireexternalgesturetofail)
> * RN 环境 movable 相关组件暂不支持缩放能力

### image

图片组件

属性

| 属性名                   | 类型     | 默认值         | 说明                                                       |
| ----------------------- | ------- | ------------- | ---------------------------------------------------------- |
| src                     | string  | `false`       | 图片资源地址、base64 格式数据或本地静态资源相对路径 |
| mode                    | string  | `scaleToFill` | 图片裁剪、缩放的模式，可选值为 `scaleToFill`、`aspectFit`、`aspectFill`、`widthFix`、`heightFix`、`top`、`bottom`、`center`、`left`、`right`、`top left`、`top right`、`bottom left`、`bottom right`             |
| enable-fast-image          | boolean  | `false`   | RN环境特有属性，开启后将使用 react-native-fast-image 进行图片渲染，请根据实际情况开启 |
| is-svg                 | boolean  | `false`   | RN 环境特有属性，传递为 `true` 时强制使用 SVG 方式渲染图片 |

事件

| 事件名           | 说明                                                 |
| ----------------| --------------------------------------------------- |
| error       | 当错误发生时触发，`event.detail = { errMsg }`            |
| load        | 当图片载入完毕时触发，`event.detail = { height, width }`  |

> \[!tip] 注意
>
> * image 组件默认宽度320px、高度240px
> * image 组件进行缩放时，计算出来的宽高可能带有小数，在不同 webview 内核下渲染可能会被抹去小数部分
> * RN 输出支持 `<image src="./logo.png" />` / `<image src="./icon.svg" />` 这类本地静态资源写法，编译后会通过 webpack 资源 loader 处理；动态绑定本地图片时建议在脚本中 `import` 后再绑定。

### icon

图标组件

属性

| 属性名                   | 类型     | 默认值         | 说明                                                       |
| ----------------------- | ------- | ------------- | ---------------------------------------------------------- |
| type      | string  |               | icon 的类型，有效值：success、success\_no\_circle、info、warn、waiting、cancel、download、search、clear |
| size      | string|number  |     `23`    | icon 的大小 |
| color		  | string  |         | icon 的颜色，同 css 的 color |

### button

按钮。

属性

| 属性名                   | 类型     | 默认值         | 说明                                                      |
| ----------------------- | ------- | ------------- | --------------------------------------------------------- |
| size                    | string  | `default`     | 按钮的大小，`default`：默认大小，`mini`：小尺寸                                                  |
| type                    | string  | `default`     | 按钮的样式类型，`primary`：绿色，`default`：白色，`warn`：红色                                               |
| plain                   | boolean | `false`       | 按钮是否镂空，背景色透明                                       |
| disabled                | boolean | `false`       | 是否禁用                                                    |
| loading                 | boolean | `false`       | 名称前是否带 loading 图标                                     |
| form-type               | string  |               | 用于 form 组件，点击分别会触发 form 组件的 submit/reset 事件，有效值为 `submit`、`reset` |
| open-type               | string  |               | 微信开放能力，当前仅支持 `share` 和 `getUserInfo`                              |
| hover-class             | string  |               | 指定按钮按下去的样式类。当 hover-class="none" 时，没有点击态效果  |
| hover-start-time        | number  |  `20`         | 按住后多久出现点击态，单位毫秒                                  |
| hover-stay-time         | number  |  `70`         | 手指松开后点击态保留时间，单位毫秒                               |

> \[!tip] 注意
>
> * openType 需要在 `mpx.config.rnConfig` 中注册对应能力如 ` onShareAppMessage`，`onUserInfo` 来配合使用。

### label

用来改进表单组件的可用性

> \[!tip] 注意
>
> * 当前不支持使用 for 属性找到对应 id，仅支持将控件放在该标签内，目前可以绑定的空间有：checkbox、radio、switch。

### checkbox

多选项目

属性

| 属性名                   | 类型     | 默认值         | 说明                                                       |
| ----------------------- | ------- | ------------- | ---------------------------------------------------------- |
| value	    | string   |              | checkbox 标识，选中时触发 checkbox-group 的 change 事件，并携带 checkbox 的 value |
| disabled  | boolean  |     `false`    | 是否禁用 |
| checked	  | boolean  |     `false`    | 当前是否选中，可用来设置默认选中 |
| color		  | string   |     `#09BB07` | checkbox的颜色，同css的color |

### checkbox-group

多项选择器，内部由多个checkbox组成。

事件

| 事件名           | 说明                |
| ----------------| ------------------ |
| change      | checkbox-group 中选中项发生改变时触发 change 事件，`detail = { value: [ 选中的 checkbox 的 value 的数组 ] } `|

### radio

单选项目

属性

| 属性名                   | 类型     | 默认值         | 说明                                                       |
| ----------------------- | ------- | ------------- | ---------------------------------------------------------- |
| value	    | string  |               | radio 标识，当该 radio 选中时，radio-group 的 change 事件会携带 radio 的 value |
| disabled  | boolean  |     false    | 是否禁用 |
| checked	  | boolean  |     false    | 当前是否选中，可用来设置默认选中 |
| color		  | string   |     #09BB07  | checkbox 的颜色，同 css 的 color |

### radio-group

单项选择器，内部由多个 radio 组成

事件

| 事件名           | 说明                |
| ----------------| ------------------ |
| change      | radio-group 中选中项发生改变时触发 change 事件，`detail = { value: [ 选中的 radio 的 value 的数组 ] }` |

### form

表单。

当点击 form 表单中 form-type 为 submit 的 button 组件时，会将表单组件中的 value 值进行提交，需要在表单组件中加上 name 来作为 key。

事件

| 事件名     | 说明                                                |
| ---------- | --------------------------------------------------- |
| submit | 携带 form 中的数据触发 submit 事件，`event.detail = {value : {'name': 'value'} }` |
| reset  | 表单重置时会触发 reset 事件 |

### input

输入框。

属性

| 属性名                   | 类型     | 默认值         | 说明                                                       |
| ----------------------- | ------- | ------------- | ---------------------------------------------------------- |
| value                   | string  |               | 输入框的初始内容                                              |
| type                    | string  | `text`        | input 的类型，可选值为 `text`、`number`、`idcard`、`digit`，不支持 `safe-password`、`nickname`              |
| password                | boolean | `false`       | 是否是密码类型                                               |
| placeholder             | string  |               | 输入框为空时占位符                                            |
| placeholder-class       | string  |               | 指定 placeholder 的样式类，仅支持 color 属性                   |
| placeholder-style       | string  |               | 指定 placeholder 的样式，仅支持 color 属性                    |
| disabled                | boolean | `false`       | 是否禁用                                                    |
| maxlength               | number  | `140`         | 最大输入长度，设置为 -1 的时候不限制最大长度                     |
| cursor-spacing          | number  | `0`           | 指定光标与键盘的距离，单位 px。取 input 距离底部的距离和 cursor-spacing 指定的距离的最小值作为光标与键盘的距离 |
| auto-focus              | boolean | `false`       | (即将废弃，请直接使用 focus )自动聚焦，拉起键盘                  |
| focus                   | boolean | `false`       | 获取焦点                                                    |
| confirm-type            | string  | `done`        | 设置键盘右下角按钮的文字，仅在 type='text' 时生效，可选值为 `send`、`search`、`next`、`go`、`done`、`return`              |
| confirm-hold            | boolean | `false`       | 点击键盘右下角按钮时是否保持键盘不收起                           |
| hold-keyboard           | boolean | `false`       | 输入框聚焦时，点击页面其他地方是否收起键盘   |
| cursor                  | number  |               | 指定 focus 时的光标位置                                      |
| cursor-color            | string  |               | 光标颜色                                                    |
| selection-start         | number  | `-1`          | 光标起始位置，自动聚集时有效，需与 selection-end 搭配使用         |
| selection-end           | number  | `-1`          | 光标结束位置，自动聚集时有效，需与 selection-start 搭配使用       |
| adjust-position         | boolean | `true`        | 键盘弹起时，是否自动上推页面                                  |
| keyboard-type           | string  |               | RN环境特有属性，设置键盘类型                                  |

事件

| 事件名                | 说明                                                                               |
| ---------------------| ---------------------------------------------------------------------------------- |
| input            | 键盘输入时触发，`event.detail = { value, cursor }`，不支持 `keyCode`                     |
| focus            | 输入框聚焦时触发，`event.detail = { value }`，不支持 `height`                            |
| blur             | 输入框失去焦点时触发，`event.detail = { value }`，不支持 `encryptedValue`、`encryptError` |
| confirm          | 点击完成按钮时触发，`event.detail = { value }`                                         |
| selectionchange | 选区改变事件, `event.detail = { selectionStart, selectionEnd }`                      |

### textarea

多行输入框。

属性

| 属性名                   | 类型     | 默认值         | 说明                                                       |
| ----------------------- | ------- | ------------- | ---------------------------------------------------------- |
| value                   | string  |               | 输入框内容                                                   |
| placeholder             | string  |               | 输入框为空时占位符                                            |
| placeholder-class       | string  |               | 指定 placeholder 的样式类，仅支持 color 属性                   |
| placeholder-style       | string  |               | 指定 placeholder 的样式，仅支持 color 属性                    |
| disabled                | boolean | `false`       | 是否禁用                                                    |
| maxlength               | number  | `140`         | 最大输入长度，设置为 -1 的时候不限制最大长度                     |
| cursor-spacing          | number  | `0`           | 指定光标与键盘的距离，单位 px。取 textarea 距离底部的距离和 cursor-spacing 指定的距离的最小值作为光标与键盘的距离 |
| auto-focus              | boolean | `false`       | (即将废弃，请直接使用 focus )自动聚焦，拉起键盘                  |
| focus                   | boolean | `false`       | 获取焦点                                                    |
| auto-height             | boolean | `false`       | 是否自动增高，设置 auto-height 时，style.height不生效          |
| confirm-type            | string  | `return`      | 设置键盘右下角按钮的文字，可选值为 `send`、`search`、`next`、`go`、`done`、`return`                       |
| confirm-hold            | boolean | `false`       | 点击键盘右下角按钮时是否保持键盘不收起                           |
| hold-keyboard           | boolean | `false`       | 输入框聚焦时，点击页面其他地方是否收起键盘  |
| cursor                  | number  |               | 指定 focus 时的光标位置                                      |
| cursor-color            | string  |               | 光标颜色                                                    |
| selection-start         | number  | `-1`          | 光标起始位置，自动聚集时有效，需与 selection-end 搭配使用         |
| selection-end           | number  | `-1`          | 光标结束位置，自动聚集时有效，需与 selection-start 搭配使用       |
| adjust-position         | boolean | `true`        | 键盘弹起时，是否自动上推页面                                  |
| keyboard-type           | string  |               | RN环境特有属性，设置键盘类型                                  |

事件

| 事件名                | 说明                                                                               |
| ---------------------| ---------------------------------------------------------------------------------- |
| input            | 键盘输入时触发，`event.detail = { value, cursor }`，不支持 `keyCode`                     |
| focus            | 输入框聚焦时触发，`event.detail = { value }`，不支持 `height`                            |
| blur             | 输入框失去焦点时触发，`event.detail = { value }`，不支持 `encryptedValue`、`encryptError` |
| confirm          | 点击完成按钮时触发，`event.detail = { value }`                                          |
| linechange       | 输入框行数变化时调用，`event.detail = { height: 0, lineCount: 0 }`，不支持 `heightRpx`    |
| selectionchange | 选区改变事件, `event.detail = {selectionStart, selectionEnd}`                                         |

### progress

进度条。

属性

| 属性名                   | 类型     | 默认值         | 说明                                                       |
| ----------------------- | ------- | ------------- | ---------------------------------------------------------- |
| percent                 | number  | `0`           | 百分比进度，范围0-100                                         |
| stroke-width            | number|string | `6`   | 进度条线的宽度，单位px                                        |
| color                   | string  |               | 进度条颜色（已废弃，请使用 activeColor）                        |
| activeColor             | string  | `#09BB07`     | 已选择的进度条的颜色                                           |
| backgroundColor         | string  | `#EBEBEB`     | 未选择的进度条的颜色                                           |
| active                  | boolean | `false`       | 进度条从左往右的动画                                           |
| active-mode             | string  | `backwards`   | 动画播放模式，`backwards`: 从头开始播放；`forwards`: 从上次结束点接着播放 |
| duration                | number  | `30`          | 进度增加1%所需毫秒数                                          |

事件

| 事件名           | 说明                                                 |
| ----------------| --------------------------------------------------- |
| activeend   | 动画完成时触发，`event.detail = { percent }`            |

> \[!tip] 注意
>
> * 不支持 `show-info` 属性，即不支持在进度条右侧显示百分比
> * 不支持 `border-radius` 属性自定义圆角大小
> * 不支持 `font-size` 属性设置右侧百分比字体大小

### picker-view

嵌入页面的滚动选择器。其中只可放置 [picker-view-column](#picker-view-column) 组件，其它节点不会显示

属性

| 属性名                   | 类型              | 默认值              | 说明                                 |
| ----------------------- | ------------------| ------------------ | ------------------------------------|
| value                   | array\<number>   | `[]`           | 数组中的数字依次表示 picker-view 内的 [picker-view-column](#picker-view-column) 选择的第几项（下标从 0 开始），数字大于 [picker-view-column](#picker-view-column) 可选项长度时，选择最后一项。|
| indicator-style         | string          |                | 设置选择器中间选中框的样式 |
| indicator-class         | string          |                | 设置选择器中间选中框的类名 |
| mask-style              | string          |                | 设置蒙层的样式           |
| mask-class              | string          |                | 设置蒙层的类名           |
| enable-wheel-animation  | boolean         |   `true`       | RN环境特有属性，是否开启滚轮滚动动画效果   |

事件

| 事件名           | 说明                |
| ----------------| ------------------ |
| change      | 滚动选择时触发 change 事件，`event.detail = {value}`，其中 `value` 为数组，表示 picker-view 内的 [picker-view-column](#picker-view-column) 当前选择的是第几项（下标从 0 开始） |

触感反馈回调方法

通过在全局注册 `mpx.config.rnConfig.onPickerVibrate` 方法，在每次滚动选择时会调用该方法。

| 注册触感方法名           | 类型          | 说明                |
| ----------------------| --------------| ------------------- |
| onPickerVibrate         | Function      | 注册自定义触感反馈方法。调用时机：在每次滚动选择时会调用该方法。可以在方法内自定义实现类似 iOS 端原生表盘的振动触感。    |

### picker-view-column

滚动选择器子项。仅可放置于 [picker-view](#picker-view) 中，其孩子节点的高度会自动设置成与 [picker-view](#picker-view) 的选中框的高度一致

### picker

从底部弹起的滚动选择器。

`picker` 节点上的文本样式（如 `color`、`font-size` 等）会透传给触发区域的子节点，用于对齐小程序中父节点文本样式影响子内容的表现。

属性

| 属性名                  | 类型         | 默认值             | 说明                          |
| -----------------------| ------------| ------------------ | -----------------------------|
| mode                   | string      | `selector`         | 选择器类型，目前支持 `selector`、 `multiSelector`、 `time`、 `date`、  `region`   |
| disabled               | boolean     | `false`            | 是否禁用                       |
| header-text            | string      |                    | 头部标题                       |

公共事件

| 事件名           | 说明                                                 |
| ----------------| ----------------------------------------------------|
| cancel      | 取消选择时触发                                         |
| change      | value 改变时触发 change 事件，`event.detail = {value}` |

#### 普通选择器：mode = selector {#mode-selector}

属性

| 属性名                  | 类型                     | 默认值         | 说明                           |
| -----------------------| ------------------------| ------------- | -----------------------------|
| range                  | array\[object]/array     | `[]`          | mode 为 selector 或 multiSelector 时，range 有效 |
| range-key              | string                  | `false`       | 当 range 是一个 Object Array 时，通过 range-key 来指定 Object 中 key 的值作为选择器显示内容 |
| value                  | number                  | 0             | 表示选择了 range 中的第几个（下标从 0 开始）|

#### 多列选择器：mode = multiSelector {#mode-multiselector}

属性与事件

| 属性名                  | 类型                     | 默认值         | 说明                           |
| -----------------------| ------------------------| ------------- | -----------------------------|
| range                  | array\[object]/array     | `[]`          | mode 为 selector 或 multiSelector 时，range 有效 |
| range-key              | string                  | `false`       | 当 range 是一个 Object Array 时，通过 range-key 来指定 Object 中 key 的值作为选择器显示内容 |
| value                  | array                   | `[]`          | 表示选择了 range 中的第几个（下标从 0 开始）|
| columnchange       |        function                 |               | 列改变时触发|

#### 多列选择器：时间选择器：mode = time {#mode-time}

属性

| 属性名                  | 类型                     | 默认值         | 说明                           |
| -----------------------| ------------------------| ------------- | -----------------------------|
| value                  | string                  | `[]`          | 表示选中的时间，格式为"hh:mm" |
| start                  | string                  | `false`       | 表示有效时间范围的开始，字符串格式为"hh:mm" |
| end                    | string                   | `[]`         | 表示有效时间范围的结束，字符串格式为"hh:mm"|

#### 多列选择器：时间选择器：mode = date {#mode-date}

属性

| 属性名                  | 类型                     | 默认值         | 说明                                      |
| -----------------------| ------------------------| ------------- | ------------------------------------------|
| value                  | string                  | `当天`         | 表示选中的日期，格式为"YYYY-MM-DD"            |
| start                  | string                  | `false`       | 表示有效日期范围的开始，字符串格式为"YYYY-MM-DD" |
| end                    | string                   | `[]`         | 表示有效日期范围的结束，字符串格式为"YYYY-MM-DD" |
| fields                 | string                   | `day`        | 有效值 year,month,day，表示选择器的粒度        |

fields 有效值：
| 属性名                  | 说明                     |
| -----------------------| ------------------------ |
| year                   | 选择器粒度为年             |
| month                  | 选择器粒度为月份           |
| day                   | 选择器粒度为天              |

#### 省市区选择器：mode = region {#mode-region}

属性

| 属性名                  | 类型                     | 默认值         | 说明                                      |
| -----------------------| ------------------------| ------------- | ------------------------------------------|
| value                  | array                   | `[]`          | 表示选中的省市区，默认选中每一列的第一个值       |
| custom-item            | string                  |               | 可为每一列的顶部添加一个自定义的项              |
| level                  | string                  | `region`      | 选择器层级                                  |

level 有效值：

| 属性名                  | 说明                     |
| -----------------------| ------------------------ |
| province               | 选省级选择器               |
| city                   | 市级选择器                 |
| region                 | 区级选择器                 |

### switch

开关选择器。

属性

| 属性名                   | 类型     | 默认值         | 说明                                                       |
| ----------------------- | ------- | ------------- | ---------------------------------------------------------- |
| checked		             | boolean  |   `false`     | 是否选中 |
| disabled   | boolean  |     `false`    | 是否禁用	|
| type	  | string  |     `switch`    | 样式，有效值：switch, checkbox		 |
| color		  | string  |     `#04BE02`    | switch 的颜色，同 css 的 color|

事件

| 事件名           | 说明                                                 |
| ----------------| --------------------------------------------------- |
| change       |  点击导致 checked 改变时会触发 change 事件，`event.detail = { value }`   |

### navigator

页面链接。

属性

| 属性名                   | 类型     | 默认值         | 说明                                                       |
| ----------------------- | ------- | ------------- | ---------------------------------------------------------- |
| hover-class	             | string  |    `false`      | 指定按下去的样式类。 |
| hover-start-time   | number  |     `50`    | 按住后多久出现点击态，单位毫秒|
| hover-stay-time	  | number  |     `400`    | 手指松开后点击态保留时间，单位毫秒	 |
| open-type		  | string  |     `navigate`    | 可支持`navigateBack`、`redirect`、`switchTab`、`reLaunch`、`navigateTo`|
| url		  | string  |       |  跳转链接	|
| delta		  | number  |       |  当 open-type 为 'navigateBack' 时有效，表示回退的层数	|

### rich-text

富文本。

属性

| 属性名                   | 类型     | 默认值         | 说明                                                       |
| ----------------------- | ------- | ------------- | ---------------------------------------------------------- |
| nodes			             | array|string  |    \[]     | 节点列表 |

### canvas

画布。

事件

| 属性名                   | 说明                                                       |
| -----------------------| ---------------------------------------------------------- |
| touchstart	  | 手指触摸动作开始		|
| touchmove	   | 手指触摸后移动		|
| touchend	  | 手指触摸动作结束	|
| touchcancel	  | 手指触摸动作被打断	|
| longtap    | 手指长按 350ms 之后触发	|
| error	    | 当发生错误时触发 error 事件， `detail = {errMsg}`	|

API

方法名                     | 说明  |
| ----------------------- | ------- |
| createImage	     |  创建一个图片对象。 仅支持在 2D Canvas 中使用	|
| createImageData	      | 创建一个 ImageData 对象。仅支持在 2D Canvas 中使用		|
| getContext	      | 该方法返回 Canvas 的绘图上下文。仅支持在 2D Canvas 中使用	|
| toDataURL	      | 返回一个包含图片展示的 data URI	|

> \[!tip] 注意
>
> * canvas 组件目前仅支持 2D 类型，不支持 webgl
> * 通过 Canvas.getContext('2d') 接口可以获取 CanvasRenderingContext2D 对象，具体接口可以参考 [HTML Canvas 2D Context](https://developer.mozilla.org/en-US/docs/Web/API/CanvasRenderingContext2D) 定义的属性、方法
> * canvas 的实现主要借助于 PostMessage 方式与 webview 容器通信进行绘制，所以对于严格依赖方法执行时机的场景，如调用 drawImage 绘图，再通过 getImageData 获取图片数据的场景，调用时需要使用 await 等方式来保证方法的执行时机
> * 通过 Canvas.createImage 画图，图片的链接不能有特殊字符，安卓手机可能会 load 失败

### video

视频

属性

| 属性名                   | 类型     | 默认值         | 说明                                                       |
| ----------------------- | ------- | ------------- | ---------------------------------------------------------- |
| src	    | string  |               | 要播放视频的资源地址或本地静态资源相对路径 |
| controls	    | boolean  |     `true`         | 是否显示默认播放控件|
| autoplay	    | boolean  |   `false`  | 是否自动播放|
| loop	    | boolean  |       `false`        | 是否循环播放	|
| muted	    | boolean  |        `false`       | 是否静音播放|
| initial-time	    | number  |     `0`          | 指定视频初始播放位置|
| object-fit  | string  |      `contain`         | 当视频大小与 video 容器大小不一致时，视频的表现形式|
| poster	    | string  |               | 视频封面的图片地址|
| enable-auto-rotation	    | boolean  |         `false`      | 是否开启手机横屏时自动全屏，当系统设置开启自动旋转时生效，仅 ios 支持|
| preferred-peak-bit-rate	    | number  |        `0`      | 指定码率上界，单位为比特每秒|
| is-drm	    | boolean  |         `false`      | 是否为 drm 视频|
| provision-url	    | string  |               | android 环境特有属性，drm 视频的 provision url|
| certificate-url	    | string  |               | ios 环境特有属性，drm 视频的 certificate url|
| license-url	    | string  |               | drm 视频的 license url|

事件

| 事件名           | 说明                                                 |
| ----------------| --------------------------------------------------- |
| play       |  当开始/继续播放时触发play事件   |
| pause       |  当暂停播放时触发 pause 事件	   |
| ended       |  当播放到末尾时触发 ended 事件   |
| timeupdate       |  播放进度变化时触发，`event.detail = {currentTime, duration}`   |
| fullscreenchange       |  视频进入和退出全屏时触发，`event.detail = {fullScreen` }   |
| waiting       |  视频出现缓冲时触发   |
| error       |  视频播放出错时触发	   |
| loadedmetadata       |  视频元数据加载完成时触发。`event.detail = {width, height, duration}`   |
| controlstoggle       |  切换 controls 显示隐藏时触发。`event.detail = {show}`	   |
| seekcomplete       |  seek 完成时触发    |

> \[!tip] 注意
>
> * 手动拖拽进度条场景，bindseekcomplete 事件，android 可以触发，ios 不支持
> * video 组件基于第三方库 `react-native-video` 来实现，需要容器中安装此依赖包

### web-view

承载网页的容器。会自动铺满整个 RN 页面

属性

| 属性名                   | 类型     | 默认值         | 说明                                                       |
| ----------------------- | ------- | ------------- | ---------------------------------------------------------- |
| src	    | string  |               | webview 指向网页的链接，如果需要对跳转的URL设定白名单可跳转，需要在业务跳转之前处理该逻辑

事件

| 属性名                   | 说明                                                       |
| ---------------------| ---------------------------------------------------------- |
| message	   |  网页向RN通过 postMessage 传递数据
| load	    |  网页加载成功时候触发此事件
| error	     |  网页加载失败的时候触发此事件

> \[!tip] 注意
>
> * 被打开的 H5 页面需使用`@mpxjs/webview-bridge@2.9.68` 及以上版本与 RN 容器进行通信，具体通信方式参见[Webview API](#webview-api)

### root-portal

使整个子树从页面中脱离出来，类似于在 CSS 中使用 position: fixed 的效果。主要用于制作弹窗、弹出层等。
属性

| 属性名                   | 类型     | 默认值         | 说明                                                       |
| ----------------------- | ------- | ------------- | ---------------------------------------------------------- |
| enable   | boolean           |   `true`	     | 是否从页面中脱离出来

> \[!tip] 注意
>
> * style 样式不支持中使用百分比计算、css variable

### sticky-section

吸顶布局容器，仅支持作为 `<scroll-view>` 的直接子节点

> \[!tip] 注意
>
> * sticky-section 目前仅支持 RN 、web 以及微信小程序环境，其他环境暂不支持。微信小程序中使用需开启 skyline 渲染模式

### sticky-header

吸顶布局容器，仅支持作为 `<scroll-view>` 的直接子节点或 `sticky-section` 组件直接子节点

属性

| 属性名                   | 类型     | 默认值         | 说明                                                       |
| ----------------------- | ------- | ------------- | ---------------------------------------------------------- |
| offset-top	    | number  |    `0`      | 吸顶时与顶部的距离 |
| padding	    | array  |     `[0, 0, 0, 0] `         | 长度为 4 的数组，按 top、right、bottom、left 顺序指定内边距 |

事件

| 事件名           | 说明                                                 |
| ----------------| --------------------------------------------------- |
| stickontopchange      |  吸顶状态变化事件, `event.detail = { isStickOnTop }`，当 sticky-header 吸顶时为 true，否则为 false   |

> \[!tip] 注意
>
> * sticky-header 目前仅支持 RN 、web 以及微信小程序环境，其他环境暂不支持。微信小程序中使用需开启 skyline 渲染模式
> * RN 环境的 sticky-header 更适用于内容稳定，状态不常变更的场景使用，目前如果 sticky 还在动画过程中就触发组件更新（如在bindstickontopchange 回调中立刻更新 state）、scroll-view 内容高度由多变少、通过修改 scroll-into-view、scroll-top 让 scroll-view 滚动，以上场景在安卓上都可能会导致闪烁或抖动

### cover-view

视图容器。
功能同 [view 组件](#view)，在 cover-view 中只能嵌套 cover-view 或 cover-image 组件。

### cover-image

视图容器。
功能同 [image 组件](#image)

## 自定义组件 {#custom-component}

Mpx 完全支持自定义组件功能，组件创建、属性配置、生命周期、插槽使用等更多组件开发的详细指南和高级用法，请参考 [自定义组件基础文档](../basic/component.md)。

本节重点介绍在 RN 环境下的特殊注意事项和限制。

### 组件属性配置 {#component-props-config}

| 属性 | 支持状态 | 说明 |
|------|---------|------|
| properties | ✅ 完全支持 | 组件外部属性声明 |
| data | ✅ 完全支持 | 组件内部数据 |
| computed | ✅ 完全支持 | 计算属性 |
| watch | ✅ 完全支持 | 数据监听 |
| observers | ✅ 完全支持 | 数据变化监听器 |
| methods | ✅ 完全支持 | 组件方法定义 |
| mixins | ✅ 完全支持 | 混入选项 |
| externalClasses | ⚠️ 需要配置 | 外部样式类，需配置[构建选项](../../api/compile.md#externalclasses) |
| behaviors | ❌ 不支持 | 小程序 behaviors 机制 |
| options | ❌ 不支持 | 组件选项（multipleSlots、virtualHost 等）|
| relations | ❌ 不支持 | 组件关系定义 |

### 生命周期钩子 {#lifecycle-hooks}

| 生命周期 | 支持状态 | 说明 |
|---------|---------|------|
| created | ✅ 完全支持 | 组件实例创建 |
| attached | ✅ 完全支持 | 组件挂载到页面 |
| ready | ✅ 完全支持 | 组件布局完成 |
| detached | ✅ 完全支持 | 组件从页面卸载 |
| lifetimes | ✅ 完全支持 | 生命周期声明对象 |
| pageLifetimes | ✅ 完全支持 | 页面生命周期（show、hide、resize）|

### 实例属性和方法 {#instance-props-methods}

| 功能 | 支持状态 | 说明 |
|------|---------|------|
| id, dataset | ✅ 完全支持 | 节点基础属性 |
| setData | ✅ 完全支持 | 数据更新方法 |
| triggerEvent | ✅ 完全支持 | 事件触发 |
| createSelectorQuery | ✅ 有限制 | 返回一个 SelectorQuery 对象实例，用以查询基础节点或非 virtualHost 自定义组件 host 节点的位置等属性，需配合 `wx:ref` 使用 |
| selectComponent | ✅ 有限制 | 在父组件当中获取子组件的实例对象，返回匹配到的第一个组件实例，需配合 `wx:ref` 使用 |
| selectAllComponents | ✅ 有限制 | 在父组件当中获取子组件的实例对象，返回匹配到的全部组件实例对象组成的数组，需配合 `wx:ref` 使用 |
| $set, $watch, $delete | ✅ 完全支持 | 响应式数据操作 |
| $refs, $forceUpdate, $nextTick | ✅ 完全支持 | 组件实例方法 |
| $rawOptions | ✅ 完全支持 | 原始选项访问 |
| $i18n | ✅ 完全支持 | 国际化访问器 |
| is | ✅ 完全支持 | 动态组件 |

#### selectComponent / selectAllComponents 使用要点 {#select-component-usage}

在 RN 环境下使用 `selectComponent` 或 `selectAllComponents` 时

1. 必须在目标节点上标记 `wx:ref`
2. 选择器支持范围有限，仅支持以下方式

* id 选择器 `#id`
* class 选择器 `.class` 或连续指定 `.a-class.b-class.c-class`

`createSelectorQuery().select()` / `selectAll()` 使用同样的 selector 映射规则。目标是基础组件时返回该基础节点信息；目标是自定义组件时，返回该组件实体 host 节点的信息。配置为 `virtualHost` 的组件没有实体 host 节点，因此不会被组件节点测量命中。

```html
<template>
  <!-- 必须添加 wx:ref 标记 -->
  <list wx:ref class="list"></list>
  <card wx:ref id="card"></card>
</template>

<script>
    import { createComponent } from '@mpxjs/core'

  createComponent({
    ready() {
      // 获取组件实例
      const instance = this.selectComponent('.list')
      console.log('selectComponent', instance)

      // 测量自定义组件的实体 host 节点
      this.createSelectorQuery()
        .select('#card')
        .boundingClientRect()
        .exec(([rect]) => {
          console.log('card rect', rect)
        })
    }
  })
</script>
```

---

---
url: /guide/rn/template.md
---
# 模板语法与生命周期 {#template-syntax-lifecycle}

本节介绍 Mpx RN 环境下的模板语法和生命周期支持。

### 目录概览 {#directory-overview}

* **[模板指令](#template-directives)** - 条件渲染、列表渲染、动态绑定等模板指令的使用
* **[事件](#events)** - 事件绑定、冒泡捕获、内联传参等事件机制
* **[生命周期](#lifecycle)** - 组件生命周期钩子的支持情况

## 模板指令 {#template-directives}

### 支持范围 {#support-scope}

在 React Native 环境下，Mpx 目前支持以下模板指令。详细的指令使用方法请参考 [模板指令 API 文档](../../api/directives.md)。

#### 基础模板指令 {#basic-template-directives}

| 指令 | 支持状态 | 说明 |
|------|---------|------|
| [wx:if](/api/directives.html#wx-if) | ✅ | 条件渲染 |
| [wx:else](/api/directives.html#wx-else) | ✅ | 条件渲染 |
| [wx:elif](/api/directives.html#wx-elif) | ✅ | 条件渲染 |
| [wx:show](/api/directives.html#wx-show) | ✅ | 显示/隐藏控制 |
| [wx:for](/api/directives.html#wx-for) | ✅ | 列表渲染 |
| [wx:for-item](/api/directives.html#wx-for-item) | ✅ | 指定循环项变量名 |
| [wx:for-index](/api/directives.html#wx-for-index) | ✅ | 指定循环索引变量名 |

#### 增强模板指令 {#enhanced-template-directives}

| 指令 | 支持状态 | 说明 |
|------|---------|------|
| [wx:class](/api/directives.html#wx-class) | ✅ | 动态类名绑定 |
| [wx:style](/api/directives.html#wx-style) | ✅ | 动态样式绑定 |
| [wx:model](/api/directives.html#wx-model) | ✅ | 双向数据绑定 |
| [wx:model-prop](/api/directives.html#wx-model-prop) | ✅ | 双向绑定属性 |
| [wx:model-event](/api/directives.html#wx-model-event) | ✅ | 双向绑定事件 |
| [wx:model-value-path](/api/directives.html#wx-model-value-path) | ✅ | 双向绑定数据路径 |
| [wx:model-filter](/api/directives.html#wx-model-filter) | ✅ | 双向绑定过滤器 |
| [wx:ref](/api/directives.html#wx-ref) | ⚠️ | 获取基础组件节点或自定义组件实例，RN 环境选择器受限 |

#### 条件编译指令 {#conditional-compile-directives}

| 指令 | 支持状态 | 说明 |
|------|---------|------|
| [@mode](../../api/directives.md#mode) | ✅ | 平台条件编译 |
| [@\_mode](/api/directives.html#mode-1) | ✅ | 平台条件编译（保留转换能力）|
| [@env](../../api/directives.md#env) | ✅ | 自定义环境条件编译 |
| [mpxTagName](../../api/directives.md#mpxtagname) | ✅ | 动态标签名 |

### 特殊说明 {#special-notes}

#### wx:ref 使用注意事项 {#wx-ref-notes}

在 RN 环境下使用 `wx:ref` 时需要注意选择器功能的限制：

* 选择器仅支持 id 选择器（`#id`）和 class 选择器（`.class`）
* `createSelectorQuery().select()` / `selectAll()` 命中自定义组件时，返回该组件实体 host 节点的信息；`virtualHost` 组件没有实体 host 节点，不支持按组件节点测量

```html
<template>
  <!-- 基础组件 -->
  <view wx:ref="tref">123</view>
  <!-- 自定义组件 -->
  <test-component wx:ref="cref"></test-component>
  <test-component id="card" wx:ref></test-component>
</template>

<script>
import { createPage } from "@mpxjs/core"

createPage({
  ready() {
    // 基础节点 nodeRef 获取节点信息
    this.$refs.tref.fields({size: true}, function (res) {
      console.log(res)
    }).exec()
    
    // 获取自定义组件实例，调用组件方法
    this.$refs.cref.show()

    // 测量自定义组件的实体 host 节点
    this.createSelectorQuery()
      .select("#card")
      .boundingClientRect()
      .exec(([rect]) => {
        console.log(rect)
      })
  }
})
</script>
```

## 事件 {#events}

在 React Native 环境下，Mpx 目前支持以下事件编写规范。

普通事件绑定

```js
<view bindtap="handleTap">
    Click here!
</view>
```

绑定并阻止事件冒泡

```js
<view catchtap="handleTap">
    Click here!
</view>
```

事件捕获

```js
<view capture-bind:touchstart="handleTap1">
  outer view
  <view capture-bind:touchstart="handleTap2">
    inner view
  </view>
</view>
```

中断捕获阶段和取消冒泡阶段

```js
<view capture-catch:touchstart="handleTap1">
  outer view
</view>

```

在此基础上也新增了事件处理内联传参的增强机制。

```html
<template>
 <!--Mpx增强语法，模板内联传参，方便简洁-->
 <view bindtap="handleTapInline('inline')">内联传参</view>
 </template>
 <script setup>
  // 直接通过参数获取数据，直观方便
  const handleTapInline = (params) => {
    console.log('params:', params)
  }
  // ...
</script>
```

除此之外，Mpx 也支持了动态事件绑定

```html
<template>
 <!--动态事件绑定-->
 <view wx:for="{{items}}" bindtap="handleTap_{{index}}">
  {{item}}
</view>
 </template>
 <script setup>
  import { ref } from '@mpxjs/core'

  const items = ref(['Item 1', 'Item 2', 'Item 3', 'Item 4'])
  const handleTap_0 = (event) => {
    console.log('Tapped on item 1');
  },

  const handleTap_1 = (event) => {
    console.log('Tapped on item 2');
  },

  const handleTap_2 = (event) => {
    console.log('Tapped on item 3');
  },

  const handleTap_3 = (event) => {
    console.log('Tapped on item 4');
  }
</script>
```

更多事件相关内容可以查看 [Mpx 事件处理](../basic/event.md)

注意事项

1. 仅 `tap`、`longpress`、`touchstart`、`touchmove`、`touchend`、`touchcancel` 事件支持阻止冒泡和捕获，其他事件使用 `catch`、`capture-bind` 或 `capture-catch` 时，编译器会给出警告并降级为普通 `bind` 绑定。
2. `tap` 和 `longpress` 由 `touchstart` / `touchend` 等底层触摸事件模拟实现，因此子组件绑定 `catchtouchend` 后，父组件的 `tap` 事件不会响应。
3. 当使用了事件委托想获取 e.target.dataset 时，只有点击到文本节点才能获取到，点击其他区域无效。建议直接将事件绑定到事件触发的元素上，使用 e.currentTarget 来获取 dataset 等数据。
4. 如果元素上设置了 opacity: 0 的样式，会导致 ios 事件无法响应。

## 生命周期 {#lifecycle}

RN 环境支持 Mpx 除 SSR 外所有生命周期钩子，关于生命周期的完整说明和最佳实践，请参考 [**生命周期详细文档**](../basic/lifecycle.md)。

---

---
url: /guide/rn/style.md
---
# 跨端样式 {#cross-platform-style}

本节提供 Mpx RN 环境下的样式开发完整说明，涵盖样式语法、处理机制和属性支持。

### 目录概览 {#directory-overview}

* **样式处理机制**：编译时和运行时的样式转换处理
* **基础语法**：CSS 选择器、样式单位、色值格式的支持说明
* **样式继承**：文本样式在 RN 环境下的继承规则和平台差异
* **增强功能**：简写属性、CSS 函数（`var()`、`calc()`、`env()`）等 Mpx 增强支持
* **属性参考**：详细的样式属性支持列表和使用说明

### 平台差异背景 {#platform-diff-background}

RN 样式属性和 Web/小程序中 CSS 样式属性是相交关系：

* **RN 独有属性**：`tintColor`、`writingDirection` 等，CSS 不支持
* **CSS 独有属性**：`clip-path`、`animation` 等，RN 不支持

因此，在跨平台开发时：

1. **优先使用交集属性**：尽量使用两边都支持的样式属性
2. **框架抹平差异**：Mpx 内部对 RN 样式进行了部分抹平处理

## 样式处理机制 {#style-processing-mechanism}

Mpx 框架在样式处理方面的工作分为两大类：

### 编译时的 class 类样式转化 {#compile-class-transform}

* ✅ 属性名转驼峰
* ✅ 单位的校验和对齐
* ✅ 过滤 RN 不支持的属性和属性值
* ✅ 简写转换
* ✅ 样式属性差异转换和拉齐

### 运行时的 style 样式处理 {#runtime-style-process}

* ✅ 属性名转驼峰
* ✅ 单位的计算和处理
* ✅ 100% 计算
* ✅ CSS 函数处理：`env()`、`calc()`、`var()`

## CSS 选择器 {#css-selectors}

RN 环境下仅支持**单类选择器**、**page选择器**、**:host选择器**，不支持类名组合选择器，不过逗号组合的选择器本质上还是单类选择器，是可以支持的。

```css
/* ✅ 支持的选择器 */
.classname {
  color: red;
}

.classA, .classB {
  color: red;
}

page {
   color: red
}

:host {
   color: red
}

/* ❌ 不支持的选择器 */
view, text {
  color: red;
}

.classA .classB {
  color: red;
}
```

## 样式单位 {#style-units}

Mpx 转 RN 支持以下单位，部分单位在特定情况下存在使用限制。

### 数值类型单位 {#numeric-units}

| 单位 | 支持情况 | 特殊说明 |
|------|---------|----------|
| `%` | ✅ 支持 | 百分比单位参考 [百分比单位说明](#percentage-unit-explanation) |
| `px` | ✅ 支持 | 绝对像素单位 |
| `rpx` | ✅ 支持 | 响应式像素，根据屏幕宽度动态计算 |
| `vh` | ✅ 支持 | 相对于视口的高度 |
| `vw` | ✅ 支持 | 相对视口的宽度 |

> \[!tip] vh 单位使用注意
>
> * **问题**：使用系统默认导航栏时，`vh` 的计算基准可能会发生变化
>   * 页面首次加载：`100vh = 屏幕总高度`
>   * 状态更新后：`100vh = 屏幕高度 - 导航栏高度`
>
> * **影响**：可能导致布局在运行时突然变化
>
> * **建议**：如需使用 `vh` 单位，推荐配合自定义导航栏使用，以确保计算基准始终一致

### 百分比单位说明 {#percentage-unit-explanation}

RN 原生较多属性不支持百分比，或对百分比的支持存在 bug（如 `font-size`、`translate` 等），但这些属性在编写 Web/小程序代码时使用较多，所以框架进行了抹平支持。

以下属性在 Mpx 输出 RN 时专门进行了百分比单位的适配：

#### 百分比计算规则 {#percentage-calculation-rules}

##### font-size

`font-size` 百分比会在文本样式透传阶段解析，计算基准按以下优先级获取：当前已解析的 `font-size`、继承文本样式中的 `font-size`，若都不存在则使用 `16` 作为默认字号基准。

```html
<view style="font-size: 16px;">
  <text style="font-size: 120%;">文本内容</text>
</view>
```

> \[!tip] 注意事项
>
> 当容器或 `text` 节点已通过文本样式继承拿到明确字号时，本地 `font-size` 百分比会优先基于继承字号计算；没有可继承字号时按默认字号 `16` 计算。

##### line-height

和 Web/小程序类似，当设置 `line-height: 120%` 或在 `font` 简写中设置 `font: 16px / 1.5 Arial` 时，实际都按百分比计算。

`line-height` 的百分比计算基准是最终文本节点合并后的 `font-size`；没有当前字号时，会继续使用继承字号或默认字号 `16`。因此同一段继承链内混合不同字号时，相同的相对 `line-height` 会在每个最终 `text` 节点上得到不同的 RN `lineHeight` 数值。

```css
.text {
  font-size: 16px;
  line-height: 150%;
}
```

> \[!tip] 注意事项
>
> 设置 `line-height` 时要注意区分值类型：
>
> * RN 运行时中的数值型 `lineHeight` 会作为绝对行高保留，不会再按字号倍数放大
> * 如需表达相对行高，优先使用百分比，或在 `font` 简写中使用 `/ 1.5` 这类 unit-less line-height；这类相对值会保留到最终文本节点再按该节点字号计算

##### gap / row-gap / column-gap

RN 原生要求 `gap` / `row-gap` / `column-gap` 最终为数值，Mpx 会在运行时将百分比换算为数值。

```html
<view parent-width="{{ 300 }}" parent-height="{{ 400 }}" style="gap: 10% 20%;">
  内容
</view>
```

> \[!tip] 注意事项
>
> * `row-gap` 百分比基于父节点高度计算，需要传入 `parent-height`
> * `column-gap` 百分比基于父节点宽度计算，需要传入 `parent-width`
> * `gap` 单值会同时作用于行列间距，并分别按上述基准计算

##### 根据自身宽高计算百分比 {#calc-percent-by-self}

`translateX`、`translateY`、`border-radius` 的百分比都是根据自身宽高来计算的。

```css
.self-based {
  transform: translateX(50%); /* 基于自身宽度 */
  transform: translateY(30%); /* 基于自身高度 */
  border-radius: 10%; /* 基于自身宽度 */
}
```

> \[!tip] 注意事项
>
> * **计算基准**：
>   * `translateX`、`border-radius` 基于节点的 `width` 计算
>   * `translateY` 基于节点的 `height` 计算
>   * `border-radius-*`（top/right/bottom/left）计算逻辑与 `border-radius` 一致
> * **生效时机**：需要在完成渲染后通过 `onLayout` 获取自身宽高，故属性设置在第一次 `onLayout` 后生效
> * **动画限制**：动画执行不会触发 `onLayout`，不建议在动画中使用这些属性的百分比

##### 根据父节点宽高计算百分比 {#calc-percent-by-parent}

除上述特殊规则外，`width`、`left`、`right`、`height`、`top`、`bottom`、`margin`、`padding` 等属性设置百分比时的计算基准都是父节点的宽高。RN 原生默认支持这些属性的百分比设置，无需框架额外处理。

**例外情况**：在 `calc()` 函数表达式中使用百分比，如 `width: calc(100% - 10px)`，这种情况是需要框架额外处理的。

###### calc() 函数内的百分比使用方式 {#calc-percentage-usage}

在 `calc()` 函数表达式内使用百分比时，需要开发者设置 `parent-width` 或 `parent-height` 属性：

* **基于父节点高度计算**：`height`、`top`、`bottom` 需要传入 `parent-height` 属性
* **基于父节点宽度计算**：`width`、`left`、`right` 需要传入 `parent-width` 属性

```html
<view parent-width="{{ 300 }}" style="width: calc(100% - 20px);">内容</view>
<view parent-height="{{ 400 }}" style="height: calc(80% + 10px);">内容</view>
```

> \[!tip] 💡 注意
>
> 属性计算基准遵循：**纵向以高度为基准，横向以宽度为基准**

### 色值类型支持 {#color-value-support}

支持以下颜色值格式：

| 格式类型 | 说明 | 示例 |
|----------|------|------|
| **Named Color** | 预定义颜色名称 | `red`、`blue`、`orange` |
| **Hex Color** | 十六进制颜色 | `#090`、`#009900`、`#090a` |
| **RGB/RGBA** | RGB/RGBA 函数 | `rgb(34, 12, 64)`、`rgba(34, 12, 64, 0.6)` |
| **HSL/HSLA** | HSL/HSLA 函数 | `hsl(30, 100%, 50%)`、`hsla(30, 100%, 50%, 0.6)` |
| **HWB** | HWB 函数 | `hwb(90 10% 10%)`、`hwb(90 10% 10% / 0.5)` |
| **Color Ints** | RN 特有格式 | `0xff00ff00` |

> **📖 参考文档**
>
> 更多颜色名称请参考：[React Native 颜色枚举值](https://reactnative.dev/docs/colors#named-colors)

## 文本样式继承 {#text-style-inheritance}

### 平台差异 {#platform-diff}

| 平台 | 文本节点处理 | 样式设置 |
|------|-------------|----------|
| **Web/小程序** | `div`/`view` 可直接包裹文本 | 可在容器节点上设置文本样式 |
| **React Native** | 必须通过 `Text` 创建文本节点 | [文本样式属性](https://reactnative.dev/docs/text-style-props) 只能设置给 `Text` 节点 |

### Mpx 抹平机制 {#mpx-flatten-mechanism}

Mpx 框架抹平了平台差异：

* ✅ 可以使用 `view` 节点直接包裹文本
* ✅ 可以在 `view` 等容器节点上设置文本样式，作用到其 Mpx 子树中的 `text` 节点
* ✅ 可以将容器上的 RN 文本截断属性迁移到最近的 `text` 节点

### 继承规则 {#inheritance-rule}

RN 原生文本样式只在 `<Text>` 子树内有限继承。Mpx RN 运行时会额外维护文本样式透传上下文，用于模拟 Web/小程序中容器文本样式向子树文本节点透传的行为。

Mpx 的文本相关能力主要分为以下几类：

1. **文本样式继承**：容器节点上的文本样式会透传到 Mpx 子树中的 `text` 节点，中间存在非 text 的 Mpx 组件时不会中断。
2. **text 嵌套继承**：父级 `text` 节点的文本样式会继续传递给嵌套的子 `text` 节点。
3. **文本属性迁移**：`numberOfLines`、`ellipsizeMode` 不是继承属性，只会从容器迁移到最近的 `text` 节点；被该 `text` 消费后，不会继续传给更深层的子 `text`。
4. **全局字体缩放**：`allowFontScaling` 不参与继承或迁移，默认值由 `mpx.config.rnConfig.allowFontScaling` 控制，组件显式设置的 `allowFontScaling` 优先。
5. **自动包裹**：`view` 节点直接包裹裸文本时，Mpx 编译时会自动添加 `text` 节点包裹文本。

本地文本样式中的 `font-size` 百分比会在文本透传阶段基于继承字号解析为确定字号；`line-height` 百分比和 `font` 简写中的 unit-less line-height 会保留到每个最终 `text` 节点消费时，再按该节点合并后的 `font-size` 解析。祖先透传下来的文本样式只作为继承值和字号基准，不会在子节点重复执行 CSS 变量、`calc()`、`font` 简写等转换。

> 出于性能考虑，文本样式透传采用按需启用策略。容器会在首次渲染时根据文本样式和 `numberOfLines`、`ellipsizeMode` 等文本属性决定是否订阅透传上下文；如果这些样式或属性后续可能通过动态数据才出现，需要在该容器上显式声明 `enable-text-pass-through="{{ true }}"`。

### 示例 {#example}

```html
<!-- 示例代码 -->
<view class="wrapper">
   文本1
   <view><text>文本2</text></view>
   <view class="content"><view><text>文本3</text></view></view>
   <text class="content"><text>文本4</text></text>
</view>
```

```css
.wrapper {
    font-size: 20px;
}
.content {
    text-align: right;
}
```

#### 渲染效果对比 {#render-effect-compare}

| 文本 | Web/小程序 | React Native |
|------|------------|--------------|
| 文本1 | 20px | 20px |
| 文本2 | 20px | 20px |
| 文本3 | 20px，居右 | 20px，居右 |
| 文本4 | 20px，居右 | 20px，居右 |

### 文本属性迁移 {#text-props-transfer}

`numberOfLines`、`ellipsizeMode` 在 RN 中只能设置到 `Text` 节点。Mpx 会将这些属性从容器迁移到最近的 `text` 节点，用于支持 Web/小程序中常见的“在容器上描述文本溢出”的写法。

```html
<view numberOfLines="1" ellipsizeMode="tail">
  <view>
    <text>这段文本会单行截断</text>
  </view>
</view>
```

这些属性不会深度继承：

```html
<view numberOfLines="1">
  <text>
    第一层 text 会消费 numberOfLines
    <text>第二层 text 不会继续继承 numberOfLines</text>
  </text>
</view>
```

如需控制 RN 文本是否跟随系统字体缩放，可以配置全局默认值：

```js
import mpx from '@mpxjs/core'

mpx.config.rnConfig = Object.assign({}, mpx.config.rnConfig, {
  allowFontScaling: true
})
```

组件上显式传入的 `allowFontScaling` 优先级高于全局配置。

## 简写样式属性 {#shorthand-style-properties}

Mpx 对通过 `class` 类定义的样式会按照 RN 的样式规则进行编译处理，其中最重要的功能是将 RN 不支持的简写属性转换成 RN 支持的多属性结构。

### 支持的简写属性 {#supported-shorthand-properties}

| 属性类型 | 简写属性 |
|----------|----------|
| **文本相关** | `text-shadow`、`text-decoration`、`font` |
| **布局相关** | `flex`、`flex-flow` |
| **间距相关** | `margin`、`padding`、`gap` |
| **定位相关** | `inset` |
| **背景相关** | `background`（支持 `background-position / background-size`） |
| **阴影相关** | `box-shadow` |
| **边框相关** | `border-radius`、`border-width`、`border-color`、`border`、`outline` |
| **方向边框** | `border-top`、`border-right`、`border-bottom`、`border-left` |

### 示例 {#example-1}

```css
/* 简写属性示例 */
.shorthand-example {
  /* 边距简写 */
  margin: 10px 20px;        /* 转换为 marginTop, marginRight, marginBottom, marginLeft */
  padding: 15px;            /* 转换为 paddingTop, paddingRight, paddingBottom, paddingLeft */
  gap: 20px 10px;           /* 转换为 rowGap, columnGap */
  inset: 0;                 /* 单值透传给 RN */
  inset: 0 10px;            /* 多值转换为 top, right, bottom, left */
  
  /* 边框简写 */
  border: 1px solid red;    /* 转换为 borderWidth, borderStyle, borderColor */
  border-radius: 5px;       /* 转换为各个角的 borderRadius */
  outline: 1px solid red;   /* 转换为 outlineWidth, outlineStyle, outlineColor */
  
  /* 弹性布局简写 */
  flex: 1 0 auto;           /* 转换为 flexGrow, flexShrink, flexBasis */

  /* 字体简写 */
  font: italic bold 16px / 1.5 Arial; /* 转换为 fontStyle, fontWeight, fontSize, lineHeight, fontFamily */
}
```

### 使用限制 {#usage-limitations}

> \[!tip] 编译时 vs 运行时
>
> * ✅ **class 类样式**：编译时会自动展开 RN 不支持的简写属性
> * ✅ **style 属性**：运行时会自动展开受支持的简写属性
>
> **CSS 变量限制**
>
> * ❌ 简写属性不支持单个 `var()` 函数，编译时会报错并原样返回
> * ✅ 多个 `var()` 函数会按顺序赋值给各个属性
>
> ```css
> /* ❌ 错误用法 */
> .error {
>   margin: var(--spacing);  /* 会报错，可能会导致 RN 运行时错误 */
> }
>
> /* ✅ 正确用法 */
> .correct {
>   margin: var(--top) var(--right) var(--bottom) var(--left);
> }
> ```

## CSS 函数 {#css-functions}

### var() 函数 {#var-function}

`var()` 函数可以插入自定义属性（CSS 变量）的值，用来代替属性值。

```css
/* 定义变量：以 -- 开头 */
:root {
  --main-color: #3498db;
  --spacing: 16px;
}

/* 使用变量：通过 var() 函数 */
.component {
  color: var(--main-color);
  margin: var(--spacing);
}
```

#### 语法 {#syntax}

```css
var(<custom-property-name>, <fallback-value>?)
```

* **第一个参数**：要替换的自定义属性名称
* **第二个参数**：可选的回退值，当自定义属性无效时使用

#### 使用示例 {#usage-example}

```vue
<template>
  <view class="component">
    <view class="header">Header</view>
    <view class="content">Content</view>
    <view class="footer">Footer</view>
  </view>
</template>

<style>
  .component {
    --content-color: #b58df1;
    --header-color: pink;
  }

.header {
  background-color: var(--header-color, blue);    /* 使用 pink */
  }

.content {
  background-color: var(--content-color, black);  /* 使用 #b58df1 */
  }

.footer {
  background-color: var(--footer-color, black);   /* 使用 black（回退值） */
  }
</style>
```

#### 渲染效果 {#render-effect}

| 元素 | 背景色 | 说明 |
|------|--------|------|
| Header | `pink` | 使用定义的 `--header-color` |
| Content | `#b58df1` | 使用定义的 `--content-color` |
| Footer | `black` | `--footer-color` 未定义，使用回退值 |

#### 注意事项 {#notes}

> \[!tip] 使用限制
>
> * **回退值逗号**：回退值允许包含逗号，如 `var(--foo, red, blue)` 会将 `red, blue` 作为完整回退值（在第一个逗号之后到函数结尾前的值都会被认为是回退值）
> * **使用场景**：`var()` 函数只能作为属性值使用，不能用作属性名或选择器

### calc() 函数 {#calc-function}

`calc()` 函数允许在声明 CSS 属性值时执行数学计算，使用表达式的结果作为最终值。

#### 语法 {#syntax-1}

```css
calc(expression)
```

表达式采用标准数学运算法则，支持四则运算：`+`、`-`、`*`、`/`

#### 运算规则 {#calculation-rules}

| 运算符 | 要求 | 说明 |
|--------|------|------|
| `+`、`-` | **两边必须有空格** | 加法和减法运算 |
| `*`、`/` | **至少一边是数字** | 乘法和除法运算 |

> \[!tip] 注意
>
> * **乘法运算**：乘数中至少有一个必须是 `number`
> * **除法运算**：除数（`/` 右边的数）必须是 `number`
> * **空格要求**：`+` 和 `-` 运算符两边必须有空格，\* 和 / 这两个运算符前后不需要空格，但考虑到统一性，仍然推荐加上空格
> * **单位支持**：所有能数值化的单位都支持 `calc()` 函数

#### 使用示例 {#usage-example-1}

```css
/* 基本用法 */
.basic {
  width: calc(100% - 80px);           /* 百分比减去固定值 */
  height: calc(50vh + 20px);          /* 视口单位加上固定值 */
  margin: calc(1rem * 2);             /* 倍数计算 */
  font-size: calc(16px / 2);          /* 除法计算 */
}

/* 与 CSS 变量结合使用 */
.variables {
  --base-width: 100px;
  --half-width: calc(var(--base-width) / 2);
  --quarter-width: calc(var(--half-width) / 2);
  
  width: var(--quarter-width);        /* 最终结果：25px */
}

/* 复杂表达式 */
.complex {
  font-size: calc(1.5rem + 3vw);      /* 响应式字体大小 */
  padding: calc(10px + 2%);           /* 固定值加百分比 */
}
```

#### 百分比计算 {#percentage-calculation}

百分比在 `calc()` 中的计算逻辑详见 [百分比单位说明](#percentage-unit-explanation)。

```css
/* 注意：需要在 template 模板对应元素标签中指定 parent-width 或 parent-height 属性 */
.percentage {
  width: calc(100% - 20px);   /* 需要在模板中指定 parent-width 属性 */
  height: calc(80% + 10px);   /* 需要在模板中指定 parent-height 属性 */
}
```

### env() 函数 {#env-function}

`env()` 函数用于将系统定义的环境变量值插入到 CSS 中，主要用于处理设备的安全区域。

#### 语法 {#syntax-2}

```css
env(<environment-variable>, <fallback-value>?)
```

* **第一个参数**：系统环境变量名称
* **第二个参数**：可选的回退值，当环境变量不可用时使用

#### 支持的环境变量 {#supported-env-variables}

| 环境变量 | 说明 | 用途 |
|----------|------|------|
| `safe-area-inset-top` | 顶部安全距离 | 避开状态栏、刘海屏等 |
| `safe-area-inset-right` | 右侧安全距离 | 避开侧边区域 |
| `safe-area-inset-bottom` | 底部安全距离 | 避开 Home 指示器等 |
| `safe-area-inset-left` | 左侧安全距离 | 避开侧边区域 |

#### 使用示例 {#usage-example-2}

```css
/* 基本用法 */
.safe-area {
  padding-top: env(safe-area-inset-top, 20px);
  padding-right: env(safe-area-inset-right, 20px);
  padding-bottom: env(safe-area-inset-bottom, 20px);
  padding-left: env(safe-area-inset-left, 20px);
}

/* 简写形式 */
.safe-area-compact {
  padding: env(safe-area-inset-top, 20px) 
           env(safe-area-inset-right, 20px) 
           env(safe-area-inset-bottom, 20px) 
           env(safe-area-inset-left, 20px);
}
```

#### env() vs var() 对比 {#env-vs-var}

| 特性 | `env()` | `var()` |
|------|---------|---------|
| **定义方式** | 系统定义 | 开发者自定义 |
| **作用域** | 全局生效 | 局部作用域 |
| **用途** | 系统环境适配 | 样式变量管理 |

## 媒体查询 {#media-query}

https://developer.mozilla.org/en-US/docs/Web/CSS/CSS\_media\_queries/Using\_media\_queries

### 媒体类型 {#media-type}

* print 不支持
* **screen 支持**
* **all 支持**

### 媒体特性 {#media-features}

* **width-视口（包括纵向滚动条）的宽度，支持**
* height-视口的高度，暂不支持
* aspect-ratio-视口（viewport）的宽高比，暂不支持
* orientation-视口的旋转方向，暂不支持
* prefers-color-scheme 系统的主题色设置为亮色或者暗色，暂不支持

### 逻辑运算符 {#logical-operators}

* **and 支持**
* not 不支持
* only 不支持
* or 不支持

### 使用示例 {#usage-example-3}

```css
/* 支持 */
@media screen and (min-width: 900px) {}
@media (max-width: 12450px) {  }
@media screen and (min-width: 320px) and (max-width: 480px) {}
/* 不支持 */
/* 单位仅支持px */
@media (max-width: 30em) {  }
@media (min-width: 30em) and (max-width: 50em) {  }
/* 媒体查询 4 级规范，暂不支持 */
@media (width <= 30em) {  }
@media (30em <= width <= 50em ) {  }
```

## 原子类 {#utility-class}

> 原子类功能正在开发中，敬请期待后续版本支持。

## 样式属性参考 {#style-property-reference}

以下是 Mpx 转 RN 支持的样式属性详细说明。

### position

设置元素的定位方式。

**值类型**：`relative` | `absolute` | `fixed`（默认 `relative`）

```css
position: absolute;
top: 10px;
```

### top / right / bottom / left

设置元素在不同方向的偏移量。

**值类型**：`number`，支持[所有数值单位](#numeric-units)

```css
position: relative;
top: 10%;
left: 20px;
```

### z-index

控制元素的堆叠覆盖顺序。

**值类型**：`number`（纯数值，无单位）

```css
position: absolute;
z-index: 10;
```

### display

设置元素的布局方式。

**值类型**：`flex` | `none`

> \[!tip] RN 布局限制
>
> * 仅支持 `flex` 布局，不支持 `block`、`grid`、`table` 等
> * `Text` 节点默认为行内布局

```css
display: flex; /* 弹性布局（默认） */
display: none; /* 隐藏元素 */
```

### opacity

设置元素的不透明度。

**值类型**：`number`（0-1，0为完全透明，1为完全不透明）

> \[!tip] 注意
>
> RN 中设置 `opacity: 0` 的元素不响应触摸事件

```css
opacity: 1;   /* 完全不透明 */
opacity: 0.6; /* 半透明 */
opacity: 0;   /* 完全透明 */
```

### overflow

控制元素溢出时的行为。

**值类型**：`visible` | `hidden` | `scroll`

```css
overflow: visible; /* 显示溢出内容 */
overflow: hidden;  /* 隐藏溢出内容 */
overflow: scroll;  /* 滚动查看溢出内容 */
```

### pointer-events

控制元素是否响应触摸事件。

**值类型**：`auto` | `none` | `box-none`（仅 RN 支持）| `box-only`（仅 RN 支持）

> \[!tip] 💡 RN 特有值
>
> * `box-none`：当前元素不响应，但子元素可响应
> * `box-only`：当前元素响应，但子元素不响应

```css
pointer-events: auto;     /* 正常响应事件 */
pointer-events: none;     /* 不响应事件 */
pointer-events: box-none; /* 仅 RN 支持 */
```

### justify-content

设置主轴方向的对齐方式。

**值类型**：`flex-start` | `flex-end` | `center` | `space-between` | `space-around` | `space-evenly`

```css
justify-content: flex-start;    /* 起始对齐（默认） */
justify-content: center;        /* 居中对齐 */
justify-content: space-between; /* 两端对齐 */
```

### align-items

设置交叉轴方向的对齐方式。

**值类型**：`flex-start` | `flex-end` | `center` | `stretch` | `baseline`

```css
align-items: stretch;    /* 拉伸填充（默认） */
align-items: center;     /* 居中对齐 */
align-items: flex-start; /* 起始对齐 */
```

### align-content

设置多行内容在交叉轴的对齐方式。

**值类型**：`flex-start` | `flex-end` | `center` | `stretch` | `space-between` | `space-around` | `space-evenly`

```css
align-content: flex-start;    /* 起始对齐 */
align-content: space-between; /* 行间等距分布 */
```

### align-self

设置单个子元素在交叉轴的对齐方式。

**值类型**：`auto` | `flex-start` | `flex-end` | `center` | `stretch` | `baseline`

```css
align-self: auto;      /* 继承父元素 align-items */
align-self: center;    /* 居中对齐 */
align-self: flex-end;  /* 末尾对齐 */
```

### flex-direction

设置主轴方向。

**值类型**：`row` | `row-reverse` | `column` | `column-reverse`

```css
flex-direction: row;          /* 水平排列（默认） */
flex-direction: column;       /* 垂直排列 */
flex-direction: row-reverse;  /* 水平反向排列 */
```

### flex-wrap

设置是否允许换行。

**值类型**：`nowrap` | `wrap` | `wrap-reverse`

> \[!tip] 注意：当 `flex-wrap: wrap` 时，`align-items: center` 不生效

```css
flex-wrap: nowrap; /* 不换行（默认） */
flex-wrap: wrap;   /* 允许换行 */
```

### flex-grow

设置元素的放大系数。

**值类型**：`number`（≥ 0，默认 0）

```css
flex-grow: 0; /* 不放大（默认） */
flex-grow: 1; /* 等比放大 */
flex-grow: 2; /* 放大系数为 2 */
```

### flex-shrink

设置元素的收缩系数。

**值类型**：`number`（≥ 0，默认 0）

```css
flex-shrink: 0; /* 不收缩（默认） */
flex-shrink: 1; /* 允许收缩 */
```

### flex-basis

设置元素在主轴上的初始大小。

**值类型**：`auto` | `number`，支持[所有数值单位](#numeric-units)

> \[!important] 优先级规则
>
> * `flex-direction: row` 时，`flex-basis` 覆盖 `width`
> * `flex-direction: column` 时，`flex-basis` 覆盖 `height`
> * `flex-basis: auto` 时，使用 `width/height` 值

```css
flex-basis: auto; /* 使用 width/height 值（默认） */
flex-basis: 100px; /* 主轴方向固定为 100px */
flex-basis: 50%;   /* 主轴方向占父容器 50% */
```

### flex

`flex-grow`、`flex-shrink`、`flex-basis` 的简写属性。

**值类型**：`none` | `auto` | `initial` | `<flex-grow>` | `<flex-grow> <flex-shrink>` | `<flex-grow> <flex-basis>` | `<flex-grow> <flex-shrink> <flex-basis>`

```css
flex: 1;        /* flex: 1 1 0 */
flex: auto;     /* flex: 1 1 auto */
flex: none;     /* flex: 0 0 auto */
flex: 2 1 100px; /* grow: 2, shrink: 1, basis: 100px */
```

### flex-flow

`flex-direction` 和 `flex-wrap` 的简写属性。

**值类型**：`<flex-direction>` | `<flex-wrap>` | `<flex-direction> <flex-wrap>`

```css
flex-flow: row;         /* 仅设置方向 */
flex-flow: row nowrap;  /* 方向 + 换行 */
```

### gap / row-gap / column-gap

设置行列间距。

**值类型**：`number`，支持[所有数值单位](#numeric-units)

> \[!important] Mpx 增强
>
> * `gap` 支持单值和双值，单值同时设置行列间距，双值按 `row-gap column-gap` 展开
> * 百分比值会在运行时换算为数值，`row-gap` 基于 `parent-height`，`column-gap` 基于 `parent-width`

```css
gap: 16px;          /* 行列间距都是 16px */
gap: 20px 10px;     /* 行间距 20px，列间距 10px */
row-gap: 20px;      /* 仅行间距 */
column-gap: 10px;   /* 仅列间距 */
gap: 10% 20%;       /* 行间距基于父高度，列间距基于父宽度 */
```

### inset

`top`、`right`、`bottom`、`left` 的定位偏移简写。

**值类型**：`number`，支持[所有数值单位](#numeric-units)

> \[!important] Mpx 增强
>
> RN 0.74+ 支持 `inset` 单值，Mpx 会保留单值写法；2-4 值写法会展开为 `top`、`right`、`bottom`、`left`。

```css
inset: 0;                 /* 单值透传给 RN */
inset: 10px 20px;         /* 展开为 top/right/bottom/left：上下 10px，左右 20px */
inset: 1px 2px 3px 4px;   /* 展开为 top/right/bottom/left：上 | 右 | 下 | 左 */
```

### width / height

设置元素的宽度和高度。

**值类型**：`auto` | `number`，支持[所有数值单位](#numeric-units)

```css
width: auto;  /* 自动宽度 */
width: 100px; /* 固定宽度 */
width: 50%;   /* 百分比宽度 */
```

### max-width / max-height / min-width / min-height

设置元素的最大/最小尺寸。

**值类型**：`number`，支持[所有数值单位](#numeric-units)

```css
max-width: 500px;  /* 最大宽度 */
min-height: 100px; /* 最小高度 */
```

### aspect-ratio

设置元素的宽高比。

**值类型**：`auto` | `number` | `<width> / <height>`

```css
aspect-ratio: 1;       /* 正方形 */
aspect-ratio: 16 / 9;  /* 16:9 比例 */
aspect-ratio: auto;    /* 自动比例 */
```

### margin

设置外边距。

**值类型**：`auto` | `number`，支持[所有数值单位](#numeric-units)

> \[!important] 💡 Mpx 增强
>
> RN 原生仅支持单值 `margin`，可设置多值是由框架按简写逻辑在编译时处理的，多值语法仅在 class 类中支持

```css
margin: 10px;               /* 四边相同（RN 原生支持） */
margin: 10px 20px;          /* 上下 | 左右（Mpx 增强） */
margin: 10px 20px 15px;     /* 上 | 左右 | 下（Mpx 增强） */
margin: 10px 20px 15px 5px; /* 上 | 右 | 下 | 左（Mpx 增强） */
```

### margin-top / margin-right / margin-bottom / margin-left

设置单边外边距。

**值类型**：`auto` | `number`，支持[所有数值单位](#numeric-units)

```css
margin-top: 10px;    /* 上边距 */
margin-left: auto;   /* 左边距自动 */
```

### padding

设置内边距。

**值类型**：`number`，支持[所有数值单位](#numeric-units)

> \[!important] 💡 Mpx 增强
>
> RN 原生仅支持单值 `padding`，可设置多值是由框架按简写逻辑在编译时处理的，多值语法仅在 class 类中支持

```css
padding: 10px;               /* 四边相同（RN 原生支持） */
padding: 10px 20px;          /* 上下 | 左右（Mpx 增强） */
padding: 10px 20px 15px;     /* 上 | 左右 | 下（Mpx 增强） */
padding: 10px 20px 15px 5px; /* 上 | 右 | 下 | 左（Mpx 增强） */
```

### padding-top / padding-right / padding-bottom / padding-left

设置单边内边距。

**值类型**：`number`，支持[所有数值单位](#numeric-units)

```css
padding-top: 10px;    /* 上内边距 */
padding-left: 20px;   /* 左内边距 */
```

### border

边框的简写属性。

**值类型**：`<border-width>` || `<border-style>` || `<border-color>`

> \[!important] 💡 Mpx 增强
>
> 按值类型识别并展开为 `border-width`、`border-style`、`border-color`，合法值不强制书写顺序；缺省 `border-style` 时按 CSS 规范补为 `none`，最终在运行时统一清除边框；`border-width` 仅支持数值单位和 `hairlineWidth`，不支持 `thin` / `medium` / `thick`

```css
border: 1px solid red;
border: red solid 1px;
border: solid #e5e5e5;
border: none;             /* 最终清除边框 */
border: 1px none red;     /* border-style 为 none，最终清除边框 */
```

### border-width

设置边框宽度。

> \[!important] 💡 Mpx 增强
>
> RN 原生仅支持设置单值，可设置多值是由框架按简写逻辑在编译时处理的，多值语法仅在 class 类中支持

**值类型**：`number`，支持[所有数值单位](#numeric-units)

```css
border-width: 1px;                /* 四边相同 */
border-width: 1px 2px;            /* 上下 | 左右 */
border-width: 1px 2px 3px 4px;    /* 上 | 右 | 下 | 左 */
```

### border-color

设置边框颜色。

> \[!important] 💡 Mpx 增强
>
> RN 原生仅支持设置单值，可设置多值是由框架按简写逻辑在编译时处理的，多值语法仅在 class 类中支持

**值类型**：`color`，参考[色值类型支持](#color-value-support)

```css
border-color: red;              /* 四边相同 */
border-color: red blue;         /* 上下 | 左右 */
border-color: red blue green;   /* 上 | 左右 | 下 */
```

### border-style

设置边框样式。

**值类型**：`solid` | `dotted` | `dashed` | `none`

> \[!tip] 注意
> RN 不支持单独设置各边的样式，只能整体设置，所以 RN 上 border-style 不支持简写形式；`border-style: none` 会在运行时转换为 `border-width: 0`

```css
border-style: solid;  /* 实线 */
border-style: dotted; /* 点线 */
border-style: dashed; /* 虚线 */
border-style: none;   /* 清除边框 */
```

### border-radius

设置圆角半径。

> \[!important] 💡 Mpx 增强
>
> RN 原生仅支持设置单值，可设置多值是由框架按简写逻辑在编译时处理的，多值语法仅在 class 类中支持

**值类型**：`number`，支持[所有数值单位](#numeric-units)

```css
border-radius: 5px;           /* 四角相同 */
border-radius: 5px 10px;      /* 对角线 */
border-radius: 5px 10px 15px 20px; /* 左上 | 右上 | 右下 | 左下 */
```

### border-top-left-radius / border-top-right-radius / border-bottom-left-radius / border-bottom-right-radius

设置单个角的圆角大小。

**值类型**：`number`，支持[所有数值单位](#numeric-units)

```css
border-top-left-radius: 5px;     /* 左上角 */
border-top-right-radius: 10px;   /* 右上角 */
border-bottom-left-radius: 2px;  /* 左下角 */
border-bottom-right-radius: 8px; /* 右下角 */
```

### border-top / border-right / border-bottom / border-left

单边边框的简写属性。

**值类型**：`<border-width>` || `<border-style>` || `<border-color>`

> \[!important] 💡 Mpx 增强
>
> 按值类型识别并展开，合法值不强制书写顺序：
>
> * `<border-width>` → `border-*-width`（对应方向）
> * `<border-color>` → `border-*-color`（对应方向）
> * `<border-style>` → `border-style`（RN 不支持单边 `border-*-style`，统一作用于四边）

```css
border-top: 1px solid red;    /* 上边框：宽度 样式 颜色 */
border-top: red solid 1px;    /* 顺序不敏感 */
border-left: 2px dotted blue; /* 左边框：宽度 样式 颜色 */
border-left: none;            /* border-style 为 none，最终清除边框 */
```

### outline / outline-style

外轮廓相关属性。

**值类型**：

* `outline`：`<outline-width>` || `<outline-style>` || `<outline-color>`
* `outline-style`：`solid` | `dotted` | `dashed` | `none`

> \[!important] Mpx 增强
>
> * `outline` 按值类型识别并展开为 `outline-width`、`outline-style`、`outline-color`，合法值不强制书写顺序
> * `outline` 与 `border` 使用一致的缺省值：缺省 `outline-width` 时补 `3px`，缺省 `outline-style` 时补 `none`
> * `outline: none`、`outline: 0`、`outline: 1px none red` 和 `outline-style: none` 会在运行时转换为 `outline-width: 0`
> * `outline` 系属性在 RN 0.76+ 生效；更低版本会被 RN 忽略

```css
outline: 1px solid red;
outline: red solid 1px;
outline: solid;          /* 补 outline-width: 3px */
outline: none;           /* 最终清除 outline */
outline-style: none;     /* 最终清除 outline */
```

### background

背景的简写属性。

**值类型**：`<background-image>` | `<background-color>` | `<background-size>` | `<background-repeat>` | `<background-position>`，具体每个属性的支持情况详见各属性的介绍文档

> \[!tip] 注意
> 仅 `view` 组件支持

```css
background: url("image.jpg") no-repeat center;
background: url("image.jpg") no-repeat center/cover;
background: linear-gradient(45deg, red, blue);
background: #f0f0f0;
```

### background-color

设置背景颜色。

**值类型**：`color`，参考[色值类型支持](#color-value-support)

```css
background-color: red;
background-color: #ff0000;
background-color: rgba(255, 0, 0, 0.5);
```

### background-image

设置背景图片或渐变。

**值类型**：`url()` | `linear-gradient()`

> \[!tip] 注意
>
> * 背景图和背景色仅 `<view>` 组件支持，且需要通过 `enable-background` 属性开启支持
> * 渐变不支持 `turn`、`px` 单位，仅支持百分比

```css
background-image: url("https://example.com/image.jpg");
background-image: linear-gradient(45deg, blue, red);
background-image: linear-gradient(to right, blue 0%, red 100%);
```

### background-size

设置背景图片大小。

> \[!tip] 注意
>
> * 仅 `<view>` 组件支持
> * 支持一个值，这个值指定图片的宽度，图片的高度隐式的为 auto；支持两个值，第一个值指定图片的宽度，第二个值指定图片的高度；不支持逗号分隔的多个值

**值类型**：`cover` | `contain` | `auto` | `number`

```css
background-size: cover;    /* 覆盖容器 */
background-size: contain;  /* 完整显示 */
background-size: 50% 25%;  /* 宽度 高度 */
```

### background-repeat

设置背景图片重复方式。

**值类型**：`no-repeat`

> \[!tip] 注意
> 仅 `view` 组件支持

```css
background-repeat: no-repeat;

/* 不支持 */
background-repeat: repeat;
```

### background-position

设置背景图片位置。

> \[!tip] 注意
> 仅 `view` 组件支持

**值类型**：`center` | `left` | `right` | `top` | `bottom` | `number`

```css
background-position: center;      /* 居中 */
background-position: 10px 20px;   /* x y 坐标 */
background-position: right 10px bottom 10px; /* 右下角偏移 */

/* 不支持 */
background-position: 1cm 2cm;
background-position: 10ch 8em;
background-position: right 3em bottom 10px;
```

### box-shadow

设置阴影颜色、阴影偏移量、阴影模糊半径。

**值类型**：`<offset-x> <offset-y> <blur-radius> <spread-radius> <color>`

> \[!important] 💡 Mpx 增强
>
> RN 旧版本不支持 `box-shadow` 属性，Mpx 按 RN 支持的 `shadowOffset`、`shadowRadius`、`shadowColor` 属性转换
>
> **简写规则**：
>
> * 按 `offset-x` `offset-y` `blur-radius` `spread-radius` `color` 顺序赋值
> * 不支持的属性会被忽略，值校验不合法时跳过该值继续校验下一个
> * 在设置 `box-shadow` 有效值的情况下，iOS 下会自动添加 `shadowOpacity: 1` 来展示阴影

**值类型详细说明**：

* `offset-x` / `offset-y` / `blur-radius`：`number`，支持[所有数值单位](#numeric-units)
* `color`：`color`，参考[色值类型支持](#color-value-support)

```css
/* offset-x | offset-y | blur-radius | color */
box-shadow: 0 1px 3px rgba(139, 0, 0, 0.32);

/* offset-x | offset-y | blur-radius | spread-radius | color */
/* spread-radius 不支持，1px 会被忽略 */
box-shadow: 2px 2px 2px 1px rgba(0, 0, 0, 0.2);
```

> \[!warning] 平台差异与限制
>
> * **Android**：仅支持 `shadowColor`，所以框架在 android 模式下不会添加 shadowOffset/shadowRadius
> * **iOS**：支持 `shadowOffset` / `shadowRadius` / `shadowColor` / `shadowOpacity`
> * **均不支持**：`spread-radius`（阴影扩散半径）
> * **布局限制**：与 `overflow: hidden` 同时使用时，RN 无法正常展示阴影，需单独新增节点
> * **RN 0.76+**：新架构支持原生 `boxShadow` 属性

### color

设置文本颜色。

**值类型**：`color`，参考[色值类型支持](#color-value-support)

> **💡 提示**：遵循[文本样式继承规则](#text-style-inheritance)

```css
color: red;
color: #ff0000;
color: rgba(255, 0, 0, 0.8);
```

### font-family

设置字体。

**值类型**：`string`

> \[!tip] 注意
>
> * 仅支持设置单一字体
> * 不支持字体文件引入
> * 遵循[文本样式继承规则](#text-style-inheritance)

```css
font-family: PingFangSC-Regular;
```

### font

设置字体简写，会展开为 `font-style`、`font-variant`、`font-weight`、`font-size`、`line-height`、`font-family` 等长属性。

**值类型**：`[font-style] [small-caps] [font-weight] font-size [ / line-height ] font-family`

> \[!tip] 注意
>
> * `font-size` 与 `font-family` 必填
> * `font-family` 多字体 fallback 会自动取首值并去除引号
> * `/` 两侧可以有空格

```css
font: 16px PingFangSC-Regular;
font: italic bold 16px / 1.5 Arial;
```

### font-size

设置字体大小。

**值类型**：`number`，支持[所有数值单位](#numeric-units)

> \[!tip] 注意
>
> * 遵循[文本样式继承规则](#inheritance-rule)
> * 百分比计算规则详见[百分比计算规则](#percentage-calculation-rules)

```css
font-size: 16px;
font-size: 1.2rem;
font-size: 120%; /* 优先基于当前或继承字号计算 */
```

### font-weight

设置字体粗细。

**值类型**：`normal` | `bold` | `100` | `200` | `300` | `400` | `500` | `600` | `700` | `800` | `900`

> \[!tip] 注意
>
> * 遵循[文本样式继承规则](#inheritance-rule)
> * 若在自定义字体图标上加 `font-weight`，可能会导致在某些安卓机型上不展示图标或者图标展示异常
> * 100，200，300，400，500，600，800，900 在 RN 上是字符串类型而非数值类型，非字符串类型可能会导致某些安卓机型异常

```css
font-weight: normal; /* 400 */
font-weight: bold;   /* 700 */
font-weight: 600;
```

### font-style

设置字体样式。

**值类型**：`normal` | `italic`

```css
font-style: normal;
font-style: italic;
```

### line-height

设置行高。

**值类型**：`number`，支持[所有数值单位](#numeric-units)和百分比

> \[!tip] 注意
>
> * 遵循[文本样式继承规则](#inheritance-rule)
> * 百分比计算规则详见[百分比计算规则](#percentage-calculation-rules)
> * 百分比和 unit-less 倍率会按最终文本节点合并后的 `font-size` 计算；数值型 `lineHeight` 是绝对行高

```css
line-height: 20px;   /* 固定行高 */
line-height: 1.5;    /* 相对倍数 */
line-height: 150%;   /* 百分比 */
```

### text-align

设置文本对齐方式。

> \[!tip] 注意
>
> 遵循[文本样式继承规则](#inheritance-rule)

**值类型**：`left` | `right` | `center` | `justify`

```css
text-align: left;    /* 左对齐 */
text-align: center;  /* 居中对齐 */
text-align: justify; /* 两端对齐 */
```

### vertical-align

设置行内文本的垂直对齐方式。

**值类型**：`auto` | `top` | `bottom` | `middle`

> \[!tip] 注意
>
> * 遵循[文本样式继承规则](#inheritance-rule)
> * 仅 Android 支持

```css
vertical-align: middle; /* 垂直居中 */
vertical-align: top;    /* 顶部对齐 */
```

### text-decoration

文本装饰线的简写属性。

**值类型**：`<text-decoration-line>` || `<text-decoration-style>` || `<text-decoration-color>`

> \[!tip] 注意
>
> * 按值类型识别并展开为 `text-decoration-line`、`text-decoration-style`、`text-decoration-color`，合法值不强制书写顺序
> * `text-decoration-line` 唯一支持的多值组合是 `underline line-through`；`none` 只作为单值生效
> * 赋值过程中，如遇到不支持的属性会忽略该属性；若属性值校验不合法，则忽略该值，继续校验下一个值是否合法，合法则赋值，不合法则继续校验下一个值
> * RN 原生不支持 `text-decoration` 简写，可使用是由框架编译和运行时处理
> * Android / Harmony 下 `<text-decoration-style>` 仅支持 `solid`；`<text-decoration-color>` 因不支持不会添加
> * 遵循[文本样式继承规则](#inheritance-rule)

```css
text-decoration: underline;           /* 下划线 */
text-decoration: line-through;        /* 删除线 */
text-decoration: underline dotted red; /* 样式 + 颜色（iOS；Android / Harmony 仅支持 solid 样式） */
text-decoration: red underline solid; /* 顺序不敏感（iOS） */
text-decoration: underline line-through red; /* 下划线 + 删除线 */
```

### text-transform

设置文本大小写转换。

> \[!tip] 注意
>
> 遵循[文本样式继承规则](#inheritance-rule)

**值类型**：`none` | `uppercase` | `lowercase` | `capitalize`

```css
text-transform: uppercase;  /* 大写 */
text-transform: lowercase;  /* 小写 */
text-transform: capitalize; /* 首字母大写 */

/** 不支持 **/
text-transform: full-width;
text-transform: full-size-kana;
text-transform: math-auto;
```

### letter-spacing

设置字符间距。

> \[!tip] 注意
>
> 遵循[文本样式继承规则](#inheritance-rule)

**值类型**：`number`，支持[所有数值单位](#numeric-units)

```css
letter-spacing: 2px;   /* 字符间距 2px */
letter-spacing: 2rpx; /* 字符间距 2rpx */
```

### text-shadow

设置文本阴影偏移量、模糊半径和颜色。

**值类型**：`<color>? && <offset-x> <offset-y> <blur-radius>?`

> \[!important] 💡 Mpx 增强
>
> RN 不支持 `text-shadow` 属性，Mpx 按 RN 支持的 `textShadowOffset`、`textShadowRadius`、`textShadowColor` 属性转换
>
> **简写规则**：
>
> * `<offset-x>` 与 `<offset-y>` 必填；`<blur-radius>` 与 `<color>` 可选
> * 颜色可以写在长度组前后任意位置
> * 长度组内部保持顺序：第一个长度为 `offset-x`，第二个长度为 `offset-y`，第三个长度为 `blur-radius`
> * 编译时和运行时如缺省 `<offset-y>` 都会发出 warn 并按 `0` 兜底
> * 不支持的属性会被忽略，值校验不合法时跳过该值继续校验下一个
> * 遵循[文本样式继承规则](#inheritance-rule)

**值类型详细说明**：

* `offset-x` / `offset-y` / `blur-radius`：`number`，支持[所有数值单位](#numeric-units)
* `color`：`color`，参考[色值类型支持](#color-value-support)

```css
/* offset-x | offset-y | blur-radius | color */
text-shadow: 1px 1px 2px rgba(0, 0, 0, 0.5);

/* offset-x | offset-y | color（省略模糊半径） */
text-shadow: 2px 2px #000;

/* color | offset-x | offset-y | blur-radius */
text-shadow: #000 2px 2px 4px;
```

### font-variant

> \[!tip] 注意
>
> 遵循[文本样式继承规则](#inheritance-rule)

设置字体变体。

**值类型**：`small-caps` | `oldstyle-nums` | `lining-nums` | `tabular-nums` | `proportional-nums`

```css
font-variant: small-caps;     /* 小型大写字母 */
font-variant: tabular-nums;   /* 等宽数字 */
font-variant: small-caps tabular-nums; /* 支持空格分隔的多值 */
```

### direction

设置文本书写方向。

**值类型**：`ltr` | `rtl` | `inherit`

```css
direction: ltr; /* 从左到右 */
direction: rtl; /* 从右到左 */
```

### user-select

控制用户是否可以选择文本。

**值类型**：`auto` | `text` | `none` | `contain` | `all`

```css
user-select: none; /* 禁止选择 */
user-select: text; /* 允许选择 */
```

### transform

设置元素变换。

**值类型**：`string` | `array`

```css
/* CSS 字符串格式 */
transform: translateX(50px) rotate(45deg);
transform: scale(1.2) skewX(10deg);

/* RN 数组格式，仅 rn 支持 */
transform: [{translateX: 50}, {rotate: '45deg'}];
```

> \[!tip] 注意
>
> 1.RN transform 不支持 scaleZ/scale3d/translateZ/translate3d/rotate3d/matrix3d
> 2.skew/skewX/skewY 在 RN Android 上不生效

### transform-origin

设置视图变换的原点，默认情况下，变换的原点是中心。

**值类型**：

* **单值**：该值必须是 `px`、百分比或关键字 `left`、`center`、`right`、`top` 和 `bottom` 之一
* **双值**：第一个值代表 X 偏移，必须是 `px`、百分比或关键字 `left`、`center` 和 `right` 之一；第二个值代表 Y 偏移，必须是 `px`、百分比或关键字 `top`、`center` 和 `bottom` 之一
* **三值**：前两个值与双值语法相同，第三个值代表 Z 偏移，必须是 `px`

```css
/* 单值 */
transform-origin: center;        /* 关键字 */
transform-origin: 50%;           /* 百分比 */
transform-origin: 10px;          /* px 值 */

/* 双值 */
transform-origin: left top;      /* 关键字组合 */
transform-origin: 50% 50%;       /* 百分比 */
transform-origin: 10px 20px;     /* px 值 */

/* 三值 */
transform-origin: 50% 50% 30px;  /* X Y Z 坐标 */
transform-origin: left top 10px; /* 关键字 + Z 偏移 */
```

### backface-visibility

设置背面可见性。

> \[!tip] 注意
>
> 仅 `<view>` 组件支持

**值类型**：`visible` | `hidden`

```css
backface-visibility: hidden; /* 背面隐藏 */
```

### object-fit

设置替换元素的内容应该如何适应到其使用高度和宽度确定的框。

> \[!tip] 注意
>
> 仅 `<view>` 组件支持

**值类型**：`cover` | `contain` | `fill` | `scale-down`

```css
object-fit: fill;       /* 拉伸填满，可能变形 */
object-fit: contain;    /* 完整显示，保持比例 */
object-fit: cover;      /* 覆盖填充，保持比例，可能裁剪 */
object-fit: scale-down; /* 缩小显示 */
```

## 跨端动画 {#cross-platform-animation}

基础组件 view 支持两种动画形式 createAnimation API 和 transition，
可以通过设置 animation 属于来使用 createAnimation API 动画，通过 class 或者 style 设置 css transition 来使用 transition 动画，
可以用过 prop enable-animation = api/transition 来指定使用 createAnimation API/transition 的动画形式，，enable-animation 设置 true 默认为 createAnimation API 形式，需要注意的是指定动画类型后，对应的动画参数也需要匹配设置，详细使用文档如下：

### createAnimation 动画API {#create-animation-api}

创建一个动画实例 animation，调用实例的方法来描述动画，最后通过动画实例的 export 方法导出动画数据传递给组件的 animation 属性。
详情参考以下动画部分微信小程序文档，以下仅描述支持能力有差异部分：

#### [wx.createAnimation](https://developers.weixin.qq.com/miniprogram/dev/api/ui/animation/wx.createAnimation.html)

* 参数 timingFunction 不支持 step-start 和 step-end

#### [动画实例 animation](https://developers.weixin.qq.com/miniprogram/dev/api/ui/animation/Animation.html) {#animation-instance}

* translateZ() 不支持
* translate3d() 不支持
* rotate3d() 不支持
* rotateZ() 不支持
* scaleZ() 不支持
* scale3d() 不支持
* animation.matrix() 不支持
* animation.matrix3d() 不支持

### CSS transition

CSS transition 动画至少需要设置动画时长和动画属性，可通过单独属性 transition-property 和 transition-property 设置，也可以通过 transition 缩写设置

> 重要提示：transition 支持设置百分比，如 `marginTop: 1%;marginTop: 100%;`；要注意的是起始值和结束值需设置为同一类型，同为px或者同为百分比， 支持 `marginTop: 10px;marginTop: 100px; `，**不支持 `marginTop: 10px; marginTop: 100%;`**

#### [transition](https://developer.mozilla.org/en-US/docs/Web/CSS/transition)

```css
/**** 支持 */
/* property name | duration */
transition: margin-right 4s;
/* property name | duration | delay */
transition: margin-right 4s 1s;
/* property name | duration | easing function */
transition: margin-right 4s ease-in-out;
/* property name | duration | easing function | delay */
transition: margin-right 4s ease-in-out 1s;

/* Apply to 2 properties */
transition: margin-right 4s, color 1s;
```

```css
/**** 需配合 transition-property 使用*/
/* transition 未定义 property 时需配合 transition-property 使用，否则仅设置duration、timingFunciton等参数实际动画不生效 */
transition: 200ms linear 50ms;
transition: 2s, 1s;
```

```css
/**** 不支持：property 不支持设置为 all  */
transition: all 0.5s ease-out
```

#### [transition-property](https://developer.mozilla.org/en-US/docs/Web/CSS/transition-property)

不支持设置为 all，不支持自定义

> 支持的 property 合集有：
> rotateX rotateY rotateZ scaleX scaleY skewX skewY translateX translateY opacity backgroundColor width height top right bottom left color borderColor borderBottomColor borderLeftColor borderRightColor borderTopColor borderTopLeftRadius borderTopRightRadius borderBottomLeftRadius borderBottomRightRadius borderRadius borderBottomWidth borderLeftWidth borderRightWidth borderTopWidth borderWidth margin marginBottom marginLeft marginRight marginTop maxHeight maxWidth minHeight minWidth padding paddingBottom paddingLeft paddingRight paddingTop

```css
/**** 支持 */
transition-property: height;
transition-property: height, color;
```

```css
/**** 不支持 */
transition-property: all;
/* <custom-ident> values */
transition-property: test_05;
transition-property: -specific;
transition-property: sliding-vertically;
transition-property: test1, animation4;
transition-property: all, -moz-specific, sliding;
transition-property: inherit;
transition-property: initial;
transition-property: revert;
transition-property: revert-layer;
transition-property: unset;
```

#### [transition-duration](https://developer.mozilla.org/zh-CN/docs/Web/CSS/transition-duration)

```css
/**** 支持 */
transition-duration: 6s;
transition-duration: 120ms;
transition-duration: 1s, 15s;
transition-duration: 10s, 30s, 230ms;
```

#### [transition-delay](https://developer.mozilla.org/zh-CN/docs/Web/CSS/transition-delay)

```css
/**** 支持 */
transition-delay: 3s;
transition-delay: 2s, 4ms;
```

#### [transition-behavior](https://developer.mozilla.org/en-US/docs/Web/CSS/transition-behavior)

不支持

#### [transition-timing-function](https://developer.mozilla.org/en-US/docs/Web/CSS/transition-timing-function)

仅支持 ease、ease-in、ease-out、ease-in-out、linear、cubic-bezier()，不支持 step-start、step-end、steps()

### CSS animation

暂不支持

### 动画监听事件 {#animation-event-listener}

#### transitionend

* CSS transition 结束或 wx.createAnimation 结束一个阶段时触发
* 不属于冒泡事件，需要绑定在真正发生了动画的节点上才会生效

#### animationstart

暂不支持

#### animationiteration

暂不支持

#### animationend

暂不支持

---

---
url: /guide/rn/application-api.md
---
# 应用能力 {#application-ability}

本节介绍在 React Native 环境下 Mpx 支持的各种应用能力，包括配置、状态管理、API适配等核心功能。

### 目录概览 {#directory-overview}

* [配置能力](#config-ability) - App配置、页面配置、导航配置
* [状态管理](#state-management) - Pinia、Store、依赖注入
* [国际化](#i18n) - i18n多语言支持
* [API能力](#api-ability) - 跨平台API、Webview通信
* [高级特性](#advanced-features) - rnConfig 相关配置内容：异步分包、分享、路由控制、屏幕适配

## 配置能力 {#config-ability}

### App 全局配置 {#app-global-config}

对标参考 [微信 app 配置](https://developers.weixin.qq.com/miniprogram/dev/reference/configuration/app.html)，以下为 RN 环境支持情况：

| 配置项 | 支持状态 | 说明 |
|--------|----------|------|
| ✅ entryPagePath | 完全支持 | 应用启动首页路径 |
| ✅ pages | 完全支持 | 页面路径列表 |
| ⚠️ window | 部分支持 | 详见下方 window 配置 |
| ❌ tabbar | 暂不支持 | 底部标签栏配置 |
| ✅ networkTimeout | 完全支持 | 网络超时设置 |
| ✅ subpackages | 完全支持 | 分包结构配置|
| ✅ usingComponents | 完全支持 | 全局自定义组件注册 |
| ✅ vw | 完全支持 | 视窗单位支持 |

### Window 导航配置 {#window-nav-config}

Window 配置控制应用导航栏外观，参考 [微信 window 配置](https://developers.weixin.qq.com/miniprogram/dev/reference/configuration/app.html#window)：

| 配置项 | 支持状态 | 说明 |
|--------|----------|------|
| ✅ navigationBarBackgroundColor | 完全支持 | 导航栏背景颜色 |
| ✅ navigationBarTextStyle | 完全支持 | 导航栏文字颜色 |
| ✅ navigationStyle | 完全支持 | 导航栏样式 |
| ✅ backgroundColor | 完全支持 | 页面背景颜色 |

### 页面配置 {#page-config}

页面级别配置，参考 [微信页面配置](https://developers.weixin.qq.com/miniprogram/dev/reference/configuration/page.html)：

| 配置项 | 支持状态 | 说明 |
|--------|----------|------|
| ✅ navigationBarBackgroundColor | 完全支持 | 页面导航栏背景色 |
| ✅ navigationBarTextStyle | 完全支持 | 页面导航栏文字颜色 |
| ✅ navigationStyle | 完全支持 | 页面导航栏样式 |
| ✅ backgroundColor | 完全支持 | 页面背景颜色 |
| ✅ usingComponents | 完全支持 | 页面组件注册 |
| ❌ disableScroll | 不支持 | RN 默认不支持页面滚动，需使用 scroll-view 组件 |

## 状态管理 {#state-management}

### Pinia 状态管理 {#pinia-store}

**支持状态：✅ 完全支持**

Mpx 在 RN 环境下完整支持 Pinia 状态管理方案，提供响应式状态管理能力。

```js
// 示例：使用 Pinia Store
import { defineStore } from 'pinia'

export const useUserStore = defineStore('user', {
  state: () => ({
    userInfo: null,
    isLogin: false
  }),
  actions: {
    setUserInfo(info) {
      this.userInfo = info
      this.isLogin = true
    }
  }
})
```

📖 **详细文档：** [Pinia 状态管理指南](../advance/pinia.md)

### Store 状态管理 {#store-manage}

**支持状态：✅ 完全支持**

支持 Mpx 原生的 Store 状态管理方案，兼容小程序开发习惯。

📖 **详细文档：** [Store 状态管理指南](../advance/store.md)

### 依赖注入 {#dependency-injection}

**支持状态：✅ 完全支持**

支持 Provide/Inject 依赖注入模式，便于组件间状态共享。

📖 **详细文档：** [依赖注入指南](/guide/advance/provide-inject.html#依赖注入-provide-inject)

## 国际化 {#i18n}

**支持状态：✅ 完全支持**

Mpx 的 i18n 国际化功能在 RN 环境下保持完整支持。

📖 **详细文档：** [国际化 i18n 指南](../advance/i18n.md)

## API 能力 {#api-ability}

### 跨平台 API 适配 {#cross-platform-api-adapt}

通过 `@mpxjs/api-proxy` 提供跨平台的小程序 API 适配能力，在 RN 环境中保持与小程序一致的使用方式。部分 API 能力相比小程序有所限制，详细支持列表请[查看完整文档](/api/extend.html#api-proxy)。

#### 使用说明 {#usage-instruction}

#### 1. 安装和配置 {#install-config}

**步骤1：引入 @mpxjs/api-proxy**

```js
import mpx from '@mpxjs/core'
import apiProxy from '@mpxjs/api-proxy'

mpx.use(apiProxy, { usePromise: true })
```

**步骤2：配置 Externals**

使用 mpx-cli 创建的项目已默认配置，无需手动设置。如需自定义，参考：

```js
// vue.config.js
externals: {
  '@react-native-async-storage/async-storage': '@react-native-async-storage/async-storage',
  '@react-native-clipboard/clipboard': '@react-native-clipboard/clipboard',
  '@react-native-community/netinfo': '@react-native-community/netinfo',
  'react-native-device-info': 'react-native-device-info',
  'react-native-safe-area-context': 'react-native-safe-area-context',
  'react-native-reanimated': 'react-native-reanimated',
  'react-native-get-location': 'react-native-get-location',
  'react-native-haptic-feedback': 'react-native-haptic-feedback'
}
```

#### 2. 依赖安装 {#dependency-install}

根据使用的 API 选择性安装依赖：

| API 功能 | 相关方法 | 依赖包 |
|----------|----------|--------|
| **弹窗选择** | `showActionSheet` | `react-native-reanimated` |
| **网络状态** | `getNetworkType`、`onNetworkStatusChange` | `@react-native-community/netinfo` |
| **位置服务** | `getLocation`、`openLocation`、`chooseLocation` | `react-native-get-location` |
| **本地存储** | `setStorage`、`getStorage`、`removeStorage` | `@react-native-async-storage/async-storage` |
| **设备信息** | `getSystemInfo`、`getDeviceInfo` | `react-native-device-info` |
| **安全区域** | `getWindowInfo`、`getLaunchOptionsSync` | `react-native-safe-area-context` |
| **震动反馈** | `vibrateShort`、`vibrateLong` | `react-native-haptic-feedback` |

**按需安装示例：**

```bash
# 示例：只使用存储和设备信息API {#example-storage-device-api}
npm install @react-native-async-storage/async-storage react-native-device-info

# 示例：使用位置服务 {#example-location-service}
npm install react-native-get-location

# 示例：使用网络状态监听 {#example-network-status}
npm install @react-native-community/netinfo

# iOS 项目需要执行（有原生依赖时） {#ios-native-dependency}
cd ios && pod install
```

> 💡 **建议：** 根据实际使用的 API 选择安装对应依赖，避免不必要的包体积增加

#### 3. 平台特殊配置 {#platform-special-config}

**react-native-get-location**

Android 权限配置：

```xml
<!-- android/app/src/main/AndroidManifest.xml -->
<uses-permission android:name="android.permission.ACCESS_FINE_LOCATION"/>
<uses-permission android:name="android.permission.ACCESS_COARSE_LOCATION"/>
```

**react-native-haptic-feedback**

Android 需要额外配置，参考 [官方文档](https://github.com/mkuczera/react-native-haptic-feedback)：

1. 在 `android/app/src/main/java/[...]/MainApplication.java` 顶部导入：

```java
import com.mkuczera.RNReactNativeHapticFeedbackPackage;
```

2. 在 `android/settings.gradle` 中添加：

```
include ':react-native-haptic-feedback'
project(':react-native-haptic-feedback').projectDir = new File(rootProject.projectDir, '../node_modules/react-native-haptic-feedback/android')
```

**react-native-reanimated**

在 `babel.config.js` 中添加插件，参考 [官方文档](https://docs.swmansion.com/react-native-reanimated/docs/fundamentals/getting-started/)：

```js
module.exports = {
  presets: ['...'],
  plugins: [
    // 其他插件...
    'react-native-reanimated/plugin', // 必须放在最后
  ],
}
```

> ⚠️ **注意：** 确保 Mpx 项目和容器中的 `react-native-reanimated` 版本一致

### 跨平台 API 使用限制 {#cross-platform-api-limit}

> RN Android 的 `startWifi`、`stopWifi`、`getWifiList` 与 `getConnectedWifi` 成功回调 `errMsg` 均与微信文档一致，以 `:ok` 结尾。

### selectComponent/selectAllComponents

在 RN 环境下使用 `selectComponent` 或 `selectAllComponents` 时，必须在目标节点上标记 wx:ref。选择器支持范围有限，仅支持以下方式

* id 选择器：`#id`
* class 选择器（可连续指定多个）：`.a-class` 或 `.a-class.b-class.c-class`

```javascript
<template>
  <!-- 必须添加 wx:ref 标记 -->
  <list wx:ref class="list"></list>
</template>

<script>
  import { createComponent } from '@mpxjs/core'

  createComponent({
    ready() {
      // 获取组件实例
      const instance = this.selectComponent('.list')
      console.log('selectComponent', instance)
    }
  })
</script>
```

#### createSelectorQuery

使用 `createSelectorQuery` 来获取基础组件需要在基础节点上标记 `wx:ref` 标签才能生效，以及所支持的选择器范围和 `selectComponent`/`selectAllComponents` 一致。

```javascript
<template>
  <view wx:ref class="title">this is view</view>
</template>

<script>
  import { createComponent } from '@mpxjs/core'

  createComponent({
    ready() {
      this.createSelectorQuery()
        .select('.title')
        .boundingClientRect(res => {
          console.log('the rect res is:', res)
        })
        .exec()
    }
  })
</script>
```

### Webview 通信 {#webview-communication}

Mpx 提供 `@mpxjs/webview-bridge` 来实现 H5 页面与 RN 应用的双向通信，具体使用方式参考[webview-bridge](../extend/webview-bridge.md)文档。

## 高级特性 {#advanced-features}

`rnConfig` 是 Mpx 框架专为 React Native 环境提供的配置对象，用于定制 RN 平台特有的行为和功能。通过 `mpx.config.rnConfig` 可以配置异步分包、分享、路由控制、屏幕适配等高级特性。

### 异步分包 {#async-subpackage}

Mpx 在 RN 环境下实现了与微信小程序同等的异步分包功能，支持按需加载分包内容。基础使用可参考 [异步分包指南](https://www.mpxjs.cn/guide/advance/async-subpackage.html)

在异步分包的能力实现当中我们借助了 RN 容器提供的分包下载执行/分包拉取的 api，因此在你的应用开始使用异步分包的功能之前需要在运行时代码提前部署好 RN 容器提供的相关 api 以供 Mpx 应用使用：

```js
import mpx from '@mpxjs/core'

// 配置分包加载器
mpx.config.rnConfig.loadChunkAsync = function (config) {
  // 分包下载并执行 api
  return drnLoadChunkAsync(config.package)
}

mpx.config.rnConfig.downloadChunkAsync = function (packages) {
  if (packages && packages.length) {
    // 分包拉取 api
    drnDownloadChunkAsync(packages)
  }
}
```

#### 构建配置 {#build-config}

在 `mpx.config.js` 中配置异步分包选项：

```js
module.exports = defineConfig({
  pluginOptions: {
    mpx: {
      plugin: {
        rnConfig: {
          asyncChunk: {
            timeout: 10000, // 异步分包加载超时时间(ms)，默认为 10s
            loading: path.resolve(__dirname, 'src/components/loading.mpx'),    // 自定义异步分包 loading 页面
            fallback: path.resolve(__dirname, 'src/components/fallback.mpx')   // 自定义异步分包页面加载失败的兜底页面配置
          }
        }
      }
    }
  }
})
```

#### 错误处理 {#error-handling}

**组件加载失败监听**：微信小程序提供了 wx.onLazyLoadError 的全局 api 来监听异步组件加载失败，这个 api 同样在 Mpx 转 RN 场景下生效；

```js
mpx.onLazyLoadError((error) => {
  console.error('异步组件加载失败:', error)
})
```

**页面加载失败监听**：微信小程序未提供相关的监听异常的 api，Mpx 转 RN 提供了一个额外的全局监听函数

```js
// RN 环境特有
mpx.config.rnConfig.onLazyLoadPageError = (error) => {
  console.error('异步页面加载失败:', {
    subpackage: error.subpackage, // 分包名
    errType: error.errType        // 'timeout' | 'fail'
  })
}
```

#### 自定义兜底页面 {#custom-fallback-page}

对于异步分包页面加载失败的情况会展示默认兜底页面，用户可以点击兜底页面底部的重试按钮重新加载异步分包页面。那么对于开发者提供的自定义的 fallback 兜底页面，框架会自动给自定义页面注入一个 `reload` 方法以供开发者做页面重试的操作，具体见下方示例：

```html
<template>
  <view class="fallback-container">
    <view class="error-message">页面加载失败</view>
    <view class="retry-btn" bindtap="handleRetry">点击重试</view>
  </view>
</template>

<script>
import { createComponent } from '@mpxjs/core'

createComponent({
  methods: {
    handleRetry() {
      this.triggerEvent('reload') // 触发重新加载，reload 事件为框架自动注入
    }
  }
})
</script>

<style>
.fallback-container {
  display: flex;
  flex-direction: column;
  align-items: center;
  justify-content: center;
  padding: 40rpx;
}

.retry-btn {
  margin-top: 20rpx;
  padding: 10rpx 20rpx;
  background-color: #007aff;
  color: white;
  border-radius: 4rpx;
}
</style>
```

### 分享 {#share}

#### mpx.config.rnConfig.openTypeHandler.onShareAppMessage

当使用 [button 组件](./rn.html#button) 并指定 `open-type="share"` 时，将触发分享。在 RN 中的分享实现需由容器实现，可在 onShareAppMessage 中调用容器提供的能力完成分享逻辑实现。

其参数为当前页面的 onShareAppMessage 钩子返回内容，如果返回内容中包含 promise，将会在 fulfilled 后将其结果合并再触发 onShareAppMessage

```ts
(shareInfo: { title: string, path: string, imageUrl?: string }) => void
```

### 路由 {#router}

#### mpx.config.rnConfig.parseAppProps

```ts
(props: Record<string, any>) => ({ initialRouteName: string, initialParams: Record<string, any> }| void)
```

用于获取初始路由配置的函数，参数为 RN 根组件接收到的参数

* initialRouteName: 首页路径，例如 pages/index
* initialParams: 将作为 首页onLoad 与 应用onLaunch 的参数，例如 { a: 1 }

在需要将 RN 应用嵌入到现有的 NA 应用中时，NA 可能会向 RN 的根组件传递 props，此时可在 parseAppProps 中接受 props 并进行处理和透传到页面

#### mpx.config.rnConfig.onStateChange

```ts
(state: Record<string, any>) => void
```

当导航状态发生变化时触发，例如页面跳转、返回等。

在需要将 RN 应用嵌入到现有的 NA 应用中时，可能需要将 RN 的路由栈同步到 NA 中以便于进行路径关系，此时可在此回调中将 RN 路径栈同步到容器中。

#### mpx.config.rnConfig.disablePageTransition

```ts
boolean
```

用于禁用页面转场动画，默认为 `false`。设置为 `true` 后，框架会在内部导航配置中使用 `animation: 'none'`。

如果需要关闭转场动画，可配置：

```js
mpx.config.rnConfig.disablePageTransition = true
```

#### mpx.config.rnConfig.onAppBack

```ts
() => boolean
```

页面栈长度为 1（即根页面）且用户尝试退出 App 时触发。

* true：允许退出应用
* false：阻止退出应用

#### mpx.config.rnConfig.onStackTopBack

控制首页回退按钮是否展示，并监听点击事件。

如果绑定该函数，则首页显示返回按钮，点击后调用该函数作为回调，如果未绑定该函数，则首页不会展示返回按钮。

如需实现点击返回，请在函数内部手动调用 back。

在需要将 RN 应用嵌入到现有的 NA 应用中时，可能 RN 应用到首页并不是 NA 应用的首页，此时可能需要 RN 应用首页展示返回按钮

### 折叠屏适配 {#foldable-screen-adaption}

#### mpx.config.rnConfig.customDimensions

```ts
(dimensions: { window: ScaledSize; screen: ScaledSize }) => { window: ScaledSize; screen: ScaledSize } | void
```

在某些情况下，我们可能不希望当前应用全屏展示，Mpx 内部基于 ScreenWidth 与 ScreenHeight 作为 rpx、vh、vw、媒体查询、onResize等特性的依赖内容，此时可在 `mpx.config.rnConfig.customDimensions` 中自定义 screen 尺寸信息来得到想要的渲染效果。

可在此方法中返回修改后的 dimensions，如果无返回或返回 undefined，则以入参作为返回值

例如: 在折叠屏中我们期望只在其中一半屏上展示，可在 customDimensions 中判断当前是否为折叠屏展开状态，如果是则将 ScreenWidth 设置为原来的一半。

### 前后台切换 {#app-state-change}

#### mpx.config.rnConfig.disableAppStateListener

```ts
boolean
```

Mpx 框架默认会使用 `ReactNative.AppState.addEventListener('change', callback)` 作为 Mpx 应用前后台切换的驱动，从而触发对应的钩子（如onhide/onshow）

在需要将 RN 应用嵌入到现有的 NA 应用中时，可能会出现AppState触发时机异常的情况（例如从 RN 页面跳转到 NA 页面时），此时可以将 disableAppStateListener 设置为 true 来禁用框架内部对 AppState 的监听。但需要在合适的时机手动调用 setAppShow() 与 setAppHide() 方法来进行驱动以确保对应的钩子能正常触发。

### 自定义设置底部虚拟按键区高度 {#custom-bottom-bar-height}

#### mpx.config.rnConfig.getBottomVirtualHeight

```ts
() => number
```

Android的不同系统或者手机的虚拟按键区高度可能存在不同的情况，框架内部统一使用了initialWindowMetrics.insets.bottom，如存在需要单独调整的场景可自定义设置虚拟按键区高度。

```javascript
// 示例
import ReactNative from 'react-native'
import { initialWindowMetrics } from 'react-native-safe-area-context'
mpx.config.rnConfig.getBottomVirtualHeight = () => {
  const screenDimensions = ReactNative.Dimensions.get('screen')
  const windowDimensions = ReactNative.Dimensions.get('window')
  return Math.max(initialWindowMetrics?.insets?.bottom || 0 , (screenDimensions.height - windowDimensions.height - ReactNative.StatusBar.currentHeight) || 0, 0)
}
```

---

---
url: /guide/rn/hybrid-with-react-native.md
---
# 混合编写 RN {#hybrid-rn}

在编写 Mpx 组件时，在某些出于性能考虑的特定情况下，可能会涉及到 Mpx 和 RN 混合编写：**在 Mpx 项目内直接使用 RN 组件和编写 RN 代码**。

## 混合使用 RN 组件 {#hybrid-use-rn-component}

### RN 组件注册 {#rn-component-register}

在 Mpx 组件内引用 RN 组件，需在 `components` 选项中进行注册。

#### 选项式 API {#options-api}

```html {4,6,20-23}
<template>
  <view>
    <!-- RN View 组件 -->
    <View>
      <!-- RN Text 组件 -->
      <Text> 我是 RN 组件 </Text>
      <!-- Mpx 组件 -->
      <view> 我是 Mpx 组件 </view>
      <!-- 支持在 RN 组件内部定义插槽 -->
      <slot name="myslot"></slot>
    </View>
  </view>
</template>

<script>
  import { createComponent } from "@mpxjs/core"
  import { View, Text } from "react-native"

  createComponent({
    components: {
      View,
      Text,
    },
  })
</script>
```

#### 组合式 API {#composition-api}

组合式 API 需要在 [defineOptions](../composition-api/composition-api.md#defineoptions) 中进行类似选项式 API 的 `components` 组件注册。

```html {4-9}
<script setup>
  import { View, Text } from "react-native"

  defineOptions({
    components: {
      View,
      Text,
    },
  })

  defineExpose({})
</script>
```

### RN 组件样式属性 style {#rn-component-style}

RN 组件支持样式属性的透传，`style/wx:style` 样式属性用法与小程序一致，并且额外支持 RN 数组样式定义方式。

```html
<template>
  <view>
    <!-- style -->
    <Text style="color: red"> 字符串形式 value </Text>
    <Text style="{{ {color: 'red'} }}"> 对象形式样式 value </Text>
    <Text style="{{ [{color: 'red'}] }}"> 数组形式样式 value </Text>
    <!-- wx:style -->
    <Text wx:style="color: red"> 字符串形式 value </Text>
    <Text wx:style="{{ {color: 'red'} }}"> 对象形式样式 value </Text>
    <Text wx:style="{{ [{color: 'red'}] }}"> 数组形式样式 value </Text>
  </view>
</template>
```

### RN 组件的属性与事件 {#rn-component-props-events}

* RN 组件属性与事件参考 RN 原生支持的属性与事件名，对应赋值方式按照 Mpx 语法进行双括号包裹。
* 组件使用的值既可以沿用 Mpx 组件的 `data`、`computed` 等响应式数据，也可以通过 [使用 React Hooks](#use-react-hooks) 返回值进行声明。

> \[!important] 注意
> 使用 React Hooks 导出的变量如果需要在模板上进行响应式更新，需要配合组件设置 `disableMemo: true` 使用，详见下方[配合模板响应式](#with-template-reactivity)。

## 使用 React Hooks {#use-react-hooks}

### 选项式 API {#options-api-1}

Mpx 提供了 React Hooks 执行机制，通过在 Mpx 组件内注册 `REACTHOOKSEXEC` 方法，保障 RN 组件的初始化执行。Hooks 的返回值支持数据与方法，比如：

* 模板上 RN 组件与 Mpx 组件的数据渲染
* 模板上的 props 传递
* 模板上的样式定义
* 模板上的事件的绑定与透传

```html {19}
<template>
  <view>
    <View onTouchEnd="{{ onTouchEnd }}">
      <Text> Count: {{ count }} </Text>
    </View>
  </view>
</template>

<script>
  import { createComponent, REACTHOOKSEXEC } from "@mpxjs/core"
  import { View, Text } from "react-native"
  import { useState } from "react"

  createComponent({
    components: {
      View,
      Text,
    },
    [REACTHOOKSEXEC]() {
      // 所有使用 hooks 的部分在此处进行注册与执行
      const [count, setCount] = useState(0)
      const onTouchEnd = () => {
        console.log("trigger event: onTouchEnd")
        setCount((count) => count + 1)
      }
      // 返回值可直接用于模板
      return {
        count,
        onTouchEnd,
      }
    },
  })
</script>
```

### 组合式 API {#composition-api-1}

Mpx 也支持组合式 API 的使用，使用方式与选项式 API 类似，均在 `onReactHooksExec` 方法内进行 hooks 的注册与执行

```html {13}
<script setup>
  import { onReactHooksExec } from "@mpxjs/core"
  import { View, Text } from "react-native"
  import { useState } from "react"

  defineOptions({
    components: {
      View,
      Text,
    },
  })

  onReactHooksExec(() => {
    const [count, setCount] = useState(0)
    const onTouchEnd = () => {
      console.log("trigger event: onTouchEnd")
      setCount((count) => count + 1)
    }
    return {
      count,
      onTouchEnd,
    }
  })

  defineExpose({})
</script>
```

### 配合模板响应式 {#with-template-reactivity}

如果你尝试了上面的示例代码，可能会好奇为什么点击后控制台正常打印了日志 `trigger event: onTouchEnd`，但是模板上的 `count` 并没有更新呢？

这是因为出于性能优化的考虑，Mpx 默认不会对 React Hooks 返回值进行响应式更新。 如果需要对使用 React Hooks 返回的变量在模板上进行响应式更新，可以通过在组件的 `options` 选项中配置 `disableMemo: true` 来开启，开启后也会关闭 RN 组件的性能优化。

选项式 API：

```js {4}
createComponent({
  // ...
  options: {
    disableMemo: true,
  },
})
```

组合式 API：

```js {4}
defineOptions({
  // ...
  options: {
    disableMemo: true,
  },
})
```

---

---
url: /guide/rn/rn-unocss.md
---
# 在Mpx RN 环境中使用原子类

Mpx 使用 unocss 作为原子类引擎，使得在使用 mpx 开发跨端项目也可以使用原子类。如果要在你的项目当中集成原子类的能力，具体操作请参照接入文档。

受限于 RN 平台的样式规则能力限制，绝大部分的 unocss 提供的原子类并不能在跨 RN 项目当中使用，以下是目前所支持的原子类：

> 对于不支持的原子类，在项目编译构建阶段会将不支持的原子类以 error 形式提示，且最终的编译产物当中不会产出对应的原子类结果

#### [Typography](https://windicss.org/utilities/general/typography.html#typography)

| 规则                      | 是否支持 |                         备注                          |
| :------------------------ | :------: | :---------------------------------------------------: |
| Font family               |    是    |                                                       |
| Font size                 |    是    |                                                       |
| Font style                |    是    |                                                       |
| Font weight               |    是    |                                                       |
| Font Variant Numberic     |    否    |                                                       |
| Hyphens                   |    否    |                                                       |
| Letter spacing            |    是    |                                                       |
| Line height               |    是    |                                                       |
| Tab size                  |    否    |                                                       |
| Text alignment            |    是    |                                                       |
| Text color                |    是    |                                                       |
| Text decoration           |    是    |                                                       |
| Text decoration style     |    是    |                 ios 支持  安卓不支持                    |
| Text decoration thickness |    否    |                                                       |
| Text underline offset     |    否    |                                                       |
| Text decoration opacity   |    是    |                                                       |
| Text indent               |    否    |                                                       |
| Text opacity              |    是    |                                                       |
| Text shadow             |    是    |                                                       |
| Text stroke               |    否    |                                                       |
| Text stroke color         |    否    |                                                       |
| Text transform            |    是    |                                                       |
| Vertical alignment        |    是    | 安卓支持，ios 不支持，且只支持 auto/top/bottom/center |
| White space               |    否    |                                                       |
| Word break                |    否    |                                                       |
| Write mode                |    否    |                                                       |
| Writing orientation       |    否    |                                                       |

#### Svg

不支持

#### [Variants](https://windicss.org/utilities/general/variants.html)

* Screen Variants

Mobile First

| Varaint          | 规则 | 备注 |
| :------------- | :------: | :---: |
| sm   |    @media (min-width: 640px)    |      |
| md   |    @media (min-width: 768px)    |      |
| lg   |    @media (min-width: 1024px)    |      |
| xl   |    @media (min-width: 1280px)    |      |
| 2xl  |    @media (min-width: 1536px)    |      |

Desktop First

| Varaint          | 规则 | 备注 |
| :------------- | :------: | :---: |
| \<sm   |    @media (max-width: 640px)    |      |
| \<md   |    @media (max-width: 768px)    |      |
| \<lg   |    @media (max-width: 1024px)    |      |
| \<xl   |    @media (max-width: 1280px)    |      |
| <2xl  |    @media (max-width: 1536px)    |      |

Only Screen

| Varaint          | 规则 | 备注 |
| :------------- | :------: | :---: |
| @sm   |   @media (min-width: 640px) and (max-width: 768px)    |      |
| @md   |   @media (min-width: 768px) and (max-width: 1024px)    |      |
| @lg   |   @media (min-width: 1024px) and (max-width: 1280px)    |      |
| @xl   |   @media (min-width: 1280px) and (max-width: 1536px)    |      |
| @2xl  |   @media (min-width: 1536px)    |      |

* Pseudo Elements

目前仅支持 `hover`

* Theme Variants

| Varaint          | 规则 | 备注 |
| :------------- | :------: | :---: |
| dark   |   暗色模式    |      |
| light   |   亮色模式    |      |

* Orientation Variants

| Varaint          | 规则 | 备注 |
| :------------- | :------: | :---: |
| portrait   |   竖屏    |      |
| landscape   |   横屏    |      |

#### [Screen Readers](https://windicss.org/utilities/accessibility/screen-readers.html)

不支持

#### [Animation](https://windicss.org/utilities/animations/animation.html)

不支持

#### [Transforms](https://windicss.org/utilities/animations/transforms.html)

| 规则                | 是否支持 | 备注 |
| :------------------ | :------: | :--: |
| Transform Type      |    是    |      |
| Transform Origin    |    是    |      |
| Transform Rotate    |    是    |      |
| Transform Scale     |    是    |      |
| Transform Skew      |    是    |      |
| Transform Translate |    是    |      |
| Perspective         |    是    |      |
| Perspective Origin  |    是    |      |

#### [Transitions](https://windicss.org/utilities/animations/transitions.html)

支持单属性及逗号分隔的多属性 transition，例如 `transition-opacity`、`transition-transform`、`transition-colors` 和多属性任意值；其中每个属性都必须处于 Mpx2RN transition 支持范围内。RN preset 会屏蔽生成 `transition-property: all` 的 `transition`、`transition-\d+`、`transition-all`、`transition-all-\d+`。

#### [Background](https://windicss.org/utilities/backgrounds/background.html)

| 规则                  | 是否支持 |                  备注                  |
| :-------------------- | :------: | :------------------------------------: |
| Background attachment |    否    |                                        |
| Background clip       |    否    |                                        |
| Background color      |    是    |                                        |
| Background opacity    |    是    |                                        |
| Background position   |    是    | 支持 left/right/top/bottom/center/数值 |
| Background repeat     |    是    |            仅支持 no-repeat            |
| Background size       |    是    |                                        |
| Background origin     |    否    |                                        |
| Background Image      |    是    |                                        |

#### [Gradients](https://windicss.org/utilities/backgrounds/gradients.html)

| 规则               | 是否支持 | 备注 |
| :----------------- | :------: | :--: |
| Gradient Direction |    是    |      |
| Gradient From      |    是    |      |
| Gradient Via       |    是    |      |
| Gradient To        |    是    |      |

#### [Background Blend Mode](https://windicss.org/utilities/backgrounds/background-blend-mode.html)

不支持

不支持

#### [Box Decoration Break](https://windicss.org/utilities/behaviors/box-decoration-break.html)

不支持

#### [Image Rendering](https://windicss.org/utilities/behaviors/image-rendering.html)

不支持

#### [Listing](https://windicss.org/utilities/behaviors/listings.html)

| 规则          | 是否支持 | 备注 |
| :------------- | :------: | :---: |
| List style type   |    否    |      |
| List style position    |    否    |      |
| List style image    |    否    |      |

#### [Overflow](https://windicss.org/utilities/behaviors/overflow.html)

仅支持 `hidden`、`scroll`、`visible` 属性值

#### [Overflow Behavior](https://windicss.org/utilities/behaviors/overscroll-behavior.html)

不支持

#### [Placeholder](https://windicss.org/utilities/behaviors/placeholder.html)

不支持

#### [Border](https://windicss.org/utilities/borders/border.html)

| 规则          | 是否支持 | 备注 |
| :------------- | :------: | :---: |
| Border radius   |    是    |  不支持 border-inline-start、border-inline-end、border-block-start、border-block-end 属性，其他都支持    |
| Border width    |    是    |      |
| Border color     |    是    |      |
| Border opacity     |    是    |      |
| Border style     |    是    |  不支持 double，hidden 样式，其他都支持   |

#### [Divider](https://windicss.org/utilities/borders/divider.html)

| 规则          | 是否支持 | 备注 |
| :------------- | :------: | :---: |
| Divider width   |    否    |     |
| Divider color    |    否    |      |
| Divider opacity    |    否    |      |
| Divider style   |    否    |      |

#### [Outline](https://windicss.org/utilities/borders/outline.html)

| 规则          | 是否支持 | 备注 |
| :------------- | :------: | :---: |
| Outline Width |      是     |      |
| Outline Color |      是     |     |
| Outline solid   |    是    |     |
| Outline dotted    |    是    |      |

#### [Ring](https://windicss.org/utilities/borders/ring.html)

| 规则          | 是否支持 | 备注 |
| :------------- | :------: | :---: |
| Ring width   |    否    |     |
| Ring color    |    否    |      |
| Ring opacity    |    否    |      |
| Ring offset width    |    否    |      |
| Ring offset color    |    否    |      |

#### [Box Shadow](https://windicss.org/utilities/effects/box-shadow.html)

| 规则          | 是否支持 | 备注 |
| :------------- | :------: | :---: |
| Box shadow size   |    是    |     |
| Box shadow color    |    是    |      |

#### [Opacity](https://windicss.org/utilities/effects/opacity.html)

支持

#### [Mix Blend Mode](https://windicss.org/utilities/effects/mix-blend-mode.html)

不支持

#### [Filter](https://windicss.org/utilities/filters/filter.html)

RN 0.76 支持，且存在机型的兼容性问题，具体参见 [RN 官方文档](https://reactnative.dev/blog/2024/10/23/release-0.76-new-architecture#box-shadow-and-filter-style-props)

| 规则          | 是否支持 | 备注 |
| :------------- | :------: | :---: |
| Filter blur   |    是    |      |
| Filter brightness     |    是    |      |
| Filter contrast     |    是    |      |
| Filter drop shadow     |    是    |      |
| Filter grayscale     |    是    |     |
| Filter hue rotate    |    是    |      |
| Filter invert     |    是    |      |
| Filter saturate     |    是    |      |
| Filter Sepia     |    是    |      |

#### [Backdrop Filter](https://windicss.org/utilities/filters/backdrop-filter.html)

不支持

| 规则          | 是否支持 | 备注 |
| :------------- | :------: | :---: |
| Backdrop blur   |    否   |      |
| Backdrop brightness     |    否    |      |
| Backdrop contrast     |    否    |      |
| Backdrop drop shadow     |    否    |      |
| Backdrop grayscale     |    否    |     |
| Backdrop hue rotate    |    否    |      |
| Backdrop invert     |    否    |      |
| Backdrop saturate     |    否    |      |
| Backdrop Sepia     |    否    |      |

#### [Accent Color](https://windicss.org/utilities/interactivity/accent-color.html)

不支持

#### [Appearance](https://windicss.org/utilities/interactivity/appearance.html)

部分支持(backface-visible,backface-hidden)

#### [Cursor](https://windicss.org/utilities/interactivity/cursor.html)

不支持，TextInput 有属性控制

#### [Caret](https://windicss.org/utilities/interactivity/caret.html)

| 规则          | 是否支持 | 备注 |
| :------------ | :------: | :--: |
| Caret Color   |    否    |      |
| Caret Opacity |    否    |      |

#### [Pointer Events](https://windicss.org/utilities/interactivity/pointer-events.html)

部分支持(auto,none)

#### [Resize](https://windicss.org/utilities/interactivity/resize.html)

不支持

#### [Scroll Behavior](https://windicss.org/utilities/interactivity/scroll-behavior.html)

不支持

#### [Touch Action](https://windicss.org/utilities/interactivity/touch-action.html)

不支持

#### [User Select](https://windicss.org/utilities/interactivity/user-select.html)

支持(none,auto,all,text)

#### [Will Change](https://windicss.org/utilities/interactivity/will-change.html)

不支持

#### [Columns](https://windicss.org/utilities/layout/columns.html)

不支持

#### [Container](https://windicss.org/utilities/layout/container.html)

不支持

#### [Display](https://windicss.org/utilities/layout/display.html)

| 规则                | 是否支持 | 备注 |
| :------------------ | :------: | :--: |
| Block               |    否    |      |
| Inline Block        |    否    |      |
| Inline              |    否    |      |
| Flow Root           |    否    |      |
| Contents            |    否    |      |
| Hidden              |    是    |      |
| Visibility          |    否    |      |
| Visibility          |    否    |      |
| Backface Visibility |    否    |      |
| List Item           |    否    |      |

#### [Flexbox](https://windicss.org/utilities/layout/flexbox.html)

| 规则                | 是否支持 | 备注 |
| :------------------ | :------: | :--: |
| Flex | 是 | |
| Flex Basis | 是 | |
| Inline Flex | 是 | |
| Flex Direction | 是 | |
| Flex Wrap | 是 | |
| Flex Stretch | 是 | |
| Flex Grow | 是 | |
| Flex Shrink | 是 | |

#### [Grid](https://windicss.org/utilities/layout/grid.html)

不支持

#### [Positioning](https://windicss.org/utilities/layout/positioning.html)

| 规则 | 是否支持 | 备注 |
| :------------------ | :------: | :--: |
| Justify Content | 是 | 只支持(justify-around,justify-between,justify-center,justify-end,justify-evenly,justify-start) |
| Justify Items | 否 | |
| Justify Self | 否 | |
| Align Content | 是 | |
| Align Items | 是 | |
| Align Self | 是 | |
| Place Content | 否 | |
| Place Items | 否 | |
| Place Self | 否 | |
| Position | 是 | 只支持(absolute,relative) |
| Top / Right / Bottom / Left | 是 | |
| Floats | 否 | |
| Clear | 否 | |
| Isolation | 否 | |
| Object Fit | 否 | |
| Object Position | 否 | |
| Z-Index | 是 | |

#### [Sizing](https://windicss.org/utilities/layout/sizing.html)

| 规则 | 是否支持 | 备注 |
| :------------------ | :------: | :--: |
| Width | 是 | |
| Min-Width | 是 | |
| Max-Width | 是 | |
| Min-Height | 是 | |
| Max-Height | 是 | |
| Box Sizing | 是 | 支持 `box-border`、`box-content` |

#### [Spacing](https://windicss.org/utilities/layout/spacing.html)

| 规则 | 是否支持 | 备注 |
| :------------------ | :------: | :--: |
| Padding | 是 | |
| Padding Y | 是 | |
| Padding X | 是 | |
| Padding Top | 是 | |
| Padding Left | 是 | |
| Padding Bottom | 是 | |
| Padding Right | 是 | |
| Margin | 是 | |
| Margin Y | 是 | |
| Margin X | 是 | |
| Margin Top | 是 | |
| Margin Left | 是 | |
| Margin Bottom | 是 | |
| Margin Right | 是 | |
| Space Between Y | 否 | |
| Space Between Y Reverse | 否 | |
| Space Between X | 否 | |
| Space Between X Reverse | 否 | |

#### [Tables](https://windicss.org/utilities/layout/tables.html)

不支持

## RN 端颜色透明度写法约束

### 背景

unocss 默认实现为了支持「单色 utility + 独立 opacity utility」的组合（如 `bg-red-500` + `bg-opacity-50`），会强制把颜色拆成两个 CSS 变量：

```css
.bg-red-500 {
  --un-bg-opacity: 1;
  background-color: rgb(239 68 68 / var(--un-bg-opacity));
}
.bg-opacity-50 {
  --un-bg-opacity: 0.5;
}
```

在浏览器上这套机制几乎免费，但在 RN 端经由 mpx-runtime 解析时，会带来三块额外开销：

1. **每个颜色 utility 多 1 个 styleObj key**：从 `{ backgroundColor }` 变成 `{ '--un-bg-opacity', backgroundColor }`，key 数量翻倍。
2. **运行时多一轮 cssVar 解析**：`useTransformStyle` 中的 `varVisitor` 需要逐个组件实例扫描并替换 `var(--*)` 引用。
3. **layer 抽离开销**：「全是 `--un-*`」的 utility 会被推到 `varUtilities` layer，运行时多一次 `mergeToLayer` 合并。

实测在 1200 卡片的 perf 列表上，将颜色 utility 的 cssVar 全部 inline 后，`__getStyle` 总耗时下降明显（从 ~700ms 降到 ~140ms 量级，与 stylus 持平）。

为此 `@mpxjs/unocss-base/preset-rn` 在编译期通过 postprocess 把所有颜色类 utility 中的 `var(--un-*-opacity)` / shadow 颜色 var 等**全部 inline 为字面量**，并丢弃配套的 `--un-*-opacity` 声明行。这是一项**对业务有感知**的破坏性优化，本节说明影响面与迁移方法。

### 影响范围与迁移

依赖「跨 utility cssVar 合成」的体系（`transform` / `filter` / `backdrop-filter` / `gradient` / `ring`）通过白名单**完整保留**，业务原有写法不受影响：

```html
<!-- ✅ 保持原样可用 -->
<view class="transform translate-x-2 rotate-45 scale-110" />
<view class="filter blur-sm brightness-110 contrast-125" />
<view class="bg-gradient-to-r from-blue-500 to-purple-500" />
```

实际**需要业务改写**的只有「颜色 + 独立 opacity utility」组合一种场景。请改用 unocss 原生的 `/{alpha}` 斜杠语法（Web / RN 双端一致）：

| 之前的写法（已不再生效） | 现在的写法 |
| :--- | :--- |
| `bg-red-500 bg-opacity-50` | `bg-red-500/50` |
| `text-blue-600 text-opacity-30` | `text-blue-600/30` |
| `border-gray-300 border-opacity-50` | `border-gray-300/50` |

> **触发逻辑**：独立 `*-opacity-{n}` utility 在 unocss 中只产出一行 `--un-*-opacity: <n>` 声明。该声明在 postprocess 中被剥离后 utility entries 为空，className 自然失效。

> **斜杠语法同样适用于其他颜色类**（如 `bg-red-500/30`、`shadow-black/20`），同色字面量 + alpha 通道直接内嵌为 `rgba(...)`，运行时零开销。

### 渲染等价性

| className | 改造前 | 改造后 |
| :--- | :--- | :--- |
| `bg-red-500` | `rgba(239,68,68,1)` | `rgba(239,68,68,1)` ≡ 同色 |
| `bg-red-500/50` | `rgba(239,68,68,0.5)` | `rgba(239,68,68,0.5)` ≡ 同色 |
| `bg-red-500 bg-opacity-50` | `rgba(239,68,68,0.5)` | **`rgba(239,68,68,1)`**（opacity utility 失效） |
| `shadow-md` | shadowColor `#000` alpha 0.1 | 同 |

迁移完成后，所有颜色相关 utility 在产物中均为字面值字符串，运行时不再有 cssVar 解析与 `varUtilities` layer 合并开销。

---

---
url: /guide/composition-api/composition-api.md
---
# 组合式 API {#composition-api}

## 什么是组合式 API {#what-is-composition-api}

组合式 API 是 Vue3 中包含的最重要的特性之一，主要由 `setup` 函数及一系列响应式 API 及生命周期钩子函数组成，与传统的选项式 API 相比，组合式 API 具备以下优势：

* 更好的逻辑复用，通过函数包装复用逻辑，显式引入调用，方便简洁且符合直觉，规避消除了 mixins 复用中存在的缺陷；
* 更灵活的代码组织，相比于选项式 API 提前规定了代码的组织方式，组合式 API 在这方面几乎没有做任何限制与规定，更加灵活自由，在功能复杂的庞大组件中，我们能够通过组合式 API 让我们的功能代码更加内聚且有条理，不过这也会对开发者自身的代码规范意识提出更高要求；
* 更方便的类型推导，虽然基于 `this` 的选项式 API 通过 `ThisType` 也能在一定程度上实现 TS 类型推导，但推导和实现成本较高，同时仍然无法完美覆盖一些复杂场景（如嵌套 mixins 等）；而组合式 API 以本地变量和函数为基础，本身就是类型友好的，我们在类型方面几乎不需要做什么额外的工作就能享受到完美的类型推导。

同时与 React Hooks 相比，组合式 API 中的 `setup` 函数只在初始化时单次执行，在数据响应能力的加持下大大降低了理解与使用成本，基于以上原因，我们决定为 Mpx 添加组合式 API 能力，让用户能够用组合式 API 方式进行小程序开发。

更多关于组合式 API 的说明可以查看 [Vue3 官方文档](https://vuejs.org/guide/extras/composition-api-faq.html)。

Mpx 是一个小程序优先的增强型跨端框架，因此我们在为 Mpx 设计实现组合式 API 的过程中，并不追求与 Vue3 中的组合式 API 完全一致，我们更多是借鉴 Vue3 中组合式 API 的设计思想，将其与目前 Mpx 及小程序中的开发模式结合起来，而非完全照搬其实现。因此在 Mpx 中一些具体的 API 设计实现会与 Vue3 存在差异，我们会在后续相关的文档中进行标注说明，如果你想查看 Mpx 与 Vue3 在组合式 API 中的差异，可以跳转到[这里](#diff-composition-api-vue3)查看。

## 组合式 API 基础 {#composition-api-basic}

### setup 函数 {#setup-function}

同 Vue3 一样，在 Mpx 当中 `setup` 函数是组合式 API 的基础，我们可以在 `createPage` 和 `createComponent` 中声明 `setup` 函数。

`setup` 函数接收 `props` 和 `context` 两个参数，其中 `context` 参数与 Vue3 中存在差别，详情可以查看[这里](#setup)。

我们参考 Vue3 中的示例实现一个小程序版本，可以看到它和 Vue3 中的实现基本一致，包含以下功能：

* 仓库列表
* 更新仓库列表的函数
* 返回列表和函数，以便其他组件选项可以对它们进行访问

```js
import { createComponent } from '@mpxjs/core'
import { fetchUserRepositories } from '@/api/repositories'

createComponent({
  properties: {
    user: String
  },
  setup (props) {
    let repositories = []
    const getUserRepositories = async () => {
      repositories = await fetchUserRepositories(props.user)
    }

    return {
      repositories, // 返回的数据，可以在其他选项式 API 中通过 this 访问或在模板上直接访问
      getUserRepositories // 返回的函数，它的行为与将其定义在 methods 选项中的行为相同
    }
  }
})
```

目前 `repositories` 是个非响应式变量，用户层面将无法感知它的变化，仓库列表将始终为空。

### 带 `ref` 的响应式变量 {#reactive-variable-with-ref}

同 Vue3 一致，我们可以通过 `ref` 函数为任意一个变量创建响应式引用，`ref` 接收参数并将其包裹在一个带有 `value` property 的对象中返回，然后可以使用该 property 访问或更改响应式变量的值，简单示例如下：

```js
import { ref } from '@mpxjs/core'

const counter = ref(0)

console.log(counter) // { value: 0 }
console.log(counter.value) // 0

counter.value++
console.log(counter.value) // 1
```

回到我们的示例中，我们通过 `ref` 创建一个响应式的 `repositories` 变量：

```js
import { createComponent, ref } from '@mpxjs/core'
import { fetchUserRepositories } from '@/api/repositories'

createComponent({
  properties: {
    user: String
  },
  setup (props) {
    let repositories = ref([])
    const getUserRepositories = async () => {
      repositories.value = await fetchUserRepositories(props.user)
    }

    return {
      repositories,
      getUserRepositories
    }
  }
})
```

通过 `ref` 包裹以后，我们每次调用 `getUserRepositories` 更新 `repositories` 的值都能被外部的 `watch` 观测到，并且触发视图的更新。

### 在 `setup` 中注册生命周期钩子 {#lifecycle-hooks-in-setup}

为了完整实现选项式 API 中的能力，我们需要支持在 `setup` 中注册生命周期钩子，同 Vue3 类似，我们也提供了一系列生命周期钩子的注册函数，这些函数都以 `on` 开头，不过由于 Mpx 的跨平台特性，我们不可能针对不同的平台提供不同的生命周期钩子函数，因此我们提供了一份抹平跨平台差异后统一的生命周期钩子，与小程序原生生命周期的映射关系可查看[这里](#lifecycle-hooks)。

我们希望在组件挂载时调用 `getUserRepositories`，可以使用 `onMounted` 钩子来实现，注意这里不是 `onReady`，不过它确实对应于微信小程序中组件的 `ready` 钩子：

```js
import { createComponent, ref, onMounted } from '@mpxjs/core'
import { fetchUserRepositories } from '@/api/repositories'

createComponent({
  properties: {
    user: String
  },
  setup (props) {
    let repositories = ref([])
    const getUserRepositories = async () => {
      repositories.value = await fetchUserRepositories(props.user)
    }
    
    // 在组件挂载时（微信小程序中相当于ready）调用 getUserRepositories
    onMounted(getUserRepositories) 

    return {
      repositories,
      getUserRepositories
    }
  }
})
```

### `watch` 响应式更改 {#watch-reactive-change}

现在我们需要对 `user` prop 的变化做出响应，可以使用新的 `watch` API，该 API 接受 3 个参数：

* 一个想要侦听的响应式引用或 getter 函数
* 一个回调
* 可选的配置选项

简单示例如下：

```js
import { ref, watch } from '@mpxjs/core'

const counter = ref(0)
watch(counter, (newValue, oldValue) => {
  console.log('The new counter value is: ' + counter.value)
})
```

当 `counter` 被修改时，例如 `counter.value = 5`，侦听将触发并执行回调打印 `The new counter value is:5`。

回到我们的示例中，当 `user` prop 发生变化时调用 `getUserRepositories` 更新仓库列表：

```js
import { createComponent, ref, onMounted, watch, toRefs } from '@mpxjs/core'
import { fetchUserRepositories } from '@/api/repositories'

createComponent({
  properties: {
    user: String
  },
  setup (props) {
    // 使用 `toRefs` 创建对 `props` 中的 `user` property 的响应式引用
    const { user } = toRefs(props)
    
    let repositories = ref([])
    const getUserRepositories = async () => {
      // 更新 `prop.user` 到 `user.value` 访问引用值
      repositories.value = await fetchUserRepositories(user.value)
    }
    
    onMounted(getUserRepositories) 
    
    // 在 user prop 的响应式引用上设置一个侦听器
    watch(user, getUserRepositories)

    return {
      repositories,
      getUserRepositories
    }
  }
})
```

你可能已经注意到在我们的 setup 的顶部使用了 toRefs。这是为了确保我们的侦听器能够根据 user prop 的变化做出反应。

### 独立的 `computed` 属性 {#independent-computed}

与 `ref` 和 `watch` 类似，也可以使用从 Mpx 导入的 `computed` 函数创建计算属性，简单示例如下：

```js
import { ref, computed } from '@mpxjs/core'

const counter = ref(0)
const twiceTheCounter = computed(() => counter.value * 2)

counter.value++
console.log(counter.value) // 1
console.log(twiceTheCounter.value) // 2
```

这里我们给 `computed` 函数传递了第一个参数，它是一个类似 getter 的回调函数，输出的是一个只读的响应式引用。为了访问新创建的计算变量的 value，我们需要像 `ref` 一样使用 `.value` property。

回到我们的示例，我们通过 `computed` 为仓库列表实现搜索功能：

```js
import { createComponent, ref, onMounted, watch, toRefs, computed } from '@mpxjs/core'
import { fetchUserRepositories } from '@/api/repositories'

createComponent({
  properties: {
    user: String
  },
  setup (props) {
    const { user } = toRefs(props)
    
    let repositories = ref([])
    const getUserRepositories = async () => {
      repositories.value = await fetchUserRepositories(user.value)
    }
    
    onMounted(getUserRepositories) 
    
    watch(user, getUserRepositories)
    
    const searchQuery = ref('')
    const repositoriesMatchingSearchQuery = computed(() => {
      return repositories.value.filter(
        repository => repository.name.includes(searchQuery.value)
      )
    })

    return {
      repositories,
      getUserRepositories,
      searchQuery,
      repositoriesMatchingSearchQuery
    }
  }
})
```

可以看到目前我们的 `setup` 函数已经相当庞大了，在不进行任何封装的情况下我们很可能在 `setup` 中写出流水账式的代码，可维护性很差，这也是为什么组合式 API 会对开发者的代码风格提出更高的要求，下面我们来拆解目前已经实现的功能，将它们提取到独立的组合函数中，先从创建 `useUserRepositories` 函数开始：

```js
// src/composables/useUserRepositories.js

import { fetchUserRepositories } from '@/api/repositories'
import { ref, onMounted, watch } from '@mpxjs/core'

export default function useUserRepositories(user) {
  const repositories = ref([])
  const getUserRepositories = async () => {
    repositories.value = await fetchUserRepositories(user.value)
  }

  onMounted(getUserRepositories)
  watch(user, getUserRepositories)

  return {
    repositories,
    getUserRepositories
  }
}

```

然后是搜索功能：

```js
// src/composables/useRepositoryNameSearch.js

import { ref, computed } from '@mpxjs/core'

export default function useRepositoryNameSearch(repositories) {
  const searchQuery = ref('')
  const repositoriesMatchingSearchQuery = computed(() => {
    return repositories.value.filter(repository => {
      return repository.name.includes(searchQuery.value)
    })
  })

  return {
    searchQuery,
    repositoriesMatchingSearchQuery
  }
}
```

现在我们有了两个单独的功能模块，接下来就可以开始在组件中使用它们了:

```js
import useUserRepositories from '@/composables/useUserRepositories'
import useRepositoryNameSearch from '@/composables/useRepositoryNameSearch'
import { createComponent, toRefs } from '@mpxjs/core'


createComponent({
  properties: {
    user: String
  },
  setup (props) {
    const { user } = toRefs(props)
    
    const { repositories, getUserRepositories } = useUserRepositories(user)
    
    const {
      searchQuery,
      repositoriesMatchingSearchQuery
    } = useRepositoryNameSearch(repositories)

    return {
      // 因为我们并不关心未经过滤的仓库
      // 我们可以在 `repositories` 名称下暴露过滤后的结果
      repositories: repositoriesMatchingSearchQuery,
      getUserRepositories,
      searchQuery,
    }
  }
})
```

现在我们使用组合式 API 完成了仓库列表组件的开发，它看上去相当清晰且易于维护。想要了解更多组合式 API 的信息，请继续查看本页接下来的章节，想要了解新的响应式 API 的使用，请跳转查看[响应式 API](reactive-api.md)章节。

## Setup

`setup` 函数在组件创建时执行，返回组件所需的数据和方法，是组合式 API 的核心。

> 注意，`setup` 函数不可被混入，所有定义在 `mixin` 中的 `setup` 都将被丢弃。

### 参数 {#parameters}

`setup` 函数接受两个参数，分别是 `props` 和 `context`。

#### Props

`setup` 函数的第一个参数 `props` 和 Vue3 中完全一致，就是包含当前组件 props 的响应式数据，当父组件更新某个 prop 时，该数据也将被更新。

```js
import { createComponent } from '@mpxjs/core'

createComponent({
  props: {
    title: String
  },
  setup(props) {
    console.log(props.title)
  }
})
```

> Warning: `props` 是响应式的，你不能使用 ES6 解构，它会消除 prop 的响应性。

如果需要解构 prop，可以在 `setup` 函数中使用 `toRefs` 函数将其转换一个包含 ref 数据的纯对象：

```js
import { createComponent, toRefs } from '@mpxjs/core'

createComponent({
  props: {
    title: String
  },
  setup(props) {
    const { title } = toRefs(props)
    // `title` 是一个 ref
    console.log(title.value)
  }
})
```

如果 `title` 是可选的 prop，则传入的 `props` 中可能没有 `title` 。在这种情况下，`toRefs` 将不会为 `title` 创建一个 ref 。你需要使用 `toRef` 替代它：

```js
import { createComponent, toRef } from '@mpxjs/core'

createComponent({
  props: {
    title: String
  },
  setup(props) {
    const title = toRef(props, 'title')
    // `title` 是一个 ref
    console.log(title.value)
  }
})
```

#### Context

由于小程序与 web 基础技术规范的差异，Mpx 中 `setup` 的第二个参数 `context` 与 Vue3 中完全不同，`context` 包含的属性如下：

```js
import { createComponent } from '@mpxjs/core'

createComponent({
  setup(props, context) {
    // 触发事件，等价于 this.triggerEvent
    console.log(context.triggerEvent)
    // 获取 NodesRef/组件实例，等价于 this.$refs
    console.log(context.refs)
    // 字节小程序中异步获取组件实例，等价于 this.$asyncRefs
    console.log(context.asyncRefs)
    // 获取组件实例，等价于 this.selectComponent，可用 this.$refs 替代
    console.log(context.selectComponent)
    // 批量获取组件实例，等价于 this.selectAllComponents，可用 $refs 替代
    console.log(context.selectAllComponents)
    // 获取 SelectorQuery 对象实例查询元素布局信息，等价于 this.createSelectorQuery，可用 $refs 替代
    console.log(context.createSelectorQuery)
    // 获取 IntersectionObserver 对象实例查询视图相交信息，等价于 this.createIntersectionObserver
    console.log(context.createIntersectionObserver)
  }
})
```

`context` 是一个普通的 JavaScript 对象，也就是说，它不是响应式的，这意味着你可以安全地对 `context` 使用 ES6 解构。

```js
import { createComponent } from '@mpxjs/core'

createComponent({
  setup(props, { triggerEvent, refs }) {
    // ...
  }
})
```

`refs` 是有状态的对象，它会随组件本身的更新而更新。这意味着你应该避免对其进行解构，并始终以 refs.x 的方式访问 NodesRef 或组件实例。与 props 不同，refs 是非响应式的。如果你打算根据 refs 的更改应用副作用，那么应该在 onUpdated 生命周期钩子中执行此操作。

### 访问组件的 property {#access-component-property}

除了 `props` 和 `context` 中包含的内容，执行 `setup` 时将**无法访问**部分组件选项，包括：

* data
* computed

### 结合模板使用 {#usage-with-template}

如果 `setup` 返回一个对象，那么该对象的 property 可以在模板中访问到：

```html
<template>
  <view>{{ collectionName }}: {{ readersNumber }} {{ book.title }}</view>
</template>

<script>
  import { createComponent, ref, reactive } from '@mpxjs/core'

  createComponent({
    properties: {
      collectionName: String
    },
    setup(props) {
      const readersNumber = ref(0)
      const book = reactive({ title: 'Mpx' })

      // 暴露给 template
      return {
        readersNumber,
        book
      }
    }
  })
</script>
```

### 使用 `this` {#use-this}

**在 `setup()` 内部，`this` 不是当前组件的引用**，因为 `setup()` 是在解析其它组件选项之前被调用的，所以 `setup()` 内部的 `this` 的行为与其它选项中的 `this` 完全不同。这使得 `setup()`  在和其它选项式 API 一起使用时可能会导致混淆。

> Mpx 的组合式 API 设计极力避免了用户需要在 `setup()` 中访问 `this` 的场景，不过在一些例外情况下，用户仍然可以通过 `getCurrentInstance()` 的方式获取到当前组件实例，注意该函数必须在 `setup()` 或生命周期钩子中同步调用。

## 生命周期钩子 {#lifecycle-hooks}

组合式 API 中，我们通过 `on${Hookname}(fn)` 的方式注册访问生命周期钩子。

Mpx 作为一个跨端小程序框架，需要兼容不同小程序平台不同的生命周期，在选项式 API 中，我们在框架中内置了一套统一的生命周期，将不同小程序平台的生命周期转换映射为内置生命周期后再进行统一的驱动，以抹平不同小程序平台生命周期钩子的差异，如微信小程序的 `attached` 钩子和支付宝小程序的 `onInit` 钩子，在组合式 API 中，我们基于框架内置的生命周期暴露了一套统一的生命周期钩子函数，下表展示了框架内置生命周期/组合式 API 生命周期函数与不同小程序平台原生生命周期的对应关系：

#### 组件生命周期 {#component-lifecycle}

|框架内置生命周期|Hook inside `setup`|微信原生|支付宝原生|
|:------------|:------------------|:-----|:-------|
| BEFORECREATE | `null` |attached（数据响应初始化前）|onInit（数据响应初始化前）|
| CREATED | `null` |attached（数据响应初始化后）|onInit（数据响应初始化后）|
| BEFOREMOUNT | onBeforeMount |ready（`MOUNTED` 执行前）|didMount（`MOUNTED` 执行前）|
| MOUNTED | onMounted |ready（`BEFOREMOUNT` 执行后）|didMount（`BEFOREMOUNT` 执行后）|
| BEFOREUPDATE | onBeforeUpdate |`null`（`setData` 执行前）|`null`（`setData` 执行前）|
| UPDATED | onUpdated |`null`（`setData` callback）|`null`（`setData` callback）|
| BEFOREUNMOUNT | onBeforeUnmount |detached（数据响应销毁前）|didUnmount（数据响应销毁前）|
| UNMOUNTED | onUnmounted |detached（数据响应销毁后）|didUnmount（数据响应销毁后）|

> 同 Vue3 一样，组合式 API 中没有提供 `BEFORECREATE` 和 `CREATED` 对应的生命周期钩子函数，用户可以直接在 `setup` 中编写相关逻辑。

> 除支付宝外的小程序平台支持使用Component构建页面，在页面中使用组件生命周期钩子与在组件中完全一致，并且框架在支付宝环境也进行了抹平实现。

#### 页面生命周期 {#page-lifecycle}

|框架内置生命周期|Hook inside `setup`|微信原生|支付宝原生|
|:------------|:------------------|:-----|:-------|
|ONLOAD|onLoad|onLoad|onLoad|
|ONSHOW|onShow|onShow|onShow|
|ONHIDE|onHide|onHide|onHide|
|ONRESIZE|onResize|onResize|events.onResize|

#### 组件中访问页面生命周期 {#access-page-lifecycle-in-component}

|框架内置生命周期|Hook inside `setup`|微信原生|支付宝原生|
|:------------|:------------------|:-----|:-------|
|ONSHOW|onShow|pageLifetimes.show|`null`（框架抹平实现）|
|ONHIDE|onHide|pageLifetimes.hide|`null`（框架抹平实现）|
|ONRESIZE|onResize|pageLifetimes.resize|`null`（框架抹平实现）|

下面是简单的使用示例：

```js
import { createComponent, onMounted, onUnmounted } from '@mpxjs/core'

createComponent({
  setup () {
    // mounted
    onMounted(()=>{
      console.log('Component mounted.')
    })
    // unmounted
    onUnmounted(()=>{
      console.log('Component unmounted.')
    })
    return {}
  }
})
```

### 框架内置生命周期 {#framework-built-in-lifecycle}

从上面可以看到我们在框架内部内置了一套统一的生命周期来抹平不同平台生命周期的差异，由于存在数据响应机制，这套内置生命周期与小程序原生的生命周期不完全一一对应，反而与 Vue 的生命周期更加相似，在过去的版本中，我们没有显式地暴露出 `BEFORECREATE` 这这类框架内置的生命周期，更多都在框架内部使用，但是在组合式 API 版本中，为了使选项式 API 的生命周期能力与之对齐，我们将框架内置的生命周期显式导出，让用户在选项式 API 开发环境下也能正常使用这些能力，简单使用示例如下：

```js
import { createComponent, BEFORECREATE } from '@mpxjs/core'

createComponent({
  [BEFORECREATE] () {
    console.log('beforeCreate exec.')
  },
  created () {
    // 原生的 created 会被映射为框架内部的 CREATED 执行，此处逻辑在 BEFORECREATE 后执行
    console.log('created exec.')
  }
})
```

### 具有副作用的页面事件 {#page-events-with-side-effects}

在小程序中，一些页面事件的注册存在副作用，即该页面事件注册与否会产生实质性的影响，比如微信中的 `onShareAppMessage` 和 `onPageScroll`，前者在不注册时会禁用当前页面的分享功能，而后者在注册时会带来视图与逻辑层之间的线程通信开销，对于这部分页面事件，我们无法通过`预注册 -> 驱动`方式提供组合式 API 的注册方式，用户可以通过选项式 API 的方式来注册使用，通过 `this` 访问组合式 API `setup` 函数的返回。

然而这种使用方式显然不够优雅，我们考虑是否可以通过一些非常规的方式提供这类副作用页面事件的组合式 API 注册支持，例如，借助编译手段。我们在运行时提供了副作用页面事件的注册函数，并在编译时通过 `babel` 插件的方式解析识别到当前页面中存在这些特殊注册函数的调用时，通过框架已有的`编译 -> 运行时注入`的方式将事件驱动逻辑添加到当前页面当中，以提供相对优雅的副作用页面事件在组合式 API 中的注册方式，同时不产生非预期的副作用影响。

我们需要先修改 `babel` 配置添加 `@mpxjs/babel-plugin-inject-page-events` 插件：

```json5
// babel.config.json
{
 "plugins": [
    [
      "@babel/transform-runtime",
      {
        "corejs": 3,
        "version": "^7.10.4"
      }
    ],
    "@mpxjs/babel-plugin-inject-page-events"
  ]
}
```

然后就能想普通生命周期一样使用组合式 API 进行页面事件注册，简单示例如下：

```js
import { createComponent, ref, onShareAppMessage } from '@mpxjs/core'

createComponent({
  setup () {
    const count = ref(0)

    onShareAppMessage(() => {
      return {
        title: '页面分享'
      }
    })

    return {
      count
    }
  }
})
```

目前我们通过这种方式支持的页面事件如下：

| 页面事件 | Hook inside `setup` | 平台支持 |
|:------------|:------------------|:-----|
| onPullDownRefresh | onPullDownRefresh | 全小程序平台 + web |
| onReachBottom | onReachBottom | 全小程序平台 + web |
| onPageScroll | onPageScroll | 全小程序平台 + web |
| onShareAppMessage | onShareAppMessage | 全小程序平台 |
| onTabItemTap | onTabItemTap | 微信/支付宝/百度/QQ |
| onAddToFavorites | onAddToFavorites | 微信 / QQ |
| onShareTimeline | onShareTimeline | 微信 |
| onSaveExitState | onSaveExitState | 微信 |

> 特别注意，由于静态编译分析实现方式的限制，这类页面事件的组合式 API 使用需要满足页面事件注册函数的调用和 `createPage` 的调用位于同一个 js 文件当中。

## 模板引用 {#template-ref}

在 Vue3 的组合式 API 中，我们可以在 `setup` 函数中使用 `ref()` 创建引用数据获取模板中绑定了 `ref` 属性的组件或 DOM 节点，优雅地将**响应式引用**和**模板引用**进行了关联统一，但在 Mpx 中，受限于小程序的技术限制，我们无法在低性能损耗下实现相同的设计，因此我们在 setup 的 context 参数中提供了 refs 对象，结合模板中的`wx:ref`指令使用，与选项式 API 中的 $refs 保持一致。

下面是组合式 API 中进行模板引用的使用示例：

```html
<template>
  <view bindtap="handleHello" wx:ref="hello">hello</view>
  <view wx:if="{{showWorld}}" wx:ref="world">world</view>
  <view wx:for="{{list}}" wx:ref="list">{{item}}</view>
</template>

<script>
  import { createComponent, ref, onMounted, nextTick } from '@mpxjs/core'

  createComponent({
    setup (props, { refs }) {
      const showWorld = ref(false)
      const list = ref(['手机', '电视', '电脑'])

      onMounted(() => {
        // 最早在 onMounted 中才能访问refs，对于节点返回 NodesRef 对象，对于组件返回组件实例
        console.log('hello ref:', refs.hello)
        // 在循环中定义 wx:ref，对应的 refs 返回数组
        console.log('list ref:', refs.list)
      })

      const handleHello = () => {
        showWorld.value = true
        nextTick(() => {
          // 数据变更后要在 nextTick 中访问更新后的视图数据
          console.log('world ref:', refs.world)
        })
      }
      
      // 暴露给 template
      return {
        showWorld,
        handleHello,
        list
      }
    }
  })
</script>
```

## `<script setup>`

和 Vue 类似，`<script setup>` 是在 Mpx 单文件组件中使用组合式 API 时的编译时语法糖。不过受小程序底层技术限制，在 Mpx 中 `<script setup>` 无法完整提供其在 Vue 中所具备的相关优势，我们提供了这个语法能力，但不作为默认的推荐选项。

### 基本语法 {#basic-syntax}

启用该语法需要在 `<script>` 代码块上添加 `setup` attribute:

```html
<script setup>
    console.log('hello Mpx script setup')
</script>
```

`<script>` 里边的代码会被编译成组件 `setup()` 函数的内容。

### 顶层的绑定会被暴露给模版 {#top-level-bindings-exposed}

> 从 v2.8.19 开始，顶层绑定自动暴露给模板的能力被取消，构建时会强制用户通过 `defineExpose` 手动声明需要暴露给模板的数据或方法。

和 Vue 一样，当使用 `<script setup>` 时，任何在 `<script setup>` 声明的顶层的绑定（包括变量，函数声明，以及 import 导入的内容） 都能在模版中直接使用：

```html
<script setup>
    import { ref } from '@mpxjs/core'
    const msg = ref('hello');
    function log() {
        console.log(msg.value)
    }
</script>
<template>
    <view>msg: {{msg}}</view>
    <view ontap="log">click</view>
</template>
```

import 导入的内容，除了从 `@mpxjs/core` 中导入的变量或方法，其他模块导入的属性和方法全部都会暴露给模版。这意味着我们可以直接在模版中使用引入的相关方法，而不需要通过 `methods` 选项来暴露：

```html
<template>
    <view ontap="clickTrigger">click</view>
</template>
<script setup>
    import { clickTrigger } from './utils'
</script>
```

> 注意项：如果你 `script setup` 中有较多对象或方法的声明和引入，比如全局 store 这种十分复杂的对象，走默认逻辑暴露给模版会造成性能问题，因此需要使用 `defineExpose` 来手动定义暴露给模版的数据和方法。

### 响应式 {#reactivity}

和 Vue 中一样，响应式状态需要明确使用响应性 API 来创建。和 `setup()` 函数的返回值一样，ref 在模版中使用的时候会自动解包：

```html
<template>
    <button ontap="addCount">{{count}}</button>
</template>
<script setup>
    import { ref } from '@mpxjs/core'
    const count = ref(0)
    function addCount() {
        count.value++
    }
</script>
```

### `defineProps()`

和 Vue 类似，为了在声明小程序组件 `properties` 选项时获得完整的类型推导支持，在 `<script setup>` 中，我们需要使用 `defineProps` API，它默认在 `<script setup>` 中可用：

```html
<script setup>
    const props = defineProps({
        testA: String
    })
</script>
```

* `defineProps` 是只能在 `<script setup>` 中使用的**编译宏**，不需要手动导入，会跟随 `<script setup>` 的处理过程一同被编译掉。
* `defineProps` 接收与小程序 `properties` 选项相同的值。
* 传入到 `defineProps` 的选项会从 setup 中提升到模块的作用域。因此传入的选项不能引用在 setup 作用域中声明的局部变量，否则会导致编译错误，不过可以引入导入的绑定。

### `defineExpose()`

在 `<script setup>` 中定义暴露给模版的变量和方法，在 Mpx `<script setup>` 中属于**强制要求**，若不使用该编译宏，则会构建报错。

Mpx 中的 defineExpose 和 Vue3 中的不尽相同，在 Vue3 中，使用 `<scrip setup>` 的组件默认是关闭的-即通过模版引用或者 `$parent` 链获取到的组件实例中不会暴露任何在`<script setup>` 中声明的绑定。

在 Mpx 中，`<script setup>` 中的声明绑定都会挂载到组件实例中，都可以通过组件实例来访问，Mpx `defineExpose` 更大的作用是假如你在 `<scrip setup>` 中引入了一些 store 实例，这些 store 实例默认会挂载到组件实例中，会导致后续的响应式处理以及组件更新速度变慢，这里我们通过强制使用
`defineExpose` 来规避掉这个问题。

```html
<script setup>
    const count = ref(0)
    const name = ref('black')
    defineExpose({
        name
    })
</script>
<template>
    <!--正确渲染 black-->
    <view>{{name}}</view>
    <!--找不到对应变量，无内容-->
    <view>{{count}}</view>
</template>
```

### `defineOptions()`

此编译宏相较于 Vue 是 Mpx 中独有的，主要是当开发者想在 `<script setup>` 中使用一些微信小程序中特有的选项式，例如 relations、moved 等，可以使用该编译宏进行定义。

```html
<script setup>
    defineOptions({
        pageLifetimes: {
            // 组件所在页面的生命周期函数
            resize: function () { }
        }
    })
</script>
```

* `defineOptions` 是只能在 `<script setup>` 中使用的**编译宏**，不需要手动导入，会跟随 `<script setup>` 的处理过程一同被编译掉。
* `defineOptions` 无返回值。
* `defineOptions` 中的选项会无脑提升至组件或页面构造器的选项之中，因此不可引用 setup 中的局部变量。

### `useContext()`

在 `<script setup>` 中，当我们想要使用 `context` 时，可以使用 `useContext()` 来获 `context` 对象。

```html
<script setup>
    const context = useContext()
    // 获取 NodesRef/组件实例，等价于 this.$refs
    console.log(context.refs)
</script>
```

### 针对 TypeScript 的功能 {#ts-features}

#### 类型 props 的声明 {#props-declaration}

props 可以通过给 `defineProps` 传递纯类型函数的方式来声明：

```ts
    const props = defineProps<{
        foo: string,
        bar: number
    }>()

    // 构建转换为
    {
        properties: {
            foo: {
                type: String
            },
            bar: {
                type: Number
            }
        }
    }
```

* `defineProps` 要么使用运行时声明，要么使用类型声明。同时使用两种方式会导致编译报错。
* 小程序中 `defineProps` 类型声明若有 optional 不会生效，因为小程序的 props 只要声明则一定会存在
* 类型声明参数必须是一下内容之一，以确保正确的静态分析：
  * 类型字面量
  * 在同一文件中的接口或者类型字面量的引用

#### 使用类型声明时的默认 props 值 {#default-props-value}

和 Vue3 一样，针对类型的 `defineProps` 声明的不足，它无法给 props 提供默认值。为了解决这个问题，我们也支持了 `withDefaults` 编译宏：

```ts
export interface Props {
  msg: string
  labels: string
}

const props = withDefaults(defineProps<Props>(), {
  msg: 'hello',
  labels: 'world'
})
```

上边代码会被编译为等价的运行时 props 的 `value` 选项。

* 小程序 properties 定义中的 optionalTypes 和 observer 字段，无法使用 TypeScript 类型声明的方式定义，如果需要定义这两个字段，目前需要使用运行时的方式来定义。

### 限制 {#limitations}

由于模块执行语义的差异，`<script setup>` 中的代码依赖单文件组件的上下文，如果将其移动到外部的 `.js` 或者 `.ts` 的时候，对于开发者可工具来说都十分混乱。因此 `<script setup>` 不能和 `src` attribute 一起使用。

## 组合式 API 与 Vue3 中的区别 {#diff-composition-api-vue3}

下面我们来总结一下 Mpx 中组合式 API 与 Vue3 中的区别：

* `setup` 的 `context` 参数不同，详见[这里](#context)
* `setup` 不支持返回**渲染函数**
* `setup` 不能是异步函数
* `<script setup>` 提供的宏方法不同，详见[这里](#script-setup)
* `<script setup>` 不支持 `import` 快捷引入组件
* `<script setup>` 必须使用 [defineExpose](#defineexpose)
* 支持的生命周期钩子不同，详见[这里](#lifecycle-hooks)
* 模板引用的方式不同，详见[这里](#template-ref)

## 组合式 API 周边生态能力的使用 {#ecosystem-usage}

我们对 Mpx 提供的周边生态能力也都进行了组合式 API 适配升级，详情如下：

* `store` 在组合式 API 中使用，详见[这里](../advance/store.md#use-store-in-composition-api)
* `pinia` 在组合式 API 中使用，详见[这里](../advance/pinia.md)
* `fetch` 在组合式 API 中使用，详见[这里](../extend.md#usefetch)
* `i18n` 在组合式 API 中使用，详见[这里](../advance/i18n.md#composition-api-usage)

---

---
url: /guide/composition-api/reactive-api.md
---
# 响应式 API {#reactive-api}

在 Mpx 中，为了支持[组合式 API](composition-api.md) 的使用，我们参考 Vue3 提供了相关的响应式 API，但由于 `proxy` 目前仍然存在浏览器兼容性问题，我们在底层还是基于 `Object.defineProperty` 实现的数据响应，因此相较于 Vue3 提供的 API 存在一些删减，同时也存在与 Vue2 一样的数据响应[使用限制](https://v2.cn.vuejs.org/v2/guide/reactivity.html#%E6%A3%80%E6%B5%8B%E5%8F%98%E5%8C%96%E7%9A%84%E6%B3%A8%E6%84%8F%E4%BA%8B%E9%A1%B9)。

## 创建响应式对象 {#create-reactive-object}

在 Mpx 中，我们可以使用 `reactive` 方法将一个 JavaScript 对象**深度转换**为响应式对象，当对象内数据发生变化时能够被系统感知，相当于 Vue2 中的 `observable`，需要注意的是在 Mpx 中 `reactive()` 是将传入的对象进行响应性转化后返回原对象，而在 Vue3 中则会基于 `proxy` API 返回传入对象的响应式代理。

目前 `reactive` 仅支持传入基础对象类型，包括纯对象和数组，暂不支持 `Map` 和 `Set` 这样的集合类型。

```js
import { reactive } from '@mpxjs/core'

// 响应式对象
const state = reactive({
  count: 0
})
```

你可以在[响应式基础 API](../../api/reactivity-api.md#reactive) 章节中了解更多关于 `reactive` 的信息。

## 使用`ref()`创建独立的响应式值 {#use-ref-create-reactive-value}

上面提到 `reactive` 只能传入对象类型数据，当我们想将一个原始数据类型的值（如数字、字符串、布尔值）变成响应式时，我们不得不先将其包装为一个对象，使用起来较为繁琐，新的 `ref` 方法能够让我们便捷地达成上述目标：

```js
import { ref } from '@mpxjs/core'

// 响应式值
const count = ref(0)
```

`ref()` 会返回一个可变的响应式对象，该对象作为一个**响应式引用**通过 `value` 属性维护着传入的内部值：

```js
import { ref } from '@mpxjs/core'

const count = ref(0)
console.log(count.value) // 0

count.value++
console.log(count.value) // 1
```

### Ref 解包 {#ref-unwrapping}

当 `ref` 作为渲染上下文 (从 `setup()` 中返回的对象) 上的 property 返回并可以在模板中被访问时，它将自动浅层次解包内部值。只有访问嵌套的 ref 时需要在模板中添加 `.value`：

```html
<template>
  <view>
    <view>{{ count }}</view>
    <view>{{ nested.count.value }}</view>
  </view>
</template>

<script>
  import { createComponent, ref } from '@mpxjs/core'
   
  createComponent({
    setup() {
      const count = ref(0)
      return {
        count,
        nested: {
          count
        }
      }
    }
  }
</script>
```

### 访问响应式对象 {#access-reactive-object}

当 `ref` 作为响应式对象的 property 被访问或更改时，为使其行为类似于普通 property，它会自动解包内部值：

```js
const count = ref(0)
const state = reactive({
  count
})

console.log(state.count) // 0

state.count = 1
console.log(count.value) // 1
```

如果将新的 ref 赋值给现有 ref 的 property，将会替换旧的 ref：

```js
const otherCount = ref(2)

state.count = otherCount
console.log(state.count) // 2
console.log(count.value) // 1
```

Ref 解包仅发生在被响应式 `Object` 嵌套的时候。当从 `Array` 访问 ref 时，不会进行解包：

```js
const arr = reactive([ref('Hello world')])
// 这里需要 .value
console.log(arr[0].value)
```

## 响应式对象解构 {#reactive-object-destructure}

当我们想使用大型响应式对象的一些 property 时，可能很想使用 **ES6 解构**来获取我们想要的 property：

```js
import { reactive } from '@mpxjs/core'

const people = reactive({
  name: 'hiyuki',
  age: 26,
  gender: 'male',
  city: 'Beijing'
})

let { name, age } = people
```

遗憾的是，使用解构的两个 property 的响应性都会丢失。对于这种情况，我们需要将我们的响应式对象转换为一组 ref。这些 ref 将保留与源对象的响应式关联：

```js
import { reactive, toRefs } from '@mpxjs/core'

const people = reactive({
  name: 'hiyuki',
  age: 26,
  gender: 'male',
  city: 'Beijing'
})

let { name, age } = toRefs(people)
age.value = 30 // age 现在是个 ref，我们需要使用 .value 进行访问，对其进行修改也将直接作用在原响应式对象中
console.log(people.age) // 30
```

你可以在[Refs API](../../api/reactivity-api.md#refs) 章节中了解更多关于 `refs` 的信息。

## 计算值 {#computed-values}

有时我们需要依赖于其他状态的状态——在 选项式 API 中，这是用组件计算属性处理的，在新的组合式 API 中，我们可以使用 `computed` 函数直接创建计算值：它接受 getter 函数并为 getter 返回的值返回一个不可变的响应式 ref 对象。

```js
import { ref, computed } from '@mpxjs/core'

const count = ref(1)
const plusOne = computed(() => count.value + 1)

console.log(plusOne.value) // 2

plusOne.value++ // error
```

或者，可以使用一个带有 get 和 set 函数的对象来创建一个可写的 ref 对象。

```js
import { ref, computed } from '@mpxjs/core'

const count = ref(1)
const plusOne = computed({
  get: () => count.value + 1,
  set: val => {
    count.value = val - 1
  }
})

plusOne.value = 1
console.log(count.value) // 0
```

## `watchEffect`

为了根据响应式状态自动应用和重新应用副作用，我们可以使用 `watchEffect` 函数。它立即执行传入的一个函数，同时响应式追踪其依赖，并在其依赖变更时重新运行该函数。

```js
const count = ref(0)

watchEffect(() => console.log(count.value))
// -> logs 0

setTimeout(() => {
  count.value++
  // -> logs 1
}, 100)
```

### 停止侦听 {#stop-watching}

当 `watchEffect` 在组件的 [setup()](composition-api.md#setup) 函数或[生命周期钩子](composition-api.md#lifecycle-hooks)被调用时，侦听器会被链接到该组件的生命周期，并在组件卸载时自动停止。

在一些情况下，也可以显式调用返回值以停止侦听：

```js
const stop = watchEffect(() => {
  /* ... */
})

// later
stop()
```

### 清除副作用 {#cleanup-side-effect}

有时副作用函数会执行一些异步的副作用，这些响应需要在其失效时清除 (即完成之前状态已改变了) 。所以侦听副作用传入的函数可以接收一个 `onInvalidate` 函数作入参，用来注册清理失效时的回调。当以下情况发生时，这个失效回调会被触发：

* 副作用即将重新执行时
* 侦听器被停止 (如果在 `setup()` 或生命周期钩子函数中使用了 `watchEffect`，则在组件卸载时)

```js
watchEffect(onInvalidate => {
  const token = performAsyncOperation(id.value)
  onInvalidate(() => {
    // id has changed or watcher is stopped.
    // invalidate previously pending async operation
    token.cancel()
  })
})
```

之所以是通过传入一个函数去注册失效回调，而不是从回调返回它，是因为返回值对于异步错误处理很重要。

在执行数据请求时，副作用函数往往是一个异步函数：

```js
const data = ref(null)
watchEffect(async onInvalidate => {
  onInvalidate(() => {
    /* ... */
  }) // 在Promise解析之前注册清除函数
  data.value = await fetchData(props.id)
})
```

我们知道异步函数都会隐式地返回一个 Promise，但是清理函数必须要在 Promise 被 resolve 之前被注册。

### 副作用刷新时机 {#side-effect-flush-timing}

默认情况下，数据发生变更时，关联的副作用会被推入异步队列中，进行异步刷新，这样可以避免同一个“tick” 中多个状态改变导致的不必要的重复调用。在核心的具体实现中，组件的 `render` 函数也是一个被侦听的副作用。当一个用户定义的副作用函数进入队列时，默认情况下，会在所有的组件 `render` 前执行：

```html
<template>
  <view>{{ count }}</view>
</template>

<script>
import { createComponent, ref, watchEffect } from '@mpxjs/core'

createComponent({
  setup() {
    const count = ref(0)

    watchEffect(() => {
      console.log(count.value)
    })

    return {
      count
    }
  }
})
</script>
```

在这个例子中：

* `count` 会在初始运行时同步打印出来
* 更改 `count` 时，将在组件**更新前**执行副作用。

如果需要在组件更新(例如：当与[模板引用](composition-api.md#template-ref)一起)后重新运行侦听器副作用，我们可以传递带有 `flush` 选项的附加 `options` 对象 (默认为 `'pre'`)：

```js
// 在组件更新后触发，这样你就可以访问更新的 DOM。
// 注意：这也将推迟副作用的初始运行，直到组件的首次渲染完成。
watchEffect(
  () => {
    /* 访问视图 */
  },
  {
    flush: 'post'
  }
)
```

`flush` 选项还接受 `sync`，这将强制效果始终同步触发。然而，这是低效的，应该很少需要。

与此同时，我们还提供了 `watchPostEffect` 和 `watchSyncEffect` 别名用来让代码意图更加明显。

## `watch`

`watch` API 相当于选项式 API 中的 `watch property`。`watch` 需要侦听特定的数据源，并在回调函数中执行副作用。默认情况下，它也是惰性的，即只有当被侦听的源发生变化时才执行回调。

* 与 [watchEffect](#watcheffect) 比较，`watch` 允许我们：
  * 懒执行副作用；
  * 更具体地说明什么状态应该触发侦听器重新运行；
  * 访问侦听状态变化前后的值。

### 侦听单个数据源 {#watch-single-source}

侦听器数据源可以是返回值的 getter 函数，也可以直接是 `ref`：

```js
// 侦听一个 getter
const state = reactive({ count: 0 })
watch(
  () => state.count,
  (count, prevCount) => {
    /* ... */
  }
)

// 直接侦听ref
const count = ref(0)
watch(count, (count, prevCount) => {
  /* ... */
})
```

### 侦听多个数据源 {#watch-multiple-sources}

侦听器还可以使用数组同时侦听多个源：

```js
const firstName = ref('')
const lastName = ref('')

watch([firstName, lastName], (newValues, prevValues) => {
  console.log(newValues, prevValues)
})

firstName.value = 'John' // logs: ["John", ""] ["", ""]
lastName.value = 'Smith' // logs: ["John", "Smith"] ["John", ""]
```

尽管如此，如果你在同一个函数里同时改变这些被侦听的来源，侦听器仍只会执行一次：

```js
createComponent({
  setup() {
    const firstName = ref('')
    const lastName = ref('')
  
    watch([firstName, lastName], (newValues, prevValues) => {
      console.log(newValues, prevValues)
    })
  
    const changeValues = () => {
      firstName.value = 'John'
      lastName.value = 'Smith'
      // 打印 ["John", "Smith"] ["", ""]
    }
  
    return { changeValues }
  }
})
```

注意多个同步更改只会触发一次侦听器。

通过更改设置 `flush: 'sync'`，我们可以为每个更改都强制触发侦听器，尽管这通常是不推荐的。或者，可以用 [nextTick](../../api/global-api.md#nexttick) 等待侦听器在下一步改变之前运行。例如：

```js
const changeValues = async () => {
  firstName.value = 'John' // 打印 ["John", ""] ["", ""]
  await nextTick()
  lastName.value = 'Smith' // 打印 ["John", "Smith"] ["John", ""]
}
```

### 侦听响应式对象 {#watch-reactive-object}

为了侦听深度嵌套的对象或数组中 property 变化，我们需要将 `deep` 选项设置为 true：

```js
const state = reactive({ 
  id: 1,
  attributes: { 
    name: '',
  }
})

watch(
  () => state,
  (state, prevState) => {
    console.log('not deep', state.attributes.name, prevState.attributes.name)
  }
)

watch(
  () => state,
  (state, prevState) => {
    console.log('deep', state.attributes.name, prevState.attributes.name)
  },
  { deep: true }
)

state.attributes.name = 'Alex' // 日志: "deep" "Alex" "Alex"
```

然而，侦听一个响应式对象或数组将始终返回该对象的引用。为了完全侦听深度嵌套的对象和数组，可能需要对值进行深拷贝。这可以通过诸如 `lodash.cloneDeep` 这样的实用工具来实现：

```js
import _ from 'lodash'

const state = reactive({
  id: 1,
  attributes: {
    name: '',
  }
})

watch(
  () => _.cloneDeep(state),
  (state, prevState) => {
    console.log(state.attributes.name, prevState.attributes.name)
  }
)

state.attributes.name = 'Alex' // 日志: "Alex" ""
```

我们也可以直接给 `watch()` 传入一个响应式对象，这种情况下会隐式地强制开启 `deep` 选项，确保嵌套的深层变更能够被监听到：

```js
const state = reactive({ 
  id: 1,
  attributes: { 
    name: '',
  }
})

watch(
  state,
  (state, prevState) => {
    console.log('implicit deep', state.attributes.name, prevState.attributes.name)
  }
)

state.attributes.name = 'Alex' // 日志: "implicit deep" "Alex" "Alex"
```

> 需要注意的是，在侦听使用 `reactive()` 创建的响应式对象时，受数据响应限制影响，在改变数组或使用 `set()` 新增对象属性时，存在和 Vue3 中表现不一致的情况，详情查看[这里](#reactivity-limit-diff)

### 立即回调的侦听器 {#immediate-watch}

同选项式 `watch` 一致，我们也可以通过传递 `immediate` 选项让侦听回调立即执行：

```js
const state = reactive({ 
  count: 0
})

watch(
  () => state.count,
  (value, oldValue) => {
    console.log('immediate', value, oldValue) // 日志: "immediate" 0 undefined
  },
  { immediate: true }
)
```

### 与 watchEffect 共享的行为 {#shared-behavior-with-watcheffect}

`watch` 与 `watchEffect` 共享[停止侦听](#stop-watching)，[清除副作用](#cleanup-side-effect) (相应地 `onInvalidate` 会作为回调的第三个参数传入)、[副作用刷新时机](#side-effect-flush-timing)行为。

## 响应式 API 与 Vue3 中的区别 {#diff-reactive-api-vue3}

下面我们来总结一下 Mpx 中响应式 API 与 Vue3 中的区别：

* 不支持 `raw` 相关 API（`markRaw` 除外，我们提供了该 API 用于跳过部分数据的响应式转换）
* 不支持 `readonly` 相关 API
* 不支持 `watchEffect`、`watch`、`computed` 的调试选项
* 不支持对 `map`、`set` 等集合类型进行响应式转换
* 受到 `Object.defineProperty` 实现带来的数据响应限制影响

### 数据响应限制带来的差异 {#reactivity-limit-diff}

同 Vue2 一致，Mpx 无法感知到对象 property 的添加或移除，我们暴露了 `set` 和 `del` API 来让用户显式地进行相关操作：

```js
import { ref, watchSyncEffect, set, del } from '@mpxjs/core'

const state = ref({
  count: 0
})

watchSyncEffect(() => {
  console.log(JSON.stringify(state.value)) // {"count":0}
})

set(state.value, 'hello', 'world') // {"count":0,"hello":"world"}

del(state.value, 'count') // {"hello":"world"}
```

同样，我们需要使用 `set` 或数组原型方法对数组进行修改：

```js
import { ref, watchSyncEffect, set } from '@mpxjs/core'

const state = ref([0, 1, 2, 3])

watchSyncEffect(() => {
  console.log(JSON.stringify(state.value)) // [0,1,2,3]
})

set(state.value, 1, 3) // [0,3,2,3]

state.value.push(4) // [0,3,2,3,4]
```

可能你已经注意到，上面两个示例当中我们都使用了 `ref()` 进行响应式数据创建，这是有原因的，在新的响应式 API 模式下，我们使用 `reactive()` 创建的响应式数据在上述情况下仍然无法绕过 Vue2 设计中的数据响应限制，即使你使用了 `set` 或数组原型方法：

```js
import { reactive, watchSyncEffect, set } from '@mpxjs/core'

const state = reactive([0, 1, 2, 3])

watchSyncEffect(() => {
  console.log(JSON.stringify(state)) // [0,1,2,3]
})

set(state, 1, 3) // 不会触发 watchEffect

state.push(4) // 不会触发 watchEffect
```

对于对象和在模板中使用也是同理：

```html
<template>
  <view bindtap="addCount2">
    <view>{{state.count}}</view>
    <view>{{state.count2}}</view>
  </view>

</template>

<script>
  import { createComponent, reactive, set } from '@mpxjs/core'
  
  createComponent({
    setup () {
      const state = reactive({
        count: 0
      })

      const addCount2 = () => {
        set(state, 'count2', 10) // 不会触发视图更新
      }

      return {
        state,
        addCount2
      }
    }
  })
</script>
```

为什么会产生这个现象呢？原因在于：基于 `Object.defineProperty` 实现的数据响应系统中，我们会对对象的每个已有属性创建了一个 `Dep` 对象，在对该属性进行 `get` 访问时通过这个对象将其与依赖它的观察者 `ReactiveEffect` 关联起来，并在 `set` 操作时触发关联 `ReactiveEffect` 的更新，这是我们大家都知道的数据响应的基本原理。但是对于新增/删除对象属性和修改数组的场景，我们无法事先定义当前不存在属性的 `get/set` (当然这在 `proxy` 当中是可行的)，因此我们会把对象或者数组本身作为一个数据依赖创建 `Dep` 对象，**通过父级访问**该数据时定义的 `get/set` 将其关联到对应的 `ReactiveEffect`，并在对数据进行新增/删除属性或数组操作时通过数据本身持有的 `Dep` 对象触发关联 `ReactiveEffect` 的更新，如下图所示：

![数据响应原理](https://gift-static.hongyibo.com.cn/static/kfpub/3547/ReactiveEffect.png)

需要注意的是，**通过父级访问**是建立 `Dep` 与 `ReactiveEffect` 关联关系的先决条件，在选项式 API 中，我们访问组件的响应式数据都需要通过 `this` 进行访问，相当于这些数据都存在 `this` 这个必要的**父级**，因此我们在使用 `$set/$delete` 进行对对象进行新增/删除属性或对数组进行修改时都能得到符合预期的结果，唯一的限制在于不能新增/删除根级数据属性，原因就在于 `this` 不存在访问它的父级。

但是在组合式 API 中，我们不需要通过 `this` 访问响应式数据，因此通过 `reactive()` 创建的响应式数据本身就是根级数据，我们自然无法通过上述方式感知到根级数据自身的变化（在 Vue3 中，基于 `proxy` 提供的强大能力响应式系统能够精确地感知到数据属性，甚至是当前不存在属性的访问与修改，不需要为数据自身建立 `Dep` 对象，自然也不存在相关问题）。

在这种情况下，我们就需要用 `ref()` 创建响应式数据，因为 `ref` 创建了一个包装对象，我们永远需要通过 `.value` 来访问其持有的数据（不管是显式访问还是隐式自动解包），这样就能保证 `ref` 数据自身的变化能够被响应式系统感知，因此也不会遇到上面描述的问题。

---

---
url: /guide/tool/unit-test.md
---
# 单元测试 {#unit-test}

Mpx 框架提供了 jest 转换器 mpx-jest，结合微信小程序提供的 [miniprogram-simulate](https://github.com/wechat-miniprogram/miniprogram-simulate) 来进行单元测试的工作。

> 因为目前仅微信提供了仿真工具，暂时只支持微信小程序平台的单元测试。如果需要 E2E 测试，则和框架无关了，可参考微信的[小程序自动化](https://developers.weixin.qq.com/miniprogram/dev/devtools/auto/)。

如果是初始化项目，单元测试相关的项目依赖和配置可以通过 @mpx/cli 创建项目时选择使用单元测试选项自动生成，如果时旧项目需要使用，可以按照下方步骤安装依赖和添加配置。

## 安装依赖 {#install-dependencies}

```html
npm i -D @mpxjs/mpx-jest @mpxjs/miniprogram-simulate jest babel-jest

// 如果项目使用了ts，则还需要安装
npm i -D ts-jest
```

## jest 相关配置 {#jest-config}

首先在项目根目录创建 jest.config.js 配置文件，并加入以下关键配置

```html
  testEnvironment: 'jsdom', // 使用 jsdom 环境
  transform: {
    '^.+\\.js$': '<rootDir>/node_modules/babel-jest',
    '^.+\\.mpx$': '<rootDir>/node_modules/@mpxjs/mpx-jest',
    '^.+\\.ts$': '<rootDir>/node_modules/ts-jest' // 如果没使用 ts 可不用添加
  },
  setupFiles: ['<rootDir>/test/setup'], // test 文件夹下声明 setup，路径可以随意定义，可以为每一个单测添加相应的配置
  transformIgnorePatterns: ['node_modules/(?!(@mpxjs))'], // 定义node_modules 中需要进行 transform 的内容

```

## 简单的断言 {#simple-assertion}

暂时进行一个简单的组件单元测试书写，对于复杂组件以及通用测试逻辑的总结我们会在后续进行发布。

示例如下：

```html
<template>
  <view>{{ message }}</view>
</template>

<script>
  import {createComponent} from '@mpxjs/core'
  createComponent({
    data: {
      message: 'hello!'
    },
    attached () {
      this.message = 'bye!'
    }
  })
</script>
```

对应的 hello-world.spec.js

```js
const simulate = require('@mpxjs/miniprogram-simulate')

// 这里是一些 Jasmine 2.0 的测试，你也可以使用你喜欢的任何断言库或测试工具。
describe('MyComponent', () => {
  let id
  beforeAll(() => {
    id = simulate.loadMpx('<rootDir>/src/components/hello-world.mpx')
  })

  // 检查 mount 中的组件实例
  it('correctly sets the message when component attached', () => {
    const comp = simulate.render(id)
    const instance = comp.instance
    
    // Mpx提供的数据响应是发生在组件挂载时的，未挂载前只能通过实例上的data访问数据
    expect(instance.data.message).toBe('hello!')
    
    const parent = document.createElement('parent-wrapper') // 创建容器节点
    comp.attach(parent) // 将组件插入到容器节点中，会触发 attached 生命周期
    // 挂载后则可以直接通过实例访问
    expect(instance.message).toBe('bye!')
  })

  // 创建一个实例并检查渲染输出
  it('renders the correct message', () => {
    const comp = simulate.render(id)
    const parent = document.createElement('parent-wrapper') // 创建容器节点
    comp.attach(parent) // 挂载组件到容器节点
    expect(comp.dom.innerHTML).toBe('<wx-view>bye!</wx-view>')
  })
})
```

## 编写可被测试的组件 {#testable-component}

很多组件的渲染输出由它的 props 决定。事实上，如果一个组件的渲染输出完全取决于它的 props，那么它会让测试变得简单，就好像断言不同参数的纯函数的返回值。看下面这个例子：

```html
<template>
  <view>{{ msg }}</view>
</template>

<script>
  import {createComponent} from '@mpxjs/core'
  createComponent({
    properties: { msg: String }
  })
</script>
```

你可以在不同的 properties 中，通过 simulate.render 的第二个参数控制组件的输出：

```js
const simulate = require('@mpxjs/miniprogram-simulate')

// 省略辅助方法
describe('MyComponent', () => {
  it('renders correctly with different props', () => {
    const id = simulate.loadMpx('<rootDir>/src/components/hello-world.mpx')
    const comp1 = simulate.render(id, { msg: 'hello' })
    const parent1 = document.createElement('parent-wrapper')
    comp1.attach(parent1)
    expect(comp1.dom.innerHTML).toBe('<wx-view>hello</wx-view>')
    
    const comp2 = simulate.render(id, { msg: 'bye' })
    const parent2 = document.createElement('parent-wrapper')
    comp2.attach(parent2)
    expect(comp2.dom.innerHTML).toBe('<wx-view>bye</wx-view>')
  })
})
```

## 断言异步更新 {#assert-async-update}

小程序视图层的更新是异步的，一些依赖视图更新结果的断言必须 await simulate.sleep() 或者 await comp.instance.$nextTick() 后进行：

```js
const simulate = require('@mpxjs/miniprogram-simulate')

// 省略辅助方法
it('updates the rendered message when vm.message updates', async () => {
  const id = simulate.loadMpx('<rootDir>/src/components/hello-world.mpx')
  const comp = simulate.render(id)
  const parent = document.createElement('parent-wrapper')
  comp.attach(parent)
  comp.instance.msg = 'foo'
  await simulate.sleep(10)
  expect(comp.dom.innerHTML).toBe('<wx-view>foo</wx-view>')
})
```

更深入的 Mpx 单元测试的内容将在以后持续更新……

---

---
url: /guide/tool/e2e-test.md
---
# E2E自动化测试 {#e2e-test}

微信小程序的官方文档推荐 [miniprogram-automator](https://developers.weixin.qq.com/miniprogram/dev/devtools/auto/quick-start.html)，其与小程序IDE的关系，正如 Google 与 UiAutomator、selenium 与 webdriver 一样；它是最契合小程序的。

虽然微信小程序提供了 automator + ide 的 E2E 的解决方案，但该项目维护频率低且 case 编写效率低、API 不够友好等问题，因此基于微信提供的能力& Mpx 生态我们产出了相对完善的小程序E2E自动化测试增强方案，此外还提供了可扩展的开箱即用的E2E基础设施。

小程序自动化 SDK 为开发者提供了一套通过外部脚本操控小程序的方案，从而实现小程序自动化测试的目的。

> 如果你之前使用过 Selenium WebDriver 或者 Puppeteer，那你可以很容易快速上手。小程序自动化 SDK 与它们的工作原理是类似的，主要区别在于控制对象由浏览器换成了小程序。

## @mpx/cli 脚手架集成E2E {#cli-integrate-e2e}

当使用 @mpxjs/cli 初始化 Mpx 项目的时候，交互式命令行里面新增了 E2E 选项，当选择了此选项，项目将会初始化 E2E 配置，完成相关内容的生成。

![](https://gift-static.hongyibo.com.cn/static/kfpub/3547/mpxtemplate_v2.png)

关于 E2E 的模板文件如下：

```
# 忽略部分文件夹 {#ignore-folders}
vue-project
├─ .e2erc.js # E2E配置
├─ src
│  ├─ app.mpx
│  ├─ pages
│  │  └─ index.png
│  └─ components
│     └─ list.mpx
├─ test
│  └─ e2e # case目录
│     └─ list.spec.js # 示例文件
├─ jest-e2e.config.js # Jest配置
└─ package.json
```

这里罗列了 E2E 项目中约定(或推荐)的目录结构，在项目开发中，请遵照这个目录结构组织代码。

### 文件说明 {#file-description}

**package.json**

使用自动化测试，我们要做的第一件事就是安装 @mpxjs/e2e 和 @mpxjs/e2e-scripts，然后我们需要在 package.json 中定义两个自动化测试的脚本 test 和 testServer。

```json
{
  "devDependencies": {
    "@mpxjs/e2e": "0.0.13",
    "@mpxjs/e2e-scripts": "0.0.12",
  }
  "scripts": {
    "test": "e2e-runner",
    "testServer": "e2e-runner --preview"
  }
}
```

小程序自动化 SDK 为开发者提供了一套通过外部脚本操控小程序的方案，从而实现小程序自动化测试的目的。

**.e2erc.js**

E2E 配置文件，包含 E2E 内置功能和插件的配置。可以在这里扩展运行时的能力，比如修改运行时是否自动保存页面快照。

```js
const path = require('path');
const PluginReport = require('@mpxjs/e2e/report-server/server.js');
module.exports = {
  recordsDir: 'dist/wx/minitest', // 录制 json 文件的存储目录
  connectFirst: false, // 优先使用 automator.connect，默认 automator.launch 优先
  defaultWaitFor: 5000, // 默认 waitFor 时长
  devServer: { // 测试报告服务器配置
    open: true,
    port: 8886
  },
  jestTimeout: 990000, // jestTimeout
  jsonCaseCpDir: 'test/e2e/e2e-json', // 从 minitest 目录复制 json 文件到该目录下
  needRealMachine: false, // 是否需要真机
  plugins: [new PluginReport()], // 自定义测试报告的插件
  projectPath: path.resolve(__dirname, './dist/wx'),
  sequence: [ // e2e 的 case 的执行顺序
    // 'minitest-1'
  ],
  testSuitsDir: 'test/e2e/', // e2e 的 case 存放目录
  useTS: false, // e2e 的 case 是否为 TS 语法
  wsEndpoint: 'ws://localhost:9420', // automator.connect 的 wsEndpoint
  timeoutSave: 3000, // 定时截图默认开启，设置为 false 即可关闭
  cacheDirectory: path.resolve(__dirname, './node_modules/@mpxjs/e2e/report-server/cache'), // 配置截图数据的保存目录
  tapSave: true, // 点击截图默认开启，设置为 false 即可关闭
  routeUpdateSave: true, // 路由切换截图默认开启，设置为 false 即可关闭
  routeTime: 300, // 路由切换 300ms 后再截图
  watchResponse: [ { url: '/api/list', handler (newRes, oldRes) { return true }} ], // 配置接口请求截图
}
```

我们提供了丰富的配置化选项，满足各种场景运行。

| 参数 | 类型 | 默认值 | 说明 |
| - | - | - | - |
| projectPath | String | ./dist/wx | 小程序代码路径，Mpx 框架的 wx 输出目录 |
| testSuitsDir | String | test/e2e/suits/ | e2e 的 case 存放目录 |
| sequence | string\[ ] | \[ ] | 用例运行的顺序 |
| recordsDir | String | dist/wx/minitest | 录制 json 文件的存储目录 |
| connectFirst | Boolean | false | 优先使用 automator 的 connect 方法 |
| wsEndpoint | String | ws://localhost:9420 | 使用 connect 方式时的 wsEndpoint 选项 |
| defaultWaitFor | Number | 15000 | 默认 waitFor 时长 |
| useTS | Boolean | false | 用例是否为 TS 语法 |
| jestTimeout | Number | 990000 |  默认测试超时时间 |
| jsonCaseCpDir | String | test/e2e-json |  从 minitest 目录复制 json 文件到该目录下 |
| needRealMachine | Boolean | false | 是否需要真机回放 |
| devServer | Object | null | 测试报告服务器配置 |
| plugins | Array | \[ ] | 自定义测试报告的插件 |
| timeoutSave | Number | 3000 | 定时3000ms保存页面快照 |
| cacheDirectory | String | report-server/cache | 页面快照的保存目录 |
| tapSave | Boolean | true | 点击时候保存页面快照 |
| routeUpdateSave | Boolean | true | 路由切换时候保存页面快照 |
| routeTime | Number | 300 | 路由切换300ms后保存页面快照 |
| watchResponse | Object | null | 监听接口请求保存页面快照 |

**e2e**

e2e 目录，所有的 case 文件存放在此目录下，默认会创建一个演示 demo 文件，也就是 list.spec.js 文件，约定 e2e 下所有的 .spec.js 结尾的作为自动化测试的文件，使用 Typescript 编写测试文件的时候, 需要将文件名改成 .spec.ts 格式，然后 tsconfig.json 加上 "esModuleInterop": true。

```js
/**
 * @file e2e test example
 * 首先开启工具安全设置中的 CLI/HTTP 调用功能
 * docs of miniprogram-automator: https://developers.weixin.qq.com/miniprogram/dev/devtools/auto/quick-start.html
 */
import automator from '@mpxjs/e2e'

describe('index', () => {
  let miniProgram
  let page

  beforeAll(async () => {
    try {
      miniProgram = await automator.connect({ wsEndpoint: 'ws://localhost:9420' })
    } catch (e) {
      miniProgram = await automator.launch({ projectPath: './dist/wx' })
    }
    page = await miniProgram.reLaunch('/pages/index')
    await page.waitFor(500)
  }, 30000)

  it('desc', async () => {
    const desc = await page.$('list', 'components/list2271575d/index')
    // 断言页面标签
    expect(desc.tagName).toBe('view')
    // 断言文字内容
    expect(await desc.text()).toContain('手机')
    // 保存页面快照
    await miniProgram.screenshot({
      path: 'test/e2e/screenshot/homePage.png'
    })
  })

  afterAll(async () => {
    await miniProgram.close()
  })
})
```

如果你已经熟悉了 Jest，你应该很适应 Jest 的断言 API。

**jest-e2e.config.js**

Jest 配置文件，这些选项可让你控制 Jest 的行为，你可以了解 Jest 的默认选项，以便在必要时扩展它们：

```js
module.exports = {
  preset: 'ts-jest',
  testEnvironment: 'node',
  testTimeout: 1000000000,
  maxWorkers: 1,
  reporters: [
    'default',
    ['<rootDir>/node_modules/@mpxjs/e2e/report-server/report.js', {}], // 自定义测试报告
  ]
}
```

除了 Jest 提供的默认测试报告器外，我们还可以自定义测试报告。框架 @mpxjs/e2e 内部提供了可视化测试报告平台，需要配置 reporters 字段。

目前对于@mpx/cli@3.\*版本也会陆续完成E2E的相关支持。

## @mpxjs/e2e-scripts

默认情况下，Jest 将会递归的找到整个工程里所有 .spec.js 或 .test.js 扩展名的文件。 Jest 支持并行运行 test ，特别是在 ci 场景，将会极大减少 test 消耗时间。配置 --maxWorkers 参数表示的是 Jest 会开启多少个线程去完成所有的测试任务，默认值是 50% \* os.cpus().length，相关的文档可见：[链接](https://jestjs.io/docs/cli#--maxworkersnumstring)。

合理的设置 maxWorkers 会使得运行变快，依赖的是并行跑用例，但是在自动化测试环境下，用例通过脚本操控模拟器或真机环境，多个用例不能同时操控一个环境，否则会相互干扰，就好比 JS 只能是单线程执行一样。

因为用例只能一个一个的执行，一个完整的项目自然会包含很多用例，但是一次只能执行一个用例的话，我们需要人工的操作很多次，才能全部执行完。为了跑一个遍就把所有的用例都执行完的话，我们会想到写一个脚本通过遍历的方式依次执行，这就是 @mpxjs/e2e-scripts 设计的初衷。

使用 @mpxjs/e2e-scripts 内部提供的命令脚本，执行 npx e2e-runner 将会按照 sequence 的定义的顺序依次执行用例文件。

```js
module.exports = {
  sequence: [ // 测试用例的执行顺序
    'minitest-1',
    'minitest-2'
  ]
}
```

上面代码表示会先执行 minitest-1.spec.js 文件，然后再执行 minitest-2.spec.js 文件。

## E2E可视化报告平台 {#e2e-report-platform}

E2E内置的 Jest 默认支持输出 HTML 的报告，因其只支持对测试结果数据的简单展示，故我们希望在其基础上，不仅针对报告查看的广度和颗粒度进行细化，还将对自动化测试过程中涉及到的痛点实现功能上的增强。

![](https://gift-static.hongyibo.com.cn/static/kfpub/3547/baogao-2.jpeg)

E2E可视化报告平台是一个运行在本地环境，统合了用例管理、测试报告、页面快照和错误日志的平台。支持对通过 WechatDevTools 录制回放功能录制出的 case 进行自定义增强的能力，同时提供执行 E2E 测试过程中产出的页面快照和错误日志等信息进行快捷、直观地查看的功能。

目前支持多种交互动作保存快照（点击、输入、滑动等），我们还在页面快照方面做了增强，提供了快照标记的功能，可以完善测试报告，增强排查手段，当点击元素后，页面快照上会自动标记出点击的区域或者元素。

## E2E录制+自动化生成case {#e2e-record-case}

微信推出了官方的录制回放能力。通过微信开发者工具可以录制用户的操作过程，期间可以进行简单断言，录制结束后支持回放。但是经过实际使用发现录制回放存在下列不足：

1. 录制结果结果以 json 形式存在于 dist 目录，难以扩展、难维护；
2. 仅支持 data快照、wxml快照、检查元素、检查路径四种简单断言，难以满足复杂业务场景的细粒度断言诉求；
3. 因等待时长、接口响应时机、组件更新时机等难以和录制时对应，录制结果回放失败频率高、不稳定；

我们通过基于微信原生的录制进行增强的方案。使用录制的便捷性降低手写流程的成本，再通过 sdk 的能力对录制所得 Case 进行增强。

这样，我们通过分析录制 JSON 文件，把 JSON 中的每一条进行分析转换，最终得到 spec 的 JS 代码文件，通过这种方式，可以大幅度降低获取元素、触发事件等常规 Case 的编写。

JSON to Spec 本质只是录制结果的一种呈现，而这种转换的目的在于通过扩展强化录制 Case，弥补录制的能力有限。

为了方便我们进行扩展，首先需要对录制所得的 JSON 文件进行语义化的分析。这么做的意义在于把录制的操作步骤和 JSON 的数据关联起来，而关联步骤和数据又可以增强可读性为用户在某一个步骤之后进行扩展增加了极大的便利性。

上一个部分已经论证过把录制和SDK增强接合起来的可行性，但是上面一系列的操作都是通过脚本的形式呈现的，这对于我们前面的降低门槛来说仍然是繁琐的。最起码对于不会写代码的的人来说，还是不够理想。接下来就是探索如何更直观、更高效的方式把这种方案落地。

我们设计了 Mpx-E2E 的工作台，当然这些也都集成到了 Mpx-E2E 的可视化平台中，下面我们看看这些具体的可视化的工作。

![](https://gift-static.hongyibo.com.cn/static/kfpub/3547/gencae.png)

分析 JSON 操作步骤后，我们把依据 JSON 生成的 Spec 同样做了可视化处理，起初的时候我们只是做了 Spec 代码的 highlight，并没有支持编辑。但是考虑到所见即所得的效率，我们又在此支持了 WEB-IDE。在生成 Spec 代码后，即可在线进行编辑，最终通过我们的@mpxjs/e2e SDK核心能力，完成了保存spec文件。

## 增强API {#enhanced-api}

> @mpxjs/e2e

小程序自动化 SDK 为开发者提供了一套通过外部脚本操控小程序的方案，从而实现小程序自动化测试的目的。

然而在我们使用过程中发现原始小程序官网提供的sdk存在能力的不足和缺失，或者说无法满足我们复杂的业务流程，针对这一系列的能力的缺失，我们开发了针对e2e的增强型api，来满足我们的整个自动化流程所需的功能

1、获取页面中的DOM元素 $ 方法 ：

SDK 中重写 page 和 element 的 `$` 方法。之所以这么处理是因为原生的 `$` 方法存在自定义组件中的元素不能稳定获取的问题，而这个问题的根源在于微信小程序会以某种规则为元素拼接组件或者父组件的名字作为真实类名，而这种规则并不固定。

目前增强后的 `$` 方法支持两个参数，第一个为选择器，第二个是自定义组件名。第二个参数不传时其行为和原生 `$` 方法一致。

```js
$(className: string, componentsName?: string): Promise<Element | any>
 
const confirmbtn = await page.$('confirm-btn', 'homepage/components/confirmef91faba/confirm')
 
const confirmbtn2 = await page.$('.confirm-btn')
const view = await page.$('view')
const id = await page.$('#id')
```

获取自定义组件中的元素需要以渲染结果为准，通常第二个参数是传入组件的 `is` 属性。注意弹窗类似的组件往往会存在动画所以需要异步获取。

```js
// 页面的渲染结果
<base-dialog is="homepage/components/dialogd2d0cea6/index">
  #shadow-root
    <view class="wrapper">
      <view class="cancel-btn">确认</view>
      <view class="confirm-btn">取消</view>
    </view>
</base-dialog>

// 对应获取元素的方法
const cancelbtn = await page.$('cancel-btn', 'homepage/components/dialogd2d0cea6/index')
const confirmbtn = await page.$('confirm-btn', 'homepage/components/dialogd2d0cea6/index')
```

2、增强 wait/ waitAll

automator 中原生支持 `wait` 方法，表示等待时长或者等待终止的断言函数。但是经过实际测试发现，使用指定的等待时间并不可靠，其运行受限于硬件条件。

经过增强的 `wait` 方法可以支持： 路由到指定页面， 指定组件渲染，指定组件更新，指定接口发起， 指定接口响应后；

```js
wait(path: string, type?: string): Promise<string | undefined> | void;
 
const miniProgram = await Automator.launch({
  projectPath: './dist/wx'
})

// 页面
page = await miniProgram.reLaunch('/pages/index/index')
await miniProgram.wait('pages/index/index')

// 组件
const suggest1 = await miniProgram.wait('suggest/components/suggestcaafe3e4/suggest', 'component')
 
// 组件更新
const suggest2 = await miniProgram.wait('suggest/components/suggestcaafe3e4/suggest', 'componentUpdate')
 
// 请求
const request = await miniProgram.wait('https://xxxx.xxx/xxx', 'request')
 
// 返回结果
const response = await miniProgram.wait('https://xxxx.xxx/xxx', 'response')
expect(response.options.data.errno).toBe(0)
const data = response.options.data.data
expect(data.status).toBe(1)
```

3、新增 mock 能力

考虑到进行 e2e 测试时有些场景需要 mock 数据，所以 SDK 结合 mpx-fetch 的 `setProxy` 能力提供了静态资源文件 mock、手动设置接口响应结果的能力。

前置：如果需要使用 mock 需要使用支持 `setProxy` 的 mpx-fetch 版本；此外还需要在 createApp 的时候传入 `setProxy` 属性，其配置与 mpx-fetch 的 `setProxy` 方法的配置相同，示例：

```js
createApp({
	setProxy: [
  	{
    	test: {
      	host: 'some-domain.com',
      	protocol: 'https:'
    	},
    	proxy: {
      	host: 'localhost',
      	port: 8887,
      	protocol: 'http:'
    	}
  	}
  ],
	// otherApp props
})
```

3.1 初始化 mock：initMock

当传入 `staticDir` 时会优先匹配该目录下的静 json 文件作为指定接口的响应结果。

接口与文件名的映射规则：将域名后的 path 中的分隔符 `/` 替换为 `-`，示例：

* 接口名称：`api/pGetIndexInfo`
* json 文件名称：`api-pGetIndexInfo.json`

```js
interface E2eMockConfig {
  staticDir: string // 本地文件目录：
}

Automator.initMock(mockCfg: E2eMockConfig): Promise<MiniProgram>
```

3.2 `setMock` 方法，除了上面的静态资源文件，mock 内置了一个 Map 列表，因此可以按需的设置某一接口的响应结果。

```js
Automator.setMock (path:string, response:any): () => void
 
// 示例：
let un = Automator.setMock('https://some-domain.com/api/pGetIndexInfo', {
  errno: 0,
  errmsg: 'mock-index-info',
  data: {
    a: 1,
    b: 2,
    c: 3
  }
});
 
// 需要取消时可以调用 un，注意这一步骤非必须！！
un();
```

3.3 `removeMockFromMap` 从 mock 内置的 Map 列表中移除指定 path 对应的的 mock 数据。

```js
Automator.removeMockFromMap (path:string): void
```

## SOP

**一、环境要求**

1.1 微信环境
安装 Node.js 并且版本大于 8.0
基础库版本为 2.7.3 及以上
开发者工具版本为 1.02.1907232 及以上
 
1.2 Mpx 环境
Mpx-E2E 很多能力基于 Mpx 增强的，最低版本要求如下：
@mpxjs/core >= 2.7.2
@mpxjs/api-proxy >= 2.7.1
@mpxjs/webpack-plugin >= 2.7.8

**二、新建项目**

2.1 安装 @mpxjs/cli 脚手架

```js
$ npm install -g @mpxjs/cli
```

2.2 初始化项目选择 E2E 测试，执行以下命令执行初始化项目

```js
$ mpx init some-proj
```

执行该命令后稍等片刻，等模板下载完成 Terminal 会输出以下提示，当输出到 ”是否需要 E2E 测试“时输入 “yes“ ，脚手架内置了 E2E 需要的依赖和简单的测试用例。待脚手架初始化完成后，你的新项目就已经拥有了开箱即用的E2E能力。

**三、已有项目**

3.1 安装 E2E sdk、runner

```js
npm i @mpxjs/e2e  @mpxjs/e2e-scripts --save-dev
```

3.2 创建 .e2erc 配置文件

> 在项目的源文件目录下创建名为 .e2erc.js 的配置文件，以下为 e2erc 各选项及其含义，建议直接复制到项目中

```js
const path = require('path');
const PluginReport = require('@mpxjs/e2e/report-server/server.js'); // E2E 报告插件
module.exports = {
  recordsDir: 'dist/wx/minitest', // 录制 json 文件的存储目录
  connectFirst: false, // 优先使用 automator.connect，默认 automator.launch 优先
  wsEndpoint: 'ws://localhost:9420', // automator.connect 的 wsEndpoint 选项，用于 connectFirst 时链接到模拟器服务
  defaultWaitFor: 15000, // 默认 waitFor 时长
  useTS: false, // 是否启用 TS , 该特性暂不支持，
  devServer: {
    open: true
  },
  jestTimeout: 990000, // jestTimeout
  jsonCaseCpDir: 'test/e2e-json', // 从 minitest 目录复制 json 文件到该目录下
  needRealMachine: false, // 是否需要真机
  plugins: [new PluginReport()], 
  projectPath: path.resolve(__dirname, './dist/wx'), // 小程序代码路径，Mpx 框架的 wx 输出目录
  testSuitsDir: 'test/e2e/suits/', // e2e 的 case 存放目录
  sequence: [ // E2E case，runner 将会按照这个数组顺序执行其中的 case 文件，
    'minitest-20', // 不需要写 .spec.js 这个扩展名
  ],
  reportsDir: 'test/reports' // 报告输出目录
}
```

**四、获取 Case**

4.1 录制 JSON Case

录制 case 是依托于微信开发者工具已有的能力，操作流程如下：

1. 启动录制
   启动微信开发者工具 -> 工具 -> 自动化测试
2. 创建用例
   选择【开始录制】按钮
   【用例名】会成为录制 JSON case 的文件名，比如上图中录制结束后会得到一个名为
   minitest-3.json 的 JSON 文件；我们推荐您采用更语义化的测试用例名称，便于后续的 CASE 管理。
   【结束录制】后，开发者工具会在小程序的代目录（Mpx 的产物输出目录，如 dist/wx）下新增 minitest/ 目录，该目录是微信开发者工具自动创建的，用于存放录制 JSON case。例如上面的例子中，录制结束后该目录下就应该有 名为 minitest-3.json 的 文件。

4.2 生成 Spec Case

启动 Mpx-E2E 平台服务，首先在项目的 package.json 中加入以下 npm script：

```js
{
  "e2eServe": "npx e2e-runner --preview"
},
```

在小程序项目录下通过命令行启动 Mpx-E2E 平台服务:

```js
npm run e2eServe
```

平台服务已经成功启动！打开 Mpx-E2E 的可视化平台:
选择【用例管理】，加载录制的 JSON Case，点击可视化平台上的 【JSON 导入】按钮。界面中间是对当前 JSON 文件的语义化解析，最后侧是包含自动生成代码的 Web IDE。点击中间的语义化解析会联动右侧 WebIDE 代码跳转到对应的区域。

4.3 可视化扩展 Spec Case

1. 新增
   鼠标悬浮在中间语义化区域中每一条的左侧的绿色按钮时，就会出现一个扩展菜单，在弹出框中填写相关信息，点击【保存】即可新增一条操作

2. 编辑
   通过可视化的方式扩展的操作可以编辑，录制的操作不能编辑；

4.4 保存 Spec case

在完成上述操作后，点击 Web-IDE 下面的 【保存】即可.

点击保存后， Web-IDE 中的内容将会被写入到 .e2erc.js 的 testSuitsDir 字段指定的目录中。当文件写入成功后，被保存的 spec 文件名会被自动写入到剪贴板中。

另外，生成这份 Case 的 JSON 文件也会被复制到 .e2erc.js 的 jsonCaseCpDir 目录下，之所以保存 JSON 文件主要是做备份，你可以不关心这个 json 的文件内容，但是我们建议你随着 spec 代码已经提交到版本库；
 
经过保存后，我们就得到了 minitest-3.spec.js Case 文件。

**五、修改 .e2erc.js sequence**

5.1 sequence 数组
经过前面的获取 Case 后步骤后，我们已经得到了 minitest-3.spec.js Case 文件。在正式运行前，我们需要把这个 minitest-3.spec.js Case 加入到 .e2erc.js 的 sequence 字段数组中。

```js
sequence: [ 
  'minitest-3', // 不用写 .spec.js 
]
```

5.2 为什么手动维护？
之所以需要手动维护这个数组，是因为微信的 automator 不能并发运行，进而 E2E 的 Case 无法并发运行；又或者某几个 spec 间是有联系的， 这种情况下只能把顺序交给人工维护。

**六、运行 e2e**

6.1 新增 npm scripts
修改项目的 package.json 中 scripts 字段，向其中加入 "test:e2e":"npx e2e-runner" 命令

6.2 运行 E2E 测试命令

```js
npm run test:e2e
```

6.3 在真机中运行 E2E

1. 真机运行 E2E 相当于微信开发者工具的【真机调试】，首先需要确保你的 Mpx 构建输出产物是 prod 模式下的产物；
2. 修改 .e2erc.js 中的 needRealMachine 字段为 true，再执行 npm run test:e2e 命令；
   静等微信开发者工具完成真机调试二维码的构建完成，待完成后用真机扫描二维码即可开始；

> 注：目前因为微信 automator 的限制，包括 wait 接口请求等能力暂时在真机上不能支持，这些问题目前已经反馈到微信，有进展我们会及时更新！

**七、测试报告**

在 .e2erc.js 中配置 report-plugin（详情见.e2erc.js 配置文件部分） 即可在所有 spec 运行结束后自动打开浏览器并呈现测试结果，测试结果包含以下三部分:

1） Jest 数据
2） 自动截图：
截图分析：在 Mpx-E2E 平台下，点击【截图】Tab 即可，截图以 spec 文件为维度展示，目前包含三种自动时机的截图：定时、点击时、路由发生时，默认全部展示。
截图筛选：通过操作 timeout/tap/router 的复选框即可实现分类查看，另外在点击时的自动截图还会对点击位置进行标记；
3）JSError 分析
如果运行过程中小程序抛出 JS 异常，此时会触发 Mpx-E2E 的收集动作，同时会抓取报错瞬间的截图

未来可视化平台会持续集成更多功能，可以涵盖业务稳定，数据稳定(埋点测试)和性能数据，持续更新...

---

---
url: /guide/extend/fetch.md
---
# 网络请求 {#network-request}

Mpx 提供了网络请求库 fetch，抹平了微信，阿里等平台请求参数及响应数据的差异；同时支持请求拦截器，请求取消等

## 使用说明 {#usage-instruction}

```js
import mpx from '@mpxjs/core'
import mpxFetch from '@mpxjs/fetch'
mpx.use(mpxFetch)
// 第一种访问形式
mpx.xfetch.fetch({
	url: 'http://xxx.com'
}).then(res => {
	console.log(res.data)
})

mpx.createApp({
	onLaunch() {
		// 第二种访问形式
		this.$xfetch.fetch({url: 'http://test.com'})
	}
})
```

## 导出说明 {#export-description}

mpx-fetch提供了一个实例 **xfetch** ，该实例包含以下api

* fetch(config)， 正常的promisify风格的请求方法
* CancelToken，实例属性，用于创建一个取消请求的凭证。
* interceptors，实例属性，用于添加拦截器，包含两个属性，request & response

## 请求拦截器 {#request-interceptor}

```js
mpx.xfetch.interceptors.request.use(function(config) {
	console.log(config)
	// 也可以返回promise
	return config
})
mpx.xfetch.interceptors.response.use(function(res) {
	console.log(res)
	// 也可以返回promise
	return res
})
```

## 请求中断 {#request-abort}

```js
const cancelToken = new mpx.xfetch.CancelToken()
mpx.xfetch.fetch({
	url: 'http://xxx.com',
	data: {
		name: 'test'
	},
	cancelToken: cancelToken.token
})
cancelToken.exec('手动取消请求') // 执行后请求中断，返回abort fail
```

## 设置请求参数 {#set-request-params}

```js
mpx.xfetch.fetch({
	url: 'http://xxx.com',
	params: {
		name: 'test'
	}
})

mpx.xfetch.fetch({
	url: 'http://xxx.com',
	method: 'POST',
	// params 参数等价于 url query
	params: {
		age: 10
	},
	data: {
		name: 'test'
	},
	// 设置参数序列化方式，等价于header = {'content-type': 'application/x-www-form-urlencoded'}
	emulateJSON: true
})
```

## 设置请求 timeout {#set-request-timeout}

```js
mpx.xfetch.fetch({
	url: 'http://xxx.com',
	method: 'POST',
	data: {
		name: 'test'
	},
	timeout: 10000 // 超时时间
})
```

## 在组合式 API 中使用 {#composition-api-usage}

在组合式 API 中我们提供了 [useFetch](../../api/extend.md#usefetch) 方法来访问 `xfetch` 实例对象

```js
// app.mpx
import mpx, { createComponent } from '@mpxjs/core'
import { useFetch } from '@mpxjs/fetch'

createComponent({
  setup() {
      useFetch().fetch({
          url: 'http://xxx.com',
          method: 'POST',
          params: {
              age: 10
          },
          data: {
              name: 'test'
          },
          emulateJSON: true,
          usePre: true,
          cacheInvalidationTime: 3000,
          ignorePreParamKeys: ['timestamp']
      }).then(res => {
          console.log(res.data)
      })   
  }
})

```

---

---
url: /guide/extend/webview-bridge.md
---
# webview-bridge

Mpx 在支持小程序跨平台开发后，各大平台的小程序均提供了 Webview 组件，允许通过 WebView 打开 H5 页面，并借助小程序提供的 API 实现 H5 与小程序之间的通信及部分小程序能力的调用。但不同平台为 WebView 提供的 API 存在差异。

例如，在微信小程序中，H5 页面需使用 wx.miniProgram.navigateTo 实现向小程序页面的跳转，而在支付宝中则需调用 my.navigateTo。这意味着开发者若想实现跨平台兼容，就必须为不同平台编写多套对应的逻辑代码。

为解决这一问题，Mpx 提供了一个抹平各平台差异的 Bridge 库：@mpxjs/webview-bridge。使用该库后，开发者只需统一调用一套接口，即可在多个小程序平台上实现一致的功能调用，有效降低开发复杂度和维护成本。

**支持运行环境**：微信小程序、支付宝小程序、Touch 'n Go App 内小程序、QQ 小程序、头条小程序、百度小程序、Web、RN

> Touch 'n Go App 内小程序中的 H5 页面会自动复用支付宝小程序的 Webview Bridge 能力，无需额外配置。

## 安装： {#install}

```shell
npm install @mpxjs/webview-bridge
```

## 使用： {#usage}

```js
import mpx from '@mpxjs/webview-bridge'
mpx.navigateBack()
mpx.env // 输出：wx/qq/ali/baidu/tt
mpx.checkJSApi()
```

## cdn地址引用： {#cdn-import}

```js
<!-- 开发环境版本，方便调试 -->
<script src="https://dpubstatic.udache.com/static/dpubimg/D2JeLyT0_Y/2.2.43.webviewbridge.js"></script>

<!-- 生产环境版本，压缩了体积 -->
<script src="https://dpubstatic.udache.com/static/dpubimg/PRg145LZ-i/2.2.43.webviewbridge.min.js"></script>


<!-- 同时支持 ES Module 引入的 -->
// index.html
<script type="module" src="https://dpubstatic.udache.com/static/dpubimg/6MQOo-ocI4/2.2.43.webviewbridge.esm.browser.min.js"></script>
// main.js
import mpx from "https://dpubstatic.udache.com/static/dpubimg/6MQOo-ocI4/2.2.43.webviewbridge.esm.browser.min.js"

//ES Module 开发版本地址： https://dpubstatic.udache.com/static/dpubimg/cdhpNhmWmJ/2.2.43.webviewbridge.esm.browser.js
```

## 支持方法： {#supported-methods}

对于web-view组件打开的网页，想要跟宿主环境通信，或者跳转到宿主环境的页面，提供了以下能力

**基础方法**

| 方法名           | 说明                                          | 微信 | 支付宝 | QQ | 头条 | 百度 | web | RN |
|---------------|---------------------------------------------|------|-------|----|------|------|-----|----|
| navigateTo    | 保留当前webview页面，跳转RN页面                        | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ |
| navigateBack  | 关闭当前页面，返回上一页或多级RN页面                         | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ |
| switchTab        | 跳转到RN的 tabBar 页面                            | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ |
| reLaunch        | 关闭所有页面，打开到应用内的某个RN页面                        | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ |
| redirectTo        | 关闭当前页面，跳转到应用内的某个RN页面                        | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ |
| config        | 微信小程序中h5调用扩展能力配置方法：用于初始化微信 JS-SDK，使 H5 页面具备调用微信原生能力的权限。                        | ✓ | ✗ | ✗ | ✗ | ✗ | ✗ | ✗ |
| invoke        | JSBridge能力调用（仅web和RN支持）                        | ✗ | ✗ | ✗ | ✗ | ✗ | ✓ | ✓ |

**扩展方法：**
| 方法/平台      | wx            | qq    | ali    | baidu    | tt    |
| ------------- |:-----:| :-----:| :-----: |:-----:| -----:|
| checkJSApi|✓|✗|✗|✗|✗|
| chooseImage|✓|✗|✓|✓|✗|
| previewImage |✓|✗|✓|✓|✗|✓|✓|✓|
| uploadImage |✓|✗|✗|✗|✗|
| downloadImage |✓|✗|✗|✗|✗|
| getLocalImgData |✓|✗|✗|✗|✗|
| startRecord |✓|✗|✗|✗|✗|
| stopRecord |✓|✗|✗|✗|✗|
| onVoiceRecordEnd |✓|✗|✗|✗|✗|
| playVoice |✓|✗|✗|✗|✗|
| pauseVoice |✓|✗|✗|✗|✗|
| stopVoice |✓|✗|✗|✗|✗|
| onVoicePlayEnd |✓|✗|✗|✗|✗|
| uploadVoice |✓|✗|✗|✗|✗|
| downloadVoice |✓|✗|✗|✗|✗|
| translateVoice |✓|✗|✗|✗|✗|
| getNetworkType |✓|✗|✓|✓|✗|
| openLocation |✓|✗|✓|✓|✗|
| getLocation |✓|✗|✓|✓|✗|
| stopSearchBeacons |✓|✗|✗|✗|✗|
| onSearchBeacons |✓|✗|✗|✗|✗|
| scanQRCode |✓|✗|✗|✗|✗|
| chooseCard |✓|✗|✗|✗|✗|
| addCard |✓|✗|✗|✗|✗|
| openCard |✓|✗|✗|✗|✗|
| alert |✓|✓|✗|✗|✗|
| showLoading |✓|✓|✗|✗|✗|
| hideLoading |✓|✓|✗|✗|✗|
| setStorage |✓|✓|✓|✗|✗|
| getStorage |✓|✓|✓|✗|✗|
| removeStorage |✓|✓|✓|✗|✗|
| clearStorage |✓|✓|✓|✗|✗|
| getStorageInfo |✓|✓|✓|✗|✗|
| startShare |✓|✓|✗|✗|✗|
| tradePay |✓|✓|✗|✗|✗|
| onMessage |✗|✗|✓|✗|✗|

### webview-bridge示例代码 {#webview-bridge-example}

```javascript
import webviewBridge from '@mpxjs/webview-bridge'
webviewBridge.navigateTo({
  url: 'RN地址',
  success: () => {
    console.log('跳转成功')
  }
})
```

### invoke示例代码 {#invoke-example}

在业务场景中，当 H5 需要调用扩展方法中的api能力（如通过 getLocation 获取地理位置）时，需与承载 H5 的「宿主环境」（如原生 App、小程序容器等）进行数据交互。

针对这类需求，Mpx 框架内部已提供「宿主环境能力挂载」机制，同时在 webview-bridge 中支持 invoke 通信方法，可实现 H5 与宿主环境的双向调用。

`webviewConfig` 需要按宿主环境配置在 `mpx.config.webConfig` 或 `mpx.config.rnConfig` 下。

**宿主环境中挂载getLocation**

```javascript
import mpx from '@mpxjs/core'
...
// 普通方法
if (__mpx_mode__ === 'ios') {
  mpx.config.rnConfig.webviewConfig = { // RN环境
    apiImplementations: {
      getLocation:  (options = {}) => {
        return {
          latitude: 0,
          longitude: 0
        }
      }
    }
  }
} else {
  mpx.config.webConfig.webviewConfig = { // web环境
    apiImplementations: {
      getLocation:  (options = {}) => {
        return {
          latitude: 0,
          longitude: 0
        }
      }
    }
  }
}

// 或者promise

if (__mpx_mode__ === 'ios') {
  mpx.config.rnConfig.webviewConfig = { // RN环境
    apiImplementations: {
      getLocation: (options = {}) => {
        return new Promise((resolve, reject) => {
          const { params = {} } = options
          if (params.text) {
            resolve({
              latitude: 0,
              longitude: 0
            })
          } else {
            reject(new Error('没有传text参数'))
          }
        })
      }
    }
  }
} else {
  mpx.config.webConfig.webviewConfig = { // web环境
    apiImplementations: {
      getLocation:  (options = {}) => {
        return new Promise((resolve, reject) => {
          const { params = {} } = options
          if (params.text) {
            resolve({
              latitude: 0,
              longitude: 0
            })
          } else {
            reject(new Error('没有传text参数'))
          }
        })
      }
    }
  }
}
```

**h5环境中调用getLocation**

```javascript
import webviewBridge from '@mpxjs/webview-bridge'
webviewBridge.invoke('getLocation', {
  params: {
    text: '我是入参'
  },
  success: (res) => {
    console.log('接收到的消息：', res.latitude)
  }
})
```

::: warning
`@mpxjs/webview-bridge`只能在h5环境中引入，不能在小程序等宿主环境使用
:::

---

---
url: /guide/extend/extend-component.md
---
# Mpx 扩展组件 {#mpx-extend-components}

除基础组件外，Mpx 额外提供一些扩展组件。扩展组件需要在页面或组件的 `usingComponents` 中注册后使用。若组件仅支持部分平台，跨平台项目中需要通过动态 JSON 配置按平台注册。

```html
<script name="json">
const isRN = __mpx_mode__ === 'ios' || __mpx_mode__ === 'android' || __mpx_mode__ === 'harmony'

module.exports = {
  usingComponents: isRN ? {
    "section-list": "@mpxjs/webpack-plugin/lib/runtime/components/extends/section-list"
  } : {}
}
</script>
```

Mpx 会根据当前编译的目标平台（wx/ali/web/ios/android/harmony），自动解析到对应平台的扩展组件实现。`section-list` 目前仅支持 RN，跨平台项目中应仅在 `ios/android/harmony` 模式注册和使用。

## section-list

跨端虚拟列表组件，可自定义分组头、列表头、列表项，自动分段渲染兼容各端。

支持平台：RN

### 属性 {#section-list-props}

| 属性名                  | 类型         | 默认值   | 说明                   |
|-----------------------|-------------|----------|------------------------|
| height                | String/Number | 100%    | 组件高度                |
| width                 | String/Number | 100%    | 组件宽度                |
| list-data | Array | \[] | 列表数据，如需使用列表分组头 `section-header`，对应 item 的数据需要包含 `isSectionHeader: true` 标识；如需使用列表分组尾 `section-footer`，对应 item 的数据需要包含 `isSectionFooter: true` 标识 |
| enable-sticky          | Boolean     | false    | 启用分组吸顶            |
| scroll-event-throttle  | Number     | 0    | RN 环境特有属性，控制 scroll 事件触发频率                |
| enhanced               | Boolean     | false    | RN 环境特有属性，开启滚动增强能力                         |
| bounces                | Boolean     | true     | RN 环境特有属性，iOS 下边界弹性控制，需同时开启 `enhanced` |
| use-list-header         | Boolean     | false     | 使用自定义列表头        |
| list-header-data        | Object      | {}       | 列表头数据              |
| use-list-footer       | Boolean     | false     | 使用自定义列表页脚        |
| list-footer-data | Object | {} | 列表页脚数据 |
| generic:recycle-item         | String      |       | 列表项，抽象节点组件名，对应组件需要通过 usingComponents 注册               |
| generic:section-header    | String      |       | 列表分组头，抽象节点组件名，对应组件需要通过 usingComponents 注册          |
| generic:section-footer | String | | 列表分组尾，抽象节点组件名，对应组件需要通过 usingComponents 注册 |
| generic:list-header     | String      |       | 列表头，抽象节点组件名，对应组件需要通过 usingComponents 注册       |
| generic:list-footer     | String      |       | 列表页脚，抽象节点组件名，对应组件需要通过 usingComponents 注册       |
| item-height            | Object      | {}       | 列表项高度配置（支持 getter/value），必须配置    |
| section-header-height   | Object      | {}       | 分组头部高度配置（getter/value），若使用了自定义分组头必须配置      |
| section-footer-height | Object | {} | 分组尾部高度配置（getter/value），若使用了自定义分组尾必须配置 |
| list-header-height      | Number      | 0        | 列表头部高度，若使用了列表头必须配置  |
| enable-back-to-top      | Boolean     | false    | 点击状态栏时滚动到顶部，仅 iOS 环境支持 |
| end-reached-threshold   | Number      | 0.1      | 触底事件触发阈值 |
| refresher-enabled       | Boolean     | false    | 开启自定义下拉刷新 |
| refresher-triggered     | Boolean     | false    | 设置当前下拉刷新状态，true 表示已触发 |
| show-scrollbar          | Boolean     | true     | 滚动条显隐控制 |
| enable-item-exposure    | Boolean     | false    | 开启列表项曝光通知 |
| item-exposure-threshold | Number      | 0        | 列表项露出比例达到多少后触发曝光通知，取值 0-100 |
| simultaneous-handlers   | Array\<Object> | \[]    | RN 环境特有属性，允许多个手势同时识别和处理 |
| wait-for                | Array\<Object> | \[]    | RN 环境特有属性，允许延迟激活处理某些手势 |

#### `item-height`/`section-header-height`/`section-footer-height` 格式说明 {#section-list-height-config}

`item-height`、`section-header-height`、`section-footer-height` 支持如下格式：

```js
height: {
  value: 400, // 定高
  getter: function (item, index) {
    const seed = item.id % 2 || 0
    const heights = [100, 300]
    return heights[seed]
  }
}
```

**说明：**

* `value`：默认高度（所有项相同高度时直接用 value 即可）。
* `getter`：函数形式，可接收每一项的数据和索引，按需返回不同高度（动态高度需求时使用）。
* `getter` 优先级 大于 value。

> 建议性能要求较高（如超大数据集）优先使用 `value` 定高。

`list-header-height` 仅支持 Number 类型，用于声明列表头部固定高度，不支持 `getter` / `value` 配置对象。

### 事件 {#section-list-events}

| 事件名                 | 说明                             |
|-----------------------|-----------------------------------|
| bindscroll                | 滚动时触发，`event.detail.scrollTop` 返回纵向滚动位置            |
| bindscrolltolower         | 滚动到底部/触底通知                 |
| bindrefresherrefresh      | 自定义下拉刷新被触发                |
| binditemexposure          | 列表项露出比例达到阈值时触发    |

#### item 曝光事件说明 {#section-list-item-exposure}

开启 `enable-item-exposure` 后，section-list 会使用 RN 的 `onViewableItemsChanged` 追踪 `recycle-item`、`section-header`、`section-footer` 的可见状态；当某个 item 露出比例达到 `item-exposure-threshold` 时，通过 `binditemexposure` 批量通知业务。

```js
{
  items: [
    {
      index: 12,
      itemData: {},
      layout: {
        offset: 650,
        length: 100
      },
      threshold: 50
    }
  ],
  time: 1710000000000
}
```

**说明：**

* `item-exposure-threshold` 为 item 自身可见百分比阈值，0 表示露出任意像素即可触发，100 表示完全可见时触发。
* `index` 为该项在 `list-data` 中的原始下标，`itemData` 为对应原始数据；无法获取原始数据时为 `null`。
* `layout` 为该项在 section-list 内容区域中的布局信息，`offset` 为该项顶部相对列表内容起点的偏移量，`length` 为该项高度；如使用了 `list-header`，`offset` 会包含 `list-header-height` 的偏移；无法获取布局信息时 `offset` 和 `length` 兜底为 `0`。
* 会统计 `recycle-item`、`section-header`、`section-footer`，不统计 `list-header`、`list-footer`。
* `section-header` 曝光统计仅支持 `enable-sticky=false` 场景；开启 `enable-sticky` 时暂不支持统计 `section-header` 曝光。
* 同一个 item 达到阈值后不会在停留期间重复触发；当它划出列表可视区域后会重置本轮状态，再次划入并达到阈值时可再次触发。
* RN 的 `viewabilityConfig` 不支持运行时动态修改，`enable-item-exposure` 与 `item-exposure-threshold` 请在组件初始化时确定。

### 方法 {#section-list-methods}

| 方法名 | 说明 |
|-------|------|
| scrollToIndex | 滚动到指定索引 |

`scrollToIndex({ index, animated, viewOffset, viewPosition })` 参数说明：

* `index`：目标索引
* `animated`：是否滚动动画
* `viewOffset`：滚动偏移量
* `viewPosition`：滚动定位，0:顶部, 0.5:中间, 1:底部

### 用法示例 {#section-list-example}

```js
<section-list
  generic:recycle-item="normal-recycle-item"
  generic:section-header="section-header"
  generic:section-footer="section-footer"
  generic:list-header="list-header"
  width="{{width}}"
  height="{{height}}"
  list-data="{{dataList}}"
  item-height="{{ itemHeight }}"
  section-header-height="{{headerHeight}}"
  section-footer-height="{{footerHeight}}"
  list-header-height="{{listHeaderHeight}}"
  use-list-header="{{true}}"
  enable-sticky="{{true}}"
/>
<script>
  import mpx, { createPage, createComponent } from '@mpxjs/core'

  const generateData = (itemsPerSection) => {
    const data = []

    for (let i = 0; i < 10; i++) {
      data.push({
        isSectionHeader: true,  // 标识该行使用 section-header 对应的抽象节点渲染
        title: `Section ${i + 1}`
      })

      // 添加该 section 的 items
      for (let j = 0; j < itemsPerSection; j++) {
        const itemNumber = i * itemsPerSection + j + 1
        data.push({
          id: itemNumber,
          title: `Item ${itemNumber}`,
          description: `This is item number ${itemNumber} in section ${i + 1}`
        })
      }
      data.push({
        isSectionFooter: true,  // 标识该行使用 section-footer 对应的抽象节点渲染
        title: `Section ${i + 1} Footer`
      })
    }
    return data
  }

  createPage({
    data: {
      width: 0,
      height: 0,
      bufferScale: 5,
      dataList: generateData(100),
      itemHeight: {
        getter: function (item, index) {
          const seed = item.id % 2 || 0
          const heights = [100, 300]
          return heights[seed]
        }
      },
      headerHeight: {
        value: 50
      },
      footerHeight: {
        value: 50
      },
      listHeaderHeight: 100
    },
    onLoad() {
      this.height = mpx.getWindowInfo().windowHeight
      this.width = mpx.getWindowInfo().windowWidth
    }
  })
  </script>
  <script type="application/json">
  {
    "usingComponents": {
      "section-list": "@mpxjs/webpack-plugin/lib/runtime/components/extends/section-list",
      "normal-recycle-item": "@/components/recycle-item",
      "section-header": "@/components/section-header",
      "section-footer": "@/components/section-footer",
      "list-header": "@/components/list"
    }
  }
</script>
```

### 其它说明 {#section-list-notes}

* 当使用了列表项、列表头、自定义分组头或者自定义分组尾，必须配置对应 `item-height`、`section-header-height`、`section-footer-height`、`list-header-height` 高度参数，否则会出现滚动异常情况。
* 可通过 ref 获取实例并调用 `scrollToIndex` 方法实现滚动。
* 如果用户滑动的速度超过渲染的速度，则会先看到空白的内容，这是为了长列表优化不得不作出的妥协。
* 当某行滑出渲染区域之外后，其内部状态将不会保留。
* 在 RN 环境，section-list 通过 RN 提供的 SectionList 实现分组吸顶。受 RN 底层实现机制限制，开启 `enable-sticky` 且快速滑动时，自定义分组头有时会出现闪烁现象。此问题需要等待 RN 官方修复，我们会持续关注并跟进。
* 若某行需要使用 `section-header` 对应的抽象节点渲染，则该行数据必须包含 `isSectionHeader: true` 字段；若某行需要使用 `section-footer` 对应的抽象节点渲染，则该行数据必须包含 `isSectionFooter: true` 字段；否则默认使用 `recycle-item` 对应的抽象节点渲染
* `isSectionFooter: true` 的数据建议放在对应分组的最后一行、下一个 `isSectionHeader: true` 数据之前，用于表示当前分组的尾部。

---

---
url: /guide/understand/runtime.md
---
# Mpx运行时增强原理 {#runtime-enhancement-principle}

数据响应作为Vue最核心的特性，在我们的日常开发中被大量使用，能够极大地提高前端开发体验和效率，我们在框架设计初期最早考虑的就是如何将数据响应特性加入到小程序开发中。在数据响应的实现上，我们引入了MobX，一个实现了纯粹数据响应能力的知名开源项目。借助MobX和mixins，我们在小程序组件创建初期建立了一个响应式数据管理系统，该系统观察着小程序组件中的所有数据(data/props/computed)并基于数据的变更驱动视图的渲染(setData)及用户注册的watch回调，实现了Vue中的数据响应编程体验。与此同时，我们基于MobX封装实现了一个Vuex规范的数据管理store，能够方便地注入组件进行全局数据管理。为了提高跨团队开发的体验，我们对store添加了多实例可合并的特性，不同团队维护自己的store，在需要时能够合并他人或者公共的store生成新的store实例，我们认为这是一种比Vuex中modules更加灵活便捷的跨团队数据管理模式

作为一个接管了小程序setData的数据响应开发框架，我们高度重视Mpx的渲染性能，通过小程序官方文档中提到的性能优化建议可以得知，setData对于小程序性能来说是重中之重，setData优化的方向主要有两个：

1. 尽可能减少setData调用的频次
2. 尽可能减少单次setData传输的数据

为了实现以上两个优化方向，我们做了以下几项工作：

* 将组件的静态模板编译为可执行的render函数，通过render函数收集模板数据依赖，只有当render函数中的依赖数据发生变化时才会触发小程序组件的setData，同时通过一个异步队列确保一个tick中最多只会进行一次setData，这个机制和Vue中的render机制非常类似，大大降低了setData的调用频次；
* 将模板编译render函数的过程中，我们还记录输出了模板中使用的数据路径，在每次需要setData时会根据这些数据路径与上一次的数据进行diff，仅将发生变化的数据通过数据路径的方式进行setData，这样确保了每次setData传输的数据量最低，同时避免了不必要的setData操作，进一步降低了setData的频次。

![Mpx数据响应机制流程示意图](https://gift-static.hongyibo.com.cn/static/kfpub/3547/runtime.jpeg)

*Mpx数据响应机制流程示意图*

---

---
url: /guide/understand/compile.md
---
# Mpx编译构建原理 {#compile-principle}

我们希望使用目前设计最强大、生态最完善的编译构建工具Webpack来实现小程序的编译构建，让用户得到web开发中先进强大的工程化开发体验。使用过Webpack的同学都知道，通常来说Webpack都是将项目中使用到的一系列碎片化模块打包为一个或几个bundle，而小程序所需要的文件结构是非常离散化的，如何调解这两者的矛盾成为了我们最大的难题。一种非常直观简单的思路在于遍历整个src目录，将其中的每一个.mpx文件都作为一个entry加入到Webpack中进行处理，这样做的问题主要有两个：

1. src目录中用不到的.mpx文件也会被编译输出，最终也会被小程序打包进项目包中，无意义地增加了包体积；
2. 对于node\_modules下的.mpx文件，我们不认为遍历node\_modules是一个好的选择。

最终我们采用了一种基于依赖分析和动态添加entry的方式来进行实现，用户在Webpack配置中只需要配置一个入口文件app.mpx，loader在解析到json时会解析json中pages域和usingComponents域中声明的路径，通过动态添加entry的方式将这些文件添加到Webpack的构建系统当中（注意这里是添加entry而不是添加依赖，因为只有entry能生成独立的文件，满足小程序的离散化文件结构），并递归执行这个过程，直到整个项目中所有用到的.mpx文件都加入进来，在输出前，我们借助了CommonsChunkPlugin/SplitChunksPlugin的能力将复用的模块抽取到一个外部的bundle中，确保最终生成的包中不包含重复模块。我们提供了一个Webpack插件和一个.mpx文件对应的loader来实现上述操作，用户只需要将其添加到Webpack配置中就可以以打包web项目的方式正常打包小程序，没有任何的前置和后置操作，支持Webpack本身的完整生态。

![Mpx编译构建机制流程示意图](https://gift-static.hongyibo.com.cn/static/kfpub/3547/mpx-liucheng.002.jpeg)

*Mpx编译构建机制流程示意图*

## 分包处理 {#subpackage-processing}

构建时对于非JS资源，是所有的包串行处理，资源map会精确记录每个包中引用了哪些资源。

在主包的处理过程中，将主包页面中引用的所有非js资源(组件、外部样式、外部模板、wxs，图像媒体等)都记录下来，在处理分包时，对分包内引用的非js资源都进行检查，如果被主包引用过则输出到主包中，否则标记为分包only的资源输出到分包目录下。

由于主包和分包限制相同，一般情况下分包体积远小于主包体积
，而微信小程序的体积限制策略主要卡主包体积不得超过2M，因此，Mpx设定的是主包体积优先策略，即尽可能减小主包体积，为此，会将分包资源尽可能打到分包去。

组件和静态资源的输出规则如下：

1. 主包引用的资源输出至主包
2. 分包引用且主包引用过的资源输出至主包，不在当前分包重复输出
3. 分包引用且无其他包引用的资源输出至当前分包
4. 分包引用且其他分包也引用过的资源，重复输出至当前分包
5. 当用户通过packageName query显式指定了资源的所属包时，输出至指定的包

如此复杂的分包策略也完全是为了尽可能良好地支持处理分包引用npm资源，因此不管在主包还是分包中，使用Mpx框架开发小程序，可以享受最舒适最自然最好用的npm机制。

而小程序原生的分包是不具备这个能力，只能引用自己分包下的资源，同时大部分基于web技术而来的转译型框架应该也都是不会考虑这个部分的。

甚至如果出现这种场景：同一个组件在A分包和B分包中都有使用，但未在主包使用，会将这个组件分别放入A分包和B分包而不是主包。（是否需要这样可自行斟酌，如果不希望出现这种情况，可在主包中引入一次该组件就会被收到主包去，全局就这一份了）

总结一下：

对于组件，若同时被多个分包引用，主包未引用，会有多份分包存在于各分包中。一旦被主包使用，就仅有一份存在于主包中。

对于资源（例如纯JS模块），若被主包使用，会被收集到主包里。若被多个分包使用，会被收集进主包的bundle里。若仅被某分包使用，就会在分包的bundle.js里（视模块大小及引用次数也可能被内联到某个组件JS里）。

进阶用户有更花式的需求可通过packageName query来显式指定输出。

---

---
url: /guide/migrate/2.9.md
---
# 从 2.8 升级至 2.9 {#upgrade-2.8-to-2.9}

Mpx 2.9 版本不包含破坏性变更，主要新增了原子类支持、输出 web 支持 SSR 和构建产物体积优化三项核心特性，更详细的介绍查看[这里](../../articles/2.9-release.md)

## 依赖升级 {#dependency-upgrade}

如果你从既有项目中进行升级，仅需将 @mpxjs 下的依赖升级至 2.9 即可

```json5
{
  "dependencies": {
    "@mpxjs/api-proxy": "^2.9.0",
    "@mpxjs/core": "^2.9.0",
    "@mpxjs/store": "^2.9.0",
    "@mpxjs/pinia": "^2.9.0",
    "@mpxjs/utils": "^2.9.0",
    "@mpxjs/fetch": "^2.9.0",
    // ...
  },
  "devDependencies": {
    "@mpxjs/webpack-plugin": "^2.9.0",
    "@mpxjs/size-report": "^2.9.0",
    "@mpxjs/babel-plugin-inject-page-events": "^2.9.0",
    // 如需使用原子类，加入以下依赖
    "@mpxjs/unocss-plugin": "^2.9.0",
    "@mpxjs/unocss-base": "^2.9.0",
    // 如需使用SSR，加入以下依赖
    "axios": "^1.6.0",
    "express": "^4.18.2",
    "serve-favicon": "^2.5.0",
    "vue-server-renderer": "^2.7.14",
    // ...
  }
}
```

## 使用原子类 {#use-utility-class}

详情查看[这里](../advance/utility-first-css.md)

## 使用SSR {#use-ssr}

详情查看[这里](../advance/ssr.md)

---

---
url: /guide/migrate/2.8.md
---
# 从 2.7 升级至 2.8 {#upgrade-2.7-to-2.8}

不同于 2.7 版本对于编译构建进行的大幅度变动升级，Mpx@2.8 版本升级的核心在于运行时支持组合式 API 能力，并尽可能追求向前兼容，以降低用户的升级成本。我们默认脚手架生成的全新项目已经适配了 2.8 版本的全部变更，如果你需要将旧项目从 2.7 升级至 2.8 版本，下面是详细的升级指引。

## 依赖升级 {#dependency-upgrade}

请按照下方列表升级或新增相关依赖：

```json5
{
  "dependencies": {
    "@mpxjs/api-proxy": "^2.8.0",
    "@mpxjs/core": "^2.8.0",
    "@mpxjs/store": "^2.8.0",
    "@mpxjs/pinia": "^2.8.0",
    "@mpxjs/utils": "^2.8.0",
    "@mpxjs/fetch": "^2.8.0",
    // 这部分依赖为输出 web 专用，如项目无需输出 web 可以省略
    "vue": "^2.7.10",
    "vue-demi": "^0.13.11",
    "vue-i18n": "^8.27.2",
    "vue-i18n-bridge": "^9.2.2"
  },
  "devDependencies": {
    "@mpxjs/webpack-plugin": "^2.8.0",
    "@mpxjs/size-report": "^2.8.0",
    "@mpxjs/babel-plugin-inject-page-events": "^2.8.0",
    // ...
  }
}
```

## 编译配置变更 {#compile-config-change}

在编译配置方面，用户几乎不用进行任何改变，唯一的例外是当用户想要通过组合式 API 的方式注册具有副作用的页面事件时，需要在 `babel` 配置中添加 `@mpxjs/babel-plugin-inject-page-events` 插件，如下所示：

```json5
// babel.config.json
{
 "plugins": [
    [
      "@babel/transform-runtime",
      {
        "corejs": 3,
        "version": "^7.10.4"
      }
    ],
    "@mpxjs/babel-plugin-inject-page-events"
  ]
}
```

关于副作用页面事件的更多详情查看[这里](../composition-api/composition-api.md#page-events-with-side-effects)。

## 运行时破坏性变化 {#runtime-breaking-changes}

在 2.8 开发过程中，我们修正了过去版本中存在的不合理的设计与实现，在运行时带来了少许破坏性改变，详情如下：

* 框架过往提供的组件增强生命周期 `pageShow/pageHide` 与微信原生提供的 `pageLifetimes.show/hide` 完全对齐，不再提供组件初始挂载时必定执行 `pageShow` 的保障（因为组件可能在后台页面进行挂载），相关初始化逻辑一定不要放置在 `pageShow` 当中；
* 取消了框架过去提供的基于内部生命周期实现的非标准增强生命周期，如 `beforeCreate/onBeforeCreate` 等，直接将内部生命周期变量导出提供给用户使用，详情查看[这里](../composition-api/composition-api.md#framework-built-in-lifecycle)；
* 为了优化 tree shaking，作为框架运行时 `default export` 的 `Mpx` 对象不再挂载 `createComponent/createStore` 等运行时方法，一律通过 `named export` 提供，`Mpx` 对象上仅保留 `set/use` 等全局 API；
* 使用 I18n 能力时，为了与新版 vue-i18n 保持对齐，`this.$i18n` 对象指向全局作用域，如需创建局部作用域需要使用组合式 API `useI18n` 的方式进行创建。
* `watch` API 不再接受第二个参数为带有 `handler` 属性的对象形式（该参数形式只应存在于 `watch` option 中），第二个参数必须为回调函数，与 [Vue](https://vuejs.org/api/reactivity-core.html#watch) 对齐。

---

---
url: /guide/migrate/2.7.md
---
# 从旧版本迁移至 2.7 {#migrate-to-2.7}

自 2.7 版本开始，Mpx 将编译构建流程基于 Webpack5 进行了**全面的重构**，优化解决了老的编译流程中存在的大量历史遗留问题，安全完整地支持了基于文件系统的持久化缓存，大幅提升了 Mpx 想的编译构建速度，以滴滴出行小程序为例，无缓存场景下相较 2.6 版本提速约 180%，有缓存场景下提速约 **10** 倍。

与此同时，Mpx 2.7 版本还带来了 rules 复用，完善的单元测试支持，独立分包构建，分包异步化等众多新特性。直接通过 @mpxjs/cli 创建的新项目就能够直接使用这些新特性，如果你对于编译构建没有太多定制化诉求，我们也推荐使用 @mpxjs/cli 新建项目，并将老项目中的 src 目录 copy 覆盖至新项目的方式进行迁移，这是一种成本最低的迁移方式。

如果你的老项目中已经对编译构建进行了高度的定制，本文将提供详细的迁移工作指引。

## 依赖升级 {#dependency-upgrade}

将下面列出的相关依赖升级至对应版本，如果有其他自行引入的 loader 也确保将其升级至 webpack5 兼容的版本：

```json5
{
  "dependencies": {
    "@mpxjs/api-proxy": "^2.7.1",
    "@mpxjs/core": "^2.7.1",
    "@mpxjs/fetch": "^2.7.1",
  },
  "devDependencies": {
    "@mpxjs/webpack-plugin": "^2.7.1",
    "webpack": "^5.64.4",
    "webpack-merge": "^5.8.0",
    "terser-webpack-plugin": "^5.2.5",
    "copy-webpack-plugin": "^9.0.1",
    "webpack-bundle-analyzer": "^4.5.0",
    "ts-loader": "^9.2.6",
    // eslint相关配置，按需安装
    "eslint": "^7.32.0",
    "eslint-config-standard": "^16.0.3",
    "eslint-plugin-html": "^6.2.0",
    "eslint-plugin-import": "^2.25.2",
    "eslint-plugin-node": "^11.1.0",
    "eslint-plugin-promise": "^5.1.1",
    "eslint-webpack-plugin": "^3.1.0",
  }
}
```

## 开启持久化缓存 {#enable-persistent-cache}

在 webpack 配置中添加以下配置项：

```js
module.exports = {
  cache: {
    type: 'filesystem',
    // 声明构建配置，注意如果声明某个文件夹为构建配置，需要在文件夹下放置空的package.json文件，避免构建依赖收集时将主项目的依赖项视为构建依赖
    buildDependencies: {
      build: [resolve('build/')],
      config: [resolve('config/')]
    },
    cacheDirectory: resolve('.cache/')
  },
  snapshot: {
    // 如果希望修改node_modules下的文件时对应的缓存可以失效，可以将此处的配置改为 managedPaths: []
    managedPaths: [resolve('node_modules/')]
  },
}
```

## 修改rules {#modify-rules}

在 2.7 版本中，我们优化了 .mpx 文件中各个 block 应用 loader 的规则。

在之前的版本中，我们基本上使用内置的规则对 .mpx 中的 block 应用 loaders，如：对 \<script> 应用 babel-loader，对 \<style lang="stylus"> 应用 stylus-loader。这种方式的弊端主要在于用户无法便捷地自定义 block 的 loaders 应用规则，比如传入特定的 loaders 配置。

在 2.7 版本中，我们支持了构建时读取用户在 module.rules 中配置的规则来对 block 进行 loaders 应用， 例如：对于 \<style lang="stylus"> 我们会对其应用用户在 rules 中对于 .stylus 文件 配置的 loaders，当用户没有在 block 中声明 lang 属性时，我们也会兜底使用不同区块默认的 lang 来进行 rules 匹配。

因此，相较于过去的版本，我们需要在 rules 中添加一些规则使得 .mpx 文件中的各类 block 都能得到正确的处理。

```js
module.exports = {
  module: {
    rules: [
      // 新版本中rules规则对.mpx文件中的区块同样生效，在旧版本中.mpx文件中script会走内置的babel转义，但是新版当中只有在include范围内的.mpx文件才会走babel，但由于新版本中.mpx文件中的script会采用.mpx.js的格式来匹配rules，因此我们可以用如下include条件让其保持与旧版本一致的表现。
      {
        test: /\.js$/,
        loader: 'babel-loader',
        include: [/\.mpx\.js/, resolve('src'), resolve('test'), resolve('node_modules/@mpxjs')]
      },
      // 如使用ts编码则需要添加本条rule
      {
        test: /\.ts$/,
        use: [
          'babel-loader',
          {
            loader: 'ts-loader',
            options: {
              appendTsSuffixTo: [/\.(mpx|vue)$/]
            }
          }
        ]
      },
      // 处理json区块
      {
        test: /\.json$/,
        resourceQuery: /asScript/,
        type: 'javascript/auto'
      },
      // 处理wxs
      {
        test: /\.(wxs|qs|sjs|qjs|jds|dds|filter\.js)$/,
        use: [
          MpxWebpackPlugin.wxsPreLoader()
        ],
        enforce: 'pre'
      },
      // 处理图像资源
      {
        test: /\.(png|jpe?g|gif|svg)$/,
        use: [
          MpxWebpackPlugin.urlLoader({
            name: 'img/[name][hash].[ext]'
          })
        ]
      },
      // 下面的rules输出小程序时需配置，如输出web需要修改为vue的相关rules，具体逻辑可以参考脚手架项目中build/getRules.js
      // mpx主loader
      {
        test: /\.mpx$/,
        use: MpxWebpackPlugin.loader(currentMpxLoaderConf)
      },
      // 如使用sass/less等其他预编译语言，自行修改test规则并用sass/less-loader替换stylus-loader
      {
        test: /\.styl(us)?$/,
        use: [
          MpxWebpackPlugin.wxssLoader(),
          'stylus-loader'
        ]
      },
      // 处理未使用预编译语言的style区块和独立样式文件
      {
        test: /\.(wxss|acss|css|qss|ttss|jxss|ddss)$/,
        use: MpxWebpackPlugin.wxssLoader()
      },
      // 处理未使用预编译语言的template区块和独立模板文件
      {
        test: /\.(wxml|axml|swan|qml|ttml|qxml|jxml|ddml)$/,
        use: MpxWebpackPlugin.wxmlLoader()
      }
    ]
  }
}
```

## entry配置修改 {#modify-entry-config}

如果进行常规的小程序输出，无需关注。如进行插件输出或独立输出组件/页面等特殊场景，mpx 提供了辅助方法来生成对应的 entry request，示例如下：

```js
module.exports = {
  entry:{
    // 输出plugin
    plugin: MpxWebpackPlugin.getPluginEntry('./plugin.json'),
    // 独立输出组件，相当于./list.mpx?isComponent，不过为了保障后续该配置不受框架内部query变动影响，建议使用辅助方法
    list: MpxWebpackPlugin.getComponentEntry('./list.mpx'),
    // 独立输出页面，相当于./index.mpx?isPage
    index: MpxWebpackPlugin.getPageEntry('./index.mpx')
  }
}
```

## MpxWebpackPlugin配置变更 {#mpx-webpack-plugin-config-change}

* 移除了forceDisableInject配置
* nativeOptions更名为nativeConfig

上述的内容中只列举了一些和 mpx 高度相关的配置项变更，如果你的项目使用了特定的插件或者loader，请确保将其升级至兼容 webpack5 的版本。

---

---
url: /guide/migrate/mpx-cli-3.md
---
# mpx-cli v2 迁移到 v3 {#migrate-v2-to-v3}

## 升级`@mpxjs/cli` {#upgrade-cli}

```
npm install @mpxjs/cli@3.x -g
```

## 配置迁移 {#config-migration}

> v3 兼容了 v2 的所有配置，如果没有特殊修改，则不需要进行配置迁移。

* `config/devServer.js`迁移到`vue.config.js`下的`devServer`
* `config/mpxPlugin.conf.js`迁移到`vue.config.js`下的`pluginOptions.mpx.plugin`
* `config/mpxLoader.conf.js`迁移到`vue.config.js`下的`pluginOptions.mpx.loader`

```js
// vue.config.js
const { defineConfig } = require('@vue/cli-service')
module.exports = defineConfig({
  pluginOptions: {
    mpx: {
      srcMode: 'wx',
      plugin: {
        // 这里等同于`@mpxjs/webpack-plugin`的参数
      },
      loader: {
        // 这里等同于`mpx-loader`参数
      }
    }
  },
  devServer: {
    // dev服务配置
  }
})
```

## 新增自定义配置/修改已有配置参数 {#custom-config-change}

```js
// vue.config.js
const { defineConfig } = require('@vue/cli-service')

module.exports = defineConfig({
  chainWebpack(config) {
    config.plugin('newPlugin').use(newPlugin, [params])
    // 使用mpx inspect 可以根据注释来查看插件命名
    config.plugin('mpx-webpack-plugin').tap(args => newArgs)
  },
  // 或者也可以通过configureWebpack配置,这里返回的配置会通过webpack-merge合并到内部配置中
  configureWebpack() {
    return {
      plugins: [new Plugin()]
    }
  }
})
```

* [webpack-chain](https://github.com/neutrinojs/webpack-chain)
* [webpack-merge](https://github.com/survivejs/webpack-merge)

## 编译后钩子 {#after-compile-hook}

由于 webpack 配置都内置到了插件里，所以编译后的钩子无法像 2.x 一样直接在`webpack`脚本里添加。

这里有两个方案来解决上述问题

1. `webpack`插件
2. 新建一个`mpx-cli`插件

例如我们新建一个`vue-cli-plugin-mpx-build-upload`插件,用来在构建完成后上传图片到`cdn`。

```js
// index.js
module.exports = function (api, options) {
  function runServiceCommand(api, command, ...args){
    const { fn } = api.service.commands[command]
    return fn && fn(...args)
  }
  // 注册一个新的命令
  api.registerCommand('build:upload', function deploy(...args) {
    // 运行原有的build命令，build会返回一个promise来表示构建完成
    return runServiceCommand(api, 'build', ...args).then(() =>
      // do something
      uploadFile()
    )
  })
}
```

然后在我们的项目里安装该插件并运行`npx mpx-cli-service build:upload`即可。

## 项目结构变化 {#project-structure-change}

![项目结构变化](https://gift-static.hongyibo.com.cn/static/kfpub/3547/filetree.jpg)

v3 版本相对于 v2 版本的目录结构更加清晰。

* 移除了`config/build`的配置目录，将其统一到了插件配置当中，可以通过`vue.config.js`修改。
* `index.html`移动到`public`目录下。
* 增加`jsconfig.json`,让类型提示更加友好。

## More

v3 版本相对于 v2 版本的整体架构相差较大，v3 版本主要基于`vue-cli`架构，主要有以下优势。

### 1. 插件化 {#plugin-architecture}

v3 版本的配置依靠插件化，将 v2 版本的文件配置整合到了各个自定义插件中。

* vue-cli-plugin-mpx-eslint eslint 配置
* vue-cli-plugin-mpx-mp 小程序构建配置以及命令
* vue-cli-plugin-mpx-plugin-mode 插件配置
* vue-cli-plugin-mpx-typescript ts 配置
* vue-cli-plugin-mpx-web web 构建配置以及命令

除此之外，也可以使用统一的`vue.config.js`来自定义配置，或者将配置抽离到插件当中，来进行统一的管理。

### 2. 模板 {#template}

v3 版本的模板也可以通过插件进行自定义生成，同时不依赖于 github，在国内网络下不会有生成模板时网络错误的问题。

### 3. 调试 {#debug}

v3 版本可以通过`mpx inspect:mp/web`来直接调试相关配置，可以更直观的发现配置错误。

### 4. 插件管理 {#plugin-management}

使用`mpx invoke`/`mpx add`/`mpx upgrade`来管理插件，可以更细粒度的控制相关配置的更新。

---

---
url: /api/app-config.md
---
# 全局配置 {#global-config}

`Mpx.config` 是一个对象，包含 Mpx 的全局配置。可以在启动应用之前修改下列 property：

## useStrictDiff

`boolean = false`

每次有数据变更时，是否使用严格的 diff 算法。如果项目中有大数据集的渲染建议使用，可以提升效率。

```javascript
import mpx from '@mpxjs/core'
mpx.config.useStrictDiff = true
```

> 注意：由于微信小程序的bug，同时使用`useStrictDiff`和增强指令`wx:style`时，要注意更改数据的方式。如下所示：

```javascript
// 入口文件
import mpx, { createApp } from '@mpxjs/core'
mpx.config.useStrictDiff = true

// 页面page文件
<template>
  <view>
    <view wx:style="{{style}}">test</view>
  </view>
</template>

<script>
  import { createPage } from '@mpxjs/core'
  createPage({
    data: {
      style: {
        color: 'red',
        fontSize: '18px'
      }
    },
    onLoad () {
      setTimeout(() => {
        this.setData({ // 当useStrictDiff设置true时，需要用setData的方式设置整个style对象
          style: {
            color: 'blue',
            fontSize: '18px'
          }
        })
        // this.style.color = 'blue' // 当useStrictDiff设置true时，不能使用这种方式，style不会生效
      }, 1000)
    }
  })
</script>
```

## ignoreWarning

`boolean = false`

是否忽略运行时的 warning 信息，默认不忽略。

```js
import mpx from '@mpxjs/core'
mpx.config.ignoreWarning = true
```

## ignoreProxyWhiteList

`Array<string> = ['id']`

Mpx 实例上的 key（包括data、computed、methods）如果有重名冲突，在`ignoreProxyWhiteList`配置中的属性会被最新的覆盖；而不在`ignoreProxyWhiteList`配置中的属性，不会被覆盖。

> 只要有重名冲突均会有报错提示。

```javascript
import mpx from '@mpxjs/core'
mpx.config.ignoreConflictWhiteList = ['id', 'test']
```

## observeClassInstance

`boolean = false`

当需要对 class 对象的数据进行响应性转化，需要开启该选项。

## proxyEventHandler

`Function`

需要代理的事件的钩子方法，该钩子方法仅对内联传参事件或 [forceProxyEventRules](compile.md#forceproxyeventrules) 规则匹配的事件生效。

```js
import mpx from '@mpxjs/core'

mpx.config.proxyEventHandler = function (event, componentIns) {
  // 首个入参为 event 事件对象
  // 其次入参为 触发事件的组件实例
}
```

## setDataHandler

```ts
function setDataHandler(data: object, target: ComponentIns<{}, {}, {}, {}, []>): any
```

页面/组件状态更新时，使用该方法可以对 setData 调用进行监听，可以用来统计 setData 调用次数和数据量的统计，方法的入参是 setData 传输的 data 和当前组件实例。

```js
import mpx from '@mpxjs/core'

mpx.config.setDataHandler = function(data, comp) {
    console.log('setData trigger', data, comp)
}
```

## forceFlushSync

`boolean = false`

Mpx 中更改响应性状态时，最终页面的更新并不是同步立即生效的，而是由 Mpx 将它们缓存在一个队列中， 异步等到下一个 tick 一起执行，如果想将所有队列的执行改为同步执行，我们可以通过该配置来实现。

```js
import mpx from '@mpxjs/core'

mpx.config.forceFlushSync = true
```

## errorHandler

`Function`

```js
mpx.config.errorHandler = function (errmsg, location, error) {
  // errmsg: 框架内部运行报错的报错归类信息，例如当执行一个watch方法报错时，会是 "Unhandled error occurs during execution of watch callback!"
  // location: 具体报错的代码路径，可选项，不一定存在。在 production 模式下会变为页面/组件的 hash id
  // error: 具体的错误堆栈，可选项，不一定存在
  // handle error
}
```

Mpx 框架运行时报错捕获感知处理函数。

* Mpx 框架生命周期执行错误；
* Mpx 中的 computed、watch 等内置方法执行报错；
* Mpx 框架的运行时的检测报错，例如存在目标平台不支持的属性，入参出参类型错误等；

同时被捕获的错误会通过 console.error 输出。

**注意**：在 production 模式下，`location` 参数会变为页面/组件的 hash id。如需查找 hash id 与实际文件路径（resourcePath）的对应关系，可以通过以下方式：

1. 在构建配置中开启 `generateBuildMap` 选项
2. 构建完成后，在输出目录中查看生成的 `outputMap.json` 文件
3. 在该文件的 `moduleIdMap` 字段中查找 hash id 与 resourcePath 的映射关系

这样可以帮助开发者在生产环境中快速定位错误发生的具体文件位置。

## webRouteConfig

Mpx 通过 config 暴露出 webRouteConfig 配置项，在 web 环境可以对路由进行配置。
此配置后续将被废弃，请使用 webConfig 进行配置

* **用法**:

```js
mpx.config.webRouteConfig = {
  mode: 'history'
}
```

## webConfig

web 环境下的一些配置，如路由模式

* **用法**:

```js
// 修改路由模式
mpx.config.webConfig.routeConfig = {
  mode: 'history'
}
// 禁用页面切换动画
mpx.config.webConfig.disablePageTransition = true
```

此处的 `disablePageTransition` 后续将被废弃，请使用编译阶段的[disablePageTransition](compile.md#webconfig)进行配置

### webConfig.enableTitleBar

`boolean = false`

是否在 Web 输出时启用内置标题栏（`mpx-titlebar`）组件。默认为 `false`，即不渲染标题栏。

设为 `true` 后，Mpx 会在每个页面的根节点外层自动注入 `<mpx-titlebar>` 组件，读取 `app.json` 的 `window` 配置及当前页面 json 配置，渲染与小程序视觉一致的 fixed 标题栏（含安全区适配与返回按钮）。

> **注意**：若页面 json 中将 `navigationStyle` 配置为 `'custom'`，则该页面的标题栏会自动隐藏，以支持自定义导航栏场景。

```js
import mpx from '@mpxjs/core'

mpx.config.webConfig.enableTitleBar = true
```

### webConfig.safeAreaInsetTop

`number = 24`

在 **Android** 设备上，标题栏顶部安全区（状态栏）的高度（单位：px）。仅在 `enableTitleBar` 为 `true` 且非 iOS 设备时生效；iOS 设备会自动使用 `env(safe-area-inset-top)` 获取安全区高度，无需手动配置。

```js
import mpx from '@mpxjs/core'

// 将 Android 状态栏高度设为 28px（默认 24px）
mpx.config.webConfig.safeAreaInsetTop = 28
```

---

---
url: /api/global-api.md
---
# 全局 API {#global-api}

## 全局对象 Mpx {#global-mpx}

`@mpxjs/core` 默认导出 mpx 全局实例对象，通过该实例对象我们可以访问部分应用实例 API

### mixin

全局注入mixin方法接收两个参数：mpx.mixin(mixins, options)

* 第一个参数是要混入的mixins，接收类型 `MixinObject|MixinObject[]`
* 第二个参数是为全局混入配置，形如`{types:string|string[], stage:number}`，其中`types`用于控制mixin注入的范围，可选值有`'app'|'page'|'component'`；`stage`用于控制注入mixin的插入顺序，当stage为负数时，注入的mixin会被插入到构造函数配置中的`options.mixins`之前，数值越小约靠前，反之当stage为正数时，注入的mixin会被插入到`options.mixins`之后，数值越大越靠后。

> 所有mixin中生命周期的执行均先于构造函数配置中直接声明的生命周期，mixin之间的执行顺序则遵从于其在`options.mixins`数组中的顺序

> options的默认值为`{types: ['app','page','component'], stage: -1}`，不传stage时，全局注入mixin的声明周期默认在`options.mixins`之前执行

```js
import mpx from '@mpxjs/core'
// 只在page中混入
mpx.mixin({
  methods: {
    getData: function(){}
  }
}, {
  types:'page'
})

// 默认混入，在app|page|component中都会混入
mpx.mixin([
  {
    methods: {
      getData: function(){}
    }
  },
  {
    methods: {
      setData: function(){}
    }
  }
])

// 只在component中混入，且执行顺序在options.mixins之后
mpx.mixin({
  attached() {
    console.log('com attached')
  }
}, {
  types: 'component',
  stage: 100
})
```

### injectMixins

该方法是 `mpx.mixin` 方法的别名，`mpx.injectMixins({})` 等同于 `mpx.mixin({})`

### observable

```ts
function observable(options: object): Mpx
```

用于创建响应式数据。

```js
import mpx from '@mpxjs/core'
// 直接通过 mpx 对象访问
const b = mpx.observable(object)
```

* **注意：**
  Mpx 2.8 版本后该 API 等同于 `reactive`，同时不再支持具名导出方式，建议直接使用 `reactive` 替代，请[点击](/api/reactivity-api/basic-reactivity.html#reactive)查看。

### set

用于对一个响应式对象新增属性，会`触发订阅者更新操作`。[查看详情](global-api.md#set)

### delete

```ts
function delete(target: Object, key: string | number): void
```

用于对一个响应式对象删除属性，会`触发订阅者更新操作`

```js
import mpx, { reactive } from '@mpxjs/core'
const person = reactive({name: 1})
mpx.delete(person, 'age')
```

* **注意：**
  `mpx.delete` 也可以使用具名导出的 `del`。[查看详情](/api/global-api.html#del)

### use

> 用于安装外部扩展, 支持多参数
> 方法接收两个参数：mpx.use(plugin, options)

* 第一个参数是要安装的外部扩展
* 第二个参数是对象，如果第二个参数是一个包含（prefix or postfix）的option， 那么将会对插件扩展的属性添加前缀或后缀

```js
import mpx from '@mpxjs/core'
import test from './test'
mpx.use(test)
mpx.use(test, {prefix: 'mpx'}, 'otherparams')
```

### watch

watch 可以通过全局实例访问，也可以使用具名导出的方式，二者逻辑相同，我们推荐使用具名导出的方式。[查看详情](reactivity-api/computed-watch-api.html#watch)

## createApp

> 注册一个小程序，接受一个 Object 类型的参数

```js
import {createApp} from '@mpxjs/core'

createApp({
  onLaunch () {
    console.log('Launch')
  },
  onShow () {
    console.log('Page show')
  },
  //全局变量 可通过getApp()访问
  globalDataA: 'I am global dataA',
  globalDataB: 'I am global dataB'
})
// 或者
createApp(options)
```

## createPage

> 类微信小程序（微信、百度、头条等）内部使用[Component的方式创建页面](https://developers.weixin.qq.com/miniprogram/dev/framework/custom-component/component.html)，所以除了支持页面的生命周期之外还同时支持组件的一切特性。当使用 Component 创建页面时，页面生命周期需要写在 methods 内部（微信小程序原生规则），mpx 进行了统一封装转换，页面生命周期都写在最外层即可

```ts
function createPage(options: object, config?: object): void
```

* options:

  具体形式除了 computed、watch 这类 Mpx 扩展特性之外，其他的属性都参照原生小程序的官方文档即可。

* config:

  如果希望标识一个组件是最纯粹的原生组件，不用数据响应等能力，可通过 config.isNative 传 true 声明。
  如果有需要复写/改写最终调用的创建页面的构造器，可以通过 config 对象的 customCtor 提供。

  * **注意:**
    mpx本身是用 component 来创建页面的，如果传page可能在初始化时候生命周期不正常导致取props有一点问题

```js
import {createPage} from '@mpxjs/core'

createPage({
  data: {test: 1},
  computed: {
    test2 () {
      return this.test + 1
    }
  },
  watch: {
    test (val, old) {
      console.log(val, old)
    }
  },
  onShow () {
    this.test++
  }
})
```

## createComponent

> 创建自定义组件，接受两个Object类型的参数。

```ts
function createComponent(options: object, config?: object): void
```

```js
import {createComponent} from '@mpxjs/core'

createComponent({
  properties: {
    prop: {
      type: Number,
      value: 10
    }
  },
  data: {test: 1},
  computed: {
    test2 () {
      return this.test + this.prop
    }
  },
  watch: {
    test (val, old) {
      console.log(val, old)
    },
    prop: {
      handler (val, old) {
        console.log(val, old)
      },
      immediate: true // 是否首次执行一次
    }
  }
})
```

## nextTick

```ts
function nextTick(callback: Function): void
```

当我们在 Mpx 中更改响应性状态时，最终页面的更新并不是同步立即生效的，而是由 Mpx 将它们缓存在一个队列中， 等到下一个 tick 一起执行，
从而保证了组件/页面无论发生多少状态改变，都仅执行一次更新，从而减少 `setData` 调用次数。

`nextTick()` 可以在状态改变后立即调用，可以传递一个函数作为参数，在等待页面/组件更新完成后，函数参数会触发执行。

```js
     import {createComponent, nextTick, ref} from '@mpxjs/core'
     createComponent({
       setup (props, context) {
         const showChild = ref(false)
         // DOM 还没有更新
         setTimeOut(() => {
            showChild.value = true
         }, 2000)
         nextTick(function() {
           context.refs['child'].showToast()
         })
         return {
           showChild
         }
       }
     })
```

## toPureObject

```ts
function toPureObject(options: object): object
```

业务拿到的数据可能是响应式数据实例（包含了些其他属性），使用`toPureObject`方法可以将响应式的数据转化成纯 js 对象。

```js
import {toPureObject} from '@mpxjs/core'
const pureObject = toPureObject(object)
```

## getMixin

专为ts项目提供的反向推导辅助方法，该函数接收类型为 `Object` ,会将传入的嵌套mixins对象拉平成一个扁平的mixin对象

```js
import { createComponent, getMixin} from '@mpxjs/core'
// 使用mixins，需要对每一个mixin子项进行getMixin辅助函数包裹，支持嵌套mixin
const mixin = getMixin({
  mixins: [getMixin({
    data: {
      value1: 2
    },
    lifetimes: {
      attached () {
        console.log(this.value1, 'attached')
      }
    },
    mixins: [getMixin({
      data: {
        value2: 6
      },
      created () {
        console.log(this.value1 + this.value2 + this.outsideVal)
      }
    })]
  })]
})
/*
mixin值
{
  data: {value2: 6, value1: 2},
  created: ƒ created(),
  attached: ƒ attached()
}
*/
createComponent({
  data: {
    outsideVal: 20
  },
  mixins: [mixin]
})

/*
以上执行输出：
28
2 "attached"
*/
```

## implement

```ts
function implement(name: string, options: object): object
```

* `{Object} options`
  * `{Array} modes`：需要取消的平台
  * `{Boolean} remove`：是否将此能力直接移除
  * `{Function} processor`：设置成功的回调函数

以微信为 base 将代码转换输出到其他平台时（如支付宝、web 平台等），会存在一些无法进行模拟的跨平台差异，会在运行时进行检测并报错指出，例如微信转支付宝时使用 moved 生命周期等。使用`implement`方法可以取消这种报错。您可以使用 mixin 自行实现跨平台差异，然后使用 implement 取消报错。

```js
import {implement} from '@mpxjs/core'

if (__mpx_mode__ === 'web') {
  const processor = () => {
  }
  implement('onShareAppMessage', {
    modes: ['web'], // 需要取消的平台，可配置多个
    remove: true, // 是否将此能力直接移除
    processor // 设置成功的回调函数
  })
}
```

## 内建生命周期变量 {#built-in-lifecycle-variable}

Mpx 在运行时自身有着一套内建生命周期，当开发者想使用内建生命周期时，可以通过内建生命周期变量进行对应生命周期的注册，
需要注意的是，这部分内建生命周期变量**只能用于选项式 API 中**。

### BEFORECREATE

`string`

在组件实例刚刚被创建时执行，在实例初始化之后、进行数据侦听和 data 初始化之前同步调用，注意此时不能调用 setData。

```js
import {createComponent, BEFORECREATE} from "@mpxjs/core"

createComponent({
  [BEFORECREATE]() {
      console.log('beforecreate trigger')
  }
})
```

### CREATED

`string`

在组件实例刚刚被创建时执行。在这一步中，实例已完成对选项的处理，意味着以下内容已被配置完毕：数据侦听、计算属性、事件/侦听器的回调函数。
然而，挂载阶段还没开始，注意此时不能调用 setData。

```js
import {createComponent, CREATED} from "@mpxjs/core"

createComponent({
  [CREATED]() {
      console.log('beforecreate trigger')
  }
})
```

### BEFOREMOUNT

选项式 API 中使用，作用同[onBeforeMount](composition-api.md#onbeforemount)

### MOUNTED

选项式 API 中使用，作用同[onMounted](composition-api.md#onmounted)

### BEFOREUPDATE

选项式 API 中使用，作用同[onBeforeUpdate](composition-api.md#onbeforeupdate)

### UPDATED

选项式 API 中使用，作用同[onUpdated](composition-api.md#onupdated)

### SERVERPREFETCH

选项式 API 中使用，作用同[onServerPrefetch](composition-api.md#onserverprefetch)

### BEFOREUNMOUNT

选项式 API 中使用，作用同[onBeforeUnmount](composition-api.md#onbeforeunmount)

### UNMOUNTED

选项式 API 中使用，作用同[onUnmounted](/api/composition-api.html#onunmounted)

### ONLOAD

选项式 API 中使用，作用同[onLoad](composition-api.md#onload)

### ONSHOW

选项式 API 中使用，作用同[onShow](composition-api.md#onshow)

### ONHIDE

选项式 API 中使用，作用同[onHide](composition-api.md#onhide)

### ONRESIZE

选项式 API 中使用，作用同[onResize](composition-api.md#onresize)

## 响应式 API {#reactivity-api}

详情请[移步](reactivity-api.md)

## 组合式 API {#composition-api}

详情请[移步](composition-api.md)

## store API

详情请[移步](store-api.md)

---

---
url: /api/instance-api.md
---
# 实例 API {#instance-api}

## $set

```ts
function $set(target: Object | Array, property: string | number, value: any): void
```

这是全局 `mpx.set` 的别名。向响应式对象中添加一个 property，并确保这个新 property 同样是响应式的，且触发视图更新。
它必须用于向响应式对象上添加新 property，因为 Mpx 无法探测普通的新增 property (比如 this.myObject.newProperty = 'hi')

* **参考**：[mpx.set](global-api.md#set)

## $watch

```ts
function $watch(expOrFn: string | Function, callback: Function | Object, options?: Object): Function
```

观察 Mpx 实例上的一个表达式或者一个函数计算结果的变化。回调函数得到的参数为新值和旧值。表达式只接受监督的键路径。对于更复杂的表达式，用一个函数取代。

```javascript
// 键路径
this.$watch('a.b.c', function (newVal, oldVal) {
  // 做点什么
})

// 函数
this.$watch(
  function () {
    // 表达式 `this.a + this.b` 每次得出一个不同的结果时
    // 处理函数都会被调用。
    // 这就像监听一个未被定义的计算属性
    return this.a + this.b
  },
  function (newVal, oldVal) {
    // 做点什么
  }
)
```

`this.$watch` 返回一个取消观察函数，用来停止触发回调：

```javascript
var unwatch = this.$watch('a', cb)
// 之后取消观察
unwatch()
```

* `options.deep`

为了发现对象内部值的变化，可以在选项参数中指定 deep: true。注意监听数组的变更不需要这么做。

```javascript
this.$watch('someObject', callback, {
  deep: true
})
this.someObject.nestedValue = 123
// callback is fired
```

* `options.deep`

在选项参数中指定 `immediate: true` 将立即以表达式的当前值触发回调：

```javascript
this.$watch('a', callback, {
  immediate: true
})
// 立即以 `a` 的当前值触发回调
```

注意在带有 immediate 选项时，你不能在第一次回调时取消侦听给定的 property。

```javascript
// 这会导致报错
var unwatch = this.$watch(
  'value',
  function () {
    doSomething()
    unwatch()
  },
  { immediate: true }
)
```

如果你仍然希望在回调内部调用一个取消侦听的函数，你应该先检查其函数的可用性：

```javascript
var unwatch = this.$watch(
  'value',
  function () {
    doSomething()
    if (unwatch) {
      unwatch()
    }
  },
  { immediate: true }
)
```

* `options.pausable`

可在选项参数中指定 pausable: true 来声明一个可被暂停的 Watcher 实例，配置好之后可以通过 this.$getPausableWatchers() 来获取当前组件或者页面下定义的所有可被暂停的 Watcher 实例，
然后根据具体是业务场景通过 watcher.pause() 或者 watcher.resume() 来暂停或者恢复 watch 的监听。
比如说在小程序页面 hide 时不需要监听的 watch 可以配置为 pausable: true，在页面 hide 时调用 watcher.pause() 暂停监听，在页面 show 时调用 watcher.resume() 来恢复监听。

```javascript
this.$watch('someObject', callback, {
  pausable: true
})

const isHide = false
const watchers = this.$getPausableWatchers()
if (watchers && watchers.length) {
  for (let i = 0; i < watchers.length; i++) {
    const watcher = watchers[i]
    isHide && watcher.pause()
    !isHide && watcher.resume()
  }
}
```

* `options.name`

为了方便获取用户定义的 Watcher 实例，可在选项参数增加配置 name 来设置当前 Watcher 实例的名称，配置 name 后可通过 this.$getWatcherByName(name) 在组件或页面中获取到命名为 name 的 Watcher 实例（注意当存在多个 name 相同 watch 时，this.$getWatcherByName 获取的最后一个使用该 name
创建的 Watcher 实例，所以为了避免混淆，请不要在多个 watch 中配置同一个 name。）

```javascript
this.$watch('someObject', callback, {
  name: 'someObject'
})

const someObjectWatch = this.$getWatcherByName('someObject')
```

**参考**：[mpx.watch](global-api.md#watch)

## $delete

```ts
function $delete(target: Object, key: string | number): void
```

删除对象属性，如果该对象是响应式的，那么该方法可以触发观察器更新（视图更新 | watch回调）

```js
  import {createComponent} from '@mpxjs/core'
  createComponent({
  data: {
    info: {
      name: 'a'
    }
  },
  watch: {
    'info' (val) {
      // 当删除属性之后会执行
      console.log(val)
    }
  },
  attached () {
    // 删除name属性
    this.$delete(this.info, 'name')
  }
  })
```

**参考：** [Mpx.delete](global-api.md#delete)

## $refs

`Object`

一个对象，持有注册过 [ref](../api/directives.html#wx-ref)的所有 DOM 元素和组件实例，调用响应的组件方法或者获取视图节点信息。

以获取组件为例，模版中引用child子组件

```html
<child wx:ref="childDom"></child>
```

javascript 中可以调用组件的方法

```javascript
import { createComponent } from '@mpxjs/core'
createComponent({
ready (){
  // 调用child中的方法
  this.$refs.childDom.childMethods()
  // 获取child中的data
  this.$refs.childDom.data
  },
})
```

**参考：** [组件 ref](../guide/basic/refs.md)

## $asyncRefs

**仅字节小程序可用**，因为字节小程序 `selectComponent` 和 `selectAllComponents` 方法为异步方法，因此使用 $refs 同步获取组件实例并不保证能够拿到正确的组件实例，需使用异步 `$asyncRefs`。

```js
import mpx, {createComponent} from '@mpxjs/core'

createComponent({
  ready() {
    if (__mpx_mode__ === 'tt') {
      this.$asyncRefs.mlist.then(res => {
        const data = res.data
        //......
      })
    }
  }
})
```

## $forceUpdate

```ts
function $forceUpdate(target: Object, callback: Function): void
```

用于强制刷新视图，正常情况下只有`发生了变化的数据`才会被发送到视图层进行渲染。强制更新时，会将某些数据强制发送到视图层渲染，无论是否发生了变化

```js
import {createComponent} from '@mpxjs/core'
createComponent({
  data: {
    info: {
      name: 'a'
    },
    age: 100
  },
  attached () {
    // 虽然不会修改age的值，但仍会触发重新渲染，并且会将age发送到视图层
    this.$forceUpdate({
      age: 100
    }, () => {
      console.log('视图更新后执行')
    })

    // 也可用于正常的数据修改，key支持Path，数组可以使用'array[index]'：value的形式
    this.$forceUpdate({
      'info.name': 'b'
    }, () => {
      console.log('视图更新后执行')
    })
  }
})
```

## $nextTick

```ts
function $nextTick(callback: Function): void
```

将回调延迟到下次 DOM 更新循环之后执行。在修改数据之后立即使用它，然后等待 DOM 更新。**注意：`callback`中`this`并不是绑定当前实例，你可以使用箭头函数避免this指向问题**。

```js
import {createComponent} from '@mpxjs/core'
  createComponent({
  data: {
    info: {
      name: 1
    }
  },
  attached () {
    // 修改数据
    this.info.name = 2
    // DOM 还没有更新

    // this.$nextTick(function() {
    //   // DOM 现在更新了
    //   console.log('会在由name变化引起的视图更新之后执行')
    //   this.doSomthing() // 报错
    // })
    this.$nextTick(() => {
      // DOM 现在更新了
      console.log('会在由name变化引起的视图更新之后执行')
      this.doSomthing()
    })
  }
})
```

## $i18n

组件中直接调用$i18n的方法，比如：$t，$tc，$te，$d，$n

首先在`mpx.plugin.conf.js`中配置i18n

```js
module.exports = {

  //...

  i18n: {
    locale: 'en-US',
    // messages既可以通过对象字面量传入，也可以通过messagesPath指定一个js模块路径，在该模块中定义配置并导出，dateTimeFormats/dateTimeFormatsPath和numberFormats/numberFormatsPath同理
    messages: {
      'en-US': {
        message: {
          hello: '{msg} world'
        }
      },
      'zh-CN': {
        message: {
          hello: '{msg} 世界'
        }
      }
    }
  }
}
```

组件中直接使用

```js
<template>
  <view>{{$t('message.hello')}}</view>
</template>

import {createComponent} from '@mpxjs/core'
createComponent({
  ready () {
    console.log(this.$t('message.hello', { msg: 'hello' }))
    console.log(this.$te('message.hello')) 
    //...
  }
})
```

## $rawOptions

`Object`

获取组件或页面构造器的构造参数。

```js
import { createComponent } from "@mpxjs/core"

createComponent({
  ready() {
    console.log(this.$rawOptions)
    /**
     * attached
     * detached
     * methods
     * mpxConvertMode
     * mpxCustomKeysForBlend
     * mpxFileResource
     * ready
     * setup
     * ...其他构造参数
     */
  }
})
```

---

---
url: /api/store-api.md
---

# Store API

**注意：** 以下 API 在 **2.8** 版本后无法通过全局应用实例 `mpx` 访问。若项目中有类似 mpx.createStore 的用法，在升级到 **2.8** 版本后请进行修改。

## createStore

```ts
function createStore(options: Object): Store
```

> 创建一个全局状态管理容器，实现复杂场景下的组件通信需求

* `options`

  options 可指定以下属性：

  * **state**: `Object`

    store的根 state 对象。

    [详细介绍](../guide/advance/store.md#state)

  * **mutations**: `{ [type: string]: Function }`

    在 store 上注册 mutation，处理函数总是接受 state 作为第一个参数（如果定义在模块中，则为模块的局部状态），payload 作为第二个参数（可选）。

    [详细介绍](../guide/advance/store.md#mutation)

  * **actions**: `{ [type: string]: Function }`

    在 store 上注册 action。处理函数总是接受 context 作为第一个参数，payload 作为第二个参数（可选）。

    context 对象包含以下属性：
    ``js
        {
          state,      // 等同于 `store.state`
          commit,     // 等同于 `store.commit`
          dispatch,   // 等同于 `store.dispatch`
          getters     // 等同于 `store.getters`
        }
        ``
    同时如果有第二个参数 payload 的话也能够接收。

    [详细介绍](../guide/advance/store.md#action)

  * **getters**：`{[key: string]: Function }`

    在 store 上注册 getter，getter 方法接受以下参数：

    ```js
    {
      state,     // 如果在模块中定义则为模块的局部状态
      getters   // 等同于 store.getters
    }
    ```

    注册的 getter 暴露为 store.getters。

    [详细介绍](../guide/advance/store.md#getter)

  * **modules**：`Object`

    包含了子模块的对象，会被合并到 store，大概长这样：

    ```js
    {
      key: {
        state,
        mutations,
        actions?,
        getters?,
        modules?
        },
        // ...
    }
    ```

    与根模块的选项一样，每个模块也包含 state 和 mutations 选项。模块的状态使用 key 关联到 store 的根状态。模块的 mutation 和 getter 只会接收 module 的局部状态作为第一个参数，而不是根状态，并且模块 action 的 context.state 同样指向局部状态。

    [详细介绍](../guide/advance/store.md#modules)

  * **deps**：`Object`

    包含了当前store依赖的第三方store：

    ```js
    {
      store1: storeA,
      store2: storeB
    }
    ```

    [详细介绍](../guide/advance/store.md#modules)

```js
import {createStore} from '@mpxjs/core'
const store1 = createStore({
  state: {
    count: 0
  },
  mutations: {
    increment (state) {
      state.count++
    }
  },
  actions: {
    increment (context) {
      context.commit('increment')
    }
  },
  ...
})
const store2 = createStore({ ...options })
```

### **Store 实例属性** {#store-instance-properties}

* **state**：`Object`
  根状态。
* **getters**：`Object`
  暴露出注册的 getter。

### **Store 实例方法** {#store-instance-methods}

* commit

```js
commit(type: string, payload?: any, options?: Object) | commit(mutation: Object, options?: Object)
```

提交 mutation。[详细介绍](../guide/advance/store.md#mutation)

* dispatch

```js
dispatch(type: string, payload?: any, options?: Object) | dispatch(action: Object, options?: Object)
```

分发 action。返回一个Promise。[详细介绍](../guide/advance/store.md#action)

* mapState

```js
mapState(map: Array<string> | Object): Object
```

为组件创建计算属性以返回 store 中的状态。[详细介绍](../guide/advance/store.md#state)

* mapGetters

```js
mapGetters(map: Array<string> | Object): Object
```

为组件创建计算属性以返回 getter 的返回值。[详细介绍](../guide/advance/store.md#getter)

* mapActions

```js
mapActions(map: Array<string> | Object): Object
```

创建组件方法分发 action。[详细介绍](../guide/advance/store.md#action)

* mapMutations

```js
mapMutations(map: Array<string> | Object): Object
```

创建组件方法提交 mutation。[详细介绍](../guide/advance/store.md#mutation)

* mapStateToRefs

```ts
mapStateToRefs(maps: Array<string> | Object): {
    [key: string]: ComputedRef<any>
}
```

**组合式 API 特有**，在组合式 API 场景下解构访问 getter 并保持 getter 响应性，可以使用该方法。[详细介绍](../guide/advance/store.md#use-store-in-composition-api)

* mapGettersToRefs

```js
mapGettersToRefs(maps: Array<string> | Object): {
    [key: string]: ComputedRef<any>
}
```

**组合式 API 特有**，在组合式 API 场景下需解构访问 state 并保持 state 响应性，可以使用该方法。[详细介绍](../guide/advance/store.md#use-store-in-composition-api)

## createStoreWithThis

```ts
function createStoreWithThis(store: Store): Store
```

> createStoreWithThis 为 createStore 的变种方法，主要为了在 `Typescript` 环境中，可以更好地支持 store 中的类型推导。
> 其主要变化在于定义 getters， mutations 和 actions 时，
> 自身的 state，getters 等属性不再通过参数传入，而是会挂载到函数的执行上下文 this 当中，通过 this.state 或 this.getters 的方式进行访问。
> 由于TS的能力限制，getters/mutations/actions 只有使用对象字面量的方式直接传入 createStoreWithThis 时
> 才能正确推导出 this 的类型，当需要将 getters/mutations/actions 拆解为对象编写时，需要用户显式地声明 this 类型，无法直接推导得出。

```js

import {createComponent, getMixin, createStoreWithThis} from '@mpxjs/core'

const store = createStoreWithThis({
  state: {
    aa: 1,
    bb: 2
  },
  getters: {
    cc() {
      return this.state.aa + this.state.bb
    }
  },
  actions: {
    doSth3() {
      console.log(this.getters.cc)
      return false
    }
  }
})

createComponent({
  data: {
    a: 1,
    b: '2'
  },
  computed: {
    c() {
      return this.b
    },
    d() {
      // data, mixin, computed中定义的数据能够被推导到this中
      return this.a + this.aaa + this.c
    },
    // 从store上map过来的计算属性或者方法同样能够被推导到this中
    ...store.mapState(['aa'])
  },
  mixins: [
    // 使用mixins，需要对每一个mixin子项进行getMixin辅助函数包裹，支持嵌套mixin
    getMixin({
      computed: {
        aaa() {
          return 123
        }
      },
      methods: {
        doSth() {
          console.log(this.aaa)
          return false
        }
      }
    })
  ],
  methods: {
    doSth2() {
      this.a++
      console.log(this.d)
      console.log(this.aa)
      this.doSth3()
    },
    ...store.mapActions(['doSth3'])
  }
})
```

## createStateWithThis

```ts
function createStateWithThis(state: Object): Object
```

> createStateWithThis 为创建 state 提供了类型推导，对于基本类型可以由 TypeScript 自行推导，使用其他类型时，推荐使用 as 进行约束

```js
import { createStateWithThis } from '@mpxjs/core'

export type StatusType = 'start' | 'running' | 'stop'

export default createStateWithThis({
  status: 'running' as StatusType
})
```

## createGettersWithThis

```ts
function createGettersWithThis(getters: Object, options: Object):Object
```

* getters

  需要定义的 getters 对象。
* options（可选参数）

  在 options 中可以传入 state，getters，deps。由于 getter 的类型推论需要基于 state，所以导出 getters 时，需要将 state 进行传入。deps 是作为一个扩展存在，getters 可以通过 deps 中传入的其他 store 来获取值，当 store 没有其他需要依赖的 deps 时可以不传。createMutationsWithThis 和 createActionsWithThis 同理。

```js
import { createGettersWithThis, createStoreWithThis } from '@mpxjs/core'

export default createGettersWithThis({
  isStart () {
    return this.state.status === 'start'
  },
  getNum () {
    return this.state.base.test + this.getters.base.getTest
  }
}, {
  state,
  deps: {
    base: createStoreWithThis({
      state: {
        testNum: 0
      },
      getters: {
        getTest () {
          return this.state.testNum * 2
        }
      }
    })
}})
```

## createMutationsWithThis

```ts
function createMutationsWithThis(mutations: Object, options: Object): Object
```

* mutations

  需要定义的 mutations 对象。
* options（可选参数）

  在 options 中可以传入 state，deps。

```js
import { createMutationsWithThis } from '@mpxjs/core'

export default createMutationsWithThis({
  setCurrentStatus (payload: StatusType) {
    this.state.status = payload
  }
}, { state })
```

## createActionsWithThis

```ts
function createActionsWithThis(actions: Object, options: Object): Object
```

* actions

  需要定义的 actions 对象。
* options（可选参数）

  由于action 可以同时调用 getters、mutations，所以需要将这些都传入，以便进行类型推导。因此 options 可以传入 state、getters、mutations、deps。

```js
import { createActionsWithThis } from '@mpxjs/core'
import state, { StatusType } from './state'
import getters from './getters'
import mutations from './mutations'

export default createActionsWithThis({
  testActions (payload: StatusType) {
    return Promise.resolve(() => {
      this.commit('setCurrentStatus', payload)
    })
  }
}, {
  state,
  getters,
  mutations
})
```

---

---
url: /api/directives.md
---
# 模板指令 {#template-directives}

## wx:if

`any`

根据表达式的值的 [truthiness](https://developer.mozilla.org/zh-CN/docs/Glossary/Truthy) 来有条件地渲染元素。在切换时元素及它的数据绑定 / 组件被销毁并重建。 **注意：如果元素是 `<block/>`, 注意它并不是一个组件，它仅仅是一个包装元素，不会在页面中做任何渲染，只接受控制属性**。

::: danger
当和 `wx:if` 一起使用时，`wx:for` 的优先级比 `wx:if` 更高。详见列[表渲染教程](../guide/basic/list-render.md)
:::

**参考：** [条件渲染 - wx:if](../guide/basic/conditional-render.md)

## wx:elif

`any`

前一兄弟元素必须有 `wx:if` 或 `wx:elif`。表示 `wx:if` 的“ `wx:elif` 块”，可以链式调用。

```html
<view wx:if="{{type === 'A'}}">
  A
</view>
<view wx:elif="{{type === 'B'}}">
  B
</view>
<view wx:elif="{{type === 'C'}}">
  C
</view>
<view wx:else>
  Not A/B/C
</view>
```

**参考：** [条件渲染 - wx:elif](../guide/basic/conditional-render.md)

## wx:else

不需要表达式，前一兄弟元素必须有 `wx:if` 或 `wx:elif`

为 `wx:if` 或者 `wx:elif` 添加 `wx:else` 块

```html
<view wx:if="{{type === 'A'}}">
  A
</view>
<view wx:else>
  Not A
</view>
```

**参考：** [条件渲染 - wx:else](../guide/basic/conditional-render.md)

## wx:for

`Array | Object | number | string`

在组件上使用 `wx:for` 控制属性绑定一个数组，即可使用数组中各项的数据重复渲染该组件。默认数组的当前项的下标变量名默认为 `index`，数组当前项的变量名默认为 `item`

```html
<view wx:for="{{array}}">
  {{ index }}: {{ item.message }}
</view>

// 0: foo
// 1: bar
```

```js
Page({
  data: {
    array: [{
      message: 'foo'
    }, {
      message: 'bar'
    }]
  }
})
```

`wx:for` 的默认行为会尝试原地修改元素而不是移动它们。要强制其重新排序元素，你需要用特殊 `attribute key` 来提供一个排序提示：

```html
<view wx:for="{{array}}" wx:key="id">
  {{ item.text }}
</view>

// foo
// bar
```

```js
import { createComponent } from '@mpxjs/core'
createComponent({
  data: {
    array: [{
      id: 1, text: 'foo'
    }, {
      id: 2, text: 'bar'
    }]
  }
})
```

::: danger
当和 `wx:if` 一起使用时，`wx:for` 的优先级比 `wx:if` 更高。详见列[表渲染教程](../guide/basic/list-render.md)
:::

`wx:for` 的详细用法可以通过以下链接查看教程详细说明。

**参考：** [列表渲染 - wx:for](../guide/basic/list-render.md)

## wx:for-index

`string`

使用 wx:for-index 可以指定数组当前下标的变量名：

```html
<view wx:for="{{array}}" wx:key="id" wx:for-index="idx">
  {{ idx }}: {{ item.text }}
</view>

// 0: foo
// 1: bar
```

```js
import { createComponent } from '@mpxjs/core'
createComponent({
  data: {
    array: [{
      id: 1, text: 'foo'
    }, {
      id: 2, text: 'bar'
    }]
  }
})
```

**参考：** [列表渲染 - wx:for-index](../guide/basic/list-render.md)

## wx:for-item

`string`

使用 wx:for-item 可以指定数组当前元素的变量名：

```html
<view wx:for="{{[1, 2, 3, 4, 5, 6, 7, 8, 9]}}" wx:for-item="i">
  <view wx:for="{{[1, 2, 3, 4, 5, 6, 7, 8, 9]}}" wx:for-item="j">
    <view wx:if="{{i <= j}}">
      {{i}} * {{j}} = {{i * j}}
    </view>
  </view>
</view>
```

**参考：** [列表渲染 - wx:for-item](../guide/basic/list-render.md)

## wx:key

`number | string`

如果列表中项目的位置会动态改变或者有新的项目添加到列表中，并且希望列表中的项目保持自己的特征和状态，需要使用 wx:key 来指定列表中项目的唯一的标识符。
**注意：如不提供 wx:key，会报一个 warning， 如果明确知道该列表是静态，或者不必关注其顺序，可以选择忽略**。

有相同父元素的子元素必须有独特的 key。重复的 key 会造成渲染错误。

常见的用例是结合 `wx:for`：

```html
<view wx:for="{{array}}" wx:key="id">
  {{ item.text }}
</view>
```

**参考：** [列表渲染 - wx:for](../guide/basic/list-render.md)

## wx:class

绑定HTML Class: 类似vue的class绑定

# 对象用法 {#object-usage}

我们可以传给 `wx:class` 一个对象，以动态地切换 class：

```html
<view wx:class="{{ {active: isActive} }}">
  这是一段测试文字
</view>
```

你可以在对象中传入更多字段来动态切换多个 class。此外，`wx:class` 指令也可以与普通的 class attribute 共存。

```html
<view class="static" wx:class="{{ {active: isActive, text-danger: hasError} }}">
  这是一段测试文字
</view>
```

```js
<script>
  import {createComponent} from '@mpxjs/core'

  createComponent({
    data: {
     isActive: true,
     hasError: false
    }
  })
</script>
```

渲染为：

```html
<view class="static active">
  这是一段测试文字
</view>
```

**注意：由于微信的限制，`wx:class` 中的 key 值不能使用引号（如: { 'my-class-name': xx }）**

绑定的数据对象不必内联定义在模板里：

```html
<view wx:class="{{ classObject }}">
  这是一段测试文字
</view>
```

```js
<script>
  import {createComponent} from '@mpxjs/core'

  createComponent({
    data: {
      classObject: {
        active: true,
        'text-danger': false
      }
    }
  })
</script>
```

我们也可以在这里绑定一个返回对象的计算属性。

如果你也想根据条件切换列表中的 class，可以用三元表达式：

```html
<view wx:class="{{ isActive ? 'active' : '' }}">
  这是一段测试文字
</view>
```

# 数组用法 {#array-usage}

我们可以把一个数组传给 `wx:class`，以应用一个 class 列表：

```html
<view wx:class="{{[activeClass, errorClass]}}">
  这是一段测试文字
</view>
```

```js
<script>
  import {createComponent} from '@mpxjs/core'

  createComponent({
    data: {
      activeClass: 'active',
      errorClass: 'text-danger'
    }
  })
</script>
```

渲染为：

```html
<view wx:class="active text-danger">
  这是一段测试文字
</view>
```

**参考：** [类名样式绑定 - 类名绑定](../guide/basic/class-style-binding.md#class-binding)

## wx:style

`wx:style` 的对象语法十分直观——看着非常像 CSS，但其实是一个 JavaScript 对象。CSS property 名可以用驼峰式 (camelCase) 或短横线分隔 (kebab-case) 来命名：

```html
<view wx:style="color: {{activeColor}}; font-size: {{fontSize}}px; fontWeight: bold">
  这是一段测试文字
</view>
```

```js
<script>
  import {createComponent} from '@mpxjs/core'

  createComponent({
    data: {
      activeColor: 'red',
      fontSize: 30
    }
  })
</script>
```

直接绑定到一个样式对象通常更好，这会让模板更清晰：

```html
<view wx:style="{{styleObject}}">
  这是一段测试文字
</view>
```

```js
<script>
  import {createComponent} from '@mpxjs/core'

  createComponent({
    data: {
      styleObject: {
        color: 'red',
        fontWeight: 'bold'
      }
    },
  })
</script>
```

同样的，对象语法常常结合返回对象的计算属性使用。

`wx:style` 的数组语法可以将多个样式对象应用到同一个元素上

```html
<view wx:style="{{[baseStyles, overridingStyles]}}">
  这是一段测试文字
</view>
```

**参考：** [类名样式绑定 - 样式绑定](../guide/basic/class-style-binding.md#style-binding)

## wx:model

除了小程序原生指令之外，mpx 基于input事件提供了一个指令 wx:model, 用于双向绑定。

```html
<template>
  <view>
    <input wx:model="{{val}}"/>
    <input wx:model="{{test.val}}"/>
    <input wx:model="{{test['val']}}"/>
  </view>
</template>

<script>
  import {createComponent} from '@mpxjs/core'
  createComponent({
    data: {
      val: 'test',
      test: {
        val: 'xxx'
      }
    }
  })
</script>
```

wx:model并不会影响相关的事件处理函数，比如像下面这样：

```html
<input wx:model="{{inputValue}}" bindinput="handleInput"/>
```

**参考：** [双向绑定](../guide/basic/two-way-binding.md)

## wx:model-prop

wx:model 默认使用 `value` 属性传值，使用 `wx:model-prop` 定义 wx:model 指令对应的属性；

## wx:model-event

wx:model 默认监听 `input` 事件，可以使用 `wx:model-event` 定义 wx:model 指令对应的事件；

父组件

```html
<template>
  <customCheck wx:model="{{checked}}" wx:model-prop="checkedProp" wx:model-event="checkedChange"></customCheck>
</template>

<script>
  import {createPage} from '@mpxjs/core'
  createPage({
    data: {
      checked: true
    }
  })
</script>
<script type="application/json">
  {
    "usingComponents": {
      "customCheck": "./customCheck"
    }
  }
</script>

```

子组件：(customCheck.mpx)

```html
<template>
  <view bindtap="handleTap" class="viewProps">{{checkedProp}}</view>
</template>

<style lang="stylus">
  .viewProps {
    width 100px
    height 100px
    color #000
  }
</style>

<script>
  import {createComponent} from '@mpxjs/core'
  createComponent({
    properties: {
      checkedProp: Boolean
    },
    methods: {
      handleTap () {
        // 这里第二个参数为自定义事件的detail，需要以下面的形式传递值以保持与原生组件对齐
        this.triggerEvent('checkedChange', {
          value: !this.checkedProp
        })
      }
    }
  })
</script>
```

如示例，当子组件被点击时，父组件的checked数据会发生变化

> 注意：由于微信限制，如果事件名使用横线分割（'checked-change'）,将不可以再使用该特性

## wx:model-value-path

定义了 `wx:model` 双向绑定时从 `event.detail` 中获取更新值的访问路径。
默认值为 `value`，即通过 `event.detail.value` 获取更新值。

并非所有的组件都会按微信的标准格式 `event.detail.value` 来传值，例如 vant 的 input 组件，值是通过抛出 `event.detail` 本身传递的，这时我们可以设置 `wx:model-value-path="[]"` 直接将 `event.detail` 作为更新值。

```html
<vant-field wx:model-value-path="[]" wx:model="{{a}}"></vant-field>
```

## wx:model-filter

在使用 `wx:model` 时我们可能需要像 Vue 的 `.trim` 、`.lazy` 这样的修饰符来对双向数据绑定的数据进行过滤和修饰；Mpx 通过增强指令 `wx:model-filter` 可以实现这一功能；
该指令可以绑定内建的 filter 或者自定义的 filter 方法，该方法接收过滤前的值，返回过滤操作后的值。

例如我们希望拿到的 input 元素中的数据是经过 trim 的。示例：

> 当然，Mpx 已经内置了 trim 过滤器；可以通过 wx:model-filter="trim" 直接使用；

```html
<template>
  <view class="cover-page">
    <view>
       <!-- wx:model-filter 过滤wx:model 的值-->
      <input type="text" wx:model-filter="trimSpace" wx:model="{{filterData}}" />
      <view >{{filterData.length}}</view>
    </view>
  </view>
</template>

<script>
  import { createPage } from '@mpxjs/core'
  createPage({
    data: {
      filterData: 'model-filter'
    },
    trimSpace (val) {
      // wx:model-filter 绑定的 filter 方法
      return typeof val === 'string' && val.trim()
    },
    methods: {
    }
  })
</script>
```

filter 方法除可以是和 `methods` 平级的方法，还可以是 `methods` 中的方法。

```html
<template>...</template>  
<script>
  import { createPage } from '@mpxjs/core'
  createPage({
    data: {
      filterData: 'model-filter'
    },
    methods: {
      trimSpace (val) {
        // wx:model-filter 支持将过滤器方法定义成 methods 中的方法
        return typeof val === 'string' && val.trim()
      }
    }
  })
</script>
```

## wx:ref

`string`

Mpx提供了 `wx:ref=xxx` 来更方便获取 WXML 节点信息的对象。在JS里只需要通过this.$refs.xxx 即可获取节点。

```html
  <view wx:ref="tref">
    123
  </view>

  <script>
    Page({
      ready () {
        this.$refs.tref.fields({size: true}, function (res) {
          console.log(res)
        }).exec()
      }
    })
  </script>
```

**参考：** [获取组件实例 - wx:ref](../guide/basic/refs.md)

## wx:show

`boolean`

与 `wx:if` 所不同的是**不会移除节点**，而是设置节点的 `style` 为 `display: none`。

```html
<view wx:show="{{show}}">
  123
</view>
```

```js
import {createPage} from '@mpxjs/core'
createPage({
  data: {
    show: false
  }
})
```

## bind

`string`

让 `bind + (:?) + eventType` 作为属性值

比如：`bindtap`

```html
<view bindtap="tapTest"> Click me! </view>
<view bind:tap="tapTest1(testVal, $event)"> Click me! </view>
```

```js
Page({
  methods: {
    tapTest () {
      console.log('Clicked!')
    },
    tapTest1 (val, event) {
      console.log(val, event)
    }
  }
})
```

Mpx做了增强的**内联传参**能力以及具体有哪些事件**类型**参考下方

**参考：** [事件处理 - bind](../guide/basic/event.md)

## catch

`string`

让 `catch + (:?) + eventType` 作为属性值

除 `bind` 外，也可以用 `catch` 来绑定事件。与 `bind` 不同，`catch` 会阻止事件向上冒泡。

```html
<view id="outer" bindtap="handleTap1">
  outer view
  <view id="middle" catchtap="handleTap2">
    middle view
    <view id="inner" bindtap="handleTap3">
      inner view
    </view>
  </view>
</view>
```

```js
Page({
  methods: {
    handleTap1 () {
      console.log('outer')
    },
    handleTap2 () {
      console.log('middle')
    },
    handleTap3 () {
      console.log('inner')
    }
  }
})
// 通过几个操作看出被catchtap的middle view阻止了向上冒泡
// click outer
// outer

// click middle
// middle

// click inner
// inner
// middle
```

**参考：** [事件处理 - catch](../guide/basic/event.md)

## capture-bind

`string`

让 `capture-bind + (:?) + eventType` 作为属性值

capture-bind要在bind之前执行，是因为事件是先捕获后冒泡，**注意：仅触摸类事件支持捕获阶段**

```html
  <view id="outer" bind:touchstart="handleTap1" capture-bind:touchstart="handleTap2">
    outer view
    <view id="inner" bind:touchstart="handleTap3" capture-bind:touchstart="handleTap4">
      inner view
    </view>
  </view>
```

点击inner view的调用顺序是(handleTap)2、4、3、1

**参考：** [事件处理 - capture-bind](../guide/basic/event.md)

## capture-catch

`string`

让 `capture-catch + (:?) + eventType` 作为属性值

capture-catch中断捕获阶段和取消冒泡阶段

```html
<view id="outer" bind:touchstart="handleTap1" capture-catch:touchstart="handleTap2">
  outer view
  <view id="inner" bind:touchstart="handleTap3" capture-bind:touchstart="handleTap4">
    inner view
  </view>
</view>
```

点击inner view仅执行handleTap2

**参考：** [事件处理 - capture-catch](../guide/basic/event.md)

## @mode

`type mode = 'wx' | 'ali' | 'qq' | 'swan' | 'tt' | 'web' | 'qa' | 'ios' | 'android' | 'harmony'`

### 属性中使用 {#use-in-attribute}

跨平台输出场景下，Mpx 框架允许用户在组件上使用 @ 和 | 符号来指定某个节点或属性只在某些平台下有效。

```html
<button
  open-type@wx|swan|ios="getUserInfo"
  bindgetuserinfo@wx|swan|ios="getUserInfo"
  open-type@ali|ios="getAuthorize"
  scope@ali="userInfo"
  enable-background@ios|android="{{ true }}"
  onTap@ali="onTap">
  获取用户信息
</button>
```

例如在上述示例中：

* 在支付宝小程序与微信和百度小程序等平台分别生效的 open-type 等属性
* 在输出iOS或android平台时，enable-background 属性生效
* 以及事件绑定或其他属性灵活的进行条件编译

假设当前 srcMode 为 wx，目标平台为 ali，则输出产物为：

```html
<button
  open-type="getAuthorize"
  scope="userInfo"
  onTap="onTap">
  获取用户信息
</button>
```

假设当前 srcMode 为 wx，目标平台为 ios，则输出产物为：

```html
<button
  open-type="getAuthorize"
  bindgetuserinfo="getUserInfo"
  open-type="getAuthorize"
  enable-background="{{ true }}"
  >
  获取用户信息
</button>
```

### 节点中使用 {#use-in-node}

同时，该指令也可以作用在单个节点上，来对节点进行跨平台条件判断。

但需要注意的是，该指令作用在单个节点时，节点仅在目标平台输出，同时节点自身属性不会进行跨平台语法转换，不过其子节点不受影响。

```html
<!--当srcMode为wx，跨平台输出ali时-->
<!--错误写法-->
<view @ali bindtap="someClick">
    <view wx:if="{{flag}}">text</view>
</view>
<!--正确写法-->
<view @ali onTap="someClick">
    <view wx:if="{{flag}}">text</view>
</view>
```

::: danger
另外在跨端输出 React Native 和 H5 时，不要在基础组件节点上使用 @mode 指令，仅可在自定义组件节点使用 @mode 指令
:::

```html
<!--错误写法-->
<view @ios>测试数据</view>
```

## @\_mode

`type _mode = '_wx' | '_ali' | '_qq' | '_swan' | '_tt' | '_web' | '_qa' ｜ '_ios' | '_android' | '_harmony'`

有时开发者期望使用 @mode 这种方式仅控制节点的展示，保留节点属性的平台转换能力，为此 Mpx 实现了一个隐式属性条件编译能力。

```html
<!--srcMode为 wx，输出 ali 时，bindtap 会被正常转换为 onTap-->
<view @_ali bindtap="someClick">test</view>
```

在对应的平台前加一个\_，例如@\_ali、@\_swan、@\_tt等，使用该隐式规则仅有条件编译能力，节点属性语法转换能力依旧。

在跨端输出 React Native 和 H5 时，可以在节点上使用该属性。

## @env

`string`

跨平台输出场景下，除了 mode 平台场景值，Mpx 框架还提供自定义 env 目标应用，来实现在不同应用下编译产出不同的代码。

关于 env 的详细介绍可以点击[查看](../guide/advance/platform.md#use-env)

跨平台输出使用 env 与 mode 一样支持文件纬度、区块纬度、节点纬度、属性纬度等条件编译，这里我们仅介绍下节点和属性纬度的指令模式使用，env 与 mode 可以组合使用。

env 属性维度条件编译与 mode 的用法大致相同，使用 : 符号与 mode 和其他 env 进行串联，与 mode 组合使用格式形如 attr@mode:env:env|mode:env，为了不与 mode 混淆，当条件编译中仅存在 env 条件时，也需要添加 : 前缀，形如 attr@:env。

```html
<!--open-type 属性仅在百度平台且应用 env 为 didi 时保留-->
<button open-type@swan:didi="getUserInfo">获取用户信息</button>
<!--open-type 属性在应用 env 为 didi 的任意小程序平台保留-->
<button open-type@:didi="getUserInfo">获取用户信息</button>
<!--open-type 属性在微信平台且应用 env 为 didi 或 qingju 时保留-->
<button open-type@wx:didi:qingju="getUserInfo">获取用户信息</button>
```

env 也可在单个节点上进行条件编译：

```html
<!--整个节点在应用 env 为 didi时进行保留-->
<view @:didi>this is a  view component</view>
```

需要注意的时，如果只声明了 env，没有声明 mode，跨平台输出时框架对于节点属性默认会进行转换：

```html
<!--srcMode为wx，跨平台输出ali时，bindtap会被转为onTap-->
<view @:didi bindtap="someClick">this is a  view component</view>
<view bindtap@:didi ="someClick">this is a  view component</view>
```

## mpxTagName

`string`

跨平台输出时，有时开发者不仅需要对节点属性进行条件编译，可能还需对节点标签进行条件编译。

为此，Mpx 框架支持了一个特殊属性 mpxTagName，如果节点存在这个属性，在最终输出时将节点标签修改为该属性的值，配合属性维度条件编译，即可实现对节点标签进行条件编译，例如在百度环境下希望将某个 view 标签替换为 cover-view，我们可以这样写：

```html
<view mpxTagName@swan="cover-view">will be cover-view in swan</view>
```

---

---
url: /api/compile.md
---

# 编译构建 {#compile-build}

对于使用 `@mpxjs/cli@3.x` 脚手架初始化的项目而言，编译构建相关的配置统一收敛至项目根目录下的 `vue.config.js` 进行配置。一个新项目初始化的 `vue.config.js` 如下图，相较于 `@mpxjs/cli@2.x` 版本，在新的初始化项目当中原有的编译构建配置都收敛至 cli 插件当中进行管理和维护，同时还对外暴露相关的接口或者 api 使得开发者能自定义修改 cli 插件当中默认的配置。

```javascript
// vue.config.js
const { defineConfig } = require('@vue/cli-service')
module.exports = defineConfig({
  pluginOptions: {
    mpx: {
      plugin: {
        // mpx webpack plugin options
      },
      unocss: {
        // @mpxjs/unocss-plugin 相关的配置
      }
    }
  }
})
```

对于使用 `@mpxjs/cli@2.x` 脚手架初始化的项目，编译构建配置涉及到 mpx 插件相关的配置主要是在 `config` 目录下 `mpxPlugin.conf.js`，涉及到 webpack 本身的配置主要是在 `build` 目录下。

```javascript
// config/mpxPlugin.conf.js
module.exports = () => {
  return {
    // mpx webpack plugin options
  }
}
```

## 类型定义 {#type-definition}

为了便于对编译配置的数据类型进行准确地描述，我们在这里对一些常用的配置类型进行定义

### Rules

```ts
type Condition = string | ((resourcePath: string) => boolean) | RegExp

interface Rules {
  include?: Condition | Array<Condition>
  exclude?: Condition | Array<Condition>
}
```

## MpxWebpackPlugin

Mpx 编译构建跨平台小程序和 web 的 webpack 主插件，安装示例如下：

::: code-group

```sh [npm]
npm install -D @mpxjs/webpack-plugin
```

```sh [pnpm]
pnpm add -D @mpxjs/webpack-plugin
```

```sh [yarn]
yarn add -D @mpxjs/webpack-plugin
```

:::

使用示例如下：

```javascript
// vue.config.js
const { defineConfig } = require('@vue/cli-service')
module.exports = defineConfig({
  pluginOptions: {
    mpx: {
      plugin: {
        // mpx webpack plugin options
      }
    }
  }
})
```

MpxWebpackPlugin支持传入以下配置：

### mode

`'wx' | 'ali' | 'swan' | 'qq' | 'tt' | 'jd' | 'dd' | 'qa' | 'web' = 'wx'`

mode 为 Mpx 编译的目标平台， 目前支持的有微信小程序(wx)\支付宝小程序(ali)\百度小程序(swan)\头条小程序(tt)\QQ 小程序(qq)\京东小程序(jd)\滴滴小程序(dd)\快应用(qa)\H5 页面(web)。

::: tip
在 @mpxjs/cli@3.x 版本当中，通过在 `npm script` 当中定义 `targets` 来设置目标平台

```javascript
// 项目 package.json
{
  "script": {
    "build:cross": "mpx-cli-service build --targets=wx,ali"
  }
}
```

:::

### srcMode

`'wx' | 'ali' | 'swan' | 'qq' | 'tt' | 'jd' | 'dd' | 'qa' = 'wx'`

默认和 [mode](#mode) 一致。，当 srcMode 和 mode 不一致时，会读取相应的配置对项目进行编译和运行时的转换。

```javascript
// vue.config.js
module.exports = defineConfig({
  pluginOptions: {
    mpx: {
      plugin: {
        srcMode: 'wx' // 根据项目初始化所选平台来设定
      }
    }
  }
})
```

::: warning
暂时只支持微信为源 mode 做跨平台，为其他时，mode 必须和 srcMode 保持一致。
:::

### modeRules

`{ [key: string]: Rules }`

批量指定文件mode，用于条件编译场景下使用某些单小程序平台的库时批量标记这些文件的mode为对应平台，而不再走转换规则。

```js
// vue.config.js
module.exports = defineConfig({
  pluginOptions: {
    mpx: {
      plugin: {
        modeRules: {
          ali: {
            include: [resolve('node_modules/vant-aliapp')]
          }
        }
      }
    }
  }
})
```

### externalClasses

`Array<string>`

定义若干个外部样式类，这些将会覆盖元素原有的样式。

```js
// vue.config.js
module.exports = defineConfig({
  pluginOptions: {
    mpx: {
      plugin: {
        externalClasses: ['custom-class', 'i-class']
      }
    }
  }
})
```

::: warning
抹平支付宝和微信之间的差异，当使用了微信 **externalClasses** 语法时，跨端输出需要在 @mpxjs/webpack-plugin 的配置中添加此配置来辅助框架进行转换。
:::

### resolveMode

`'webpack' | 'native' = 'webpack'`

指定resolveMode，默认webpack，更便于引入npm包中的页面/组件等资源。若想编写时和原生保持一致或兼容已有原生项目，可设为native，此时需要提供[projectRoot](#projectroot)以指定项目根目录，且使用npm资源时需在前面加`~`。

```js
// vue.config.js
module.exports = defineConfig({
  pluginOptions: {
    mpx: {
      plugin: {
        resolveMode: 'webpack'
      }
    }
  }
})
```

### projectRoot

`string`

当resolveMode为native时需通过该字段指定项目根目录。

```js
// vue.config.js
module.exports = defineConfig({
  pluginOptions: {
    mpx: {
      plugin: {
         resolveMode: 'native',
         projectRoot: path.resolve(__dirname, '../src')
      }
    }
  }
})
```

### writeMode

`'full' | 'change' = 'change'`

webpack 的输出默认是全量输出，而小程序开发者工具不关心文件是否真正发生了变化。设置为 change 时，Mpx 在 watch 模式下将内部 diff 一次，只会对内容发生变化的文件进行写入，以提升小程序开发者工具编译性能。

```js
// vue.config.js
module.exports = defineConfig({
  pluginOptions: {
    mpx: {
      plugin: {
         writeMode: 'change'
      }
    }
  }
})
```

### autoScopeRules

[`Rules`](#rules)

是否需要对样式加 scope ，目前只有支付宝小程序平台没有样式隔离，因此该部分内容也只对支付宝小程序平台生效。提供 include 和 exclude 以精确控制对哪些文件进行样式隔离，哪些不隔离，和webpack的rules规则相同。也可以通过在 style 代码块上声明 scoped 进行。

```js
// vue.config.js
module.exports = defineConfig({
  pluginOptions: {
    mpx: {
      plugin: {
         autoScopeRules: {
           include: [resolve('../src')],
           exclude: [resolve('../node_modules/vant-aliapp')] // 比如一些组件库本来就是为支付宝小程序编写的，应该已经考虑过样式隔离，就不需要再添加
         }
      }
    }
  }
})
```

### forceDisableProxyCtor

`boolean = false`

用于控制在跨平台输出时对实例构造函数（`App` | `Page` | `Component` | `Behavior`）进行代理替换以抹平平台差异。当配置 `forceDisableProxyCtor` 为 true 时，会强行取消平台差异抹平逻辑，开发时需针对输出到不同平台进行条件判断。

### transMpxRules

[`Rules`](#rules)

是否转换 wx / my 等全局对象为 Mpx 对象，

```js
// vue.config.js
module.exports = defineConfig({
  pluginOptions: {
    mpx: {
      plugin: {
        transMpxRules: {
          include: () => true,
          exclude: ['@mpxjs']
        }
      }
    }
  }
})
```

### forceProxyEventRules

[`Rules`](#rules)

强制代理规则内配置的事件。

```js
// vue.config.js
module.exports = defineConfig({
  pluginOptions: {
    mpx: {
      plugin: {
        forceProxyEventRules: {
          include: ['src/packages/index.mpx']
        }
      }
    }
  }
})
```

### defs

`object`

给模板、js、json、style中定义一些全局常量。一般用于区分平台/环境。

```js
// vue.config.js
module.exports = defineConfig({
  pluginOptions: {
    mpx: {
      plugin: {
        defs: {
          __env__: 'mini'
        }
      }
    }
  }
})
```

在模板中使用：

```html
<template>
  <view>{{__env__}}</view>
</template>
```

在js中使用：

```js
const env = __env__;
```

在style中使用：

```js
/* @mpx-if (__env__ === 'mini') */
.color {
  background: red;
}
/* @mpx-endif */
```

在json中使用：

```js
<script name='json'>
  module.exports = {
    "component": true,
    "usingComponents": {
      "a": __env__
    }
  }
</script>
```

> 注意：这里定义之后使用的时候是按照全局变量来使用，而非按照`process.env.KEY`这样的形式

### attributes

`Array<string> = ['image:src', 'audio:src', 'video:src', 'cover-image:src', 'import:src', 'include:src']`

`Mpx` 提供了可以给自定义标签设置资源的功能，配置该属性后，即可在目标标签中使用 `:src` 加载相应资源文件

```js
// vue.config.js
module.exports = defineConfig({
  pluginOptions: {
    mpx: {
      plugin: {
        attributes: ['customTag:src']
      }
    }
  }
})
```

```html
<customTag :src="'https://www....../avator.png'"></customTag>
```

:::tip
该属性可通过 `MpxWebpackPlugin` 配置，也可以通过配置 `WxmlLoader`，后者优先级高。
:::

### externals

`Array<string>`

目前仅支持微信小程序 weui 组件库通过 useExtendedLib 扩展库的方式引入，这种方式引入的组件将不会计入代码包大小。配置 externals 选项，Mpx 将不会解析 weui 组件的路径并打包。

```javascript
// vue.config.js
module.exports = defineConfig({
  pluginOptions: {
    mpx: {
      plugin: {
        externals: ['weui']
      }
    }
  }
})
```

```html
<script name="json">
  // app.mpx json部分
  module.exports = {
    "useExtendedLib": {
      "weui": true
    }
  }
</script>
```

```html
<!-- 在 page 中使用 weui 组件 -->
<template>
  <view wx:if="{{__mpx_mode__ === 'wx'}}">
    <mp-icon icon="play" color="black" size="{{25}}" bindtap="showDialog"></mp-icon>
    <mp-dialog title="test" show="{{dialogShow}}" bindbuttontap="tapDialogButton" buttons="{{buttons}}">
      <view>test content</view>
    </mp-dialog>
  </view>
</template>

<script>
  import{ createPage } from '@mpxjs/core'

  createPage({
    data: {
      dialogShow: false,
      showOneButtonDialog: false,
      buttons: [{text: '取消'}, {text: '确定'}],
    },
    methods: {
      tapDialogButton () {
        this.dialogShow = false
        this.showOneButtonDialog = false
      },
      showDialog () {
        this.dialogShow = true
      }
    }
  })
</script>

<script name="json">
  const wxComponents = {
    "mp-icon": "weui-miniprogram/icon/icon",
    "mp-dialog": "weui-miniprogram/dialog/dialog"
  }
  module.exports = {
    "usingComponents": __mpx_mode__ === 'wx'
      ? Object.assign({}, wxComponents)
      : {}
  }
</script>
```

**参考**：weui组件库

### miniNpmPackages

`Array<string>`

微信小程序官方提供了[发布小程序 npm 包的约束](https://developers.weixin.qq.com/miniprogram/dev/devtools/npm.html)。
部分小程序npm包，如[vant组件库](https://vant-contrib.gitee.io/vant-weapp/#/quickstart)官方文档使用说明，引用资源并不会包含miniprogram所指定的目录
如 "@vant/weapp/button/index"，导致 `Mpx` 解析路径失败。
`Mpx`为解决这个问题，提供miniNpmPackage字段供用户配置需要解析的小程序npm包。miniNpmPackage对应的数组值为npm包对应的package.json中的name字段。
`Mpx`解析规则如下:

1. 如package.json中有miniprogram字段，则会默认拼接miniprogram对应的值到资源路径中
2. 如package.json中无miniprogram字段，但配置了miniNpmPackage，则默认会拼接miniprogram\_dist目录

```js
// vue.config.js
module.exports = defineConfig({
  pluginOptions: {
    mpx: {
      plugin: {
        miniNpmPackages: ['@vant/weapp']
      }
    }
  }
})
```

### normalNpmPackages

`Array<string>`

使用小程序原生 npm 包时，由于微信小程序 npm 包要求根目录下必须有构建文件生成目录，（默认为 miniprogram\_dist 目录），此目录可以通过在 package.json 文件中新增一个 miniprogram 字段来指定。

因此大多小程序 npm 包 package.json 中都会存在 miniprogram 字段，Mpx 框架在构建时也会默认读取 miniprogram 拼接到资源路径和输出路径中。

但存在一种场景，例如使用 antd-mini 组件库时，使用纯支付宝场景下的包无需读取 miniprogram 字段进行拼接，但是对应 npm 包又存在 miniprogram 字段，这时需要通过该配置告诉框架不要去读，直接走默认路径。

```js
// vue.config.js
module.exports = defineConfig({
  pluginOptions: {
    mpx: {
      plugin: {
        normalNpmPackages: ['antd-mini']
      }
    }
  }
})
```

### forceUsePageCtor

`Boolean = false`

为了获取更丰富的生命周期来进行更加完善的增强处理，在非支付宝小程序环境下，`Mpx` 默认会使用 `Conponent` 构造器来创建页面。将该值设置为 `true` 时，会强制使用 `Page` 构造器创建页面。

```js
// vue.config.js
module.exports = defineConfig({
  pluginOptions: {
    mpx: {
      plugin: {
        forceUsePageCtor: true
      }
    }
  }
})
```

### transRpxRules

`Array<object> | object`

* `option.mode` 可选值有 none/only/all，分别是不启用/只对注释内容启用/只对非注释内容启用
* `option.designWidth` 设计稿宽度，默认值就是750，可根据需要修改
* `option.include` 同webpack的include规则
* `option.exclude` 同webpack的exclude规则
* `option.comment` rpx注释，建议使用 'use px'/'use rpx'，当 mode 为 all 时默认值为 use px，mode 为 only 时默认值为 'use rpx'

为了处理某些IDE中不支持`rpx`单位的问题，Mpx 提供了一个将 px 转换为 rpx 的功能。支持通过注释控制行级、块级的是否转换，支持局部使用，支持不同依赖分别使用不用的转换规则等灵活的能力。`transRpxRules`可以是一个对象，也可以是多个这种对象组成的数组。

```js
// vue.config.js
const path = require('path')

module.exports = defineConfig({
  pluginOptions: {
    mpx: {
      plugin: {
        transRpxRules: [
          {
            mode: 'only', // 只对注释为'use rpx'的块儿启用转换rpx
            comment: 'use rpx', // mode为'only'时，默认值为'use rpx'
            include: path.resolve('src'),
            exclude: path.resolve('lib'),
            designWidth: 750
          },
          {
            mode: 'all', // 所有样式都启用转换rpx，除了注释为'use px'的样式不转换
            comment: 'use px', // mode为'all'时，默认值为'use px'
            include: path.resolve('node_modules/@didi/mpx-sec-guard')
          }
        ]
      }
    }
  }
})
```

#### 应用场景及相应配置 {#scenarios-and-config}

接下来我们来看下一些应用场景及如何配置。如果是用脚手架生成的项目，在`mpx.plugin.conf.js`里找到`transRpxRules`，应该已经有预设的`transRpxRules`选项，按例修改即可。

三种场景分别是 [普通使用](#scenario-1) ， [只对某些特殊样式转换](#scenario-2) ， [不同路径分别配置规则](#scenario-3)

#### 场景一 {#scenario-1}

设计师给的稿是2倍图，分辨率750px。或者更高倍图。

```js
// vue.config.js
module.exports = defineConfig({
  pluginOptions: {
    mpx: {
      plugin: {
        transRpxRules: [{
          mode: 'all',
          designWidth: 750 // 如果是其他倍，修改此值为设计稿的宽度即可
        }]
      }
    }
  }
})
```

#### 场景二 {#scenario-2}

大部分样式都用px下，某些元素期望用rpx。或者反过来。

```js
// vue.config.js
module.exports = defineConfig({
  pluginOptions: {
    mpx: {
      plugin: {
        transRpxRules: [{
          mode: 'only',
          comment: 'use rpx',
          designWidth: 750 // 设计稿宽度
        }]
      }
    }
  }
})
```

mpx的rpx注释能帮助你仅为部分类或者部分样式启用rpx转换，细节请看下方附录。

#### 场景三 {#scenario-3}

使用了第三方组件，它的设计宽度和主项目不一致，期望能设置不同的转换规则

```js
// vue.config.js
const path = require('path')

module.exports = defineConfig({
  pluginOptions: {
    mpx: {
      plugin: {
        transRpxRules: [
          {
            mode: 'only',
            designWidth: 750,
            comment: 'use rpx',
            include: resolve('src')
          },
          {
            mode: 'all',
            designWidth: 1280, // 对iview单独使用一个不同的designWidth
            include: path.resolve('node_modules/iview-weapp')
          }
        ]
      }
    }
  }
})
```

> 注意事项：转换规则是不可以对一个文件做多次转换的，会出错，所以一旦被一个规则命中后就不会再次命中另一个规则，include 和 exclude 的编写需要注意先后顺序，就比如上面这个配置，如果第一个规则 include 的是 '/' 即整个项目，iview-weapp 里的样式就无法命中第二条规则了。

#### transRpxRules附录 {#transrpxrules-appendix}

* **designWidth**

设计稿宽度，单位为`px`。默认值为`750px`。

`mpx`会基于小程序标准的屏幕宽度`baseWidth 750rpx`，与`option.designWidth`计算出一个转换比例`transRatio`。

转换比例的计算方式为`transRatio = (baseWidth / designWidth)`，精度为小数点后2位四舍五入。

所有生效的`rpx注释样式`中的px会乘上`transRatio`得出最终的 rpx 值。

例如：

```css
/* 转换前：designWidth = 1280 */
.btn {
  width: 200px;
  height: 100px;
}

/* 转换后: transRatio = 0.59 */
.btn {
  width: 118rpx;
  height: 59rpx;
}
```

* **comment: rpx 注释样式**

根据`rpx注释`的位置，`mpx`会将`一段css规则`或者`一条css声明`视为`rpx注释样式`。

开发者可以声明一段 rpx 注释样式，提示编译器是否转换这段 css 中的 px。

例如：

```html
<style lang="css">
  /* use rpx */
  .not-translate-a {
    font-size: 100px;
    padding: 10px;
  }
  .not-translate-b {
    /* use rpx */
    font-size: 100px;
    padding: 10px;
  }
  .translate-a {
    font-size: 100px;
    padding: 10px;
  }
  .translate-b {
    font-size: 100px;
    padding: 10px;
  }
</style>
```

> 第一个注释位于一个`选择器`前，是一个`css规则注释`，整个规则都会被视为`rpx注释样式`

> 第二个注释位于一个`css声明`前，是一个`css声明注释`，只有`font-size: 100px`会被视为`rpx注释样式`

> `transRpx = only`模式下，只有两部分`rpx注释样式`会转rpx。

### postcssInlineConfig

`{options? : PostcssOptions, plugins? : PostcssPlugin[], mpxPrePlugins? : PostcssPlugin[], ignoreConfigFile : Boolean}`

使用类似于 postcss.config.js 的语法书写 postcss 的配置文件。用于定义 Mpx 对于组件/页面样式进行 postcss 处理时的配置， ignoreConfigFile 传递为 true 时会忽略项目中的 postcss 配置文件 。

```js
// vue.config.js
module.exports = defineConfig({
  pluginOptions: {
    mpx: {
      plugin: {
        postcssInlineConfig: {
          plugins: [
            // require('postcss-import'),
            // require('postcss-preset-env'),
            // require('cssnano'),
            // require('autoprefixer')
          ]
        }
      }
    }
  }
})
```

**注意**：默认添加的 postcss 插件均会在`mpx的内置插件`（例如如rpx插件等）之后处理。如需使配置的插件优先于内置插件，可以在 `postcssInlineConfig` 中添加 `mpxPrePlugins` 配置：

```js
// vue.config.js
module.exports = defineConfig({
  pluginOptions: {
    mpx: {
      plugin: {
        postcssInlineConfig: {
          plugins: [
            require('postcss-import'),
            require('postcss-preset-env'),
          ],
          mpxPrePlugins: [
            require('cssnano'),
            require('autoprefixer')
          ]
          // 以下写法同理
          // mpxPrePlugins: {
          //   'cssnano': {},
          //   'autoprefixer': {}
          // }
        }
      }
    }
  }
})
```

`postcss.config.js` 中配置同理：

```js
// postcss.config.js
module.exports = {
  plugins: [
    require('postcss-import'),
    require('postcss-preset-env'),
  ],
  mpxPrePlugins: [
    require('cssnano'),
    require('autoprefixer')
  ]
}

```

在上面这个例子当中，postcss 插件处理的最终顺序为：`cssnano` -> `autoprefixer` -> `mpx内置插件` -> `postcss-import` -> `postcss-preset-env`

::: warning
注意：在 `mpxPrePlugins` 中配置的 postcss 插件如果不通过 mpx 进行处理，那么将不会生效。
:::

### decodeHTMLText

`boolean = false`

设置为 true 时在模板编译时对模板中的 text 内容进行 decode

### nativeConfig

`{cssLangs: string[]}`

为原生多文件写法添加css预处理语言支持，用于优先搜索预编译器后缀的文件，按 cssLangs 中的声明顺序查找。默认按照 css , less , stylus ,  scss , sass 的顺序

```js
// vue.config.js
module.exports = defineConfig({
  pluginOptions: {
    mpx: {
      plugin: {
        nativeConfig: {
          cssLangs: ['css', 'less', 'stylus', 'scss', 'sass']
        }
      }
    }
  }
})
```

### webConfig {#web-config}

**`mode === 'web'`** 输出时使用的编译期配置对象，在 `plugin.webConfig`（如 `vue.config.js` / `mpx.config.js` 的 `pluginOptions.mpx.plugin` 下）中传入，由 `MpxWebpackPlugin` 读取并参与 Web 侧 rpx 转换、SSR、页面切换动画与内建组件等编译逻辑。

#### webConfig.transRpxFn {#webconfig-transrpxfn}

`(match: string, $1: number) => string`

自定义 Web 输出时对 **rpx** 单位的转换规则，常见写法为转为 **vw** 或 **rem**。

#### webConfig.useSSR {#webconfig-usessr}

`boolean = false`

在 **SSR** 模式下若使用 **异步分包**，需将 `useSSR` 设为 **`true`**；其它场景保持默认即可。

#### webConfig.disablePageTransition {#webconfig-disablepagetransition}

`boolean = true`

为 `true` 时 **禁用** 页面切换动画；设为 **`false`** 可 **开启** 切换过渡效果。

#### webConfig.customBuiltInComponents {#webconfig-custombuiltincomponents}

`Record<string, string> | undefined`

在 **Web 输出**（**`mode === 'web'`**）、且 **非 app 入口**（存在参与编译的用户模版）时生效，用于 **替换或扩展** 框架对某一微信基础标签在 Web 侧的内建实现。

**key**

* 须为 **微信小程序侧基础标签名**（如 `view`、`text`、`scroll-view`），与模版中写的标签一致。
* **不要** 使用 **`mpx-*`** 作为 key。

**value**（文档约定，插件 **不在编译期校验** 格式）

* 建议使用 **绝对路径**（POSIX 以 **`/`** 开头，或 Windows 下 **`path.isAbsolute` 为真**），或 **以 npm 包名开头的模块路径**（如 **`@scope/pkg/...`**、**`my-pkg/...`**，首段须为合法包名，避免写成易被误认为工程相对路径的 **`src/...`**）。
* **不要** 使用 **`./`、`../`** 及 **`~`** 前缀；不符合约定时一般由 **webpack 解析** 等环节报错。

**注意事项**

* 某标签一旦在配置中声明，Web 侧将 **优先使用你提供的模块** 作为该基础标签的实现；**属性、事件、子节点等与微信文档的差异** 需在你的组件内 **自行对齐**。
* **app 入口** 仅内置 **`mpx-keep-alive`**，**不使用** 本配置项。
* **小程序等其它输出形态** 不读取 `webConfig.customBuiltInComponents`；仅在 **Web / RN** 输出下配置有效。RN 侧请使用 **`rnConfig.customBuiltInComponents`**，约定与本节相同，见 [rnConfig.customBuiltInComponents](#rnconfig-custombuiltincomponents)。

```js
// mpx.config.js
module.exports = defineConfig({
  pluginOptions: {
    mpx: {
      plugin: {
        webConfig: {
          transRpxFn: function (match, $1) {
            if ($1 === '0') return $1
            return `${$1 * +(100 / 750).toFixed(8)}vw`
          },
          // 当 SSR 模式下使用异步分包时
          useSSR: true,
          // 开启页面切换动画
          disablePageTransition: false,
          customBuiltInComponents: {
            view: require('path').resolve(__dirname, 'src/builtin/MpxView.vue')
          }
        }
      }
    }
  }
})
```

### rnConfig {#rn-config}

**`mode` 为输出 React Native（如 `react`）时**使用的编译期配置对象，由 `MpxWebpackPlugin` 传入 loader 上下文，并会挂到运行时的 `mpx.config.rnConfig` 上供 RN 逻辑读取（与小程序 / Web 无关）。

#### rnConfig.projectName

`string | undefined`

若配置，则在入口脚本中调用 `AppRegistry.registerComponent(projectName, () => app)`，用于注册 RN 根组件名称。

#### rnConfig.supportSubpackage

`boolean = true`

为 `true` 时，RN 输出下页面与组件可走异步分包与 `import()` 等逻辑；为 `false` 时关闭相关能力。插件初始化时若未传入则默认为 `true`。

#### rnConfig.asyncChunk

`{ timeout?: number, fallback?: string, loading?: string } | undefined`

异步分包相关：

* **timeout**：传给内部 `LoadAsyncChunkModule` 的超时时间（毫秒级用途，见 `@mpxjs/webpack-plugin` 实现）。
* **fallback** / **loading**：异步页面/组件的占位与 loading 组件资源路径（经 `addQuery(..., { isComponent: true })` 参与打包），在 `react/script-helper.js` 中生成异步包装代码时使用。

#### rnConfig.customBuiltInComponents {#rnconfig-custombuiltincomponents}

`Record<string, string> | undefined`

在 **RN 输出**（**`mode`** 为 **`ios` / `android` / `harmony`** 等）时生效。与 [webConfig.customBuiltInComponents](#webconfig-custombuiltincomponents) 的 **key、value 约定及注意事项** 相同，仅在 **`rnConfig`** 中配置，便于与 Web 使用不同的模块路径。

**注意事项**

* 页面/组件 **主模版** 以及 **子模版**（如通过 import 引入的模版）均会应用本配置。
* **key / value** 及路径书写要求与 Web 一节一致，此处不再重复；详见 [webConfig.customBuiltInComponents](#webconfig-custombuiltincomponents)。

#### rnConfig.loadChunkAsync（运行时）

编译插件不会在选项里“实现”该函数；异步分包下载 chunk 时，运行时代码会调用 **`mpx.config.rnConfig.loadChunkAsync`**（若存在）。需在 RN 应用启动后自行挂载，例如与原生下载、热更新方案对接。与 **asyncChunk** 编译配置配合使用。

```js
// vue.config.js / mpx.config.js 片段
const path = require('path')

module.exports = defineConfig({
  pluginOptions: {
    mpx: {
      plugin: {
        mode: 'react',
        rnConfig: {
          projectName: 'MyMpxApp',
          supportSubpackage: true,
          asyncChunk: {
            timeout: 10000,
            fallback: path.resolve(__dirname, 'src/rn/PageFallback.mpx'),
            loading: path.resolve(__dirname, 'src/rn/PageLoading.mpx')
          },
          customBuiltInComponents: {
            view: '@your-org/mpx-rn-builtin/MpxView.mpx',
            text: path.resolve(__dirname, 'src/builtin/MpxText.mpx')
          }
        }
      }
    }
  }
})
```

### i18n

```js
// vue.config.js
module.exports = defineConfig({
  pluginOptions: {
    mpx: {
      plugin: {
        i18n: {
          locale: 'en-US',
          messages: {
            'en-US': {
              message: {
                hello: '{msg} world'
              }
            },
            'zh-CN': {
              message: {
                hello: '{msg} 世界'
              }
            }
          },
          // messagesPath: path.resolve(__dirname, '../src/i18n.js')
        }
      }
    }
  }
})
```

Mpx 支持国际化，底层实现依赖类`wxs`能力，通过指定语言标识和语言包，可实现多语言之间的动态切换。可配置项包括locale、messages、messagesPath。

#### i18n.locale

`string`

通过配置 locale 属性，可指定语言标识，默认值为 'zh-CN'

#### i18n.messages

`object`

通过配置 messages 属性，可以指定项目语言包，Mpx 会依据语言包对象定义进行转换，示例如下：

```js
messages: {
  'en-US': {
    message: {
      'title': 'DiDi Chuxing',
      'subTitle': 'Make travel better'
    }
  },
  'zh-CN': {
    message: {
      'title': '滴滴出行',
      'subTitle': '让出行更美好'
    }
  }
}
```

#### i18n.messagesPath

`string`

为便于开发，Mpx 还支持配置语言包资源路径 messagesPath 来代替 messages 属性，Mpx 会从该路径下的 js 文件导出语言包对象。如果同时配置 messages 和 messagesPath 属性，Mpx 会优先设定 messages 为 i18n 语言包资源。

详细介绍及使用见[工具-国际化i18n](../guide/tool/i18n.md)一节。

### auditResource

`'component' | boolean = false`

检查资源输出情况，如果置为true，则会提示有哪些资源被同时输出到了多个分包，可以检查是否应该放进主包以消减体积，设置为 `'component'` 的话，则只检查组件资源是否被输出到多个分包。

```js
// vue.config.js
module.exports = defineConfig({
  pluginOptions: {
    mpx: {
      plugin: {
        auditResource: true
      }
    }
  }
})
```

### subpackageModulesRules

`object`

是否将多分包共用的模块分别输出到各自分包中，匹配规则为include匹配到且未被exclude匹配到的资源

依据微信小程序的分包策略，多个分包使用到的 js 模块会打入主包当中，但在大型分包较多的项目中，该策略极易将大量的模块打入主包，从而使主包体积大小超出2M限制，该配置项提供给开发者自主抉择，可将部分模块冗余输出至多个分包，从而控制主包体积不超限

```js
// vue.config.js
module.exports = defineConfig({
  pluginOptions: {
    mpx: {
      plugin: {
        subpackageModulesRules: {
          include: ['@someNpm/name/src/api/*.js'],
          exclude: ['@someNpm/name/src/api/module.js']
        }
      }
    }
  }
})
```

> tips: 该功能是将模块分别放入多个分包，模块状态不可复用，使用前要依据模块功能做好评估，例如全局store就不适用该功能

### generateBuildMap

`boolean = false`

是否生成构建结果与源码之间的映射文件。用于单元测试等场景。

```js
// vue.config.js
module.exports = defineConfig({
  pluginOptions: {
    mpx: {
      plugin: {
        generateBuildMap: true
      }
    }
  }
})
```

**参考**：[单元测试](../guide/tool/unit-test.md)

### autoVirtualHostRules

[`Rules`](#rules)
批量配置是否虚拟化组件节点，对应微信中[`VirtualHost`](https://developers.weixin.qq.com/miniprogram/dev/framework/custom-component/wxml-wxss.html) 。默认不开启，开启后也将抹平支付宝小程序中的表现差异。提供 include 和 exclude 以精确控制对哪些文件开启VirtualHost，哪些不开启。和webpack的rules规则相同。

默认情况下，自定义组件本身的那个节点是一个“普通”的节点，使用时可以在这个节点上设置 `class` 、`style` 、动画、 flex 布局等，就如同普通的 view 组件节点一样。但有些时候，自定义组件并不希望这个节点本身可以设置样式、响应 flex 布局等，而是希望自定义组件内部的第一层节点能够响应 flex 布局或者样式由自定义组件本身完全决定。这种情况下，可以将这个自定义组件设置为“虚拟的”。

```js
// vue.config.js
module.exports = defineConfig({
  pluginOptions: {
    mpx: {
      plugin: {
        autoVirtualHostRules: {
          include: [resolve('../src')],
          exclude: [resolve('../components/other')]
        }
      }
    }
  }
})
```

**注意：** 建议使用`autoVirtualHostRules`配置项，不要使用微信组件内部的 options virtualHost 配置，因为组件内部的 options virtualHost 在跨平台输出时无法进行兼容抹平处理。

### partialCompileRules

`Rules | { pages?: Rules, page?: Rules, components?: Rules, component?: Rules }`

在大型的小程序开发当中，全量打包页面和组件耗时非常长，往往在`开发过程`中仅仅只需用到几个页面或组件而已，该配置项支持打包指定的小程序页面和组件。

**注意：** @mpxjs/webpack-plugin@2.9.41版本之前该配置为 partialCompile。

历史写法 `partialCompileRules: { include, exclude }` 保持兼容，仅作用于页面；被保留页面引用的组件会继续全部编译。如需同时过滤组件，可使用 `pages` / `components` 分类型配置。`page` / `component` 为对应单数别名。

```js
// vue.config.js
module.exports = defineConfig({
  pluginOptions: {
    mpx: {
      plugin: {
        // include 可以是正则、字符串、函数、数组
        partialCompileRules: {
          include: [
            '/project/pages',
            /pages\/internal/,
            (pageResourcePath) => pageResourcePath.includes('pages')
          ] // 满足任意条件的页面都会被打包，旧写法只过滤页面
        }
      }
    }
  }
})
```

```js
// vue.config.js
module.exports = defineConfig({
  pluginOptions: {
    mpx: {
      plugin: {
        partialCompileRules: {
          pages: {
            include: [
              '/project/pages',
              /pages\/internal/,
              (pageResourcePath) => pageResourcePath.includes('pages')
            ] // 满足任意条件的页面都会被打包
          },
          components: {
            include: [
              '/project/components/base',
              /components\/debug/,
              (componentResourcePath) => componentResourcePath.includes('components')
            ] // 满足任意条件的组件都会被打包
          }
        }
      }
    }
  }
})
```

:::warning
该特性只能用于**开发环境**。配置页面过滤规则后，未命中的页面会被替换为默认页面；配置组件过滤规则后，未命中的组件会被替换为默认组件，其 `usingComponents` 声明仍会保留。
:::

### optimizeRenderRules

[`Rules`](#rules)

render 函数中可能会存在一些重复变量，该配置可消除 render 函数中的重复变量，进而减少包体积。不配置该参数，则不会消除重复变量。

同时框架 render 函数优化提供了两个等级，使用 level 字段来进行控制，默认为 level = 1

* level = 1时，框架生成 render 函数中完成保留 template 中的计算逻辑，setData 传输量保持了最优。
* level = 2时，框架生成 render 函数中仅保留所有 template 中使用到的响应性变量，无任何计算逻辑保留，render 函数体积达最小状态，但 setData 传输量相对于 level=1 会有所增加。

```js
// vue.config.js
module.exports = defineConfig({
  pluginOptions: {
    mpx: {
      plugin: {
        optimizeRenderRules: {
          include: [
            resolve('src')
          ],
          level: 1
        }
      }
    }
  }
})
```

### asyncSubpackageRules

```ts
type Condition = string | Function | RegExp

interface AsyncSubpackageRules {
  include: Condition | Array<Condition>
  exclude?: Condition | Array<Condition>
  root: string
  placeholder: string | { name: string, resource?: string}
}
```

* include: 同 webpack include 规则
* exclude: 同 webpack exclude 规则
* root: 匹配规则的组件或js模块的输出分包名
* placeholder: 匹配规则的组件所配置的componentPlaceholder，可支持配置原生组件和自定义组件，原生组件可直接以string类型配置，自定义组件需要配置对象，name 为该自定义组件名, resource 为自定义组件的路径，路径可为绝对路径和相对于项目目录的相对路径

异步分包场景下批量设置组件或 js 模块的异步分包，提升资源异步分包输出的灵活性。

```js
// vue.config.js
module.exports = defineConfig({
  pluginOptions: {
    mpx: {
      plugin: {
        // include 可以是正则、字符串、函数、数组
        asyncSubpackageRules: [
          {
            include: '/project/pages', // 文件路径包含 '/project/pages' 的组件或者 require.async 异步引用的js 模块都会被打包至sub1分包
            root: 'sub1',
            placeholder: 'view'
          }
        ]
      }
    }
  }
})
```

:::warning

* 该配置匹配的组件，若使用方在引用路径已设置?root或componentPlaceholder，则以引用路径中的?root或componentPlaceholder为最高优先级
* 若placeholder配置使用自定义组件，注意一定要配置 placeholder 中的 resource 字段
* 本功能只会对使用require.async异步引用的js模块生效，若引用路径中已配置?root，则以路径中?root优先
  :::

### transSubpackageRules

`Array`

仅在输出 RN (ios/android/harmony) 时生效。

用于配置分包资源转移规则，可将指定分包中的页面或组件资源转移到其他分包或主包中。

* **from**: `Array<string>` 源分包名称列表
* **to**: `string` 目标分包名称。当为 `''` (空字符串) 时，表示输出到主包

#### 示例 {#example}

```js
// mpx.config.js
module.exports = {
  pluginOptions: {
    mpx: {
      transSubpackageRules: [
        {
          from: ['comp-pages'],
          to: 'common'
        },
        {
          from: ['sub1'],
          to: ''
        }
      ]
    }
  }
}
```

### retryRequireAsync

`boolean = false`

开启时在处理`require.async`时会添加单次重试逻辑

```js
// vue.config.js
module.exports = defineConfig({
  pluginOptions: {
    mpx: {
      plugin: {
        retryRequireAsync: true
      }
    }
  }
})
```

### disableRequireAsync

`boolean = false`

Mpx 框架在输出 微信小程序、支付宝小程序、字节小程序、Web、RN 平台时，默认支持分包异步化能力，但若在某些场景下需要关闭该能力，可配置该项。

```js
// vue.config.js
module.exports = defineConfig({
  pluginOptions: {
    mpx: {
      plugin: {
        disableRequireAsync: true
      }
    }
  }
})
```

### optimizeSize

`boolean = false`

开启后可优化编译配置减少构建产物体积

```js
// vue.config.js
module.exports = defineConfig({
  pluginOptions: {
    mpx: {
      plugin: {
        optimizeSize: true
      }
    }
  }
})
```

## MpxWebpackPlugin static methods

`MpxWebpackPlugin` 通过静态方法暴露了以下五个内置 loader，详情如下：

### MpxWebpackPlugin.loader

`MpxWebpackPlugin` 所提供的最主要 loader，用于处理 `.mpx` 文件，根据不同的[目标平台](#mode)将 `.mpx` 文件输出为不同的结果。

> 在微信环境下 `todo.mpx` 被loader处理后的文件为：`todo.wxml`、`todo.wxss`、`todo.js`、`todo.json`

```js
module.exports = {
  module: {
    rules: [
      {
        test: /\.mpx$/,
        use: MpxWebpackPlugin.loader()
      }
    ]
  }
};
```

### MpxWebpackPlugin.pluginLoader

:::warning
该 loader 仅在开发**小程序插件**时使用，可在使用 Mpx 脚手架进行项目初始化时选择进行组件开发来生成对应的配置文件。
:::

`MpxWebpackPlugin.pluginLoader` 用于根据开发者编写的`plugin.json`文件内容，将特定的小程序组件、页面以及 js 文件进行构建，最终以小程序插件的形式输出。

```js
// vue.config.js
const { defineConfig } = require('@vue/cli-service')
const MpxWebpackPlugin = require('@mpxjs/webpack-plugin')
module.exports = defineConfig({
  configureWebpack() {
    return {
      module: {
        rules: [
          {
            resource: path.resolve('src/plugin/plugin.json'), // 小程序插件的plugin.json的绝对路径
            use: MpxWebpackPlugin.pluginLoader()
          }
        ]
      }
    }
  }
})
```

更多细节请查阅 [小程序插件开发](https://developers.weixin.qq.com/miniprogram/dev/framework/plugin/development.html)

### MpxWebpackPlugin.wxsPreLoader

加载并解析 `wxs` 脚本文件，并针对不同平台，做了差异化处理；同时可支持处理内联`wxs`。

```js
// vue.config.js
const { defineConfig } = require('@vue/cli-service')
const MpxWebpackPlugin = require('@mpxjs/webpack-plugin')
module.exports = defineConfig({
  configureWebpack() {
    return {
      module: {
        rules: [
          {
            test: /\.(wxs|qs|sjs|filter\.js)$/,
            loader: MpxWebpackPlugin.wxsPreLoader(),
            enforce: 'pre'
          }
        ]
      }
    }
  }
})
```

### MpxWebpackPlugin.fileLoader

提供图像资源的处理，生成对应图像文件，输出到输出目录并返回 public URL。如果是分包资源，则会输出到相应的分包资源文件目录中。

```js
// vue.config.js
const { defineConfig } = require('@vue/cli-service')
const MpxWebpackPlugin = require('@mpxjs/webpack-plugin')
module.exports = defineConfig({
  configureWebpack() {
    return {
      module: {
        rules: [
          {
            test: /\.(png|jpe?g|gif|svg)$/,
            loader: MpxWebpackPlugin.fileLoader({
              name: 'img/[name][hash].[ext]'
            })
          }
        ]
      }
    }
  }
})
```

**选项**：

* `name` : 自定义输出文件名模板

### MpxWebpackPlugin.urlLoader

微信小程序对于图像资源存在一些限制，`MpxWebpackPlugin.urlLoader` 针对这些差异做了相关处理，开发者可以使用web应用开发的方式进行图像资源的引入，`MpxWebpackPlugin.urlLoader` 可根据图像资源的不同引入方式，支持 CDN 或者 Base64 的方式进行处理。更多细节请查阅[图像资源处理](../guide/advance/image-process.md)。

```js
// vue.config.js
const { defineConfig } = require('@vue/cli-service')
const MpxWebpackPlugin = require('@mpxjs/webpack-plugin')
module.exports = defineConfig({
  configureWebpack() {
    return {
      module: {
        rules: [
          {
            test: /\.(png|jpe?g|gif|svg)$/,
            loader: MpxWebpackPlugin.urlLoader({
              name: 'img/[name][hash].[ext]',
              limit: 2048,
            })
          }
        ]
      }
    }
  }
})
```

**选项**:

* `name` :  自定义输出文件名模板
* `mimetype` : 指定文件的 MIME 类型
* `limit` : 对内联文件作为数据 URL 的字节数限制
* `publicPath` : 自定义 public 目录
* `fallback` : 文件字节数大于限制时，为文件指定加载程序

### MpxWebpackPlugin.getPageEntry

在 webpack config entry 入口文件配置中，你可以使用该方法获取独立构建页面路径，构建产物为该页面的独立原生代码，
你可以提供该页面给其他小程序使用。

```js
// vue.config.js
const { defineConfig } = require('@vue/cli-service')
const MpxWebpackPlugin = require('@mpxjs/webpack-plugin')
module.exports = defineConfig({
  chainWebpack(config) {
    config.entry('index').add(MpxWebpackPlugin.getPageEntry('./index.mpx'))
  }
})
```

### MpxWebpackPlugin.getComponentEntry

在 webpack config entry 入口文件配置中，你可以使用该方法获取独立构建组件路径，构建产物为该组件的独立原生代码，
你可以提供该组件给其他小程序使用。

```js
// vue.config.js
const { defineConfig } = require('@vue/cli-service')
const MpxWebpackPlugin = require('@mpxjs/webpack-plugin')
module.exports = defineConfig({
  chainWebpack(config) {
    config.entry('index').add(MpxWebpackPlugin.getComponentEntry('./components/list.mpx'))
  }
})
```

### MpxWebpackPlugin.getNativeEntry

在 webpack config entry 入口文件配置中，你可以使用该方法获取原生小程序入口文件路径。如果你不想将原生的小程序入口文件整合为 `app.mpx` 文件，则可以使用该方法直接使用原有的小程序入口文件进行编译。见[#1330]([1330]\(https://github.com/didi/mpx/issues/1330\))。

```js
// vue.config.js
const { defineConfig } = require('@vue/cli-service')
const MpxWebpackPlugin = require('@mpxjs/webpack-plugin')
module.exports = defineConfig({
  chainWebpack(config) {
    // 将 app 入口由默认的 app.mpx 更改为 app.js
    config.entry('app').clear().add(MpxWebpackPlugin.getNativeEntry('./src/app.js'))
  }
})
```

## MpxUnocssPlugin

Mpx 编译 unocss 原子类的 webpack 主插件

如果在使用 `@mpxjs/cli@3.x` 创建项目时选择了 unocss，会自动安装 MpxUnocssPlugin ，直接在 mpx.unocss 配置项中传入相关配置即可

```js
// vue.config.js
const { defineConfig } = require('@vue/cli-service')
module.exports = defineConfig({
  pluginOptions: {
    mpx: {
      unocss: {
        // @mpxjs/unocss-plugin 相关的配置
      }
    }
  }
})
```

如果创建项目时未选 unocss，需手动安装，安装示例如下：

```bash
npm install -D @mpxjs/unocss-plugin
pnpm install -D @mpxjs/unocss-plugin
yarn add -D @mpxjs/unocss-plugin
```

使用示例如下：

```js
  // vue.config.js
  const MpxUnocssPlugin = require('@mpxjs/unocss-plugin')
  const { defineConfig } = require('@vue/cli-service')

  module.exports = defineConfig({
    configureWebpack: {
      plugins: [
        new MpxUnocssPlugin({
          // @mpxjs/unocss-plugin 相关的配置
        })
      ]
    },
  })
```

插件支持配置如下：

### unoFile

`string = 'styles/uno'`

生成主包或分包通用样式存储的相对路径

```js
// vue.config.js
const { defineConfig } = require('@vue/cli-service')
module.exports = defineConfig({
  pluginOptions: {
    mpx: {
      unocss: {
        unoFile: 'styles/uno'
      }
    }
  }
})
```

则会把通用样式存储到下面目录

```js
  // 主包
  dist/wx/styles/uno.wxss
  // 分包
  dist/wx/package/styles/uno.wxss
```

### minCount

`number = 2`

使用到某个原子类的最小分包个数，比如设置为2的话一个原子类只有超过2个分包使用才会输出到主包

> 主要是用来控制主包占用的，数值越大分包的原子类就有更大可能性不占用主包

```js
// vue.config.js
const { defineConfig } = require('@vue/cli-service')
module.exports = defineConfig({
  pluginOptions: {
    mpx: {
      unocss: {
        minCount: 2
      }
    }
  }
})
```

```html
  <!-- minCount=2 -->
  <!-- a分包 -->
  <view class="bg-black color-white"></view>
  <!-- b分包 -->
  <view class="bg-black"></view>
```

unocss将把生成的`bg-black`样式打包到主包

### styleIsolation

`string = 'isolated'`

需要和微信小程序的styleIsolation配合使用，比如小程序使用样式隔离的话，这里需要对应配置为isolated，这样的话每个组件会独立引用对应的原子类文件，配置为'apply-shared'的话只有父级页面和app会建立引用，然后通过配合微信的apply-shared的方式获取父级上定义的原子类

```js
// vue.config.js
const { defineConfig } = require('@vue/cli-service')
module.exports = defineConfig({
  pluginOptions: {
    mpx: {
      unocss: {
        styleIsolation: 'isolated'
      }
    }
  }
})
```

### scan

```ts
  interface Scan {
    include?: string[]
    exclude?: string[]
  }
```

配置需要扫描的文件目录

```js
// vue.config.js
const { defineConfig } = require('@vue/cli-service')
module.exports = defineConfig({
  pluginOptions: {
    mpx: {
      unocss: {
        scan: {
          include: ['src/**/*']
        }
      }
    }
  }
})
```

### escapeMap

`object`

针对原子类中出现的`[` `(` `,`等特殊字符，在web中会通过转义字符`\`进行转义，由于小程序环境下不支持css选择器中出现`\`转义字符，我们内置支持了一套不带`\`的转义规则对这些特殊字符进行转义，同时替换模版和css文件中的类名，内建的默认转义规则，可自定义转译规则

```js
// vue.config.js
const { defineConfig } = require('@vue/cli-service')
module.exports = defineConfig({
  pluginOptions: {
    mpx: {
      unocss: {
        escapeMap: {
          ':': '_d_',
        }
      }
    }
  }
})
```

```css
  <view class="dark:text-green-400"/>
```

将会转化为

```css
  .dark .dark_d_text-green-400{--un-text-opacity:1;color:rgba(74,222,128,var(--un-text-opacity));}
```

### root

`string = process.cwd()`

文件根目录

```js
// vue.config.js
const { defineConfig } = require('@vue/cli-service')
module.exports = defineConfig({
  pluginOptions: {
    mpx: {
      unocss: {
        root: process.cwd()
      }
    }
  }
})
```

### transformCSS

`boolean = true`

转化css指令为常规css

```js
// vue.config.js
const { defineConfig } = require('@vue/cli-service')
module.exports = defineConfig({
  pluginOptions: {
    mpx: {
      unocss: {
        transformCSS: true
      }
    }
  }
})
```

```css
  .custom-div {
    @apply text-center my-0 font-medium;
  }
```

将会转化为

```css
  .custom-div {
    margin-top: 0;
    margin-bottom: 0;
    text-align: center;
    font-weight: 500;
  }
```

### transformGroups

`boolean = true`

转化Variant group

```js
// vue.config.js
const { defineConfig } = require('@vue/cli-service')
module.exports = defineConfig({
  pluginOptions: {
    mpx: {
      unocss: {
        transformGroups: true
      }
    }
  }
})
```

```html
  <view class="lg:(p-2 m-2 text-red-600)"></view>
```

将会转化为

```html
  <view class="lg:p-2 lg:m-2 lg:text-red-600"></view>
```

### config

`UserConfig | string`

config可以传配置对象也可以传一个配置文件路径

```js
// vue.config.js
const { defineConfig } = require('@vue/cli-service')
module.exports = defineConfig({
  pluginOptions: {
    mpx: {
      unocss: {
        config: {
          rules: [
            ['m-1', { margin: '10rpx' }],
          ]
        }
      }
    }
  }
})
```

### configFiles

`LoadConfigSource[]`

```ts
  interface LoadConfigSource<T = any> {
      files: Arrayable<string>;
      /**
       * @default ['mts', 'cts', 'ts', 'mjs', 'cjs', 'js', 'json', '']
      */
      extensions?: string[];
      /**
       * Loader for loading config,
      *
      * @default 'auto'
      */
      parser?: BuiltinParsers | CustomParser<T> | 'auto';
      /**
       * Rewrite the config object,
      * return nullish value to bypassing loading the file
      */
      rewrite?: <F = any>(obj: F, filepath: string) => Promise<T | undefined> | T | undefined;
      /**
       * Transform the source code before loading,
      * return nullish value to skip transformation
      */
      transform?: (code: string, filepath: string) => Promise<string | undefined> | string | undefined;
      /**
       * Skip this source if error occurred on loading
      *
      * @default false
      */
      skipOnError?: boolean;
  }
```

configFiles的话是传递额外的配置文件数组，比如不想用uno.config作为配置文件的话可以在这里面配

```js
// vue.config.js
const { defineConfig } = require('@vue/cli-service')
module.exports = defineConfig({
  pluginOptions: {
    mpx: {
      unocss: {
        configFiles: [
          {
            files: [
              'uno2.config.js'
            ]
          }
        ]
      }
    }
  }
})
```

### commentConfig

我们还支持了commentConfig进行组件局部配置，目前支持safelist和styleIsolation，safelist可以用空格分隔写多个

```html
  <template>
    <!-- mpx_config_styleIsolation: 'isolated' -->
    <!-- mpx_config_safelist: 'text-red-500 bg-black' -->
    <view>mpx-unocss</view>
  </template>
```

## MpxUnocssBase

Mpx 内置的 unocss preset，继承自 `@unocss/preset-wind3`，并额外提供小程序原子类的预设样式，安装示例如下：

```bash
npm install -D @mpxjs/unocss-base
pnpm install -D @mpxjs/unocss-base
yarn add -D @mpxjs/unocss-base
```

使用示例如下：

```js
  // uno.config.mjs
  import { defineConfig } from 'unocss'
  import presetMpx from '@mpxjs/unocss-base'

  export default defineConfig({
    presets: [
      presetMpx({
        // ...
      })
    ],
    // unocss的config，具体配置参考https://unocss.dev/config/
  })
```

支持的配置项如下：

### baseFontSize

`number = 37.5`

同比换算1rem = 37.5rpx适配小程序

```js
  // uno.config.js
  import { defineConfig } from 'unocss'
  import presetMpx from '@mpxjs/unocss-base'

  export default defineConfig({
    presets: [
      presetMpx({
        baseFontSize: 37.5
      })
    ],
  })
```

### preflight

`boolean = true`

是否生成预设样式

```js
  // uno.config.js
  import { defineConfig } from 'unocss'
  import presetMpx from '@mpxjs/unocss-base'

  export default defineConfig({
    presets: [
      presetMpx({
        preflight: true
      })
    ],
  })
```

将添加预设样式在主包

```css
page{--un-rotate:0;--un-rotate-x:0;--un-rotate-y:0;--un-rotate-z:0;--un-scale-x:1;--un-scale-y:1;--un-scale-z:1;--un-skew-x:0;--un-skew-y:0;--un-translate-x:0;--un-translate-y:0;--un-translate-z:0;--un-pan-x: ;--un-pan-y: ;--un-pinch-zoom: ;--un-scroll-snap-strictness:proximity;--un-ordinal: ;--un-slashed-zero: ;--un-numeric-figure: ;--un-numeric-spacing: ;--un-numeric-fraction: ;--un-border-spacing-x:0;--un-border-spacing-y:0;--un-ring-offset-shadow:0 0 rgba(0,0,0,0);--un-ring-shadow:0 0 rgba(0,0,0,0);--un-shadow-inset: ;--un-shadow:0 0 rgba(0,0,0,0);--un-ring-inset: ;--un-ring-offset-width:0px;--un-ring-offset-color:#fff;--un-ring-width:0px;--un-ring-color:rgba(147,197,253,0.5);--un-blur: ;--un-brightness: ;--un-contrast: ;--un-drop-shadow: ;--un-grayscale: ;--un-hue-rotate: ;--un-invert: ;--un-saturate: ;--un-sepia: ;--un-backdrop-blur: ;--un-backdrop-brightness: ;--un-backdrop-contrast: ;--un-backdrop-grayscale: ;--un-backdrop-hue-rotate: ;--un-backdrop-invert: ;--un-backdrop-opacity: ;--un-backdrop-saturate: ;--un-backdrop-sepia: ;}
```

### dark

`class | media | DarkModeSelectors = 'class'`

```ts
  interface DarkModeSelectors {
    /**
     * light variant的选择器.
     *
     * @default '.light'
     */
    light?: string

    /**
     * dark variant的选择器
     *
     * @default '.dark'
     */
    dark?: string
  }
```

默认情况下，此预设使用dark:variant生成基于类的dark模式。

```html
  <view class="dark:text-green-400" />
```

我们将生成

```css
  .dark .dark_c_text-green-400{--un-text-opacity:1;color:rgba(74,222,128,var(--un-text-opacity));}
```

要选择基于媒体查询的dark模式，您可以使用@dark:variant

```html
  <view class="@dark:text-green-400" />
```

我们将生成

```css
  @media (prefers-color-scheme: dark){
    ._u_dark_c_text-green-400{--un-text-opacity:1;color:rgba(74,222,128,var(--un-text-opacity));}
  }
```

或者使用针对dark:variant的配置进行全局设置

```js
  presetMpx({
    dark: "media"
  })
```

### attributifyPseudo

`boolean = false`

将伪选择器生成为\[group='']，而不是.group。只支持`group`|`peer`|`parent`|`previous`
如果attributifyPseudo为true的话，

```html
  <view class="group">
    <view class="group-hover:opacity-100" />
  </view>
```

上面template将生成

```css
  [group=""]:hover .group-hover_c_opacity-100{opacity:1;}
```

为false则生成

```css
  .group:hover .group-hover_c_opacity-100{opacity:1;}
```

### variablePrefix

`string = 'un-'`

CSS变量的前缀

```js
  presetMpx({
    variablePrefix: 'un-'
  })
```

```css
  .bg-red-500{--un-bg-opacity:1;background-color:rgba(239,68,68,var(--un-bg-opacity));}
```

## Request query

Mpx中允许用户在request中传递特定query执行特定逻辑，目前已支持的query如下：

### ?resolve

用于获取资源最终被输出的正确路径。

Mpx 在处理页面路径时会把对应的分包名作为 root 加在路径前。处理组件路径时会添加 hash，防止路径名冲突。直接写资源相对路径可能与最终输出的资源路径不符。

编写代码时使用 import 引入页面地址后加上 `?resolve`，这个地址在编译时会被处理成正确的绝对路径，即资源的最终输出位置。

```javascript
import subPackageIndexPage from '../subpackage/pages/index.mpx?resolve'

mpx.navigateTo({
  url: subPackageIndexPage
})
```

### ?root

1. 声明分包别名

指定分包别名，Mpx 项目在编译构建后会输出该别名的分包，外部小程序或 H5 页面跳转时，可直接配置该分包别名下的资源路径。

```js
// 可在项目app.mpx中进行配置
module.exports = {
  packages: [
    '@packagePath/src/app.mpx?root=test',
  ]
}

// 使用
wx.navigateTo({url : '/test/homepage/index'})
```

2. 声明组件所属异步分包

微信小程序新增 [分包异步化特性](https://developers.weixin.qq.com/miniprogram/dev/framework/subpackages/async.html) ，使跨分包的组件可以等待对应分包下载后异步使用, 在mpx中使用需通过?root声明组件所属异步分包即可使用，示例如下：

```html
<!--/packageA/pages/index.mpx-->
// 这里在分包packageA中即可异步使用分包packageB中的hello组件
<script type="application/json">
  {
    "usingComponents": {
      "hello": "../../packageB/components/hello?root=packageB",
      "simple-hello": "../components/hello"
    },
    "componentPlaceholder": {
      "hello": "simple-hello"
    }
  }
</script>
```

### ?fallback

`boolean`

对于使用`MpxWebpackPlugin.urlLoader`的文件，如果在引用资源的末尾加上`?fallback=true`，则使用配置的自定义loader。图片的引入和处理详见[图像资源处理](../guide/advance/image-process.md)。

```js
// vue.config.js
const { defineConfig } = require('@vue/cli-service')
module.exports = defineConfig({
  pluginOptions: {
    mpx: {
      urlLoader: {
        name: 'img/[name][hash].[ext]',
        publicPath: 'http://a.com/',
        fallback: 'file-loader' // 自定义fallback为true时使用的loader
      }
    }
  }
})
```

```css
/* png资源引入 */
<style>
  .logo2 {
    background-image: url('./images/logo.png?fallback=true'); /* 设置fallback=true，则使用如上方所配置的file-loader */
  }
</style>
```

### ?useLocal

`boolean`

静态资源存放有两种方式：本地、远程（配置 publicPath ）。useLocal 是用于在配置了 publicPath 时声明部分资源输出到本地。比如配置了通用的 CDN 策略，但如网络兜底资源需要强制走本地存储，可在引用资源的末尾加上`?useLocal=true`

```css
/* 单个图片资源设置为存储到本地 */
<style>
  .logo2 {
    background-image: url('./images/logo.png?useLocal=true');
  }
</style>
```

### ?isStyle

`boolean`

isStyle 是在非 style 模块中编写样式时，声明这部分引用的静态资源按照 style 环境来处理。如在 javascript 中 require 了一个图像资源，然后模版 template style 属性中进行引用， 则 require 资源时可选择配置`?isStyle=true`

```html
<template>
  <view class="list">
    <!-- isStyle 案例一：引用 javascript 中的数据 -->
    <view style="{{testStyle}}">测试</view>
    <!-- isStyle 案例二：设置资源按照style处理规则处理。style处理规则为: 默认走base64，除非同时配置了 publicPath 和 fallback -->
    <image src="../images/car.jpg?isStyle=true"></image>
    <!-- 普通非style模式，默认走 fallback 或者 file-loader 解析，输出到 publicPath 或者 本地img目录下 -->
    <image src="../images/car.jpg"></image>
  </view>
</template>
```

```js
/* 将 script 中的图像资源标识为 style 资源 */
<script>
  import { createComponent } from '@mpxjs/core'
  const backCar = require('../images/car.jpg?isStyle=true')

  createComponent({
    data: {},
    computed: {
      testStyle () {
        return `background-image : url(${backCar}); width:100px; height: 100px`
      }
    }
  })
</script>
```

### ?isPage

`boolean`

在 webpack config entry 入口文件配置中，你可以在路径后追加 ?isPage 来声明独立页面构建，构建产物为该页面的独立原生代码，
你可以提供该页面给其他小程序使用。此外，独立页面构建也可以通过MpxWebpackPlugin.getPageEntry生成，推荐使用[此方法。](#mpxwebpackplugin-getpageentry)

```js
// vue.config.js
const { defineConfig } = require('@vue/cli-service')
const MpxWebpackPlugin = require('@mpxjs/webpack-plugin')
module.exports = defineConfig({
  chainWebpack(config) {
    config.entry('index').add('../src/pages/index.mpx?isPage')
    // 或者
    // config.entry('index').add(MpxWebpackPlugin.getPageEntry('./index.mpx'))
  }
})
```

:::warning
对于使用 `@mpxjs/cli@2.x` 脚手架初始化的项目，配置 entry 的方式如下

```js
// build/getWebpackConf.js
module.exports = {
  entry: {
    index: '../src/pages/index.mpx?isPage'
  }
}
```

:::

### ?isComponent

`boolean`

在 webpack config entry 入口文件配置中，你可以在路径后追加 ?isComponent 来声明独立组件构建，构建产物为该组件的独立原生代码，
你可以提供该组件给其他小程序使用。
此外，独立组件构建也可以通过MpxWebpackPlugin.getComponentEntry生成，推荐使用[此方法。](#mpxwebpackplugin-getcomponententry)。

```js
// vue.config.js
const { defineConfig } = require('@vue/cli-service')
const MpxWebpackPlugin = require('@mpxjs/webpack-plugin')
module.exports = defineConfig({
  chainWebpack(config) {
    config.entry('index').add('../src/components/list.mpx?isComponent')
    // 或者
    // config.entry('index').add(MpxWebpackPlugin.getComponentEntry('./components/list.mpx'))
  }
})
```

### ?async

`boolean | string`

输出 H5 时 Vue Router 的路由懒加载功能，Mpx框架默认会对分包开启路由懒加载功能并将分包所有页面都打入同一个Chunk
，如果你希望对于部分主包页面或者分包页面配置路由懒加载并想自定义Chunk Name，则可以使用该功能。

```html
// app.mpx
<script type="application/json">
  {
    "pages": [
      "./pages/index?async", // 主包页面配置路由懒加载，Chunk Name 为随机数字
      "./pages/index2?async=app_pages2"，// 主包页面配置路由懒加载，Chunk Name 自定义为 app_pages2
    ],
    "packages": [
      "./packages/sub1/app.mpx?root=sub1"
    ]
  }
</script>

// packages/sub1/app.mpx

<script type="application/json">
  {
    "pages": [
      "./pages/index?async=sub1_pages_index", // 分包中页面设置路由懒加载并设置自定义Chunk Name
      "./pages/index2?async=sub2_pages_index2" // 分包中页面设置路由懒加载并设置自定义Chunk Name
    ]
  }
</script>

```

---

---
url: /api/builtIn.md
---
# 内建组件 {#built-in-components}

## component

* is `string` : 动态渲染组件，通过改变`is`的值，来渲染不同的组件

* range `string` : 使用 range 来指定可能渲染的组件，不传递时则为 全局注册 + usingComponents 中注册的所有组件，存在多个组件时使用逗号 `,` 分隔

```html
  <!-- ComponentName 是在全局或者组件中完成注册的组件名称 -->
  <component is="{{ComponentName}}"></component>

  <!-- 只会展示 compA 或者 compB 组件 -->
  <component is="{{ComponentName}}" range="compA,compB"></component>
```

**参考**：[动态组件](../guide/basic/component.md#dynamic-component)

## slot

* name `string` : 用于命名插槽

`<slot>` 元素作为组件模板中的内容分发插槽，`<slot>`元素自身将被替换。

详细用法，可参考下面的链接。

**参考**：[slot](../guide/basic/component.md#slot)

---

---
url: /api/reactivity-api.md
---

# 响应式 API {#reactivity-api}

## 响应式基础 API {#reactivity-basic-api}

### reactive

将对象处理为响应性对象。

```js
const obj = reactive({ count: 0 })
obj.count++
```

响应式转换是“深层”的：它会影响到所有嵌套的 property。一个响应式对象也将深层地解包任何 ref property，同时保持响应性。

```js
const count = ref(1)
const obj = reactive({ count })

// ref 会被解包
console.log(obj.count === count.value) // true

// 它会更新 `obj.count`
count.value++
console.log(count.value) // 2
console.log(obj.count) // 2
```

当将 `ref` 分配给 `reactive` property 时，ref 将被自动解包。

```ts
const count = ref(1)
const obj = reactive({})

obj.count = count

console.log(obj.count) // 1
console.log(obj.count === count.value) // true
```

当访问到某个响应式数组或 Map 这样的原生集合类型中的 ref 元素时，不会执行 ref 的解包

```js
const refArr = ref([ref(2)])
const state = reactive({
    count: 1,
    refArr
})

// 无需.vlaue
console.log(state.refArr)
// 这里需要.value
console.log(state.refArr[0].value)
```

当需要给响应式对象新增属性时，需要使用set，并且新增属性的响应式对象需要为 ref 或者做为其他响应性对象的key

```js
const state = reactive({
    count: 1
})
const stateRef = ref({
    count: 1
})
const stateRefWrap = reactive({
    data: {
        count: 1
    }
})

onLoad(() => {
    setTimeout(() => {
        set(state, 'foo', 1) // 不生效
        set(stateRef.value, 'foo', 1) // 生效
        set(stateRefWrap.data, 'foo', 1) // 生效
    }, 2000)
})

return {
    state,
    stateRef,
    stateRefWrap
}
```

### isReactive

检查对象是否是由 reactive 创建的响应式对象。

```js
import { createComponent, reactive, isReactive } from '@mpxjs/core'

createComponent({
    setup(){
        const state = reactive({
            count: 1
        })
        console.log(isReactive(state)) // -> true
        return {
            state
        }
    }
})
```

### markRaw

标记一个对象，使其永远不会被抓换为响应性对象，并返回对象本身

```js
import { markRaw, reactive, isReactive } from '@mpxjs/core'

const foo = markRaw({
    count: 1
})
const state = reactive({
    foo
})
console.log(isReactive(state.foo)) // -> false
```

**注意：**

如果将标记对象内部的未标记对象添加进响应性对象，然后再次访问该响应性对象，就会得到该原始对象的可响应性对象

```js
import { markRaw, reactive, isReactive } from '@mpxjs/core'

const foo = markRaw({
    nested: {}
})

const bar = reactive({
    nested: foo.nested
})

console.log(foo.nested === bar.nested) // -> true
```

### shallowReactive

reactive() 的浅层作用形式，只跟踪自身 property 的响应性，但不执行嵌套对象的深层响应式转换(返回原始值)

**注意：**

和 reactive() 不同，这里没有深层级的转换：一个浅层响应式对象里只有根级别的 property 是响应式的。property 的值会被原样存储和暴露，这也意味着值为 ref 的 property 不会被自动解包了。

```js
import { shallowReactive } from '@mpxjs/core'

const count = ref(0)
const state = shallowReactive({
  foo: 1,
  nested: {
    bar: 2
  },
  head: count  
})

// 更改状态自身的属性是响应式的
state.foo++

// ...但下层嵌套对象不会被转为响应式
isReactive(state.nested) // false

// 不是响应式的
state.nested.bar++

// ref 属性不会解包
state.head.value 
```

### set

用于对一个响应式对象新增属性，会`触发订阅者更新操作`

```ts
function set(target: Object | Array, property: string | number, value: any): void
```

```js
import { set, reactive } from '@mpxjs/core'
const person = reactive({name: 1})
// 具名导出使用
set(person, 'age', 17) // age 改变后会触发订阅者视图更新
```

### del

用于对一个响应式对象删除属性，会`触发订阅者更新操作`

```ts
function del(target: Object | Array, property: string | number): void
```

```js
import {del, reactive } from '@mpxjs/core'
const person = reactive({name: 1})
del(person, 'age')
```

## Computed 与 Watch {#computed-and-watch}

### computed

```ts
// 只读形式
function computed<T>(
    getter: () => T
): Readonly<Ref<Readonly<T>>>

// 可写形式
function computed<T>(
    options: {
        get: () => T
        set: (value: T) => void
    }
): Ref<T>
```

接受一个 getter 函数，并根据 getter 的返回值返回一个不可变的响应式 ref 对象。

```js
const count = ref(1)
const plusOne = computed(() => count.value + 1)

console.log(plusOne.value) // 2

plusOne.value++ // 错误
```

或者接受一个具有 get 和 set 函数的对象，用来创建可写的 ref 对象。

```js
const count = ref(1)
const plusOne = computed({
  get: () => count.value + 1,
  set: val => {
    count.value = val - 1
  }
})

plusOne.value = 1
console.log(count.value) // 0
```

### watchEffect

```ts
function watchEffect(
  effect: (onInvalidate: InvalidateCbRegistrator) => void,
  options?: WatchEffectOptions
): StopHandle

interface WatchEffectOptions {
    flush?: 'pre' | 'post' | 'sync' // 默认：'pre'
}

type InvalidateCbRegistrator = (invalidate: () => void) => void

type StopHandle = () => void
```

立即执行传入的函数，同时对其依赖进行响应式追踪，并在其依赖变更时重新运行该函数。

```js
const count = ref(0)

watchEffect(() => console.log(count.value))
// -> logs 0

setTimeout(() => {
  count.value++
  // -> logs 1
}, 100)
```

* 停止侦听

```js
const stop = watchEffect(() => {
  /* ... */
})

// later
stop()
```

* 清除副作用

侦听副作用传入的函数可以接收一个函数作入参，用来注册清理回调，清理回调会在该副作用下一次执行前被调用，
可以用来清理无效的副作用，例如等待中的异步请求

```js
watchEffect(async (onCleanup) => {
  const { response, cancel } = doAsyncWork(id.value)
  // `cancel` 会在 `id` 更改时调用
  // 以便取消之前未完成的请求
  onCleanup(cancel)
  data.value = await response
})
```

* 副作用刷新时机

响应式系统会进行副作用函数缓存，并异步地刷新执行他们

组件的 update 函数也是一个被侦听的副作用。当一个用户定义的副作用函数进入队列时，默认情况下，会在所有的组件 update 前执行，
在watchEffect的第二个参数中，我们可以传入flush来进行副作用刷新时机调整

```js
// 默认为 pre
watchEffect(callback, {
    flush: 'pre'
})

// 侦听器回调中能访问被更新之后的DOM
// 注意：这也将推迟副作用的初始运行，直到组件的首次渲染完成。
watchEffect(callback, {
  flush: 'post'
})

// 强制同步触发, 十分低效
watchEffect(callback, {
    flush: 'sync'
})
```

### watchSyncEffect

watchEffect 的别名，带有 flush: 'sync' 选项。

### watchPostEffect

watchEffect 的别名，带有 flush: 'post' 选项。

### watch

```ts
// 侦听单一源
function watch<T>(
    source: WatcherSource<T>,
    callback: (
        value: T,
        oldValue: T,
        onInvalidate: InvalidateCbRegistrator
    ) => void,
    options?: WatchOptions
): StopHandle

// 侦听多个源

type WatcherSource<T> = Ref<T> | (() => T)

type InvalidateCbRegistrator = (invalidate: () => void) => void

type StopHandle = () => void

interface WatchOptions extends WatchEffectOptions {
    immediate?: boolean // 默认：false
    deep?: boolean // 默认：false
    immediateAsync: boolean // 默认：false
}
```

该 API 与选项式 API 中的 watch 基本等效，watch 需要侦听特定的数据源，并在单独的回调函数中执行副作用。默认情况下
是惰性的——即回调仅在侦听源发生变化时被调用。

与 watchEffect 比较，watch 允许我们：

* 懒执行副作用；
* 更具体地说明什么状态应该触发侦听器重新运行；
* 访问侦听状态变化前后的值。

#### 侦听单一源 {#watch-single-source}

watch 可以侦听一个具有返回值的 getter，也可以直接是一个 ref

```js
// 侦听一个 getter
const state = reactive({ count: 0 })
watch(
  () => state.count,
  (count, prevCount) => {
    /* ... */
  }
)

// 直接侦听ref
const count = ref(0)
watch(count, (count, prevCount) => {
  /* ... */
})
```

#### 侦听多个源 {#watch-multiple-sources}

还可以使用数组的形式同时侦听多个数据源：

```js
import { watch } from '@mpxjs/core'

watch([aRef, bRef], ([a, b], [prevA, prevB]) => {
    /* ... */
})
```

#### 与 watchEffect 相同的行为 {#watcheffect-behavior}

**watch** 与 **watchEffect** 在手动停止侦听、清除副作用、副作用刷新时机方面有相同的行为。

```js
import { watch } from '@mpxjs/core'

let unwatch = watch(() => {
  return a.value + b.value
}, (newVal, oldVal) => {
  // 做点什么
})

// 调用返回值unwatch可以取消观察
unwatch()
```

#### watch 选项 {#watch-options}

* **选项**：deep

  为了发现对象内部值的变化，可以在选项参数中指定 deep: true。

  ```javascript
  import {watch} from '@mpxjs/core'

  watch(() => {
    return this.someObject
  }, () => {
    // 回调函数
  }), {
    deep: true
  })
  this.someObject.nestedValue = 123
  // callback is fired
  ```

* **选项**：once

  在选项参数中指定 `once: true` 该回调方法只会执行一次，后续的改变将不会触发回调；\
  该参数也可以是函数，若函数返回值为 `true` 时，则后续的改变将不会触发回调

  ```JavaScript
  import {watch} from '@mpxjs/core'

  watch(() => {
    return this.a
  }, () => {
    // 该回调函数只会执行一次
  }, {
    once: true
  })

  // 当 once 是函数时
  watch(() => {
    return this.a
   }, (val, newVal) => {
    // 当 val 等于2时，this.a 的后续改变将不会被监听
   }, {
    once: (val, oldVal) => {
      if (val == 2) {
        return true
      }
    }
  })
  ```

* **选项**：immediate

  在选项参数中指定 `immediate: true` 将立即以表达式的当前值触发回调。

  ```javascript
  import {watch} from '@mpxjs/core'

  watch(() => {
    return this.a
  }, () => {
    // 回调函数
  }), {
    immediate: true
  })
  // 立即以 `this.a` 的当前值触发回调
  ```

  注意在带有 immediate 选项时，你不能在第一次回调时取消侦听。

  ```javascript
  import {watch} from '@mpxjs/core'

  var unwatch = watch(() => {
    return this.a
  }, () => {
    unwatch() // 这会导致报错！
  }), {
    immediate: true
  })

  ```

  如果你仍然希望在回调内部调用取消侦听的函数，你应该先检查其可用性。

  ```javascript
  import {watch} from '@mpxjs/core'

  var unwatch = watch(() => {
    return this.a
  }, () => {
    if (unwatch) { // 请先检查其可用性！
      unwatch()
    }
  }), {
    immediate: true
  })
  ```

## Effect 作用域 API {#effect-scope-api}

### effectScope

```ts
function effectScope(detached?: boolean): EffectScope

interface EffectScope {
    run<T>(fn: () => T): T | undefined
    stop(): void
    pause(): void
    resume(): void
}
```

创建一个 effect 作用域对象，捕获在其内部创建的响应性副作用(例如计算属性或监听器)，可以对这些副作用进行批量处理

```js
import { effectScope } from '@mpxjs/core'

const scope = effectScope()
scope.run(() => {
    const doubled = computed(() => counter.value * 2)
    
    watch(doubled, () => console.log(doubled.value))
    
    watchEffect(() => console.log('Count: ', doubled.value))
})

scope.stop()
```

需要注意的是，effectScope 接受一个 detached 参数，默认为false，该参数来表示当前作用域是否和父级作用域进行分离，若 detached 为 true，
当前 effectScope 则不会被父级作用域收集。

* 暂停侦听

Mpx 提供了 pause 方法可以将整个作用域中的响应性副作用批量暂停侦听。

```js
import { effectScope, onHide } from '@mpxjs/core'
const scope = effectScope()
scope.run(() => {
    const doubled = computed(() => counter.value * 2)

    watch(doubled, () => console.log(doubled.value))

    watchEffect(() => console.log('Count: ', doubled.value))
})

onHide(() => {
    scope.pause()
})
```

* 恢复侦听

被暂停的作用域可以使用 resume 方法来恢复侦听。

```js
import {onShow} from '@mpxjs/core'
// ......

onShow(() => {
    scope.resume()
})
```

### getCurrentScope

```ts
function getCurrentScope(): EffectScope | undefined
```

返回当前活跃的 effect 作用域。

### onScopeDispose

```ts
function onScopeDispose(fn: () => void): void
```

在当前活跃的 effect 作用域上注册一个处理回调。该回调会在相关的 effect 作用域结束之后被调用。

## Refs

### ref

```ts
interface Ref<T> {
    value: T
}
function ref<T>(value: T): Ref<T>
```

接受一个内部值，返回一个响应式的、可更改的 ref 对象，此对象只有一个指向其内部值的 property .value。

```js
const count = ref(0)
console.log(count.value) // 0

count.value++
console.log(count.value) // 1
```

**注意事项：**

1.所有对 .value 的操作都将被追踪，并且写操作会触发与之相关的副作用。

2.如果将一个对象赋值给 ref，那么这个对象将被 reactive 转为具有深层次响应式的对象。这也意味着如果对象中包含了嵌套的 ref，它们将被深层地解包。

```js
import { ref } from '@mpxjs/core'
const foo = ref(0)
const state = ref({
    count: 1,
    foo
})
// 获取count
console.log(state.value.count)
// 获取foo
console.log(state.value.foo)
```

### unref

如果参数是一个 ref，则返回内部值，否则返回参数本身，是 `val = isRef(ref) ? ref.value : ref` 的语法糖函数。

```js
import { ref, unref } from '@mpxjs/core'
const count = ref(0)
const foo = unref(count)

console.log(foo === 0) // -> true
```

### toRef

用于为响应式对象上的property 创建 ref。创建的 ref 与其源 property 保持同步：改变源 property
将更新 ref，改变 ref 也将更新 property。

```js
const state = reactive({
    f: 1,
    b: 2
})

const stateRef = ref({
    black: 1,
    white: 2
})

const fooRef = toRef(state, 'f')
const blackRef = toRef(stateRef.value, 'black') 

// 更改ref的值更新属性
fooRef.value++
blackRef.value++
console.log(state.f) // 2
console.log(stateRef.value.black) // 2

// 更改property的值更新ref
state.f++
stateRef.value.black++
console.log(fooRef.value) // 3
console.log(blackRef.value) // 3
```

**注意：**

即使源 property 当前不存在，toRef() 也会返回一个可用的 ref，而 toRefs 则不会，这在处理可选properties的时候
非常有用

### toRefs

将一个响应式对象转换为一个普通对象，这个普通对象的每个 property 都是指向源对象相应 property 的 ref。每个单独的 ref 都是 `toRef` 创建的

```js
const state = reactive({
    black: 1,
    white: 2
})

const stateAsRefs = toRefs(state)

state.black++
console.log(stateAsRefs.black.value) // 2

stateAsRefs.black.value++
console.log(state.black) // 3
```

toRefs 在使用组合式函数中的响应式对象时有很大作用，使用它，对响应式对象进行解构将不会失去响应性

```js
function useFeatX() {
    const state = reactive({
        black: 1,
        white: 2
    })
    
    // 在返回时都转为 ref
    return toRefs(state)
}

// 解构而不会失去响应性
const {black, white} = useFeatX()
```

**注意：**

* toRefs 在调用时只会为源对象上可以列举出的 property 创建 ref。如果要为可能还不存在的 property
  创建 ref，请改用 `toRef`

### isRef

检查某个值是否为 ref，返回true/false。

### customRef

```ts
function customRef<T>(factory: CustomRefFactory<T>): Ref<T>

type CustomRefFactory<T> = (
    track: () => void,
    trigger: () => void
) => {
    get: () => T,
    set: (value: T) => void
}
```

创建一个自定义 ref，可对其进行依赖项跟踪和更新触发显示控制。需要一个工厂函数，该函数接收 `track` 和 `trigger`
做为参数，并且应该返回一个带有 `get` 和 `set` 的对象。

同时，`track()` 应该在 get() 方法中调用，`trigger()` 应该在 `set()` 中调用。不过这里具体何时调用、
是否调用都将由用户自己来控制

示例：创建一个防抖 ref，即只在最近一次 set 调用后的一段固定间隔后再调用：

```js
function useDebouncedRef(value, delay = 200) {
  let timeout
  return customRef((track, trigger) => {
    return {
      get() {
        track()
        return value
      },
      set(newValue) {
        clearTimeout(timeout)
        timeout = setTimeout(() => {
          value = newValue
          trigger()
        }, delay)
      }
    }
  })
}

// text 的每次改变都只在最近一次set后的200ms后调用
const text = useDebouncedRef('hello')
```

### shallowRef

`ref()` 的浅层作用形式，创建一个仅跟踪自身 `.value` 变化的 ref，其他值不做任何处理都为非响应式

```js
const state = shallowRef({
    count: 1
})

// 不会触发更改
state.value.count++

// 会触发更改
state.value = {
    black: 1
}
```

**注意：**
shallowRef 的内部值将会被原样存储和暴露，不会被深层递归转为响应性， 只有对 `.value` 的访问是响应式的

常常用于对大型数据结构的性能优化或是与外部的状态管理系统集成。

### triggerRef

强制触发依赖于一个浅层 `ref` 的副作用，这通常在对浅引用的内部值进行深度变更后使用。

```js
const shallow = shallowRef({
  greet: 'Hello, world'
})

// 触发该副作用第一次应该会打印 "Hello, world"
watchEffect(() => {
  console.log(shallow.value.greet)
})

// 这次变更不应触发副作用，因为这个 ref 是浅层的
shallow.value.greet = 'Hello, universe'

// 手动执行该 shallowRef 关联的副作用，打印 "Hello, universe"
triggerRef(shallow)

```

---

---
url: /api/composition-api.md
---
# 组合式 API {#composition-api}

## setup

一个组件选项，在组件被创建之前，props 被解析之后执行。是组合式 API 的入口。

* **参数**：
  * `{Data} props`
  * `{SetupContext} context`

该 **props** 对象仅包含显性声明的 properties。并且所有声明了的prop，不论父组件是否向其传递，
都将出现在 **props** 对象中。其中未被传入的可选的 prop 的值会是默认值或 undefined。

```js
import { createComponent } from '@mpxjs/core'

createComponent({
    properties: {
        min: {
            type: Number,
            value: 0
        },
        lastLeaf: {
            // 这个属性可以是 Number 、 String 、 Boolean 三种类型中的一种
            type: Number,
            optionalTypes: [String, Object],
            value: 0
        }
    },
    setup(props) {
        console.log(props.min)
        console.log(props.lastLeaf)
    }
})
```

* **类型声明**：

```ts
interface SetupContext {
    triggerEvent(
       name: string,
       detail?: object, // detail对象，提供给事件监听函数
       options?: {
         bubbles?: boolean
         composed?: boolean
         capturePhase?: boolean
       }
    ): void
    refs: ObjectOf<NodesRef & ComponentIns>
    asyncRefs: ObjectOf<Promise<NodesRef & ComponentIns>> // 字节小程序特有
    nextTick: (fn: () => void) => void
    forceUpdate: (params?: object, callback?: () => void) => void
    selectComponent(selector: string): ComponentIns
    selectAllComponents(selector: string): ComponentIns[]
    createSelectorQuery(): SelectorQuery
    createIntersectionObserver(
      options: {
        thresholds?: Array<number>
        initialRatio?: number
        observeAll?: boolean
      }
    ): IntersectionObserver}

function setup(props: Record<string, any>, context: SetupContext): Record<string, any>
```

## 生命周期钩子 {#lifecycle-hooks}

可以通过直接导入 on\* 函数来注册生命周期钩子：

```js
import { onMounted, onUpdated, onUnmounted, createComponent } from '@mpxjs/core'

createComponent({
  setup() {
    onMounted(() => {
      console.log('mounted!')
    })
    onUpdated(() => {
      console.log('updated!')
    })
    onUnmounted(() => {
      console.log('unmounted!')
    })
  }
})
```

这些生命周期钩子注册函数只能在 setup() 期间同步使用，因为它们依赖于内部的全局状态来定位当前活动的实例 (此时正在调用其 setup() 的组件实例)。
在没有当前活动实例的情况下，调用它们将会出错。

组件实例的上下文也是在生命周期钩子的同步执行期间设置的，因此，在生命周期钩子内同步创建的侦听器和计算属性也会在组件卸载时自动删除。

新版本的生命周期钩子我们基本上和 Vue 中的生命周期钩子对齐，相较于之前还是有部分生命周期钩子的改动。

### onBeforeMount

`Function`

在组件布局完成后执行，refs 相关的前置工作在该钩子中执行。

### onMounted

`Function`

在组件布局完成后执行，refs 可以直接获取。

### onBeforeUpdate

`Function`

在数据发生改变后，组件/页面更新之前被调用。这里适合在现有组件/页面将要被更新之前访问它，
比如移除某个手动添加的监听器，或者获取某个元素更新前的高度。

### onUpdated

`Function`

在数据更改导致的页面/组件重新渲染和更新完毕之后被调用。

注意，onUpdated 不会保证所有的子组件也都被重新渲染完毕。如果你希望等待整个视图都渲染完毕，可以在 onUpdated 内部使用 nextTick。

### onBeforeUnmount

`Function`

在卸载组件/页面实例之前调用。在这个阶段，实例仍然是完全正常的。

### onUnmount

`Function`

卸载组件实例后调用。调用此钩子时，组件实例的所有指令都被解除绑定，所有事件侦听器都被移除。

### onLoad

`Function`

小程序页面 onLoad 事件，监听页面加载。
::: tip 注意
在页面拼接参数时，不同平台对 URL 参数的处理方式存在差异：

* **微信、QQ、字节跳动、RN**：参数透传，保持原始格式
* **其他平台**：会自动对 encode 后的参数进行 decode

为了提供统一的参数处理方式，`onLoad` 钩子额外提供了一个经过 encode 处理的参数对象，方便业务使用统一的参数格式，同时不影响各平台原有的参数返回。

**微信、QQ、字节跳动、RN下的效果：**

```js
// A页面
...
createPage({
  methods: {
    jumpPage () {
      mpx.navigateTo({
        url: `./pages/test?name=${encodeURIComponent('我')}&encode=true`
      })
    }
  }
})
...

// test页面
...
createPage({
  onLoad(rawQuery, decodedQuery) {
    // rawQuery = {name: "%E6%88%91", encode: "true"}
    // decodedQuery = {name: "我", encode: "true"}
    ...
  }
})
...
```

**其他平台的效果：**

```js
// A页面
...
createPage({
  methods: {
    jumpPage () {
      mpx.navigateTo({
        url: `./pages/test?name=${encodeURIComponent('我')}&encode=true`
      })
    }
  }
})
...

// test页面
...
createPage({
  onLoad(rawQuery, decodedQuery) {
    // rawQuery = {name: "我", encode: "true"}
    // decodedQuery = {name: "我", encode: "true"}
    ...
  }
})
...
```

:::

### onShow

`Function`

小程序页面 onShow 事件，监听页面展示。

### onHide

`Function`
小程序页面 onHide 事件，监听页面隐藏。

### onResize

`Function`

小程序页面 onResize 事件，页面尺寸改变时触发。

### onPullDownRefresh

`Function`

小程序监听用户下拉刷新事件。[详细介绍](https://developers.weixin.qq.com/miniprogram/dev/reference/api/Page.html#onPullDownRefresh)

### onReachBottom

`Function`

小程序监听用户上拉触底事件。[详细介绍](https://developers.weixin.qq.com/miniprogram/dev/reference/api/Page.html#onReachBottom)

### onShareAppMessage

`Function`

小程序监听用户点击页面内转发按钮（button 组件 open-type="share"）或右上角菜单“转发”按钮的行为，并自定义转发内容。[详细介绍](https://developers.weixin.qq.com/miniprogram/dev/reference/api/Page.html#onShareAppMessage-Object-object)

### onShareTimeline

`Function`

小程序监听右上角菜单“分享到朋友圈”按钮的行为，并自定义分享内容。[详细介绍](https://developers.weixin.qq.com/miniprogram/dev/reference/api/Page.html#onShareTimeline)

**注意：** 仅微信小程序支持

### onAddToFavorites

`Function`

小程序监听用户点击右上角菜单“收藏”按钮的行为，并自定义收藏内容。[详细介绍](https://developers.weixin.qq.com/miniprogram/dev/reference/api/Page.html#onAddToFavorites-Object-object)

**注意：** 仅微信小程序支持

### onPageScroll

`Function`

小程序监听用户滑动页面事件。[详细介绍](https://developers.weixin.qq.com/miniprogram/dev/reference/api/Page.html#onPageScroll-Object-object)

### onTabItemTap

`Function`

点击 tab 时触发。[详细介绍](https://developers.weixin.qq.com/miniprogram/dev/reference/api/Page.html#onTabItemTap-Object-object)

### onSaveExitState

`Function`

每当小程序可能被销毁之前，页面回调函数 onSaveExitState 会被调用，可以进行退出状态的保存。[详细介绍](https://developers.weixin.qq.com/miniprogram/dev/reference/api/Page.html#onSaveExitState)

**注意：** 仅微信小程序支持

### onServerPrefetch

* **类型：** `Function`
* **详细：**

SSR渲染定制钩子，在服务端渲染期间被调用，可以实现在服务端进行数据预取。

**注意：** 仅 web 环境支持

## getCurrentInstance

getCurrentInstance 支持访问内部组件实例。

* **注意：**

getCurrentInstance 只暴露给高阶使用场景，典型的比如在库中。强烈反对在应用的代码中使用 getCurrentInstance。请不要把它当作在组合式 API 中获取 this 的替代方案来使用。

getCurrentInstance 只能在 setup 或生命周期钩子中调用。

## useI18n

点击[查看详情](extend.md#usei18n)

## useFetch

点击[查看详情](extend.md#usefetch)

## provide

点击[查看详情](../guide/advance/provide-inject.md#composition-syntax-1)

## inject

点击[查看详情](../guide/advance/provide-inject.md#组合式语法-1)

---

---
url: /api/optional-api.md
---
# 选项式 API {#optional-api}

### options.shallowReactivePattern

* **类型：** `RegExp`
* **详细：**

取消data/properties内数据的深度响应。

适用于每次更新均为整体的更新而非局部少量数据更新的大型数据，可减少掉对应属性“数据响应初始化”以及“diff比较”两个阶段的耗时

```html
<!-- child -->
<script>
createComponent({
  properties: {
    bigPropData: Object
  },
  data: {
    // 这个是视图上需要用到的大数据
    bigData: { a: 0 }
  },
  options: {
    // 配置具体哪些data或者properties需要忽略响应
    shallowReactivePattern: /bigData|bigPropData/
  }，
  methods: {
    foo() {
      this.bigData = { a: 1 } // 可触发视图更新
    },
    bar() {
      this.bigData.a = 2 // 不可触发视图更新
    }
  }
})
</script>

<!-- perant -->
<template>
  <child bigPropData="{{parentBigData}}"/>
</template>
<script>
createComponent({
  data: {
    parentBigData: []
  },
  options: {
    shallowReactivePattern: /parentBigData/ // 父组件中传入的data也需要开启shallowReactive
  }
})
</script>
```

> 注意

### onAppInit

* **类型：** `Function`
* **详细：**

通过 createApp 注册一个应用期间被调用，输出 web 时 SSR渲染模式下，需要在此钩子中生成 pinia 的实例并返回。

### onSSRAppCreated

* **类型：** `Function`
* **详细：**

SSR渲染定制钩子，在服务端渲染期间被调用，可以在这个钩子中可以去返回应用程序实例，以及完成服务器端路由匹配，store 的状态挂载等。类 Vue 的 server entry 中的功能。

**注意：** 仅 web 环境支持

---

---
url: /api/extend.md
---

# 周边拓展 {#extensions}

## mpx-fetch

mpx-fetch提供了一个实例**xfetch** ，该实例包含以下api

### fetch(config)

> 正常的promisify风格的请求方法

* `{Object} config`

  config 可指定以下属性：

  * **url**

    `string`

    设置请求url
  * **method**

    `string`

    设置请求方式，默认为GET
  * **data**

    `object`

    设置请求参数
  * **params**

    `object`

    设置请求参数，参数会以 Query String 的形式进行传递
  * **header**

    `object`

    设置请求的 header，header 中不能设置 Referer。
    `content-type` 默认为 `application/json`
  * **timeout**

    `number`

    单位为毫秒。若不传，默认读取app.json文件中\_\_networkTimeout属性。 对于超时的处理可在 catch 方法中进行
  * **emulateJSON**

    `boolean`

    设置为 true 时，等价于 header = {'content-type': 'application/x-www-form-urlencoded'}
  * **usePre**

    `boolean`

    预请求开关，若设置为 true，则两次请求间隔在有效期内且请求参数和请求方式对比一致的情况下，会返回上一次的请求结果
  * **cacheInvalidationTime**

    `number`

    预请求缓存有效时长，单位 ms，默认为 5000ms。当两次请求时间间隔超过设置时长后再发起二次请求时，上一次的请求缓存会失效然后重新发起请求
  * **ignorePreParamKeys**

    `array` | `string`

    在判断缓存请求是否可用对比前后两次请求参数时，默认对比的是 options 传入的所有参数（包括 params 和 data ）。但在具体业务场景下某些参数不一致时的缓存结果依旧可使用（比如参数中带有时间戳），所以提供 ignorePreParamKeys 来设置对比参数过程中可忽略的参数的 key，支持字符串数组和字符串（字符串传多个 key 时使用英文逗号分隔）类型。
    配置后在进行参数对比时，不会对比在 ignorePreParamKeys 设置的参数。

```js
import mpx from '@mpxjs/core'
import mpxFetch from '@mpxjs/fetch'
mpx.use(mpxFetch)
// 第一种访问形式
mpx.xfetch.fetch({
    url: 'http://xxx.com',
    method: 'POST',
    params: {
        age: 10
    },
    data: {
        name: 'test'
    },
    header: {
      'content-type': 'application/x-www-form-urlencoded',
    },
    emulateJSON: true,
    usePre: true,
    cacheInvalidationTime: 3000,
    ignorePreParamKeys: ['timestamp']
}).then(res => {
	console.log(res.data)
})

mpx.createApp({
	onLaunch() {
		// 第二种访问形式
		this.$xfetch.fetch({url: 'http://test.com'})
	}
})
```

### CancelToken

命名导出，用于创建一个取消请求的凭证。

```js
import { CancelToken } from '@mpxjs/fetch'
const cancelToken = new CancelToken()
mpx.xfetch.fetch({
	url: 'http://xxx.com',
	data: {
		name: 'test'
	},
	cancelToken: cancelToken.token
})
cancelToken.exec('手动取消请求') // 执行后请求中断，返回abort fail
```

### XFetch

命名导出，用于创建一个新的mpx-fetch实例进行独立使用

```ts
interface FetchOptions{
    useQueue: boolean // 是否开启队列功能
    proxy: boolean // 是否开启代理功能
}
```

```js
import { XFetch } from '@mpxjs/fetch'
const newFetch = new XFetch(options) // 生成新的mpx-fetch实例
```

### interceptors

> 实例属性，用于添加拦截器，包含两个属性，request & response

```js
mpx.xfetch.interceptors.request.use(function(config) {
    console.log(config)
    // 也可以返回promise
    return config
})
mpx.xfetch.interceptors.response.use(function(res) {
    console.log(res)
    // 也可以返回promise
    return res
})
```

### proxy 代理{#proxy}

#### setProxy

> 配置代理项，可以传入一个数组或者一个对象，请求会按设置的规则进行代理

* **参数：**

  `{Array | Object}`

  * **test**

    `object`

    * url

      `string`

      全路径匹配，规则可以参考[path-to-regexp](https://www.npmjs.com/package/path-to-regexp)，也可参考下面的简单示例。

      ::: warning
      如果设置了此项，则 protocol、host、port、path 规则不再生效。此项支持 path-to-regexp 匹配，protocol、host、port、path 为全等匹配。
      :::

    * protocol

      `string`

      待匹配的协议头

    * host

      `string`

      不包含端口的 host

    * port

      `string`

      待匹配的端口

    * path

      `string`

      待匹配的路径

    * params

      `object`

      同时匹配请求中的 `params` 和 `query`

    * data

      `object`

      匹配请求中的 `data`

    * header

      `object`

      匹配请求中的 `header`

    * method

      `Method | Method[]`

      匹配请求方法，不区分大小写，可以传一个方法，也可以传一个方法数组

    * custom

      `function`

      自定义匹配规则，参数会注入原始请求配置，结果需返回 `true` 或 `false`

      ::: warning
      如果设置了此项，匹配结果以此项为准，以上规则均不再生效。
      :::

  * **proxy**

    `object`

    * url

      `string`

      代理的 url

    * protocol

      `string`

      修改原请求的协议头

    * host

      `string`

      代理的 host，不包含端口号

    * port

      `string`

      修改端口号

    * path

      `string`

      修改原请求路径

    * params

      `object`

      合并原请求的 params

    * data

      `object`

      合并原请求的 data

    * header

      `object`

      合并原请求的 header

    * method

      `Method`

      替换原请求的方法

    * custom

      `function`

      自定义代理规则，会注入两个参数，第一个是上一个匹配规则处理后的请求配置，第二个是 match 的参数对象，结果需返回要修改的请求配置对象。

      ::: warning
      如果设置了此项，最终代理配置将以此项为准，其他配置规则均不再生效。
      :::

  * **waterfall**

    `boolean`

    默认为 `false`，为 `false` 时，命中当前规则处理完就直接返回；为 `true` 时，命中当前匹配规则处理完成后将结果传递给下面命中匹配规则继续处理。

```js
mpx.xfetch.setProxy([{
    test: { // 此项匹配之后，会按下面 proxy 配置的修改请求配置
		header: {
            'content-type': 'application/x-www-form-urlencoded'
        },
        method: 'get',
        params: {
            a: 1
        },
        data: {
            test1: 'abc'
        }
	},
	proxy: {
		header: {
			env: 'env test'
		},
		params: {
			b: 2
        },
        data: {
            test2: 'cba'
        }
	},
	waterfall: true // 为 true 时会将此次修改后的请求配置继续传递给下面的规则处理
}, {
    test: {// 可以分别单独匹配 protocol、host、port、path；代理规则同样
        protocol: 'http:',
		host: 'mock.didi.com',
		port: '',
		path: '/mock/test'
    },
    proxy: {
        host: 'test.didi.com',
        port: 8888
    },
    waterfall: true
}, {
    test: { // 自定义匹配规则
        custom (config) { // config 为原始的请求配置
            // 自定义匹配逻辑
			if (xxx) {
				return true
			}
			return false
		}
    },
    proxy: { // 自定义代理配置
        custom (config, params) {
			// config 为上面匹配后修改过的请求配置
            // params 为 match 后的参数对象
            // 返回需要修改的请求配置对象
			return {
                params: {
                    c: 3
                },
				data: {
					test3: 'aaa'
				}
			}
		}
    },
    waterfall: true
}, {
    test: {
        // : 可以匹配目标项，并将 match 结果返回到代理 custom 函数中
        // :和?都属于保留符号，若不想做匹配时需用 '\\' 转义
        // (.*)为全匹配
        url: ':protocol\\://mock.didi.com/mock/:id/oneapi/router/forum/api/v1/(.*)',
        method: ['get', 'post']
    },
    proxy: {
        url: 'https://127.0.0.1:8080/go/into/$id/api/v2/abcd' // '$'项在代理生效后会替换匹配规则中的':'项
    },
    waterfall: false // false 时不会继续匹配后面的规则
}])
```

#### prependProxy

> 向前追加代理规则

```js
mpx.xfetch.prependProxy({
	test: {},
	proxy: {},
	waterfall: true
})
```

#### appendProxy

> 向后追加代理规则

```js
mpx.xfetch.appendProxy({
	test: {},
	proxy: {},
	waterfall: true
})
```

#### getProxy

> 查看已有的代理配置

```js
console.log(mpx.xfetch.getProxy())
```

#### clearProxy

> 解除所有的代理配置

```js
mpx.xfetch.clearProxy()
```

### useFetch

```ts
useFetch(options?: FetchOptions):xfetch
```

在组合式 API 中使用，用来获取 `@mpxjs/fetch` 插件的 xfetch 实例，等用于 `mpx.xfetch`。 关于 xfetch 实例的详细介绍，请点击[查看](extend.md#mpx-fetch)

此外该方法可选择传入 `options` 参数，若传入参数，则会创建一个新的 XFetch 实例返回，若不传入参数，则默认将全局 `xfetch` 实例返回。

```js
// app.mpx
import mpx from '@mpxjs/core'
import mpxFetch from '@mpxjs/fetch'
mpx.use(mpxFetch)

// script-setup.mpx
import { useFetch } from '@mpxjs/fetch'
useFetch().fetch({
  url: 'http://xxx.com',
  method: 'POST',
  params: {
    age: 10
  },
  data: {
    name: 'test'
  },
  emulateJSON: true,
  usePre: true,
  cacheInvalidationTime: 3000,
  ignorePreParamKeys: ['timestamp']
}).then(res => {
  console.log(res.data)
})
```

* **注意：** options 参数同 [XFetch](extend.md#xfetch) 章节。

## size-report

Mpx框架项目包体积可以进行分组、分包、页面、冗余Npm包等维度的分析和对比，详细[请见](/advance/size-report.html)

### 插件配置项 {#plugin-options}

* **server**

  `object`

  本地可视化服务相关配置

* **filename**

  `string`

  构建生成的包体积详细输出文件地址

* **threshold**

  `object`

  配置项目总体积和分包体积阈值，包含两个字段，size 为项目总体积阈值，packages 为分包体积阈值

  ```html
  {
     size: '16MB', // 项目总包体积限额 16M
     packages: '2MB' // 项目每个分包体积限额 2M
  }
  ```

* **groups**

  `Array<object>`

  配置体积计算分组，以输入分组为维度对体积进行分析，当没有该配置时结果中将不会包含分组体积信息

  * name

    `string`

    分组名称

  * threshold

    `string | object`

    分组相关体积阈值，若不配置则该分组不校验体积阈值，同时也支持对分组中占各分包体积阈值

    ```html
    // 分组体积限额 500KB
    threshold: '500KB'
    // 或者如下方，分组体积限额500KB，分组占主包体积限额160KB
    threshold: {
      size: '500KB',
      packages: {
        main: '160KB'
      }
    }
    ```

  * entryRules

    `object`

    配置分组 entry 匹配规则，小程序中所有的页面和组件都可被视为 entry

    * include: 包含符合条件的入口文件，默认为空数组，规则数组中支持函数、正则、字符串
    * exclude: 剔除符合条件的入口文件，默认为空数组，规则数组中支持函数、正则、字符串

    ```html
    include: [/@someGroup\/some-npm-package/],
    exclude: [/@someGroup\/some-two-pack/]
    ```

  * noEntryRules

    `object`

    配置计算分组中纯 js 入口引入的体积（不包含组件和页面）

    * include: 包含符合条件的 js 文件，默认为空数组，规则数组中支持函数、正则、字符串
    * exclude: 剔除符合条件的 js 文件，默认为空数组，规则数组中支持函数、正则、字符串

    ```html
    include: [/@someGroup\/some-npm-package/],
    exclude: [/@someGroup\/some-two-pack/]
    ```

* **reportPages**

  `boolean`

  是否收集页面维度体积详情，默认 false

* **reportAssets**

  `boolean`

  是否收集资源维度体积详情，默认 false

* **reportRedundance**

  `boolean`

  是否收集冗余资源，默认 false

* **showEntrysPackages**

  `Array<string>`

  展示某些分包资源的引用来源信息，例如 \['main'] 为查看主包资源的引用来源信息，默认为 \[]

配置使用示例：

```html
{
  // 本地可视化服务相关配置
  server: {
    enable: true, // 是否启动本地服务，非必填，默认 true
    autoOpenBrowser: true, // 是否自动打开可视化平台页面，非必填，默认 true
    port: 0, // 本地服务端口，非必填，默认 0(随机端口)
    host: '127.0.0.1', // 本地服务host，非必填
  },
  // 体积报告生成后输出的文件地址名，路径相对为 dist/wx 或者 dist/ali
  filename: '../report.json',
  // 配置阈值，此处代表总包体积阈值为 16MB，分包体积阈值为 2MB，超出将会触发编译报错提醒，该报错不阻断构建
  threshold: {
    size: '16MB',
    packages: '2MB'
  },
  // 配置体积计算分组，以输入分组为维度对体积进行分析，当没有该配置时结果中将不会包含分组体积信息
  groups: [
    {
      // 分组名称
      name: 'vant',
      // 配置分组 entry 匹配规则，小程序中所有的页面和组件都可被视为 entry，如下所示的分组配置将计算项目中引入的 vant 组件带来的体积占用
      entryRules: {
        include: '@vant/weapp'
      }
    },
    {
      name: 'pageGroup',
      // 每个分组中可分别配置阈值，如果不配置则表示
      threshold: '500KB',
      entryRules: {
        include: ['src/pages/index', 'src/pages/user']
      }
    },
    {
      name: 'someSdk',
      entryRules: {
        include: ['@somegroup/someSdk/index', '@somegroup/someSdk2/index']
      },
      // 有的时候你可能希望计算纯 js 入口引入的体积（不包含组件和页面），这种情况下需要使用 noEntryRules
      noEntryRules: {
        include: 'src/lib/sdk.js'
      }
    }
  ],
  // 是否收集页面维度体积详情，默认 false
  reportPages: true,
  // 是否收集资源维度体积详情，默认 false
  reportAssets: true,
  // 是否收集冗余资源，默认 false
  reportRedundance: true,
  // 展示某些分包资源的引用来源信息，默认为 []
  showEntrysPackages: ['main']
}
```

## i18n

### useI18n

组合式 API 中使用，用来获取 i18n 实例。

**参数选项**

***

#### locale

`Locale`

设置语言环境

**注意：** 只传 locale，不传 messages 属性时不起作用

#### fallbackLocale

`Locale`

预设的语言环境，找不到语言环境时进行回退。

#### messages

`LocaleMessages`

本地化的语言环境信息。

**返回实例属性和方法**

***

#### locale

`WritableComputedRef<Locale>`

可响应性的 ref 对象，表示当前 i18n 实例所使用的 locale。

修改 ref 值会对局部或者全局语言集的 locale 进行更改，并触发翻译方法重新执行。

#### fallbackRoot

`boolean`

本地化失败时是否回归到全局作用域。

#### getLocaleMessage( locale )

```ts
function getLocaleMessage (locale: string): LocaleMessageObject
```

获取语言环境的 `locale` 信息。

#### setLocaleMessage( locale, message )

```ts
function setLocaleMessage(locale: Locale, messages: LocaleMessageObject): void
```

设置语言环境的 `locale` 信息。

#### mergeLocaleMessage( locale, message )

```ts
function mergeLocaleMessage(locale: Locale, messages: LocaleMessageObject): void
```

将语言环境信息 `locale` 合并到已注册的语言环境信息中。

#### messages

```ts
readonly messages: ComputedRef<{
   [K in keyof Messages]: Messages[K];
}>;
```

* **只读**

局部或者全局的语言环境信息。

#### isGlobal

`boolean`

是否是全局 i18n 实例。

#### t

```ts
function t(key: string, choice?: number, values: Array | Object): TranslateResult
```

文案翻译函数

根据传入的 key 以及当前 locale 环境获取对应文案，文案来源是全局作用域还是本地作用域取决于 `useI18n` 执行时是否传入对应的 `messages、locale` 等值。

**choice 参数可选** ，当传入 choice 时，t 函数的表现为使用复数进行翻译，和老版本中的 tc 函数表现一致。

```html
<template>
  <view>{{t('car', 1)}}</view>
  <view>{{t('car', 2)}}</view>

  <view>{{t('apple', 0)}}</view>
  <view>{{t('apple', 1)}}</view>
  <view>{{t('apple', 10, {count: 10})}}</view>
</template>

<script>
  // 语言环境信息如下：
  const messages = {
    en: {
      car: 'car | cars',
      apple: 'no apples | one apple | {count} apples'
    }
  }
</script>
```

输入如下：

```html
<view>car</view>
<view>cars</view>

<view>no apples</view>
<view>one apple</view>
<view>10 apples</view>
```

关于复数的更多信息可以点击[查看](https://kazupon.github.io/vue-i18n/zh/guide/pluralization.html#%E5%A4%8D%E6%95%B0)

**values 参数可选** ，如果需要对文案信息即逆行格式化处理，则需要传入 values。

```html
<template>
  // 模版输出 hello world
  <view>{{t('message.hello', { msg: 'hello'})}}</view>
</template>
<script>
  import {createComponent, useI18n} from "@mpxjs/core"

  const messages = {
    en: {
      message: {
        hello: '{msg} world'
      }
    }
  }

  createComponent({
    setup(){
        const { t } = useI18n({
          messages: {
              'en-US': en
          }
        })
      return {t}
    }
  })

</script>
```

#### te

```ts
function te(key: string): boolean
```

检查 key 是否存在。

---

---
url: /api-proxy.md
---
# 跨平台环境 API {#api-proxy}

Mpx 生态提供的一套跨平台环境 API 的抹平，方便开发者在开发跨平台应用时，使用相同的代码访问跨平台一致的环境 API 能力，目前已支持的平台包括微信、支付宝等主流小程序平台、Web 和 React Native。

已完成跨平台适配的环境 API 均会在官方文档中提供详细说明。若您在文档中未找到某个环境 API 的相关介绍，说明该 API 尚未进行跨平台适配。

如果你的应用只需要输出到小程序，而无需跨平台，你可以参考对应小程序平台的官方文档直接调用对应的环境 API，即使该 API 未在当前文档中列出。

## 使用 {#usage}

```js
// 使用 Mpx 生态

import mpx from "@mpxjs/core"
import apiProxy from "@mpxjs/api-proxy"

mpx.use(apiProxy, options)
```

## 配置项 (Options) {#options}

所有配置均为可选，可根据实际需求组合使用

| 参数名称        | 类型              | 含义                                                       | 是否必填 | 默认值  | 备注                                                        |
| --------------- | ----------------- | ---------------------------------------------------------- | -------- | ------- | ----------------------------------------------------------- |
| ~~platform~~    | ~~Object~~        | ~~各平台之间的转换~~                                       | ~~否~~   |         | 已删除                                                      |
| ~~exclude~~     | ~~Array(String)~~ | ~~跨平台时不需要转换的 api~~                               | ~~否~~   | ~~\[]~~  | 已删除                                                      |
| usePromise      | Boolean           | 是否启用 Promise 化风格调用                                | 否       | `false` | 开启后，符合 Promise 化规则的异步 API 会返回 Promise 对象   |
| whiteList       | Array(String)     | **强制启用** Promise 化的 API 名单                         | 否       | `[]`    | 仅在 usePromise: true 时有效，可覆盖 blackList              |
| blackList       | Array(String)     | **强制禁用** Promise 化的 API 名单                         | 否       | `[]`    | 即使在 usePromise: true 时，名单内的 API 也不会返回 Promise |
| ~~fallbackMap~~ | ~~Object~~        | ~~对于不支持的 API，允许配置一个映射表，接管不存在的 API~~ | ~~否~~   | ~~{}~~  | 已删除                                                      |
| custom          | Object            | 提供用户在各渠道下自定义 api 开放能力                      | 否       | `[]`    | 用于扩展或自定义特定平台下的 API 实现                       |

## 使用介绍 {#introduction}

### 普通形式 {#normal-form}

```js
import mpx from "@mpxjs/core"
import apiProxy from "@mpxjs/api-proxy"

mpx.use(apiProxy)

mpx.showModal({
  title: "标题",
  content: "这是一个弹窗",
  success(res) {
    if (res.cancel) {
      console.log("用户点击取消")
    }
  },
})
```

### usePromise

启用 `usePromise` 选项后，在 Promise 化规则范围内的异步 `API` 会返回 `Promise` 对象。部分小程序 `API`（如 `uploadFile`）的返回值本身具有特定意义（例如返回一个 `uploadTask` 对象用于监听上传进度或取消任务）。为了兼容这种情况，这些 `API` 的原始返回值会被挂载到返回的 `Promise` 对象的 `__returned` 属性上，开发者仍可正常访问和使用。

> \[!important] ⚠️ 注意
>
> * **与原生微信小程序差异**
>   * 在 `Mpx` 中，开启 `usePromise` 后，在 Promise 化规则范围内的异步 `API` 会返回 `Promise`，统一支持 `await` 或 `.then()` 语法（部分 API 因语义或命名规则默认不参与 Promise 化，见下文「whiteList 与 blackList」）。
>   * 而微信小程序原生环境中则存在差异：大部分接收 `success` 和 `fail` 回调的 `API` 已支持 `Promise` 化写法，**但存在个别特例——** 这些 `API` 虽然同样接收 `success` 和 `fail` 参数，却不支持 `promisify` 风格调用。
> * **混用风险**
>   * API 调用同时支持 `success/fail` 回调与 `Promise` 的 `then/catch` 写法，且两者两种方式可以共存使用。虽然支持共存，但还是**强烈建议开启 `usePromise` 后，支持 `promisify` 风格的 `API` 都走 `then/catch` 写法**以避免产生下面提示的第三项的影响
>   * 当同时使用时，若调用成功，`success` 回调与 `then` 方法会依次执行；若调用失败，`fail` 回调与 `catch` 方法会依次执行。
>   * 需注意：若仅使用了 `success/fail` 回调（未搭配 `then/catch`），当 API 调用失败时，由于没有 `catch` 捕获异常，会触发 `onUnhandledRejection` 事件。
> * **临时关闭 Promise 转换**
>   * 如仍需在某次调用中使用 `success/fail` 回调，且不希望触发因未捕获 `Promise` 错误而产生的警告，可通过传入 `usePromise: false` 选项临时关闭本次调用的 `Promise` 转换（默认为 `true`）。

```js
import mpx from "@mpxjs/core"
import apiProxy from "@mpxjs/api-proxy"

// 启用 Promise 风格
mpx.use(apiProxy, {
  usePromise: true,
  blackList: ["getSystemInfo"],
})

// 加入黑名单后，需要以 success/fail 方式调用
mpx.getSystemInfo({
  success(res) {
    console.log(res, "getSystemInfo success")
  },
  fail(err) {
    console.log(err, "getSystemInfo error")
  },
})
```

### whiteList 与 blackList {#whitelist-and-blacklist}

在 `usePromise: true` 时，除你在 `whiteList` / `blackList` 中的配置外，实现里还会按命名与语义过滤一部分 **默认不** 做 Promise 化的方法，例如：

* 名称以 `Sync` 结尾的同步风格 API；
* 名称以 `on`、`off` 开头的监听类 API；
* 名称匹配 `get*Manager` 的 API；
* 名称匹配 `create*` 的 API（`createBLEConnection`、`createBLEPeripheralServer` 等少数例外会参与 Promise 化）；
* 另有少量特殊 API（如 `nextTick`、`canIUse`、部分信息获取类方法等）在实现中固定不参与 Promise 化。

`whiteList` 中的名称会 **强制** 参与 Promise 化（可覆盖上述默认规则）；`blackList` 中的名称会与上述内置规则 **合并**，用于强制保持回调风格。

当平台侧新增了带 `success` / `fail` 的 API，而本地 `@mpxjs/api-proxy` 版本尚未跟进时，也可通过 `whiteList` / `blackList` 显式控制是否 Promise 化，减少行为不确定带来的问题。

### custom

为特定平台扩展自定义 API：

```js
import mpx from "@mpxjs/core"
import apiProxy from "@mpxjs/api-proxy"

// 启用 Promise 风格
mpx.use(apiProxy, {
  usePromise: true,
  custom: {
    ali: {
      // 支付宝小程序下扩展自定义 API
      myCustomMethod() {
        console.log("ali")
      },
    },
    ios: {
      // RN 下扩展自定义API
      myCustomMethod() {
        console.log("ios")
      },
    },
  },
})

if (__mpx_mode__ === "ali" || __mpx_mode__ === "ios") {
  mpx.myCustomMethod()
}
```

### 独立调用 {#standalone-call}

作为 Mpx 框架的内置能力，也支持独立调用，无需显式挂载在 Mpx 实例上

```js
import { getProxy } from "@mpxjs/api-proxy"
// 获取代理实例，与 mpx.use(apiProxy, options) 使用相同的 install 逻辑
const proxy = getProxy(options)

// 调用方式与原生 API 一致，代理层会自动处理跨平台转换
proxy.navigateTo({
  url: "/pages/test",
  success(res) {
    console.log(res)
  },
})
```

### 按需导入单个 API {#import-single-api}

除了使用完整的代理实例，也可以从 `@mpxjs/api-proxy` 中按需 **具名导入** 包内已实现并导出的 API（导出集合与 `getProxy()` 挂到目标上的方法一致）。未导出或未在本文档子页中出现的接口，通常表示尚未做跨端适配或需直接使用各端原生对象。

```js
// 直接导入所需的 API 方法
import { navigateTo } from "@mpxjs/api-proxy"

// 像使用原生 API 一样直接调用
navigateTo({
  url: "/pages/test",
  success(res) {
    console.log(res)
  },
})
```

---

---
url: /api-proxy/base/base64ToArrayBuffer.md
---
## mpx.base64ToArrayBuffer(string base64)

微信小程序从基础库 2.4.0 开始，该接口停止维护

将 Base64 字符串转成 ArrayBuffer 对象

支持情况： 微信、支付宝、web、RN

[参考文档](https://developers.weixin.qq.com/miniprogram/dev/api/base/wx.base64ToArrayBuffer.html)

### 参数 {#parameters}

**string base64**\
要转化成 ArrayBuffer 对象的 Base64 字符串

### 返回值 {#return-value}

**ArrayBuffer**\
ArrayBuffer 对象

### 示例代码 {#example-code}

```js
const base64 = 'CxYh'
const arrayBuffer = mpx.base64ToArrayBuffer(base64)
```

---

---
url: /api-proxy/base/arrayBufferToBase64.md
---
## mpx.arrayBufferToBase64(ArrayBuffer arrayBuffer)

微信小程序从基础库 2.4.0 开始，该接口停止维护

将 ArrayBuffer 对象转成 Base64 字符串

支持情况： 微信、支付宝、web、RN

[参考文档](https://developers.weixin.qq.com/miniprogram/dev/api/base/wx.arrayBufferToBase64.html)

### 参数 {#parameters}

**ArrayBuffer arrayBuffer**\
要转换成 Base64 字符串的 ArrayBuffer 对象

### 返回值 {#return-value}

**string**\
Base64 字符串

### 示例代码 {#example-code}

```js
const arrayBuffer = new Uint8Array([11, 22, 33])
const base64 = mpx.arrayBufferToBase64(arrayBuffer)
```

---

---
url: /api-proxy/base/canIUse.md
---
## mpx.canIUse(string schema)

判断当前环境是否支持指定的 API、对象或方法。

RN 支持情况：支持。RN 下使用静态能力表判断，不会为了检测能力而加载原生模块。

[参考文档](https://developers.weixin.qq.com/miniprogram/dev/api/base/wx.canIUse.html)

### 参数 {#parameters}

**string schema**\
API、对象或方法的能力描述，写法遵循小程序 `canIUse` 的 `schema` 约定。

RN 静态能力表只收录抹平层已有实际能力的内置 API、对象与方法，不收录 `envError`、空实现或明确未实现的兼容占位能力。该判断不会检测可选原生依赖是否安装、运行时权限是否授予，也不包含通过 `custom` 注入的业务 API。

### 返回值 {#return-value}

**boolean**\
支持返回 `true`，否则返回 `false`。

### 示例代码 {#example-code}

```js
mpx.canIUse('request') // true
mpx.canIUse('RequestTask.abort') // true
mpx.canIUse('RequestTask.onHeadersReceived') // false（RN 暂未实现）
mpx.canIUse('previewImage') // false（RN 暂未实现）
```

---

---
url: /api-proxy/base/system/getSystemInfo.md
---
## mpx.getSystemInfo(Object object)

微信小程序从基础库 2.20.1 开始，该接口停止维护

获取系统信息。

支持情况： 微信、支付宝、web、RN

[参考文档](https://developers.weixin.qq.com/miniprogram/dev/api/base/system/wx.getSystemInfo.html)

### 参数 {#parameters}

**Object object**

属性	类型	默认值	必填	说明
| 属性    | 类型     | 默认值 | 必填 | 说明                 |
| ------- | -------- | ------ | ---- | -------------------- |
| success | function |        | 否   | 接口调用成功的回调函数 |
| fail    | function |        | 否   | 接口调用失败的回调函数 |
| complete| function |        | 否   | 接口调用结束的回调函数（调用成功、失败都会执行） |

**object.success 回调函数**

**参数**

**Object res**

### 示例代码 {#example-code}

```js
mpx.getSystemInfo({
  success (res) {
    console.log(res.model)
    console.log(res.pixelRatio)
    console.log(res.windowWidth)
    console.log(res.windowHeight)
    console.log(res.language)
    console.log(res.version)
    console.log(res.platform)
  }
})
```

---

---
url: /api-proxy/base/system/getSystemInfoSync.md
---
## mpx.getSystemInfo(Object object)

微信小程序从基础库 2.20.1 开始，该接口停止维护

mpx.getSystemInfo 的同步版本。

支持情况： 微信、支付宝、web、RN

[参考文档](https://developers.weixin.qq.com/miniprogram/dev/api/base/system/wx.getSystemInfoSync.html)

### 示例代码 {#example-code}

```js
try {
  const res = mpx.getSystemInfoSync()
  console.log(res.model)
  console.log(res.pixelRatio)
  console.log(res.windowWidth)
  console.log(res.windowHeight)
  console.log(res.language)
  console.log(res.version)
  console.log(res.platform)
} catch (e) {
  // Do something when catch error
}

```

---

---
url: /api-proxy/base/system/getWindowInfo.md
---
## mpx.getWindowInfo()

获取窗口信息

支持情况： 微信、支付宝、web、RN

[参考文档](https://developers.weixin.qq.com/miniprogram/dev/api/base/system/wx.getWindowInfo.html)

### 参数 {#parameters}

**Object**

### 示例代码 {#example-code}

```js
const deviceInfo = mpx.getDeviceInfo()

console.log(deviceInfo.abi)
console.log(deviceInfo.benchmarkLevel)
console.log(deviceInfo.brand)
console.log(deviceInfo.model)
console.log(deviceInfo.platform)
console.log(deviceInfo.system)
```

---

---
url: /api-proxy/base/system/getDeviceInfo.md
---
## mpx.getDeviceInfo()

获取设备基础信息

支持情况： 微信、支付宝、web、RN

[参考文档](https://developers.weixin.qq.com/miniprogram/dev/api/base/system/wx.getDeviceInfo.html)

### 参数 {#parameters}

**Object**

| 属性           | 类型   | 说明                                                                                                   | 最低版本 | 支付宝 | RN | web |
|----------------|--------|------------------------------------------------------------------------------------------------------|----------|--------|----|-----|
| abi            | string | 应用（微信APP）二进制接口类型（仅 Android 支持）                                                      |          | ✓ | ✗  | ✗   |
| deviceAbi      | string | 设备二进制接口类型（仅 Android 支持）                                                                 | 2.25.1   | ✗      | ✗  | ✗   |
| benchmarkLevel | number | 设备性能等级（仅 Android 支持）。取值为：-2 或 0（该设备无法运行小游戏），-1（性能未知），>=1（设备性能值，该值越高，设备性能越好，目前最高不到50）注意：从基础库3.4.5开始，本返回值停止维护，请使用wx.getDeviceBenchmarkInfo获取设备性能等级 |          | ✗      | ✗  | ✗   |
| brand          | string | 设备品牌                                                                                                |          | ✓ | ✓ | ✓ |
| model          | string | 设备型号。新机型刚推出一段时间会显示unknown，微信会尽快进行适配。                                      |          | ✓ | ✓ | ✓ |
| system         | string | 操作系统及版本                                                                                         |          | ✓ | ✓ | ✓ |
| platform       | string | 客户端平台                                                                                             |          | ✓ | ✓ | ✓ |
| cpuType        | string | 设备 CPU 型号（仅 Android 支持）（Tips: GPU 型号可通过 WebGLRenderingContext.getExtension('WEBGL\_debug\_renderer\_info') 来获取） | 2.29.0   | ✗      | ✗  | ✗   |
| memorySize     | string | 设备内存大小，单位为 MB                                                                                | 2.30.0   | ✗      | ✗  | ✗   |

### 示例代码 {#example-code}

```js
const deviceInfo = mpx.getDeviceInfo()

console.log(deviceInfo.abi)
console.log(deviceInfo.benchmarkLevel)
console.log(deviceInfo.brand)
console.log(deviceInfo.model)
console.log(deviceInfo.platform)
console.log(deviceInfo.system)
```

---

---
url: /api-proxy/base/app/life-cycle/getEnterOptionsSync.md
---
## mpx.getEnterOptionsSync()

获取应用启动时的参数

支持情况： 微信、支付宝、RN、web

[参考文档](https://developers.weixin.qq.com/miniprogram/dev/platform-capabilities/miniapp/api/diffapi/getEnterOptionsSync.html)

### 返回值 {#return-value}

| 参数   | 类型   | 说明                                   |
| ------ | ------ | -------------------------------------- |
| path   | string | 启动的路径 (代码包路径)                |
| scene  | string | 启动的场景值，返回 1168，含义可查看场景值 |
| query  | number | 启动的 query 参数                      |

---

---
url: /api-proxy/base/app/life-cycle/getLaunchOptionsSync.md
---
## mpx.getLaunchOptionsSync()

获取本次应用启动时的参数

支持情况： 微信、支付宝、RN、web

[参考文档](https://developers.weixin.qq.com/miniprogram/dev/platform-capabilities/miniapp/api/diffapi/getLaunchOptionsSync.html)

### 返回值 {#return-value}

| 参数   | 类型   | 说明                                   |
| ------ | ------ | -------------------------------------- |
| path   | string | 启动的路径 (代码包路径)                |
| scene  | string | 启动的场景值，返回 1168，含义可查看场景值 |
| query  | number | 启动的 query 参数                      |

---

---
url: /api-proxy/base/app/app-event/onAppShow.md
---
## mpx.onAppShow(function listener)

监听小程序切前台事件。该事件与 App.onShow 的回调参数一致。

支持情况： 微信、支付宝、RN、web

[参考文档](https://developers.weixin.qq.com/miniprogram/dev/api/base/app/app-event/wx.onAppShow.html)

### 参数 {#parameters}

**function listener**

小程序切前台事件的监听函数

**参数**

**Object options**\
启动参数

### 示例代码 {#example-code}

```js
const onAppShowHandler = (res) => {
  console.log('onAppShow:', res)
};

mpx.onAppShow(onAppShowHandler)

```

---

---
url: /api-proxy/base/app/app-event/onAppHide.md
---
## mpx.onAppHide(function listener)

监听小程序切后台事件。该事件与 App.onHide 的回调参数一致。

支持情况： 微信、支付宝、RN、web

[参考文档](https://developers.weixin.qq.com/miniprogram/dev/api/base/app/app-event/wx.onAppHide.html)

### 参数 {#parameters}

**function listener**

小程序切前台事件的监听函数

**参数**

**Object options**\
启动参数

---

---
url: /api-proxy/base/app/app-event/offAppShow.md
---
## mpx.offAppShow(function listener)

移除小程序切前台事件的监听函数

支持情况： 微信、支付宝、RN、web

[参考文档](https://developers.weixin.qq.com/miniprogram/dev/api/base/app/app-event/wx.offAppShow.html)

### 参数 {#parameters}

**function listener**

onAppShow 传入的监听函数。不传此参数则移除所有监听函数(支付宝除外)。

### 示例代码 {#example-code}

```js
const listener = function (res) { console.log(res) }

mpx.onAppShow(listener)
mpx.offAppShow(listener)
```

---

---
url: /api-proxy/base/app/app-event/offAppHide.md
---
## mpx.offAppHide(function listener)

移除小程序切后台事件的监听函数

支持情况： 微信、支付宝、RN、web

[参考文档](https://developers.weixin.qq.com/miniprogram/dev/api/base/app/app-event/wx.offAppShow.html)

### 参数 {#parameters}

**function listener**

onAppHide 传入的监听函数。不传此参数则移除所有监听函数(支付宝除外)。

### 示例代码 {#example-code}

```js
const listener = function (res) { console.log(res) }

mpx.onAppHide(listener)
mpx.offAppHide(listener)
```

---

---
url: /api-proxy/base/app/app-event/onError.md
---
## mpx.onError(function listener)

监听小程序错误事件。如脚本错误或 API 调用报错等。该事件与 App.onError 的回调时机与参数一致。

支持情况： 微信、支付宝、RN、web

[参考文档](https://developers.weixin.qq.com/miniprogram/dev/api/base/app/app-event/wx.onError.html)

### 参数 {#parameters}

**function listener**

小程序错误事件的监听函数

**参数**

**object error**\
错误

| 属性 | 类型 | 说明 |
| --- | --- | --- |
| message | string | 错误信息，包含堆栈 |

---

---
url: /api-proxy/base/app/app-event/offError.md
---
## mpx.offError(function listener)

移除小程序错误事件的监听函数

支持情况： 微信、支付宝、RN、web

[参考文档](https://developers.weixin.qq.com/miniprogram/dev/api/base/app/app-event/wx.offError.html)

### 参数 {#parameters}

**function listener**

onError 传入的监听函数。不传此参数则移除所有监听函数(支付宝除外)。

### 示例代码 {#example-code}

```js
const listener = function (res) { console.log(res) }

mpx.onError(listener)
mpx.offError(listener) // 需传入与监听时同一个的函数对象
```

---

---
url: /api-proxy/base/app/app-event/onUnhandledRejection.md
---
## mpx.onUnhandledRejection(function listener)

监听未处理的 Promise 拒绝事件。该事件与 App.onUnhandledRejection 的回调时机与参数一致。

支持情况： 微信、支付宝、RN、web

[参考文档](https://developers.weixin.qq.com/miniprogram/dev/api/base/app/app-event/wx.onUnhandledRejection.html)

### 参数 {#parameters}

**function listener**

未处理的 Promise 拒绝事件的监听函数

**参数**

**Object res**

| 属性 | 类型 | 说明 |
| --- | --- | --- |
| reason | string | 拒绝原因，一般是一个 Error 对象 |
| promise | Promise.\<any> | 被拒绝的 Promise 对象 |

---

---
url: /api-proxy/base/app/app-event/offUnhandledRejection.md
---
## mpx.offLazyLoadError(function listener)

移除未处理的 Promise 拒绝事件的监听函数

支持情况： 微信、支付宝、RN、web

[参考文档](https://developers.weixin.qq.com/miniprogram/dev/api/base/app/app-event/wx.offUnhandledRejection.html)

### 参数 {#parameters}

**function listener**

onUnhandledRejection 传入的监听函数。不传此参数则移除所有监听函数(支付宝除外)。

### 示例代码 {#example-code}

```js
const listener = function (res) { console.log(res) }

mpx.onUnhandledRejection(listener)
mpx.offUnhandledRejection(listener) // 需传入与监听时同一个的函数对象
```

---

---
url: /api-proxy/base/app/app-event/onLazyLoadError.md
---
## mpx.onLazyLoadError(function listener)

监听小程序异步组件加载失败事件。

支持情况： 微信、支付宝、RN、web

[参考文档](https://developers.weixin.qq.com/miniprogram/dev/api/base/app/app-event/wx.onLazyLoadError.html)

### 参数 {#parameters}

**function listener**

小程序异步组件加载失败事件的监听函数

**参数**

**Object res**

| 属性 | 类型 | 说明 |
| --- | --- | --- |
| type | string | 'subpackage' 失败类型 |
| subpackage | Array | 异步组件所属的分包 |
| errMsg | string | 详细信息 |

---

---
url: /api-proxy/base/app/app-event/offLazyLoadError.md
---
## mpx.offLazyLoadError(function listener)

移除小程序异步组件加载失败事件的监听函数

支持情况： 微信、支付宝、RN、web

[参考文档](https://developers.weixin.qq.com/miniprogram/dev/api/base/app/app-event/wx.offLazyLoadError.html)

### 参数 {#parameters}

**function listener**

onLazyLoadError 传入的监听函数。不传此参数则移除所有监听函数(支付宝除外)。

### 示例代码 {#example-code}

```js
const listener = function (res) { console.log(res) }

mpx.onLazyLoadError(listener)
mpx.offLazyLoadError(listener) // 需传入与监听时同一个的函数对象
```

---

---
url: /api-proxy/route/navigateTo.md
---
## mpx.navigateTo(Object object)

保留当前页面，跳转到应用内的某个页面。

支持情况： 微信、支付宝、RN、web

[参考文档](https://developers.weixin.qq.com/miniprogram/dev/api/route/wx.navigateTo.html)

### 参数 {#parameters}

**Object object**

| 属性         | 类型     | 默认值 | 必填 | 说明 | 支付宝 | RN | web |
|--------------|----------|--------|------|------|--------|------------|-----|
| url          | string   |        | 是   | 需要跳转的应用内非 tabBar 的页面的路径 (代码包路径), 路径后可以带参数。参数与路径之间使用 ? 分隔，参数键与参数值用 = 相连，不同参数用 & 分隔；如 'path?key=value\&key2=value2' | ✓ | ✓ | ✓ |
| events       | Object   |        | 否   | 页面间通信接口，用于监听被打开页面发送到当前页面的数据。基础库 2.7.3 开始支持。 | ✓ | ✓ | ✓ |
| routeType    | string   |        | 否   | 2.29.2 自定义路由类型，相关文档 自定义路由 | ✗ | ✗ | ✗ |
| routeConfig  | Object   |        | 否   | 3.4.0 自定义路由配置，相关文档 自定义路由 | ✗ | ✗ | ✗ |
| routeOptions | Object   |        | 否   | 3.4.0 自定义路由参数，相关文档 自定义路由 | ✗ | ✗ | ✗ |
| success      | function |        | 否   | 接口调用成功的回调函数 | ✓ | ✓ | ✓ |
| fail         | function |        | 否   | 接口调用失败的回调函数 | ✓ | ✓ | ✓ |
| complete     | function |        | 否   | 接口调用结束的回调函数（调用成功、失败都会执行） | ✓ | ✓ | ✓ |

**object.success 回调函数**

**参数**

**Object res**

| 属性         | 类型         | 说明                     |
|--------------|--------------|--------------------------|
| eventChannel | EventChannel | 和被打开页面进行通信     |

### 示例代码 {#example-code}

```js
mpx.navigateTo({
  url: 'test?id=1',
  events: {
    // 为指定事件添加一个监听器，获取被打开页面传送到当前页面的数据
    acceptDataFromOpenedPage: function(data) {
      console.log(data)
    },
    someEvent: function(data) {
      console.log(data)
    }
    ...
  },
  success: function(res) {
    // 通过eventChannel向被打开页面传送数据
    res.eventChannel.emit('acceptDataFromOpenerPage', { data: 'test' })
  }
})

```

---

---
url: /api-proxy/route/redirectTo.md
---
## mpx.redirectTo(Object object)

关闭当前页面，跳转到应用内的某个页面。但是不允许跳转到 tabbar 页面。

支持情况： 微信、支付宝、RN、web

[参考文档](https://developers.weixin.qq.com/miniprogram/dev/api/route/wx.redirectTo.html)

### 参数 {#parameters}

**Object object**

| 属性      | 类型     | 默认值 | 必填 | 说明 |
|-----------|----------|--------|------|------|
| url       | string   |        | 是   | 需要跳转的应用内非 tabBar 的页面的路径 (代码包路径), 路径后可以带参数。参数与路径之间使用 ? 分隔，参数键与参数值用 = 相连，不同参数用 & 分隔；如 'path?key=value\&key2=value2' |
| success   | function |        | 否   | 接口调用成功的回调函数 |
| fail      | function |        | 否   | 接口调用失败的回调函数 |
| complete  | function |        | 否   | 接口调用结束的回调函数（调用成功、失败都会执行） |

### 示例代码 {#example-code}

```js
mpx.redirectTo({
  url: 'test?id=1'
})
```

---

---
url: /api-proxy/route/switchTab.md
---
## mpx.switchTab(Object object)

跳转到 tabBar 页面，并关闭其他所有非 tabBar 页面

支持情况： 微信、支付宝、web

> RN 平台当前不支持该 API；调用时会通过 `envError` 报告环境不支持，`mpx.canIUse('switchTab')` 返回 `false`。

[参考文档](https://developers.weixin.qq.com/miniprogram/dev/api/route/wx.switchTab.html)

### 参数 {#parameters}

**Object object**

| 属性      | 类型     | 默认值 | 必填 | 说明 |
|-----------|----------|--------|------|------|
| url       | string   |        | 是   | 需要跳转的 tabBar 页面的路径 (代码包路径)（需在 app.json 的 tabBar 字段定义的页面），路径后不能带参数。 |
| success   | function |        | 否   | 接口调用成功的回调函数 |
| fail      | function |        | 否   | 接口调用失败的回调函数 |
| complete  | function |        | 否   | 接口调用结束的回调函数（调用成功、失败都会执行） |

### 示例代码 {#example-code}

```js
// app.json
{
  "tabBar": {
    "list": [{
      "pagePath": "index",
      "text": "首页"
    },{
      "pagePath": "other",
      "text": "其他"
    }]
  }
}
```

```js
mpx.switchTab({
  url: '/index'
})
```

---

---
url: /api-proxy/route/reLaunch.md
---
## mpx.reLaunch(Object object)

关闭所有页面，打开到应用内的某个页面

支持情况： 微信、支付宝、RN、web

[参考文档](https://developers.weixin.qq.com/miniprogram/dev/api/route/wx.reLaunch.html)

### 参数 {#parameters}

**Object object**

| 属性      | 类型     | 默认值 | 必填 | 说明 |
|-----------|----------|--------|------|------|
| url       | string   |        | 是   | 需要跳转的应用内页面路径 (代码包路径)，路径后可以带参数。参数与路径之间使用?分隔，参数键与参数值用=相连，不同参数用&分隔；如 'path?key=value\&key2=value2' |
| success   | function |        | 否   | 接口调用成功的回调函数 |
| fail      | function |        | 否   | 接口调用失败的回调函数 |
| complete  | function |        | 否   | 接口调用结束的回调函数（调用成功、失败都会执行） |

> RN 平台成功回调参数的 `errMsg` 为 `reLaunch:ok`，失败回调参数的 `errMsg` 以 `reLaunch:fail` 开头。

### 示例代码 {#example-code}

```js
mpx.reLaunch({
  url: 'test?id=1'
})
```

---

---
url: /api-proxy/route/navigateBack.md
---
## mpx.navigateBack(Object object)

关闭当前页面，返回上一页面或多级页面。

支持情况： 微信、支付宝、RN、web

[参考文档](https://developers.weixin.qq.com/miniprogram/dev/api/route/wx.navigateBack.html)

### 参数 {#parameters}

**Object object**

| 属性      | 类型     | 默认值 | 必填 | 说明 |
|-----------|----------|--------|------|------|
| delta     | number   | 1      | 否   | 返回的页面数，如果 delta 大于现有页面数，则返回到页面栈中只剩一个页面为止。 |
| success   | function |        | 否   | 接口调用成功的回调函数 |
| fail      | function |        | 否   | 接口调用失败的回调函数 |
| complete  | function |        | 否   | 接口调用结束的回调函数（调用成功、失败都会执行） |

### 示例代码 {#example-code}

```js
mpx.navigateTo({
  url: 'B?id=1'
})

// 此处是B页面
mpx.navigateTo({
  url: 'C?id=1'
})

// 在C页面内 navigateBack，将返回A页面
mpx.navigateBack({
  delta: 2
})

```

---

---
url: /api-proxy/interface/interactive/showActionSheet.md
---
## mpx.showActionSheet(Object object)

显示操作菜单

支持情况： 微信、支付宝、web、RN

[参考文档](https://developers.weixin.qq.com/miniprogram/dev/api/ui/interaction/wx.showActionSheet.html)

### 参数 {#parameters}

**Object object**

| 属性 | 类型 | 默认值 | 必填 | 说明 | 微信最低版本 |
|------|------|--------|------|------|------------|
| alertText | string | - | 否 | 警示文案 | 2.14.0 |
| itemList | Array\<string> | - | 是 | 按钮的文字数组，数组长度最大为 6 | - |
| itemColor | string | #000000 | 否 | 按钮的文字颜色 | - |
| success | function | - | 否 | 接口调用成功的回调函数 | - |
| fail | function | - | 否 | 接口调用失败的回调函数 | - |
| complete | function | - | 否 | 接口调用结束的回调函数（调用成功、失败都会执行） | - |

**object.success 回调函数**

**参数**

**Object res**

| 属性 | 类型 | 说明 |
|------|------|------|
| tapIndex | number | 用户点击的按钮序号，从上到下的顺序，从0开始 |

### 示例代码 {#example-code}

```js
mpx.showActionSheet({
  itemList: ['A', 'B', 'C'],
  success (res) {
    console.log(res.tapIndex)
  },
  fail (res) {
    console.log(res.errMsg)
  }
})

```

---

---
url: /api-proxy/interface/interactive/showModal.md
---
## mpx.showModal(Object object)

显示模态对话框

支持情况： 微信、支付宝、web、RN

[参考文档](https://developers.weixin.qq.com/miniprogram/dev/api/ui/interaction/wx.showModal.html)

### 参数 {#parameters}

**Object object**

| 属性            | 类型     | 默认值   | 必填 | 说明                                         | 最低版本 | 支付宝 | RN | web |
|-----------------|----------|----------|------|----------------------------------------------|----------|--------|------------|-----|
| title           | string   |          | 否   | 提示的标题                                   |          | ✓ | ✓ | ✓ |
| content         | string   |          | 否   | 提示的内容                                   |          | ✓ | ✓ | ✓ |
| showCancel      | boolean  | true     | 否   | 是否显示取消按钮                             |          | ✓ | ✓ | ✓ |
| cancelText      | string   | 取消     | 否   | 取消按钮的文字，最多 4 个字符                |          | ✓ | ✓ | ✓ |
| cancelColor     | string   | #000000  | 否   | 取消按钮的文字颜色，必须是 16 进制格式的颜色字符串 |          | ✓ | ✓ | ✓ |
| confirmText     | string   | 确定     | 否   | 确认按钮的文字，最多 4 个字符                |          | ✓ | ✓ | ✓ |
| confirmColor    | string   | #576B95  | 否   | 确认按钮的文字颜色，必须是 16 进制格式的颜色字符串 |          | ✓ | ✓ | ✓ |
| editable        | boolean  | false    | 否   | 是否显示输入框                               | 2.17.1   | ✓ | ✓ | ✗ |
| placeholderText | string   |          | 否   | 显示输入框时的提示文本                       | 2.17.1   | ✓ | ✓ | ✗ |
| success         | function |          | 否   | 接口调用成功的回调函数                       |          | ✓ | ✓ | ✓ |
| fail            | function |          | 否   | 接口调用失败的回调函数                       |          | ✓ | ✓ | ✓ |
| complete        | function |          | 否   | 接口调用结束的回调函数（调用成功、失败都会执行） |          | ✓ | ✓ | ✓ |

**object.success 回调函数**

**参数**

**Object res**

| 属性   | 类型   | 说明                                                         | 最低版本 |
|--------|--------|--------------------------------------------------------------|----------|
| content | string | editable 为 true 时，用户输入的文本                          |          |
| confirm | boolean | 为 true 时，表示用户点击了确定按钮                           |          |
| cancel  | boolean | 为 true 时，表示用户点击了取消（用于 Android 区分关闭方式） | 1.1.0    |

### 示例代码 {#example-code}

```js
mpx.showModal({
  title: '提示',
  content: '这是一个模态弹窗',
  success (res) {
    if (res.confirm) {
      console.log('用户点击确定')
    } else if (res.cancel) {
      console.log('用户点击取消')
    }
  }
})

```

---

---
url: /api-proxy/interface/interactive/enableAlertBeforeUnload.md
---
## mpx.disableAlertBeforeUnload(Object object)

关闭小程序页面返回询问对话框。

支持情况： 微信、支付宝

[参考文档](https://developers.weixin.qq.com/miniprogram/dev/api/ui/interaction/wx.disableAlertBeforeUnload.html)

### 参数 {#parameters}

**Object object**

| 属性    | 类型     | 默认值 | 必填 | 说明                 |
| ------- | -------- | ------ | ---- | -------------------- |
| success | function |        | 否   | 接口调用成功的回调函数 |
| fail    | function |        | 否   | 接口调用失败的回调函数 |
| complete| function |        | 否   | 接口调用结束的回调函数（调用成功、失败都会执行） |

### 示例代码 {#example-code}

```js
mpx.disableAlertBeforeUnload({
  success: function(res) {
    console.log(res);
  },
  fail: function(err) {
    console.log(err);
  }
})
```

---

---
url: /api-proxy/interface/interactive/disableAlertBeforeUnload.md
---
## mpx.enableAlertBeforeUnload(Object object)

开启小程序页面返回询问对话框。

支持情况： 微信、支付宝

[参考文档](https://developers.weixin.qq.com/miniprogram/dev/api/ui/interaction/wx.enableAlertBeforeUnload.html)

### 参数 {#parameters}

**Object object**

| 属性    | 类型     | 默认值 | 必填 | 说明                 |
| ------- | -------- | ------ | ---- | -------------------- |
| message | string   |        | 是   | 询问对话框内容       |
| success | function |        | 否   | 接口调用成功的回调函数 |
| fail    | function |        | 否   | 接口调用失败的回调函数 |
| complete| function |        | 否   | 接口调用结束的回调函数（调用成功、失败都会执行） |

### 示例代码 {#example-code}

```js
mpx.enableAlertBeforeUnload({
  success: function(res) {
    console.log(res);
  },
  fail: function(err) {
    console.log(err);
  }
})
```

---

---
url: /api-proxy/interface/interactive/showToast.md
---
## mpx.showToast(Object object)

显示消息提示框

支持情况： 微信、支付宝、web、RN

[参考文档](https://developers.weixin.qq.com/miniprogram/dev/api/ui/interaction/wx.showToast.html)

> RN 环境会校验 `title`：缺失或类型不是 `string` 时进入 `fail`，并同时执行 `complete`。

### 参数 {#parameters}

**Object object**

### 示例代码 {#example-code}

```js
mpx.showToast({
  title: '成功',
  icon: 'success',
  duration: 2000
})
```

---

---
url: /api-proxy/interface/interactive/hideToast.md
---
## mpx.hideToast(Object object)

隐藏消息提示框

支持情况： 微信、支付宝、web、RN

[参考文档](https://developers.weixin.qq.com/miniprogram/dev/api/ui/interaction/wx.hideToast.html)

### 参数 {#parameters}

**Object object**

| 属性        | 类型     | 默认值 | 必填 | 说明                                         | 最低版本 | 支付宝 | RN | web |
|-------------|----------|--------|------|----------------------------------------------|----------|--------|------------|-----|
| noConflict  | boolean  | false  | 否   | 目前 toast 和 loading 相关接口可以相互混用，此参数可用于取消混用特性 | 2.22.1    | ✗ | ✓ | ✗ |
| success     | function |        | 否   | 接口调用成功的回调函数                       |          | ✓ | ✓ | ✓ |
| fail        | function |        | 否   | 接口调用失败的回调函数                       |          | ✓ | ✓ | ✓ |
| complete    | function |        | 否   | 接口调用结束的回调函数（调用成功、失败都会执行） |          | ✓ | ✓ | ✓ |

---

---
url: /api-proxy/interface/interactive/showLoading.md
---
## mpx.showLoading(Object object)

显示 loading 提示框。需主动调用 mpx.hideLoading 才能关闭提示框

支持情况： 微信、支付宝、web、RN

[参考文档](https://developers.weixin.qq.com/miniprogram/dev/api/ui/interaction/wx.showLoading.html)

### 参数 {#parameters}

**Object object**

| 属性     | 类型     | 默认值 | 必填 | 说明                                   |
|----------|----------|--------|------|----------------------------------------|
| title    | string   |        | 是   | 提示的内容                             |
| mask     | boolean  | false  | 否   | 是否显示透明蒙层，防止触摸穿透         |
| success  | function |        | 否   | 接口调用成功的回调函数                 |
| fail     | function |        | 否   | 接口调用失败的回调函数                 |
| complete | function |        | 否   | 接口调用结束的回调函数（调用成功、失败都会执行） |

> RN 环境会校验 `title`：缺失或类型不是 `string` 时进入 `fail`，并同时执行 `complete`。

### 示例代码 {#example-code}

```js
mpx.showLoading({
  title: '加载中',
})

setTimeout(function () {
  mpx.hideLoading()
}, 2000)
```

---

---
url: /api-proxy/interface/interactive/hideLoading.md
---
## mpx.hideLoading(Object object)

隐藏 loading 提示框

支持情况： 微信、支付宝、web、RN

[参考文档](https://developers.weixin.qq.com/miniprogram/dev/api/ui/interaction/wx.hideLoading.html)

### 参数 {#parameters}

**Object object**

| 属性        | 类型     | 默认值 | 必填 | 说明                                               | 最低版本 |
|-------------|----------|--------|------|----------------------------------------------------|----------|
| noConflict  | boolean  | false  | 否   | 目前 toast 和 loading 相关接口可以相互混用，此参数可用于取消混用特性 | 2.22.1   |
| success     | function |        | 否   | 接口调用成功的回调函数                             |          |
| fail        | function |        | 否   | 接口调用失败的回调函数                             |          |
| complete    | function |        | 否   | 接口调用结束的回调函数（调用成功、失败都会执行）    |          |

---

---
url: /api-proxy/interface/navigation-bar/hideHomeButton.md
---
## mpx.hideHomeButton(Object object)

隐藏返回首页按钮。微信7.0.7版本起，当用户打开的小程序最底层页面是非首页时，默认展示“返回首页”按钮，开发者可在页面 onShow 中调用 hideHomeButton 进行隐藏。

支持情况： 微信、支付宝

[参考文档](https://developers.weixin.qq.com/miniprogram/dev/api/ui/navigation-bar/wx.hideHomeButton.html)

### 参数 {#parameters}

**Object object**

| 属性    | 类型     | 默认值 | 必填 | 说明                 |
| ------- | -------- | ------ | ---- | -------------------- |
| success | function |        | 否   | 接口调用成功的回调函数 |
| fail    | function |        | 否   | 接口调用失败的回调函数 |
| complete| function |        | 否   | 接口调用结束的回调函数（调用成功、失败都会执行） |

---

---
url: /api-proxy/interface/navigation-bar/setNavigationBarTitle.md
---
## mpx.setNavigationBarTitle(Object object)

动态设置当前页面的标题

支持情况： 微信、支付宝、RN、web

[参考文档](https://developers.weixin.qq.com/miniprogram/dev/api/ui/navigation-bar/wx.setNavigationBarTitle.html)

### 参数 {#parameters}

**Object object**

| 属性    | 类型     | 默认值 | 必填 | 说明                 |
| ------- | -------- | ------ | ---- | -------------------- |
| title   | string   |        | 是   | 页面标题             |
| success | function |        | 否   | 接口调用成功的回调函数 |
| fail    | function |        | 否   | 接口调用失败的回调函数 |
| complete| function |        | 否   | 接口调用结束的回调函数（调用成功、失败都会执行） |

### 示例代码 {#example-code}

```js
mpx.setNavigationBarTitle({
  title: '当前页面'
})
```

---

---
url: /api-proxy/interface/navigation-bar/setNavigationBarColor.md
---
## mpx.setNavigationBarColor(Object object)

设置页面导航条颜色

支持情况：微信、支付宝、RN、web

[参考文档](https://developers.weixin.qq.com/miniprogram/dev/api/ui/navigation-bar/wx.setNavigationBarColor.html)

### 参数 {#parameters}

**Object object**

> RN 会校验颜色参数：`frontColor` 仅接受 `#ffffff` / `#000000`，`backgroundColor` 接受 `#RGB` / `#RRGGBB` 格式。参数无效时触发 `fail` 与 `complete`，且不会修改导航栏配置。

### 示例代码 {#example-code}

```js
mpx.setNavigationBarColor({
  frontColor: '#ffffff',
  backgroundColor: '#ff0000',
  animation: {
    duration: 400,
    timingFunc: 'easeIn'
  }
})
```

---

---
url: /api-proxy/interface/tab-bar/hideTabBar.md
---
## mpx.hideTabBar(Object object)

隐藏 tabBar

支持情况： 微信、支付宝、web

[参考文档](https://developers.weixin.qq.com/miniprogram/dev/api/ui/tab-bar/wx.hideTabBar.html)

### 参数 {#parameters}

**Object object**

| 属性     | 类型     | 默认值 | 必填 | 说明                                   | 支付宝 | web |
|----------|----------|--------|------|----------------------------------------|--------|-----|
| animation| boolean  | false  | 否   | 是否需要动画效果                       | ✓ | ✗ |
| success  | function |        | 否   | 接口调用成功的回调函数                 | ✓ | ✓ |
| fail     | function |        | 否   | 接口调用失败的回调函数                 | ✓ | ✓ |
| complete | function |        | 否   | 接口调用结束的回调函数（成功或失败均执行） | ✓ | ✓ |

---

---
url: /api-proxy/interface/tab-bar/showTabBar.md
---
## mpx.showTabBar(Object object)

显示 tabBar

支持情况： 微信、支付宝、web

[参考文档](https://developers.weixin.qq.com/miniprogram/dev/api/ui/tab-bar/wx.showTabBar.html)

### 参数 {#parameters}

**Object object**

| 属性     | 类型     | 默认值 | 必填 | 说明                                   | 支付宝 | web |
|----------|----------|--------|------|----------------------------------------|--------|-----|
| animation| boolean  | false  | 否   | 是否需要动画效果                       | ✓ | ✗ |
| success  | function |        | 否   | 接口调用成功的回调函数                 | ✓ | ✓ |
| fail     | function |        | 否   | 接口调用失败的回调函数                 | ✓ | ✓ |
| complete | function |        | 否   | 接口调用结束的回调函数（成功或失败均执行） | ✓ | ✓ |

---

---
url: /api-proxy/interface/tab-bar/setTabBarStyle.md
---
## mpx.setTabBarStyle(Object object)

动态设置 tabBar 的整体样式

支持情况： 微信、支付宝、web

[参考文档](https://developers.weixin.qq.com/miniprogram/dev/api/ui/tab-bar/wx.setTabBarStyle.html)

### 参数 {#parameters}

**Object object**

属性	类型	默认值	必填	说明
| 属性            | 类型     | 默认值 | 必填 | 说明                                         |
|-----------------|----------|--------|------|----------------------------------------------|
| color           | string   |        | 否   | tab 上的文字默认颜色，HexColor               |
| selectedColor   | string   |        | 否   | tab 上的文字选中时的颜色，HexColor           |
| backgroundColor | string   |        | 否   | tab 的背景色，HexColor                       |
| borderStyle     | string   |        | 否   | tabBar上边框的颜色，仅支持 black/white        |
| success         | function |        | 否   | 接口调用成功的回调函数                       |
| fail            | function |        | 否   | 接口调用失败的回调函数                       |
| complete        | function |        | 否   | 接口调用结束的回调函数（调用成功、失败都会执行） |

### 示例代码 {#example-code}

```js
mpx.setTabBarStyle({
  color: '#FF0000',
  selectedColor: '#00FF00',
  backgroundColor: '#0000FF',
  borderStyle: 'white'
})
```

---

---
url: /api-proxy/interface/tab-bar/setTabBarItem.md
---
## mpx.setTabBarItem(Object object)

动态设置 tabBar 某一项的内容

支持情况： 微信、支付宝、web

[参考文档](https://developers.weixin.qq.com/miniprogram/dev/api/ui/tab-bar/wx.setTabBarItem.html)

### 参数 {#parameters}

**Object object**

| 属性             | 类型     | 默认值 | 必填 | 说明                                                                                   | 支付宝 | web |
|------------------|----------|--------|------|----------------------------------------------------------------------------------------|--------|-----|
| index            | number   |        | 是   | tabBar 的哪一项，从左边算起                                                           | ✓ | ✗ |
| text             | string   |        | 否   | tab 上的按钮文字                                                                      | ✓ | ✓ |
| iconPath         | string   |        | 否   | 图片路径，icon 大小限制为 40kb，建议尺寸为 81px \* 81px，当 postion 为 top 时，此参数无效 | ✓ | ✓ |
| selectedIconPath | string   |        | 否   | 选中时的图片路径，icon 大小限制为 40kb，建议尺寸为 81px \* 81px ，当 postion 为 top 时，此参数无效 | ✓ | ✓ |
| success          | function |        | 否   | 接口调用成功的回调函数                                                                | ✓ | ✓ |
| fail             | function |        | 否   | 接口调用失败的回调函数                                                                | ✓ | ✓ |
| complete         | function |        | 否   | 接口调用结束的回调函数（成功或失败均执行）                                             | ✓ | ✓ |

### 示例代码 {#example-code}

```js
mpx.setTabBarItem({
  index: 0,
  text: 'text',
  iconPath: '/path/to/iconPath',
  selectedIconPath: '/path/to/selectedIconPath'
})
```

---

---
url: /api-proxy/interface/pull-down-refresh/stopPullDownRefresh.md
---
## mpx.stopPullDownRefresh(Object object)

停止当前页面下拉刷新。

支持情况： 微信、支付宝、web

[参考文档](https://developers.weixin.qq.com/miniprogram/dev/api/ui/pull-down-refresh/wx.stopPullDownRefresh.html)

### 参数 {#parameters}

**Object object**

| 属性      | 类型      | 默认值 | 必填 | 说明                                                         |
|-----------|-----------|--------|------|--------------------------------------------------------------|
| success   | function  |        | 否   | 接口调用成功的回调函数                                       |
| fail      | function  |        | 否   | 接口调用失败的回调函数                                       |
| complete  | function  |        | 否   | 接口调用结束的回调函数（调用成功、失败都会执行）             |

### 示例代码 {#example-code}

```js
createPage({
  onPullDownRefresh () {
    mpx.stopPullDownRefresh()
  }
})
```

---

---
url: /api-proxy/interface/pull-down-refresh/startPullDownRefresh.md
---
## mpx.startPullDownRefresh(Object object)

开始下拉刷新。调用后触发下拉刷新动画，效果与用户手动下拉刷新一致。

支持情况： 微信、支付宝、web

[参考文档](https://developers.weixin.qq.com/miniprogram/dev/api/ui/pull-down-refresh/wx.startPullDownRefresh.html)

### 参数 {#parameters}

**Object object**

| 属性      | 类型      | 默认值 | 必填 | 说明                                                         |
|-----------|-----------|--------|------|--------------------------------------------------------------|
| success   | function  |        | 否   | 接口调用成功的回调函数                                       |
| fail      | function  |        | 否   | 接口调用失败的回调函数                                       |
| complete  | function  |        | 否   | 接口调用结束的回调函数（调用成功、失败都会执行）             |

### 示例代码 {#example-code}

```js
mpx.startPullDownRefresh()
```

---

---
url: /api-proxy/interface/scroll/pageScrollTo.md
---
## mpx.pageScrollTo(Object object)

将页面滚动到目标位置，支持选择器和滚动距离两种方式定位

支持情况： 微信、支付宝、RN、web

[参考文档](https://developers.weixin.qq.com/miniprogram/dev/api/ui/scroll/wx.pageScrollTo.html)

### 参数 {#parameters}

**Object object**

| 属性        | 类型     | 默认值 | 必填 | 说明                                                                 | 最低版本 | 支付宝 | web | RN |
|-------------|----------|--------|------|----------------------------------------------------------------------|----------|--------|-----|-----|
| scrollTop   | number   |        | 否   | 滚动到页面的目标位置，单位 px                                        |          | ✓ | ✓ | ✓ |
| duration    | number   | 300    | 否   | 滚动动画的时长，单位 ms                                             |          | ✓ | ✓ | ✓ |
| selector    | string   |        | 否   | 选择器                                                              | 2.7.3    | ✓ | ✓ | ✓ |
| offsetTop   | number   |        | 否   | 偏移距离，需要和 selector 参数搭配使用，可以滚动到 selector 加偏移距离的位置，单位 px | 2.23.1   | ✓ | ✗ | ✓ |
| success     | function |        | 否   | 接口调用成功的回调函数                                               |          | ✓ | ✓ | ✓ |
| fail        | function |        | 否   | 接口调用失败的回调函数                                               |          | ✓ | ✓ | ✓ |
| complete    | function |        | 否   | 接口调用结束的回调函数（调用成功、失败都会执行）                      |          | ✓ | ✓ | ✓ |

### 示例代码 {#example-code}

#### 使用 scrollTop 滚动到指定位置

```js
mpx.pageScrollTo({
  scrollTop: 0,
  duration: 300
})
```

#### 使用 selector 滚动到指定元素（小程序）

```xml
<view id="target-section">目标区域</view>
```

```js
mpx.pageScrollTo({
  selector: '#target-section',
  duration: 300
})
```

#### 使用 scrollTop 滚动到顶部（React Native）

::: warning React Native 平台特殊说明
在 React Native 平台上使用 `pageScrollTo` 时，需要在页面的 scroll-view 组件上声明固定的 `wx:ref="pageScrollView"`，框架将通过该固定 ref 定位滚动容器。
:::

```xml
<template>
  <view class="page">
    <!-- scroll-view 必须声明固定 ref 名称 pageScrollView -->
    <scroll-view wx:ref="pageScrollView" scroll-y="{{true}}" style="height: 100vh;">
      <view style="height: 500px;">顶部内容</view>
      <view style="height: 500px;">底部内容</view>
    </scroll-view>
  </view>
</template>

<script>
import { createPage } from '@mpxjs/core'

createPage({
  methods: {
    scrollToTop() {
      mpx.pageScrollTo({
        scrollTop: 0,
        duration: 300
      })
    }
  }
})
</script>
```

#### 使用 selector 滚动到指定元素（React Native）

```xml
<template>
  <view class="page">
    <!-- scroll-view 必须声明固定 ref 名称 pageScrollView -->
    <scroll-view wx:ref="pageScrollView" scroll-y="{{true}}" style="height: 100vh;">
      <view style="height: 500px;">顶部内容</view>

      <!-- 目标元素需要同时添加 id 和 wx:ref -->
      <view id="target-section" wx:ref style="height: 200px;">
        目标区域
      </view>

      <view style="height: 500px;">底部内容</view>
    </scroll-view>
  </view>
</template>

<script>
import { createPage } from '@mpxjs/core'

createPage({
  methods: {
    scrollToTarget() {
      mpx.pageScrollTo({
        selector: '#target-section',
        duration: 300,
        offsetTop: 10,  // 可选：偏移 10px
        success: () => {
          console.log('滚动成功')
        },
        fail: (err) => {
          console.error('滚动失败:', err)
        }
      })
    }
  }
})
</script>
```

### React Native 平台注意事项

#### 必需的配置

1. **scroll-view 必须声明固定 ref 名称 `pageScrollView`**

```xml
<!-- ✅ 正确 -->
<scroll-view wx:ref="pageScrollView" scroll-y="{{true}}">
  <!-- 内容 -->
</scroll-view>

<!-- ❌ 错误：缺少 wx:ref="pageScrollView" -->
<scroll-view scroll-y="{{true}}">
  <!-- 内容 -->
</scroll-view>
```

2. **使用 selector 时，目标元素必须同时有 id 和 wx:ref**

```xml
<!-- ✅ 正确：同时有 id 和 wx:ref -->
<view id="section-1" wx:ref>区域 1</view>

<!-- ❌ 错误：只有 id，没有 wx:ref -->
<view id="section-1">区域 1</view>
```

3. **启用滚动方向**

```xml
<!-- ✅ 正确：启用纵向滚动 -->
<scroll-view scroll-y="{{true}}">

<!-- ❌ 错误：没有启用滚动 -->
<scroll-view>
```

---

---
url: /api-proxy/interface/animation/createAnimation.md
---
## [Animation](https://developers.weixin.qq.com/miniprogram/dev/api/ui/animation/Animation.html) mpx.createAnimation(Object object)

创建一个动画实例 animation。调用实例的方法来描述动画。最后通过动画实例的 export 方法导出动画数据传递给组件的 animation 属性。

支持情况： 微信、支付宝、web、RN

[参考文档](https://developers.weixin.qq.com/miniprogram/dev/api/ui/animation/wx.createAnimation.html)

### 参数 {#parameters}

**Object object**

**返回值**

[Animation](https://developers.weixin.qq.com/miniprogram/dev/api/ui/animation/Animation.html)

---

---
url: /api-proxy/interface/custom-component/nextTick.md
---
## mpx.nextTick(function callback)

延迟一部分操作到下一个时间片再执行。

支持情况： 微信、支付宝、web、RN

[参考文档](https://developers.weixin.qq.com/miniprogram/dev/api/ui/custom-component/wx.nextTick.html)

### 参数 {#parameters}

**function callback**

---

---
url: /api-proxy/interface/menu/getMenuButtonBoundingClientRect.md
---
## mpx.getMenuButtonBoundingClientRect()

获取菜单按钮（右上角胶囊按钮）的布局位置信息。坐标信息以屏幕左上角为原点。

支持情况: 微信、支付宝、React Native

> **React Native 说明**: 由于 RN 应用没有微信的右上角胶囊按钮,该 API 会基于屏幕尺寸和安全区返回一个模拟的胶囊位置,可用于获取顶部导航区域的参考尺寸,保持代码兼容性。

[参考文档](https://developers.weixin.qq.com/miniprogram/dev/api/ui/menu/wx.getMenuButtonBoundingClientRect.html)

### 返回值 {#return-value}

**Object**\
菜单按钮的布局位置信息

| 属性  | 类型   | 说明                 |
| ----- | ------ | -------------------- |
| width | number | 宽度，单位：px       |
| height| number | 高度，单位：px       |
| top   | number | 上边界坐标，单位：px |
| right | number | 右边界坐标，单位：px |
| bottom| number | 下边界坐标，单位：px |
| left  | number | 左边界坐标，单位：px |

### 示例代码 {#example-code}

```js
const res = mpx.getMenuButtonBoundingClientRect()

console.log(res.width)
console.log(res.height)
console.log(res.top)
console.log(res.right)
console.log(res.bottom)
console.log(res.left)
```

---

---
url: /api-proxy/interface/window/onWindowResize.md
---
## mpx.onWindowResize(function listener)

监听窗口尺寸变化事件

支持情况： 微信、RN、web

[参考文档](https://developers.weixin.qq.com/miniprogram/dev/api/ui/window/wx.onWindowResize.html)

### 参数 {#parameters}

**function listener**\
窗口尺寸变化事件的监听函数

**参数**

**Object res**

### 示例代码 {#example-code}

---

---
url: /api-proxy/interface/window/offWindowResize.md
---
## mpx.offWindowResize(function listener)

移除窗口尺寸变化事件的监听函数

支持情况： 微信、RN、web

[参考文档](https://developers.weixin.qq.com/miniprogram/dev/api/ui/window/wx.offWindowResize.html)

### 参数 {#parameters}

**function listener**\
onWindowResize 传入的监听函数。不传此参数则移除所有监听函数。

### 示例代码 {#example-code}

```js
const listener = function (res) { console.log(res) }

mpx.onWindowResize(listener)
mpx.offWindowResize(listener) // 需传入与监听时同一个的函数对象
```

---

---
url: /api-proxy/network/request/request.md
---
## [RequestTask](https://developers.weixin.qq.com/miniprogram/dev/api/network/request/RequestTask.html) mpx.request(Object object)

发起 HTTPS 网络请求

支持情况： 微信、支付宝、RN、web

[参考文档](https://developers.weixin.qq.com/miniprogram/dev/api/network/request/wx.request.html)

### 参数 {#parameters}

**Object object**

**object.success 回调函数**

**参数**

**Object res**

**object.fail 回调函数**

**参数**

**Object err**

### 返回值 {#return-value}

[RequestTask](https://developers.weixin.qq.com/miniprogram/dev/api/network/request/RequestTask.html)

### 示例代码 {#example-code}

```js
mpx.request({
  url: 'example.php', //仅为示例，并非真实的接口地址
  data: {
    x: '',
    y: ''
  },
  header: {
    'content-type': 'application/json' // 默认值
  },
  success (res) {
    console.log(res.data)
  }
})
```

---

---
url: /api-proxy/network/download/downloadFile.md
---
## [DownloadTask](https://developers.weixin.qq.com/miniprogram/dev/api/network/download/DownloadTask.html) mpx.downloadFile(Object object)

下载文件资源到本地。客户端直接发起一个 HTTPS GET 请求，返回文件的本地临时路径 (本地路径)，单次下载允许的最大文件为 200MB。使用前请注意阅读相关说明。

注意：请在服务端响应的 header 中指定合理的 Content-Type 字段，以保证客户端正确处理文件类型。

支持情况： 微信、支付宝

[参考文档](https://developers.weixin.qq.com/miniprogram/dev/api/network/download/wx.downloadFile.html)

### 参数 {#parameters}

**Object object**

| 属性           | 类型     | 默认值 | 必填 | 说明                                                                                                                        | 最低版本 | 支付宝 |
| -------------- | -------- | ------ | ---- | --------------------------------------------------------------------------------------------------------------------------- | -------- | ------ |
| url            | string   |        | 是   | 下载资源的 url                                                                                                              |          | ✓ |
| header         | Object   |        | 否   | HTTP 请求的 Header，Header 中不能设置 Referer                                                                               |          | ✓ |
| timeout        | number   | 60000  | 否   | 超时时间，单位为毫秒，默认值为 60000 即一分钟。                                                                             | 2.10.0   | ✓ |
| filePath       | string   |        | 否   | 指定文件下载后存储的路径 (本地路径)                                                                                          | 1.8.0    | ✓ |
| enableProfile  | boolean  | true   | 否   | 是否开启 profile。iOS 和 Android 端默认开启，其他端暂不支持。开启后可在接口回调的 res.profile 中查看性能调试信息。           |          | ✗ |
| enableHttp2    | boolean  | false  | 否   | 是否开启 http2                                                                                                              | 2.10.4   | ✗ |
| enableQuic     | boolean  | false  | 否   | 是否开启 Quic/h3 协议（iOS 微信目前使用 gQUIC-Q43；Android 微信在 v8.0.54 前使用 gQUIC-Q43，v8.0.54 开始使用 IETF QUIC，即 h3 协议；PC微信使用 IETF QUIC，即 h3 协议） | 2.10.4   | ✗ |
| success        | function |        | 否   | 接口调用成功的回调函数                                                                                                      |          | ✓ |
| fail           | function |        | 否   | 接口调用失败的回调函数                                                                                                      |          | ✓ |
| complete       | function |        | 否   | 接口调用结束的回调函数（调用成功、失败都会执行）                                                                            |          | ✓ |

**object.success 回调函数**

**参数**

**Object res**

### 返回值 {#return-value}

[DownloadTask](https://developers.weixin.qq.com/miniprogram/dev/api/network/download/DownloadTask.html)

### 示例代码 {#example-code}

```js
mpx.downloadFile({
  url: 'https://example.com/audio/123', //仅为示例，并非真实的资源
  success (res) {
    // 只要服务器有响应数据，就会把响应内容写入文件并进入 success 回调，业务需要自行判断是否下载到了想要的内容
    if (res.statusCode === 200) {
      mpx.playVoice({
        filePath: res.tempFilePath
      })
    }
  }
})
```

---

---
url: /api-proxy/network/upload/uploadFile.md
---
## [UploadTask](https://developers.weixin.qq.com/miniprogram/dev/api/network/upload/wx.uploadFile.html) mpx.uploadFile(Object object)

将本地资源上传到服务器。客户端发起一个 HTTPS POST 请求，其中 content-type 为 multipart/form-data

支持情况： 微信、支付宝

[参考文档](https://developers.weixin.qq.com/miniprogram/dev/api/network/upload/wx.uploadFile.html)

### 参数 {#parameters}

**Object object**

| 属性           | 类型     | 默认值 | 必填 | 说明                                                                                                                        | 最低版本 | 支付宝 |
| -------------- | -------- | ------ | ---- | --------------------------------------------------------------------------------------------------------------------------- | -------- | ------ |
| url            | string   |        | 是   | 开发者服务器地址                                                                                                           |          | ✓ |
| filePath       | string   |        | 是   | 要上传文件资源的路径 (本地路径)                                                                                            |          | ✓ |
| name           | string   |        | 是   | 文件对应的 key，开发者在服务端可以通过这个 key 获取文件的二进制内容                                                        |          | ✓ |
| header         | Object   |        | 否   | HTTP 请求 Header，Header 中不能设置 Referer                                                                                |          | ✓ |
| formData       | Object   |        | 否   | HTTP 请求中其他额外的 form data                                                                                            |          | ✓ |
| timeout        | number   |        | 否   | 超时时间，单位为毫秒                                                                                                       | 2.10.0   | ✓ |
| enableProfile  | boolean  | true   | 否   | 是否开启 profile。iOS 和 Android 端默认开启，其他端暂不支持。开启后可在接口回调的 res.profile 中查看性能调试信息。           | 3.5.0    | ✗ |
| enableHttp2    | boolean  | false  | 否   | 是否开启 http2                                                                                                             | 2.10.4   | ✗ |
| enableQuic     | boolean  | false  | 否   | 是否开启 Quic/h3 协议（iOS 微信目前使用 gQUIC-Q43；Android 微信在 v8.0.54 前使用 gQUIC-Q43，v8.0.54 开始使用 IETF QUIC，即 h3 协议；PC微信使用 IETF QUIC，即 h3 协议） | 2.10.4   | ✗ |
| success        | function |        | 否   | 接口调用成功的回调函数                                                                                                      |          | ✓ |
| fail           | function |        | 否   | 接口调用失败的回调函数                                                                                                      |          | ✓ |
| complete       | function |        | 否   | 接口调用结束的回调函数（调用成功、失败都会执行）                                                                            |          | ✓ |

**object.success 回调函数**

**参数**

**Object res**

### 返回值 {#return-value}

[UploadTask](https://developers.weixin.qq.com/miniprogram/dev/api/network/upload/wx.uploadFile.html)

### 示例代码 {#example-code}

```js
mpx.chooseImage({
  success (res) {
    const tempFilePaths = res.tempFilePaths
    mpx.uploadFile({
      url: 'https://example.weixin.qq.com/upload', //仅为示例，非真实的接口地址
      filePath: tempFilePaths[0],
      name: 'file',
      formData: {
        'user': 'test'
      },
      success (res){
        const data = res.data
        //do something
      }
    })
  }
})
```

---

---
url: /api-proxy/network/websocket/connectSocket.md
---
## [SocketTask](https://developers.weixin.qq.com/miniprogram/dev/api/network/websocket/SocketTask.html) mpx.connectSocket(Object object)

创建一个 WebSocket 连接。

支持情况： 微信、支付宝

[参考文档](https://developers.weixin.qq.com/miniprogram/dev/api/network/upload/wx.uploadFile.html)

### 参数 {#parameters}

**Object object**

| 属性                | 类型           | 默认值 | 必填 | 说明                                         | 最低版本 | 支付宝 | RN | web |
| ------------------- | -------------- | ------ | ---- | -------------------------------------------- | -------- | ------ | ---------- | --- |
| url                 | string         |        | 是   | 开发者服务器 wss 接口地址                    |          | ✓ | ✓ | ✓ |
| header              | Object         |        | 否   | HTTP Header，Header 中不能设置 Referer        |          | ✓ | ✗ | ✗ |
| protocols           | Array.\<string> |        | 否   | 子协议数组                                   | 1.4.0    | ✓ | ✓ | ✓ |
| tcpNoDelay          | boolean        | false  | 否   | 建立 TCP 连接的时候的 TCP\_NODELAY 设置        | 2.4.0    | ✗ | ✗ | ✗ |
| perMessageDeflate   | boolean        | false  | 否   | 是否开启压缩扩展                             | 2.8.0    | ✗ | ✗ | ✗ |
| timeout             | number         |        | 否   | 超时时间，单位为毫秒                         | 2.10.0   | ✓ | ✗ | ✗ |
| forceCellularNetwork| boolean        | false  | 否   | 强制使用蜂窝网络发送请求                     | 2.29.0   | ✗ | ✗ | ✗ |
| success             | function       |        | 否   | 接口调用成功的回调函数                       |          | ✓ | ✓ | ✓ |
| fail                | function       |        | 否   | 接口调用失败的回调函数                       |          | ✓ | ✓ | ✓ |
| complete            | function       |        | 否   | 接口调用结束的回调函数（调用成功、失败都会执行） |          | ✓ | ✓ | ✓ |

### 返回值 {#return-value}

[SocketTask](https://developers.weixin.qq.com/miniprogram/dev/api/network/websocket/SocketTask.html)

---

---
url: /api-proxy/payment/requestPayment.md
---
## mpx.requestPayment(Object object)

发起微信/支付宝支付。

支持情况： 微信、支付宝

[参考文档](https://developers.weixin.qq.com/miniprogram/dev/api/payment/wx.requestPayment.html)

### 参数 {#parameters}

**Object object**

### 示例代码 {#example-code}

```js

mpx.requestPayment({
  timeStamp: '',
  nonceStr: '',
  package: '',
  signType: 'MD5',
  paySign: '',
  success (res) { },
  fail (res) { }
})
```

---

---
url: /api-proxy/storage/setStorage.md
---
## mpx.setStorage(Object object)

将数据存储在本地缓存中指定的 key 中。

支持情况： 微信、支付宝、RN、web

[参考文档](https://developers.weixin.qq.com/miniprogram/dev/api/storage/wx.getStorage.html)

### 参数 {#parameters}

**Object object**

属性	类型	默认值	必填	说明	最低版本
| 属性      | 类型     | 默认值 | 必填 | 说明 | 最低版本 | 支付宝 | RN | web |
| --------- | -------- | ------ | ---- | ------------------------------------------------------------ | --------- | ------ | ---- | --- |
| key       | string   |        | 是   | 本地缓存中指定的 key                                         |           | ✓ | ✓ | ✓ |
| data      | any      |        | 是   | 需要存储的内容。只支持原生类型、Date、及能够通过JSON.stringify序列化的对象。 |           | ✓ | ✓ | ✓ |
| encrypt   | Boolean  | false  | 否   | 是否开启加密存储。只有异步的 setStorage 接口支持开启加密存储。开启后，将会对 data 使用 AES128 加密，接口回调耗时将会增加。若开启加密存储，setStorage 和 getStorage 需要同时声明 encrypt 的值为 true。此外，由于加密后的数据会比原始数据膨胀1.4倍，因此开启 encrypt 的情况下，单个 key 允许存储的最大数据长度为 0.7MB，所有数据存储上限为 7.1MB | 2.21.3   | ✗ | ✗ | ✗ |
| success   | function |        | 否   | 接口调用成功的回调函数                                       |           | ✓ | ✓ | ✓ |
| fail      | function |        | 否   | 接口调用失败的回调函数                                       |           | ✓ | ✓ | ✓ |
| complete  | function |        | 否   | 接口调用结束的回调函数（调用成功、失败都会执行）              |           | ✓ | ✓ | ✓ |

### 示例代码 {#example-code}

```js
mpx.setStorage({
  key:"key",
  data:"value"
})
```

---

---
url: /api-proxy/storage/setStorageSync.md
---
## mpx.setStorageSync(string key, any data)

将数据存储在本地缓存中指定的 key 中。

支持情况： 微信、支付宝、web

[参考文档](https://developers.weixin.qq.com/miniprogram/dev/api/storage/wx.setStorageSync.html)

### 示例代码 {#example-code}

```js
try {
  mpx.setStorageSync('key', 'value')
} catch (e) { }
```

---

---
url: /api-proxy/storage/getStorage.md
---
## mpx.getStorage(Object object)

从本地缓存中异步获取指定 key 的内容。

支持情况： 微信、支付宝、RN、web

[参考文档](https://developers.weixin.qq.com/miniprogram/dev/api/storage/wx.getStorage.html)

### 参数 {#parameters}

**Object object**

| 属性    | 类型     | 默认值 | 必填 | 说明                                                                                                                        | 最低版本 |
| ------- | -------- | ------ | ---- | --------------------------------------------------------------------------------------------------------------------------- | -------- |
| key     | string   |        | 是   | 本地缓存中指定的 key                                                                                                        |          |
| encrypt | Boolean  | false  | 否   | 是否开启加密存储。只有异步的 getStorage 接口支持开启加密存储。开启后，将会对 data 使用 AES128 解密，接口回调耗时将会增加。若开启加密存储，setStorage 和 getStorage 需要同时声明 encrypt 的值为 true | 2.21.3   |
| success | function |        | 否   | 接口调用成功的回调函数                                                                                                      |          |
| fail    | function |        | 否   | 接口调用失败的回调函数                                                                                                      |          |
| complete| function |        | 否   | 接口调用结束的回调函数（调用成功、失败都会执行）                                                                            |          |

**object.success 回调函数**

**参数**

**Object res**

| 属性 | 类型 | 说明         |
| ---- | ---- | ------------ |
| data | any  | key对应的内容 |

### 示例代码 {#example-code}

```js
mpx.getStorage({
  key: 'key',
  success (res) {
    console.log(res.data)
  }
})
```

---

---
url: /api-proxy/storage/getStorageSync.md
---
## mpx.getStorageSync(string key)

从本地缓存中同步获取指定 key 的内容。

支持情况： 微信、支付宝、web

[参考文档](https://developers.weixin.qq.com/miniprogram/dev/api/storage/wx.getStorageSync.html)

### 示例代码 {#example-code}

```js
try {
  var value = mpx.getStorageSync('key')
  if (value) {
    // Do something with return value
  }
} catch (e) {
  // Do something when catch error
}
```

---

---
url: /api-proxy/storage/removeStorage.md
---
## mpx.removeStorage(Object object)

从本地缓存中移除指定 key。

支持情况： 微信、支付宝、RN、web

[参考文档](https://developers.weixin.qq.com/miniprogram/dev/api/storage/wx.removeStorage.html)

### 参数 {#parameters}

**Object object**

属性	类型	默认值	必填	说明
| 属性    | 类型     | 默认值 | 必填 | 说明                 |
| ------- | -------- | ------ | ---- | -------------------- |
| key     | string   |        | 是   | 本地缓存中指定的 key |
| success | function |        | 否   | 接口调用成功的回调函数 |
| fail    | function |        | 否   | 接口调用失败的回调函数 |
| complete| function |        | 否   | 接口调用结束的回调函数（调用成功、失败都会执行） |

### 示例代码 {#example-code}

```js
mpx.removeStorage({
  key: 'key',
  success (res) {
    console.log(res)
  }
})
```

---

---
url: /api-proxy/storage/removeStorageSync.md
---
## mpx.removeStorageSync(string key)

从本地缓存中移除指定 key，mpx.removeStorage 的同步版本。

支持情况： 微信、支付宝、web

[参考文档](https://developers.weixin.qq.com/miniprogram/dev/api/storage/wx.removeStorageSync.html)

### 示例代码 {#example-code}

```js
try {
  mpx.removeStorageSync('key')
} catch (e) {
  // Do something when catch error
}
```

---

---
url: /api-proxy/storage/clearStorage.md
---
## mpx.clearStorage(Object object)

清理本地数据缓存。

支持情况： 微信、支付宝、RN、web

[参考文档](https://developers.weixin.qq.com/miniprogram/dev/api/storage/wx.clearStorage.html)

### 参数 {#parameters}

**Object object**

| 属性    | 类型     | 默认值 | 必填 | 说明                 |
| ------- | -------- | ------ | ---- | -------------------- |
| success | function |        | 否   | 接口调用成功的回调函数 |
| fail    | function |        | 否   | 接口调用失败的回调函数 |
| complete| function |        | 否   | 接口调用结束的回调函数（调用成功、失败都会执行） |

### 示例代码 {#example-code}

```js
mpx.clearStorage()
```

---

---
url: /api-proxy/storage/clearStorageSync.md
---
## mpx.clearStorageSync()

清理本地数据缓存，mpx.clearStorage 的同步版本。

支持情况： 微信、支付宝、web

[参考文档](https://developers.weixin.qq.com/miniprogram/dev/api/storage/wx.clearStorageSync.html)

### 示例代码 {#example-code}

```js
try {
  mpx.clearStorageSync()
} catch(e) {
  // Do something when catch error
}
```

---

---
url: /api-proxy/storage/getStorageInfo.md
---
## mpx.getStorageInfo(Object object)

异步获取当前storage的相关信息。

支持情况： 微信、支付宝、RN、web

[参考文档](https://developers.weixin.qq.com/miniprogram/dev/api/storage/wx.getStorageInfo.html)

### 参数 {#parameters}

**Object object**

| 属性    | 类型     | 默认值 | 必填 | 说明                 |
| ------- | -------- | ------ | ---- | -------------------- |
| success | function |        | 否   | 接口调用成功的回调函数 |
| fail    | function |        | 否   | 接口调用失败的回调函数 |
| complete| function |        | 否   | 接口调用结束的回调函数（调用成功、失败都会执行） |

**object.success 回调函数**

**参数**

**Object res**

| 属性       | 类型           | 说明                           | 支付宝 | RN | web |
| ---------- | -------------- | ------------------------------ | ------ | ---------- | --- |
| keys       | Array\<string> | 当前 storage 中所有的 key      | ✓ | ✓ | ✓ |
| currentSize| number         | 当前占用的空间大小, 单位 KB    | ✓ | ✗ | ✗ |
| limitSize  | number         | 限制的空间大小，单位 KB         | ✓ | ✗ | ✗ |

### 示例代码 {#example-code}

```js
mpx.getStorageInfo({
  success (res) {
    console.log(res.keys)
    console.log(res.currentSize)
    console.log(res.limitSize)
  }
})
```

---

---
url: /api-proxy/storage/getStorageInfoSync.md
---
## mpx.getStorageInfoSync()

异步获取当前storage的相关信息，mpx.getStorageInfo 的同步版本。

支持情况： 微信、支付宝、web

[参考文档](https://developers.weixin.qq.com/miniprogram/dev/api/storage/wx.getStorageInfoSync.html)

### 返回值 {#return-value}

**Object object**

属性	类型	说明
| 属性       | 类型                | 说明                           |
| 属性       | 类型                | 说明                           | 支付宝 | web |
| ---------- | ------------------- | ------------------------------ | ------ | --- |
| keys       | Array\<string>    | 当前 storage 中所有的 key      | ✓ | ✓ |
| currentSize| number              | 当前占用的空间大小, 单位 KB    | ✓ | ✗ |
| limitSize  | number              | 限制的空间大小，单位 KB         | ✓ | ✗ |

### 示例代码 {#example-code}

```js
try {
  const res = mpx.getStorageInfoSync()
  console.log(res.keys)
  console.log(res.currentSize)
  console.log(res.limitSize)
} catch (e) {
  // Do something when catch error
}
```

---

---
url: /api-proxy/canvas/canvasToTempFilePath.md
---
## mpx.canvasToTempFilePath(Object object, Object this)

把当前画布指定区域的内容导出生成指定大小的图片。在 draw() 回调里调用该方法才能保证图片导出成功。

支持情况： 微信、支付宝

| 属性       | 类型     | 默认值                | 必填 | 说明                                                                          | 最低版本 |
| ---------- | -------- | --------------------- | ---- | ----------------------------------------------------------------------------- | -------- |
| x          | number   | 0                     | 否   | 指定的画布区域的左上角横坐标                                                  | 1.2.0    |
| y          | number   | 0                     | 否   | 指定的画布区域的左上角纵坐标                                                  | 1.2.0    |
| width      | number   | canvas 宽度 - x       |      | 指定的画布区域的宽度                                                          | 1.2.0    |
| height     | number   | canvas 高度 - y       | 否   | 指定的画布区域的高度                                                          | 1.2.0    |
| destWidth  | number   | width × 屏幕像素密度  | 否   | 输出的图片的宽度                                                              | 1.2.0    |
| destHeight | number   | height × 屏幕像素密度 | 否   | 输出的图片的高度                                                              | 1.2.0    |
| canvasId   | string   |                       | 否   | 画布标识，传入 canvas 组件的 canvas-id                                        |          |
| canvas     | Object   |                       | 否   | 画布标识，传入 canvas 组件实例（canvas type="2d" 时使用该属性）。             |          |
| fileType   | string   | png                   | 否   | 目标文件的类型，合法值：`png`、`jpg`                                          | 1.7.0    |
| quality    | number   |                       | 否   | 图片的质量，目前仅对 jpg 有效。取值范围为 (0, 1]，不在范围内时当作 1.0 处理。 | 1.7.0    |
| success    | function |                       | 否   | 接口调用成功的回调函数                                                        |          |
| fail       | function |                       | 否   | 接口调用失败的回调函数                                                        |          |
| complete   | function |                       | 否   | 接口调用结束的回调函数（调用成功、失败都会执行）                              |          |

### object.success 回调函数 {#object-success-callback}

### 参数 {#parameters}

**Object res**

| 属性         | 类型   | 说明                          |
| ------------ | ------ | ----------------------------- |
| tempFilePath | string | 生成文件的临时路径 (本地路径) |

**Object this**\
在自定义组件下，当前组件实例的 this，以操作组件内 canvas 组件

### 示例代码 {#example-code}

```js
mpx.canvasToTempFilePath({
  x: 100,
  y: 200,
  width: 50,
  height: 50,
  destWidth: 100,
  destHeight: 100,
  canvasId: "myCanvas",
  success(res) {
    console.log(res.tempFilePath)
  },
})
```

---

---
url: /api-proxy/canvas/canvasGetImageData.md
---
## mpx.canvasGetImageData(Object object, Object this)

获取 canvas 区域隐含的像素数据。

支持情况： 微信、支付宝

[参考文档](https://developers.weixin.qq.com/miniprogram/dev/api/canvas/wx.canvasGetImageData.html)

### 参数 {#parameters}

**Object object**

| 属性 | 类型 | 默认值 | 必填 | 说明 |
| --- | --- | --- | --- | --- |
| canvasId | string | - | 是 | 画布标识，传入 canvas 组件的 canvas-id 属性 |
| x | number | - | 是 | 将要被提取的图像数据矩形区域的左上角横坐标 |
| y | number | - | 是 | 将要被提取的图像数据矩形区域的左上角纵坐标 |
| width | number | - | 是 | 将要被提取的图像数据矩形区域的宽度 |
| height | number | - | 是 | 将要被提取的图像数据矩形区域的高度 |
| success | function | - | 否 | 接口调用成功的回调函数 |
| fail | function | - | 否 | 接口调用失败的回调函数 |
| complete | function | - | 否 | 接口调用结束的回调函数（调用成功、失败都会执行） |

### object.success 回调函数 {#object-success-callback}

### 参数 {#success-parameters}

**Object res**
| 属性 | 类型 | 说明 |
| --- | --- | --- |
| width | number | 图像数据矩形的宽度 |
| height | number | 图像数据矩形的高度 |
| data | Uint8ClampedArray | 图像像素点数据，一维数组，每四项表示一个像素点的 rgba |

**Object this**\
在自定义组件下，当前组件实例的this，以操作组件内 canvas 组件

### 示例代码 {#example-code}

```js
mpx.canvasGetImageData({
  canvasId: 'myCanvas',
  x: 0,
  y: 0,
  width: 100,
  height: 100,
  success(res) {
    console.log(res.width) // 100
    console.log(res.height) // 100
    console.log(res.data instanceof Uint8ClampedArray) // true
    console.log(res.data.length) // 100 * 100 * 4
  }
})
```

---

---
url: /api-proxy/media/audio/createInnerAudioContext.md
---
## [InnerAudioContext](https://developers.weixin.qq.com/miniprogram/dev/api/media/audio/InnerAudioContext.html) mpx.createInnerAudioContext(Object object)

创建内部 audio 上下文 InnerAudioContext 对象。

支持情况： 微信、支付宝、web

[参考文档](https://developers.weixin.qq.com/miniprogram/dev/api/media/audio/wx.createInnerAudioContext.html)

### 参数 {#parameters}

**Object object**

| 属性 | 类型 | 默认值 | 必填 | 说明 | 最低版本 | 支付宝 | web |
| --- | --- | --- | --- | --- | --- | --- | --- |
| useWebAudioImplement | boolean | false | 否 | 是否使用 WebAudio 作为底层音频驱动，默认关闭。对于短音频、播放频繁的音频建议开启此选项，开启后将获得更优的性能表现。由于开启此选项后也会带来一定的内存增长，因此对于长音频建议关闭此选项。 | 2.19.0 | **✗** | **✗** |

### 返回值 {#return-value}

[InnerAudioContext](https://developers.weixin.qq.com/miniprogram/dev/api/media/audio/InnerAudioContext.html)

### 注意事项 {#notes}

InnerAudioContext 音频资源不会自动释放，因此如果不再需要使用音频，请及时调用 InnerAudioContext.destroy() 释放资源，避免内存泄漏。

---

---
url: /api-proxy/media/image/previewImage.md
---
## mpx.previewImage(Object object)

在新页面中全屏预览图片。预览的过程中用户可以进行保存图片、发送给朋友等操作。

支持情况： 微信、支付宝、web

[参考文档](https://developers.weixin.qq.com/miniprogram/dev/api/media/image/wx.previewImage.htmll)

### 参数 {#parameters}

**Object object**

### 示例代码 {#example-code}

```js
mpx.previewImage({
  current: '', // 当前显示图片的http链接
  urls: [] // 需要预览的图片http链接列表
})
```

---

---
url: /api-proxy/media/image/compressImage.md
---
## mpx.compressImage(Object object)

压缩图片接口，可选压缩质量。iOS 仅支持压缩 JPG 格式图片。

支持情况： 微信、支付宝

[参考文档](https://developers.weixin.qq.com/miniprogram/dev/api/media/image/wx.compressImage.html)

### 参数 {#parameters}

**Object object**

| 属性              | 类型     | 默认值 | 必填 | 说明                                                                 | 最低版本 |
| ----------------- | -------- | ------ | ---- | -------------------------------------------------------------------- | -------- |
| src               | string   |        | 是   | 图片路径，图片的路径，支持本地路径、代码包路径                        |          |
| quality           | number   | 80     | 否   | 压缩质量，范围0～100，数值越小，质量越低，压缩率越高（仅对jpg有效）。 |          |
| compressedWidth   | number   |        | 否   | 压缩后图片的宽度，单位为px，若不填写则默认以compressedHeight为准等比缩放。 | 2.26.0   |
| compressedHeight  | number   |        | 否   | 压缩后图片的高度，单位为px，若不填写则默认以compressedWidth为准等比缩放 | 2.26.0   |
| success           | function |        | 否   | 接口调用成功的回调函数                                               |          |
| fail              | function |        | 否   | 接口调用失败的回调函数                                               |          |
| complete          | function |        | 否   | 接口调用结束的回调函数（调用成功、失败都会执行）                     |

**object.success 回调函数**

**参数**

**Object res**

| 属性         | 类型   | 说明                           |
| ------------ | ------ | ------------------------------ |
| tempFilePath | string | 压缩后图片的临时文件路径 (本地路径) |

### 示例代码 {#example-code}

```js
mpx.compressImage({
  src: '', // 图片路径
  quality: 80 // 压缩质量
})
```

---

---
url: /api-proxy/media/image/getImageInfo.md
---
## mpx.getImageInfo(Object object)

获取图片信息。网络图片需先配置download域名才能生效。

支持情况： 微信、支付宝、web、RN

[参考文档](https://developers.weixin.qq.com/miniprogram/dev/api/media/image/wx.getImageInfo.html)

### 参数 {#parameters}

**Object object**

| 属性     | 类型     | 默认值 | 必填 | 说明                                         |
| -------- | -------- | ------ | ---- | -------------------------------------------- |
| src      | string   |        | 是   | 图片的路径，支持网络路径、本地路径、代码包路径 |
| success  | function |        | 否   | 接口调用成功的回调函数                       |
| fail     | function |        | 否   | 接口调用失败的回调函数                       |
| complete | function |        | 否   | 接口调用结束的回调函数（调用成功、失败都会执行） |

**object.success 回调函数**

**参数**

**Object res**

### 示例代码 {#example-code}

```js
mpx.getImageInfo({
  src: 'images/a.jpg',
  success (res) {
    console.log(res.width)
    console.log(res.height)
  }
})

mpx.chooseImage({
  success (res) {
    mpx.getImageInfo({
      src: res.tempFilePaths[0],
      success (res) {
        console.log(res.width)
        console.log(res.height)
      }
    })
  }
})
```

---

---
url: /api-proxy/media/video/chooseMedia.md
---
## mpx.chooseMedia(Object object)

拍摄或从手机相册中选择图片或视频。

支持情况： 微信

[参考文档](https://developers.weixin.qq.com/miniprogram/dev/api/media/video/wx.chooseMedia.html)

### 参数 {#parameters}

**Object object**

**object.success 回调函数**

**参数**

**Object res**

### 示例代码 {#example-code}

```js
mpx.chooseMedia({
  count: 9,
  mediaType: ['image','video'],
  sourceType: ['album', 'camera'],
  maxDuration: 30,
  camera: 'back',
  success(res) {
    console.log(res.tempFiles[0].tempFilePath)
    console.log(res.tempFiles[0].size)
  }
})
```

---

---
url: /api-proxy/location/getLocation.md
---
## mpx.getLocation(Object object)

获取当前的地理位置、速度。当用户离开小程序后，此接口无法调用。

支持情况： 微信、支付宝、RN、web

[参考文档](https://developers.weixin.qq.com/miniprogram/dev/api/location/wx.getLocation.html)

### 参数 {#parameters}

**Object object**

| 属性                   | 类型     | 默认值 | 必填 | 说明                                                                 | 最低版本 | 支付宝 | RN | Web |
| ---------------------- | -------- | ------ | ---- | -------------------------------------------------------------------- | -------- | ------ |----|-----|
| type                   | string   | wgs84  | 否   | wgs84 返回 gps 坐标，gcj02 返回可用于 wx.openLocation 的坐标         |          | ✓ | ✗ | ✗ |
| altitude               | boolean  | false  | 否   | 传入 true 会返回高度信息，由于获取高度需要较高精确度，会减慢接口返回速度 | 1.6.0    | ✗ | ✗ | ✗ |
| isHighAccuracy         | boolean  | false  | 否   | 开启高精度定位                                                      | 2.9.0    | ✗ | ✓ | ✓ |
| highAccuracyExpireTime | number   |        | 否   | 高精度定位超时时间(ms)，指定时间内返回最高精度，该值3000ms以上高精度定位才有效果 | 2.9.0    | ✗ | ✗ | ✗ |
| success                | function |        | 否   | 接口调用成功的回调函数                                               |          | ✓ | ✓ | ✓ |
| fail                   | function |        | 否   | 接口调用失败的回调函数                                               |          | ✓ | ✓ | ✓ |
| complete               | function |        | 否   | 接口调用结束的回调函数（调用成功、失败都会执行）                     |          | ✓ | ✓ | ✓ |

**object.success 回调函数**

**参数**

**Object res**

| 属性              | 类型   | 说明                                                         | 最低版本 | 支付宝 | RN | Web |
| ----------------- | ------ | ------------------------------------------------------------ | -------- | ------ |----|-----|
| latitude          | number | 纬度，范围为 -90~90，负数表示南纬                            |          | ✓ | ✓ | ✓ |
| longitude         | number | 经度，范围为 -180~180，负数表示西经                          |          | ✓ | ✓ | ✓ |
| speed             | number | 速度，单位 m/s                                               |          | ✗ | ✓ | ✓ |
| accuracy          | number | 位置的精确度，反应与真实位置之间的接近程度，可以理解成10即与真实位置相差10m，越小越精确 |          | ✓ | ✓ | ✓ |
| altitude          | number | 高度，单位 m                                                 | 1.2.0    | ✓ | ✓ | ✓ |
| verticalAccuracy  | number | 垂直精度，单位 m（Android 无法获取，返回 0）                 | 1.2.0    | ✓ | ✓ | ✗ |
| horizontalAccuracy| number | 水平精度，单位 m                                             | 1.2.0    | ✓ | ✗ | ✗ |

### 示例代码 {#example-code}

```js
mpx.getLocation({
 type: 'wgs84',
 success (res) {
   const latitude = res.latitude
   const longitude = res.longitude
   const speed = res.speed
   const accuracy = res.accuracy
 }
})
```

---

---
url: /api-proxy/location/chooseLocation.md
---
## mpx.chooseLocation(Object object)

打开地图选择位置。

支持情况： 微信、支付宝

[参考文档](https://developers.weixin.qq.com/miniprogram/dev/api/location/wx.chooseLocation.html)

### 参数 {#parameters}

**Object object**

| 属性      | 类型     | 默认值 | 必填 | 说明                                 | 最低版本 |
| --------- | -------- | ------ | ---- | ------------------------------------ | -------- |
| latitude  | number   |        | 否   | 目标地纬度                           | 2.9.0    |
| longitude | number   |        | 否   | 目标地经度                           | 2.9.0    |
| success   | function |        | 否   | 接口调用成功的回调函数               |          |
| fail      | function |        | 否   | 接口调用失败的回调函数               |          |
| complete  | function |        | 否   | 接口调用结束的回调函数（调用成功、失败都会执行） |          |

**object.success 回调函数**

**参数**

**Object res**

| 属性      | 类型   | 说明                                                                 |
| --------- | ------ | -------------------------------------------------------------------- |
| name      | string | 位置名称                                                             |
| address   | string | 详细地址                                                             |
| latitude  | number | 纬度，浮点数，范围为-90~90，负数表示南纬。使用 gcj02 国测局坐标系     |
| longitude | number | 经度，浮点数，范围为-180~180，负数表示西经。使用 gcj02 国测局坐标系   |

---

---
url: /api-proxy/location/openLocation.md
---
## mpx.openLocation(Object object)

使用微信内置地图查看位置

支持情况： 微信、支付宝

[参考文档](https://developers.weixin.qq.com/miniprogram/dev/api/location/wx.chooseLocation.html)

### 参数 {#parameters}

**Object object**

| 属性      | 类型     | 默认值           | 必填 | 说明                                         |
| --------- | -------- | ---------------- | ---- | -------------------------------------------- |
| latitude  | number   |                  | 是   | 纬度，范围为-90~90，负数表示南纬。使用 gcj02 国测局坐标系 |
| longitude | number   |                  | 是   | 经度，范围为-180~180，负数表示西经。使用 gcj02 国测局坐标系 |
| scale     | number   | 微信(18)支付宝(15) | 否   | 缩放比例，范围5~18                          |
| name      | string   |                  | 否   | 位置名                                      |
| address   | string   |                  | 否   | 地址的详细说明                              |
| success   | function |                  | 否   | 接口调用成功的回调函数                      |
| fail      | function |                  | 否   | 接口调用失败的回调函数                      |
| complete  | function |                  | 否   | 接口调用结束的回调函数（调用成功、失败都会执行） |

### 示例代码 {#example-code}

```js
mpx.getLocation({
 type: 'gcj02', //返回可以用于wx.openLocation的经纬度
 success (res) {
   const latitude = res.latitude
   const longitude = res.longitude
   mpx.openLocation({
     latitude,
     longitude,
     scale: 18
   })
 }
})
```

---

---
url: /api-proxy/location/onLocationChange.md
---
## mpx.onLocationChange(function listener)

监听实时地理位置变化事件，需结合 wx.startLocationUpdateBackground、wx.startLocationUpdate使用。

支持情况： 微信

[参考文档](https://developers.weixin.qq.com/miniprogram/dev/api/location/wx.onLocationChange.html)

### 参数 {#parameters}

**function listener**\
实时地理位置变化事件的监听函数

**参数**

**Object res**

| 属性              | 类型   | 说明                                                         | 最低版本 |
| ----------------- | ------ | ------------------------------------------------------------ | -------- |
| latitude          | number | 纬度，范围为 -90~90，负数表示南纬。使用 gcj02 国测局坐标系    |          |
| longitude         | number | 经度，范围为 -180~180，负数表示西经。使用 gcj02 国测局坐标系  |          |
| speed             | number | 速度，单位 m/s                                               |          |
| accuracy          | number | 位置的精确度                                                 |          |
| altitude          | number | 高度，单位 m                                                 | 1.2.0    |
| verticalAccuracy  | number | 垂直精度，单位 m（Android 无法获取，返回 0）                 | 1.2.0    |
| horizontalAccuracy| number | 水平精度，单位 m                                             | 1.2.0    |

### 示例代码 {#example-code}

```js
const _locationChangeFn = function(res) {
  console.log('location change', res)
 }
 mpx.onLocationChange(_locationChangeFn)
 mpx.offLocationChange(_locationChangeFn)
```

---

---
url: /api-proxy/location/offLocationChange.md
---
## mpx.offLocationChange(function listener)

移除实时地理位置变化事件的监听函数

支持情况： 微信

[参考文档](https://developers.weixin.qq.com/miniprogram/dev/api/location/wx.offLocationChange.html)

### 参数 {#parameters}

**function listener**\
onLocationChange 传入的监听函数。不传此参数则移除所有监听函数。

### 示例代码 {#example-code}

```js
const listener = function (res) { console.log(res) }

mpx.onLocationChange(listener)
mpx.offLocationChange(listener) // 需传入与监听时同一个的函数对象
```

---

---
url: /api-proxy/location/startLocationUpdate.md
---
## mpx.startLocationUpdate(Object object)

开启小程序进入前台时接收位置消息。

支持情况： 微信

[参考文档](https://developers.weixin.qq.com/miniprogram/dev/api/location/wx.startLocationUpdate.html)

### 参数 {#parameters}

**Object object**

| 属性     | 类型     | 默认值      | 必填 | 说明                                         |
| -------- | -------- | ----------- | ---- | -------------------------------------------- |
| type     | string   | 坐标，gcj02 | 否   | wgs84 返回 gps 坐标，gcj02 返回可用于 wx.openLocation 的坐标 |
| success  | function |             | 否   | 接口调用成功的回调函数                       |
| fail     | function |             | 否   | 接口调用失败的回调函数                       |
| complete | function |             | 否   | 接口调用结束的回调函数（调用成功、失败都会执行） |

---

---
url: /api-proxy/location/stopLocationUpdate.md
---
## mpx.stopLocationUpdate(Object object)

关闭监听实时位置变化，前后台都停止消息接收

支持情况： 微信

[参考文档](https://developers.weixin.qq.com/miniprogram/dev/api/location/wx.stopLocationUpdate.html)

### 参数 {#parameters}

**Object object**

| 属性     | 类型     | 默认值 | 必填 | 说明                                         |
| -------- | -------- | ------ | ---- | -------------------------------------------- |
| success  | function |        | 否   | 接口调用成功的回调函数                       |
| fail     | function |        | 否   | 接口调用失败的回调函数                       |
| complete | function |        | 否   | 接口调用结束的回调函数（调用成功、失败都会执行） |

---

---
url: /api-proxy/open-api/login/login.md
---
## mpx.login(Object object)

调用接口获取登录凭证（code）。

支持情况： 微信、支付宝

[参考文档](https://developers.weixin.qq.com/miniprogram/dev/api/open-api/login/wx.login.html)

### 参数 {#parameters}

**Object object**

| 属性     | 类型     | 默认值 | 必填 | 说明                                   | 最低版本 |
|----------|----------|--------|------|----------------------------------------|----------|
| timeout  | number   |        | 否   | 超时时间，单位ms                       | 1.9.90   |
| success  | function |        | 否   | 接口调用成功的回调函数                 |          |
| fail     | function |        | 否   | 接口调用失败的回调函数                 |          |
| complete | function |        | 否   | 接口调用结束的回调函数（成功或失败均执行） |          |

**object.success 回调函数**

**参数**

**Object res**

| 属性 | 类型   | 说明 |
|------|--------|------|
| code | string | 用户登录凭证（有效期五分钟）。开发者需要在开发者服务器后台调用 code2Session，使用 code 换取 openid、unionid、session\_key 等信息 |

**object.fail 回调函数**

**参数**

**Object err**

| 属性   | 类型   | 说明                                   | 最低版本 |
|--------|--------|----------------------------------------|----------|
| errMsg | String | 错误信息                               |          |
| errno  | Number | errno 错误码，错误码的详细说明参考 Errno错误码 | 2.24.0   |

### 示例代码 {#example-code}

```js

mpx.login({
  success (res) {
    if (res.code) {
      //发起网络请求
      mpx.request({
        url: 'https://example.com/onLogin',
        data: {
          code: res.code
        }
      })
    } else {
      console.log('登录失败！' + res.errMsg)
    }
  }
})
```

---

---
url: /api-proxy/open-api/login/checkSession.md
---
## mpx.checkSession(Object object)

检查登录态 session\_key 是否过期。

支持情况： 微信

[参考文档](https://developers.weixin.qq.com/miniprogram/dev/api/open-api/login/wx.checkSession.html)

### 参数 {#parameters}

**Object object**

| 属性     | 类型     | 默认值 | 必填 | 说明                                         |
| -------- | -------- | ------ | ---- | -------------------------------------------- |
| success  | function |        | 否   | 接口调用成功的回调函数                       |
| fail     | function |        | 否   | 接口调用失败的回调函数                       |
| complete | function |        | 否   | 接口调用结束的回调函数（调用成功、失败都会执行） |

### 示例代码 {#example-code}

```js
mpx.checkSession({
  success () {
    //session_key 未过期，并且在本生命周期一直有效
  },
  fail () {
    // session_key 已经失效，需要重新执行登录流程
    mpx.login() //重新登录
  }
})
```

---

---
url: /api-proxy/open-api/user-info/getUserInfo.md
---
## mpx.getUserInfo(Object object)

获取用户信息。

支持情况： 微信、支付宝

[参考文档](https://developers.weixin.qq.com/miniprogram/dev/api/open-api/user-info/wx.getUserInfo.html)

### 参数 {#parameters}

**Object object**

**object.success 回调函数**

**参数**

**Object res**

属性	类型	说明	最低版本
| 属性         | 类型     | 说明                                                                 | 最低版本 |
|--------------|----------|----------------------------------------------------------------------|----------|
| userInfo     | UserInfo | 用户信息对象，不包含 openid 等敏感信息                               |          |
| rawData      | string   | 不包括敏感信息的原始数据字符串，用于计算签名                         |          |
| signature    | string   | 使用 sha1( rawData + sessionkey ) 得到字符串，用于校验用户信息，详见 用户数据的签名验证和加解密 |          |
| encryptedData| string   | 包括敏感数据在内的完整用户信息的加密数据，详见 用户数据的签名验证和加解密 |          |
| iv           | string   | 加密算法的初始向量，详见 用户数据的签名验证和加解密                   |          |
| cloudID      | string   | 敏感数据对应的云 ID，开通云开发的小程序才会返回，可通过云调用直接获取开放数据，详细见云调用直接获取开放数据 | 2.7.0    |

### 示例代码 {#example-code}

```js
mpx.getUserInfo({
  success: function(res) {
    var userInfo = res.userInfo
    var nickName = userInfo.nickName
    var avatarUrl = userInfo.avatarUrl
    var gender = userInfo.gender //性别 0：未知、1：男、2：女
    var province = userInfo.province
    var city = userInfo.city
    var country = userInfo.country
  }
})
```

---

---
url: /api-proxy/open-api/setting/getSetting.md
---
## mpx.getSetting(Object object)

获取用户的当前设置。

支持情况： 微信、支付宝

[参考文档](https://developers.weixin.qq.com/miniprogram/dev/api/open-api/setting/wx.getSetting.html)

### 参数 {#parameters}

**Object object**

| 属性              | 类型     | 默认值 | 必填 | 说明                                                                 | 最低版本 |
| ----------------- | -------- | ------ | ---- | -------------------------------------------------------------------- | -------- |
| withSubscriptions | Boolean  | false  | 否   | 是否同时获取用户订阅消息的订阅状态，默认不获取。注意：withSubscriptions 只返回用户勾选过订阅面板中的“总是保持以上选择，不再询问”的订阅消息。 | 2.10.1   |
| success           | function |        | 否   | 接口调用成功的回调函数                                               |          |
| fail              | function |        | 否   | 接口调用失败的回调函数                                               |          |
| complete          | function |        | 否   | 接口调用结束的回调函数（调用成功、失败都会执行）                     |          |

**object.success 回调函数**

**参数**

**Object res**

| 属性                   | 类型                | 说明                                                         | 最低版本 | 支付宝 |
| ---------------------- | ------------------- | ------------------------------------------------------------ | -------- | ------ |
| authSetting            | AuthSetting         | 用户授权结果                                                 |          | ✓ |
| subscriptionsSetting   | SubscriptionsSetting| 用户订阅消息设置，接口参数withSubscriptions值为true时才会返回。 | 2.10.1   | ✓ |
| miniprogramAuthSetting | AuthSetting         | 在插件中调用时，当前宿主小程序的用户授权结果                 |          | ✗ |

### 示例代码 {#example-code}

```js
mpx.getSetting({
  success (res) {
    console.log(res.authSetting)
  }
})
```

---

---
url: /api-proxy/open-api/setting/openSetting.md
---
## mpx.openSetting(Object object)

调起客户端小程序设置界面，返回用户设置的操作结果。

支持情况： 微信、支付宝

[参考文档](https://developers.weixin.qq.com/miniprogram/dev/api/open-api/setting/wx.getSetting.html)

### 参数 {#parameters}

**Object object**

| 属性              | 类型     | 默认值 | 必填 | 说明                                                                 | 最低版本 |
| ----------------- | -------- | ------ | ---- | -------------------------------------------------------------------- | -------- |
| withSubscriptions | Boolean  | false  | 否   | 是否同时获取用户订阅消息的订阅状态，默认不获取。注意：withSubscriptions 只返回用户勾选过订阅面板中的“总是保持以上选择，不再询问”的订阅消息。 | 2.10.3   |
| success           | function |        | 否   | 接口调用成功的回调函数                                               |          |
| fail              | function |        | 否   | 接口调用失败的回调函数                                               |          |
| complete          | function |        | 否   | 接口调用结束的回调函数（调用成功、失败都会执行）                     |          |

**object.success 回调函数**

**参数**

**Object res**

| 属性                 | 类型                | 说明                                                         | 最低版本 |
| -------------------- | ------------------- | ------------------------------------------------------------ | -------- |
| authSetting          | AuthSetting         | 用户授权结果                                                 |          |
| subscriptionsSetting | SubscriptionsSetting| 用户订阅消息设置，接口参数withSubscriptions值为true时才会返回。 | 2.10.3   |

### 示例代码 {#example-code}

```js
mpx.openSetting({
  success (res) {
    console.log(res.authSetting)
  }
})
```

---

---
url: /api-proxy/device/contacts/addPhoneContact.md
---
## mpx.addPhoneContact(Object object)

添加手机通讯录联系人。用户可以选择将该表单以「新增联系人」或「添加到已有联系人」的方式，写入手机系统通讯录。

支持情况： 微信、支付宝

[参考文档](https://developers.weixin.qq.com/miniprogram/dev/api/device/contact/wx.addPhoneContact.html)

### 参数 {#parameters}

**Object object**

| 属性 | 类型 | 默认值 | 必填 | 说明 |
| --- | --- | --- | --- | --- |
| firstName | string | - | 是 | 名字 |
| photoFilePath | string | - | 否 | 头像本地文件路径 |
| nickName | string | - | 否 | 昵称 |
| lastName | string | - | 否 | 姓氏 |
| middleName | string | - | 否 | 中间名 |
| remark | string | - | 否 | 备注 |
| mobilePhoneNumber | string | - | 否 | 手机号 |
| weChatNumber | string | - | 否 | 微信号 |
| addressCountry | string | - | 否 | 联系地址国家 |
| addressState | string | - | 否 | 联系地址省份 |
| addressCity | string | - | 否 | 联系地址城市 |
| addressStreet | string | - | 否 | 联系地址街道 |
| addressPostalCode | string | - | 否 | 联系地址邮政编码 |
| organization | string | - | 否 | 公司 |
| title | string | - | 否 | 职位 |
| workFaxNumber | string | - | 否 | 工作传真 |
| workPhoneNumber | string | - | 否 | 工作电话 |
| hostNumber | string | - | 否 | 公司电话 |
| email | string | - | 否 | 电子邮件 |
| url | string | - | 否 | 网站 |
| workAddressCountry | string | - | 否 | 工作地址国家 |
| workAddressState | string | - | 否 | 工作地址省份 |
| workAddressCity | string | - | 否 | 工作地址城市 |
| workAddressStreet | string | - | 否 | 工作地址街道 |
| workAddressPostalCode | string | - | 否 | 工作地址邮政编码 |
| homeFaxNumber | string | - | 否 | 住宅传真 |
| homePhoneNumber | string | - | 否 | 住宅电话 |
| homeAddressCountry | string | - | 否 | 住宅地址国家 |
| homeAddressState | string | - | 否 | 住宅地址省份 |
| homeAddressCity | string | - | 否 | 住宅地址城市 |
| homeAddressStreet | string | - | 否 | 住宅地址街道 |
| homeAddressPostalCode | string | - | 否 | 住宅地址邮政编码 |
| success | function | - | 否 | 接口调用成功的回调函数 |
| fail | function | - | 否 | 接口调用失败的回调函数 |
| complete | function | - | 否 | 接口调用结束的回调函数（调用成功、失败都会执行） |

---

---
url: /api-proxy/device/bluetooth-ble/closeBLEConnection.md
---
mpx.closeBLEConnection(Object object)

断开与蓝牙低功耗设备的连接。

支持情况： 微信、支付宝

[参考文档](https://developers.weixin.qq.com/miniprogram/dev/api/device/bluetooth-ble/wx.closeBLEConnection.html)

### 参数 {#parameters}

**Object object**

| 属性 | 类型 | 默认值 | 必填 | 说明 |
| --- | --- | --- | --- | --- |
| deviceId | string |  | 是 | 蓝牙设备 id |
| success | function |  | 否 | 接口调用成功的回调函数 |
| fail | function |  | 否 | 接口调用失败的回调函数 |
| complete | function |  | 否 | 接口调用结束的回调函数（调用成功、失败都会执行） |

> RN 平台未传 `deviceId` 时进入 `fail` 回调，`errMsg` 为 `closeBLEConnection:fail parameter error`，随后以同一结果调用 `complete`。

### 错误 {#error}

| 错误码 | 错误信息 | 说明 | 支付宝 |
| --- | --- | --- | --- |
| 0 | ok | 正常 | **✗** |
| -1 | already connect | 已连接 | **✗** |
| 10000 | not init | 未初始化蓝牙适配器 | **✓** |
| 10001 | not available | 当前蓝牙适配器不可用 | **✓** |
| 10002 | no device | 没有找到指定设备 | **✓** |
| 10003 | connection fail | 连接失败 | **✓** |
| 10004 | no service | 没有找到指定服务 | **✓** |
| 10005 | no characteristic | 没有找到指定特征 | **✓** |
| 10006 | no connection | 当前连接已断开 | **✓** |
| 10007 | property not support | 当前特征不支持此操作 | **✓** |
| 10008 | system error | 其余所有系统上报的异常 | **✓** |
| 10009 | system not support | Android 系统特有，系统版本低于 4.3 不支持 BLE | **✓** |
| 10012 | operate time out | 连接超时 | **✓** |
| 10013 | invalid\_data | 连接 deviceId 为空或者是格式不正确 | **✓** |

### 示例代码 {#example-code}

```js
mpx.closeBLEConnection({
  deviceId,
  success (res) {
    console.log(res)
  }
})
```

---

---
url: /api-proxy/device/bluetooth-ble/createBLEConnection.md
---
mpx.createBLEConnection(Object object)

连接蓝牙低功耗设备。

若小程序在之前已有搜索过某个蓝牙设备，并成功建立连接，可直接传入之前搜索获取的 deviceId 直接尝试连接该设备，无需再次进行搜索操作。

支持情况： 微信、支付宝

[参考文档](https://developers.weixin.qq.com/miniprogram/dev/api/device/bluetooth-ble/wx.createBLEConnection.html)

### 参数 {#parameters}

**Object object**

| 属性 | 类型 | 默认值 | 必填 | 说明 | 支付宝 |
| --- | --- | --- | --- | --- | --- |
| deviceId | string |  | 是 | 蓝牙设备 id | **✓** |
| timeout | number |  | 否 | 超时时间，单位 ms，不填表示不会超时 | **✗** |
| success | function |  | 否 | 接口调用成功的回调函数 | **✓** |
| fail | function |  | 否 | 接口调用失败的回调函数 | **✓** |
| complete | function |  | 否 | 接口调用结束的回调函数（调用成功、失败都会执行） | **✓** |

> RN 平台未传 `deviceId` 时进入 `fail` 回调，`errMsg` 为 `createBLEConnection:fail parameter error`，随后以同一结果调用 `complete`。

### 错误 {#error}

| 错误码 | 错误信息 | 说明 | 支付宝 |
| --- | --- | --- | --- |
| 0 | ok | 正常 | **✗** |
| -1 | already connect | 已连接 | **✗** |
| 10000 | not init | 未初始化蓝牙适配器 | **✓** |
| 10001 | not available | 当前蓝牙适配器不可用 | **✓** |
| 10002 | no device | 没有找到指定设备 | **✓** |
| 10003 | connection fail | 连接失败 | **✓** |
| 10004 | no service | 没有找到指定服务 | **✓** |
| 10005 | no characteristic | 没有找到指定特征 | **✓** |
| 10006 | no connection | 当前连接已断开 | **✓** |
| 10007 | property not support | 当前特征不支持此操作 | **✓** |
| 10008 | system error | 其余所有系统上报的异常 | **✓** |
| 10009 | system not support | Android 系统特有，系统版本低于 4.3 不支持 BLE | **✓** |
| 10012 | operate time out | 连接超时 | **✓** |
| 10013 | invalid\_data | 连接 deviceId 为空或者是格式不正确 | **✓** |

### 示例代码 {#example-code}

```js
mpx.createBLEConnection({
  deviceId,
  success (res) {
    console.log(res)
  }
})
```

---

---
url: /api-proxy/device/bluetooth-ble/onBLEConnectionStateChange.md
---
mpx.onBLEConnectionStateChange(function listener)

监听蓝牙低功耗连接状态改变事件。包括开发者主动连接或断开连接，设备丢失，连接异常断开等等

支持情况： 微信、支付宝

[参考文档](https://developers.weixin.qq.com/miniprogram/dev/api/device/bluetooth-ble/wx.onBLEConnectionStateChange.html)

### 参数 {#parameters}

**function listener**

蓝牙低功耗连接状态改变事件的监听函数

**参数**

**Object res**

| 属性 | 类型 | 说明 |
| --- | --- | --- |
| deviceId | string | 蓝牙设备 id |
| connected | boolean | 是否处于已连接状态 |

### 示例代码 {#example-code}

```js
mpx.onBLEConnectionStateChange(function(res) {
  // 该方法回调中可以用于处理连接意外断开等异常情况
  console.log(`device ${res.deviceId} state has changed, connected: ${res.connected}`)
})
```

---

---
url: /api-proxy/device/clipboard/setClipboardData.md
---
## mpx.setClipboardData(Object object)

设置系统剪贴板的内容。调用成功后，会弹出 toast 提示"内容已复制"，持续 1.5s

支持情况： 微信、支付宝

[参考文档](https://developers.weixin.qq.com/miniprogram/dev/api/device/clipboard/wx.setClipboardData.html)

### 参数 {#parameters}

**Object object**

| 属性     | 类型     | 默认值 | 必填 | 说明                                         |
| -------- | -------- | ------ | ---- | -------------------------------------------- |
| data     | string   |        | 是   | 剪贴板的内容                                 |
| success  | function |        | 否   | 接口调用成功的回调函数                       |
| fail     | function |        | 否   | 接口调用失败的回调函数                       |
| complete | function |        | 否   | 接口调用结束的回调函数（调用成功、失败都会执行） |

### 示例代码 {#example-code}

```js
mpx.setClipboardData({
  data: 'data',
  success (res) {
    mpx.getClipboardData({
      success (res) {
        console.log(res.data) // data
      }
    })
  }
})
```

---

---
url: /api-proxy/device/clipboard/getClipboardData.md
---
## mpx.getClipboardData(Object object)

获取系统剪贴板的内容

支持情况： 微信、支付宝

[参考文档](https://developers.weixin.qq.com/miniprogram/dev/api/device/clipboard/wx.getClipboardData.html)

### 参数 {#parameters}

**Object object**

| 属性     | 类型     | 默认值 | 必填 | 说明                                         |
| -------- | -------- | ------ | ---- | -------------------------------------------- |
| success  | function |        | 否   | 接口调用成功的回调函数                       |
| fail     | function |        | 否   | 接口调用失败的回调函数                       |
| complete | function |        | 否   | 接口调用结束的回调函数（调用成功、失败都会执行） |

**object.success 回调函数**

**参数**

**Object object**

| 属性 | 类型   | 说明         |
| ---- | ------ | ------------ |
| data | string | 剪贴板的内容 |

### 示例代码 {#example-code}

```js
mpx.getClipboardData({
  success (res){
    console.log(res.data)
  }
})
```

---

---
url: /api-proxy/device/network/getNetworkType.md
---
## mpx.getNetworkType(Object object)

获取网络类型

支持情况： 微信、支付宝、web、RN

[参考文档](https://developers.weixin.qq.com/miniprogram/dev/api/device/network/wx.getNetworkType.html)

### 参数 {#parameters}

**Object object**

| 属性     | 类型     | 默认值 | 必填 | 说明                                         |
| -------- | -------- | ------ | ---- | -------------------------------------------- |
| success  | function |        | 否   | 接口调用成功的回调函数                       |
| fail     | function |        | 否   | 接口调用失败的回调函数                       |
| complete | function |        | 否   | 接口调用结束的回调函数（调用成功、失败都会执行） |

**object.success 回调函数**

**参数**

**Object res**

### 示例代码 {#example-code}

```js
mpx.getNetworkType({
  success (res) {
    const networkType = res.networkType
    const weakNet = res.weakNet
  }
})
```

---

---
url: /api-proxy/device/network/onNetworkStatusChange.md
---
## mpx.onNetworkStatusChange(function listener)

监听网络状态变化事件

支持情况： 微信、支付宝、web、RN

[参考文档](https://developers.weixin.qq.com/miniprogram/dev/api/device/network/wx.onNetworkStatusChange.html)

### 参数 {#parameters}

**function listener**\
网络状态变化事件的监听函数

**参数**

**Object res**

### 示例代码 {#example-code}

```js
mpx.onNetworkStatusChange(function (res) {
  console.log(res.isConnected)
  console.log(res.networkType)
})
```

---

---
url: /api-proxy/device/network/offNetworkStatusChange.md
---
## mpx.offNetworkStatusChange(function listener)

移除网络状态变化事件的监听函数

支持情况： 微信、支付宝、web、RN

[参考文档](https://developers.weixin.qq.com/miniprogram/dev/api/device/network/wx.offNetworkStatusChange.html)

### 参数 {#parameters}

**function listener**\
onNetworkStatusChange 传入的监听函数。不传此参数则移除所有监听函数。

### 示例代码 {#example-code}

```js
const listener = function (res) { console.log(res) }

mpx.onNetworkStatusChange(listener)
mpx.offNetworkStatusChange(listener) // 需传入与监听时同一个的函数对象
```

---

---
url: /api-proxy/device/screen/getScreenBrightness.md
---
## mpx.getScreenBrightness(Object object)

获取屏幕亮度

支持情况： 微信、支付宝

[参考文档](https://developers.weixin.qq.com/miniprogram/dev/api/device/screen/wx.getScreenBrightness.html)

### 参数 {#parameters}

**Object object**

| 属性    | 类型     | 默认值 | 必填 | 说明                 |
| ------- | -------- | ------ | ---- | -------------------- |
| success | function |        | 否   | 接口调用成功的回调函数 |
| fail    | function |        | 否   | 接口调用失败的回调函数 |
|complete |	function	||	否	| 接口调用结束的回调函数（调用成功、失败都会执行）|

**object.success 回调函数**

**参数**

**Object object**

| 属性  | 类型   | 说明                                 |
| ----- | ------ | ------------------------------------ |
| value | number | 屏幕亮度值，范围 0 ~ 1，0 最暗，1 最亮 |

---

---
url: /api-proxy/device/screen/setScreenBrightness.md
---
## mpx.setScreenBrightness(Object object)

设置屏幕亮度

支持情况： 微信、支付宝

[参考文档](https://developers.weixin.qq.com/miniprogram/dev/api/device/screen/wx.setScreenBrightness.html)

### 参数 {#parameters}

**Object object**

| 属性     | 类型     | 默认值 | 必填 | 说明 |
| -------- | -------- | ------ | ---- | ------------------------------------------------------------ |
| value    | number   |        | 是   | 屏幕亮度值，范围 0 ~ 1，0 最暗，1 最亮。在安卓端支持传入特殊值 -1，表示屏幕亮度跟随系统变化 |
| success  | function |        | 否   | 接口调用成功的回调函数 |
| fail     | function |        | 否   | 接口调用失败的回调函数 |
| complete | function |        | 否   | 接口调用结束的回调函数（调用成功、失败都会执行） |

---

---
url: /api-proxy/device/screen/setVisualEffectOnCapture.md
---
## mpx.setVisualEffectOnCapture(Object object)

设置截屏/录屏时屏幕表现

支持情况： 微信、支付宝

[参考文档](https://developers.weixin.qq.com/miniprogram/dev/api/device/screen/wx.setVisualEffectOnCapture.html)

### 参数 {#parameters}

**Object object**

| 属性         | 类型     | 默认值 | 必填 | 说明                                                         |
| ------------ | -------- | ------ | ---- | ------------------------------------------------------------ |
| visualEffect | string   | none   | 否   | 截屏/录屏时的表现，仅支持 none / hidden，传入 hidden 则表示在截屏/录屏时隐藏屏幕 |
| success      | function |        | 否   | 接口调用成功的回调函数                                       |
| fail         | function |        | 否   | 接口调用失败的回调函数                                       |
| complete     | function |        | 否   | 接口调用结束的回调函数（调用成功、失败都会执行）             |

---

---
url: /api-proxy/device/screen/onUserCaptureScreen.md
---
## mpx.onUserCaptureScreen(function listener)

监听用户主动截屏事件。用户使用系统截屏按键截屏时触发，只能注册一个监听

支持情况： 微信、支付宝

[参考文档](https://developers.weixin.qq.com/miniprogram/dev/api/device/screen/wx.onUserCaptureScreen.html)

### 参数 {#parameters}

**function listener**

用户主动截屏事件的监听函数

**参数**

**Object res**

| 属性   | 类型    | 说明                                                                 | 最低版本 | 支付宝 |
| ------ | ------- | -------------------------------------------------------------------- | -------- | ------ |
| query  | string  | 支持开发者自定义一键打开小程序时的 query                              | 3.3.0    | ✗ |
| promise| promise | 如果该参数存在，则其它的参数将会以 resolve 结果为准，如果一秒内不 resolve，分享会使用上面传入的默认参数 | 3.3.0    | ✗ |

### 示例代码 {#example-code}

```js
mpx.onUserCaptureScreen(function (res) {
  console.log('用户截屏了')
      return {
          query: "parameter=test", // 通过截屏图片打开小程序的query参数
          promise: new Promise((resolve) => { // 通过promise延时传递小程序的query参数
                  setTimeout(() => {
                      resolve({
                          query: "parameter=test2",
                      })
                  }, 1000) // 在1秒内对query进行解析
              })
      }
  }
)
```

---

---
url: /api-proxy/device/screen/offUserCaptureScreen.md
---
## mpx.offUserCaptureScreen(function callback)

用户主动截屏事件。取消事件监听。

支持情况： 微信、支付宝

[参考文档](https://developers.weixin.qq.com/miniprogram/dev/api/device/screen/wx.onUserCaptureScreen.html)

### 参数 {#parameters}

**function callback**

用户主动截屏事件的回调函数

---

---
url: /api-proxy/device/keyboard/hideKeyboard.md
---
## mpx.hideKeyboard(Object object)

在input、textarea等focus拉起键盘之后，手动调用此接口收起键盘

支持情况： 微信、支付宝、RN

[参考文档](https://developers.weixin.qq.com/miniprogram/dev/api/device/keyboard/wx.hideKeyboard.html)

### 参数 {#parameters}

**Object object**

| 属性     | 类型     | 默认值 | 必填 | 说明                                         |
| -------- | -------- | ------ | ---- | -------------------------------------------- |
| success  | function |        | 否   | 接口调用成功的回调函数                       |
| fail     | function |        | 否   | 接口调用失败的回调函数                       |
| complete | function |        | 否   | 接口调用结束的回调函数（调用成功、失败都会执行） |

### 示例代码 {#example-code}

```js
mpx.hideKeyboard({
  complete: res => {
    console.log('hideKeyboard res', res)
  }
})
```

---

---
url: /api-proxy/device/keyboard/onKeyboardHeightChange.md
---
## mpx.onKeyboardHeightChange(function listener)

监听键盘高度变化事件

支持情况： 微信、RN

[参考文档](https://developers.weixin.qq.com/miniprogram/dev/api/device/keyboard/wx.onKeyboardHeightChange.html)

### 参数 {#parameters}

**function listener**\
键盘高度变化事件的监听函数

**参数**

**Object res**

| 属性  | 类型   | 说明     |
| ----- | ------ | -------- |
| height| number | 键盘高度 |

### 示例代码 {#example-code}

```js
mpx.onKeyboardHeightChange(res => {
  console.log(res.height)
})
```

---

---
url: /api-proxy/device/keyboard/offKeyboardHeightChange.md
---
## mpx.offKeyboardHeightChange(function listener)

移除键盘高度变化事件的监听函数

支持情况： 微信、RN

[参考文档](https://developers.weixin.qq.com/miniprogram/dev/api/device/keyboard/wx.offKeyboardHeightChange.html)

### 参数 {#parameters}

**function listener**\
onKeyboardHeightChange 传入的监听函数。不传此参数则移除所有监听函数。

### 示例代码 {#example-code}

```js
const listener = function (res) { console.log(res) }

mpx.onKeyboardHeightChange(listener)
mpx.offKeyboardHeightChange(listener) // 需传入与监听时同一个的函数对象
```

---

---
url: /api-proxy/device/phone/makePhoneCall.md
---
## mpx.makePhoneCall(Object object)

拨打电话

支持情况： 微信、支付宝、RN

[参考文档](https://developers.weixin.qq.com/miniprogram/dev/api/device/phone/wx.makePhoneCall.html)

### 参数 {#parameters}

**Object object**

| 属性        | 类型     | 默认值 | 必填 | 说明                                   |
|-------------|----------|--------|------|----------------------------------------|
| phoneNumber | string   |        | 是   | 需要拨打的电话号码                     |
| success     | function |        | 否   | 接口调用成功的回调函数                 |
| fail        | function |        | 否   | 接口调用失败的回调函数                 |
| complete    | function |        | 否   | 接口调用结束的回调函数（成功或失败均执行） |

### 示例代码 {#example-code}

```js

mpx.makePhoneCall({
  phoneNumber: '1340000' //仅为示例，并非真实的电话号码
})
```

---

---
url: /api-proxy/device/scan/scanCode.md
---
## mpx.scanCode(Object object)

调起客户端扫码界面进行扫码

支持情况： 微信、支付宝

[参考文档](https://developers.weixin.qq.com/miniprogram/dev/api/device/scan/wx.scanCode.html)

### 参数 {#parameters}

**Object object**

**object.success 回调函数**

**参数**

**Object res**

### 示例代码 {#example-code}

```js
// 允许从相机和相册扫码
mpx.scanCode({
  success (res) {
    console.log(res)
  }
})

// 只允许从相机扫码
mpx.scanCode({
  onlyFromCamera: true,
  success (res) {
    console.log(res)
  }
})
```

---

---
url: /api-proxy/device/vibrate/vibrateShort.md
---
## mpx.vibrateShort(Object object)

使手机发生较短时间的振动（15 ms）。仅在 iPhone 7 / 7 Plus 以上及 Android 机型生效

支持情况： 微信、支付宝、RN

[参考文档](https://developers.weixin.qq.com/miniprogram/dev/api/device/vibrate/wx.vibrateShort.html)

### 参数 {#parameters}

**Object object**

| 属性     | 类型     | 默认值 | 必填 | 说明                                   | 最低版本 |
|----------|----------|--------|------|----------------------------------------|----------|
| type     | string   |        | 是   | 震动强度类型，有效值为：heavy、medium、light | 2.13.0   |
| success  | function |        | 否   | 接口调用成功的回调函数                 |          |
| fail     | function |        | 否   | 接口调用失败的回调函数                 |          |
| complete | function |        | 否   | 接口调用结束的回调函数（调用成功、失败都会执行） |          |

**object.success 回调函数**

**参数**

**Object res**

---

---
url: /api-proxy/device/vibrate/vibrateLong.md
---
## mpx.vibrateLong(Object object)

使手机发生较长时间的振动（400 ms)

支持情况： 微信、支付宝、RN

[参考文档](https://developers.weixin.qq.com/miniprogram/dev/api/device/vibrate/wx.vibrateLong.html)

### 参数 {#parameters}

**Object object**

| 属性     | 类型     | 默认值 | 必填 | 说明                                   |
|----------|----------|--------|------|----------------------------------------|
| success  | function |        | 否   | 接口调用成功的回调函数                 |
| fail     | function |        | 否   | 接口调用失败的回调函数                 |
| complete | function |        | 否   | 接口调用结束的回调函数（调用成功、失败都会执行） |

---

---
url: /api-proxy/wxml/createIntersectionObserver.md
---
## [IntersectionObserver](https://developers.weixin.qq.com/miniprogram/dev/api/wxml/IntersectionObserver.html) mpx.createIntersectionObserver(Object component, Object options)

创建并返回一个 IntersectionObserver 对象实例。在自定义组件或包含自定义组件的页面中，应使用 `this.createIntersectionObserver([options])` 来代替。输出 RN 时，底层工厂方法要求第三个参数传入最近的滚动容器上下文；使用组件或页面实例方法时，该参数会由框架内部自动填充。

支持情况： 微信、支付宝、web、RN

[参考文档](https://developers.weixin.qq.com/miniprogram/dev/api/wxml/wx.createIntersectionObserver.html)

### 参数 {#parameters}

**Object component**

自定义组件实例

**Object options**

选项

| 属性         | 类型    | 默认值 | 必填 | 说明                                                                                                   | 最低版本 |
| ------------ | ------- | ------ | ---- | ------------------------------------------------------------------------------------------------------ | -------- |
| thresholds   | Array.\<number>   | \[0]    | 否   | 一个数值数组，包含所有阈值。                                                                           |          |
| initialRatio | number  | 0      | 否   | 初始的相交比例，如果调用时检测到的相交比例与这个值不相等且达到阈值，则会触发一次监听器的回调函数。     |          |
| observeAll   | boolean | false  | 否   | 是否同时观测多个目标节点（而非一个），如果设为 true ，observe 的 targetSelector 将选中多个节点（注意：同时选中过多节点将影响渲染性能） | 2.0.0    |
| nativeMode   | boolean | false  | 否   | 是否使用原生观察器模式。                                                                              | 3.5.7    |

### 返回值 {#return-value}

[IntersectionObserver](https://developers.weixin.qq.com/miniprogram/dev/api/wxml/IntersectionObserver.html)

---

---
url: /api-proxy/wxml/createSelectorQuery.md
---
## [SelectorQuery](https://developers.weixin.qq.com/miniprogram/dev/api/wxml/SelectorQuery.html) mpx.createSelectorQuery()

返回一个 SelectorQuery 对象实例。在自定义组件或包含自定义组件的页面中，应使用 this.createSelectorQuery() 来代替。

支持情况： 微信、支付宝、web、RN

[参考文档](https://developers.weixin.qq.com/miniprogram/dev/api/wxml/wx.createSelectorQuery.html)

### 特别说明RN中 {#rn-note}

1. 调用 createSelectorQuery 组件时，需要通过 wx:ref 进行绑定。
2. 调用 createSelectorQuery 方法创建的 SelectorQuery 实例, 在使用过程中需要手动调用实例上的 in 方法来指定组件上下文。

### 返回值 {#return-value}

[SelectorQuery](https://developers.weixin.qq.com/miniprogram/dev/api/wxml/SelectorQuery.html)

### 示例代码 {#example-code}

```js
const query = mpx.createSelectorQuery()
query.select('#the-id').boundingClientRect()
query.selectViewport().scrollOffset()
query.exec(function(res){
  res[0].top       // #the-id节点的上边界坐标
  res[1].scrollTop // 显示区域的竖直滚动位置
}).in(this) // RN需要指定上下文，其他环境不强制
```

---

---
url: /api-proxy/ext/getExtConfig.md
---
## mpx.getExtConfig(Object object)

获取第三方平台自定义的数据字段

支持情况： 微信、支付宝

[参考文档](https://developers.weixin.qq.com/miniprogram/dev/api/ext/wx.getExtConfig.html)

### 参数 {#parameters}

**Object object**

| 属性     | 类型     | 默认值 | 必填 | 说明                                         |
| -------- | -------- | ------ | ---- | -------------------------------------------- |
| success  | function |        | 否   | 接口调用成功的回调函数                       |
| fail     | function |        | 否   | 接口调用失败的回调函数                       |
| complete | function |        | 否   | 接口调用结束的回调函数（调用成功、失败都会执行） |

**object.success 回调函数**

**参数**

**Object res**

| 属性     | 类型   | 说明                   |
| -------- | ------ | ---------------------- |
| extConfig| Object | 第三方平台自定义的数据 |

### Tips

本接口暂时无法通过 `mpx.canIUse` 判断是否兼容，开发者需要自行判断 `mpx.getExtConfig` 是否存在来兼容

```js
if (mpx.getExtConfig) {
  mpx.getExtConfig({
    success (res) {
      console.log(res.extConfig)
    }
  })
}
```

---

---
url: /api-proxy/ext/getExtConfigSync.md
---
## mpx.getExtConfigSync()

mpx.getExtConfig 的同步版本

支持情况： 微信、支付宝

[参考文档](https://developers.weixin.qq.com/miniprogram/dev/api/ext/wx.getExtConfigSync.html)

### 参数 {#parameters}

**Object**

第三方平台自定义的数据

### Tips

本接口暂时无法通过 `mpx.canIUse` 判断是否兼容，开发者需要自行判断 `mpx.getExtConfigSync` 是否存在来兼容

```js
let extConfig = mpx.getExtConfigSync? mpx.getExtConfigSync(): {}
console.log(extConfig)
```

---

---
url: /articles/1.0.md
---

# 滴滴开源小程序框架Mpx {#didi-open-source-mpx}

> 作者：[hiyuki](https://github.com/hiyuki)

Mpx是一款致力于提高小程序开发体验的增强型小程序框架，通过Mpx，我们能够以最先进的web开发体验(Vue + Webpack)来开发生产性能深度优化的小程序，Mpx具有以下一些优秀特性：

* 数据响应特性(watch/computed)
* 增强的模板语法(动态组件/样式绑定/类名绑定/内联事件函数/双向绑定等)
* 深度性能优化(原生自定义组件/基于依赖收集和数据变化的setData)
* Webpack编译(npm/循环依赖/Babel/ESLint/css预编译/代码优化等)
* 单文件组件开发 testtest123
* 状态管理(Vuex规范/多实例/可合并)
* 跨团队合作(packages)
* 逻辑复用能力(mixins)
* 脚手架支持
* 小程序自身规范的完全支持
* 支付宝小程序的支持

## 设计思路 {#design-concept}

目前业界主流的小程序框架主要有WePY，mpvue和Taro，这三者都是将其他的语法规范转译为小程序语法规范，我们称其为转译型框架。不同于上述三者，Mpx是一款基于小程序语法规范的增强型框架，我们使用Vue中优秀的语法特性增强了小程序，而不是让用户直接使用vue语法来开发小程序，之所以采用这种设计主要是基于如下考虑：

* 转译型框架无法支持源框架的所有语法特性(如Vue模板中的动态特性或React中动态生成的jsx)，用户在使用源框架语法进行开发时可能会遇到不可预期的错误，具有不确定性
* 小程序本身的技术规范在不断地更新进步，许多新的技术规范在转译型框架中无法支持或需要很高的支持成本，而对于增强型框架来说只要新的技术规范不与增强特性冲突，就能够直接支持

## 技术实现 {#technical-implementation}

小程序刚推出时不支持自定义组件，无法进行组件化开发，当时最早的小程序框架WePY做的核心工作就是支持了小程序的组件化开发，后来的mpvue也基于Vue做了类似的工作。由于当时的小程序本身不支持自定义组件，WePY和mpvue的组件化支持都是基于编译做的组件化封装，用户编写的组件模板会被编译为Page中模板的一部分，在组件中定义的数据会被编译为Page中的数据，对组件进行数据更新也会基于路径映射调用Page.setData。这个方案在当时的技术条件下确实是一个唯一解，但该方案在复杂的小程序应用中会存在明显性能问题，原因在于该方案中页面的数据量会很大，而且每个组件的局部更新实际上都会成为页面级别的全局更新，在组件较多的页面中容易引发性能问题。在小程序自定义组件推出后，我们通过性能测试确认了该方案解决了上述组件封装方案中的性能问题。由于自定义组件在当时是一个最新的技术标准，业内的小程序框架都未支持，而我们本身的业务又有复杂小程序的开发需求，于是我们就基于小程序自定义组件规范启动了Mpx框架的设计与开发

*Page与Component setData性能对照*

| |Component|Page|
|---|----------|----- |
|局部更新|1975ms|7186ms|
|全局更新|6210ms|24612ms|

> 性能衡量标准说明：
> 局部更新：文档中存在1000个节点，其中一个节点更新1000次的耗时；
> 全局更新：文档中存在5个节点，5个节点独立更新1000次的耗时
> 以上数据在iphone7微信小程序环境下测试得出

### 数据响应与性能优化 {#reactivity-and-performance}

数据响应作为Vue最核心的特性，在我们的日常开发中被大量使用，能够极大地提高前端开发体验和效率，我们在框架设计初期最早考虑的就是如何将数据响应特性加入到小程序开发中。在数据响应的实现上，我们引入了MobX，一个实现了纯粹数据响应能力的知名开源项目。借助MobX和mixins，我们在小程序组件创建初期建立了一个响应式数据管理系统，该系统观察着小程序组件中的所有数据(data/props/computed)并基于数据的变更驱动视图的渲染(setData)及用户注册的watch回调，实现了Vue中的数据响应编程体验。与此同时，我们基于MobX封装实现了一个Vuex规范的数据管理store，能够方便地注入组件进行全局数据管理。为了提高跨团队开发的体验，我们对store添加了多实例可合并的特性，不同团队维护自己的store，在需要时能够合并他人或者公共的store生成新的store实例，我们认为这是一种比Vuex中modules更加灵活便捷的跨团队数据管理模式

作为一个接管了小程序setData的数据响应开发框架，我们高度重视Mpx的渲染性能，通过小程序官方文档中提到的性能优化建议可以得知，setData对于小程序性能来说是重中之重，setData优化的方向主要有两个：

1. 尽可能减少setData调用的频次
2. 尽可能减少单次setData传输的数据

为了实现以上两个优化方向，我们做了以下几项工作：

* 将组件的静态模板编译为可执行的render函数，通过render函数收集模板数据依赖，只有当render函数中的依赖数据发生变化时才会触发小程序组件的setData，同时通过一个异步队列确保一个tick中最多只会进行一次setData，这个机制和Vue中的render机制非常类似，大大降低了setData的调用频次；
* 将模板编译render函数的过程中，我们还记录输出了模板中使用的数据路径，在每次需要setData时会根据这些数据路径与上一次的数据进行diff，仅将发生变化的数据通过数据路径的方式进行setData，这样确保了每次setData传输的数据量最低，同时避免了不必要的setData操作，进一步降低了setData的频次。
  基于以上优化，我们大大减少了小程序setData的调用频次和传递数据量，与初版Mpx中track全量数据的方案相比提升显著。

*Mpx setData优化效果*

|   |旧版mpx|新版mpx|
|---|----|-----|
|setData次数	|164   	|88	|
|setData数据量	|370kB	|38kB|

> 以上数据由较复杂小程序在固定交互流程后统计得出

![Mpx数据响应机制流程示意图](https://dpubstatic.udache.com/static/dpubimg/4cb54489-b99d-4560-97aa-68f756730131.jpeg)
*Mpx数据响应机制流程示意图*

### 编译构建 {#compilation-and-build}

我们希望使用目前设计最强大、生态最完善的编译构建工具Webpack来实现小程序的编译构建，让用户得到web开发中先进强大的工程化开发体验。使用过Webpack的同学都知道，通常来说Webpack都是将项目中使用到的一系列碎片化模块打包为一个或几个bundle，而小程序所需要的文件结构是非常离散化的，如何调解这两者的矛盾成为了我们最大的难题。一种非常直观简单的思路在于遍历整个src目录，将其中的每一个.mpx文件都作为一个entry加入到Webpack中进行处理，这样做的问题主要有两个：

1. src目录中用不到的.mpx文件也会被编译输出，最终也会被小程序打包进项目包中，无意义地增加了包体积；
2. 对于node\_modules下的.mpx文件，我们不认为遍历node\_modules是一个好的选择。

最终我们采用了一种基于依赖分析和动态添加entry的方式来进行实现，用户在Webpack配置中只需要配置一个入口文件app.mpx，loader在解析到json时会解析json中pages域和usingComponents域中声明的路径，通过动态添加entry的方式将这些文件添加到Webpack的构建系统当中（注意这里是添加entry而不是添加依赖，因为只有entry能生成独立的文件，满足小程序的离散化文件结构），并递归执行这个过程，直到整个项目中所有用到的.mpx文件都加入进来，在输出前，我们借助了CommonsChunkPlugin/SplitChunksPlugin的能力将复用的模块抽取到一个外部的bundle中，确保最终生成的包中不包含重复模块。我们提供了一个Webpack插件和一个.mpx文件对应的loader来实现上述操作，用户只需要将其添加到Webpack配置中就可以以打包web项目的方式正常打包小程序，没有任何的前置和后置操作，支持Webpack本身的完整生态。

![Mpx编译构建机制流程示意图](https://dpubstatic.udache.com/static/dpubimg/ce6d470c-0a4c-486e-a2f5-ad225c289832.jpeg)
*Mpx编译构建机制流程示意图*

# 现状和未来 {#status-and-future}

目前Mpx框架已经在滴滴内部大量使用，支撑了滴滴出行、青桔单车、街兔电单车、营销、车服等业务在小程序上的实现，线上运行稳定，收到了大量的好评反馈。未来我们在对框架进行持续迭代优化的同时会持续跟进微信和支付宝最新的技术标准，同时也会将在更多的小程序平台上进行适配。由于我们的设计初衷和专注点在于增强小程序开发体验，Mpx并没有进行跨H5甚至是跨Native的支持，但现实业务当中确实存在这样的诉求，未来我们会在Mpx的基础上对跨端进行一定的尝试，与此同时我们依然会持续维护升级Mpx，原因在于跨端意味着灵活性受限及能力的缺失，我们希望能给用户提供第二种选择。

*Mpx与业内主流小程序框架异同对比*

|   |WePY|mpvue|Taro|Mpx|
|---|----|-----|----|---|
|代码规范	|自定义|	Vue	|React	|小程序+|
|组件化实现	|Page封装	|Page封装|	Component|	Component|
|数据响应|	脏值检查|	Vue|	无	|Mobx|
|状态管理|	Redux|	Vuex|	Redux|类Vuex|

## 结语 {#conclusion}

如果你注重开发体验和产品性能，专注于小程序开发，那Mpx会是一个很好的选择。最后感谢开源社区源源不断涌现出的优秀项目，给我们提供了无限的启发和巨大的技术帮助。

Github: <https://github.com/didi/mpx>
使用文档: <https://mpxjs.cn/>
用户交流群:
![微信](https://dpubstatic.udache.com/static/dpubimg/at_XEnlFb0/WechatIMG1.jpeg)

---

---
url: /articles/2.0.md
---

# 滴滴小程序框架Mpx发布2.0，支持小程序跨平台开发，可直接转换已有微信小程序

> 作者：[hiyuki](https://github.com/hiyuki)

Mpx是一款致力于提高小程序开发体验和效率的增强型小程序框架，目前在滴滴公司内部支撑了包括滴滴出行小程序，滴滴出行广场小程序，青桔单车，黑马电单车，小桔养车，小桔加油在内的小程序生态；自去年11月开源以来，Mpx也吸纳了众多外部开发者的加入，基于Mpx开发了开走吧，好免街，花忆等小程序。

长期以来，Mpx优秀的开发体验和强大的稳定性得到了内外开发者的一致认可和好评，这非常符合Mpx的设计初衷。但是在各大厂商陆续推出自己的小程序平台，且各家的技术标准都不统一的今天，单纯地提高某一个平台的开发体验已经不能满足广大小程序开发者们的诉求，`一套代码在多小程序平台运行`已经成为一个现实上的刚需。为了解决这个小程序开发的痛点，Mpx发布了2.0版本，适配了目前业内已经发布的所有小程序平台(微信、支付宝、百度、头条、qq)，并且提供了直接将现有微信小程序编译输出到其他平台运行的能力。

Mpx2.0版本新增的主要特性主要包含：

* 完整支持了目前业内已发布的所有小程序平台(微信，支付宝，百度，qq，头条)；
* Mpx小程序跨平台开发，支持将已有的Mpx微信项目编译输出到其他已支持的小程序平台中运行，[点击查看详情](../guide/advance/platform.md)；
* 小程序原生组件跨平台编译，支持将已有的微信原生组件编译输出到其他已支持的小程序平台中运行；
* 深度分包优化，编译过程中进行精准分包资源判断，所有分包only的资源(组件、js、外部样式、外部模板、wxs，图像媒体等)都会精确输出到分包目录中；
* render函数中完整支持wxs模块，[关于render函数点击查看详情](../guide/understand/runtime.md)；
* 支持了模板引入，内联wxs，自定义tabbar，独立分包，workers，云开发等原生能力，进一步完善原生兼容性。

同业内主流的小程序跨端框架相比，Mpx更专注于小程序开发本身，在小程序开发中具备以下优势：

* 基于小程序自身的技术标准进行增强，没有进行过重的DSL转换，开发时遇到的坑会更少；
* 完全兼容原生小程序技术规范，0成本迁移原生小程序项目;
* 跨平台开发以跨小程序平台为目标，大部分差异抹平工作在编译阶段进行，大大减少运行时适配层增加的包体积；
* 支持业内微信小程序组件库(如vant、iView等)直接转换到其他小程序平台运行;
* 非常重视小程序性能，提供了深度的setData和包体积优化。

关于Mpx更详细的介绍可以查看[官方文档](https://mpxjs.cn/)和[这篇文章](1.0.md)。

Github：<https://github.com/didi/mpx>

## 跨平台开发

作为2.0版本的核心能力，Mpx的跨平台开发能力允许用户直接将已有小程序项目编译输出到其他已支持的小程序平台中运行。微信小程序作为小程序概念的提出者，有着最广泛的生态覆盖，因此我们优先支持了将微信小程序编译为其他平台小程序的能力。基于这个能力，用户不仅能跨平台编译微信Mpx项目，甚至能够将微信的原生自定义组件也编译到其他小程序平台进行运行，这意味着我们的跨平台项目能够直接使用一些社区内已有的UI组件库生态(如vant、iView等)，极大地提高了跨平台开发的适用范围。

### 设计理念

Mpx框架的核心设计理念在于增强，增强是指在小程序已有的原生能力基础上做加法，拓展小程序的开发能力，提高小程序的开发体验和效率。这个设计理念使Mpx给开发者带来了更强的确定性和可预期性，更低的学习上手和调试成本。基于这个理念，Mpx在不同的小程序平台中进行了差异性的增强适配，并参考各个平台的模板指令风格提供了不同的增强模板指令集，让用户在各小程序平台中都可以以增强的方式去最大限度地使用平台自有的原生能力。

我们在对Mpx提供跨平台能力的支持时也遵循了增强的核心设计理念。简单来讲，Mpx的跨平台能力是在多平台能力的基础上，在编译和运行时增加了一层转换层，将源平台的代码转换为目标平台的代码之后，再按照既有的目标平台的处理逻辑进行增强，同时我们也提供了一套完善的条件编译机制，让用户自行实现少数框架无法转换的部分。

![Mpx跨平台开发流程示意图](https://dpubstatic.udache.com/static/dpubimg/38652040-2fbf-435b-aeff-563666c4021c.png)

*Mpx跨平台开发流程示意图*

Mpx跨平台能力设计思路明显区别于业内已有的其他小程序跨平台框架，主要差异在于：

* Mpx以小程序本身的DSL作为基准，而没有使用web框架(React,Vue)的DSL；
* Mpx主要通过编译和运行时转换的方式处理平台差异，没有提供额外的差异抹平层(基础组件库等)。

之所以采用这种设计，主要基于以下原因：

* Mpx主要以跨小程序平台为目标，目前各大小程序平台的技术规范具有一定相似性，绝大部分平台差异能够通过编译和运行时手段抹平，同时省去的差异抹平层也能够进一步减少框架运行时体积；
* 使用小程序本身的DSL作为基准允许用户直接在已有项目中使用跨平台能力，对于原生小程序项目或组件也能够使用该能力进行跨平台输出；
* 结合完善的条件编译支持，该方案能够在满足用户跨平台需求的同时仍然允许用户最大限度地使用各个小程序平台提供的能力，完全延续了Mpx增强的核心设计理念。

### 使用方法

Mpx跨平台开发的使用方式非常简单，用户只需在MpxWebpackPlugin创建时传入mode和srcMode参数指定源平台和目标平台，当srcMode和mode不一致时，框架会读取相应的配置对项目进行编译和运行时转换。

```js
// 微信转支付宝
new MpxWebpackPlugin({
  // mode指定目标平台，可选值有(wx|ali|swan|qq|tt)
  mode: 'ali',
  // srcMode指定源码平台，默认值同目标平台一致
  srcMode: 'wx'
})
```

### 差异抹平

目前各大厂商的小程序技术规范在宏观层面上大致保持一致，但是技术细节方面存在很多差异，大致划分为以下几个部分：

* 模板语法/基础组件差异
* json配置差异
* wxs语法差异
* 页面/组件对象差异
* api调用差异
* webview bridge差异

其中，对于模板语法/基础组件、json配置和wxs中的静态差异，我们主要通过编译手段进行转换处理，对于这部分差异中无法转换的部分会在编译阶段报错指出；而对于页面/组件对象、api调用和webview bridge中js运行时的差异，我们主要通过运行时手段进行处理，对应的无法转换部分也会在运行时中报错指出。

值得注意的是，我们在跨平台转换中做的工作不仅是对可转换的技术标准进行转换映射，对于一些目标平台中不存在的能力，我们也尽可能地通过编译和运行时手段提供了模拟和支持，最大限度地减少用户在跨平台开发中需要付出的额外工作量。以差异性最大但现实场景也最多的微信转支付宝为例，Mpx模拟提供了许多微信中支持但支付宝中未支持的能力：

* 组件自定义事件
* 组件间关系
* 获取子组件实例
* observers/property observer
* 内联wxs
* 外部样式类

对于原生自定义组件的跨平台转换，我们会对其进行简单的运行时注入，使其能够使用Mpx框架提供的运行时转换能力。

### 条件编译

对于框架无法抹平的差异部分，会在编译和运行时报错指出，对于这部分错误，我们提供了完善的条件编译机制让用户能够自行编写目标平台的patch进行修复，该能力也能用于实现具有平台差异性的业务逻辑。

上文中提到Mpx通过读取用户传入的mode和srcMode来决定是否以及如何对项目进行转换，mode和srcMode分别代表整个项目构建的目标平台和源平台，条件编译能够让用户在项目中创建声明了自身平台属性(localSrcMode)的文件和代码块。在项目构建中，框架会优先加载带有localSrcMode声明且localSrcMode与项目目标平台匹配(localSrcMode===mode)的文件和代码块，这部分文件和代码块需要完全依照自身声明的平台标准进行编写，Mpx不会对其进行任何编译和运行时的跨平台转换。

Mpx提供了三种维度的条件编译，分别是文件维度，区块维度和代码维度，用户可以根据平台差异的覆盖范围灵活选择使用。

## 性能优化 {#performance-optimization}

Mpx框架专注于小程序开发，在性能优化方面我们做过很多尝试和努力，主要集中在两个方面：

* 运行时的setData优化
* 编译构建时的包体积优化

### setData优化

数据响应是Mpx运行时增强的核心能力，该能力让用户在小程序开发中能够像Vue中一样使用watch和computed特性，并且用直接赋值的方式操作数据驱动视图更新，而不需要手动调用setData方法，换言之框架接管了小程序中的setData调用。

通过各大小程序平台的设计原理和性能优化建议可以得知，setData对于小程序的性能表现非常重要，而setData优化的两大方向在于：

* 尽可能减少setData调用的频次
* 尽可能减少单次setData传输的数据

为了实现setData的优化，我们在模板编译过程中对于每个组件的模板都生成了一个渲染函数(render function)，该函数模拟模板的渲染逻辑，在每次执行时访问当次渲染所需的数据，并将当次访问过的数据路径记录下来作为函数返回值返回。

在运行时，框架会在每个组件创建时创建一个render watcher，该watcher追踪渲染函数，当渲染依赖数据发生变更时异步执行渲染函数，在render watcher回调中得到渲染函数返回的数据路径，基于这些路径与上一次的缓存数据进行diff比对，过滤掉未发生变化的数据后得到最小必要数据，最后调用setData将最小必要数据发送到真实的小程序渲染层更新视图。

基于这个机制，当数据发生变更时，只有当前渲染依赖的那部分数据发生变更才会异步地触发render watcher的执行，而每次执行后也只有实际发生变更的那部分数据会被setData发送到渲染层。这样用户就能自由地根据业务需求来操作数据，无需关注setData的调用优化，框架能够自动进行程序上最优的setData调用，在提升用户开发体验的同时也提升了程序性能。

在1.x版本中，渲染函数内无法执行wxs的逻辑，对于含有wxs的组件有可能降级到全量设置数据的模式，在2.0版本中，我们将wxs模块转译处理为js可执行的代码后注入到js bundle中，含有wxs的渲染函数也能够正常访问并执行wxs逻辑。

![setData优化示意图](https://dpubstatic.udache.com/static/dpubimg/9ead35f1-693f-44f4-beb3-f98555ab6861.png)

*setData优化示意图*

### 包体积优化 {#bundle-size-optimization}

类似于运行时对于setData的接管，Mpx在编译阶段接管了项目的资源管理。得益于webpack强大的插件机制，Mpx开发了一个深度定制的webpack插件，基于webpack完成小程序的打包构建工作。用户在使用Mpx开发小程序时可以不受限制地使用npm依赖、最新的es特性和css预处理器等现代web开发能力。与此同时，Mpx在包体积优化上也做了很多工作，让用户专注于业务开发而无需花费过多精力进行包体积管理，我们所做的优化工作如下：

* 打包构建工作完全基于依赖分析，任何没有被引用的资源都不会出现在dist当中；
* 对于npm组件和页面的构建也完全基于依赖分析按需打包，不会copy整个miniprogram\_dist目录，也不需要执行构建npm，使用体验和包体积均优于微信小程序自身的npm支持方案；
* 基于webpack提供的能力进行公共模块抽取和代码压缩等优化工作；
* 完善的分包支持，对所有资源进行从属分析，将所有分包only的资源都输出到分包目录中。

分包作为微信小程序中优化包体积的核心手段(类似于异步按需加载)，Mpx对其进行了完善的支持。为了精确地标记出分包only的资源，我们在构建时将主包和分包的依赖收集步骤拆分开来串行处理，先处理主包，再处理分包。在主包的处理过程中，将主包页面中引用的所有非js资源(组件、外部样式、外部模板、wxs，图像媒体等)都记录下来，在处理分包时，对分包内引用的非js资源都进行检查，如果被主包引用过则输出到主包中，否则标记为分包only的资源输出到分包目录下。

对于js模块资源，我们在脚手架中生成的构建配置中提供了辅助函数，便于用户进行分包bundle的配置，经过该配置后，分包only的公用模块会被打入分包bundle输出到分包目录下，其余的公共模块会正常打入主bundle中。

在跨平台开发中，我们建议用户使用Mpx提供的[packages](../guide/advance/subpackage.md#packages)来定义分包，这样在转换到不支持分包的小程序平台时会自动降级为同步包进行处理。

![分包构建示意图](https://dpubstatic.udache.com/static/dpubimg/3121ca4e-1b47-43bc-992a-b351c4a03da4.png)

*分包构建示意图*

## 渐进迁移

Mpx提供了良好的渐进迁移支持，对于使用原生或其他小程序框架的开发者来说，采用渐进迁移的方式逐步引入Mpx进行开发成本并不大。

在2.0版本中我们进一步完善了Mpx的原生兼容性，跟进支持了各个小程序平台最新的技术能力，如自定义tabbar，独立分包，分包预加载，workers，云开发等能力，同时补齐了一些1.x版本遗漏的支持。得益于此，对于使用原生小程序开发的开发者来说，迁移Mpx的成本几乎为0，用户只需将对应页面组件的构造函数替换为Mpx提供的createPage/createCompnent，即可使用Mpx提供的各种增强能力。

对于使用其他框架的开发者，Mpx也提供了局部构建的机制，允许用户将特定的页面和组件单独构建输出为原生组件，用户只需手动或者编写脚本输出的原生组件整合进原有项目中即可。

## 未来规划 {#future-plan}

作为滴滴公司内部小程序生态的基础设施，我们会对Mpx框架进行长期的维护更新，确保能在第一时间支持各个小程序平台最新的技术特性。与此同时，我们也会进一步完善框架的基础能力，目前已排上日程待支持能力包括：

* i18n
* ts支持
* 单元测试支持

在跨平台能力方面，我们也会根据社区的反馈和建议，以及小程序的标准化进程，对其进行持续的完善与更新。

最后，如果你专注小程序开发，关注开发体验和产品性能，那Mpx会是你最好的选择。

---

---
url: /articles/performance.md
---

# 小程序框架运行时性能大测评 {#runtime-performance-benchmark}

> 作者：董宏平([hiyuki](https://github.com/hiyuki))，滴滴出行小程序负责人，mpx框架负责人及核心作者

随着小程序在商业上的巨大成功，小程序开发在国内前端领域越来越受到重视，为了方便广大开发者更好地进行小程序开发，各类小程序框架也层出不穷，呈现出百花齐放的态势。但是到目前为止，业内一直没有出现一份全面、详细、客观、公正的小程序框架测评报告，为小程序开发者在技术选型时提供参考。于是我便筹划推出一系列文章，对业内流行的小程序框架进行一次全方位的、客观公正的测评，本文是系列文章的第一篇——运行时性能篇。

在本文中，我们会对下列框架进行运行时性能测试(排名不分先后):

* wepy2(https://github.com/Tencent/wepy) @2.0.0-alpha.20
* uniapp(https://github.com/dcloudio/uni-app) @2.0.0-26120200226001
* mpx(https://github.com/didi/mpx) @2.5.3
* chameleon(https://github.com/didi/chameleon) @1.0.5
* mpvue(https://github.com/Meituan-Dianping/mpvue) @2.0.6
* kbone(https://github.com/Tencent/kbone) @0.8.3
* taro next(https://github.com/NervJS/taro) @3.0.0-alpha.5

其中对于kbone和taro next均以vue作为业务框架进行测试。

运行时性能的测试内容包括以下几个维度：

* 框架运行时体积
* 页面渲染耗时
* 页面更新耗时
* 局部更新耗时
* setData调用次数
* setData发送数据大小

框架性能测试demo全部存放于https://github.com/hiyuki/mp-framework-benchmark 中，欢迎广大开发者进行验证纠错及补全；

## 测试方案 {#test-plan}

为了使测试结果真实有效，我基于常见的业务场景构建了两种测试场景，分别是动态测试场景和静态测试场景。

### 动态测试场景 {#dynamic-test-scenario}

动态测试中，视图基于数据动态渲染，静态节点较少，视图更新耗时和setData调用情况是该测试场景中的主要测试点。

动态测试demo模拟了实际业务中常见的长列表+多tab场景，该demo中存在两份优惠券列表数据，一份为可用券数据，另一份为不可用券数据，其中同一时刻视图中只会渲染展示其中一份数据，可以在上方的操作区模拟对列表数据的各种操作及视图展示切换(切tab)。

*动态测试demo*

在动态测试中，我在外部通过函数代理的方式在初始化之前将App、Page和Component构造器进行代理，通过mixin的方式在Page的onLoad和Component的created钩子中注入setData拦截逻辑，对所有页面和组件的setData调用进行监听，并统计小程序的视图更新耗时及setData调用情况。该测试方式能够做到对框架代码的零侵入，能够跟踪到小程序全量的setData行为并进行独立的耗时计算，具有很强的普适性，代码具体实现可以查看https://github.com/hiyuki/mp-framework-benchmark/blob/master/utils/proxy.js

### 静态测试场景 {#static-test-scenario}

静态测试模拟业务中静态页面的场景，如运营活动和文章等页面，页面内具备大量的静态节点，而没有数据动态渲染，初始ready耗时是该场景下测试的重心。

静态测试demo使用了我去年发表的一篇技术文章的html代码进行小程序适配构建，其中包含大量静态节点及文本内容。

*静态测试demo*

## 测试流程及数据 {#test-process-and-data}

> 以下所有耗时类的测试数据均为微信小程序中真机进行5次测试计算平均值得出，单位均为ms。Ios测试环境为手机型号iPhone 11，系统版本13.3.1，微信版本7.0.12，安卓测试环境为手机型号小米9，系统版本Android10，微信版本7.0.12。

> 为了使数据展示不过于混乱复杂，文章中所列的数据以Ios的测试结果为主，安卓测试结论与Ios相符，整体耗时比Ios高3~4倍左右，所有的原始测试数据存放在https://github.com/hiyuki/mp-framework-benchmark/blob/master/rawData.csv

> 由于transform-runtime引入的core-js会对框架的运行时体积和运行耗时带来一定影响，且不是所有的框架都会在编译时开启transform-runtime，为了对齐测试环境，下述测试均在transform-runtime关闭时进行。

### 框架运行时体积 {#framework-runtime-size}

由于不是所有框架都能够使用`webpack-bundle-analyzer`得到精确的包体积占用，这里我通过将各框架生成的demo项目体积减去native编写的demo项目体积作为框架的运行时体积。

|     | demo总体积(KB) | 框架运行时体积(KB) |
| --- | --------- | ----------- |
|native|27|0|
|wepy2|66|39|
|uniapp|114|87|
|mpx|78|51|
|chameleon|136|109|
|mpvue|103|76|
|kbone|395|368|
|taro next|183|156|

该项测试的结论为：\
native > wepy2 > mpx > mpvue > uniapp > chameleon > taro next > kbone

结论分析：

* wepy2和mpx在框架运行时体积上控制得最好；
* taro next和kbone由于动态渲染的特性，在dist中会生成递归渲染模板/组件，所以占用体积较大。

### 页面渲染耗时(动态测试) {#page-render-time-dynamic}

我们使用`刷新页面`操作触发页面重新加载，对于大部分框架来说，页面渲染耗时是从触发刷新操作到页面执行onReady的耗时，但是对于像kbone和taro next这样的动态渲染框架，页面执行onReady并不代表视图真正渲染完成，为此，我们设定了一个特殊规则，在页面onReady触发的1000ms内，在没有任何操作的情况下出现setData回调时，以最后触发的setData回调作为页面渲染完成时机来计算真实的页面渲染耗时，测试结果如下：

|     | 页面渲染耗时 |
| --- | --------- |
|native|60.8|
|wepy2|64|
|uniapp|56.4|
|mpx|52.6|
|chameleon|56.4|
|mpvue|117.8|
|kbone|98.6|
|taro next|89.6|

> 该项测试的耗时并不等同于真实的渲染耗时，由于小程序自身没有提供performance api，真实渲染耗时无法通过js准确测试得出，不过从得出的数据来看该项数据依然具备一定的参考意义。

该项测试的结论为：\
mpx ≈ chameleon ≈ uniapp ≈ native ≈ wepy2 > taro next ≈ kbone ≈ mpvue

结论分析：

* 由于mpvue全量在页面进行渲染，kbone和taro next采用了动态渲染技术，页面渲染耗时较长，其余框架并无太大区别。

### 页面更新耗时(无后台数据) {#page-update-time-no-data}

这里后台数据的定义为data中存在但当前页面渲染中未使用到的数据，在这个demo场景下即为不可用券的数据，当前会在不可用券为0的情况下，对可用券列表进行各种操作，并统计更新耗时。

更新耗时的计算方式是从数据操作事件触发开始到对应的setData回调完成的耗时

> mpvue中使用了当前时间戳(new Date)作为超时依据对setData进行了超时时间为50ms的节流操作，该方式存在严重问题，当vue内单次渲染同步流程执行耗时超过50ms时，后续组件patch触发的setData会突破这个节流限制，以50ms每次的频率对setData进行高频无效调用。在该性能测试demo中，当优惠券数量超过500时，界面就会完全卡死。为了顺利跑完整个测试流程，我对该问题进行了简单修复，使用setTimeout重写了节流部分，确保在vue单次渲染流程同步执行完毕后才会调用setData发送合并数据，之后mpvue的所有性能测试都是基于这个patch版本来进行的，该patch版本存放在https://github.com/hiyuki/mp-framework-benchmark/blob/master/frameworks/mpvue/runtime/patch/index.js

> 理论上来讲native的性能在进行优化的前提下一定是所有框架的天花板，但是在日常业务开发中我们可能无法对每一次setData都进行优化，以下性能测试中所有的native数据均采用修改数据后全量发送的形式来实现。

第一项测试我们使用`新增可用券(100)`操作将可用券数量由0逐级递增到1000：

|     | 100 | 200 | 300 | 400 | 500 | 600 | 700 | 800 | 900 | 1000 |
| --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | ---- |
|native|84.6|69.8|71.6|75|77.2|78.8|82.8|93.2|93.4|105.4|
|wepy2|118.4|168.6|204.6|246.4|288.6|347.8|389.2|434.2|496|539|
|uniapp|121.2|100|96|98.2|97.8|99.6|104|102.4|109.4|107.6|
|mpx|110.4|87.2|82.2|83|80.6|79.6|86.6|90.6|89.2|96.4|
|chameleon|116.8|115.4|117|119.6|122|125.2|133.8|133.2|144.8|145.6|
|mpvue|112.8|121.2|140|169|198.8|234.2|278.8|318.4|361.4|408.2|
|kbone|556.4|762.4|991.6|1220.6|1468.8|1689.6|1933.2|2150.4|2389|2620.6|
|taro next|470|604.6|759.6|902.4|1056.2|1228|1393.4|1536.2|1707.8|1867.2|

然后我们按顺序逐项点击`删除可用券(all)` > `新增可用券(1000)` > `更新可用券(1)` > `更新可用券(all)` > `删除可用券(1)`：

|     | delete(all) | add(1000) | update(1) | update(all) | delete(1) |
| --- | ----------- | --------- | --------- | ----------- | --------- |
| native |32.8|295.6|92.2|92.2|83|
| wepy2 |56.8|726.4|49.2|535|530.8|
| uniapp |43.6|584.4|54.8|144.8|131.2|
| mpx |41.8|489.6|52.6|169.4|165.6|
| chameleon |39|765.6|95.6|237.8|144.8|
| mpvue |103.6|669.4|404.4|414.8|433.6|
| kbone |120.2|4978|2356.4|2419.4|2357|
| taro next |126.6|3930.6|1607.8|1788.6|2318.2|

> 该项测试中初期我update(all)的逻辑是循环对每个列表项进行更新，形如`listData.forEach((item)=>{item.count++})`，发现在chameleon框架中执行界面会完全卡死，追踪发现chameleon框架中没有对setData进行异步合并处理，而是在数据变动时直接同步发送，这样在数据量为1000的场景下用该方式进行更新会高频触发1000次setData，导致界面卡死；对此，我在chameleon框架的测试demo中，将update(all)的逻辑调整为深clone产生一份更新后的listData，再将其整体赋值到this.listData当中，以确保该项测试能够正常进行。

该项测试的结论为：\
native > mpx ≈ uniapp > chameleon > mpvue > wepy2 > taro next > kbone

结论分析：

* mpx和uniapp在框架内部进行了完善的diff优化，随着数据量的增加，两个框架的新增耗时没有显著上升；
* wepy2会在数据变更时对props数据也进行setData，在该场景下造成了大量的无效性能损耗，导致性能表现不佳；
* kbone和taro next采用了动态渲染方案，每次新增更新时会发送大量描述dom结构的数据，与此同时动态递归渲染的耗时也远大于常规的静态模板渲染，使得这两个框架在所有的更新场景下耗时都远大于其他框架。

### 页面更新耗时(有后台数据) {#page-update-time-with-data}

刷新页面后我们使用`新增不可用券(1000)`创建后台数据，观察该操作是否会触发setData并统计耗时

|     | back add(1000) |
| --- | -------------- |
| native | 45.2
| wepy2 | 174.6
| uniapp | 89.4
| mpx | 0
| chameleon | 142.6
| mpvue | 134
| kbone | 0
| taro next | 0

> mpx进行setData优化时inspired by vue，使用了编译时生成的渲染函数跟踪模板数据依赖，在后台数据变更时不会进行setData调用，而kbone和taro next采用了动态渲染技术模拟了web底层环境，在上层完整地运行了vue框架，也达到了同样的效果。

然后我们执行和上面无后台数据时相同的操作进行耗时统计，首先是递增100：

|     | 100 | 200 | 300 | 400 | 500 | 600 | 700 | 800 | 900 | 1000 |
| --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | ---- |
| native |88|69.8|71.2|80.8|79.4|84.4|89.8|93.2|99.6|108|
| wepy2 |121|173.4|213.6|250|298|345.6|383|434.8|476.8|535.6|
| uniapp |135.4|112.4|110.6|106.4|109.6|107.2|114.4|116|118.8|117.4|
| mpx |112.6|86.2|84.6|86.8|90|87.2|91.2|88.8|92.4|93.4|
| chameleon |178.4|178.2|186.4|184.6|192.6|203.8|210|217.6|232.6|236.8|
| mpvue |139|151|173.4|194|231.4|258.8|303.4|340.4|384.6|429.4|
| kbone |559.8|746.6|980.6|1226.8|1450.6|1705.4|1927.2|2154.8|2367.8|2617|
| taro next |482.6|626.2|755|909.6|1085|1233.2|1384|1568.6|1740.6|1883.8|

然后按下表操作顺序逐项点击统计

|     | delete(all) | add(1000) | update(1) | update(all) | delete(1) |
| --- | ----------- | --------- | --------- | ----------- | --------- |
| native |43.4|299.8|89.2|89|87.2|
| wepy2 |43.2|762.4|50|533|522.4|
| uniapp |57.8|589.8|62.6|160.6|154.4|
| mpx |45.8|490.8|52.8|167|166|
| chameleon |93.8|837|184.6|318|220.8|
| mpvue |124.8|696.2|423.4|419|430.6|
| kbone |121.4|4978.2|2331.2|2448.4|2348
| taro next |129.8|3947.2|1610.4|1813.8|2290.2|

该项测试的结论为：\
native > mpx > uniapp > chameleon > mpvue > wepy2 > taro next > kbone

结论分析：

* 具备模板数据跟踪能力的三个框架mpx，kbone和taro next在有后台数据场景下耗时并没有显著增加；
* wepy2当中的diff精度不足，耗时也没有产生明显变化；
* 其余框架由于每次更新都会对后台数据进行deep diff，耗时都产生了一定提升。

### 页面更新耗时(大数据量场景) {#page-update-time-large-data}

> 由于mpvue和taro next的渲染全部在页面中进行，而kbone的渲染方案会额外新增大量的自定义组件，这三个框架都会在优惠券数量达到2000时崩溃白屏，我们排除了这三个框架对其余框架进行大数据量场景下的页面更新耗时测试

首先还是在无后台数据场景下使用`新增可用券(1000)`将可用券数量递增至5000：

|     | 1000 | 2000 | 3000 | 4000 | 5000 |
| --- | ---- | ---- | ---- | ---- | ---- |
| native |332.6|350|412.6|498.2|569.4|
| wepy2 |970.2|1531.4|2015.2|2890.6|3364.2|
| uniapp |655.2|593.4|655|675.6|718.8|
| mpx |532.2|496|548.6|564|601.8|
| chameleon |805.4|839.6|952.8|1086.6|1291.8|

然后点击`新增不可用券(5000)`将后台数据量增加至5000，再测试可用券数量递增至5000的耗时：

|     | back add(5000) |
| --- | -------------- |
| native |117.4|
| wepy2 |511.6|
| uniapp |285|
| mpx |0|
| chameleon |824|

|     | 1000 | 2000 | 3000 | 4000 | 5000 |
| --- | ---- | ---- | ---- | ---- | ---- |
| native |349.8|348.4|430.4|497|594.8|
| wepy2 |1128|1872|2470.4|3263.4|4075.8|
| uniapp |715|666.8|709.2|755.6|810.2|
| mpx |538.8|501.8|562.6|573.6|595.2|
| chameleon |1509.2|1672.4|1951.8|2232.4|2586.2|

该项测试的结论为：\
native > mpx > uniapp > chameleon > wepy2

结论分析：

* 在大数据量场景下，框架之间基础性能的差异会变得更加明显，mpx和uniapp依然保持了接近原生的良好性能表现，而chameleon和wepy2则产生了比较显著的性能劣化。

### 局部更新耗时 {#partial-update-time}

我们在可用券数量为1000的情况下，点击任意一张可用券触发选中状态，以测试局部更新性能

|     | toggleSelect(ms) |
| --- | ------------ |
| native |2|
| wepy2 |2.6|
| uniapp |2.8|
| mpx |2.2|
| chameleon |2|
| mpvue |289.6|
| kbone |2440.8|
| taro next |1975|

该项测试的结论为：\
native ≈ chameleon ≈ mpx ≈ wepy2 ≈ uniapp > mpvue > taro next > kbone

结论分析：

* 可以看出所有使用了原生自定义组件进行组件化实现的框架局部更新耗时都极低，这足以证明小程序原生自定义组件的优秀性和重要性；
* mpvue由于使用了页面更新，局部更新耗时显著增加；
* kbone和taro next由于递归动态渲染的性能开销巨大，导致局部更新耗时同样巨大。

### setData调用 {#setdata-call}

我们将`proxySetData`的count和size选项设置为true，开启setData的次数和体积统计，重新构建后按照以下流程执行系列操作，并统计setData的调用次数和发送数据的体积。

操作流程如下：

1. 100逐级递增可用券(0->500)
2. 切换至不可用券
3. 新增不可用券(1000)
4. 100逐级递增可用券(500->1000)
5. 更新可用券(all)
6. 切换至可用券

操作完成后我们使用`getCount`和`getSize`方法获取累积的setData调用次数和数据体积，其中数据体积计算方式为JSON.stringify后按照utf-8编码方式进行体积计算，统计结果为：

|     | count | size(KB) |
| --- | ----- | ---- |
| native |14|803|
| wepy2 |3514|1124|
| mpvue |16|2127|
| uniapp |14|274|
| mpx |8|261|
| chameleon |2515|319|
| kbone |22|10572|
| taro next |9|2321|

该项测试的结论为：\
mpx > uniapp > native > chameleon > wepy2 > taro next > mpvue > kbone

结论分析：

* mpx框架成功实现了理论上setData的最优；
* uniapp由于缺失模板追踪能力紧随其后；
* chameleon由于组件每次创建时都会进行一次不必要的setData，产生了大量无效setData调用，但是数据的发送本身经过diff，在数据发送量上表现不错；
* wepy2的组件会在数据更新时调用setData发送已经更新过的props数据，因此也产生了大量无效调用，且diff精度不足，发送的数据量也较大；
* taro next由于上层完全基于vue，在数据发送次数上控制到了9次，但由于需要发送大量的dom描述信息，数据发送量较大；
* mpvue由于使用较长的数据路径描述数据对应的组件，也产生了较大的数据发送量；
* kbone对于setData的调用控制得不是很好，在上层运行vue的情况依然进行了22次数据发送，且发送的数据量巨大，在此流程中达到了惊人的10MB。

### 页面渲染耗时(静态测试) {#page-render-time-static}

此处的页面渲染耗时与前面描述的动态测试场景中相同，测试结果如下：

|     | 页面渲染耗时 |
| --- | --------- |
| native |70.4|
| wepy2 |86.6|
| mpvue |115.2|
| uniapp |69.6|
| mpx |66.6|
| chameleon |65|
| kbone |144.2|
| taro next |119.8|

该项测试的结论为：\
chameleon ≈ mpx ≈ uniapp ≈ native > wepy2 > mpvue ≈ taro next > kbone

结论分析：

* 除了kbone和taro next采用动态渲染耗时增加，mpvue使用页面模板渲染性能稍差，其余框架的静态页面渲染表现都和原生差不多。

## 结论 {#conclusion}

综合上述测试数据，我们得到最终的小程序框架运行时性能排名为：\
mpx > uniapp > chameleon > wepy2 > mpvue > taro next > kbone

## 一点私货 {#personal-opinion}

虽然kbone和taro next采用了动态渲染技术在性能表现上并不尽如人意，但是我依然认为这是很棒的技术方案。虽然本文从头到位都在进行性能测试和对比，但性能并不是框架的全部，开发效率和高可用性仍然是框架的重心，开发效率相信是所有框架设计的初衷，但是高可用性却在很大程度被忽视。从这个角度来说，kbone和taro next是非常成功的，不同于过去的转译思路，这种从抹平底层渲染环境的做法能够使上层web框架完整运行，在框架可用性上带来非常大的提升，非常适合于运营类简单小程序的迁移和开发。

我主导开发的mpx框架(https://github.com/didi/mpx) 选择了另一条道路解决可用性问题，那就是基于小程序原生语法能力进行增强，这样既能避免转译web框架时带来的不确定性和不稳定性，同时也能带来非常接近于原生的性能表现，对于复杂业务小程序的开发者来说，非常推荐使用。在跨端输出方面，mpx目前能够完善支持业内全部小程序平台和web平台的同构输出，滴滴内部最重要最复杂的小程序——滴滴出行小程序完全基于mpx进行开发，并利用框架提供的跨端能力对微信和支付宝入口进行同步业务迭代，大大提升了业务开发效率。

---

---
url: /articles/mpx1.md
---

# 小程序开发者，为什么你应该尝试下MPX

> 作者：[sky-admin](https://github.com/sky-admin)

> MPX框架是滴滴出行推出的一款专注小程序开发的增强型框架。本篇文章将从使用角度谈谈MPX的优势与好处。如果嫌内容太长，优势部分每个小节都有简单的一句话总结，可以快速阅读。如果想了解更多设计细节，可以阅读 [前一篇文章 - MPX2.0发布](2.0.md)。

## 背景 {#background}

在小程序逐渐火热的今天，越来越多的开发者需要进行小程序的开发。原生小程序的开发有诸多不便，开发者又需要在众多的小程序框架中做出抉择。

那么今天，我们要给大家安利一款小程序框架：MPX

## 优势

之所以建议开发者们考虑使用MPX框架来开发小程序，是因为MPX框架具有一些别的框架所没有的优点。

MPX立足原生小程序，在保证坑少的同时做了很多能力增强，提供了数据响应、模板增强、性能优化、跨平台开发等能力，以提升用户的开发体验及效率。

接下来会从 原生兼容 -> 第三方组件支持 -> 按需构建 -> 跨平台编译 -> 能力增强 -> 独特性能优势 六个点来逐一讲述。

### 原生兼容

> MPX完全兼容原生，坑少。渐进接入简单。

从语法风格上，我们可以看到目前市面上流行的小程序框架基本是基于web框架（taro/nanachi - react，uniapp/megalo/mpvue - vue）或者是一套全新（chameleon）/ 半全新（wepy）的标准。

使用了这些框架，你所写的代码，并不是小程序代码。而是react/vue或者另一套代码。而这些代码源码到小程序代码，需要经过一次全面的转换，这个转换可能会引入一些未知的问题，产生一些坑。

同时随着时间，小程序自身会逐步迭代，做出更多的功能特性，提供更好的组件、方法。而一些框架可能会受限于精力或框架节奏，没有办法第一时间跟进，甚至框架慢慢疏于维护而无法使用。

而MPX选择的是，**全面拥抱原生**。

口说无凭，我们来看个典型的MPX组件长什么样。

![mpx组件示例](https://dpubstatic.udache.com/static/dpubimg/3877c653-d180-4fe7-8661-457b9de1bd82.png)

乍一看好像和vue没什么区别，也就多了个json块，template里写的是小程序的标签。

由于这一块全是符合微信小程序原生语法，我们是不会做任何转换的，所以你写什么就是什么。（如果使用了MPX的增强特性，还是会进行一些必要的转换的，后续我们也会出文章详细解释MPX的增强是如何实现的，相对来说，我们的转换比较轻量、透明、易理解）

当微信出了新的能力、新的标签、新的生命周期钩子，使用MPX框架来编写的小程序只需要直接用起来就行。

所以，使用MPX框架，你可以轻易地使用 **[自定义组件的relations](https://developers.weixin.qq.com/miniprogram/dev/framework/custom-component/relations.html)** 来搞定组件间关系，使用 **[wxs](https://developers.weixin.qq.com/miniprogram/dev/framework/view/wxs/)** 来更好地构建页面。

MPX几乎支持原生的每一个特性，在 .mpx 文件里，模板部分写的是原生小程序的模板语法，脚本部分写的是原生小程序的脚本语法，json部分写的是原生小程序的配置信息。用MPX，你才是真的在开发小程序。

目前很多原生小程序开发者可能想尝试下框架，老项目接入框架，选MPX肯定是最简单的了。口说无凭，我们搞了个demo来给大家打个样：在我们GitHub项目中有examples文件夹，里面的 [原生项目渐进接入MPX示例](https://github.com/didi/mpx/tree/master/examples/mpx-progressive) 。

### 第三方组件库

> MPX提供了完备的第三方组件库支持

上面说了MPX对原生的极致兼容，能让你想到什么？对，就是对第三方组件库的完美支持。

支持第三方组件库的重要性大家都知道，所以这个能力大部分框架都支持了。但是支持和完美支持还是有区别的。据简单观察，taro/mpvue/uniapp对于第三方组件库的支持都是以复制的形式进行的，也就是和微信小程序本来的行为很像。

那么MPX是怎么支持第三方组件库的呢，这里有个demo：也在我们的GitHub里的examples文件夹下，[MPX使用第三方组件库示例](https://github.com/didi/mpx/tree/master/examples/mpx-useuilib) ，核心代码见下图：

![MPX使用第三方组件库代码示例](https://dpubstatic.udache.com/static/dpubimg/9ecdd898-f7e5-48cc-89c2-bfc7ce3a03f9.png)

乍一眼看不太出来有什么特别的？没用过别的框架引第三方组件，简单找了找其他框架好像也没提供相应的demo，用过的朋友可以自行对比下。

在MPX里使用第三方组件库，仅需&#x8981;***像web项目一样npm安装即可，并不需要复制文件***。然后在json里直接写包名就会去node\_modules下面查找了。再配合webpack alias可以做到更简单、更语义化。

然而这还没有结束~

细心的朋友会发现，这段示例代码中既有vant的组件，也有iview的组件，如果按照微信的规范，这些组件库会通过miniprogram字段指定自己的构建文件生成目录，开发者工具会把这个目录完全拷贝到最终发布的代码里去，我们就会有两个巨大的组件库占据宝贵的空间。

我们当然是希望用多少引多少，而不是一股脑全引进去，对，于是MPX提供了按需引用的能力，在下一章[按需引用](#按需引用)细讲。

以及，组件库目前很少有跨小程序平台的组件库啊，如果我用了vant，支付宝、QQ里没有vant怎么办？也许这是别的框架不怎么推荐使用第三方库的原因，而MPX里，我们帮你把别人的组件库也转了，细节看下下章[跨小程序平台](#跨小程序平台)

### 按需引用

> 通过webpack依赖分析收集，使用第三方组件库或者拆分开发大型项目时MPX能保证构建的代码全是要用到的代码

原生小程序本身的编译是遍历项目文件夹里所有的JS，包装成一个AMD包，也就是说项目文件夹里所有的文件，不论是否被使用，都会占用包体积并上传。

同时，原生微信小程序的npm支持是基于文件夹复制的，第三方包通过声明miniprogram字段指定要拷贝的文件夹，不论使用还是未使用的资源（模板/js/样式/图片），全会被复制到项目文件夹中。

而我们提供了@mpxjs/webpack-plugin插件，借助webpack生态，解析.mpx文件的json部分或原生的json文件将依赖作为新的入口添加子编译。基于依赖收集，而不是文件遍历。

带来的好处就是：如果你喜欢vant的按钮，iview的输入框，wux的布局，欢迎尝试MPX，让你能同时使用多个UI框架的同时不用担心应用的体积爆炸。

同理，面对一个大型项目，我们可以拆成不同的部分，由不同的团队完成后发npm包，在一个主项目中引入即可，具体内容可以看文档[packages](../guide/advance/subpackage.md#packages)一节。

收集依赖的细节可以查阅文档[编译构建](../guide/understand/compile.md)一节。

### 跨小程序平台

> MPX的跨平台方法能带着第三方组件库一起跨小程序平台，同时提供了充足完善的条件编译能力。

在 MPX 1.0 时代，MPX框架是专注提升微信小程序的开发体验，虽然也提供了支付宝版，但代码完全要另写。

而随着越来越多的 super app 提供了小程序能力，目前至少有5种体系的小程序（微信、支付宝系列、百度系列、头条系列、QQ），如果每一个平台都需要维护一份代码，工程师人数明显不够用了，所以跨小程序平台的能力也是 MPX 2.0 的主打特性。

我们的跨平台的方法就是转换。都是小程序，语法基本一样，配置、钩子的差异在MPX运行时里提供了抹平。

而除此之外最大的区别也就是模板上的标签和指令。所以我们实现了一套转换的架子，再编写一份转换规则，即可完成微信小程序到支付宝、百度、头条小程序的转换。

采用这种转换的模式，非常方便用户理解我们是如何把微信小程序转换成支付宝、百度等小程序平台的。而且只要用户有需求，可以补齐任一套小程序转换其他平台的规则，就可以完成以某个小程序为标准为基础来编写小程序代码以及进一步转换成别的平台的能力。

再结合前面一直在说的我们对原生小程序的支持，就可以撞出一点不一样的东西，比如，前文提到的第三方组件库跨小程序平台。

对，我们能帮你把针对微信编写的ui组件库在支付宝、百度上运行起来，带着组件库一起跨小程序平台。

那么一定会有这样一个问题，就算MPX对原生的支持再怎么牛逼，有的基础能力只有微信平台有，别的平台没有，MPX的转换还能无中生有吗？

当然不能，其实这个问题对于所有的跨端框架都是一个问题，所以跨端最核心的问题是，如何搞定差异化部分。

MPX提供了丰富的条件编译能力，可以以文件为维度差别构建，可以以代码块为维度，也可以以代码维度进行差别构建。

而且MPX的差异化构建能力也是完全基于webpack实现的，所以上面提到的第三方组件库如果确实存在转换不了的地方，比如vant的picker组件使用内联wxs写了一个小方法叫isSimple在模板里调用了，但是这个方法的写法在百度小程序的filter脚本（filter可以理解为百度小程序的wxs）里不支持，因为百度的filter要求必须导出一个对象包裹方法。

最好的解决办法当然是给vant-weapp提pr帮他们解决一下这个问题，但时间可能会比较慢，所以在MPX里，可以利用webpack的alias能力：

![通过alias解决第三方组件的跨平台问题](https://dpubstatic.udache.com/static/dpubimg/7f90593b-65b4-40d0-bd93-6396e8a18e64.png)

当尝试构建百度小程序时，会优先去查找pick/index.swan.wxml，再被alias到一个src下的文件，自己修改一下第三方包里有一些小问题的部分即可。

关于跨平台的条件编译，更多具体信息可以[查阅我们的官方文档 - 跨平台编译](../guide/advance/platform.md#跨平台编译)

### 能力增强

> 通过数据响应、编译时预处理提供了computed/watch，完备的样式类型绑定，双向数据绑定，动态组件等一系列方便开发者更好开发小程序的能力增强

能力增强应该是一个框架提供的最核心最重要的能力了，而MPX也确实在这里下了很大的力气，提供了多且好用的能力增强，不过受限于此处的篇幅，就只简单介绍，细节大家还是[查阅我们的文档](../guide/basic/template.md)的好。

别的框架由于往往基于react/vue的，会给个列表写明不支持哪些能力，用户写的时候习惯使然，往往用了后可能才反应过来哦这个不支持。MPX则是原生的小程序语法写着难受时候突然想起MPX有这个能力。

列一下MPX增强的能力：

* 模板上的增强
  * 样式类名绑定
  * 内联事件传参
  * 动态组件
  * 双向绑定
  * 节点获取ref
* JS里的增强
  * 数据响应
  * setData优化
  * ES6+
* 样式上的增强
  * 预处理支持
  * rpx转换
* JSON里的增强
  * packages
  * 分包资源优化

MPX最显著的能力是数据响应，它衍生出computed/watch，以及双向数据绑定等。这个能力和Vue比较像，不同的是在MPX里是由mobx提供的数据响应能力。

而同样是数据响应，我们做了一些不一样的优化。

### 性能优势

> 通过对模板的解析抽象出访问的数据以保证在提供了数据响应能力的同时不至于劣化性能。

mpvue/wepy/megalo等框架也提供了数据响应的能力，但是数据响应在小程序领域有个较大的问题，微信开发指南里明确提到要注意setData的调用频次和数据量的大小。

而数据响应最基本的做法就是数据变了就去set数据，这会极大劣化小程序的性能表现。

而MPX通过对模板进行解析，抽象出对应的render函数，在调用setData发送数据前执行render函数找到真正需要发送的数据。

效果如图：

![小程序性能分析](https://dpubstatic.udache.com/static/dpubimg/9399b75c-5c81-4584-89b6-5e7f2c2ba7ba.png)

小程序开发者工具的audits面板能辅助用户分析出可能需要优化的点。正如前文所说，MPX在红框部分，尤其是红框里的第三条，不将模板上未使用的数据发送到渲染层上做了极大的优化。

只要不出现渲染函数执行失败（会有warning在console里提示，同时兜底逻辑会进行全量setData以保证程序仍可正常运行），使用MPX开发的小程序就永远不用担心发送了模板未使用的数据。

虽然只是一个小小的TODO MVC示例，但是这个优化和应用的规模没关系，而且同时大家可以尝试别家的小demo对比看看。

这个优化的细节可以看[前一篇文章](2.0.md)，或者我们的文档[MPX运行机制 - 数据响应与性能优化](../guide/understand/runtime.md)

## 总结 {#summary}

与目前市面上的诸多框架相比，MPX希望以原生小程序为基础，全面拥抱原生小程序，在原生小程序的基础上做增强，通过尽可能少的转换实现尽可能多的能力增强，在提升小程序开发体验的同时，保证不因转换或框架的问题产生过多的坑。

MPX框架的目标用户是对小程序质量有较高要求的开发者，如果你是原生小程序开发者，或者厌倦了解决某些以web框架DSL语法为基础的转换框架造成的坑，欢迎尝试MPX框架。

---

---
url: /articles/mpx2.md
---

# Mpx 小程序框架技术揭秘 {#mpx-tech-reveal}

> 作者：[CommanderXL](https://github.com/CommanderXL)

与目前业内的几个小程序框架相比较而言，mpx 开发设计的出发点就是基于原生的小程序去做功能增强。所以从开发框架的角度来说，是没有任何“包袱”，围绕着原生小程序这个 core 去做不同功能的 patch 工作，使得开发小程序的体验更好。

于是我挑了一些我非常感兴趣的点去学习了下 mpx 在相关功能上的设计与实现。

## 编译环节 {#compilation-phase}

### 动态入口编译 {#dynamic-entry-compilation}

不同于 web 规范，我们都知道小程序每个 page/component 需要被最终在 webview 上渲染出来的内容是需要包含这几个独立的文件的：js/json/wxml/wxss。为了提升小程序的开发体验，mpx 参考 vue 的 SFC(single file component)的设计思路，采用单文件的代码组织方式进行开发。既然采用这种方式去组织代码的话，那么模板、逻辑代码、json配置文件、style样式等都放到了同一个文件当中。那么 mpx 需要做的一个工作就是如何将 SFC 在代码编译后拆分为 js/json/wxml/wxss 以满足小程序技术规范。熟悉 vue 生态的同学都知道，vue-loader 里面就做了这样一个编译转化工作。具体有关 vue-loader 的工作流程可以参见我写的[文章](https://github.com/CommanderXL/Biu-blog/issues/33)。

这里会遇到这样一个问题，就是在 vue 当中，如果你要引入一个页面/组件的话，直接通过`import`语法去引入对应的 vue 文件即可。但是在小程序的标准规范里面，它有自己一套组件系统，即如果你在某个页面/组件里面想要使用另外一个组件，那么需要在你的 json 配置文件当中去声明`usingComponents`这个字段，对应的值为这个组件的路径。

在 vue 里面 import 一个 vue 文件，那么这个文件会被当做一个 dependency 去加入到 webpack 的编译流程当中。但是 mpx 是保持小程序原有的功能，去进行功能的增强。因此一个 mpx 文件当中如果需要引入其他页面/组件，那么就是遵照小程序的组件规范需要在`usingComponents`定义好`组件名:路径`即可，**mpx 提供的 webpack 插件来完成确定依赖关系，同时将被引入的页面/组件加入到编译构建的环节当中**。

接下来就来看下具体的实现，mpx webpack-plugin 暴露出来的插件上也提供了静态方法去使用 loader。这个 loader 的作用和 vue-loader 的作用类似，首先就是拿到 mpx 原始的文件后转化一个 js 文本的文件。例如一个 list.mpx 文件里面有关 json 的配置会被编译为：

```javascript
require("!!../../node_modules/@mpxjs/webpack-plugin/lib/extractor?type=json&index=0!../../node_modules/@mpxjs/webpack-plugin/lib/json-compiler/index?root=!../../node_modules/@mpxjs/webpack-plugin/lib/selector?type=json&index=0!./list.mpx")
```

这样可以清楚的看到 list.mpx 这个文件首先 selector(抽离`list.mpx`当中有关 json 的配置，并传入到 json-compiler 当中) --->>> json-compiler(对 json 配置进行处理，添加动态入口等) --->>> extractor(利用 child compiler 单独生成 json 配置文件)

其中动态添加入口的处理流程是在 json-compiler 当中去完成的。例如在你的 `page/home.mpx` 文件当中的 json 配置中使用了 局部组件 `components/list.mpx`:

```javascript
<script type="application/json">
  {
    "usingComponents": {
      "list": "../components/list"
    }
  }
</script>
```

在 json-compiler 当中：

```javascript
...

const addEntrySafely = (resource, name, callback) => {
  // 如果loader已经回调，就不再添加entry
  if (callbacked) return callback()
  // 使用 webpack 提供的 SingleEntryPlugin 插件创建一个单文件的入口依赖(即这个 component)
  const dep = SingleEntryPlugin.createDependency(resource, name)
  entryDeps.add(dep)
  // compilation.addEntry 方法开始将这个需要被编译的 component 作为依赖添加到 webpack 的构建流程当中
  // 这里可以看到的是整个动态添加入口文件的过程是深度优先的
  this._compilation.addEntry(this._compiler.context, dep, name, (err, module) => {
    entryDeps.delete(dep)
    checkEntryDeps()
    callback(err, module)
  })
}

const processComponent = (component, context, rewritePath, componentPath, callback) => {
  ...
  // 调用 loaderContext 上提供的 resolve 方法去解析这个 component path 完整的路径，以及这个 component 所属的 package 相关的信息(例如 package.json 等)
  this.resolve(context, component, (err, rawResult, info) => {
    ...
    componentPath = componentPath || path.join(subPackageRoot, 'components', componentName + hash(result), componentName)
    ...
    // component path 解析完之后，调用 addEntrySafely 开始在 webpack 构建流程中动态添加入口
    addEntrySafely(rawResult, componentPath, callback)
  })
}

if (isApp) {
  ...
} else {
  if (json.usingComponents) {
    // async.forEachOf 流程控制依次调用 processComponent 方法
    async.forEachOf(json.usingComponents, (component, name, callback) => {
      processComponent(component, this.context, (path) => {
        json.usingComponents[name] = path
      }, undefined, callback)
    }, callback)
  }
  ...
}
...
```

这里需要解释说明下有关 webpack 提供的 SingleEntryPlugin 插件。这个插件是 webpack 提供的一个内置插件，当这个插件被挂载到 webpack 的编译流程的过程中是，会绑定`compiler.hooks.make.tapAsync`hook，当这个 hook 触发后会调用这个插件上的 SingleEntryPlugin.createDependency 静态方法去创建一个入口依赖，然后调用`compilation.addEntry`将这个依赖加入到编译的流程当中，这个是单入口文件的编译流程的最开始的一个步骤(具体可以参见 [Webpack SingleEntryPlugin 源码](https://github.com/webpack/webpack/blob/master/lib/SingleEntryPlugin.js))。

Mpx 正是利用了 webpack 提供的这样一种能力，在遵照小程序的自定义组件的规范的前提下，解析 mpx json 配置文件的过程中，手动的调用 SingleEntryPlugin 相关的方法去完成动态入口的添加工作。这样也就串联起了所有的 mpx 文件的编译工作。

### Render Function

Render Function 这块的内容我觉得是 Mpx 设计上的一大亮点内容。Mpx 引入 Render Function 主要解决的问题是性能优化方向相关的，因为小程序的架构设计，逻辑层和渲染层是2个独立的。

这里直接引用 Mpx 有关 Render Function 对于性能优化相关开发工作的描述：

> 作为一个接管了小程序setData的数据响应开发框架，我们高度重视Mpx的渲染性能，通过小程序官方文档中提到的性能优化建议可以得知，setData对于小程序性能来说是重中之重，setData优化的方向主要有两个：

> * 尽可能减少setData调用的频次
> * 尽可能减少单次setData传输的数据
>   为了实现以上两个优化方向，我们做了以下几项工作：

> 将组件的静态模板编译为可执行的render函数，通过render函数收集模板数据依赖，只有当render函数中的依赖数据发生变化时才会触发小程序组件的setData，同时通过一个异步队列确保一个tick中最多只会进行一次setData，这个机制和Vue中的render机制非常类似，大大降低了setData的调用频次；

> 将模板编译render函数的过程中，我们还记录输出了模板中使用的数据路径，在每次需要setData时会根据这些数据路径与上一次的数据进行diff，仅将发生变化的数据通过数据路径的方式进行setData，这样确保了每次setData传输的数据量最低，同时避免了不必要的setData操作，进一步降低了setData的频次。

接下来我们看下 Mpx 是如何实现 Render Function 的。这里我们从一个简单的 demo 来说起：

```html
<template>
  <text>Computed reversed message: "{{ reversedMessage }}"</text>
  <view>the c string {{ demoObj.a.b.c }}</view>
  <view wx:class="{{ { active: isActive } }}"></view>
</template>

<script>
import { createComponent } from "@mpxjs/core";

createComponent({
  data: {
    isActive: true,
    message: 'messages',
    demoObj: {
      a: {
        b: {
          c: 'c'
        }
      }
    }
  },
  computed() {
    reversedMessage() {
      return this.message.split('').reverse().join('')
    }
  }
})
</script>
```

`.mpx` 文件经过 loader 编译转换的过程中。对于 template 模块的处理和 vue 类似，首先将 template 转化为 AST，然后再将 AST 转化为 code 的过程中做相关转化的工作，最终得到我们需要的 template 模板代码。

在`packages/webpack-plugin/lib/template-compiler.js`模板处理 loader 当中:

```javascript
let renderResult = bindThis(`global.currentInject = {
    moduleId: ${JSON.stringify(options.moduleId)},
    render: function () {
      var __seen = [];
      var renderData = {};
      ${compiler.genNode(ast)}return renderData;
    }
};\n`, {
    needCollect: true,
    ignoreMap: meta.wxsModuleMap
  })
```

在 render 方法内部，创建 renderData 局部变量，调用`compiler.genNode(ast)`方法完成 Render Function 核心代码的生成工作，最终将这个 renderData 返回。例如在上面给出来的 demo 实例当中，通过`compiler.genNode(ast)`方法最终生成的代码为：

```javascript
((mpxShow)||(mpxShow)===undefined?'':'display:none;');
if(( isActive )){
}
"Computed reversed message: \""+( reversedMessage )+"\"";
"the c string "+( demoObj.a.b.c );
(__injectHelper.transformClass("list", ( {active: isActive} )));
```

mpx 文件当中的 template 模块被初步处理成上面的代码后，可以看到这是一段可执行的 js 代码。那么这段 js 代码到底是用作何处呢？可以看到`compiler.genNode`方法是被包裹至`bindThis`方法当中的。即这段 js 代码还会被`bindThis`方法做进一步的处理。打开 bind-this.js 文件可以看到内部的实现其实就是一个 babel 的 transform plugin。在处理上面这段 js 代码的 AST 的过程中，通过这个插件对 js 代码做进一步的处理。最终这段 js 代码处理后的结果是：

```javascript
/* mpx inject */ global.currentInject = {
  moduleId: "2271575d",
  render: function () {
    var __seen = [];
    var renderData = {};
    (renderData["mpxShow"] = [this.mpxShow, "mpxShow"], this.mpxShow) || (renderData["mpxShow"] = [this.mpxShow, "mpxShow"], this.mpxShow) === undefined ? '' : 'display:none;';
    "Computed reversed message: \"" + (renderData["reversedMessage"] = [this.reversedMessage, "reversedMessage"], this.reversedMessage) + "\"";
    "the c string " + (renderData["demoObj.a.b.c"] = [this.demoObj.a.b.c, "demoObj"], this.__get(this.__get(this.__get(this.demoObj, "a"), "b"), "c"));
    this.__get(__injectHelper, "transformClass")("list", { active: (renderData["isActive"] = [this.isActive, "isActive"], this.isActive) });
    return renderData;
  }
};
```

bindThis 方法对于 js 代码的转化规则就是：

1. 一个变量的访问形式，改造成 this.xxx 的形式；
2. 对象属性的访问形式，改造成 this.\_\_get(object, property) 的形式(this.\_\_get方法为运行时 mpx runtime 提供的方法)

这里的 this 为 mpx 构造的一个代理对象，在你业务代码当中调用 createComponent/createPage 方法传入的配置项，例如 data，都会通过这个代理对象转化为响应式的数据。

需要注意的是不管哪种数据形式的改造，最终需要达到的效果就是确保在 Render Function 执行的过程当中，这些被模板使用到的数据能被正常的访问到，在访问的阶段中，这些被访问到的数据即被加入到 mpx 构建的整个响应式的系统当中。

只要在 template 当中使用到的 data 数据(包括衍生的 computed 数据)，最终都会被 renderData 所记录，而记录的数据形式是例如：

```javascript
renderData['xxx'] = [this.xxx, 'xxx'] // 数组的形式，第一项为这个数据实际的值，第二项为这个数据的 firstKey(主要用以数据 diff 的工作)
```

以上就是 mpx 生成 Render Function 的整个过程。总结下 Render Function 所做的工作：

1. 执行 render 函数，将渲染模板使用到的数据加入到响应式的系统当中；
2. 返回 renderData 用以接下来的数据 diff 以及调用小程序的 setData 方法来完成视图的更新

### Wxs Module

Wxs 是小程序自己推出的一套脚本语言。[官方文档](https://developers.weixin.qq.com/miniprogram/dev/reference/wxs/01wxs-module.html)给出的示例，wxs 模块必须要声明式的被 wxml 引用。和 js 在 jsCore 当中去运行不同的是 wxs 是在渲染线程当中去运行的。因此 wxs 的执行便少了一次从 jsCore 执行的线程和渲染线程的通讯，从这个角度来说是对代码执行效率和性能上的比较大的一个优化手段。

有关官方提到的有关 wxs 的运行效率的问题还有待论证：

> “在 android 设备中，小程序里的 wxs 与 js 运行效率无差异，而在 ios 设备中，小程序里的 wxs 会比 js 快 2~20倍。”

因为 mpx 是对小程序做渐进增强，因此 wxs 的使用方式和原生的小程序保持一致。在你的`.mpx`文件当中的 template block 内通过路径直接去引入 wxs 模块即可使用：

```html
<template>
  <wxs src="../wxs/components/list.wxs" module="list">
  <view>{{ list.FOO }}</view>
</template>
```

```js
// wxs/components/list.wxs
const Foo = 'This is from list wxs module'
module.exports = {
  Foo
}
```

在 template 模块经过 template-compiler 处理的过程中。模板编译器 compiler 在解析模板的 AST 过程中会针对 wxs 标签缓存一份 wxs 模块的映射表：

```javascript
{
  meta: {
    wxsModuleMap: {
      list: '../wxs/components/list.wxs'
    }
  }
}
```

当 compiler 对 template 模板解析完后，template-compiler 接下来就开始处理 wxs 模块相关的内容：

```javascript
// template-compiler/index.js

module.exports = function (raw) {
  ...

  const addDependency = dep => {
    const resourceIdent = dep.getResourceIdentifier()
    if (resourceIdent) {
      const factory = compilation.dependencyFactories.get(dep.constructor)
      if (factory === undefined) {
        throw new Error(`No module factory available for dependency type: ${dep.constructor.name}`)
      }
      let innerMap = dependencies.get(factory)
      if (innerMap === undefined) {
        dependencies.set(factory, (innerMap = new Map()))
      }
      let list = innerMap.get(resourceIdent)
      if (list === undefined) innerMap.set(resourceIdent, (list = []))
      list.push(dep)
    }
  }

  // 如果有 wxsModuleMap 即为 wxs module 依赖的话，那么下面会调用 compilation.addModuleDependencies 方法
  // 将 wxsModule 作为 issuer 的依赖再次进行编译，最终也会被打包进输出的模块代码当中
  // 需要注意的就是 wxs module 不仅要被注入到 bundle 里的 render 函数当中，同时也会通过 wxs-loader 处理，单独输出一份可运行的 wxs js 文件供 wxml 引入使用
  for (let module in meta.wxsModuleMap) {
    isSync = false
    let src = meta.wxsModuleMap[module]
    const expression = `require(${JSON.stringify(src)})`
    const deps = []
    // parser 为 js 的编译器
    parser.parse(expression, {
      current: { // 需要注意的是这里需要部署 addDependency 接口，因为通过 parse.parse 对代码进行编译的时候，会调用这个接口来获取 require(${JSON.stringify(src)}) 编译产生的依赖模块
        addDependency: dep => {
          dep.userRequest = module
          deps.push(dep)
        }
      },
      module: issuer
    })
    issuer.addVariable(module, expression, deps) // 给 issuer module 添加 variable 依赖
    iterationOfArrayCallback(deps, addDependency)
  }

  // 如果没有 wxs module 的处理，那么 template-compiler 即为同步任务，否则为异步任务
  if (isSync) {
    return result
  } else {
    const callback = this.async()

    const sortedDependencies = []
    for (const pair1 of dependencies) {
      for (const pair2 of pair1[1]) {
        sortedDependencies.push({
          factory: pair1[0],
          dependencies: pair2[1]
        })
      }
    }

    // 调用 compilation.addModuleDependencies 方法，将 wxs module 作为 issuer module 的依赖加入到编译流程中
    compilation.addModuleDependencies(
      issuer,
      sortedDependencies,
      compilation.bail,
      null,
      true,
      () => {
        callback(null, result)
      }
    )
  }
}
```

### template/script/style/json 模块单文件的生成 {#single-file-generation}

不同于 Vue 借助 webpack 是将 Vue 单文件最终打包成单独的 js chunk 文件。而小程序的规范是每个页面/组件需要对应的 wxml/js/wxss/json 4个文件。因为 mpx 使用单文件的方式去组织代码，所以在编译环节所需要做的工作之一就是将 mpx 单文件当中不同 block 的内容拆解到对应文件类型当中。在动态入口编译的小节里面我们了解到 mpx 会分析每个 mpx 文件的引用依赖，从而去给这个文件创建一个 entry 依赖(SingleEntryPlugin)并加入到 webpack 的编译流程当中。我们还是继续看下 mpx loader 对于 mpx 单文件初步编译转化后的内容：

```javascript
/* script */
export * from "!!babel-loader!../../node_modules/@mpxjs/webpack-plugin/lib/selector?type=script&index=0!./list.mpx"

/* styles */
require("!!../../node_modules/@mpxjs/webpack-plugin/lib/extractor?type=styles&index=0!../../node_modules/@mpxjs/webpack-plugin/lib/wxss/loader?root=&importLoaders=1&extract=true!../../node_modules/@mpxjs/webpack-plugin/lib/style-compiler/index?{\"id\":\"2271575d\",\"scoped\":false,\"sourceMap\":false,\"transRpx\":{\"mode\":\"only\",\"comment\":\"use rpx\",\"include\":\"/Users/XRene/demo/mpx-demo-source/src\"}}!stylus-loader!../../node_modules/@mpxjs/webpack-plugin/lib/selector?type=styles&index=0!./list.mpx")

/* json */
require("!!../../node_modules/@mpxjs/webpack-plugin/lib/extractor?type=json&index=0!../../node_modules/@mpxjs/webpack-plugin/lib/json-compiler/index?root=!../../node_modules/@mpxjs/webpack-plugin/lib/selector?type=json&index=0!./list.mpx")

/* template */
require("!!../../node_modules/@mpxjs/webpack-plugin/lib/extractor?type=template&index=0!../../node_modules/@mpxjs/webpack-plugin/lib/wxml/wxml-loader?root=!../../node_modules/@mpxjs/webpack-plugin/lib/template-compiler/index?{\"usingComponents\":[],\"hasScoped\":false,\"isNative\":false,\"moduleId\":\"2271575d\"}!../../node_modules/@mpxjs/webpack-plugin/lib/selector?type=template&index=0!./list.mpx")
```

接下来可以看下 styles/json/template 这3个 block 的处理流程是什么样。

首先来看下 json block 的处理流程：`list.mpx -> json-compiler -> extractor`。第一个阶段 list.mpx 文件经由 json-compiler 的处理流程在前面的章节已经讲过，主要就是分析依赖增加动态入口的编译过程。当所有的依赖分析完后，调用 json-compiler loader 的异步回调函数：

```javascript
// lib/json-compiler/index.js

module.exports = function (content) {

  ...
  const nativeCallback = this.async()
  ...

  let callbacked = false
  const callback = (err, processOutput) => {
    checkEntryDeps(() => {
      callbacked = true
      if (err) return nativeCallback(err)
      let output = `var json = ${JSON.stringify(json, null, 2)};\n`
      if (processOutput) output = processOutput(output)
      output += `module.exports = JSON.stringify(json, null, 2);\n`
      nativeCallback(null, output)
    })
  }
}
```

这里我们可以看到经由 json-compiler 处理后，通过`nativeCallback`方法传入下一个 loader 的文本内容形如：

```javascript
var json = {
  "usingComponents": {
    "list": "/components/list397512ea/list"
  }
}

module.exports = JSON.stringify(json, null, 2)
```

即这段文本内容会传递到下一个 loader 内部进行处理，即 extractor。接下来我们来看下 extractor 里面主要是实现了哪些功能：

```javascript
// lib/extractor.js

module.exports = function (content) {
  ...
  const contentLoader = normalize.lib('content-loader')
  let request = `!!${contentLoader}?${JSON.stringify(options)}!${this.resource}` // 构建一个新的 resource，且这个 resource 只需要经过 content-loader
  let resultSource = defaultResultSource
  const childFilename = 'extractor-filename'
  const outputOptions = {
    filename: childFilename
  }
  // 创建一个 child compiler
  const childCompiler = mainCompilation.createChildCompiler(request, outputOptions, [
    new NodeTemplatePlugin(outputOptions),
    new LibraryTemplatePlugin(null, 'commonjs2'), // 最终输出的 chunk 内容遵循 commonjs 规范的可执行的模块代码 module.exports = (function(modules) {})([modules])
    new NodeTargetPlugin(),
    new SingleEntryPlugin(this.context, request, resourcePath),
    new LimitChunkCountPlugin({ maxChunks: 1 })
  ])

  ...
  childCompiler.hooks.thisCompilation.tap('MpxWebpackPlugin ', (compilation) => {
    // 创建 loaderContext 时触发的 hook，在这个 hook 触发的时候，将原本从 json-compiler 传递过来的 content 内容挂载至 loaderContext.__mpx__ 属性上面以供接下来的 content -loader 来进行使用
    compilation.hooks.normalModuleLoader.tap('MpxWebpackPlugin', (loaderContext, module) => {
      // 传递编译结果，子编译器进入content-loader后直接输出
      loaderContext.__mpx__ = {
        content,
        fileDependencies: this.getDependencies(),
        contextDependencies: this.getContextDependencies()
      }
    })
  })

  let source

  childCompiler.hooks.afterCompile.tapAsync('MpxWebpackPlugin', (compilation, callback) => {
    // 这里 afterCompile 产出的 assets 的代码当中是包含 webpack runtime bootstrap 的代码，不过需要注意的是这个 source 模块的产出形式
    // 因为使用了 new LibraryTemplatePlugin(null, 'commonjs2') 等插件。所以产出的 source 是可以在 node 环境下执行的 module
    // 因为在 loaderContext 上部署了 exec 方法，即可以直接执行 commonjs 规范的 module 代码，这样就最终完成了 mpx 单文件当中不同模块的抽离工作
    source = compilation.assets[childFilename] && compilation.assets[childFilename].source()

    // Remove all chunk assets
    compilation.chunks.forEach((chunk) => {
      chunk.files.forEach((file) => {
        delete compilation.assets[file]
      })
    })

    callback()
  })

  childCompiler.runAsChild((err, entries, compilation) => {
    ...
    try {
      // exec 是 loaderContext 上提供的一个方法，在其内部会构建原生的 node.js module，并执行这个 module 的代码
      // 执行这个 module 代码后获取的内容就是通过 module.exports 导出的内容
      let text = this.exec(source, request)
      if (Array.isArray(text)) {
        text = text.map((item) => {
          return item[1]
        }).join('\n')
      }

      let extracted = extract(text, options.type, resourcePath, +options.index, selfResourcePath)
      if (extracted) {
        resultSource = `module.exports = __webpack_public_path__ + ${JSON.stringify(extracted)};`
      }
    } catch (err) {
      return nativeCallback(err)
    }
    if (resultSource) {
      nativeCallback(null, resultSource)
    } else {
      nativeCallback()
    }
  })
}
```

稍微总结下上面的处理流程：

1. 构建一个以当前模块路径及 content-loader 的 resource 路径
2. 以这个 resource 路径作为入口模块，创建一个 childCompiler
3. childCompiler 启动后，创建 loaderContext 的过程中，将 content 文本内容挂载至 loaderContext.**mpx** 上，这样在 content-loader 在处理入口模块的时候仅仅就是取出这个 content 文本内容并返回。实际上这个入口模块经过 loader 的过程不会做任何的处理工作，仅仅是将父 compilation 传入的 content 返回出去。
4. loader 处理模块的环节结束后，进入到 module.build 阶段，这个阶段对 content 内容没有太多的处理
5. createAssets 阶段，输出 chunk。
6. 将输出的 chunk 构建为一个原生的 node.js 模块并执行，获取从这个 chunk 导出的内容。也就是模块通过`module.exports`导出的内容。

所以上面的示例 demo 最终会输出一个 json 文件，里面包含的内容即为：

```javascript
{
  "usingComponents": {
    "list": "/components/list397512ea/list"
  }
}
```

## 运行时环节 {#runtime-phase}

以上几个章节主要是分析了几个 Mpx 在编译构建环节所做的工作。接下来我们来看下 Mpx 在运行时环节做了哪些工作。

### 响应式系统 {#reactivity-system}

小程序也是通过数据去驱动视图的渲染，需要手动的调用`setData`去完成这样一个动作。同时小程序的视图层也提供了用户交互的响应事件系统，在 js 代码中可以去注册相关的事件回调并在回调中去更改相关数据的值。Mpx 使用 Mobx 作为响应式数据工具并引入到小程序当中，使得小程序也有一套完成的响应式的系统，让小程序的开发有了更好的体验。

还是从组件的角度开始分析 mpx 的整个响应式的系统。每次通过`createComponent`方法去创建一个新的组件，这个方法将原生的小程序创造组件的方法`Component`做了一层代理，例如在 attched 的生命周期钩子函数内部会注入一个 mixin：

```javascript
// attached 生命周期钩子 mixin

attached() {
  // 提供代理对象需要的api
  transformApiForProxy(this, currentInject)
  // 缓存options
  this.$rawOptions = rawOptions // 原始的，没有剔除 customKeys 的 options 配置
  // 创建proxy对象
  const mpxProxy = new MPXProxy(rawOptions, this) // 将当前实例代理到 MPXProxy 这个代理对象上面去
  this.$mpxProxy = mpxProxy // 在小程序实例上绑定 $mpxProxy 的实例
  // 组件监听视图数据更新, attached之后才能拿到properties
  this.$mpxProxy.created()
}
```

在这个方法内部首先调用`transformApiForProxy`方法对组件实例上下文`this`做一层代理工作，在 context 上下文上去重置小程序的 setData 方法，同时拓展 context 相关的属性内容：

```javascript
function transformApiForProxy (context, currentInject) {
  const rawSetData = context.setData.bind(context) // setData 绑定对应的 context 上下文
  Object.defineProperties(context, {
    setData: { // 重置 context 的 setData 方法
      get () {
        return this.$mpxProxy.setData.bind(this.$mpxProxy)
      },
      configurable: true
    },
    __getInitialData: {
      get () {
        return () => context.data
      },
      configurable: false
    },
    __render: { // 小程序原生的 setData 方法
      get () {
        return rawSetData
      },
      configurable: false
    }
  })
  // context 绑定注入的render函数
  if (currentInject) {
    if (currentInject.render) { // 编译过程中生成的 render 函数
      Object.defineProperties(context, {
        __injectedRender: {
          get () {
            return currentInject.render.bind(context)
          },
          configurable: false
        }
      })
    }
    if (currentInject.getRefsData) {
      Object.defineProperties(context, {
        __getRefsData: {
          get () {
            return currentInject.getRefsData
          },
          configurable: false
        }
      })
    }
  }
}
```

接下来实例化一个 mpxProxy 实例并挂载至 context 上下文的 $mpxProxy 属性上，并调用 mpxProxy 的 created 方法完成这个代理对象的初始化的工作。在 created 方法内部主要是完成了以下的几个工作：

1. initApi，在组件实例 this 上挂载`$watch`,`$forceUpdate`,`$updated`,`$nextTick`等方法，这样在你的业务代码当中即可直接访问实例上部署好的这些方法；
2. initData
3. initComputed，将 computed 计算属性字段全部代理至组件实例 this 上；
4. 通过 Mobx observable 方法将 data 数据转化为响应式的数据；
5. initWatch，初始化所有的 watcher 实例；
6. initRender，初始化一个 renderWatcher 实例；

这里我们具体的来看下 initRender 方法内部是如何进行工作的：

```javascript
export default class MPXProxy {
  ...
  initRender() {
    let renderWatcher
    let renderExcutedFailed = false
    if (this.target.__injectedRender) { // webpack 注入的有关这个 page/component 的 renderFunction
      renderWatcher = watch(this.target, () => {
        if (renderExcutedFailed) {
          this.render()
        } else {
          try {
            return this.target.__injectedRender() // 执行 renderFunction，获取渲染所需的响应式数据
          } catch(e) {
            ...
          }
        }
      }, {
        handler: (ret) => {
          if (!renderExcutedFailed) {
            this.renderWithData(ret) // 渲染页面
          }
        },
        immediate: true,
        forceCallback: true
      })
    }
  }
  ...
}
```

在 initRender 方法内部非常清楚的看到，首先判断这个 page/component 是否具有 renderFunction，如果有的话那么就直接实例化一个 renderWatcher：

```javascript
export default class Watcher {
  constructor (context, expr, callback, options) {
    this.destroyed = false
    this.get = () => {
      return type(expr) === 'String' ? getByPath(context, expr) : expr()
    }
    const callbackType = type(callback)
    if (callbackType === 'Object') {
      options = callback
      callback = null
    } else if (callbackType === 'String') {
      callback = context[callback]
    }
    this.callback = typeof callback === 'function' ? action(callback.bind(context)) : null
    this.options = options || {}
    this.id = ++uid
    // 创建一个新的 reaction
    this.reaction = new Reaction(`mpx-watcher-${this.id}`, () => {
      this.update()
    })
    // 在调用 getValue 函数的时候，实际上是调用 reaction.track 方法，这个方法内部会自动执行 effect 函数，即执行 this.update() 方法，这样便会出发一次模板当中的 render 函数来完成依赖的收集
    const value = this.getValue()
    if (this.options.immediateAsync) { // 放置到一个队列里面去执行
      queueWatcher(this)
    } else { // 立即执行 callback
      this.value = value
      if (this.options.immediate) {
        this.callback && this.callback(this.value)
      }
    }
  }

  getValue () {
    let value
    this.reaction.track(() => {
      value = this.get() // 获取注入的 render 函数执行后返回的 renderData 的值，在执行 render 函数的过程中，就会访问响应式数据的值
      if (this.options.deep) {
        const valueType = type(value)
        // 某些情况下，最外层是非isObservable 对象，比如同时观察多个属性时
        if (!isObservable(value) && (valueType === 'Array' || valueType === 'Object')) {
          if (valueType === 'Array') {
            value = value.map(item => toJS(item, false))
          } else {
            const newValue = {}
            Object.keys(value).forEach(key => {
              newValue[key] = toJS(value[key], false)
            })
            value = newValue
          }
        } else {
          value = toJS(value, false)
        }
      } else if (isObservableArray(value)) {
        value.peek()
      } else if (isObservableObject(value)) {
        keys(value)
      }
    })
    return value
  }

  update () {
    if (this.options.sync) {
      this.run()
    } else {
      queueWatcher(this)
    }
  }

  run () {
    const immediateAsync = !this.hasOwnProperty('value')
    const oldValue = this.value
    this.value = this.getValue() // 重新获取新的 renderData 的值
    if (immediateAsync || this.value !== oldValue || isObject(this.value) || this.options.forceCallback) {
      if (this.callback) {
        immediateAsync ? this.callback(this.value) : this.callback(this.value, oldValue)
      }
    }
  }

  destroy () {
    this.destroyed = true
    this.reaction.getDisposer()()
  }
}
```

Watcher 观察者核心实现的工作流程就是：

1. 构建一个 Reaction 实例；
2. 调用 getValue 方法，即 reaction.track，在这个方法内部执行过程中会调用 renderFunction，这样在 renderFunction 方法的执行过程中便会访问到渲染所需要的响应式的数据并完成依赖收集；
3. 根据 immediateAsync 配置来决定回调是放到下一帧还是立即执行；
4. 当响应式数据发生变化的时候，执行 reaction 实例当中的回调函数，即`this.update()`方法来完成页面的重新渲染。

mpx 在构建这个响应式的系统当中，主要有2个大的环节，其一为在构建编译的过程中，将 template 模块转化为 renderFunction，提供了渲染模板时所需响应式数据的访问机制，并将 renderFunction 注入到运行时代码当中，其二就是在运行环节，mpx 通过构建一个小程序实例的代理对象，将小程序实例上的数据访问全部代理至 MPXProxy 实例上，而 MPXProxy 实例即 mpx 基于 Mobx 去构建的一套响应式数据对象，首先将 data 数据转化为响应式数据，其次提供了 computed 计算属性，watch 方法等一系列增强的拓展属性/方法，虽然在你的业务代码当中 page/component 实例 this 都是小程序提供的，但是最终经过代理机制，实际上访问的是 MPXProxy 所提供的增强功能，所以 mpx 也是通过这样一个代理对象去接管了小程序的实例。需要特别指出的是，mpx 将小程序官方提供的 setData 方法同样收敛至内部，这也是响应式系统提供的基础能力，即开发者只需要关注业务开发，而有关小程序渲染运行在 mpx 内部去帮你完成。

## 性能优化 {#performance-optimization}

由于小程序的双线程的架构设计，逻辑层和视图层之间需要桥接 native bridge。如果要完成视图层的更新，那么逻辑层需要调用 setData 方法，数据经由 native bridge，再到渲染层，这个工程流程为：

> 小程序逻辑层调用宿主环境的 setData 方法；

> 逻辑层执行 JSON.stringify 将待传输数据转换成字符串并拼接到特定的JS脚本，并通过evaluateJavascript 执行脚本将数据传输到渲染层；

> 渲染层接收到后， WebView JS 线程会对脚本进行编译，得到待更新数据后进入渲染队列等待 WebView 线程空闲时进行页面渲染；

> WebView 线程开始执行渲染时，待更新数据会合并到视图层保留的原始 data 数据，并将新数据套用在WXML片段中得到新的虚拟节点树。经过新虚拟节点树与当前节点树的 diff 对比，将差异部分更新到UI视图。同时，将新的节点树替换旧节点树，用于下一次重渲染。

[文章来源](https://mp.weixin.qq.com/s?__biz=MjM5MTA1MjAxMQ==\&mid=2651232791\&idx=1\&sn=4b83b66d376b1331a992d242cb2a0f17\&chksm=bd4943938a3eca853a687765397517cc0ab9cfe4c711705e8fd821bbea8a1ab3c115c8c2fc65\&scene=21#wechat_redirect)

而 setData 作为逻辑层和视图层之间通讯的核心接口，那么对于这个接口的使用遵照一些准则将有助于性能方面的提升。

### 尽可能的减少 setData 传输的数据 {#reduce-setdata-data}

Mpx 在这个方面所做的工作之一就是基于数据路径的 diff。这也是官方所推荐的 setData 的方式。每次响应式数据发生了变化，调用 setData 方法的时候确保传递的数据都为 diff 过后的最小数据集，这样来减少 setData 传输的数据。

接下来我们就来看下这个优化手段的具体实现思路，首先还是从一个简单的 demo 来看：

```javascript
<script>
import { createComponent } from '@mpxjs/core'

createComponent({
  data: {
    obj: {
      a: {
        c: 1,
        d: 2
      }
    }
  }
  onShow() {
    setTimeout(() => {
      this.obj.a = {
        c: 1,
        d: 'd'
      }
    }, 200)
  }
})
</script>
```

在示例 demo 当中，声明了一个 obj 对象(这个对象里面的内容在模块当中被使用到了)。然后经过 200ms 后，手动修改 obj.a 的值，因为对于 c 字段来说它的值没有发生改变，而 d 字段发生了改变。因此在 setData 方法当中也应该只更新 obj.a.d 的值，即：

```javascript
this.setData('obj.a.d', 'd')
```

因为 mpx 是整体接管了小程序当中有关调用 setData 方法并驱动视图更新的机制。所以当你在改变某些数据的时候，mpx 会帮你完成数据的 diff 工作，以保证每次调用 setData 方法时，传入的是最小的更新数据集。

这里也简单的分析下 mpx 是如何去实现这样的功能的。在上文的编译构建阶段有分析到 mpx 生成的 Render Function，这个 Render Function 每次执行的时候会返回一个 renderData，而这个 renderData 即用以接下来进行 setData 驱动视图渲染的原始数据。renderData 的数据组织形式是模板当中使用到的数据路径作为 key 键值，对应的值使用一个数组组织，数组第一项为数据的访问路径(可获取到对应渲染数据)，第二项为数据路径的第一个键值，例如在 demo 示例当中的 renderData 数据如下：

```javascript
renderData['obj.a.c'] = [this.obj.a.c, 'obj']
renderData['obj.a.d'] = [this.obj.a.d, 'obj']
```

当页面第一次渲染，或者是响应式输出发生变化的时候，Render Function 都会被执行一次用以获取最新的 renderData 来进行接下来的页面渲染过程。

```javascript
// src/core/proxy.js

class MPXProxy {
  ...
  renderWithData(rawRenderData) { // rawRenderData 即为 Render Function 执行后获取的初始化 renderData
    const renderData = preprocessRenderData(rawRenderData) // renderData 数据的预处理
    if (!this.miniRenderData) { // 最小数据渲染集，页面/组件初次渲染的时候使用 miniRenderData 进行渲染，初次渲染的时候是没有数据需要进行 diff 的
      this.miniRenderData = {}
      for (let key in renderData) { // 遍历数据访问路径
        if (renderData.hasOwnProperty(key)) {
          let item = renderData[key]
          let data = item[0]
          let firstKey = item[1] // 某个字段 path 的第一个 key 值
          if (this.localKeys.indexOf(firstKey) > -1) {
            this.miniRenderData[key] = diffAndCloneA(data).clone
          }
        }
      }
      this.doRender(this.miniRenderData)
    } else { // 非初次渲染使用 processRenderData 进行数据的处理，主要是需要进行数据的 diff 取值工作，并更新 miniRenderData 的值
      this.doRender(this.processRenderData(renderData))
    }
  }

  processRenderData(renderData) {
    let result = {}
    for (let key in renderData) {
      if (renderData.hasOwnProperty(key)) {
        let item = renderData[key]
        let data = item[0]
        let firstKey = item[1]
        let { clone, diff } = diffAndCloneA(data, this.miniRenderData[key]) // 开始数据 diff
        // firstKey 必须是为响应式数据的 key，且这个发生变化的 key 为 forceUpdateKey 或者是在 diff 阶段发现确实出现了 diff 的情况
        if (this.localKeys.indexOf(firstKey) > -1 && (this.checkInForceUpdateKeys(key) || diff)) {
          this.miniRenderData[key] = result[key] = clone
        }
      }
    }
    return result
  }
  ...
}

// src/helper/utils.js

// 如果 renderData 里面即包含对某个 key 的访问，同时还有对这个 key 的子节点访问的话，那么需要剔除这个子节点
/**
 * process renderData, remove sub node if visit parent node already
 * @param {Object} renderData
 * @return {Object} processedRenderData
 */
export function preprocessRenderData (renderData) {
  // method for get key path array
  const processKeyPathMap = (keyPathMap) => {
    let keyPath = Object.keys(keyPathMap)
    return keyPath.filter((keyA) => {
      return keyPath.every((keyB) => {
        if (keyA.startsWith(keyB) && keyA !== keyB) {
          let nextChar = keyA[keyB.length]
          if (nextChar === '.' || nextChar === '[') {
            return false
          }
        }
        return true
      })
    })
  }

  const processedRenderData = {}
  const renderDataFinalKey = processKeyPathMap(renderData) // 获取最终需要被渲染的数据的 key
  Object.keys(renderData).forEach(item => {
    if (renderDataFinalKey.indexOf(item) > -1) {
      processedRenderData[item] = renderData[item]
    }
  })
  return processedRenderData
}
```

其中在 processRenderData 方法内部调用了 diffAndCloneA 方法去完成数据的 diff 工作。在这个方法内部判断新、旧值是否发生变化，返回的 diff 字段即表示是否发生了变化，clone 为 diffAndCloneA 接受到的第一个数据的深拷贝值。

这里大致的描述下相关流程：

1. 响应式的数据发生了变化，触发 Render Function 重新执行，获取最新的 renderData；
2. renderData 的预处理，主要是用以剔除通过路径访问时同时有父、子路径情况下的子路径的 key；
3. 判断是否存在 miniRenderData 最小数据渲染集，如果没有那么 Mpx 完成 miniRenderData 最小渲染数据集的收集，如果有那么使用处理后的 renderData 和 miniRenderData 进行数据的 diff 工作(diffAndCloneA)，并更新最新的 miniRenderData 的值；
4. 调用 doRender 方法，进入到 setData 阶段

相关参阅文档：

* [Page](https://developers.weixin.qq.com/miniprogram/dev/reference/api/Page.html#Page.prototype.setData\(Object%20data,%20Function%20callback\))

### 尽可能的减少 setData 的调用频次 {#reduce-setdata-frequency}

每次调用 setData 方法都会完成一次从逻辑层 -> native bridge -> 视图层的通讯，并完成页面的更新。因此频繁的调用 setData 方法势必也会造成视图的多次渲染，用户的交互受阻。所以对于 setData 方法另外一个优化角度就是尽可能的减少 setData 的调用频次，将多个同步的 setData 操作合并到一次调用当中。接下来就来看下 mpx 在这方面是如何做优化的。

还是先来看一个简单的 demo:

```javascript
<script>
import { createComponent } from '@mpxjs/core'

createComponent({
  data: {
    msg: 'hello',
    obj: {
      a: {
        c: 1,
        d: 2
      }
    }
  }
  watch: {
    obj: {
      handler() {
        this.msg = 'world'
      },
      deep: true
    }
  },
  onShow() {
    setTimeout(() => {
      this.obj.a = {
        c: 1,
        d: 'd'
      }
    }, 200)
  }
})
</script>
```

在示例 demo 当中，msg 和 obj 都作为模板依赖的数据，这个组件开始展示后的 200ms，更新 obj.a 的值，同时 obj 被 watch，当 obj 发生改变后，更新 msg 的值。这里的逻辑处理顺序是：

```javascript
obj.a 变化 -> 将 renderWatch 加入到执行队列 -> 触发 obj watch -> 将 obj watch 加入到执行队列 -> 将执行队列放到下一帧执行 -> 按照 watch id 从小到大依次执行 watch.run -> setData 方法调用一次(即 renderWatch 回调)，统一更新 obj.a 及 msg -> 视图重新渲染
```

接下来就来具体看下这个流程：由于 obj 作为模板渲染的依赖数据，自然会被这个组件的 renderWatch 作为依赖而被收集。当 obj 的值发生变化后，首先触发 reaction 的回调，即 `this.update()` 方法，如果是个同步的 watch，那么立即调用 `this.run()` 方法，即 watcher 监听的回调方法，否则就通过 `queueWatcher(this)` 方法将这个 watcher 加入到执行队列：

```javascript
// src/core/watcher.js
export default Watcher {
  constructor (context, expr, callback, options) {
    ...
    this.id = ++uid
    this.reaction = new Reaction(`mpx-watcher-${this.id}`, () => {
      this.update()
    })
    ...
  }

  update () {
    if (this.options.sync) {
      this.run()
    } else {
      queueWatcher(this)
    }
  }
}
```

而在 queueWatcher 方法中，lockTask 维护了一个异步锁，即将 flushQueue 当成微任务统一放到下一帧去执行。所以在 flushQueue 开始执行之前，还会有同步的代码将 watcher 加入到执行队列当中，当 flushQueue 开始执行的时候，依照 watcher.id 升序依次执行，这样去确保 renderWatcher 在执行前，其他所有的 watcher 回调都执行完了，即执行 renderWatcher 的回调的时候获取到的 renderData 都是最新的，然后再去进行 setData 的操作，完成页面的更新。

```javascript
// src/core/queueWatcher.js
import { asyncLock } from '../helper/utils'
const queue = []
const idsMap = {}
let flushing = false
let curIndex = 0
const lockTask = asyncLock()
export default function queueWatcher (watcher) {
  if (!watcher.id && typeof watcher === 'function') {
    watcher = {
      id: Infinity,
      run: watcher
    }
  }
  if (!idsMap[watcher.id] || watcher.id === Infinity) {
    idsMap[watcher.id] = true
    if (!flushing) {
      queue.push(watcher)
    } else {
      let i = queue.length - 1
      while (i > curIndex && watcher.id < queue[i].id) {
        i--
      }
      queue.splice(i + 1, 0, watcher)
    }
    lockTask(flushQueue, resetQueue)
  }
}

function flushQueue () {
  flushing = true
  queue.sort((a, b) => a.id - b.id)
  for (curIndex = 0; curIndex < queue.length; curIndex++) {
    const watcher = queue[curIndex]
    idsMap[watcher.id] = null
    watcher.destroyed || watcher.run()
  }
  resetQueue()
}

function resetQueue () {
  flushing = false
  curIndex = queue.length = 0
}
```

---

---
url: /articles/size-control.md
---

# 滴滴出行小程序体积优化实践 {#size-control-practice}

> 作者：[sky-admin](http://github.com/sky-admin)

## 概述 {#overview}

2019年下半年，为了将微信钱包/支付宝九宫格入口的滴滴出行迁移为小程序，团队对小程序进行了大量的功能升级与补全。在整个过程中也遇到并克服了一系列问题和挑战，其中包体积问题尤为突出。接下来全面介绍一下滴滴出行小程序在体积控制方面做的努力与沉淀。

## 背景 {#background}

微信对小程序包体积的要求是总体积不得超过12M，主包及单个分包体积不得超过2M。支付宝对于小程序包体积的计算方式虽和微信略有区别，不过整体也大同小异。

18年至19年初时，滴滴出行小程序里承载的业务只有网约车，且业务需求较少，在主包内都能够搞定。而在下半年时，为了将微信钱包/支付宝九宫格入口迁移至小程序，小程序开始新增诸如公交/代驾/车服/单车/顺风车等众多业务线，同时网约车的业务需求也要做全面的补齐，业务量和代码量一起爆炸式增长。

滴滴出行包含了丰富多样的出行业务，包含了快车/专车/出租车/豪华车/拼车/单车/代驾/顺风车/公交/车生活等众多业务线。整个滴滴出行小程序的最重要，使用最高频的页面是首页与订单详情页，首页中承载了各个业务线的需求表达，各个业务线的订单详情页则承载了具体的出行订单展示逻辑。此外还有各种功能页面比如个人中心，营销页面，设置，历史行程。

按照滴滴出行的产品逻辑，所有业务线的需求表达逻辑都在首页承载，为了良好的切换体验，在首页采用了单页顶导的方案进行业务线展示。即每个业务线在首页中提供一个需求表达组件，当用户切换顶导业务线后，切换出对应的业务线组件。

在这种设计下，所有的业务线的需求表达逻辑都集中在首页这个单一页面中，导致在业务迭代过程中，承载首页的主包体积迅速增长，很快触碰了小程序平台的单包2M上限，对后续的业务迭代与发展带来巨大阻碍。因此，对于包体积的控制是我们在小程序开发过程中面临的一大难题。

## 体积控制 {#size-control}

下面我们将介绍滴滴出行小程序开发迭代过程中，我们对于小程序包体积进行的一系列优化控制实践。

### 基础优化手段 {#basic-optimization}

对于小程序来说，基础的包体积优化手段包括：资源压缩/去除代码冗余/资源CDN化/异步加载

在web开发中，webpack提供了大量的代码优化能力，包括依赖分析、模块去重、代码压缩、tree shaking、side effects等，这些能力可以方便地完成资源压缩和去除代码冗余的工作。滴滴出行小程序基于滴滴开源的小程序框架Mpx( https://github.com/didi/mpx )进行开发，Mpx框架的编译构建完全基于webpack，兼容webpack内部生态，天然可以使用上述能力对包体积进行优化。

小程序中支持部分静态资源（如图像视频等）使用CDN地址加载，我们会尽可能将相关的资源压缩后放到CDN上，避免这部分资源对包体积的占用。

小程序场景下无法像web当中通过script标签便捷地进行异步加载，但是小程序平台后期纷纷支持了分包加载的方案来实现该能力，由于分包加载是小程序特有的技术规范，webpack无法直接支持，因此Mpx框架专门针对该技术规范进行了良好的适配支持，关于该能力的应用我们会在后文详细阐述。

除此之外，Mpx框架还针对小程序场景进行了许多包体积优化的适配工作，如尽可能减少框架运行时包体积占用（压缩后占用56Kb），对引用到的页面/组件按需进行打包构建，声明公共样式进行样式复用，分包内公共模块抽取等。

在Mpx框架的这些能力的支持下，基本不需要额外配置就能构建出一个经过初步优化的小程序包。

> 微信开发者工具选项里也有类似的"上传代码时自动压缩混淆"可勾选，但在开发者工具中上传代码时计算体积是直接计算的当前项目代码的体积，并不会依据压缩后的体积。因此，如果你使用原生小程序进行开发，你的source代码极有可能进行进一步的压缩以节省空间。

### 分析体积 {#analyze-size}

虽然框架已经提供了很多在体积控制方面的优化，但是随着业务迭代我们发现主包体积依然偏大。

在遇到主包体积偏大后，我们需要弄明白，主包里有哪些东西？它们为什么这么大？

使用原生小程序或者其他非基于webpack的框架进行开发的同学遇到这个问题后，可能只能去看硬盘上的文件大小。这样一来，各个模块的大小占比可能并不直观。而我们则可以借助 webpack-bundle-analyzer 这样一个webpack插件去做辅助分析。

比如这是一个使用Mpx框架编写的demo，通过 `npm run build --report` 就可以看到这样一个界面：

![体积分析图](https://dpubstatic.udache.com/static/dpubimg/3e488293-959e-4617-8187-69fdb532e9ab.jpg)

可以看到这个demo工程由 moment / lodash / socket-weapp / core-js 等第三方库组成。各个库的大小，相互依赖关系也能清晰地看出。

对于滴滴出行小程序也是能看到类似的图，能看到整个项目到底是由哪些代码组成。

另外，滴滴出行前端开发一直是采用“源码编译”的，可以让整个项目里公共的依赖可以实现仅有一份，一起共用。简而言之，也有助于减少项目代码体积。[相关资料：https://github.com/DDFE/DDFE-blog/issues/23 ](https://github.com/DDFE/DDFE-blog/issues/23)

要完美发挥源码编译的效果，需要上下游一起建立整套源码编译生态，比如主项目的依赖方在声明公用依赖时，就应该用peerDep或者devDep来声明一些公有依赖，这些共有依赖应该在主项目中统一声明，避免因版本不同装出两份公共依赖，那样反而会增大体积。由于滴滴出行小程序涉及业务线及团队众多，部分团队可能并不知道这个事情，因此代码里实际是可能出现上述劣化场景。而依照分析图，可以容易地发现这种问题，并推动相关团队清除这些重复依赖。

同时，我们依照体积分析图，对其中体积较大的文件重点分析，进行了一轮业务代码梳理和精简，删除了一些无用代码，精简了websocket的消息体描述文件等。

### 配置分包 {#configure-subpackages}

分包是小程序给出的类似web异步引入的一个方案，把一些初始进入时不需要的页面可以放进分包里，跳转到对应页面时才去下载分包，将这些页面及其附属资源放到分包里可以有效减少主包体积。

Mpx框架早期对分包规范进行了初步支持，资源访问规则保持和微信一致，主要根据资源存放的目录判断应该输出到主包还是分包。有这个能力后，我们把行程页抽到了分包，大概抽出了200多K左右的空间。

有了行程页的成功拆分后，我们开始对所有的非首页代码进行分包操作，比如起终点选择和个人中心。以及部分业务线的接入是通过npm的方式接入，我们也尽可能将这些业务线的所有非首页的代码放到了分包。

这里还有个题外话，得益于mpx早期设计了packages形式的业务组合方案，可以很方便地让业务独立开发，又能及其方便地整合。而后发现微信的分包的json配置设计和packages很像，就在这个基础上支持了微信的分包，用户侧仅需在原来的packages基础上加一个query标记这个分包的名字即可。

拆除各个分包后，整个项目结构大概如图：

![分包一期结构图](https://dpubstatic.udache.com/static/dpubimg/0562f94d-3929-42b8-a389-854e14983373.png)

初阶的分包工作进行完毕后，总计从主包里拆了差不多400K的空间到分包里。

### 分包资源精细化管理 {#subpackage-resource-management}

上面提到，Mpx框架初期的分包处理规则是完全按照微信的方式，把在分包路径下的资源收集到分包里。而npm管理的资源因为都在node\_modules目录下，不属于任何分包路径，则会被全部收集进主包。

比如之前我们有行程页分包，行程页自有的状态管理store整个都在行程页分包的路径下，就会被收集到行程页分包中。而行程页还用到了封装好的didi-socket库，这个库是公共的npm包，即使它只在行程页分包里被使用，但由于它本身路径是在node\_modules下的，那么就会将其收集进主包里。

因为早期的一些设计，行程页的资源和首页是分割开的，都比较独立地存在于各自的路径下，一期的分包处理的大头也主要是行程页，它刚好契合了Mpx初期对分包处理上的特点，因此能较好地收集进行程页分包里。

随着业务迭代，后续大量业务线的接入都是通过npm进行的，就会有大量npm包资源，他们都在node\_modules目录下，因此全部会被收集进主包。

所以Mpx框架进行了一系列改造：

1. 在构建的依赖收集过程中，我们会对收集到的依赖打上标记，记录它是被哪些分包引入的。一旦它只有一个分包引入，它就会被输出到这个分包中。
2. 我们会根据用户定义的分包配置，自动在 SplitChunksPlugin 中生成各个分包的 cacheGroups ，把分包中的复用模块抽取到分包下的bundle中。
3. 对于组件和静态资源，如果他们被多个分包所引用且未在主包中引用，为了确保主包体积最优，这些资源将产生多份副本分别输出到对应分包中，而不会占用主包体积。

这样一来，***不管分包中引用的资源原本在什么位置，最终输出时都会尽可能将其输出到dist的分包目录下，避免占用主包空间***。

这个改动完成后项目结构看似和之前一样，但得益于Mpx处理分包资源能力的升级，我们得以将业务线分包中引用的npm资源成功输出到其所在的分包目录下。

### 封面方案 {#cover-solution}

再后来滴滴出行小程序需要替换微信/支付宝里原有的WebApp入口，小程序接入的业务线迅速增加，包体积迅速增长。

这个部分体积增长的主要原因前面提到过，所有的业务线都要接入到主页来展示。这也是由于业务特点决定的，滴滴出行提供了丰富的出行产品线，包括快车/专车/出租车/豪华车/拼车/单车/代驾/顺风行车等产品，用户是可能需要反复切换挑选的。这个过程还要保留起终点车型之类的信息，必须是一个页面内切换组件加一整套非常复杂的大型状态管理才能比较流畅顺滑地实现。而不能像一些电商/信息平台，将不同的功能拆分到不同页面，让用户通过首页的菜单进入子页面再进行操作，首页只承载入口，只有较少的业务逻辑，分包处理起来就会容易很多。

因此各个业务线都要提供首页组件进行接入。这个组件会在首页被用到，所以无论如何也拆不到分包里。最终，整个首页主包部分的体积可以分成两个部分：基础库和业务代码。两者的体积占比大概是公共依赖基础库占1M左右，业务代码占1M左右。

这么庞大的基础库体积主要是由于滴滴出行的业务线及业务团队众多，各方均有一些自己的基础依赖。比如网约车依赖的长链接通信pb数据描述文件，地图会依的大数计算库，顺风车依赖的CML框架运行时、代驾依赖的通信网关库，以及公用的组件库和polyfill等。

所以滴滴出行小程序面对的问题在当时已经无法用纯技术方案在短期内快速解决问题了，于是我们做了一个工程架构调整，可以叫封面页方案，解决了主包问题。

封面方案简单讲，就是做一个带滴滴出行Logo的封面作为启动页面，而页面一旦加载，立刻跳转另一个页面，这个页面真正承载业务，且它被放在分包里。

这个操作的意义在于，主包里就只剩下了所有方都要依赖的基础框架/库等，而业务全被抽离到了分包里。

![封面方案结构图](https://dpubstatic.udache.com/static/dpubimg/0f0ed782-8f67-4601-bc83-a8a343e1050b.png)

这是封面方案完成后项目的结构图，之前很大块的首页业务逻辑被抽出到首页分包中了。

这样一个挪移的操作的结果是我们可以有2M的主包空间来乘放基础的公共的库，有一个2M左右的分包来乘放前面提到的滴滴出行的集成了各种业务的“大主页”。而当时拆下来差不多有1.2M的主包，800K+的业务主分包。

这个改造最优秀的一点在于，后续的业务迭代产生的体积增长几乎全是在业务主分包里，剩下的1.1M+空间留给业务迭代还是比较充裕的。而主包的体积在理想条件下是可以长久保持不变的，就不会因为业务需求的不断开发反复导致主包体积临近超标，不再需要为主包体积感到焦虑。

当然，可以看到，这个方案本身是没有消减任何体积的，只是把位置变换了一下。除此之外，这个封面页方案其实也存在一些缺陷，比如首屏业务的展示会变慢，因为要加载的内容会变多，不过小程序本身有较好的缓存资源的能力，因此还算可以接受。

相比于因体积问题卡住需求迭代以及产品线的接入，目前这个方案至少能解决有无问题。我们开发团队后续也会持续跟进关注体积问题，看是否会有产品方案变更或者小程序本身给出一些解决方案来进一步优化这个部分。

## 总结 {#summary}

Mpx框架在包体积控制上做了大量工作，对于npm场景下的小程序分包进行了非常完善的支持。

滴滴出行小程序团队在框架支持的基础上，通过梳理业务依赖，充分利用分包，调整交互方案等一系列手段，在不阻碍业务发展的前提下，将庞大复杂的滴滴出行小程序包体积控制在平台限制范围内。

希望本文能给在包体积上遇到问题的小程序开发者们带来一些启发，欢迎留言交流。

---

---
url: /articles/ts-derivation.md
---

# 使用Typescript新特性Template Literal Types完善链式key的类型推导

> 作者：[anotherso1a](https://github.com/anotherso1a)

## 前言 {#intro}

在**Mpx框架**中我们采用了类似 `Vuex` 的数据仓库设计，这使得小程序的数据也可以在框架中得到**统一的管理**。但由于设计上的原因，这一部分在TS推导的实现上变得异常艰难，其中有一个明显的问题就是**链式key**的推导：

```ts
// 一段 mpx-store 代码实例

createStoreWithThis({
  // other options ...
  actions: {
    someAction() {
      // 下面这一个dispatch语句如何得到正确的推导？result的类型如何获取？
      let result = this.dispatch('deeperActions.anotherAction', 1)
      return result
    }
  },
  deps: {
    deeperActions: createStoreWithThis({
      actions: {
        anotherAction(payload: number) {
          // do something
          return 'result' + payload
        }
      }
    }),
    // other deps ...
  }
})
```

我们该如何获取 `this.dispatch('deeperActions.anotherAction', 1)` 的返回值？如何针对dispatch后续的参数类型做限制？这几乎是不可能解决的问题。

好消息是，在 2020.09.19，typescript团队release了一个[beta版本](https://github.com/microsoft/TypeScript/releases/tag/v4.1-beta)。这个版本新推出了一个特性：**模板字符串类型（Template Literal Types）**。

这让**链式key**的推导出现了曙光，不久后，我们开始尝试完善 `mpx-store` 的推导，此篇文章也是基于我们实践中所做的一些工作总结而来。

## 特性

这里可以直接看[官网](https://www.typescriptlang.org/docs/handbook/release-notes/typescript-4-1.html)例子，可以十分直观的感受到其特性：

```ts
type Color = "red" | "blue";
type Quantity = "one" | "two";

type SeussFish = `${Quantity | Color} fish`;
//   ^ = type SeussFish = "one fish" | "two fish" | "red fish" | "blue fish"
```

根据例子得知：模板字符串的使用方式几乎和ES6的字符串模板一致，可以做字符串的拼接，当接收字面量联合类型时，会做matrix操作，返回所有可能的拼接后的字面量联合类型。

另一个例子：

```ts
type A = '1' | '2'
type B = 'a' | 'b'
type C = 'C' | 'D'

type D = `${A}${B}${C}`
// type D = "1aC" | "1aD" | "1bC" | "1bD" | "2aC" | "2aD" | "2bC" | "2bD"
```

## 可以用来做什么

这个新特性的出现使得在js中常用的链式key取值，调用等，都能够使用ts进行完整的推导。

**第一个问题：**

```js
function getValueByPath(object, prop) {
  prop = prop || '';
  const paths = prop.split('.');
  let current = object;
  let result = null;
  for (let i = 0, j = paths.length; i < j; i++) {
    const path = paths[i];
    if (!current) break;

    if (i === j - 1) {
      result = current[path];
      break;
    }
    current = current[path];
  }
  return result;
}

// 调用例子
getValueByPath({ a: false }, 'a') // false
getValueByPath({ a: { b: { c: 1 } } }, 'a.b') // { c: 1 }
```

**如何将以上 getValueByPath 函数使用ts改写，使该函数的调用具有完备的类型推断？**

**第二个问题：**

```ts
type simpleActions = {
  actionOne(payload: number): Promise<number>
  actionTwo(payload: string): Promise<boolean>
}

declare function dispatch<K extends keyof simpleActions>(type: K): ReturnType<simpleActions[K]>

dispatch('actionOne')
// function dispatch<"actionOne">(type: "actionOne"): Promise<number>
```

**我们很容易为上面的 `simpleActions` 编写出其对应的 `dispatch` 函数，并具备完整推导，但针对下面这种深层次的actions，如何为其编写dispatch函数？**

```ts
const actions = {
  someAction(payload: number) {
    return payload
  },
  deeperActions: {
    anotherAction() {
      // do something
      return 'result'
    },
    otherActions: {
      finalAction(payload: string) {
        return !payload
      }
    }
  }
}

type Actions = typeof actions

// 编写一个 dispatch 方法，使得：
// let result = dispatch('deeperActions.anotherAction') // 返回类型为： Promise<string>
// let final = dispatch('deeperActions.otherActions.finalAction', 'hello world') // 返回类型为：Promise<boolean>
```

在typescript发布4.1之前，这几乎是不可能完成的任务，但是4.1的发布使我们能够对这一部分的缺失做一些类型补全。

接下来我们围绕上面两个问题分别进行实现。

## getValueByPath使用TS实现

需要使 `getValueByPath({ a: { b: { c: 1 } } }, 'a.b')` 获得完整的推导，我们首先需要能拿到两个参数的完整类型，这在ts中是十分容易的。第二步则是对两个参数的类型做映射处理，最好使得第一个参数输入完成之后，第二个参数直接能具备完整推导。

### 单层推导

我们可以先尝试着实现对单层对象取值的类型推导：

首先能得到一个大致的函数结构，接受两个参数，返回一个值

```ts
declare function getValueByPath(object: Record<any, any>, prop: string): any
```

上面这种写法是拿不到参数类型的，为了能正确拿到参数的类型，我们使用范型来填充参数 `object`：

```ts
declare function getValueByPath<T extends Record<any, any>>(object: T, prop: string): any
```

可以直接在编辑器上面尝试一下(我使用的是vscode)，很明显可以看到，我们正确的拿到了第一个参数的类型：

![xx](https://dpubstatic.udache.com/static/dpubimg/5a1f9aef-c5ff-4109-980a-85216b62e291.png)

能取到参数的类型对象，就能使用关键字 `keyof` 获取对象的每一个key，接下来我们把候选key值限定给参数prop，然后把对应的返回值结果填充到函数的结果当中，这里我们引入第二个范型 `K`。尝试调用之后，我们发现结果都符合预期。

```ts
declare function getValueByPath<T extends Record<any, any>, K extends keyof T>(object: T, prop: K): T[K]

let a = getValueByPath({a: 1, b: '2'}, 'a') // number
let b = getValueByPath({a: 1, b: '2'}, 'b') // string
let c = getValueByPath({a: 1, b: '2'}, 'c') // Argument of type '"c"' is not assignable to parameter of type '"a" | "b"'.ts(2345)
```

### 多层推导

仅仅是单层推导的结构依然是无法满足我们对于 `getValueByPath({ a: { b: { c: 1 } } }, 'a.b')` 推导的需求：

```ts
let a = getValueByPath({ a: { b: { c: 1 } } }, 'a.b') 
// Argument of type '"a.b"' is not assignable to parameter of type '"a"'.ts(2345)
```

可以看到，第二个候选参数的类型仅有 `"a"`，而我们按正常期望来讲，`getValueByPath`的第一个参数传入 `{ a: { b: { c: 1 } } }` 之后，第二个候选参数类型应该为： `"a" | "a.b" | "a.b.c"` 。

接下来我们使用4.1的新特性，将对象： `{ a: { b: { c: 1 } } }` 与其链式key： `"a" | "a.b" | "a.b.c"` 一一对应起来。

工欲善其事，必先利其器。我们先封装好两个工具函数：

```ts
// 取出对象的所有除了 symbol 以外的key
type StringKeyof<T> = Exclude<keyof T, symbol>

// 将字符串用 . 进行拼接
type CombineStringKey<H extends string | number, L extends string | number> = H extends '' ? `${L}` : `${H}.${L}`
```

我们知道，`symbol` 类型是没办法放在**模板字符串**中的，所以对key进行拼接之前，需要过滤掉所有 `symbol` 类型的key。而 `StringKeyof` 函数，就是用来过滤对象中所有不符合**模板字符串**类型的key的方法。其实际用法与 `keyof` 相同，只是返回值能用于**模板字符串**。

`CombineStringKey` 则是对两个key进行拼接，拼接的结果自然就是我们需要的链式key格式。

调用例子：

```ts
const symbol1 = Symbol()

type A = {
  1: string
  a: string
  [symbol1]: string
}

type K = StringKeyof<A> // 1 | 'a'

type B = CombineStringKey<'', 'a'>         // "a"
type C = CombineStringKey<B, 'b'>          // "a.b"
type D = CombineStringKey<C, 'c1' | 'c2'>  // "a.b.c1" | "a.b.c2"
type E = CombineStringKey<D, 'd'>          // "a.b.c1.d" | "a.b.c2.d"
```

我们现在以下面这个对象类型为例，取出该对象所有符合要求的链式key：

```ts
type deepObj = {
  a: number;
  b: {
    c: string;
    d: number;
    e: {
      f: number;
      g: boolean;
    };
  };
}
```

思路：遍历对象的所有key，同时对key对应的值进行判断，如果是一个更深层次的对象，则保留外层的key，对更深层对象递归处理，把后续递归出的key都和上一层中保留的key进行拼接。

```ts
type ChainKeys<T, P extends string | number = ''> = {
  [K in StringKeyof<T>]: T[K] extends Record<any, any> ? ChainKeys<T[K], CombineStringKey<P, K>> : {
    [_ in CombineStringKey<P, K>]:T[K]
  }
}[StringKeyof<T>]
```

我们将 `ChainKeys` 函数拆开来看，首先是它的参数，接受两个类型参数，第一个是类型T，第二个则是用于拼接的**前缀字符串**，其值可选。我们使用 `in` 语法遍历 `T` 的所有 key 值，也就是 `[K in StringKeyof<T>]`，这里我们使用了前面封装好的方法 `StringKeyof` 来代替 `keyof` 关键字。对对应的 key 的值，也就是 `T[K]`，我们使用 `extends` 进行前置判断，如果 `T[K]` 是一个**复杂类型**，我们则将当前的字符串前缀 `P` 和当前的 `K` 进行拼接，递归调用 `ChainKeys` 函数进行处理。如果 `T[K]` 为**基本类型**，我们直接使用 `Record` 方法组装拼接好的key（`CombineStringKey<P, K>`）和value（`T[K]`），为了方便在编辑器里面查看结果，这里将`Record<CombineStringKey<P, K>, T[K]>` 替换为 `{ [_ in CombineStringKey<P, K>]:T[K] }`。最后将所有结果打平成联合类型，也就是最后的一个取值操作：`{...}[StringKeyof<T>]`，这和 `[1,2,3][number] // 3 | 1 | 2` 的处理方式一致。

接下来我们在编辑器中查看一下调用结果：

![img](https://dpubstatic.udache.com/static/dpubimg/36f16bdc-4754-4387-bdac-bf3710a3ea56.png)

如红框中所示，发现链式key已经和其类型一一对应起来了。

但是这还有一些问题：

一、`"b"` 以及 `"b.e"` 没有出现在枚举当中。

二、返回结果是一个**联合类型**，如何把这个结果运用到函数当中呢？

第一个问题其实很好解决，当我们在递归处理的同时，将当前的链式key与对应值也进行处理就可以，即：

```ts
type ChainKeys<T, P extends string | number = ''> = {
  [K in StringKeyof<T>]: T[K] extends Record<any, any>
    ? Record<CombineStringKey<P, K>, T[K]> & ChainKeys<T[K], CombineStringKey<P, K>> 
    : {
      [_ in CombineStringKey<P, K>]:T[K]
    }
}[StringKeyof<T>]
```

同样为了方便编辑器中查看结果我们把 `Record<CombineStringKey<P, K>, T[K]>` 替换成 `{ [_ in CombineStringKey<P, K>]:T[K] }`：

![img](https://dpubstatic.udache.com/static/dpubimg/d0bb4b70-f355-4d41-8430-031ac4a44136.png)

可以看到 `b` 以及 `"b.e"` 这样的key都被取出来并放到了结果当中。其实这里还是有一些问题，如果你实际去代码编辑器里面查看结果的话，会发现有很多重复的 `b` ，这是因为后续使用交叉类型进行拼接的 `ChainKeys` 的返回值是一个联合类型，如此一来，`b` 会被分配到联合类型的**每一项**上，在后面我们会解决这个问题。

第二个问题是结果为联合类型，我们如何才能将其运用至函数当中呢？

大家都知道，对联合类型使用 `keyof` 操作，返回的类型为 `never`，即无法取出联合类型的所有key值：

```ts
type T = { a: number } | { b: string }
type K = keyof T // never
// 如何使K的类型为 a ｜ b 呢？
```

这里我们引入另一个工具函数：`UnionToIntersection`，顾名思义，该函数的作用就是将联合类型转换为交叉类型，至于**为什么**它能将联合类型转换为交叉类型，我们后面会讲：

```ts
type UnionToIntersection<U> = (U extends any ? (k: U) => void : never) extends ((k: infer I) => void) ? I : never;
```

我们将其运用到ChainKeys的推导当中去：

```ts
type ChainKeys<T, P extends string | number = ''> = UnionToIntersection<{
  [K in StringKeyof<T>]: T[K] extends Record<any, any>
    ? Record<CombineStringKey<P, K>, T[K]> & ChainKeys<T[K], CombineStringKey<P, K>> 
    : {
      [_ in CombineStringKey<P, K>]:T[K]
    }
}[StringKeyof<T>]>
```

再经过一些润色得到一个比较精简的函数：

```ts
type ChainKeys<T, P extends string | number = ''> = UnionToIntersection<{
  [K in StringKeyof<T>]: Record<CombineStringKey<P, K>, T[K]> & (T[K] extends Record<any, any> ? ChainKeys<T[K], CombineStringKey<P, K>> : {})
}[StringKeyof<T>]>
```

尝试调用该方法最终得到的结果为：

![img](https://dpubstatic.udache.com/static/dpubimg/f7b952df-6668-434e-b26c-e43345a0f4b4.png)

最终，我们以此为基础，编写 `getValueByPath` 函数的定义：

```ts
declare function getValueByPath<T extends Record<any, any>, K extends keyof ChainKeys<T>>(object: T, prop: K): ChainKeys<T>[K]

let a = getValueByPath({ a: { b: { c: 1 } } }, 'a')     // { b: { c: number } }
let b = getValueByPath({ a: { b: { c: 1 } } }, 'a.b')   // { c: number }
let c = getValueByPath({ a: { b: { c: 1 } } }, 'a.b.c') // number
```

到此，我们算是完成了 `getValueByPath` 函数的类型定义以及推导。

## 深层次Actions的dispatch函数TS实现

其实在推导 `getValueByPath` 的过程中，我们已经基本上完成了所有实现该 `dispatch` 所需要的条件，与 `getValueByPath` 不同的是，我们只需要遍历出函数所对应的链式key即可，改写一下 `ChainKeys` 方法：

```ts
interface DeeperActions {
  [k: string]: ((...args: any[]) => any) | DeeperActions
}
type ActionChainKeys<T, P extends string | number = ''> = UnionToIntersection<{
  [K in StringKeyof<T>]: T[K] extends DeeperActions
    ? ActionChainKeys<T[K], CombineStringKey<P, K>>
    : Record<CombineStringKey<P, K>, T[K]>
}[StringKeyof<T>]>
```

我们除去了对对象的混入，同时将判断类型改为了 `DeeperActions` ，以此来判断该 `action` 对象是否有更深层次的actions。

调用结果：

![img](https://dpubstatic.udache.com/static/dpubimg/812f50b2-a148-4065-9f87-a9b010502c6d.png)

再看我们最开始提出的问题：

> 编写一个 dispatch 方法，使得：
>
> `let result = dispatch('deeperActions.anotherAction') // 返回类型为： Promise<string>`
>
> `let final = dispatch('deeperActions.otherActions.finalAction', 'hello world') // 返回类型为：Promise<boolean>`

我们开始定义 `dispatch` 方法：

```ts
declare function dispatch<K extends keyof ChainingActions>(key: K, ...args: Parameters<ChainingActions[K]>): ReturnType<ChainingActions[K]>
```

这里我们分别使用了 `Parameters` 和 `ReturnType` 函数来获取对应 `action` 的参数以及返回值，用来填充至 `dispatch` 方法中，实际编写调用代码：

![](https://dpubstatic.udache.com/static/dpubimg/c6165376-d374-4ede-9bd2-0c99ca336337.png)

![](https://dpubstatic.udache.com/static/dpubimg/9447cd1a-04b6-4972-80a1-13f28de2b0cc.png)

考虑到我们的 `actions` 无论如何都会返回一个 `Promise`，上述定义其实还是稍微有一些问题，但是改动起来也很方便，只需要在 `ReturnType` 外层使用 `Promise` 包装一下就可以了：

```ts
type Promisify<T> = T extends Promise<any> ? T : Promise<T>

declare function dispatch<K extends keyof ChainingActions>(key: K, ...args: Parameters<ChainingActions[K]>): Promisify<ReturnType<ChainingActions[K]>>

let result = dispatch('deeperActions.anotherAction') // Promise<string>
let final = dispatch('deeperActions.otherActions.finalAction', 'hello world') // Promise<boolean>
```

至此，我们 `dispatch` 的TS实现也已经完成。

最终结果：

![](http://cdn.qiniu.archerk.com.cn/QQ20210128-162139-HD.gif)

* 若图片加载失败请访问： http://cdn.qiniu.archerk.com.cn/QQ20210128-162139-HD.gif

## 结尾

其实 `getValueByPath` 这一部分的内容是有一些缺陷的，因为TS本身**限制了递归的次数**，当数据层级达到一定程度时，上文的推导会失效。在Mpx的建设中我们还对此做了一些优化，尽可能的**减少**了递归次数。

这里也给出**另一个方案**做链式key推导，这种方式**性能**上会好很多，因为不用解析出所有的链式key，而是根据链式key**反向解析**前面的对象，因此该方案可以解析出正确的类型，但是会丧失一部分代码提示：

```ts
type CutChainKeys<T extends string> = T extends `${infer A}.${infer B}` ? [A, B] : [T, never]

type GetValueByPath<T extends Record<string, any>, K extends string> = CutChainKeys<K> extends [string, never]
  ? T[CutChainKeys<K>[0]]
  : GetValueByPath<T[CutChainKeys<K>[0]], CutChainKeys<K>[1]>

declare function test<T extends Record<any, any>, K extends string>(o: T, k: K): GetValueByPath<T, K>

let s = test({
  a: {
    b: 1,
    c: {
      d: {
        e: {
          f: 'f'
        }
      }
    }
  }
}, 'a.c.d.e.f') // string
```

通过这一系列的处理，我们基本完成了 `mpx-store` 的类型推导，包括对应的**辅助函数**等。这也使得我们能够在项目中更好的使用TS进行开发。在最新的滴滴出行小程序更新中，我们已经开始使用TS全量进行开发，目前看来开发体验还不错，后期也会逐步将旧的代码重构为TS。我们后续也会持续维护和迭代框架，也欢迎有兴趣的朋友来一起[共建](https://github.com/didi/mpx)。

有写的不好的地方请多包含，也欢迎大家批评指正。

## 题外话：UnionToIntersection

上面提到的，我们使用工具函数 `UnionToIntersection` 将联合类型转换为交叉类型。而 `UnionToIntersection` 又是如何将**联合类型转换为交叉类型**的呢？

在 [Conditional Types](https://www.typescriptlang.org/docs/handbook/release-notes/typescript-2-8.html) 中有提到一些点：

### Distributive conditional types

> Conditional types in which the checked type is a naked type parameter are called distributive conditional types. Distributive conditional types are automatically distributed over union types during instantiation. For example, an instantiation of `T extends U ? X : Y` with the type argument `A | B | C` for `T` is resolved as `(A extends U ? X : Y) | (B extends U ? X : Y) | (C extends U ? X : Y)`.

即在**执行** `extends` **语句时**，如果 `extends` 左侧为**联合类型**，则会被分配成**对应数量个**子条件判断语句，最终**联合**每个子语句的结果。

```ts
type A = 1 | '2' | 3

type IsNumber<T> = T extends number ? T : never

type B = IsNumber<A> // 1 | 3
```

### Type inference in conditional types

> Within the `extends` clause of a conditional type, it is now possible to have `infer` declarations that introduce a type variable to be inferred. Such inferred type variables may be referenced in the true branch of the conditional type. It is possible to have multiple `infer` locations for the same type variable.

在条件判断语句中，可以使用 `infer` 关键字做类型推断，同一个候选值能有**多个**推断位置。

```ts
type ReturnType<T> = T extends (...args: any[]) => infer R ? R : any;
```

**正位推断**的结果会被推导为**联合**类型：

```ts
type Foo<T> = T extends { a: infer U; b: infer U } ? U : never;
type T10 = Foo<{ a: string; b: string }>; // string
type T11 = Foo<{ a: string; b: number }>; // string | number
```

**逆变位置推断**的结果会被处理成**交叉**类型：

```ts
type Bar<T> = T extends { a: (x: infer U) => void; b: (x: infer U) => void }
  ? U
  : never;
type T20 = Bar<{ a: (x: string) => void; b: (x: string) => void }>; // string
type T21 = Bar<{ a: (x: string) => void; b: (x: number) => void }>; // string & number
```

**注意**：这里是`ts-2.8`发布时的文档以及例子，现在来说是不存在 `string & number` 类型的，如果实际编写这段代码的话会发现 `T21` 的值为 `never`，因为不可能存在一个值既为 `string` 又为 `number`。逆变与协变的一些概念可以参考一下[逆变与协变](https://zh.wikipedia.org/wiki/%E5%8D%8F%E5%8F%98%E4%B8%8E%E9%80%86%E5%8F%98)。

### UnionToIntersection 原理探究

有了以上两个信息之后，我们再来看看 `UnionToIntersection` 的实现，为了方便阅读我们做一些折行：

```ts
type UnionToIntersection<U> = (
    U extends any 
      ? (k: U) => void
      : never
  ) extends ((k: infer I) => void) 
    ? I
    : never;
```

发现实际上 `UnionToIntersection` 分为两步：

1、将联合类型的**每一项**填充至 函数类型 `(k: U) => void` 的参数 `k` 中。

2、使用 `infer` 关键字在**逆变位**对 `(k: U) => void` 做推导，将参数的类型推入结果 `I` 中，组成**交叉**类型。

拆分看实现：

```ts
// 联合类型推入函数参数
type UnionToFunction<U> = U extends any ? (k: U) => void : never
// 对函数逆变推导，将参数推导为交叉类型
type FunctionsToIntersection<F> = [F] extends [(k: infer I) => void] ? I : never

type Union = { a: number } | { b: string }

type Fun = UnionToFunction<Union> // ((k: { a: number }) => void) | ((k: { b: string }) => void)

type Intersection = FunctionsToIntersection<Fun> // { a: number } & { b: string }
```

可以注意到我们拆分开来了 `UnionToIntersection` 后并不是完全按照原有写法去写的，在 `FunctionsToIntersection` 函数中，我们使用了`[]`将类型给包裹起来，这是为了**避免**第一个特性（Distributive conditional types）的影响，如果不做包裹，则 `extends` 左侧为联合类型，被分配成若干个子句后，同一位置的 `infer` 就会被分别执行，无法合成为交叉类型。而使用`[]`进行包裹之后则避免了这个影响，`extends` 左侧不再是一个联合类型，而是一个数组类型。

## 参考资料汇总

* [Template Literal Types](https://www.typescriptlang.org/docs/handbook/release-notes/typescript-4-1.html)
* [Conditional Types](https://www.typescriptlang.org/docs/handbook/release-notes/typescript-2-8.html)
* [逆变与协变 Covariance and contravariance](https://zh.wikipedia.org/wiki/%E5%8D%8F%E5%8F%98%E4%B8%8E%E9%80%86%E5%8F%98)
* [TS递归上限](https://github.com/microsoft/TypeScript/issues/30188)
* [Mpx中的实现（前期）](https://github.com/didi/mpx/pull/631)

---

---
url: /articles/2.7-release.md
---
# Mpx2.7 版本正式发布，大幅提升编译构建速度 {#mpx-2-7-release}

> 作者：[hiyuki](https://github.com/hiyuki)

[Mpx](https://www.mpxjs.cn/)是一款开源的增强型跨端小程序框架，它具有良好的开发体验，极致的应用性能和一份源码同构输出所有小程序平台及web环境的跨端能力。近期，我们发布了框架最新的2.7版本，基于`webpack5`彻底重构了框架的核心编译构建流程，利用持久化缓存大幅提升了编译构建速度，最高提升可达10倍。除此之外，`Mpx2.7`版本还带来了一系列重要的功能更新，包括分包输出能力增强，完善的单元测试支持和用户Rules应用等，下面会对这些新特性进行逐个展开介绍。

## 编译构建提速 {#build-speed-up}

随着小程序生态的日渐发展壮大，各类线上小程序业务体量和复杂度的不断升级，小程序的包体积从最开始的2M以内膨胀到20M甚至30M，已经远远不复当初的"**小**"程序之名。随着小程序项目大小的不断增加，采用框架进行小程序开发的开发者们往往都会面临一个问题，即框架的编译耗时过长，Mpx也不例外。

以团队负责的小程序项目为例，该项目目前的总包体积已经超过25M，包含近30000个JS模块，400多个页面和3000多个组件，在本地进行一次完整构建需要等待15分钟，CI环境下甚至需要近半个小时，远远超出能够忍受的范围，对小程序开发体验和开发效率造成了极大的影响。虽然旧版本中的watch模式能够在很大程度上缓解我们在开发调试过程中面临的编译耗时问题，但我们在日常开发中，仍然有很多场景无法使用watch模式（首次构建/CI环境/需真机预览等），基于内存缓存的watch模式也无法长期运行。对于这个问题，我们在过去也做了很多技术尝试，如支持watch:prod模式，局部编译，多线程编译，DLL预编译等等，但是整体尝试下来这些方案要么收效有限要么适用面不足，都没能探索到一个能从根本上解决问题的方案。

直到2020年底，`webpack5`正式发布，基于文件系统持久化缓存能力的出现，让我们看到了该问题的解决之道。由于webpack5相较于webpack4有着非常多的升级改动，而Mpx的编译构建在过去版本中也存在着各种历史遗留问题，我们花了较长的时间吃透webpack5的源码以及重新思考Mpx中存在的不合理设计。经过3个多月的开发，我们彻底重构了Mpx的核心编译构建流程，使其能够**完整安全地**利用webpack5持久化缓存能力进行构建提速，同时也彻底解决了旧版Mpx中存在的历史遗留问题，在去年10月完成了beta版的开发与发布，并在业务中进行了初步的落地尝试。之后又经过2个多月的业务回归测试和框架功能补全，我们在beta版的基础上又迭代修复了近30个patch版本，在业务上完成了充分的回归测试，让我们确信目前的新版本已经达到了能够release的阶段。

> 为什么不是`Vite`
>
> 聊起编译提速，可能大部分人首先想到的是Vite，诚然Vite是一个极富创造力的技术方案，但是在小程序场景下，却不一定是最合适的方案，这主要源于Vite最核心的设计利用了现代浏览器原生支持的ESM，而目前没有任何一家的小程序环境能够原生支持ESM，这就使得Vite最核心的按需编译能力无法得到发挥，而Vite使用esbuild带来的编译速度提升，在webpack环境中也可以选择esbuild-loader提供的能力来替换babel/terser，而且目前esbuild提供的编译能力成熟度还远不能和babel/terser相比，再加上Mpx的编译构建流程很大程度上依赖了webpack提供的能力，从成本和收益上考虑采用webpack5对于我们来说无疑是更好的方案。

以团队负责的小程序项目为例，我们来看一下Mpx2.7版本带来的编译提速效果：相较于旧版长达15分钟的构建耗时，在无缓存环境下，新版的构建耗时约为8分钟，速度提升了近1倍；而在有缓存环境下，新版构建耗时可以缩短至80s，速度提升了**10倍以上**！随着我们对CI流程的持久化缓存改造完成，可以确保在日常的大部分构建场景都会在有缓存的环境下进行。

## 分包输出能力增强 {#subpackage-output-enhancement}

在Mpx2.7版本中，我们对小程序分包能力的支持进行了进一步的完善增强。

### 独立分包初始化模块 {#independent-subpackage-init}

在过去的版本中，我们对独立分包进行过专门的构建支持，以满足独立分包资源独占的要求。不过在使用独立分包进行业务开发时，往往会面临的一个棘手问题在于初始化逻辑无处安放。这是由于独立分包没有app.js，而在小程序中，组件的js逻辑会早于页面js执行，具体的执行顺序又和组件的嵌套关系有关，因此我们无法找到一个确定的代码位置来存放独立分包的初始化逻辑。

在Mpx2.7版本中，我们针对独立分包新增了一个全新的增强特性，让用户能够声明独立分包的初始化模块，该模块将会在独立分包启动时全局最先执行，其实现思路大致如下：在构建时为独立分包中所有的组件和页面都添加模块引用，指向用户声明的初始化模块，这样在独立分包启动时，不管哪个组件/页面的js最先执行，都能保障这个初始化模块最先执行，同时由于模块缓存的存在，后续的组件/页面执行时，该模块也不会被重复执行。

该特性的详细使用方式可以参考我们的[文档说明](https://www.mpxjs.cn/guide/advance/subpackage.html#独立分包)

### 分包异步化 {#subpackage-async}

[分包异步化](https://developers.weixin.qq.com/miniprogram/dev/framework/subpackages/async.html)是微信小程序在去年下半年提出的全新技术特性，该特性打破了传统分包只能引用自身和主包资源的规则限制，通过相关配置和声明，允许分包异步地引用其他分包内的资源，对于复杂小程序的包体积和加载性能优化具有极其重要的意义。

在过去，受限于小程序分包资源引用规则，Mpx在编译构建时对于跨分包共用的资源有两种处理策略，其一是将其输出到主包当中，让多个分包都能够通过主包访问，这种策略下可以达到总包体积最优，但是往往会对主包体积造成过大的压力。当主包超出2m限制时，我们就需要采用第二种策略，将这部分跨分包共用的资源冗余地输出到各自的分包中，消除其对于主包体积的占用。在实际的Mpx编译构建当中，这两种策略是同时存在的，具体什么时候采用哪种策略是根据资源类型和用户配置来决定的。

由于分包异步化技术打破了传统分包资源引用规则的限制，理想情况下我们可以做到主包不超限的同时总包无冗余，不过该技术目前也存在一些不足：一是跨平台支持度不佳，只有微信支持，不过据我们了解支付宝目前也在跟进中；二是对交互和体验会带来一些影响，同时存在业务改造成本，但这依然不妨碍该技术成为大型小程序优化包体积和加载性能的最优路径。

![分包异步化资源引用](https://dpubstatic.udache.com/static/dpubimg/c7ac0180-6914-46c6-aaed-c1d3cface8e1.jpeg)

我们在Mpx2.7版本中对分包异步化中最常用的`跨分包自定义组件引用`进行了完整支持，与原生小程序不同，Mpx中资源的分包归属不由源码位置决定，而是由资源引用关系决定，因此在跨分包资源引用的场景下，用户需要声明引用的资源属于哪个分包，简单使用示例如下：

```json5
{
  "usingComponents": {
    // 通过root query声明组件所属的分包，与packages语法下使用root query声明package所属分包的语义保持一致
    "button": "../subPackageA/components/button?root=subPackageA",
    "list": "../subPackageB/components/full-list?root=subPackageB",
    "simple-list": "../components/simple-list"
  },
  "componentPlaceholder": {
    "button": "view",
    "list": "simple-list"
  }
}
```

详细使用方式可参考[文档说明](https://www.mpxjs.cn/guide/advance/async-subpackage.html#分包异步化)

对于另一项`跨分包JS代码引用`能力的使用支持，我们目前也正在探索规划中，预计能在今年Q1内完成开发支持。

## 单元测试支持 {#unit-test-support}

Mpx自从20年开始就对单元测试有了初步的支持，但过去的单测方案在设计上存在一些缺陷，可用性不高，业务落地困难，在Mpx2.7版本中，我们设计了一套全新的技术方案，克服了原有方案中存在的所有问题，在可用性上得到了质的飞跃，新旧方案的对比如下：

旧方案：通过Mpx编译构建预先将完整的项目源码构建输出为原生小程序格式，再通过jest + miniprogram-simulate加载构建产出的原生小程序组件来执行测试case。该方案的优点在于编译流程统一，方案实现成本较低，缺点在于执行任何case都需要执行完整的构建流程，耗时较长；而且由于构建本身不基于jest进行，也无法使用jest提供的模块mock功能。

![旧版单测方案](https://dpubstatic.udache.com/static/dpubimg/31756195-2734-4300-8ab4-8b1b7a7d8c8f.jpeg)

新方案：我们fork了miniprogram-simulate仓库对其扩展了load mpx组件的能力，在资源加载的transform过程中通过mpx-jest插件将mpx组件编译为原生小程序组件，再将内容传递给miniprogram-simulate执行渲染并运行测试case。该方案中模块加载完全基于jest并能够实现组件的按需编译，完美规避旧方案中存在的问题，缺点在于编译流程基于jest api重构，与mpx基于webpack的编译流程独立，存在额外的维护成本，后续我们会将通用的编译逻辑抽离维护，在webpack和jest两侧复用。

![新版单测方案](https://dpubstatic.udache.com/static/dpubimg/5486308b-b844-402e-802f-f9cc08a07259.jpeg)

关于单元测试更详细的使用指南可参考[文档说明](https://www.mpxjs.cn/guide/tool/unit-test.html)

随着单测方案的完善，我们今年也会推动单元测试在小程序业务中全面落地，更好地保障代码质量与业务稳定。

## Module.rules复用 {#module-rules-reuse}

Mpx的单文件支持很大程度上参考了`vue-loader`的设计，在vue-loader@15版本前，对于单文件组件中各个区块(block)的loaders应用逻辑默认内置在loader当中，如需对某些区块进行自定义配置，需要向loader的options中传递额外的loader应用规则，无法复用webpack配置的`module.rules`中已经定义好的规则，这往往会导致我们需要在loader options和module.rules中维护重复的loader规则，同样的问题也存在于旧版的`mpx-loader`中。

在vue-loader@15版本发布之后，其通过克隆用户原始的rules的方式实现了module.rules的复用，用户不再需要往loader options中传递冗余的loaders规则，本次全新Mpx2.7版本也支持了该特性，我们使用了webpack提供的`matchResource`能力实现了module.rules的复用，该方案相较于clone rules的方式实现起来更加简洁优雅。

以上就是Mpx2.7版本的核心更新内容，目前使用脚手架工具创建的项目默认都会使用2.7版本，过往项目如需迁移升级可以查看[这篇指南](https://www.mpxjs.cn/guide/migrate/2.7.html)。

## 即将到来的新特性 {#upcoming-features}

以上就是我们本次Mpx2.7版本带来的全部特性，后续我们也有计划撰写一系列文章对其中的技术细节进行更加深入的分析与介绍，除了上面介绍到的特性外，我们还有一系列特性处于即将发布的状态：

* [组件维度运行时渲染方案](https://github.com/didi/mpx/pull/919)
* [页面局部构建能力](https://github.com/didi/mpx/pull/924)
* E2E自动化测试能力
* 基于Vite构建输出web应用
* 跨端输出快手小程序
* @mpxjs/fetch提供接口mock能力

## 未来规划 {#future-plan}

未来，我们的工作重心将重新回到运行时，重点致力于`composition api`编码规范支持和数据响应系统的升级，在保障性能和包体积方面优势的同时，带给开发者用户与时俱进的开发体验。

在跨端方面，我们与[移动端跨端框架Hummer](https://github.com/didi/Hummer)进行了合作，初步探索了Mpx基于Hummer输出为移动端原生应用的可行性，目前整体流程已经基本跑通，待后续能力逐步完善和业务充分落地后，就会在开源版本中发布。

与此同时，`Mpx-cube-ui`小程序跨端组件库也在持续地开发完善中，目前业务落地效果良好，预计会在今年下半年正式开源。

---

---
url: /articles/2.8-release.md
---
# Mpx2.8 版本正式发布，使用组合式 API 开发小程序

> 作者：[hiyuki](https://github.com/hiyuki)

小程序跨端开发框架 [Mpx](https://www.mpxjs.cn/) 自18年立项开源以来，如今已经走过了第四个年头，其高性能、优体验、跨平台的特性收获了公司内外开发者用户的一致好评。

为了不辜负开发者用户对我们的信赖，更好地支持集团小程序业务开发，一方面我们对 Mpx 的稳定版本进行着高频的维护迭代，快速响应处理集团内外开发者用户在框架开发使用过程中遇到的问题；另一方面我们持续跟进探索业内最新动态，力争将更新更好的开发能力与体验带给小程序开发者用户。继年初我们在 [2.7 版本](../guide/migrate/2.7.md)中对 Mpx 的编译系统进行重构适配 Webpack5，基于持久化缓存大幅提升编译速度后，在最新的 [2.8 版本](../guide/migrate/2.8.md)中，我们对 Mpx 的运行时框架也进行了大量重构改造工作，完整支持了 Vue3 提出的组合式 API 开发范式，让用户能够使用当下最热门的开发方式进行小程序开发，我们先来简单感受一下组合式 API 的使用：

```html
<template>
  <view>{{ collectionName }}: {{ book.title }}({{ readersNumber }})</view>
  <button bindtap="addReaders">addReaders</button>
</template>

<script>
  import { createComponent, ref, reactive, onMounted } from '@mpxjs/core'

  createComponent({
    properties: {
      collectionName: String
    },
    setup () {
      const readersNumber = ref(0)
      const book = reactive({ title: 'Mpx' })

      onMounted(() => {
        console.log('Component mounted.')
      })

      // 暴露给 template
      return {
        readersNumber,
        book,
        addReaders () {
          readersNumber.value++
        }
      }
    }
  })
</script>
```

可以看出和 Vue3 组合式 API 的使用是高度类似的，利用框架导出的一系列响应式 API 和 生命周期钩子函数在 `setup` 中编写业务逻辑，并将模板依赖的数据与方法作为返回值返回，与传统的选项式 API 相比，组合式 API 具备以下优势：

* 更好的逻辑复用，通过函数包装复用逻辑，显式引入调用，方便简洁且符合直觉，规避消除了 mixins 复用中存在的缺陷；
* 更灵活的代码组织，相比于选项式 API 提前规定了代码的组织方式，组合式 API 在这方面几乎没有做任何限制与规定，更加灵活自由，在功能复杂的庞大组件中，我们能够通过组合式 API 让我们的功能代码更加内聚且有条理，不过这也会对开发者自身的代码规范意识提出更高要求；
* 更好的类型推导，虽然基于 `this` 的选项式 API 通过 `ThisType` 类型体操的方式也能在一定程度上实现 TS 类型推导，但推导和实现成本较高，同时仍然无法完美覆盖一些复杂场景（如嵌套 mixins 等）；而组合式 API 以本地变量和函数为基础，本身就是类型友好的，我们在类型方面几乎不需要做什么额外的工作就能享受到完美的类型推导。

同时与 React Hooks 相比，组合式 API 中的 `setup` 函数只在初始化时单次执行，在数据响应能力的加持下大大降低了理解与使用成本，基于以上原因，我们决定为 Mpx 添加组合式 API 能力，让用户能够用组合式 API 方式进行小程序开发。

## 组合式 API 实现

从上面的简单示例中可以看出，抛开响应式 API 和生命周期注册模式的变化，组合式 API 的实现要点在于动态添加模板依赖的数据和方法，这也是我们在小程序中实现组合式 API 可能遇到的核心技术卡点。

对于动态添加模板依赖数据，我们在过去的实践中已经充分证明了其可行性，事实上，从 Mpx 最初的版本开始，我们就充分利用了这项能力来实现我们对计算属性和 `dataFn` （类似于 Vue 使用函数定义 `data`）的支持，这项能力的关键在于存在合适的生命周期用于动态添加初始化数据，这里对于初始化数据的定义是能够影响组件树的初始渲染，举个简单的例子：存在一对父子组件 parent/child，parent 使用 `props` 向 child 传递数据，当我们在 parent 初始创建时使用 `setData` 动态添加 `props` 数据，同时 child 在初始创建时能够通过 `props` 正确获取到这部分的数据时，我们就可以将这部分动态添加的数据视作初始化数据，这是我们在小程序中实现完备数据响应支持的基础。

幸运的是，目前业内所有主流小程序平台（微信/支付宝/百度/字节/QQ）都支持了上述能力，微信从一开始就支持在 `attached` 生命周期中调用 `setData` 函数动态添加初始化数据，在上述的父子 `props` 传递场景中，也能够在子组件的 `attached` 中正确获取这部分数据，支付宝和字节小程序一开始并不支持该能力，不过支付宝在 `component2` 组件系统重构后，字节在橙心合作项目中与我们沟通后，都成功支持了该能力。

而对于动态返回的方法，最简单能想到的方案就是直接挂载到组件实例上，经过我们的完整测试，上述业内主流小程序平台都支持使用这种方式动态添加方法，基于以上事实，我们非常确定组合式 API 能够在小程序环境中顺利实现，下图简要展示了 Mpx 支持组合式 API 的初始化流程：

![composition-api-init](https://dpubstatic.udache.com/static/dpubimg/0bxxw8bB9PJxXLeiMQ__6_composition-api-init.png)

### 生命周期钩子函数

在组合式 API 中，`setup` 函数只有在组件创建时初始化单次执行，因此需要提供一系列生命周期钩子函数来代替选项式 API 中的生命周期钩子选项，由于小程序原生只支持选项式的生命周期注册方式，我们通过`预注册 -> 驱动`的方式来实现 `setup` 中函数式注册生命周期钩子的语法糖，简单来讲就是使用选项式 `mixins` 的方式提前注册所有需要的生命周期钩子，在选项式生命周期钩子执行时驱动对应在 `setup` 中使用生命周期钩子函数注册的代码逻辑执行，如下图所示：

![composition-api-hook](https://dpubstatic.udache.com/static/dpubimg/2nmOjxvubyk6H32yP5cFc_composition-api-hook.png)

作为跨端小程序框架，Mpx 需要兼容不同小程序平台不同的生命周期，在选项式 API 中，我们在框架中内置了一套统一的生命周期，将不同小程序平台的生命周期转换映射为内置生命周期后再进行统一的驱动，以抹平不同小程序平台生命周期钩子的差异，如微信小程序的 `attached` 钩子和支付宝小程序的 `onInit` 钩子，在组合式 API 中，我们沿用了同样的逻辑，设计了一套与框架内置生命周期对应的生命周期钩子函数，以相同的方式进行驱动，因此这些生命周期钩子函数天然具备了跨平台特性，下表显示了在组件 / 页面中框架生命周期与原生平台生命周期的对应关系：

|框架内置生命周期|Hooks in `setup`|微信原生|支付宝原生|
|:------------|:------------------|:-----|:-------|
| BEFORECREATE | `null` |attached（数据响应初始化前）|onInit（数据响应初始化前）|
| CREATED | `null` |attached（数据响应初始化后）|onInit（数据响应初始化后）|
| BEFOREMOUNT | onBeforeMount |ready（`MOUNTED` 执行前）|didMount（`MOUNTED` 执行前）|
| MOUNTED | onMounted |ready（`BEFOREMOUNT` 执行后）|didMount（`BEFOREMOUNT` 执行后）|
| BEFOREUPDATE | onBeforeUpdate |`null`（`setData` 执行前）|`null`（`setData` 执行前）|
| UPDATED | onUpdated |`null`（`setData` callback）|`null`（`setData` callback）|
| BEFOREUNMOUNT | onBeforeUnmount |detached（数据响应销毁前）|didUnmount（数据响应销毁前）|
| UNMOUNTED | onUnmounted |detached（数据响应销毁后）|didUnmount（数据响应销毁后）|
| ONLOAD | onLoad |onLoad|onLoad|
| ONSHOW | onShow |onShow|onShow|
| ONHIDE | onHide |onHide|onHide|
| ONRESIZE | onResize |onResize|events.onResize|

> 同 Vue3 一样，Mpx 在组合式 API 中没有提供 `BEFORECREATE` 和 `CREATED` 对应的生命周期钩子函数，用户可以直接在 `setup` 中编写相关逻辑。

#### 具有副作用的页面事件

在小程序中，一些页面事件的注册存在副作用，即该页面事件注册与否会产生实质性的影响，比如微信中的 `onShareAppMessage` 和 `onPageScroll`，前者在不注册时会禁用当前页面的分享功能，而后者在注册时会带来视图与逻辑层之间的线程通信开销，对于这部分页面事件，我们无法通过`预注册 -> 驱动`方式提供组合式 API 的注册方式，用户可以通过选项式 API 的方式来注册使用，通过 `this` 访问组合式 API `setup` 函数的返回。

然而这种使用方式显然不够优雅，我们考虑是否可以通过一些非常规的方式提供这类副作用页面事件的组合式 API 注册支持，例如，借助编译手段。我们在运行时提供了副作用页面事件的注册函数，并在编译时通过 `babel` 插件的方式解析识别到当前页面中存在这些特殊注册函数的调用时，通过框架已有的`编译 -> 运行时注入`的方式将事件驱动逻辑添加到当前页面当中，以提供相对优雅的副作用页面事件在组合式 API 中的注册方式，同时不产生非预期的副作用影响，简单示例如下：

```js
import { createPage, ref, onShareAppMessage } from '@mpxjs/core'

createPage({
  setup () {
    const count = ref(0)

    onShareAppMessage(() => {
      return {
        title: '页面分享'
      }
    })

    return {
      count
    }
  }
})
```

目前我们通过这种方式支持的页面事件如下：

| 页面事件 | Hooks in `setup` | 平台支持 |
|:------------|:------------------|:-----|
| onPullDownRefresh | onPullDownRefresh | 全小程序平台 + web |
| onReachBottom | onReachBottom | 全小程序平台 + web |
| onPageScroll | onPageScroll | 全小程序平台 + web |
| onShareAppMessage | onShareAppMessage | 全小程序平台 |
| onTabItemTap | onTabItemTap | 微信/支付宝/百度/QQ |
| onAddToFavorites | onAddToFavorites | 微信 / QQ |
| onShareTimeline | onShareTimeline | 微信 |
| onSaveExitState | onSaveExitState | 微信 |

> **特别注意**，由于静态编译分析实现方式的限制，这类页面事件的组合式 API 使用需要满足页面事件注册函数（如`onShareAppMessage`）的调用和 `createPage` 的调用位于同一个 js 文件当中。

关于生命周期钩子函数的更多信息可以查看[这里](../guide/composition-api/composition-api.md#lifecycle-hooks)。

### `<script setup>`

同 Vue3 一样，我们在 `.mpx` 单文件组件 / 页面中实现了 `<script setup>` 的组合式 API 编译语法糖，相较于常规的写法，`<script setup>` 具备以下优势：

* 更少的样板内容，更简洁的代码
* 能够使用纯 TypeScript 声明 props 类型
* 更好的 IDE 类型推导性能

简单使用示例如下：

```html
<script setup>
  import { ref } from '@mpxjs/core'

  const msg = ref('hello')

  function log () {
    console.log(msg.value)
  }
</script>
<template>
  <view>msg: {{msg}}</view>
  <view ontap="log">click</view>
</template>
```

可以看到使用方式与 Vue3 基本一致，不过由于 Mpx 的组合式 API 设计实现与 Vue3 存在差异，对应 `<script setup>` 也与 Vue3 中存在一些差异：

* 不支持 `import` 快捷注册组件
* 没有 `defineEmits()` 编译宏
* 没有 `useSlots()` 和 `useAttrs()` 运行时函数
* 以编译宏的形式提供了 `useContext()`，获取 `setup` 函数的第二个参数 `context`
* `defineExpose()` 编译宏的作用与 Vue3 中有所差别，能够限定模板中能访问的变量范围

> **特别注意**，受小程序底层技术限制，我们在 Mpx 的实现中无法像 Vue3 那样将模板编译的渲染函数和 `<script setup>` 放置到同一作用域下进行变量访问，而是通过静态编译分析提取出 `<script setup>` 的顶层作用域变量，再以上文中提到的动态添加数据与方法的方式将其设置到模板当中，如果 `<script setup>` 中声明了较多顶层作用域变量，它们并不一定都会被模板访问，就会带来无效的性能开销，因此我们强烈建议使用 `defineExpose()` 限定模板中能访问的变量范围，你可以把它等同于 `setup` 函数中的 `return`。

关于 `<script setup>` 的更多信息可以查看[这里](../guide/composition-api/composition-api.md#script-setup)。

### 组合式 API 与 Vue3 中的差异

我们来总结一下 Mpx 中组合式 API 与 Vue3 中的区别：

* `setup` 的 `context` 参数不同，详见[这里](../guide/composition-api/composition-api.md#context)
* `setup` 不支持返回**渲染函数**
* `setup` 不能是异步函数
* `<script setup>` 提供的宏方法不同，详见[这里](../guide/composition-api/composition-api.md#script-setup)
* `<script setup>` 不支持 `import` 快捷注册组件
* 支持的生命周期钩子不同，详见[这里](../guide/composition-api/composition-api.md#lifecycle-hooks)
* 模板引用的方式不同，详见[这里](../guide/composition-api/composition-api.md#template-ref)

关于组合式 API 的更多信息可以查看[这里](../guide/composition-api/composition-api.md)。

## 响应式 API 实现

组合式 API 的正常工作离不开响应式 API 的支持，下面我们来聊聊 Mpx 中响应式 API 的设计实现。我们知道 Vue3 中响应式 API 基于 `proxy` 进行了重构实现，但是目前 `proxy` 的浏览器兼容占比仍然无法达到我们对于线上可用性的要求，因此在 Mpx 中，我们仍然基于 `Object.defineProperty` 进行核心数据响应能力的实现，同时借鉴了 Vue3 中优秀的代码设计与实现，如 `reactiveEffect` 和 `effectScope` 等，尽可能实现与 Vue3 中响应式 API 能力对齐。

说到这里，很多同学可能会想到 `@vue/composition-api` 这个库，该库提供的关键能力正是基于 Vue2 的数据响应系统模拟实现 Vue3 中的响应式 API，我们在前期也对 `@vue/composition-api` 在 Mpx 中的复用进行了非常有价值的探索尝试。不过最终我们还是决定在 Mpx 的运行时框架中进行独立实现，原因主要在于：`@vue/composition-api` 是作为一个 Vue2 插件存在，无法直接侵入 Vue2 源码，导致部分能力无法实现或会带来额外的性能开销，例如 `flush: 'post'` 和 `ref` 自动解包等。我们也看到在最新的 Vue2.7 版本中，也是在运行时框架里重新实现了这部分内容，以规避上述问题。

下图展示了 Mpx 中响应式 API 核心模块依赖关系：

![composition-api-reactive](https://dpubstatic.udache.com/static/dpubimg/4ySdEqTRhc_DRWWCJWrhJ_composition-api-reactive.png)

### 数据响应限制带来的差异

由于 `Object.defineProperty` 的能力限制，Mpx 存在和 Vue2 一致的数据响应限制，无法感知到对象 property 的添加和删除以及数组的索引赋值，与 Vue2 一致，我们暴露了 `set` 和 `del` API 来让用户显式地进行相关操作。除此之外，由于使用方式发生了变化，我们在使用 `reactive` API 创建响应式数据时，还会遇到新的限制，我们来看一下代码示例：

```js
import { reactive, watchSyncEffect, set } from '@mpxjs/core'

const state = reactive([0, 1, 2, 3])

watchSyncEffect(() => {
  console.log(JSON.stringify(state)) // [0,1,2,3]
})

set(state, 1, 3) // 不会触发 watchEffect

state.push(4) // 不会触发 watchEffect
```

可以看出，即使我们使用了 `set` API 和数组原型方法对数组进行修改，我们仍然无法监听到数据变化。

> 相同的限制在使用 `Object.defineProperty` 的 Vue2.7 中也同样存在。

为什么会存在这个限制呢？原因在于：基于 `Object.defineProperty` 实现的数据响应系统中，我们会对对象的每个已有属性创建了一个 `Dep` 对象，在对该属性进行 `get` 访问时通过这个对象将其与依赖它的观察者 `ReactiveEffect` 关联起来，并在 `set` 操作时触发关联 `ReactiveEffect` 的更新，这是我们大家都知道的数据响应的基本原理。但是对于新增/删除对象属性和修改数组的场景，我们无法事先定义当前不存在属性的 `get/set` (当然这在 `proxy` 当中是可行的)，因此我们会把对象或者数组本身作为一个数据依赖创建 `Dep` 对象，**通过父级访问**该数据时定义的 `get/set` 将其关联到对应的 `ReactiveEffect`，并在对数据进行新增/删除属性或数组操作时通过数据本身持有的 `Dep` 对象触发关联 `ReactiveEffect` 的更新，如下图所示：

![数据响应原理](https://dpubstatic.udache.com/static/dpubimg/XkI9cQBsLy_7np-T3rt56_composition-api-reactive2.png)

需要注意的是，**通过父级访问**是建立 `Dep` 与 `ReactiveEffect` 关联关系的先决条件，在选项式 API 中，我们访问组件的响应式数据都需要通过 `this` 进行访问，相当于这些数据都存在 `this` 这个必要的**父级**，因此我们在使用 `$set/$delete` 进行对对象进行新增/删除属性或对数组进行修改时都能得到符合预期的结果，唯一的限制在于不能新增/删除根级数据属性，原因就在于 `this` 不存在访问它的父级。

但是在组合式 API 中，我们不需要通过 `this` 访问响应式数据，因此通过 `reactive()` 创建的响应式数据本身就是根级数据，我们自然无法通过上述方式感知到根级数据自身的变化（在 Vue3 中，基于 `proxy` 提供的强大能力响应式系统能够精确地感知到数据属性，甚至是当前不存在属性的访问与修改，不需要为数据自身建立 `Dep` 对象，自然也不存在相关问题）。

在这种情况下，我们就需要用 `ref()` 创建响应式数据，因为 `ref` 创建了一个包装对象，我们永远需要通过 `.value` 来访问其持有的数据（不管是显式访问还是隐式自动解包），这样就能保证 `ref` 数据自身的变化能够被响应式系统感知，因此也不会遇到上面描述的问题，如下所示：

```js
import { ref, watchSyncEffect, set } from '@mpxjs/core'

const state = ref([0, 1, 2, 3])

watchSyncEffect(() => {
  console.log(JSON.stringify(state.value)) // [0,1,2,3]
})

set(state.value, 1, 3) // [0,3,2,3]

state.value.push(4) // [0,3,2,3,4]
```

### 响应式 API 与 Vue3 中的区别

我们来总结一下 Mpx 中响应式 API 与 Vue3 中的区别：

* 不支持 `raw` 相关 API（`markRaw` 除外，我们提供了该 API 用于跳过部分数据的响应式转换）
* 不支持 `readonly` 相关 API
* 不支持 `watchEffect`、`watch`、`computed` 的调试选项
* 不支持对 `map`、`set` 等集合类型进行响应式转换
* 受到 `Object.defineProperty` 实现带来的数据响应限制影响

关于响应式 API 的更多信息可以查看[这里](../guide/composition-api/reactive-api.md)。

## 生态周边适配

除了 Mpx 运行时核心提供了组合式 API 支持外，我们对 Mpx 的周边生态能力也都进行了组合式 API 适配支持，包括 `store`、`i18n`、`fetch` 等。

### Pinia store 支持

Pinia 是基于组合式 API 设计的全新数据管理方案，目前已经取代 Vuex 成为 Vue3 官方推荐的 store，我们在研究了 pinia 的设计实现后，对其简练优雅的设计思想及其与组合式 API 的高度适配非常满意（特别是在使用 `setup` 函数创建 store 时，使用心智与编写组件完全一致，可以将其视作是没有视图的组件）。因此我们 fork 了 pinia 的源码仓库，基于 Mpx 提供的数据响应能力对其进行了适配改造，使其在 Mpx 环境下也能正常运行，目前相关代码维护在 `@mpxjs/pinia` 中，在组合式 API 中的简单使用示例如下：

```js
import { createComponent, ref, computed, toRefs } from '@mpxjs/core'
import { defineStore } from '@mpxjs/pinia'

// 使用组合式 API 创建 pinia store 的使用心智与 setup 函数完全一致，强烈推荐
const useSetupStore = defineStore('setup', () => {
  const count = ref(0)
  const doubleCount = computed(() => count.value * 2)

  function increment () {
    count.value++
  }

  return { count, doubleCount, increment }
})

createComponent({
  setup () {
    const store = useSetupStore()
    // store 同 props 类似是一个 reactive 对象，解构数据需使用 toRefs 以保持数据响应性
    const { count, doubleCount } = toRefs(store)
    // 方法可以直接解构
    const { increment } = store
  
    return { count, doubleCount, increment }
    //
  }
})
```

Mpx 中通过 `createStore` 创建的类 Vuex store 在组合式 API 中仍然可以使用，我们可以在 `setup` 函数中引用 store 实例进行[数据读取与方法调用](../guide/advance/store.md#use-store-in-composition-api)，不过整体使用体验与 pinia store 存在较大差距，我们还是推荐在组合式 API 开发中优先使用 pinia store 作为数据管理方案。

### I18n 支持

传统选项式 API 中，我们使用 `this.$t` 方法在组件内调用翻译函数，但在组合式 API 中我们无法访问 `this`，为此我们参考了 Vue I18n 最新的 9.x 版本，该版本针对 Vue3 及组合式 API 进行了重构适配，提供了全新的 `useI18n` API，简单使用示例如下：

```html
<template>
  <view>{{t('message.hello')}}</view>
  <button bindtap="changeLocale">change locale</button>
</template>

<script>
  import { createComponent, useI18n } from '@mpxjs/core'

  createComponent({
    setup () {
      // useI18n 不传参数时指向全局 i18n 对象，也可以传递 locale 和 messages 配置创建局部 i18n 对象
      const { t, locale } = useI18n()

      function changeLocale () {
        locale.value = locale.value === 'zh-CN' ? 'en-US' : 'zh-CN'
      }
      // 返回的翻译方法名必须为 t，不能进行重命名
      return { t, changeLocale }
    }
  })
</script>
```

> 上面示例代码看上去像是我们在模板上直接调用 setup() 返回的 t 翻译方法，但是熟悉小程序开发的同学都知道在小程序架构下这是不可能的，示例中的写法其实由框架通过编译 + 运行时手段实现的语法糖，我们会在模板编译时定向扫描 t/te/tm 等 i18n 方法，将其转换为计算属性注入到运行时当中，这就意味着如果我们对翻译方法进行重命名，模板编译时无法识别出 i18n 方法调用，自然也就无法正常运行。

Mpx 中 i18n 提供了两种实现模式，分别是 wxs 和 computed，可以使用编译选项中的 `i18n.isComputed` 进行切换，两种方式各有优劣，其中：

* wxs 模式的优势在于逻辑层和视图层独立维护语言集，无额外运行时性能开销，且使用没有任何限制；劣势同样源于语言集同时存在于逻辑层（js）和视图层（wxs）当中，这部分的包体积占用翻倍；
* computed 模式的优势在于语言集只存在于逻辑层中，无额外包体积占用，且可以通过动态添加语言集的方式进一步减少包体积占用；劣势则是会产生额外的运行时性能开销，且使用上存在限制，模板调用时无法直接访问 `wx:for` 中的 `item` 和 `index`。

在组合式 API 中模板上使用 `useI18n()` 返回的翻译函数 `t/te/tm` 时，为了完整实现 `useI18n` API的功能，会强制使用 computed 模式进行实现，这也意味着该用法会受到 computed 模式使用限制的影响。不过当你不需要使用 `useI18n` 接受 `messages` 参数创建局部语言集作用域功能时，你也完全可以在模板中继续使用原有的 `$t/$tc/$te/$tm` 方法，这些方法受编译选项 `i18n.isComputed` 的影响，同时指向全局语言集作用域。

更多关于生态周边的组合式 API 使用指南可以点击下方链接查看详情：

* [store](../guide/advance/store.md#use-store-in-composition-api)
* [i18n](../guide/advance/i18n.md#composition-api-usage)
* [fetch](../guide/extend/fetch.md#composition-api-usage)

## 输出 web 适配

跨端输出 web 作为 Mpx 的一大核心特性，在业务中存在广泛使用，同时也是我们设计实现任何框架新特性需要优先考虑的事项。在本次组合式 API 支持中，我们从设计之初就考虑了跨端输出 web 的适配支持，保障使用 Mpx 组合式 API 开发的业务代码都能在 web 环境中正常运行。

我们输出 web 的整体技术方向在于尽可能复用 Vue 已有的生态能力，为了实现这个目标，我们需要提供尽可能与 Vue 保持一致的 API 设计，以降低抹平适配成本。在输出 web 时，核心组合式 API 基于 Vue2.7 版本中的已有能力进行适配提供，简单举个例子：对于 `import { ref } from 'mpxjs/core'` 这行语句，在小程序中会指向 Mpx 内部维护的 `ref` 实现，而在输出 web 时会指向 Vue 中维护的 `ref` 实现，两者的实现虽然不仅相同，但只要保障对外函数签名一致，对于开发者用户来说就无感知。

我们借助了 Mpx 强大的条件编译能力进行上述实现，对运行时导出根据输出平台进行重定向，这样还能保障跨端输出产物干净简洁，仅包含当前输出环境下必要的逻辑，如下图所示：

![composition-api-web](https://dpubstatic.udache.com/static/dpubimg/E0FojaPKOxZOa5h5OEPQk_composition-api-web.png)

同理，我们也采用了类似的方式实现了组合式 API 周边能力对于输出 web 的适配支持，如pinia store 使用 pinia 原始版本进行适配实现，而 i18n 能力则是使用 vue-i18n@8.x + vue-i18n-bridge 进行适配实现。

## 性能表现

性能是 Mpx 一直以来的核心关注点，我们对组合式 API 的最终实现版本进行了一系列性能评估测试，我们使用组合式 API 版本对业务中的评价组件进行了重构，评价组件属于我们业务中交互及功能相对比较复杂的组件，源码行数约 1000 行，组件数据 27 项，组件方法 18 个，我们在测试项目中对选项式 API 和组合式 API 两个版本实现的组件进行了一系列测试。

### 组件初始化耗时

由于组合式 API 改变了原有的组件初始化流程，我们对组件的初始化耗时进行了重点测试，测试口径如下：

* 耗时计算以挂载组件为起点，以组件 `ready` 执行为终点
* 测试结果为10次手工测试排除最大最小值后求均值
* IOS 测试机型为 iPhone 13 pro max，安卓测试机型为 OPPO R9

结果显示两个版本的组件初始化耗时大抵持平，不分优劣。

|    |IOS  |安卓  |
|----|-----|-----|
|选项式 API|42.5ms|366.6ms|
|组合式 API|42.4ms|370.1ms|

### 组件 JS 体积

在构建产物体积方面，由于组合式 API 的写法对于 JS 代码压缩更加有利，同样的逻辑实现下，组合式 API 版本的组件构建压缩后 JS 体积略胜一筹。

|    |组件 JS 体积|
|----|-----|
|选项式 API|15.67KB|
|组合式 API|13.60KB|

### 框架运行时体积 {#framework-runtime-size}

在 Mpx2.8 版本中，我们在框架运行时中新增了组合式 API 相关实现，不过通过优化运行时导出，使其对 tree shaking 更加友好，我们的框架运行时体积在实际构建产物中没有产生太大增长。

|    |框架运行时体积|
|----|-----|
|选项式 API|51.66KB|
|组合式 API|57.47KB|

综上所述，组合式 API 版本的运行时性能与选项式 API 大抵持平，在包体积占用方面，新版框架运行时体积占用略有提升，不过由于组合式 API 开发模式对代码压缩更友好，加上组合式 API 更易进行逻辑复用的特点，我们预计在实际业务项目中，组合式 API 的包体积占用会更小。

## 破坏性改变

Mpx 组合式 API 版本完全兼容原有的选项式 API 开发方式，不过我们在运行时重构过程中依然带来了少量的破坏性改变，详情如下：

* 框架过往提供的组件增强生命周期 `pageShow/pageHide` 与微信原生提供的 `pageLifetimes.show/hide` 完全对齐，不再提供组件初始挂载时必定执行 `pageShow` 的保障（因为组件可能在后台页面进行挂载），相关初始化逻辑一定不要放置在 `pageShow` 当中；
* 取消了框架过去提供的基于内部生命周期实现的非标准增强生命周期，如 `beforeCreate/onBeforeCreate` 等，直接将内部生命周期变量导出提供给用户使用，详情查看[这里](../api/global-api.md#built-in-lifecycle-variable);
* 为了优化 tree shaking，作为框架运行时 `default export` 的 `Mpx` 对象不再挂载 `createComponent/createStore` 等运行时方法，一律通过 `named export` 提供，`Mpx` 对象上仅保留 `set/use` 等全局 API，详情查看[这里](../api/global-api.md#global-mpx)；
* 使用 I18n 能力时，为了与新版 vue-i18n 保持对齐，`this.$i18n` 对象指向全局作用域，如需创建局部作用域需要使用组合式 API `useI18n` 的方式进行创建。
* `watch` API 不再接受第二个参数为带有 `handler` 属性的对象形式（该参数形式只应存在于 `watch` option 中），第二个参数必须为回调函数，与 [Vue](https://vuejs.org/api/reactivity-core.html#watch) 对齐。

更详细的迁移指南请点击查看[这里](../guide/migrate/2.8.md)。

## 未来规划 {#future-plan}

在完成编译持久化缓存和组合式 API 支持后，我们已经完成了去年规划中最大的两个技术升级，后续我们的技术规划如下：

* 支持使用 Vite 进行 web 构建
* 完善 Mpx 跨端输出 Hummer 并正式 release
* 优化运行时 render 函数，降低包体积占用
* 内置支持原子类使用
* Mpx-cube-ui 正式开源

最后，再次感谢所有参与 Mpx 组合式 API 技术建设的同学们，也欢迎社区同学加入 Mpx 项目开源共建。

---

---
url: /articles/2.9-release.md
---
# Mpx2.9 版本正式发布，支持原子类、SSR 和包体积优化 {#mpx-2-9-release}

> 作者：[hiyuki](https://github.com/hiyuki)

[Mpx](https://github.com/didi/mpx) 是滴滴开源的一款增强型跨端小程序框架，自2018年立项开源以来如今已经进入第六个年头，在这六年间，Mpx 根植于业务，与业务共同成长，针对小程序业务开发中遇到的各类痛点问题提出了解决方案，并在集团内部建设了完善的小程序跨端开发生态。目前，Mpx 已经覆盖支持了集团内部全量小程序业务开发，成为了集团小程序开发的统一技术标准。

随着小程序业务的发展演进，性能和包体积的重要性愈发凸显，Mpx从设计之初就非常重视性能和包体积的优化，本次的 **Mpx2.9** 版本更新带来的三大核心特性——原子类、SSR 和包体积优化也都与性能和包体积息息相关，下面我们逐个展开介绍。

## 原子类支持 {#atomic-class-support}

原子类(utility-first CSS)是近几年流行起来的一种全新的样式开发方式，在前端社区内取得了良好的口碑，越来越多的主流网站也基于原子类进行开发，比较知名的有 [Github](https://github.com/)，[OpenAI](https://openai.com/)，[Netflix](https://top10.netflix.com/) 和 [NASA官网](https://www.jpl.nasa.gov/) 等。使用原子类离不开原子类框架的支持，常用的原子类框架有 [Tailwindcss](https://tailwindcss.com/)、[Windicss](https://windicss.org/) 和 [Unocss](https://unocss.dev/) 等。

在 Mpx2.9 版本中，我们在框架中内置了原子类支持，让小程序开发也能使用原子类。对项目进行简单配置开启原子类支持后，用户就可以在 Mpx 页面/组件模板中直接使用一些预定义的基础样式类，诸如 flex，pt-4，text-center 和 rotate-90 等，对样式进行组合定义，并且在 Mpx 支持的所有小程序平台和 web 平台中正常运行，下面是一个简单示例：

```html

<view class="container">
  <view class="flex">
    <view class="py-8 px-8 inline-flex mx-auto bg-white rounded-xl shadow-md">
      <view class="text-center">
        <view class="text-base text-black font-semibold mb-2">
          Erin Lindford
        </view>
        <view class="text-gray-500 font-medium pb-3">
          Product Engineer
        </view>
        <view class="mt-2 px-4 py-1 text-sm text-purple-600 font-semibold rounded-full border border-solid border-purple-200">
          Message
        </view>
      </view>
    </view>
  </view>
</view>
```

通过这种方式，我们在不编写任何自定义样式代码的情况下得到了一张简单的个人卡片，实际渲染效果如下：

![utility-css-demo](https://dpubstatic.udache.com/static/dpubimg/Or3aaN-mmxV8pK-LmEVPm_demo.png)

相较于传统的自定义类编写样式的方式，使用原子类能给你带来以下这些好处：

* **不用再烦恼于为自定义类取类名**，传统样式开发中，我们仅仅是为某个元素定义样式就需要绞尽脑汁发明一些抽象的类名，还得提防类名冲突，使用原子类可以完全将你从这种琐碎无趣的工作中解放；
* **停止 css 体积的无序增长**，传统样式开发中，css 体积会随着你的迭代不断增长，而在原子类中，一切样式都可以复用，你几乎不需要编写新的 css；
* **让调整样式变得更加安全**，传统 css 是全局的，当你修改某个样式时无法保障其不会破坏其他地方的样式，而你在模板中使用的原子类是本地的，你完全不用担心修改它会影响其他地方。

而相较于使用内联样式，原子类也有一些重要的优势：

* **约束下的设计**，使用内联样式时，里面的每一个数值都是魔法数字（magic number）
  ，而通过原子工具类，你可以选择一些符合预定义设计规范的样式，便于构筑具有视觉一致性的UI；
* **响应式设计**，你无法在内联样式中使用媒体查询，然而通过原子类框架中提供的响应式工具，你可以轻而易举地构建出响应式界面；
* **Hover、focus 和其他状态**，使用内联样式无法定义特定状态下的样式，如 hover 和 focus，通过原子类框架的状态变量能力，我们可以轻松为这些状态定义样式。

看到这里相信你已经迫不及待地想要在 Mpx 中体验原子类开发了吧，使用最新版本的 `@mpxjs/cli` 脚手架创建项目时，在 prompt 中选择使用原子类，就可以在新创建的项目模版中直接使用原子类，可使用的工具类可以参考 [交互示例](https://unocss.dev/interactive/)，在已有项目中开启原子类支持可以参考[配置指南](../guide/advance/utility-first-css.md#compile-config)

### 小程序原子类使用注意事项 {#atomic-class-notes}

小程序和 web 环境对于 css 的支持存在底层差异，小程序内也存在大量自身独有的技术特性，Mpx 在支持原子类时针对这些环境特异性进行了抹平和适配，在框架的支持下，我们实现了大部分（超过90%）原子类功能和工具类在小程序环境下正常使用，并额外支持了原子类产物的分包输出和样式隔离下的原子类使用，详情如下：

#### 特殊字符转义 {#special-char-escape}

现代原子类框架支持 `value auto-infer`（值自动推导），可以在模版中根据相关规则书写灵活的自定义值原子类，如 `p-5px bg-[hsl(211.7,81.9%,69.6%)]` 等，针对原子类中出现的 `[` `(` `,` 等特殊字符，在 web 中会通过转义字符 `\` 进行转义，由于小程序环境下不支持 css 选择器中出现 `\` 转义字符，我们内置支持了一套不带 `\` 的转义规则对这些特殊字符进行转义，同时替换模版和 css 文件中的类名，内建的默认转义规则如下：

```js
const escapeMap = {
  '(': '_pl_',
  ')': '_pr_',
  '[': '_bl_',
  ']': '_br_',
  '{': '_cl_',
  '}': '_cr_',
  '#': '_h_',
  '!': '_i_',
  '/': '_s_',
  '.': '_d_',
  ':': '_c_',
  ',': '_2c_',
  '%': '_p_',
  '\'': '_q_',
  '"': '_dq_',
  '+': '_a_',
  $: '_si_',
  // unknown用于兜底不在上述范围中未知的转义字符
  unknown: '_u_'
}
```

与此同时，用户也可以通过传递 `@mpxjs/unocss-plugin` 的 [escapeMap](../api/compile.md#escapemap) 配置项来覆盖内建的转义规则。

#### 原子类分包输出 {#atomic-class-subpackage}

在 web 中，原子类会被全部打包输出单个样式文件，一般会放置在顶层样式表中以供全局访问，但在小程序中这种全量的输出策略并不是最优的，主要原因在于小程序中可供全局访问的主包体积存在 **2M 大小限制**，主包体积十分紧缺珍贵，Mpx 在构建输出时遵循着分包优先的原则，尽可能充分利用分包体积从而减少对主包体积的占用，再进行原子类产物输出时，我们也遵循了相同的原则。

在Mpx中，我们在收集原子类时同时记录了每个原子类的引用分包，在收集结束后根据每个原子类的分包引用数量决定该原子类应该输出到主包还是分包当中，我们在 `@mpxjs/unocss-plugin` 中提供了 [minCount](../api/compile.md#mincount) 配置项来决定分包的输出规则，该配置项的默认值为2，即当一个原子类被2个或以上分包引用时，会被作为公共原子类抽取到主包中，否则输出到所属分包中，这也是全局最优的策略。当我们想要让原子类输出产物更少地占用主包体积时，我们也可以将`minCount`值调大，让原子类抽取到主包的条件更加苛刻，不过这样也会伴随着原子类分包冗余的增加。

`unocss.config.js` 配置中定义的 `safelist` 原子类默认会输出到主包，为了组件局部使用的 `safelist` 有输出到分包的机会，我们在模版中提供了[注释配置](../api/compile.md#commentconfig)（comments config），灵感来源于 `webpack` 中的魔法注释（magic comments），用户可以在组件模版中通过`注释配置`声明当前组件所需的 `safelist`，对应的原子类也会根据上述的规则输出到主包或分包中，使用示例如下：

```html
<template>
  <!-- mpx_config_safelist: 'text-red-500 bg-blue-500' -->
  <!-- 动态样式中可以使用text-red-500和bg-blue-500原子类 -->
  <view wx:class="{{classObj}}">test</view>
  <!-- ... -->
</template>
```

#### 样式隔离与组件分包异步 {#style-isolation-and-async}

在小程序中，自定义组件的样式默认是隔离的，web 中通过全局样式访问原子类的方式不再生效，不过由于小程序提供了[样式隔离配置](https://developers.weixin.qq.com/miniprogram/dev/framework/custom-component/wxml-wxss.html#%E7%BB%84%E4%BB%B6%E6%A0%B7%E5%BC%8F%E9%9A%94%E7%A6%BB)，我们可以将该组件样式隔离配置调整为 `apply-shared` 来获取页面或 app 中定义的原子类，但是当我们在使用传统类名和原子类混合开发或者迁移原子类的过程中，我们往往希望保留原本自定义组件的样式隔离。

针对这种情况，我们在 `@mpxjs/unocss-plugin` 中提供了 [styleIsolation](../api/compile.md#styleisolation) 配置项，可选设置为 `isolated`|`apply-shared`，当设置为 `isolated` 时每个组件都会通过 `@import` 独立引用主包或者分包的原子类样式文件，因此不会受到样式隔离的影响；当设置为 `apply-shared` 时，只有 app 和分包页面会引用对应的原子类样式文件，自定义组件需要通过配置样式隔离为 `apply-shared` 使原子类生效。

在组件分包异步的情况下对应组件即使将样式隔离配置为 `apply-shared` 的情况下，`@mpxjs/unocss-plugin` 也需要将  `styleIsolation` 设置为 `isolated` 才能正常工作，原因在于组件分包异步的情况下，组件被其他分包的页面所引用渲染，由于上述原子类样式分包输出的规则，其他分包的页面中可能并不包含当前组件所需的原子类，只有在 `isolated` 模式下由组件自身引用所需的原子类样式才能保证正常工作，类似于 `safelist`，我们也提供了[注释配置](../api/compile.md#commentconfig)的方式对组件的 `styleIsolation` 模式进行局部配置，示例如下：

```html
<template>
  <!-- mpx_config_styleIsolation: 'isolated' -->
  <!-- 当前组件会直接引用对应主包或分包的原子类样式 -->
  <view class="@dark:(text-white bg-dark-500)">
    <!-- ... -->
</template>
```

### 原子类使用参考文档 {#atomic-class-docs}

Mpx 中使用原子类的详细参考文档如下：

* [原子类使用指南](../guide/advance/utility-first-css.md)
* [原子类 API 参考](../api/compile.md#mpxunocssplugin)

## 输出 web 支持 SSR {#web-ssr-support}

近些年来，SSR/SSG 由于其良好的首屏展现速度和SEO友好性逐渐成为主流的技术规范，各类SSR框架层出不穷，未来进一步提升性能表现，在 SSR 的基础上还演进出 [islands architecture](https://docs.astro.build/en/concepts/islands/) 和 [0 hydration](https://qwik.builder.io/docs/concepts/resumable/) 等更加精细复杂的理念和架构。

近两年随着团队对于前端性能的重视，SSR/SSG 技术也在团队业务中逐步推广落地，并在首屏性能方面取得了显著的收效。但由于过去 Mpx 对 SSR 的支持不完善，使用 Mpx 开发的跨端页面一直无法享受到 SSR 带来的性能提升，在 Mpx2.9 版本中，我们对 web 输出流程进行了大量适配改造，解决了 SSR 中常见的内存泄漏、跨请求状态污染和数据预请求等问题，完整实现了 SSR 技术方案。

### 配置使用 SSR {#ssr-config}

在 Vue SSR 项目中，我们一般需要提供 server entry 和 client entry 两个文件作为 webpack 的构建入口，然后通过 webpack 构建出 server bundle 和 client bundle。在用户访问页面时，在服务端使用 server bundle 渲染出 HTML 字符串，作为静态页面发送到客户端，然后在客户端使用 client bundle 通过水合（hydration）对静态页面进行激活，实现可交互效果，下图展示了 Vue SSR 的大致流程。

![Vue SSR流程](https://img-hxy021.didistatic.com/static/webappstatic/do1_kWBH7L8mTgpHeKsBKp85)

Mpx SSR 实现的大致流程思路与 Vue 一致，不过为了保持与小程序代码的兼容性，在配置使用上有一些改动差异，下面我们详细展开介绍：

#### 构建server/client bundle {#build-server-client-bundle}

SSR项目中，我们需要分别构建出 server bundle 和 client bundle，对于不同环境的产物构建，我们需要进行不同的配置。
在 Vue 中，我们需要提供 `entry-server.js` 和 `entry-client.js` 两个文件分别作为 server 和 client 的构建入口，与 Vue 不同，在 Mpx 中我们通过编译处理与运行时增强生命周期实现了使用 `app.mpx` 作为统一构建入口，无需区分 server 和 client。

##### 服务端构建配置 {#server-build-config}

服务端配置中除了将 entry 制定为 `app.mpx` 及其它基础配置外，最重要的是安装 `vue-server-renderer` 包中提供的  `server-plugin` 插件，该插件能够构建产出 `vue-ssr-server-bundle.json` 文件供 `renderer` 后续消费。

```js
// webpack.server.config.js
const VueSSRServerPlugin = require('vue-server-renderer/server-plugin')

module.exports = merge(baseConfig, {
  // 将 entry 指向项目的 app.mpx 文件
  entry: './app.mpx',
  // ...
  plugins: [
   // 产出 `vue-ssr-server-bundle.json`
    new VueSSRServerPlugin()
  ]
})
```

更加详细的配置说明可参考 [Vue SSR的服务端配置](https://v2.ssr.vuejs.org/guide/build-config.html#server-config)

##### 客户端构建配置 {#client-build-config}

类似服务端构建配置，在客户端构建中我们需要使用 `vue-server-renderer` 包中 `client-plugin` 插件来帮助我们生成客户端环境的资源清单 `vue-ssr-client-manifest.json`，并供 `renderer` 后续消费。

```js
// webpack.client.config.js
const VueSSRClientPlugin = require('vue-server-renderer/client-plugin')

module.exports = merge(baseConfig, {
  // 将 entry 指向项目的 app.mpx 文件
  entry: './app.mpx',
  // ...
  plugins: [
    // 产出 `vue-ssr-client-manifest.json`。
    new VueSSRClientPlugin()
  ]
})
```

更加详细的配置说明可参考 [Vue SSR的客户端配置](https://v2.ssr.vuejs.org/guide/build-config.html#client-config)

#### 准备页面模版 {#prepare-page-template}

SSR 渲染中，我们创建 `renderer` 需要一个页面模板，简单的示例如下：

```html
<!DOCTYPE html>
<html lang="en">
  <head><title>Hello</title></head>
  <body>
    <!--vue-ssr-outlet-->
  </body>
</html>
```

与 CSR 渲染模版不同，SSR 渲染模版中需要提供一个特殊的 `<!--vue-ssr-outlet-->`注释，标记 SSR 渲染产物的插入位置，如使用 `@mpxjs/cli` 脚手架创建 SSR 项目，该模版已经内置于脚手架中。

#### 集成启动 SSR 服务 {#ssr-service-integration}

当我们准备好页面模版和双端构建产物后，我们就可以创建 `renderer` 并与 Node 服务进行集成，启动 SSR 服务，下面以 `express` 为例：

```js
//server.js
const app = require('express')()
const { createBundleRenderer } = require('vue-server-renderer')
// 通过 vue-server-renderer/server-plugin 生成的文件
const serverBundle = require('../dist/server/vue-ssr-server-bundle.json')
// 通过 vue-server-renderer/client-plugin 生成的文件
const clientManifest = require('../dist/client/vue-ssr-client-manifest.json')
 // 页面模版文件
const template = require('fs').readFileSync('../src/index.template.html', 'utf-8')
// 创建 renderer 渲染器
const renderer = createBundleRenderer(serverBundle, {
    runInNewContext: false,
    template,
    clientManifest,
});
// 注册启动 SSR 服务
app.get('*', (req, res) => {
  const context = { url: req.url }
  renderer.renderToString(context, (err, html) => {
    if (err) {
      res.status(500).end('Internal Server Error')
      return
    }
    res.end(html);
  })
})
app.listen(8080)
```

### SSR 生命周期 {#ssr-lifecycle}

在 Mpx 2.9 的版本中，我们提供了三个全新用于 SSR 的生命周期，分别是`onAppInit`、`serverPrefetch` 和 `onSSRAppCreated`，以统一服务端与客户端的构建入口，下面展开介绍：

#### onAppInit

在 SSR 中用户每发出一个请求，我们都会为其生成一个新的应用实例，`onAppInit` 生命周期会在应用创建 `new Vue(...)` 前被调用，其执行的返回结果会被合并到创建应用的 `options` 中

很常见的使用场景在于返回新的全局状态管理实例，Mpx 中提供了 `@mpxjs/pinia` 作为全局状态管理工具，我们可以在 `onAppInit` 中返回全新的 `pinia` 示例避免产生跨请求状态污染，示例如下：

```js
// app.mpx
import mpx, { createApp } from '@mpxjs/core'
import { createPinia } from '@mpxjs/pinia'

createApp({
  // ...
  onAppInit () {
    const pinia = createPinia()
    return {
      pinia
    }
  }
})
```

#### serverPrefetch

当我们需要在 SSR 使用数据预拉取时，可以使用这个生命周期进行，使用方法与 Vue 一致, 示例如下：

选项式 API：

```js
import { createPage } from '@mpxjs/core'
import useStore from '../store/index'

createPage({
  //...
  serverPrefetch () {
    const query = this.$route.query
    const store = useStore(this.$pinia)
    // return the promise from the action, fetch data and update state
    return store.fetchData(query)
  }
})
```

组合式 API：

```js
import { onServerPrefetch, getCurrentInstance, createPage } from '@mpxjs/core'
import useStore from '../store/index'

createPage({
  setup () {
    const store = userStore()
    onServerPrefetch(() => {
      const query = getCurrentInstance().proxy.$route.query
      // return the promise from the action, fetch data and update state
      return store.fetchData(query)
    })
  }
})
```

关于数据预拉取更详细的说明可以查看[这里](https://v2.ssr.vuejs.org/guide/data.html)。

#### onSSRAppCreated

在 Vue SSR 项目中，我们会在 `entry-server.js` 中导出一个工厂函数，在该函数中实现创建应用实例、路由匹配和状态同步等逻辑，并返回应用实例 `app`。

在 Mpx SSR 中，我们将这部分逻辑整合在 `onSSRAppCreated` 中执行，该生命周期执行时用户可以从参数中获取应用实例 `app`、路由实例 `router`、数据管理实例 `pinia` 和 SSR 上下文 `context`，在完成必要的操作后，该生命周期需要返回一个 `resolve(app)` 的 promise。

通常我们会在 `onSSRAppCreated` 中进行路由路径设置和数据预拉取后的状态同步工作，示例如下：

```js
// app.mpx
createApp({
    // ...,
    onSSRAppCreated ({ pinia, router, app, context }) {
      return new Promise((resolve, reject) => {
        // 设置服务端路由路径
        router.push(context.url)
        router.onReady(() => {
          // 应用完成渲染时执行
          context.rendered = () => {
            // 将服务端渲染后得到的 pinia.state 同步到 context.state 中，
            // context.state 会被自动序列化并通过 `window.__INITIAL_STATE__`
            // 注入到 HTML 中，并在客户端运行时再读取同步
            context.state = pinia.state.value
          }
          // 返回应用程序实例
          resolve(app)
        }, reject)
      })
    }
})
```

如用户没有配置 onSSRAppCreated，框架内部会执行兜底逻辑，以保障 SSR 的正常运行。

### 其他注意事项 {#ssr-other-notes}

1. Mpx SSR 渲染支持 i18n 的功能，但为了防止内存泄漏，当前 i18n 实例不会随着每次请求而重新创建，这是由于 Vue2.x 版本插件机制的设计缺陷所造成的，因此在使用 i18n 进行 SSR 时可能会产生跨请求状态污染的问题，这个问题会在未来 Mpx 输出 web 切换为 Vue3 后完全解决。

2. 在服务端渲染阶段，对于 global 全局对象访问修改，如\_\_mpx, \_\_mpxRouter, \_\_mpxPinia 都可能导致全局状态污染，所以在服务端渲染阶段请尽量避免进行相关操作；对于存在全局访问修改的方法，如 getApp(), getCurrentPages() 等在服务端渲染中被调用时，会产生相关报错提示。

3. 由于服务器无法收到 URL 中的 hash 信息，使用 SSR 时需要通过修改 `mpx.config.webRouteConfig` 将路由模式设置成 `history` 模式。

## 包体积优化 {#bundle-size-optimization}

近几年来随着小程序的商业成功和用户增长，各大互联网公司都在加大对小程序业务的投入，小程序的体量和复杂性都在快速增长，在这样的背景下，小程序的包体积大小成为了制约小程序业务迭代发展的一大限制，同时过大的包体积也会显著影响小程序的性能表现。

Mpx 在设计之初就考虑了包体积问题，完整继承了 webpack 已有的代码优化能力，如公共模块抽离、tree shaking、混淆压缩等。除此之外，我们还设计开发了业内最完善的分包构建流程，完整支持基于配置声明和依赖分析的普通分包、独立分包及分包异步化的构建输出，极大地缓解了复杂小程序中的主包和总包体积过大的问题。在 Mpx2.9 版本中，我们针对复杂小程序页面组件和 JS 模块众多的特点，对构建产物进行了针对性地优化，进一步降低了构建产物体积，主要优化项如下：

### 模版代码优化 {#template-code-optimization}

Mpx 通过 webpack 进行打包构建，并对小程序原生 commonjs 支持进行适配改造，以实现 webpack 构建产物在小程序环境下运行，为了将构建产物中的模块和 chunk 链接到一起，webpack 和 mpx 会在构建产物生成一些模版代码进行相关工作，下面是一个页面 js 中包含的模版代码示例：

```js
var self = {}
self.webpackChunkmpx_test_2_8 = require('../bundle.js')
(self.webpackChunkmpx_test_2_8 = self.webpackChunkmpx_test_2_8 || []).push([[405], {
  1307: function (t, e, o) {
    // ...
  },
  4236: function (t) {
    // ...
  },
  // ...
}, function (t) {
  var e
  e = 1307, t(t.s = e)
}])
```

可以看出模版代码主要由 chunk 链接代码，chunk id，模块 id 和模块包装函数组成，对于中小项目来说，这些模版代码一般不会占用太多体积，但是在复杂大体量小程序中众多模块的叠加效应下，这部分体积就变得不可忽视。

我们对模版代码的生成逻辑和生成产物进行分析，发现 webpack 生产模式的默认配置中，很多配置项并不是体积最优的选项，一个典型的例子在于模块/chunk id：为了保障生成产物的内容稳定，来尽可能提升浏览器的缓存利用率，webpack 默认的模块/chunk id 采用 `deterministic` 模式进行生成，该模式下模块 id 为模块源路径的定长数字 hash，比项目模块总数长 1 位。由于在小程序中代码包按照版本的维度进行全量管理，保证文件局部的内容稳定在小程序环境下无正向意义，这就有了优化空间，我们可以简单将模块/chunk id 的生成逻辑改为数字自增，在主小程序中就能节省出上百 KB 总包体积。

类似的可优化点还存在于 chunk 链接代码和模块包装函数当中，我们在 `@mpxjs/webpack-plugin@2.9` 版本中提供了一个新的配置项 [optimizeSize](../api/compile.md#optimizesize)，其中整合了一系列模版代码体积优化配置，开启后就能自动优化构建产物中的模版代码体积，在实际业务中，我们开启 `optimizeSize` 后可以减少总包体积约 **1.6%**，效果非常显著，下面是上述示例在开启 `optimizeSize` 后的产物对比：

```js
var g = {}
g.c = require('../bundle.js'), (g.c = g.c || []).push([[8], {
  448: function (t, e, o) {
    // ...
  },
  463: function (t) {
    // ...
  }
  // ...
}, function (t) {
  var e
  e = 448, t(t.s = e)
}])
```

### 空模块移除 {#empty-module-removal}

Mpx 在处理 `.mpx` 单文件时会将其分拆为 `template/js/style/json` 四个新模块来进行分别处理，其中 `template/style/json` 部分的内容会在处理后通过内置的 `extractor` 抽取输出为静态文件，抽取之后原本分拆出来的模块就会以空模块的形式残留在构建产物中（template 模块在抽取后还需要保留 render 函数和 refs 等信息所以不会成为空模块），如下所示：

```js
/***/ 533:
/***/ (function(__unused_webpack_module, __unused_webpack_exports, __webpack_require__) {
// ...
/* template */
__webpack_require__(535)
/* styles */
__webpack_require__(536)
/* json */
__webpack_require__(537)
/* script */
__webpack_require__(534)
/***/ }),
/***/ 536:
/***/ (function() {
/***/ }),
/***/ 537:
/***/ (function() {
/***/ })
```

从上面示例中可以看出 `536/537` 模块的定义和引用都是完全不必要的，但由于 webpack 本身对于空模块没有进行识别和优化的手段，在过去的版本中这些空模块代码会占用我们一部分总包体积。在 Mpx2.9 版本中，我们定义了全新的依赖类型 `CommonjsExtractDependency` 对于这类可能被抽取成为空模块的 `request` 进行识别处理，当模块内容在完成抽取后为空时，自动将其从模块图中移除，并在产物生成时不再生成其引用代码。该项优化措施内置开启，升级后自动生效，在实际业务中可减少总包体积约 **0.7%**。

### Render函数优化 {#render-function-optimization}

Render 函数是 Mpx 运行时 `setData` 优化的一项核心设计，我们在模版编译时将用户模版转换为简易的 render 函数，该函数执行时能够完全模拟视图渲染的数据访问过程，正确地收集当前视图的数据依赖，避免将视图不需要的数据通过 `setData` 发送到视图中。

![render函数](https://dpubstatic.udache.com/static/dpubimg/ZQ6p8Rs2m7QCumOll3nmd.jpg)

虽然我们生成的简化版 render 函数仅保留了数据访问逻辑，在代码体积上并不算大，但是仍然存在着一定的优化空间，我们来看下面这个例子：

```js
function render(){
  this.a
  if(this.c){
    this.a
    this.b
    this.c.a
    this.c.b
    this.d
  }
  this.b
}
```

可以看出 `if block` 下存在着大量冗余不必要的数据访问，例如 `this.a` 和 `this.b` 在父级 `block` 中已经进行过访问，`this.c.a` 和 `this.c.b` 由于在 `if condition` 中进行过 `this.c` 的访问也不再必要（render函数执行时会对模版依赖数据进行深度diff，父路径访问后子路径就无需再进行访问），上述 render 函数可以优化为：

```js
function render(){
  this.a
  if(this.c){
    this.d
  }
  this.b
}
```

在 Mpx2.9 版本中，我们通过两轮 `ast` 遍历（`2 pass ast travese`）的方式实现了这个优化，在第一轮遍历中，我们收集了数据访问信息并按照 `block` 结构存储在 `blockVisitTree` 中，第二轮遍历时依据 `blockVisitTree` 中的信息对不必要的数据访问进行剪枝优化。

除此之外，我们也大幅优化了 render 函数中的数据收集代码，有效地降低了 render 函数的体积占用。

该优化目前没有默认开启，可以通过 `@mpxjs/webpack-plugin` 中的 [optimizeRenderRules](../api/compile.md#optimizerenderrules) 配置项配置生效范围进行开启，全量开启后在实际业务中可节省总包体积约 **5%**。

## 未来规划 {#future-plan}

在未来，我们对 Mpx 构建产物还有进一步的优化方案可以探索实施，主要分为两个方向：

* 编译注入代码优化，在功能不变的情况下简化编译注入的代码，对于 render 函数也有一种运行时有损的方案（略微增大运行时开销）可以尝试
* 模版和JSON压缩，对模版和JSON中的组件名及组件路径进行短哈希压缩，缺点是丢失dist产物的可读性，可能需要对其提供 sourceMap 支持

除此之外，我们近期的框架升级计划还包括：

* 局部运行时渲染增强
* 数据响应升级为 proxy 实现，输出 web 升级为 vue3
* 支付宝 2.0 基础库适配优化
* 微信 skyline 适配优化
* 输出 Hummer 能力完善

在构建提速方面，我们也会在以下方向进行探索：

* 输出 web 支持 vite 构建
* 基于模块联邦的分布式构建
* 基于 Rust 的高性能构建探索

最后，特别感谢@[pagnkelly](https://github.com/pagnkelly)、@[yandadaFreedom](https://github.com/yandadaFreedom)和
@[zhuzhh](https://github.com/zhuzhh)对于 2.9 版本功能开发的突出贡献，也欢迎大家使用 Mpx 进行小程序跨端开发并加入社区共建。

Github：https://github.com/didi/mpx

官网/文档：https://mpxjs.cn/

---

---
url: /articles/2.11-release.md
---
# Mpx 2.11.0 版本正式发布，跨端样式能力增强，对 AI coding 更加友好 {#mpx-2-11-release}

> 作者：hiyuki

在 Mpx 2.11.0 中，我们围绕跨端输出 RN 做了一轮中型版本升级。本次升级的主线在于：让 Mpx2RN 的样式能力更接近 Web / 小程序开发者熟悉的 W3C 语义，让 `class`、`wx:class`、`style`、`wx:style` 等不同样式入口具备一致能力，同时继续降低 RN 运行时高频渲染路径的成本。

对于正在将小程序项目输出到 RN 的团队来说，这意味着更少的平台差异、更少的条件编译，以及更稳定的复杂页面渲染性能。

## 跨端样式能力拉齐 W3C 标准 {#rn-style-standard-alignment}

RN 原生样式体系和 Web / 小程序之间存在较大天然差异，Mpx2RN 过去通过编译与运行时结合的方式对齐进行了系统性抹平，但是在文本继承、盒模型默认值和 CSS 简写属性等细节能力上仍存在差异，2.11.0 对这些差异进行了查缺补漏进一步抹平，使其更加符合 W3C 标准。

### 文本样式继承

首先是文本样式继承。RN 原生要求文本内容必须落在 `Text` 节点中，很多文本样式也只能直接作用在 `Text` 上；而 Web / 小程序中更常见的写法，是在 `view` 这类容器节点上统一声明 `color`、`font-size`、`line-height`、`text-align` 等文本表现，再由内部文本自然继承。这个差异过去会直接暴露给跨端适配：同一块 UI 在小程序中只需要切换容器状态，在 RN 侧却可能需要额外找到每个内部文本节点并补齐样式。

2.11.0 中，Mpx2RN 可以将容器节点上的文本样式透传到 Mpx 子树中的 `text` 节点，即使中间存在非 text 组件也不会中断；父级 `text` 的文本样式也可以继续传递给嵌套的子 `text`。这让“在容器上描述文本表现”的写法更加接近 Web / 小程序心智，尤其适合卡片选中态、主题色切换、禁用态、深浅色模式、局部字号缩放等场景。

| 有文本样式继承 | 无文本样式继承 |
| --- | --- |
| ![有文本样式继承时，AI 跨端适配能够正确处理内部文字选中态高亮](https://dpubstatic.udache.com/static/dpubimg/ibU61iu65XyqzFs2GSXEi.png) | ![没有文本样式继承时，AI 未能正确处理内部文字选中态高亮](https://dpubstatic.udache.com/static/dpubimg/eYUif85LfrJsOUHz30J3-.png) |
| 选中态只需要作用在外层卡片，内部“4分钟 / 预计车辆到站 / 一中公交站”等文本可以继承高亮色，AI 迁移时更容易保留原始设计语义。 | AI 只处理了容器背景色，内部文本仍保持默认深色，视觉上没有形成正确的选中态高亮。 |

这个能力带来的收益不只是少写几行样式。对于复杂业务组件来说，文本节点往往分散在多层组件、条件渲染和插槽结构里，选中态的文字颜色、字号、行高如果不能从容器继承，就需要在模板、样式和脚本之间反复传递状态。人手改造容易遗漏某个分支，AI 改造则更容易只修到当前可见节点，忽略隐藏态、异步数据或组件内部文本。文本样式继承把这类跨端差异收敛到框架运行时，业务代码可以继续表达“这张卡片被选中，所以卡片内文字进入高亮态”，而不需要把这个意图拆成多个 RN 专属细节。

当然，文本样式继承也有明确边界。Mpx2RN 继承的是文本相关样式，包括 `color`、`font*`、`text*`、`letterSpacing`、`lineHeight`、`includeFontPadding`、`writingDirection` 等；布局、盒模型、背景、边框等非文本样式不会被当作文本样式继承。`numberOfLines`、`ellipsizeMode` 属于文本截断能力，不会作为普通文本样式继续向更深层文本传递。如果某个容器的文本样式或文本截断属性只会在后续动态数据中出现，需要在首次渲染时显式声明 `enable-text-pass-through`。

```html
<!-- 首次渲染时 selected 可能为 false，容器上还没有 color；
     后续切换选中态时，需要提前声明 enable-text-pass-through。 -->
<view
  class="station-card"
  enable-text-pass-through
  wx:style="{{
    selected
      ? { color: '#fff', background: '#ff5a35' }
      : { background: '#f0f4fa' }
  }}"
>
  <text class="eta">4分钟</text>
  <text class="desc">预计车辆到站</text>
  <view class="station-wrapper">
    <text class="station">一中公交站</text>
  </view>
</view>
```

如果容器在首次渲染时已经通过 class 或 style 带有文本样式，通常不需要额外配置；`enable-text-pass-through` 主要用于上面这种“初始无文本样式，后续动态出现文本样式或文本截断属性”的场景。

### 默认盒模型拉齐

其次是默认盒模型，RN 原生默认 `box-sizing` 使用 `border-box`，而非 Web / 小程序默认的 `content-box`。2.11.0 中 Mpx2RN 默认将业务节点盒模型对齐到 `content-box`，同时提供了 `rnConfig.defaultBoxSizing` 配置，存量业务需要快速升级时仍可按需切回 `border-box`。这能显著减少固定宽高、padding、border 同时存在时的跨端布局偏差。

```js
import mpx from '@mpxjs/core'
// 正常不建议开启该配置
mpx.config.rnConfig.defaultBoxSizing = 'border-box'
```

### 样式简写能力增强

最后是简写属性能力增强，本次重点补齐和强化的 CSS 简写属性如下：

| 属性 | 支持形式 | 处理说明 |
| --- | --- | --- |
| `gap` | `gap: <row-gap> <column-gap>?` | 展开为 `rowGap` / `columnGap`；单值同时作用于行列，百分比在运行时按容器尺寸换算。 |
| `inset` | `inset: <top> <right>? <bottom>? <left>?` | 按 CSS 四值规则展开为 `top` / `right` / `bottom` / `left`。 |
| `border`、`border-top`、`border-right`、`border-bottom`、`border-left` | `<width>`、`<style>`、`<color>` 顺序不敏感 | 按值类型展开到对应 `border*Width`、`borderStyle`、`borderColor`；缺省宽度按 `medium = 3px` 补齐，缺省样式按 `none` 处理。 |
| `outline` | `<width>`、`<style>`、`<color>` 顺序不敏感 | 展开为 `outlineWidth` / `outlineStyle` / `outlineColor`；缺省规则与 `border` 对齐，`outline-style: none` 会在运行时转换为 `outlineWidth: 0`，最终表现依赖 RN 版本的 `outline` 能力。 |
| `font` | `[font-style] [small-caps] [font-weight] <font-size> [/ <line-height>] <font-family>` | 展开为 `fontStyle`、`fontVariant`、`fontWeight`、`fontSize`、`lineHeight`、`fontFamily`；`font-size` 与 `font-family` 必填，不支持的可选 token 会被忽略并告警。 |
| `text-decoration` | `none` / `underline` / `line-through`，可组合 `solid` / `double` / `dotted` / `dashed` 与颜色 | 展开为 `textDecorationLine` / `textDecorationStyle` / `textDecorationColor`；`underline line-through` 会合并为同一个 `textDecorationLine`，`style` / `color` 表现受 RN 平台能力约束。 |
| `text-shadow` | `<offset-x> <offset-y>? <blur-radius>? <color>?` | 展开为 `textShadowOffset` / `textShadowRadius` / `textShadowColor`；缺少 `offset-y` 时按 `0` 补齐，颜色缺省为 `#000`。 |
| `background` | `url()` / `linear-gradient()` / 颜色 / `no-repeat` / `none`，并支持 `<position> / <size>` | 展开为 `backgroundImage`、`backgroundColor`、`backgroundRepeat`、`backgroundPosition`、`backgroundSize`；`background-size` 支持 `contain`、`cover`、`auto` 和长度值，不支持多重背景。 |

部分无序简写会按 CSS 规范根据值类型解析，例如 `border: red solid 1px` 与 `border: 1px solid red` 都能得到正确结果。`background` 也进一步支持 `background-position / background-size` 语法。

```css
.card {
  gap: 24rpx 16rpx;
  inset: 0 24rpx;
  border: #e5e5e5 solid 1px;
  outline: red solid 1px;
  font: italic bold 28rpx / 1.5 Arial;
  text-decoration: underline dotted #1677ff;
  text-shadow: 0 2rpx 4rpx rgba(0, 0, 0, 0.2);
  background: url("https://example.com/bg.png") no-repeat center / cover #fff;
}
```

## 运行时样式增强 {#runtime-style-enhancement}

2.11.0 的另一个重点，是补齐运行时样式入口的处理能力，让 `style` / `wx:style` 和编译期 `class` / `wx:class` 样式能力实现平权。

过去一些样式增强主要发生在 `<style>` / class 编译阶段，而通过 `style`、`wx:style` 等动态入口进入的样式，可能无法获得同等处理。现在 Mpx2RN 在运行时补齐了 CSS var / UnoCSS var 解析、简写展开、`flex` / `background` / `transform` / `font` 样式转换等同编译期一致的样式处理能力。

这意味着：

* `class` / `wx:class` 中可用的样式简写属性，`flex` / `background` / `transform` / `font` 等需要 Mpx 转换处理的样式，现在在 `style` / `wx:style` 中同样可用。
* CSS var 和 fallback 中同样可使用上述简写属性和特定样式，不再受限。

对开发者来说，这一点非常关键：动态样式不再是“弱一等”的入口。很多原本需要拆成长属性、绕开 CSS 变量或写条件分支的场景，现在可以保持更自然的 CSS 写法。

```html
<view
  class="card"
  wx:style="{{
    {
      margin: '16rpx 24rpx',
      border: active ? '2rpx solid #1677ff' : '0',
      background: `var(--card-bg, #fff)`
    }
  }}"
/>
```

## 对 AI 生成与迁移代码更友好 {#ai-friendly-development}

Mpx2RN 样式能力的增强，也是在提升框架对 AI 编程的友好度。

在跨端输出 RN 的旧适配模式中，很多 Web / 小程序中自然成立的写法，在 RN 侧并不原生支持。例如容器上的文本样式继承、CSS var 中使用简写属性、`style` 中动态写入 `border` / `background` / `font` 等简写，都可能需要被拆成多处等效实现：模板里补 `text` 或迁移属性，样式里拆成长属性，脚本里配合动态 class / style，必要时还要加条件编译。这样的改造往往不是单文件修改，而是模板、样式、脚本甚至组件调用方之间的协同调整。

对人来说，这类改造已经很容易遗漏边界；对 AI 来说，风险会更高。AI 可能只看到了某个样式属性不兼容，于是局部替换成 RN 写法，却没有同步处理原平台表现、动态样式入口、CSS 变量 fallback、文本子树继承关系或组件默认样式优先级。最终结果可能是“看起来改了”，但实际影响面难以评估。

2.11.0 通过框架层统一抹平这些差异，让 AI 更容易生成正确代码，也更容易安全地改造旧项目：

* 容器文本样式继承由运行时统一处理，AI 不需要为了 RN 单独重排文本节点结构。
* 简写属性在 `class`、`wx:class`、`style`、`wx:style` 等入口中的能力更一致，AI 不需要根据入口差异拆成不同写法。
* 默认盒模型、文本缩放、简写展开和组件默认样式优先级都有稳定规则，AI 更少依赖隐性平台知识。
* 跨端差异收敛到框架内部后，代码审查时也更容易判断一次 AI 改动的真实影响面。

换句话说，本次升级不只是让手写代码更接近标准 CSS 心智，也让 AI 生成、迁移和重构 Mpx2RN 代码时拥有更稳定的目标语义。

下面是一组 AI 迁移同一小程序页面到 Mpx2RN 的效果对比。可以看到，旧版框架中更容易出现文本样式丢失和层级样式不一致的问题；升级到 2.11.0 后，适配结果与源平台效果更加接近，文字颜色、字号和整体视觉层次的偏差明显降低。

| 微信小程序效果 | Mpx2RN skill 适配效果（旧版框架 2.10.21） | Mpx2RN skill 适配效果（新版框架 2.11.0） |
| --- | --- | --- |
| ![微信小程序源页面效果](https://dpubstatic.udache.com/static/dpubimg/Tv0d1sMr56iaG_n15n32v.png) | ![Mpx2RN skill 在旧版框架 2.10.21 中的适配效果，存在较明显的文字样式丢失](https://dpubstatic.udache.com/static/dpubimg/EmHp6XaPYGpIuS8Ep7XSW.png) | ![Mpx2RN skill 在新版框架 2.11.0 中的适配效果，文字样式和源平台更加接近](https://dpubstatic.udache.com/static/dpubimg/sCKdmUd3Hub25HmbDq0UQ.png) |

适配 2.11.0 的新版 skills 已经同步发布，详情查看当前仓库内：.agents/skills/mpx2rn

## RN 运行时性能优化 {#rn-runtime-performance}

在样式能力增强的同时，我们也对 RN 运行时热路径做了一轮性能优化，重点覆盖 `view`、`text`、`simple-view`、`simple-text`、`image`、`useTransformStyle`、`background` 等高频链路。

本轮优化主要围绕几类通用手段展开：在样式处理前先判断是否真正命中特殊能力，避免普通节点进入完整增强流程；在拆分 style / props 时尽量复用原对象引用，减少临时对象分配；在背景、图片等高频能力上延迟或跳过不必要的解析、状态更新和回调绑定；同时压缩组件默认逻辑中的无效分支，让列表、卡片这类重复节点在批量渲染和全量更新时少做无关工作。

我们构造了一个接近业务真实压力的商品网格页面 DEMO 做了对比验证：页面包含 500 张商品卡片，单轮渲染约 1000 个 view、1000 个 text，500 张卡片均使用了本地背景图。测试场景为 Android 设备 20 轮采样，对比“背景图 + 全量更新”下从触发页面更新到 `$nextTick` 的总耗时。

| 版本 | `JS 初始化 -> onReady` 平均耗时 | `全量更新 -> nextTick` 平均耗时 | 说明 |
| --- | --- | --- | --- |
| 原版本 | 8135ms | 6004ms | 样式增强优化前 |
| 优化版本 | 7917ms | 3989ms | 样式增强优化后 |

> 平均值按报告口径剔除最高 2 个与最低 2 个样本后计算。优化版本为快的那组数据，原版本为慢的那组数据。

可以看到，首屏 `onReady` 的总耗时变化不大，主要收益集中在全量更新链路：`全量更新 -> nextTick` 从 6004ms 降到 3989ms，更新总耗时下降约 **33.6%**。这也符合本轮优化的预期：首屏初始化受 JS 初始化、页面创建、资源加载等因素共同影响，而全量更新会集中放大 view / text / background / props / innerProps 等运行时热路径差异。

进一步看 `@mpxjs/perf` 的框架内置探针，优化收益更加清晰。全量更新 window 中，原版本 `view:render:total` avg 为 1.422ms，优化版本为 0.894ms，原版本相对优化版本慢 **59.0%**；`view:render:createElement` 慢 **80.4%**，`view:render:props` 慢 **137.5%**，`text:render:style` 慢 **71.9%**。这说明优化收益并不主要来自 `getStyle` 本身，而是来自 render 链路上的 props 拆分、innerProps 处理、文本样式处理、background 子节点构造等高频成本下降。

| 指标 | 优化版本 avg | 原版本 avg | 原版本相对优化版本 |
| --- | --- | --- | --- |
| `view:render:total` | 0.894ms | 1.422ms | +59.0% |
| `view:render:style` | 0.344ms | 0.423ms | +22.8% |
| `view:render:createElement` | 0.482ms | 0.869ms | +80.4% |
| `view:render:props` | 0.022ms | 0.053ms | +137.5% |
| `text:render:style` | 0.070ms | 0.121ms | +71.9% |

峰值数据也印证了这一点。在全量更新场景下，原版本 `view:render:total` max 可达到 69.83ms，优化版本为 13.67ms；原版本 `text:render:total` max 为 26.27ms，优化版本为 2.59ms。也就是说，本轮优化不仅降低了平均耗时，也明显压低了复杂样式更新下的长尾尖峰。

对于大列表、复杂卡片、带背景图或渐变的页面，这类优化会更明显地体现在滚动、全量刷新和批量状态更新等交互场景中。

此外，本版本继续完善了 `@mpxjs/perf` 运行时测速探针，作为框架内部性能分析与业务定位问题的辅助工具。它不是本次升级的使用重点，但为后续持续优化 RN 运行时热路径提供了更贴近 Mpx 抽象层的数据来源。

## 实现原理 {#implementation-principle}

作为 2.11.0 新增支持的核心能力，本章会结合示例介绍文本样式继承的实现原理，性能考量，以及其是如何与运行时样式能力增强结合工作的。

文本样式继承并不是简单地把父级 `style` 原样塞给子级 `text`。它依赖一条更完整的运行时样式处理链路：先把来自 `class`、`wx:class`、`style`、`wx:style` 等入口的样式，经过 CSS var 解析、`calc()` 处理、样式简写处理和单位换算等步骤，规整成稳定的 RN style，再从中拆出真正可继承的文本样式，最后通过上下文传递给文本子树。运行时样式增强负责前半段的标准化，文本样式继承负责后半段的上下文传递和最终合并，两者配合后才能让“在容器上描述文本表现”的写法在 RN 侧继续成立。

下面以一个具体父子结构为例：顶层 `view` 声明 `color` 与 `font` 简写，中间 `view` 只有布局样式，底部两个 `text` 分别声明 `font-size` / `line-height` 和 `font` 简写。运行时会在每一层按需处理样式，并让最终表现尽量贴近 W3C 中“父级文本样式可被文本后代继承、子级自身样式后合并覆盖”的心智。

![Mpx2RN 父子文本样式继承与运行时性能优化流程](https://dpubstatic.udache.com/static/dpubimg/5xH2dnbGWbFwKJpUgAb_A_2.11-runtime-style-text-inheritance.png)

首先，顶层 `view` 的样式会进入 `useTransformStyle`。这一层处理的是运行时样式增强：如果样式来自 `style` / `wx:style`，其中的 `font`、`background`、`border`、`gap`、CSS var、`calc()`、百分比等写法会和 class 编译产物一样被标准化处理。以示例中的 `font: 600 24rpx / 150% Arial` 为例，运行时会按需展开为 `fontWeight`、`fontSize`、`lineHeight`、`fontFamily` 等 RN 可识别字段；如果这些值来自 CSS var 或动态表达式，也会先完成变量解析、百分比 / `calc()` 处理和必要的单位转换。

样式标准化之后，`splitStyle` 会把结果拆成三类：布局、盒模型、背景等普通样式继续留给当前 `View`；`backgroundImage`、`backgroundSize`、`backgroundPosition` 等背景样式交给 `mpx-view` 的背景子节点处理；`color`、`font*`、`text*`、`lineHeight` 等文本相关字段则被拆成 `textStyle`。这一步是文本继承的边界：只有文本表现会进入继承链路，布局、背景、边框等非文本样式不会被错误传递给后代 `Text`。

拆出的 `textStyle` 会交给 `useTextPassThrough`，与父级文本上下文合并后写入 `TextPassThroughContext`，再由 `wrapChildren` 包裹子树。这里有一个关键细节：父级的 `lineHeight: '150%'` 不会在顶层 `view` 上提前算成固定数字，而是继续以百分比中间态向下传递。因为真正应该决定行高基准的是最终 `text` 节点合并后的 `fontSize`，而不是某个祖先容器的字号。

再看中间 `view`。它只有 `padding` 这类布局样式，没有 `color`、`font*`、`text*`、`lineHeight` 等文本样式。此时运行时不会创建新的文本上下文或 Provider，已有的 `TextPassThroughContext` 会通过 React Context 自然穿过这一层。因为这一层没有需要参与文本继承的内容，运行时可以继续走普通布局样式路径：无文本特殊 key 时尽量复用原对象，也不做额外上下文合并和子树包裹，减少高频渲染中的对象分配和 React 节点开销。

最后到两个底层 `text`。`text A` 自己声明了 `font-size: 20rpx` 和 `line-height: 120%`，运行时会先拿到父级继承的 `color`、`fontWeight`、`fontFamily` 等，再用自身样式后合并覆盖；因此它最终保留父级颜色和字体族，但字号变为自身的 `20`，行高按自身字号计算为 `20 * 120% = 24`。`text B` 则通过 `font: 700 30rpx / 1.2 Arial` 声明自身文本表现，`font` 简写同样先经过运行时样式增强展开，其中 unit-less 的 `1.2` 会先保留为 `120%`，等最终 `fontSize: 30` 确定后再计算出 `lineHeight: 36`。

这套顺序本质上是在 RN 上模拟更接近 CSS 继承与级联的行为：运行时样式增强先把动态样式和简写语义规整到统一形态，父级可继承文本样式再进入上下文，子级自身样式后合并并覆盖，百分比 `font-size` / `line-height` 延迟到最终文本节点再解析。这样既能让“在容器上描述文本表现”的写法继续成立，又能避免混排文本中大字号片段被祖先层提前算出的较小行高压缩。

性能上，这条链路也尽量只在必要时工作。`useTransformStyle` 会先收集 key 特征，再进入 CSS var、`calc()`、百分比、简写展开、背景解析等对应分支，普通样式不会无差别跑完整增强流程；组件默认样式会在用户样式转换完成后再兜底写入，避免用户简写被默认长属性反向覆盖；`splitStyle` / `splitProps` 在没有特殊 key 时尽量复用原对象；文本上下文内容只有发生变化时才替换引用，减少子树无意义更新。对于“首屏没有文本样式、后续动态出现文本样式或截断属性”的节点，则需要提前声明 `enable-text-pass-through`，用稳定的启用状态保障 Hook 执行顺序及子树结构稳定。

## 更多值得关注的能力增强 {#more-highlights}

除上述主线外，2.11.0 还包含一些对 RN 输出和跨端一致性很有价值的能力点：

* RN 模板支持无值布尔属性，例如 `<scroll-view scroll-y />` 会按微信语义等价为 `true`。
* `image`、`video` 及自定义内建组件支持本地静态资源路径，`image` 新增 `is-svg` 属性用于强制 SVG 渲染。
* 新增 RN `section-list` 扩展组件，支持自定义列表头尾、分组头尾、分组吸顶、下拉刷新、手势协同以及 `scrollToIndex()`。
* `picker` 补齐 `range`、`range-key` 动态更新和触发区域文本样式透传能力。
* `createSelectorQuery().select()` / `selectAll()` 支持查询非 `virtualHost` 自定义组件的实体 host 节点。
* 新增 `rnConfig.disablePageTransition` 配置，用于统一关闭 RN 页面转场动画。
* 组件默认样式与用户简写样式的优先级问题得到修复，例如用户写 `border: 0`、`margin: 0`、`flex-flow: column nowrap` 时，不再被组件内部默认长属性反向覆盖。
* `createIntersectionObserver().observe()` 支持传入 refs，并修复多个 `nodeRefs` 场景下的目标解析问题。
* `text-decoration-style` / `text-decoration-color` 会按 iOS、Android 与 Harmony 的实际支持范围进行校验和转换。
* 修复 Android 输入框 `confirm-type` 与触摸交互、相机权限重复请求、安全区顶部初始化、页面级导航栏文字样式，以及 `picker-view-column` 项高度和滚轮动画等问题。
* RN 内建组件过滤小程序属性，避免无效属性直接透传给 RN 原生组件。
* 自定义组件和 built-in 组件的 `displayName` 传递更完整，调试体验更好。
* Web 输出优化 UnoCSS 注入顺序，拉齐小程序中 UnoCSS 覆盖全局样式的行为。
* Web 模板处理增强，支持 `<import>` 与 `<template>` 场景下的模板转译复用。
* RN 环境 API 修复 BLE 连接相关回调管理问题，补齐无效 callback 检查，优化 `offBluetoothAdapterStateChange`、`offBLEConnectionStateChange` 等监听移除语义，并修复鸿蒙默认写入方式。
* `@mpxjs/api-proxy` 补全位置、系统、键盘和相机相关 API 的 TypeScript 类型定义。
* i18n 修复了字面量 key 与路径解析、`NaN` 归一化相关问题。
* URL query 解析修复逗号被误拆分的问题。

## 升级指南 {#upgrade-guide}

Mpx 2.11.0 是一次以跨端样式能力增强为核心的体验升级。它从样式标准拉齐、样式能力补充和运行时样式一致性三个层面显著增强跨端输出 RN 的样式解析能力，并通过精细的运行时热路径优化保障性能，同时提升对人和对 AI 的跨端开发友好度。

对于全新项目，我们推荐直接升级到 2.11.0。新版本可以默认享受更完整的文本样式继承、运行时样式增强、CSS 简写支持、默认盒模型对齐和 RN 运行时性能优化，也能让后续 AI 生成、迁移和重构代码时拥有更稳定的目标语义。

对于存量项目，升级前需要重点关注样式表现回归。由于 2.11.0 的样式能力支持程度与之前版本存在较大差异，一些过去在 RN 侧未生效、被拆解处理或依赖平台差异的样式，升级后可能会按照更接近 Web / 小程序的语义生效。因此建议在升级后对核心页面、复杂组件、动态样式、文本混排、选中态、禁用态、盒模型尺寸等场景进行全量视觉回归，确认最终表现符合预期。

---

---
url: /articles/mpx-cube-ui.md
---
# 小程序跨端组件库 Mpx-cube-ui 开源啦 {#mpx-cube-ui-open-source}

> 作者：[CommanderXL](https://github.com/CommanderXL)

Mpx-cube-ui 是一款基于 [Mpx 小程序框架](https://www.mpxjs.cn/) 的移动端基础组件库，一份源码可以跨端输出所有小程序平台及 Web，同时具备良好的拓展能力和可定制化的能力来帮助你快速构建 Mpx 应用项目。

Mpx-cube-ui 提供了灵活配置的主题定制能力，在组件设计开发阶段对表现层的结构和样式进行抽离，利用预编译器和 CSS 变量的能力，提供细粒度（颜色、字体、圆角、阴影等）的样式定制能力，你的项目可以按需使用主题的编译方案还是运行时方案来满足不同样式风格的业务场景开发。

Mpx-cube-ui 提供了开箱即用的跨端输出能力，源码基于 Mpx 小程序框架进行开发，依托于 Mpx 提供的[跨平台能力](2.0.md#跨平台开发)即基于微信小程序跨平台编译输出为支付宝、百度、QQ、头条等目标平台的小程序代码，同时还可以输出到 Web。

接下来会通过这篇文章去分享一下 Mpx-cube-ui 是如何诞生的。

## 业务现状 {#business-status}

### 集团产品的迭代 {#group-product-iteration}

越来越多的业务产品开始借助小程序的渠道来拓展产品的推广和使用，不同的技术团队承接的不同业务产品方向的需求。在滴滴所有的小程序产品当中，滴滴出行小程序作为最大的C端流量入口，承接了不同业务产品流量分发。在具体到小程序产品的研发环节，不同业务的小程序都被集成到了滴滴出行小程序当中，一同打包上线并发布。
当然在这种跨业务、技术部门的产品研发当中，不同的技术团队都会有自身配套的基础能力建设。就拿小程序的组件库来说，每个独立的业务产品都会依据对应的交互设计规范来搭建一套满足自身业务述求的基础组件用以提高日常的业务开发效率，例如按钮、半浮层弹窗、Toast、Dialog、表单等等。

### 团队内的业务迭代 {#team-business-iteration}

除了跨业务产品研发的场景外，在同一个技术团队内部也可能会承接来自不同业务产品方向的需求，这些不同业务产品同样也会有独立发展迭代的述求。由于业务场景的约束，团队内部同样也会面临如何做基础能力的沉淀和复用的议题，在节省研发资源的同时去提升业务项目交付的质量和效率。

那么在不同的业务产品发展初期，为了快速交付产品的功能保障上线时间，研发侧会尽量利用之前已有的基础能力来快速搭建产品功能。就拿小程序组件库的复用来说，常见的方式有：

* 直接侵入到原有的组件代码当中进行 Hard Code，不同的业务产品依赖同一份组件代码，利用一些 if/else 或者条件编译等手段来使得原有的组件在满足最新的业务述求的同时，还要确保不会影响到原有的业务使用；
* Fork 一份原有组件库的代码，在此基础上单独迭代维护，做到和原有组件的彻底隔离而不会造成污染；

对于第一种方案来说：组件本身因为增量的差异化需求使得组件本身的维护成本变高，同时对于差异化的代码处理难免在编译打包环节出现代码冗余问题，也就是原本不属于当前业务产品的代码实现也被一同打包；
对于第二种方案来说：组件库维护的数量变多，使得后续的组件迭代和更新需要修改多处代码；

此外，在小程序的场景下还面临着包体积等平台规范的硬性约束，特别是对于像滴滴出行小程序这种体量大的小程序来说，众多小程序业务产品被集成到同一个小程序当中，包体积也是日常研发过程中重点关注的一个指标。模块或组件的可复用性好、可拓展性强也意味着不需要重复去开发同一份功能相同代码，随之代码包体积也不会因重复实现相同功能而增速过快。

## Mpx 技术生态 {#mpx-tech-ecosystem}

在 Mpx 整个技术生态当中，组件体系目前是不完备的。

在我们目前使用 Mpx 去搭建实际的业务产品的过程中，我们基于小程序平台的基础组件去搭建了特定业务场景的基础业务组件，因为业务场景、功能和代码实现等各方面的原因，这些业务场景的基础组件是没法开放给社区的 Mpx 开发者来使用的。因此对于社区来说，要么只能同样基于平台的基础组件去开发上层基础组件，或者是使用第三方的原生小程序组件库，不管哪种方式对于社区的开发者而言，都有不少的上手和开发成本。

因此在社区当中也有比较强的述求，期望 Mpx 能提供更为基础通用的组件来更好的支持上层的业务开发。

## 组件库自身的维护 {#component-library-maintenance}

* 文档示例一体化

不管是我们内部维护的业务组件库还是之前我们开源的基于 Vue 的 Web 组件库 [Cube-ui](https://didi.github.io/cube-ui/#/zh-CN)，组件本身的文档示例也是在组件库迭代过程中也是比较占用时间精力的，在示例和文档方面往往需要重复写多份文案，还要确保它们之间是同步更新的。那么针对组件库自身的维护，如何尽量减少组件库本身的维护成本也是我们需要深入思考的一部分工作。

以上这些问题促使我们重新思考整个 Mpx 组件体系的构建和发展。

## Mpx 组件体系 {#mpx-component-system}

经过业务的长期迭代和验证，Mpx-cube-ui 作为 Mpx 技术生态当中组件体系的基础设施：脱离于业务的基础组件库，同时又要有良好的拓展能力和可定制化的能力来更好的支持上层业务。

![组件分层设计](https://gift-pypu-cdn.didistatic.com/static/driver_miniprogram/do1_6wEnx7fVXGlK8hILtuYa)
在整个组件体系的搭建过程中，我们依据组件的特性将组件拆分为如下几种类型：

* 业务组件一般来源于某一个具体的产品功能，用以解决特定问题域，更加强调关注点分离，代码的维护成本；
* 基础业务组件一般来源于某一类的业务产品，在特定的业务背景下抽象的比较通用的，较少糅合业务逻辑，介于基础组件和业务组件之间，强调解决效率，可复用性，可维护性；
* 基础组件一般来源于我们设计交互元语言，用以定义业务产品和用户的交互、反馈，更加强调一致性，效率，可复用性；

底层的基础组件（可组合性、可拓展性、稳定性）是为了更好的服务于上层的（基础）业务组件。

从底层的基础组件到业务组件（由下至上），组件的业务属性越来越强，所要解决的问题域更加聚焦，更贴合具体的问题和场景，同时它们的可复用性也随之降低。

## Mpx-cube-ui 组件设计 {#mpx-cube-ui-design}

这里通过乘客交易、司机运营两个不同业务方向的组件来举例说明 Mpx-cube-ui 在组件的设计和开发当中所做的一些思考。
在这两个业务场景当中都有 Modal 半浮层组件，不过在司乘业务不同的设计规范约束下，组件间的差异还是比较大的。

![mpx-cube-ui-modal](https://gift-pypu-cdn.didistatic.com/static/driver_miniprogram/do1_1EABWsPUeVHTim2iwTUf)

那么为了解决上文当中组件库在跨业务产品的的可复用性、可拓展性的问题，核心所遵循的原则是：

**弱化不同业务场景的设计规范（去业务），回归到组件本身的行为（逻辑）、结构和样式（表现）：**

* 行为，组件所特有的行为方法：展示（show），隐藏（hide），关闭（close）；
* 结构，方便组件间的重新组合：头部区，标题区，内容区，底部操作区；
* 样式，方便业务场景的主题定制：颜色、字号、圆角、边距等；

![组件设计原则](https://gift-pypu-cdn.didistatic.com/static/driver_miniprogram/do1_ceWLvE8RbZIIduHHTdtu)

对于 Mpx-cube-ui 组件的主题定制有个简单的逻辑关系：

* 全局基础样式变量：提供了基本色值、字号等，会影响到所有组件的展示；
* 组件样式变量：对于基本的色值、字号等继承于全局基础变量，涉及到组件自身的结构、样式变量会单独定义；
* 组件渲染样式：直接依赖组件样式变量；

![mpx-cube-ui-modal](https://gift-pypu-cdn.didistatic.com/static/driver_miniprogram/do1_b4uBKbP8yIwdip7pBZAq)

通过定制[全局基础样式变量](https://www.mpxjs.cn/mpx-cube-ui/guide/design-tokens.html)和[组件样式变量](https://www.mpxjs.cn/mpx-cube-ui/components/base/button.html#css-variable)都能达到定制主题的目的，有关主题定制的功能具体参见[文档](https://www.mpxjs.cn/mpx-cube-ui/guide/theme.html)。

在 Mpx-cube-ui 实现的定制主题的方案当中是利用预编译器和 Css Varaibles 的能力来提供细粒度的样式定制能力：

![业务架构图](https://gift-pypu-cdn.didistatic.com/static/driver_miniprogram/do1_3ZVcQITsryAG4k96hFrH)

* 利用预编译器可编程的能力，在编译阶段就可以完成主题能力的定制，当你的业务项目作为独立应用迭代，可以只利用预编译器的能力，从而使得你的 css 代码体积尽可能的小；
* 利用 Css Varaibles 的能力，可以解决更为复杂的场景，例如同一个组件在巨型应用当中，在不同业务场景页面需要有不同的主题样式；

在[官网示例](https://www.mpxjs.cn/mpx-cube-ui/guide/intro.html)当中可以直接体验主题切换功能。

## 未来的规划 {#future-plan}

1. 开源更多我们内部所沉淀出的基础组件，去满足多样化的业务场景开发；
2. 将文档示例一体化的能力独立打包开源，用以组件库的快速建站以及降低文档、示例代码的维护成本。

---

---
url: /articles/mpx-cli-next.md
---
# @mpxjs/cli 插件化改造 {#mpx-cli-plugin-transformation}

[@mxpjs/cli 地址](https://github.com/mpx-ecology/mpx-cli)

## 背景 & 现状 {#background-and-status}

Mpx 脚手架 `@mpxjs/cli` 作为 Mpx 生态当中比较重要的一部分，是使用 Mpx 进行小程序开发的入口。

`@mpxjs/cli@2.x` 版本整体是基于模板配置的方式完成项目的初始化，整个的工作流是：

1. 下载一份存放于远端的 mpx 项目原始模板（mpx-template）

2. 根据用户的 prompts 选项完成用户选项的注入，并初始化最终的项目文件

完成项目的初始化后，除了一些基础配置文件外，整个项目的文件主要包含了如下的结构：

```javascript
-- mpx-project
 |-- src // 项目源码
 |-- config // 项目配置文件
   |-- index.js // 配置入口文件
   |-- mpxLoader.conf.js // mpx-loader 配置
   |-- mpxPlugin.conf.js // mpx webpack-plugin 配置
   |-- user.conf.js // 用户的 prompts 选择信息
 |-- build // 编译构建配置
   |-- build.js // 构建编译脚本
   |-- getPlugins.js // webpack plugins 
   |-- getRules.js // webpack module rules
   |-- getWebpackConf.js // webpack 配置生成辅助函数
   |-- utils.js // 工具函数
   |-- webpack.base.conf.js // webpack 基础配置
```

在初始化的项目当中，有关项目的所有配置文件，编译构建代码是全部暴露给开发者的，开发者可以对这些文件进行修改来满足自己实际的项目开发需要。同时还可以基于这一套原始的模板文件二次拓展为满足自己业务场景的模板。

**基于远程模板初始化项目的方式最大的一个好处就是将项目所有的底层配置完全暴露给开发者，开发者可以任意去修改对应的配置。**

## `mpxjs/cli@2.x` 自身的痛点 {#mpx-cli-2-x-pain-points}

目前 `@mpxjs/cli@2.x` 采用这种基于模板的方式面临着两方面的痛点：

1. 对于 `@mpxjs/cli` 的使用者而言：

* 模板和业务项目割裂：远程模板没有严格的版本控制，用户无法感知到远程模板的更新变化；

* 项目升级困难：对于用户来说没有一个很好的方式完成升级工作，基本只能通过 copy 代码的方式，将 `mpx-template` 更新后的内容复制一份到自己的项目当中；或者是通过脚手架重新创建一个新的项目，将老的代码迁移到新项目当中；

* 项目结构臃肿：从项目结构角度来说没法做到按需，初始化代码臃肿。Mpx 支持了小程序跨平台、跨端、小程序插件等等相关的开发，不同的编译构建配置都需要全部生成，在运行时阶段才能决定是否启动对应的功能；

* 跨 Web 构建能力弱：在基于 Mpx 的跨 Web 场景构建中有关 `web` 侧的编译构建的配置是比较初级的，像 `MPA 多页应用` 等比较常用的功能是需要用户重新去手动搭建一套的；

* 可拓展性差，基于目前的模板拉取的方式无法满足多样化的业务需求场景迭代；

2. 对于 `@mpxjs/cli` 的开发者而言：

* 分支场景多，功能模块耦合度高：脚手架的所有功能全部集合到一个大的模板当中。各部分的能力都是耦合在一起，为了满足不同项目的实际开发需要，代码里面需要写比较多的 `if...else...` 判断逻辑来决定要开启哪些功能，生成哪部分的模板；
* 长期可维护性差，开发心智负担重；

**针对以上问题，通过调研业内一些优秀的脚手架工具，发现 `@vue/cli` 插件化的架构设计能很好的去解决我们以上所遇到的问题。核心思路是将 `@vue/cli` 作为 `@mpxjs/cli` 底层的引擎，收敛 Mpx 对于核心依赖管理、模板、构建配置的能力，充分利用 `@vue/cli` 提供的插件机制去构建、拓展上层的插件集。**

### 有关 `@vue/cli` {#about-vue-cli}

简单介绍下 `@vue/cli` 的插件化架构：

`@vue/cli@3.x` 相较于 `2.x` 版本相比，整个 `@vue/cli` 的架构发生了非常大的变化，从基于模板的脚手架迭代为基于插件化的脚手架。简单的概述下整个插件化的构架就是：

![mpx-cli-3](https://dpubstatic.udache.com/static/dpubimg/zfUXzzdOptIviAJ15AgSn_cli-3.png)

* @vue/cli 提供 vue cli 命令，负责偏好设置，生成模板、`vue-cli-plugin` 插件依赖管理的工作，例如 `vue create <projectName>`、`vue add <pluginName>`；

* @vue/cli-service 作为 @vue/cli 整个插件系统当中的内部核心插件，提供了 npm script 注册服务，内置了部分 webpack 配置的同时，又提供了 `vue-cli-plugin` 插件的导入、加载以及 webpack 配置更新服务等。

以上是 `@vue/cli` 生态当中最为核心的两部分内容，二者分工明确，各司其职。

此外在 `@vue/cli` 生态当中非常重要的一个点就是 `vue-cli-plugin` 插件，每个插件主要完成模板生成及生产编译构建配置。根据 `@vue/cli` 设计的规范，开发一个 `vue-cli-plugin` 需要遵照**相关的约定**来进行开发：

* @vue/cli **约定**插件如果要生成模板，那么需要提供 `generator` 入口文件；

* @vue/cli-service **约定**插件的 `webpack` 配置更新需要放到插件的入口文件当中来完成，同时插件的命名也需要包含 `vue-cli-plugin` 前缀，因为 @vue/cli-service 是依据命名来加载相关的插件的；

## 插件化改造方案 {#plugin-transformation-plan}

一张图了解下插件化改造之后的 `@mpxjs/cli` 的架构设计：

![mpx-cli-2](https://dpubstatic.udache.com/static/dpubimg/hNaL_GUMzUVLOsyY5quGE_cli-2.png)

### 底层能力 {#underlying-capabilities}

将 `@vue/cli`、`@vue/cli-service` 分别作为 `@mpx/cli`和 `@mpx/cli-service` 的底层能力，即利用插件化的架构设计，同时还非常灵活的满足了 Mpx 做差异化场景迭代的定制化改造。上层的插件满足 `vue-cli-plugin` 插件开发的规范，最终底层的能力还是依托于 `@vue/cli` 和 `@vue/cli-service` 进行工作。

### 上层插件拆分 {#upper-plugin-splitting}

将原本大而全的模板进行插件化拆分，从 Mpx 所要解决的问题以及设计思路来考虑，站在跨平台的角度：

1. web 开发

* 基于 `wx` 的跨 `web` 开发；

2. 小程序开发

* 基于 `wx` 的跨平台(`ali`、`swan`，`tt`，`dd`)的小程序开发；
* 使用云函数的微信小程序开发；
* 微信小程序的插件模式的开发；

一个项目可能只需要某一种开发模式，例如仅仅是微信小程序的插件模式开发，也有可能是小程序和web平台混合开发等等，不同的开发模式对应了：

1. **不同的目录结构**；

2. **不同的编译构建配置**

***

基于这样一种现状以及 `@mpxjs/cli` 所要解决的问题，从跨平台的角度出发将功能进行了拆分，最终拆解为如下的9个插件：

* [vue-cli-plugin-mpx](https://github.com/mpx-ecology/mpx-cli/tree/master/packages/vue-cli-plugin-mpx)（mpx 基础开发插件）

* [vue-cli-plugin-mpx-mp](https://github.com/mpx-ecology/mpx-cli/tree/master/packages/vue-cli-plugin-mpx-mp)（mpx 小程序平台开发插件）

* [vue-cli-plugin-mpx-web](https://github.com/mpx-ecology/mpx-cli/tree/master/packages/vue-cli-plugin-mpx-web)（mpx 跨 web 平台开发插件）

* [vue-cli-plugin-mpx-cloud-func](https://github.com/mpx-ecology/mpx-cli/tree/master/packages/vue-cli-plugin-mpx-cloud-func)（微信小程序云函数开发插件）

* [vue-cli-plugin-mpx-plugin-mode](https://github.com/mpx-ecology/mpx-cli/tree/master/packages/vue-cli-plugin-mpx-plugin-mode)（微信小程序插件模式开发插件）

* [vue-cli-plugin-mpx-eslint](https://github.com/mpx-ecology/mpx-cli/tree/master/packages/vue-cli-plugin-mpx-eslint)（mpx eslint 插件）

* [vue-cli-plugin-mpx-unit-test](https://github.com/mpx-ecology/mpx-cli/tree/master/packages/vue-cli-plugin-mpx-unit-test)（小程序单元测试插件）

* [vue-cli-plugin-mpx-typescript](https://github.com/mpx-ecology/mpx-cli/tree/master/packages/vue-cli-plugin-mpx-typescript)（mpx typescript 插件）

这些拆解出来的插件都将和功能相关的**项目模板**以及**编译构建**配置进行了收敛。

项目模板的生成不用说，借助 `@vue/cli` 的 `Generator API` 按需去生成项目开发所需要的模板，例如项目需要使用 `eslint` 的功能，那么在生成项目的时候会生成对应 `vue-cli-plugin-mpx-eslint` 所提供的模板文件，如果不需要使用，项目当中最终也不会出现和 `eslint` 相关的文件配置。

重点说下编译构建的配置是如何进行拆解的：

**在 `@vue/cli@3.x` 基于插件的架构设计当中，决定是否要使用某个插件的依据就是判断这个插件是否被你的项目所安装**和基于模板的构架相比最大的区别就是：基于模板的架构在最终生成的模板配置里需要保存一些环境配置文件，以供编译构建的运行时来判断是否启用某些功能。但是基于插件的架构基本上是不再需要这些环境配置文件的，因为你如果要使用一个插件的功能，只需要安装它即可。

因此依照这样的设计规范，我们将：

* `eslint`

* `unit-test`

* `typescript`

这些非常独立的功能都单独抽离成了可拔插的插件，安装即启用。

以上功能有个特点就是和平台是完全解耦的，所以在拆解的过程中可以拆的比较彻底。但是由于 `mpx` 项目的特殊性，即要支持基于 `wx` 小程序的跨端以及 `web` 开发，同时还要支持小程序的云函数、小程序插件模式的开发，且不同开发模式的编译构建配置都有些差异。可以用如下的集合图来表示他们之间的关系：

![mpx-cli-4](https://dpubstatic.udache.com/static/dpubimg/3bgI4GSZ09ai4G1C3TDtr_cli-4.png)

不同插件进行组合使用来满足不同场景下的使用。

在不同平台开发模式下是有 `mpx` 编译构建的基础配置的，这个是和平台没有太多关系，因此将这部分的配置单独抽离为一个插件：`vue-cli-plugin-mpx`，**同时这个插件也被置为了 `@mpxjs/cli` 的 `preset` 预设插件，不管任何项目开发模式下，这个插件都会被默认的安装**。

```javascript
// vue-cli-plugin-mpx
module.exports = function (api, options, webpackConfig) {
  webpackConfig.module
    .rule('json')
    .test(/\.json$/)
    .resourceQuery(/asScript/)
    .type('javascript/auto')

  webpackConfig.module
    .rule('wxs-pre-loader')
    .test(/\.(wxs|qs|sjs|filter\.js)$/)
    .pre()
    .use('mpx-wxs-pre-loader')
    .loader(MpxWebpackPlugin.wxsPreLoader().loader)

  const transpileDepRegex = genTranspileDepRegex(options.transpileDependencies || [])
  webpackConfig.module
    .rule('js')
    .test(/\.js$/)
    .include
    .add(filepath => transpileDepRegex && transpileDepRegex.test(filepath))
    .add(filepath => /\.mpx\.js/.test(filepath)) // 处理 mpx 转 web 的情况，vue-loader 会将 script block fake 出一个 .mpx.js 路径，用以 loader 的匹配
    .add(api.resolve('src'))
    .add(api.resolve('node_modules/@mpxjs'))
    .add(api.resolve('test'))
    .end()
    .use('babel-loader')
    .loader('babel-loader')

  const transpileDepRegex = genTranspileDepRegex(options.transpileDependencies)
  webpackConfig.module
    .rule('js')
    .test(/\.js$/)
    .include
      .add(filepath => transpileDepRegex && transpileDepRegex.test(filepath))
      .add(api.resolve('src'))
      .add(api.resolve('node_modules/@mpxjs'))
      .add(api.resolve('test'))
        .end()
    .use('babel-loader')
      .loader('babel-loader')

  webpackConfig.resolve.extensions
    .add('.mpx')
    .add('.wxml')
    .add('.ts')
    .add('.js')

  webpackConfig.resolve.modules.add('node_modules')
}
```

在小程序的开发模式下，`vue-cli-plugin-mpx-mp` 会在 `vue-cli-plugin-mpx` 的基础上去拓展 `webpack` 配置以满足小程序的编译构建。

在跨 web 的开发模式下，`vue-cli-plugin-mpx-web` 会在 `vue-cli-plugin-mpx` 和 `@vue/cli` 的基础上去拓展配置以满足 web 侧的开发编译构建。

### Web 平台编译构建能力增强 {#web-platform-build-enhancement}

在 `@mpxjs/cli@2.x` 版本当中有关 `web` 侧的编译构建的配置是比较初级的，像 `热更新`、`MPA 多页应用` 等比较常用的功能是需要用户重新去手动搭建一套的。而 `@vue/cli@3.x` 即为 `vue` 项目而生，提供了非常完备的 `web` 应用的编译构建打包配置。

**所以 `@mpxjs/cli@next` 版本里面做了一项非常重要的工作就是复用 `@vue/cli` 的能力，弥补 `mpx` 项目在跨 `web` 项目编译构建的不足。**

因此关于 `mpx` 跨 `web` 编译构建的部分也单独抽离为一个插件：`vue-cli-plugin-mpx-web`，这个插件所做的工作就是在 `@vue/cli` 提供的 `web` 编译构建的能力上去适配 `mpx` 项目。这样也就完成了 `mpx` 跨 `web` 项目编译构建能力的增强。

**这也意味着 `@vue/cli` 所提供的能力基本上在 mpx 跨 web 项目当中都可使用。**

### 项目配置拓展能力 {#project-config-extension}

在 `@mpxjs/cli@2.x` 版本的项目如果要进行配置拓展，基本需要进行以下2个步骤：

1. 对 `config` 文件夹下的相关的配置文件进行修改；

2. 对 `build` 文件夹下的编译构建配置文件进行修改；

这也是在文章一开始的时候就提到的基于模板的大而全的文件组织方式。

而在 `@mpxjs/cli@next` 版本当中，将项目的配置拓展全部收敛至 `vue.config.js` 文件当中去完成，同时减少了开发者需要了解项目结构的心智负担。

```javascript
// vue.config.js

module.exports = {
  pluginOptions: {
    mpx: {
      plugin: {
        // mpx-plugin 相关的配置
      },
      loader: {
        // mpx-loader 相关的配置
      }
    }
  },
  configureWebpack() {},
  chainWebpack() {
    // 自定义的 webpack 配置
  }
}
```

### 改造后的目录结构 {#transformed-directory-structure}

在第一章节展示了目前 `@mpxjs/cli@2.x` 初始化项目的结构和现状。经过这次的插件化的改造后，项目的结构变得更为简洁，开发者只需要关注 `src` 源码目录以及 `vue.config.js` 配置文件即可：

```javascript
-- mpx-project
 |--src
 |--vue.config.js 
```

## 没有银弹 {#no-silver-bullet}

虽然基于 `@vue/cli` 插件的架构模式完成了 `@mpxjs/cli@3.x` 的插件化改造升级。但是由于 `mpx` 项目开发的一些特殊性，不同插件之间的协同工作是有一些约定的。

例如 `@vue/cli-service` 内置了一些 `webpack` 的配置，因为 `@vue/cli` 是专门针对 `web`应用的，这些配置会在所有的编译构建流程当中生效，不过这些配置当中有些对于小程序的开发来说是不需要的。

那么针对这种情况，为了避免不同模式下的 `webpack` 配置相互污染。`web` 侧的编译构建还是基于 `@vue/cli` 提供的能力去适配 `mpx` 的 `web` 开发。而小程序侧的编译构建配置是通过 `@vue/cli-service` 内部暴露出来的一些方法去跳过一些对于小程序开发来说不需要的 `webpack` 配置来最终满足小程序的构建配置。

因此在各插件的开发当中，需要暴露该插件所应用的平台：

```javascript
module.export.platform = 'mp'  // 可选值： 'web'
```

这样在实际的构建过程当中通过平台的标识来决定对应哪些插件会生效。

## 如何开发一个基于 mpx 的业务脚手架插件 {#how-to-develop-mpx-cli-plugin}

具体参阅[文档](https://github.com/mpx-ecology/mpx-cli/blob/master/PLUGIN_GUIDE.md)

---

---
url: /articles/unit-test.md
---

# Mpx 小程序单元测试能力建设与实践 {#unit-test-capability-construction}

> 作者：[Blackgan3](https://github.com/Blackgan3)

## 什么是单元测试 {#what-is-unit-test}

In computer programming, unit testing is a software testing method by which individual units of source code—sets of one or more computer program modules together with associated control data, usage procedures, and operating procedures—are tested to determine whether they are fit for use wikipedia

对一个函数，模块，类进行运行结果正确性检验的工作就是单元测试，此外每个单元测试的对象应该是一个最简单的组件/函数。

那写单测又能给我们哪些收益呢？

* 大幅提高项目代码可维护性
* 覆盖率到达一定指标后可大幅提高研发效率
* 让你的代码零线上bug锐减，上线不再提心吊胆
* 改进设计，促进重构

此外，单测高覆盖率的项目也会给公司节省大量支出：
![unit-test-money.png](https://cdn.nlark.com/yuque/0/2021/png/116604/1640872105786-b7b230b4-7f65-4a0f-8dbf-e8ba89f61837.png)
据微软统计单测效益结果，如上图展示，绝大多数bug都是在coding阶段产生，并且随着需求开发进度的推进，修复bug的成本会随指数级增长，当我们在unit test阶段发现并修复这个bug是能给公司带来巨大收益的。

下方介绍两种常见的项目单元测试规范：

* TDD (Test driven development)

> 测试驱动开发，在书写业务代码之前，先根据需求进行单元功能测试用例书写

这里驱动开发的不是简单的测试用例，是能够持续验证、重构并且对需求功能极致细化的测试用例

* BDD (Behavior driven development)

> 行为驱动开发，通过具有辨识力的测试用例驱动项目开发团队所有人，使用自然语言来描述功能，一般和 TDD 相结合，针对行为进行测试，让开发者在写单测时从专注代码实现转为业务行为，能使单测更加场景化和智能化

单元测试的书写初期必定伴随着大量精力与时间的消耗，但长期持续维护的业务在搭建并完善好整个单元测试体系后，可大大提高项目稳定性和研发效率

## 前端单元测试 {#frontend-unit-test}

### 前端单元测试工具 {#frontend-unit-test-tools}

前端单元测试目前有很多框架和工具，我们下方列出三个较为流行的框架和工具库进行介绍

* Mocha: 功能丰富的 javascript 测试框架(不包括断言和仿真环境，快照测试需额外配置)，可以运行在node.js和浏览器中
* Jasmine：Behavior-Drive development(BDD)风格的测试框架，在业内较为流行,功能很全面，自带asssert、mock功能
* Jest：一个功能全面的 javascript 测试框架，基于Jasmine 做了大量新特性(例如并行执行、源代码改动感知等)，开箱即用，适用于绝大多数 js 项目

### 测试断言库 {#assertion-library}

在单测运行框架中，我们需要断言库来进行方法返回和实例状态的正确性验证

* should: BDD风格断言                    (true).should.be.ok
* expect: expect()样式断言              expect(true).toBe(true)
* assert: Node.js 内置断言模块       assert(true === true)
* chai: expect()，assert()和should风格的断言都支持，全能型选手

在众多前端单元测试框架中，Jest 目前凭借零配置，高性能，且对于断言，快照，覆盖率等都有很好的集成，是目前较为流行的一个单测框架

### Jest 框架简介 {#jest-introduction}

简单来看下 Jest 框架的特点以及大致的运行原理

**Jest 的整体框架特点大概归纳总结为以下几点:**

* 在操作系统上高效的进行文件搜索以及相互依赖关系匹配
* 单测并行执行，运行效率高
* 内置断言库、覆盖率、快照测试等功能，开箱可用
* 使用 vm 来进行沙盒环境运行，单测之间相互隔离

![image.png](https://cdn.nlark.com/yuque/0/2021/png/116604/1639153318989-0e6ac9ed-75a3-4874-8a48-5370db55891d.png#averageHue=%23464a4d\&clientId=uf375a834-bd4b-4\&crop=0\&crop=0\&crop=1\&crop=1\&from=paste\&height=579\&id=u7fb4026f\&margin=%5Bobject%20Object%5D\&name=image.png\&originHeight=2014\&originWidth=777\&originalType=binary\&ratio=1\&rotation=0\&showTitle=false\&size=495531\&status=done\&style=none\&taskId=u6e39efb8-e12a-49b0-b8ce-ade9b63fd2c\&title=\&width=223.5)
打开 Jest pacakges，可以看到大概有50多个包，我们根据这些不同的包来将整个 jest 运行流程整体串起来

**第一步 jest-cli 读取相关配置**
当我们执行 jest 命令时，先去执行 jest-cli 中的 run 方法，再调用 jest-core 中的 runCli 方法，其中通过 jest-config 提供的 readConfigs 来读取 Jest 相关配置，返回全局配置(globalConfig)和局部配置(configs)

![unit-test-jest-step1.png](https://cdn.nlark.com/yuque/0/2021/png/116604/1640502186276-2a1c2976-58a5-4fd9-91db-c5df8265fc7f.png#clientId=u3d4e127e-cc05-4\&crop=0\&crop=0\&crop=1\&crop=1\&from=paste\&height=161\&id=uc6c948fd\&margin=%5Bobject%20Object%5D\&name=unit-test-jest-step1.png\&originHeight=177\&originWidth=808\&originalType=binary\&ratio=1\&rotation=0\&showTitle=false\&size=23884\&status=done\&style=none\&taskId=ub778d79f-2480-411f-97c3-d13aed04965\&title=\&width=735)

**第二步 文件静态分析**
使用 jest-haste-map 来进行项目中所有文件的检索以及生成文件之间的相互依赖关系，在 jest-core 中的 \_run10000 方法中执行 buildContextsAndHasteMaps，返回 contexts 和 hasteMapInstances，contexts 中的 hasteFs 存储的就是文件及依赖关系。

\*\*jest-haste-map \*\*检索的过程中借助 jest-worker 来根据当前cpu核数并行的进行文件检索，借助 fb-watch-man/crawler 对整体文件变动做实时监听，做到只执行有改动的单元测试文件，实现单测缓存效果。

![unit-test-jest-haste.png](https://cdn.nlark.com/yuque/0/2021/png/116604/1640524931986-a0ee9e99-151b-464e-96f3-c5d403a258f5.png#clientId=u059512e6-4582-4\&crop=0\&crop=0\&crop=1\&crop=1\&from=paste\&height=555\&id=u042b30bc\&margin=%5Bobject%20Object%5D\&name=unit-test-jest-haste.png\&originHeight=1109\&originWidth=2131\&originalType=binary\&ratio=1\&rotation=0\&showTitle=false\&size=188410\&status=done\&style=none\&taskId=u0c46aead-c2c6-4bd4-a90a-cf1e8cce042\&title=\&width=1065.5)
下方看一个简单的jest-haste-map使用示例

```javascript
import JestHasteMap from 'jest-haste-map';
import {cpus} from 'os';

const hasteMap = new JestHasteMap.default({
  extensions: ['js'],
  maxWorkers: cpus().length,
  name: 'test',
  platforms: []
});

const {hasteFS} = await hasteMap.build();
const testFiles = hasteFS.getAllFiles();

console.log(testFiles);
// ['/path/to/tests/list1.spec.js', '/path/to/tests/list2.spec.js', …]
```

**第三步 单测检索和排序**
经过第一步和第二步，我们拿到了 **配置对象 configs**，以及**文件Map HasteContext**，接下来通过 SearchSource 对象检索出所有的单元测试到一个数组中，检索出单元测试文件后，在正式执行之前，我们需要先对当前拿到的所有单测进行权重优先级排序。

单测排序的工作是由 jest Sequencer 完成的，默认排序优先级为 failed (上次失败的先运行)> duration(耗时长的先运行) > size(文件体积大的先运行)，当然这里我们也可以自定义customSequencer来覆盖 jest 默认的排序规则，jest 排序规则如下。

![unit-test-jest-scquencer.png](https://cdn.nlark.com/yuque/0/2021/png/116604/1640525025246-045963f5-1df6-411c-9257-74359f05e235.png#clientId=u059512e6-4582-4\&crop=0\&crop=0\&crop=1\&crop=1\&from=paste\&height=802\&id=u61d4057e\&margin=%5Bobject%20Object%5D\&name=unit-test-jest-scquencer.png\&originHeight=1603\&originWidth=2726\&originalType=binary\&ratio=1\&rotation=0\&showTitle=false\&size=292495\&status=done\&style=none\&taskId=udcf49166-d29d-4ba5-97b4-f942d8b9fe4\&title=\&width=1363)

```javascript
		return tests.sort((testA, testB) => {
      if (failedA !== failedB) {
        return failedA ? -1 : 1;
      } else if (hasTimeA != (testB.duration != null)) {
        // If only one of two tests has timing information, run it last
        return hasTimeA ? 1 : -1;
      } else if (testA.duration != null && testB.duration != null) {
        return testA.duration < testB.duration ? 1 : -1;
      } else {
        return fileSize(testA) < fileSize(testB) ? 1 : -1;
      }
    });
```

**第四步 开始执行**
在经过第三步之后，我们拿到了经过排序后的单测文件，接下来开始进入到执行步骤，执行单测时的整个调度工作是 jest/core 中的 TestScheduler 来完成，例如 scheduler 会推算是串行执行还是并行执行，推算单测执行完的大概时间，覆盖率报告的生成等，scheduler 会调用 jest-runner 中的 runTests 方法去触发单测执行

如果需要并行执行，runTest 方法触发 jest-worker 创建多个child process 子进程来支持 parallel 执行

单元测试中全局方法和全局变量，比如 test() describe() it() 等是由 jest-cirucs(jest-jasmine) 提供并注入global中

![unit-test-jest-run-test.png](https://cdn.nlark.com/yuque/0/2021/png/116604/1640527878045-b379169e-e180-4226-884d-2da6b90321ec.png#clientId=u059512e6-4582-4\&crop=0\&crop=0\&crop=1\&crop=1\&from=paste\&id=u4114c79f\&margin=%5Bobject%20Object%5D\&name=unit-test-jest-run-test.png\&originHeight=2878\&originWidth=3480\&originalType=binary\&ratio=1\&rotation=0\&showTitle=false\&size=683293\&status=done\&style=none\&taskId=ue36536e2-f975-4782-8f78-6d5203e2ae6\&title=)
最终单测的运行是由 jest-runtime 中创建的 vm 虚拟机隔离执行，vm 作用域中dom环境是由 jest-environment-jsdom 提供，此外 jest-runtime 中还包括了 transformer 能力以及mock功能的具体实现等，这部分功能在接下来的Mpx框架单元测试实现章节我们会去详细介绍它。

**第五步 处理返回结果**
此外 jest-runner中提供了一套类似于 redux 的数据流机制和eventEmitter来管理维护单测状态以及单测执行结果，在jest-runner 中进行事件触发，在TestScheduler 中进行事件监听并对执行结果进行各种处理和序列化，
最后在 jest-core 中的runJest方法中进行执行结果的终端输出/文件输出等一系列处理。

## 小程序单元测试 {#miniprogram-unit-test}

### 与 web 应用的不同 {#difference-from-web}

上个章节讲完前端单测简介，以及jest单测框架的大概运行原理后，接下来我们看下单元测试在小程序场景下与web场景的不同

首先小程序本身是双线程分离的机制，但目前并没有这种独特的运行环境用来执行单元测试，这里需要借助小程序官方提供的 miniprogram-simulate 工具集，来将整体运行机制调整为单线程模拟运行，并利用 dom 环境来进行小程序组件的注册渲染以及整个自定义组件树的搭建

小程序的单元测试执行依赖 js 运行环境和 dom 环境，这里我们选择 jest 框架来提供对应的环境

下方是一个简单的微信小程序官方提供的单元测试demo，具体关于miniprogram-simulate 的更多API的使用可以去官方文档查看 <https://github.com/wechat-miniprogram/miniprogram-simulate>

```javascript
import simulate from 'miniprogram-simulate'
test('comp', () => {
    const id = simulate.load(path.join(__dirname, './comp')) // 注册自定义组件，返回组件 id
    const comp = simulate.render(id) // 使用 id 渲染自定义组件，返回组件封装实例

    const parent = document.createElement('parent-wrapper') // 创建容器节点
    comp.attach(parent) // 将组件插入到容器节点中，会触发 attached 生命周期

    expect(comp.dom.innerHTML).toBe('<div>123</div>') // 判断组件渲染结果
    // 执行其他的一些测试逻辑

    comp.detach() // 将组件从容器节点中移除，会触发 detached 生命周期
})
```

此外对于小程序工具集的整体运行流程，在下方章节进行了简要总结。

### 小程序单测框架整体流程 {#miniprogram-test-framework-flow}

小程序单元测试中微信官方提供的相关库有 miniprogram-simulate、j-component 和 miniprogram-exparser等

* miniprogram-simulate: 小程序自定义组件测试工具集，进行小程序内置组件的注册以及模拟微信原生api的注入
* j-component: 仿小程序组件系统，可以让小程序自定义组件跑在 web 端。
* miniprogram-exparser：微信小程序官方的组件系统模块，exparser 的组件模型和 WebComponents标准中的 Shadow DOM 高度相似，基于 Shadow DOM 原型，可在纯 JS 环境运行，维护整个组件的节点树相关的信息，包括属性、事件等。
* miniprogram-compiler:  wcc、wcsc 官方编译器的 node 封装版，用于编译 wxml、wxss 文件

开发者在使用的时候经常用的的两个方法就是 simulate.load 和 simulate.render 方法，那这里我们就从这两个方法为入口进行整个流程的总结
**1.miniprogramSimulate.load(path)**
![小程序-load.png](https://cdn.nlark.com/yuque/0/2022/png/116604/1645371259515-600e82a3-5a16-4b50-90d2-4de16b3a6e13.png#clientId=u8f88ae50-6693-4\&crop=0\&crop=0\&crop=1\&crop=1\&from=paste\&height=2179\&id=u91907731\&margin=%5Bobject%20Object%5D\&name=%E5%B0%8F%E7%A8%8B%E5%BA%8F-load.png\&originHeight=2179\&originWidth=3100\&originalType=binary\&ratio=1\&rotation=0\&showTitle=false\&size=655139\&status=done\&style=none\&taskId=uffad3560-8564-4372-bf2f-ceded0ad196\&title=\&width=3100)

```javascript
let nowLoad
// miniprogram-simulate
function load(path, definition){
  // 省略部分判断
  const id = register(componentPath, tagName, cache, hasRegisterCache)
  cache.needRunJsList.forEach(item => {
    // nowLoad 用于执行用户代码调用 Component 构造器时注入额外的参数给 j-component
    nowLoad = item[1]
    // require('xxx.js')
    _.runJs(item[0])
  })
	return id
}
function register(componentPath, tagName, cache, hasRegisterCache) {
  // 随机生成，不重复
  const id = _.getId()
  const component = {
    id,
    path: componentPath,
    tagName,
    json: _.readJson(`${componentPath}.json`),
   	wxml: compile.getWxml(componentPath, cache.options),
    wxss: wxss.getContent(`${componentPath}.wxss`)
  }
  // 存入需要执行的自定义组件 js
  cache.needRunJsList.push([componentPath, component])
  return component.id
}
global.Component = options => {
	const component = nowLoad
  jComponent.register(definition)
}

function register(definition = {}) {
    const componentManager = new ComponentManager(definition)
    return componentManager.id
}

// ComponentManager 方法
class ComponentManager {
    constructor(definition) {
        // ......
        this.exparserDef = this.registerToExparser()
        _.cache(this.id, this)
    },
    registerToExparser() {
    ...
        const exparserDef = {
            is: this.id,
            using,
            generics: [], // TODO
            template: {
                func: this.generateFunc,
                data: this.data,
            },
            properties: definition.properties,
            data: definition.data,
            methods: definition.methods,
            ...
        }
        // miniprogram-exparser
        return exparser.registerElement(exparserDef)
    }
}

```

**2.miniprogramSimulate.render(id)**

![微信小程序-render.png](https://cdn.nlark.com/yuque/0/2022/png/116604/1645372791716-b3faf038-ff6f-4309-9a91-270bcfda4aa7.png#clientId=u8f88ae50-6693-4\&crop=0\&crop=0\&crop=1\&crop=1\&from=paste\&height=2069\&id=u272fdda2\&margin=%5Bobject%20Object%5D\&name=%E5%BE%AE%E4%BF%A1%E5%B0%8F%E7%A8%8B%E5%BA%8F-render.png\&originHeight=2069\&originWidth=3131\&originalType=binary\&ratio=1\&rotation=0\&showTitle=false\&size=668246\&status=done\&style=none\&taskId=u0ed961d2-5859-4c1b-ac1b-79595d39e8e\&title=\&width=3131)
miniprogram-simulate中render方法会调用j-component create，根据id从缓存对象中获取componentManager，进行组件实例创建

```javascript
  /**
   * 创建组件实例
   */
  create(id, properties) {
    const componentManager = _.cache(id)

    if (!componentManager) return

    return new RootComponent(componentManager, properties)
  },
```

RootComponent 构造函数中使用之前的 \_exparserDef 对象进行真实dom节点创建，生成 \_exparserNode

```javascript
class RootComponent extends Component{
	constructor(componentManager, properties) {
  	...
    this._exparserNode = exparser.createElement(tagName || id, exparserDef) // create exparser node and render
		...
    this._bindEvent() // touchstart，touchemove blur 等事件绑定
  }
}
```

新生成的 rootComponent 实例继承Component对象，定义了许多我们单测中需要用到的组件方法

```javascript
class Component {
	get dom() ...
  get data() ....
  get instance ...
  dispatchEvent ...
  addEventListener ...
  removeEventListener ...
  querySelector ...
  setData ...
  triggerLifeTime ...
  triggerPageLifeTime ...
  toJSON...
}
```

当然中间还有很多细节实现，比如模版渲染 j-component/template/compile，组件更新 j-component/render 等，感兴趣的话可以详细去看下里边具体的实现，这里我们暂且按下不表。至此，我们拿到了 component 实例，并可以进行正常的组件状态获取以及更新，然后在Jest框架中去断言组件的各种属性以及方法执行后的预期。

## Mpx 框架单元测试 {#mpx-framework-unit-test}

经过上方 Jest 框架讲解以及小程序单元测试流程分析后，接下来看下在Mpx框架中的单测能力支持实现

### 初期版本 {#initial-version}

Mpx框架的初期单测架构，是将Mpx框架开发的小程序项目，先构建编译为源码，再使用 miniprogram-simulate + j-component + jest 对构建后的小程序原生代码运行单元测试
![mpx-old-unit-test-architecture.png](https://cdn.nlark.com/yuque/0/2021/png/116604/1640786157277-5f92065d-c87e-46ed-b57e-4692b3d78a36.png#clientId=uc72cd25a-bebe-4\&crop=0\&crop=0\&crop=1\&crop=1\&from=paste\&height=485\&id=uf9a7caa5\&margin=%5Bobject%20Object%5D\&name=mpx-old-unit-test-architecture.png\&originHeight=969\&originWidth=3076\&originalType=binary\&ratio=1\&rotation=0\&showTitle=false\&size=744497\&status=done\&style=none\&taskId=uf25026f4-fd27-4116-bcb5-ffbe7357910\&title=\&width=1538)
该方案执行任何case都需要执行完整的构建流程，而且预构建已经完成了所有的模块收集，无法使用jest提供的模块mock功能，导致业务使用成本很高，落地困难。

### 优化版本 {#optimized-version}

经过调研，Jest 本身支持代码转换功能

> Jest在项目中以JavaScript的代码形式运行，但是如果使用一些Node.js不支持的，却可以开箱即用的语法(如JSX，TypeScript中的类型，Vue模板等)那你就需要将代码转换为纯JavaScript，转换的工作就是transformer

这里我们就可以通过Jest提供的转换能力编写mpx-jest转换器，实现在Jest模块加载过程中实时地将当前的Mpx组件编译转换为原生小程序组件，再交由miniprogram-simulate加载运行测试case。

该方案中模块加载完全基于Jest并能实现按需编译，完美规避旧方案中存在的缺陷，缺点在于编译构建流程基于Jest api重构，与Mpx自身基于Webpack的构建流程独立存在，带来额外维护成本，这一问题我们通过将通用的编译转换逻辑抽离出来统一维护，在Webpack和Jest两侧复用，从而解决了改问题。同时在实现这个方案的过程中也做了一部分对应库的改动，将会在下方介绍。

首先来看下 jest-runtime 中 transform 的整体流程。

* runTest 方法调用 runtime.requireModule(path)，传入对应的单测文件地址
* 判断是否是mock module，如果是则直接走 requireMock方法，否则继续往下进行
* 定义 localModule
* 调用 this.\_loadModule
* \_createRequireImplementation(module, options) 赋值给module.require
* transformFile 处理对应的文件
* createScriptFromCode(transformdCode)
* getVmContext  使用 vm 创建沙盒环境
* 在沙盒环境执行对应的 jest 单测代码

![jest-runtime1.png](https://cdn.nlark.com/yuque/0/2022/png/116604/1645251815753-ba8529bb-c63f-477f-bb2a-60182bf5f390.png#clientId=u3600a0a4-27fc-4\&crop=0\&crop=0\&crop=1\&crop=1\&from=paste\&height=811\&id=u9a266c8b\&margin=%5Bobject%20Object%5D\&name=jest-runtime1.png\&originHeight=3242\&originWidth=4075\&originalType=binary\&ratio=1\&rotation=0\&showTitle=false\&size=1246325\&status=done\&style=none\&taskId=uae1603dd-c05f-443b-977e-849426edf0d\&title=\&width=1019)
其中关键节点的代码如下

```javascript
			// 自定义 localModule
			const localModule = {
        children: [],
        exports: {},
        filename: modulePath,
        id: modulePath,
        loaded: false,
        path: path().dirname(modulePath)
      };
      // 自定义 module.require
			Object.defineProperty(module, 'require', {
        // rquireModuleOrMock || rquireInternalModule
      	value: this._createRequireImplementation(module, options)
    	});

			// transformCode
			const transformedCode = this.transformFile(filename, options);
			
			// createScriptFromCode
			const script = vm.script('({"' + EVAL_RESULT_VARIABLE + `":function(${args.join(',')}){` + transformedCode + '\n}});';)
			const vmContext = this._environment.getVmContext();
      runScript = script.runInContext(vmContext, {
        filename
      })
			compiledFunction = runScript[EVAL_RESULT_VARIABLE]
      compiledFunction.call(
        module.exports,
        module, // module object
        module.exports, // module exports
        module.require, // require implementation
        module.path, // __dirname
        module.filename, // __filename
        // @ts-expect-error
        ...lastArgs.filter(notEmpty),
      );
```

上方是整个 jest-runtime 中对于require module 时transform的整体流程。在Jest的这一能力之上，我们基于 @mpxjs/webpack-plugin 开发了 mpx-jest transformer，实现将 Mpx 单文件组件转换输出为对应的小程序原生代码。
![改良方案01.png](https://cdn.nlark.com/yuque/0/2022/png/116604/1645264785364-2db4095b-0344-4fa8-8d56-bfeb28c0f78d.png#clientId=uec723a90-39b3-4\&crop=0\&crop=0\&crop=1\&crop=1\&from=paste\&height=1588\&id=ubbef4532\&margin=%5Bobject%20Object%5D\&name=%E6%94%B9%E8%89%AF%E6%96%B9%E6%A1%8801.png\&originHeight=1588\&originWidth=3007\&originalType=binary\&ratio=1\&rotation=0\&showTitle=false\&size=368757\&status=done\&style=none\&taskId=u8c2c10f8-f83f-4765-b312-bb75081e05c\&title=\&width=3007)
在完成代码转换后，对应的 script 代码做为String存在于内存中，无法直接使用 Jest 环境的 require 加载执行，为此我们参考上述 jest-runtime 中的 loadModule方法实现了requireFromString方法，核心还是使用node vm 模块来进行 script 代码的执行，同时将jsdom-environment 和 Jest global 对象合并做为 vmContext

![改造方案2.png](https://cdn.nlark.com/yuque/0/2022/png/116604/1645269513406-df59853a-086d-4d5f-87a5-cb003d556ce9.png#clientId=uec723a90-39b3-4\&crop=0\&crop=0\&crop=1\&crop=1\&from=paste\&height=802\&id=u2da3911b\&margin=%5Bobject%20Object%5D\&name=%E6%94%B9%E9%80%A0%E6%96%B9%E6%A1%882.png\&originHeight=802\&originWidth=1970\&originalType=binary\&ratio=1\&rotation=0\&showTitle=false\&size=125179\&status=done\&style=none\&taskId=u182d9b94-f659-4d25-80d5-d9d01fdbaac\&title=\&width=1970)
至此，我们的整体单测方案就大致完成，通过 mpx-jest 转换组件，再交由 miniprogram-simulate 来渲染组件实例，从而完成对组件状态的断言，在实际测试的过程中，还遇到了以下问题进行解决。

1.Mpx框架的文件纬度的条件编译支持
Mpx框架的跨平台输出部分支持对文件进行平台和应用的条件编译引用

```javascript
// 文件列表
example.wx.mpx
example.ali.mpx

// 代码使用
{
	example: '../src/example'
}
```

这里我们需要在Jest运行时环境中提供该功能，借助Jest本身提供的 resolver 自定义能力，让我们可以对请求的文件进行自定义resolve功能，这里我们使用Mpx中现有的resolve plugin 和 enhanced-resolve来自定义resolve方法进行文件条件编译的支持。

```javascript
const { CachedInputFileSystem, ResolverFactory } = require('enhanced-resolve')
const AddModePlugin = require('@mpxjs/webpack-plugin/lib/resolver/AddModePlugin')

module.exports = (request, options) => {
  const addModePlugin = new AddModePlugin('before-file', 'wx', {
    include: () => true
  }, 'file')
  // create a resolver
  const myResolver = ResolverFactory.createResolver({
    ...
    plugins: [addModePlugin]
  })
  let result = myResolver.resolveSync({}, options.basedir, request)
	return result.split('?')[0]
}
```

2.miniprogram-simulate 定制化方法
在小程序单元测试的章节中，我们介绍了小程序相关库的运行机制，miniprogram-simulate提供的 load 方法默认只解析渲染原生组件，我们的Mpx组件，mpx-jest 转换器无法和miniprogram-simulate进行关联，所以这里我们选择fork miniprogram-simulate 仓库，自定义了loadMpx和registerMpx方法。

```javascript
// 使用
import simulate from '@mpxjs/miniprogram-simulate'
const id = simulate.loadMpx('src/components/list.mpx')

//@mpxjs/miniprogram-simulate 中 loadMpx 实现简单描述
function loadMpx(path, tagName, options = {}) {
	// ...省略一部分校验逻辑
  // .mpx 结尾文件会经过 mpx-jest 进行转换，输出 wxml,wxss,json,script
  const componentContent = require(componentPath)
  id = registerMpx(componentPath, tagName, cache, hasRegisterCache, componentContent)
  //....
  return id
}
function registerMpx(...){
  // 部分 require('xx/xx.json') 等修改为直接赋值
}

```

对于组件/页面在存在大量组件引用的情况下，mock引用组件可大大提升单测的运行速度，原有miniprogram-simulate框架并没有提供mock功能，所以这里我们也自定义了mockComponent和clearMockComponent方法。

```javascript
// 代码在 @mpxjs/miniprogram-simulate 中
let mockComponentMap = {}

function registerMpx() {
	// 判断是否是mock的组件
  if (mockComponentMap[tagName]) {
    componentPath = mockComponentMap[tagName]
  }
}
/**
 * mock usingComponents中的组件
 * @param compName
 * @param compDefinition
 */
function mockComponent(compName, compDefinition) {
  mockComponentMap[compName] = compDefinition
}
/**
 * 清除 component mock 数据
 */
function clearMockComponent() {
  mockComponentMap = {}
}

// 单测中使用时
simulate.mockComponent('list', {
  template: '<view>component list</view>'
})
```

3.封装定制test-utils工具集
书写单测的过程中我们会有很多重复工作，比如创建挂载组件、代理接口、模拟多个组件、断言多个数据等，这里我们将这些共性的方法抽离封装成了 test-utils

```javascript
/**
 * 创建渲染并挂载自定义组件
 * @param {组件基于所在项目的相对路径,例如'src/subpackage/gulfstream/components/bottom/bottom.mpx'} compPath
 * @returns 用于测试的自定义组件
 */
export function createCompAndAttach (compPath, renderProps = {}) {
  const id = simulate.loadMpx(compPath)
  let comp = simulate.render(id, renderProps)
  const parent = document.createElement('div')
  comp.attach(parent)
  return comp
}

/**
 * 借助xfetch构造mock请求
 * @param {待模拟url} mockUrl
 * @param {mock数据文件路径} mockFilePath
 */
export function proxyFetch (mockUrl, mockUrlData) {
  let mockData
  mpx.xfetch.fetch = jest.fn( (options) => {
    return new Promise((resolve) => {
      if (options.url.includes(mockUrl)) {
        if (typeof mockUrlData === 'string') {
          mockData = getMockContent(mockUrlData)
        } else {
          mockData = mockUrlData
        }
      }
      resolve({
        errno: 0,
        data: mockData
      })
    })
  })
}
......
```

至此，Mpx框架的单元测试方案整体上就完备了，整体上的方案架构如下图所示
![Mpx单测架构图.png](https://cdn.nlark.com/yuque/0/2022/png/116604/1645448762294-8e4cb0ab-bc09-4688-9360-ab4d67776af1.png#clientId=uc67aedb9-b0af-4\&crop=0\&crop=0\&crop=1\&crop=1\&from=paste\&height=1164\&id=u19264b9b\&margin=%5Bobject%20Object%5D\&name=Mpx%E5%8D%95%E6%B5%8B%E6%9E%B6%E6%9E%84%E5%9B%BE.png\&originHeight=2327\&originWidth=3335\&originalType=binary\&ratio=1\&rotation=0\&showTitle=false\&size=7199152\&status=done\&style=none\&taskId=uc2ecd51a-8419-46f1-a52a-1c9a8868ce1\&title=\&width=1667.5)

## Mpx组件单元测试实战 {#mpx-component-unit-test-practice}

在上方介绍过整体的jest框架流程以及Mpx框架单元测试架构后，接下来我们着手进行 Mpx 框架开发的小程序组件的单元测试用例书写实战

使用 @mpxjs/cli 创建模版项目时选择使用单元测试，**会自动生成有单测能力的模版项目**，和普通 Jest + miniprogram-simulate 搭建的原生小程序单测项目不同的是，transform 中添加了 Mpx 文件的处理，这里jest.config.js其他配置就不过多列出，可通过新创建项目进行查看。

```json
	transform: {
    '^.+\\.js$': '<rootDir>/node_modules/babel-jest',
    '^.+\\.mpx$': '<rootDir>/node_modules/@mpxjs/mpx-jest'
  }
```

首先我们列出一个组件示例，具体项目可点击链接查看:
<https://github.com/Blackgan3/mpx-unit-test-demo>

首先对于组件单测的书写，我们希望有一套固定的规范，即所写的不同组件的单测能有一个相同的格式和顺序，这里我们建议的顺序为

* 组件初始化断言
* 组件初始化各种形态断言
* 组件变化- data|computed|watch变化断言
* 组件变化- 事件触发断言
* 组件销毁断言

根据上方组件功能，首先我们建议对组件usingComponents 引入的组件进行模拟注册，这样可以节省组件渲染挂载的时间

```javascript
	beforeEach(() => {
    // 进行usingComponents 组件 mock
    testUtils.mockComponents([
      'list'
    ])
  })
```

1.我们首先需要对组件初始化成功后进行各种组件形态预期，即组件初始化断言

```javascript
	it('test component init correctly', function () {
    const comp = testUtils.createCompAndAttach(compPath)
    const insData = comp.instance.data
    testUtils.checkExpectedData(insData, {
      someClassShowOne: false,
      someClassShowTwo: false,
      someClassShowTwoFlag: false,
      listData2: ["手机", "电视", "电脑"],
      key: 1,
      compStatus: 1,
      timeDeferFlag: false
    })
    const domHTML = comp.dom.innerHTML
    // 进行组件初始化dom快照测试
    expect(domHTML).toMatchSnapshot()
  })
```

上方我们使用工具方法创建并挂载生成组件实例，然后对组件data中key值和value进行预期断言，最后对组件初始化生成的HTML进行快照测试

2.组件初始化各种形态断言
当组件的初始化数据源有多种形态，比如你的组件初始化数据是由接口或者其他重要的props传递过来决定的，那这里我们可以对不同的数据源组件的不同表现进行断言

```javascript
	it ('test comp different data', async function () {
    // 进行唯一数据源请求的接口代理
    proxyFetch('api/somePackage/getCompData', {
      status: 1
    })
    const comp = testUtils.createCompAndAttach(compPath)
    // 目前 status 为 1，再次改变数据源代理
    proxyFetch('api/somePackage/getCompData', {
      status: 2
    })
    await comp.instance.fetchCompData()
    await comp.instance.$nextTick()
    expect(comp.instance.data.compStatus).toBe(2)
    expect(comp.instance.data.compData).toEqual({status: 2})
    expect(comp.dom.innerHTML).toMatchSnapshot()
		// 再次改变数据源代理，修改源数据
    proxyFetch('api/somePackage/getCompData', {
      status: 3
    })
    await comp.instance.fetchCompData()
    await comp.instance.$nextTick()
    expect(comp.instance.data.compStatus).toBe(3)
    expect(comp.instance.data.compData).toEqual({status: 3})
    expect(comp.dom.innerHTML).toMatchSnapshot()
  })
```

3.组件变化- props|data|computed|watch变化断言
接下来我们需要对组件自身的 props|data|computed|watch 等属性变化时所触发的组件相应变化做出各种预期。

```javascript
	// 组件 props 改变后组件的各种形态预期
	it('test props different values correspond to different performance', function () {
    // 传入初始渲染 props
    const successContent = 'some successContent'
    const comp = testUtils.createCompAndAttach(compPath, {
      successContent
    })
    const childComp = comp.querySelector('.successContent')
    expect(childComp).toBeDefined()
    expect(comp.instance.data.successContent).toBe(successContent)
    // 对最终的HTML进行快照测试
    expect(childComp.dom.innerHTML).toMatchSnapshot()
  })
	// 当组件data中的someClassShowOne改变之后需要做的哪些预期
	// 当组件computed中的someCompShow改变之后需要做的预期
	// ......
	
```

4.组件必不可少的会有方法，这里我们对示例组件的方法调用进行预期

```javascript
	it ('test someClassShowTwoFlag tap event trigger', async function () {
    const comp = testUtils.createComp(compPath)
    const fetchCompDataSpy = jest.spyOn(comp.instance, 'fetchCompData')
    const changeSomeClassShowTwoFlagSpy = jest.spyOn(comp.instance, 'changeSomeClassShowTwoFlag')
    proxyFetch('api/somePackage/getCompData', {
      status: 1
    })
    comp.attach(document.body)
    const compData = comp.instance.data
    const changeFlagViewComp = comp.querySelector('.changeFlagClass')

    // dispatchEvent 为异步
    changeFlagViewComp.dispatchEvent('tap')
    await testUtils.sleep(0)

    expect(changeSomeClassShowTwoFlagSpy).toBeCalledWith(true)
    expect(fetchCompDataSpy).toHaveBeenCalledTimes(2)
    expect(compData.someClassShowTwo).toBeTruthy()
    expect(comp.instance.someClassShowTwoFlag).toBeTruthy() // 此处注意 非template中使用过到的data，获取更新后的值，从instance中获取
    expect(comp.dom.innerHTML).toMatchSnapshot()
  })	

	it('test someTimeDeferAction tap event trigger', async function () {
    jest.useFakeTimers()
    jest.spyOn(global, 'setTimeout')

    const comp = testUtils.createCompAndAttach(compPath)
    const compData = comp.instance.data
    const someTimeDeferActionSpy = jest.spyOn(comp.instance, 'someTimeDeferAction')
    const childComp = comp.querySelector('.someTimeDeferActionClass')
    childComp.dispatchEvent('tap')

    // comp.instance.someTimeDeferAction()
    await Promise.resolve()

    jest.runAllTimers()
    await comp.instance.$nextTick()

    expect(compData.timeDeferFlag).toBeTruthy()
    expect(someTimeDeferActionSpy).toHaveBeenCalledTimes(1)
    expect(comp.dom.innerHTML).toMatchSnapshot()
    jest.useRealTimers()
  })
```

以上，我们对当前的示例组件完成了整体内容的单元测试书写，完整版单测文件可点击链接查看
<https://github.com/Blackgan3/mpx-unit-test-demo/blob/master/test/components/example.spec.js>

## 结语 {#conclusion}

通篇文章我们依次进行了前端常用单测框架简介，jest框架原理总结，小程序单元测试内部执行流程，最后介绍Mpx框架中单测能力的支持实现以及Mpx组件单测实战。

学习到了jest不仅仅是一个单元测试框架，你甚至可以使用它的各个工具库自己创建一个单元测试框架；以及感受到小程序场景下单元测试的差异化；Mpx框架层面也做了诸多改造来支撑单测功能的落地。

后续我们还会继续跟进推动业务中落地TDD规范，复杂逻辑组件中各种功能场景单测用例规范的补充等问题，持续在小程序单测方向深耕并有更好的规范总结产出。

参考文章：

* [https://jestjs.io](https://jestjs.io/)
* <https://jestjs.io/docs/architecture>
* <https://medium.com/code-for-cause/jest-architecture-9870bbfcda44>

---

---
url: /articles/2.9-release-alter.md
---
# Mpx2.9 版本正式发布，支持原子类、SSR 和包体积优化 {#mpx-2-9-release}

> 作者：[董宏平](https://github.com/hiyuki)

[Mpx](https://github.com/didi/mpx) 是滴滴开源的一款增强型跨端小程序框架，自2018年立项开源以来如今已经进入第六个年头，在这六年间，Mpx 根植于业务，与业务共同成长，针对小程序业务开发中遇到的各类痛点问题提出了解决方案，并在集团内部建设了完善的小程序跨端开发生态。目前，Mpx 已经覆盖支持了集团内部全量小程序业务开发，成为了集团小程序开发的统一技术标准，并在今年年初被评选为集团内首个开源精品项目。

随着小程序业务的发展演进，性能和包体积的重要性愈发凸显，Mpx从设计之初就非常重视性能和包体积的优化，本次的 **Mpx2.9** 版本更新带来的三大核心特性——原子类、SSR 和包体积优化也都与性能和包体积息息相关，下面我们逐个展开介绍。

## 原子类支持 {#atomic-class-support}

原子类(utility-first CSS)是近几年流行起来的一种全新的样式开发方式，在前端社区内取得了良好的口碑，越来越多的主流网站也基于原子类进行开发，比较知名的有 [Github](https://github.com/)，[OpenAI](https://openai.com/)，[Netflix](https://top10.netflix.com/) 和 [NASA官网](https://www.jpl.nasa.gov/) 等。使用原子类离不开原子类框架的支持，常用的原子类框架有 [Tailwindcss](https://tailwindcss.com/)、[Windicss](https://windicss.org/) 和 [Unocss](https://unocss.dev/) 等。

在 Mpx2.9 版本中，我们在框架中内置了基于 `unocss` 的原子类支持，让小程序开发也能使用原子类。对项目进行简单配置开启原子类支持后，用户就可以在 Mpx 页面/组件模板中直接使用一些预定义的基础样式类，诸如 flex，pt-4，text-center 和 rotate-90 等，对样式进行组合定义，并且在 Mpx 支持的所有小程序平台和 web 平台中正常运行，下面是一个简单示例：

```html
<view class="container">
  <view class="flex">
    <view class="py-8 px-8 inline-flex mx-auto bg-white rounded-xl shadow-md">
      <view class="text-center">
        <view class="text-base text-black font-semibold mb-2">
          Erin Lindford
        </view>
        <view class="text-gray-500 font-medium pb-3">
          Product Engineer
        </view>
        <view
          class="mt-2 px-4 py-1 text-sm text-purple-600 font-semibold rounded-full border border-solid border-purple-200">
          Message
        </view>
      </view>
    </view>
  </view>
</view>
```

通过这种方式，我们在不编写任何自定义样式代码的情况下得到了一张简单的个人卡片，实际渲染效果如下：

![utility-css-demo](https://dpubstatic.udache.com/static/dpubimg/Or3aaN-mmxV8pK-LmEVPm_demo.png)

相较于传统的自定义类编写样式的方式，使用原子类能给你带来以下这些好处：

* **不用再烦恼于为自定义类取类名**，传统样式开发中，我们仅仅是为某个元素定义样式就需要绞尽脑汁发明一些抽象的类名，还得提防类名冲突，使用原子类可以完全将你从这种琐碎无趣的工作中解放；
* **停止 css 体积的无序增长**，传统样式开发中，css 体积会随着你的迭代不断增长，而在原子类中，一切样式都可以复用，你几乎不需要编写新的 css；
* **让调整样式变得更加安全**，传统 css 是全局的，当你修改某个样式时无法保障其不会破坏其他地方的样式，而你在模板中使用的原子类是本地的，你完全不用担心修改它会影响其他地方。

而相较于使用内联样式，原子类也有一些重要的优势：

* **约束下的设计**，使用内联样式时，里面的每一个数值都是魔法数字（magic number）
  ，而通过原子工具类，你可以选择一些符合预定义设计规范的样式，便于构筑具有视觉一致性的UI；
* **响应式设计**，你无法在内联样式中使用媒体查询，然而通过原子类框架中提供的响应式工具，你可以轻而易举地构建出响应式界面；
* **Hover、focus 和其他状态**，使用内联样式无法定义特定状态下的样式，如 hover 和 focus，通过原子类框架的状态变量能力，我们可以轻松为这些状态定义样式。

看到这里相信你已经迫不及待地想要在 Mpx 中体验原子类开发了吧，使用最新版本的 `@mpxjs/cli` 脚手架创建项目时，在 prompt 中选择使用原子类，就可以在新创建的项目模版中直接使用 `unocss` 的原子类，可使用的工具类可以参考 [unocss 交互示例](https://unocss.dev/interactive/)，在已有项目中开启原子类支持可以参考[配置指南](../guide/advance/utility-first-css.md#compile-config)

### 小程序原子类使用注意事项 {#atomic-class-notes}

小程序和 web 环境对于 css 的支持存在底层差异，小程序内也存在大量自身独有的技术特性，Mpx 在支持原子类时针对这些环境特异性进行了抹平和适配，在框架的支持下，我们实现了大部分（超过90%）原子类功能和工具类在小程序环境下正常使用，并额外支持了原子类产物的分包输出和样式隔离下的原子类使用，详情如下：

#### 特殊字符转义 {#special-char-escape}

基于 `unocss` 的原子类支持 `value auto-infer`（值自动推导），可以在模版中根据相关规则书写灵活的自定义值原子类，如 `p-5px bg-[hsl(211.7,81.9%,69.6%)]` 等，针对原子类中出现的 `[` `(` `,` 等特殊字符，在 web 中会通过转义字符 `\` 进行转义，由于小程序环境下不支持 css 选择器中出现 `\` 转义字符，我们内置支持了一套不带 `\` 的转义规则对这些特殊字符进行转义，同时替换模版和 css 文件中的类名，内建的默认转义规则如下：

```js
const escapeMap = {
    '(': '_pl_',
    ')': '_pr_',
    '[': '_bl_',
    ']': '_br_',
    '{': '_cl_',
    '}': '_cr_',
    '#': '_h_',
    '!': '_i_',
    '/': '_s_',
    '.': '_d_',
    ':': '_c_',
    ',': '_2c_',
    '%': '_p_',
    '\'': '_q_',
    '"': '_dq_',
    '+': '_a_',
    $: '_si_',
    // unknown用于兜底不在上述范围中未知的转义字符
    unknown: '_u_'
  }
```

与此同时，用户也可以通过传递 `@mpxjs/unocss-plugin` 的 [escapeMap](../api/compile.md#escapemap) 配置项来覆盖内建的转义规则。

#### 原子类分包输出 {#atomic-class-subpackage}

在 web 中，原子类会被全部打包输出单个样式文件，一般会放置在顶层样式表中以供全局访问，但在小程序中这种全量的输出策略并不是最优的，主要原因在于小程序中可供全局访问的主包体积存在 **2M 大小限制**，主包体积十分紧缺珍贵，Mpx 在构建输出时遵循着分包优先的原则，尽可能充分利用分包体积从而减少对主包体积的占用，再进行原子类产物输出时，我们也遵循了相同的原则。

在Mpx中，我们在收集原子类时同时记录了每个原子类的引用分包，在收集结束后根据每个原子类的分包引用数量决定该原子类应该输出到主包还是分包当中，我们在 `@mpxjs/unocss-plugin` 中提供了 [minCount](../api/compile.md#mincount) 配置项来决定分包的输出规则，该配置项的默认值为2，即当一个原子类被2个或以上分包引用时，会被作为公共原子类抽取到主包中，否则输出到所属分包中，这也是全局最优的策略。当我们想要让原子类输出产物更少地占用主包体积时，我们也可以将`minCount`值调大，让原子类抽取到主包的条件更加苛刻，不过这样也会伴随着原子类分包冗余的增加。

`unocss.config.js` 配置中定义的 `safelist` 原子类默认会输出到主包，为了组件局部使用的 `safelist` 有输出到分包的机会，我们在模版中提供了[注释配置](../api/compile.md#commentconfig)（comments config），灵感来源于 `webpack` 中的魔法注释（magic comments），用户可以在组件模版中通过`注释配置`声明当前组件所需的 `safelist`，对应的原子类也会根据上述的规则输出到主包或分包中，使用示例如下：

```html
<template>
    <!-- mpx_config_safelist: 'text-red-500 bg-blue-500' -->
    <!-- 动态样式中可以使用text-red-500和bg-blue-500原子类 -->
    <view wx:class="{{classObj}}">test</view>
    <!-- ... -->
</template>
```

#### 样式隔离与组件分包异步 {#style-isolation-and-async}

在小程序中，自定义组件的样式默认是隔离的，web 中通过全局样式访问原子类的方式不再生效，不过由于小程序提供了[样式隔离配置](https://developers.weixin.qq.com/miniprogram/dev/framework/custom-component/wxml-wxss.html#%E7%BB%84%E4%BB%B6%E6%A0%B7%E5%BC%8F%E9%9A%94%E7%A6%BB)，我们可以将该组件样式隔离配置调整为 `apply-shared` 来获取页面或 app 中定义的原子类，但是当我们在使用传统类名和原子类混合开发或者迁移原子类的过程中，我们往往希望保留原本自定义组件的样式隔离。

针对这种情况，我们在 `@mpxjs/unocss-plugin` 中提供了 [styleIsolation](../api/compile.md#styleisolation) 配置项，可选设置为 `isolated`|`apply-shared`，当设置为 `isolated` 时每个组件都会通过 `@import` 独立引用主包或者分包的原子类样式文件，因此不会受到样式隔离的影响；当设置为 `apply-shared` 时，只有 app 和分包页面会引用对应的原子类样式文件，自定义组件需要通过配置样式隔离为 `apply-shared` 使原子类生效。

在组件分包异步的情况下对应组件即使将样式隔离配置为 `apply-shared` 的情况下，`@mpxjs/unocss-plugin` 也需要将  `styleIsolation` 设置为 `isolated` 才能正常工作，原因在于组件分包异步的情况下，组件被其他分包的页面所引用渲染，由于上述原子类样式分包输出的规则，其他分包的页面中可能并不包含当前组件所需的原子类，只有在 `isolated` 模式下由组件自身引用所需的原子类样式才能保证正常工作，类似于 `safelist`，我们也提供了[注释配置](../api/compile.md#commentconfig)的方式对组件的 `styleIsolation` 模式进行局部配置，示例如下：

```html
<template>
    <!-- mpx_config_styleIsolation: 'isolated' -->
    <!-- 当前组件会直接引用对应主包或分包的原子类样式 -->
     <view class="@dark:(text-white bg-dark-500)">
    <!-- ... -->
</template>
```

### 原子类使用参考文档 {#atomic-class-docs}

Mpx 中使用原子类的详细参考文档如下：

* [原子类使用指南](../guide/advance/utility-first-css.md)
* [原子类 API 参考](../api/compile.md#mpxunocssplugin)

## 输出 web 支持 SSR {#web-ssr-support}

近些年来，SSR/SSG 由于其良好的首屏展现速度和SEO友好性逐渐成为主流的技术规范，各类SSR框架层出不穷，未来进一步提升性能表现，在 SSR 的基础上还演进出 [islands architecture](https://docs.astro.build/en/concepts/islands/) 和 [0 hydration](https://qwik.builder.io/docs/concepts/resumable/) 等更加精细复杂的理念和架构。

近两年随着团队对于前端性能的重视，SSR/SSG 技术也在团队业务中逐步推广落地，并在首屏性能方面取得了显著的收效。但由于过去 Mpx 对 SSR 的支持不完善，使用 Mpx 开发的跨端页面一直无法享受到 SSR 带来的性能提升，在 Mpx2.9 版本中，我们对 web 输出流程进行了大量适配改造，解决了 SSR 中常见的内存泄漏、跨请求状态污染和数据预请求等问题，完整实现了基于 Vue 和 Pinia 的 SSR 技术方案。

### 配置使用 SSR {#ssr-config}

在 Vue SSR 项目中，我们一般需要提供 server entry 和 client entry 两个文件作为 webpack 的构建入口，然后通过 webpack 构建出 server bundle 和 client bundle。在用户访问页面时，在服务端使用 server bundle 渲染出 HTML 字符串，作为静态页面发送到客户端，然后在客户端使用 client bundle 通过水合（hydration）对静态页面进行激活，实现可交互效果，下图展示了 Vue SSR 的大致流程。

![Vue SSR流程](https://img-hxy021.didistatic.com/static/webappstatic/do1_kWBH7L8mTgpHeKsBKp85)

Mpx SSR 核心基于 Vue SSR 实现，大致流程思路与 Vue 一致，不过为了保持与小程序代码的兼容性，在配置使用上有一些改动差异，下面我们详细展开介绍：

#### 构建server/client bundle {#build-server-client-bundle}

SSR项目中，我们需要分别构建出 server bundle 和 client bundle，对于不同环境的产物构建，我们需要进行不同的配置。
在 Vue 中，我们需要提供 `entry-server.js` 和 `entry-client.js` 两个文件分别作为 server 和 client 的构建入口，与 Vue 不同，在 Mpx 中我们通过编译处理与运行时增强生命周期实现了使用 `app.mpx` 作为统一构建入口，无需区分 server 和 client。

##### 服务端构建配置 {#server-build-config}

服务端配置中除了将 entry 制定为 `app.mpx` 及其它基础配置外，最重要的是安装 `vue-server-renderer` 包中提供的  `server-plugin` 插件，该插件能够构建产出 `vue-ssr-server-bundle.json` 文件供 `renderer` 后续消费。

```js
// webpack.server.config.js
const VueSSRServerPlugin = require('vue-server-renderer/server-plugin')

module.exports = merge(baseConfig, {
  // 将 entry 指向项目的 app.mpx 文件
  entry: './app.mpx',
  // ...
  plugins: [
   // 产出 `vue-ssr-server-bundle.json`
    new VueSSRServerPlugin()
  ]
})
```

更加详细的配置说明可参考 [Vue SSR的服务端配置](https://v2.ssr.vuejs.org/guide/build-config.html#server-config)

##### 客户端构建配置 {#client-build-config}

类似服务端构建配置，在客户端构建中我们需要使用 `vue-server-renderer` 包中 `client-plugin` 插件来帮助我们生成客户端环境的资源清单 `vue-ssr-client-manifest.json`，并供 `renderer` 后续消费。

```js
// webpack.client.config.js
const VueSSRClientPlugin = require('vue-server-renderer/client-plugin')

module.exports = merge(baseConfig, {
  // 将 entry 指向项目的 app.mpx 文件
  entry: './app.mpx',
  // ...
  plugins: [
    // 产出 `vue-ssr-client-manifest.json`。
    new VueSSRClientPlugin()
  ]
})
```

更加详细的配置说明可参考 [Vue SSR的客户端配置](https://v2.ssr.vuejs.org/guide/build-config.html#client-config)

#### 准备页面模版 {#prepare-page-template}

SSR 渲染中，我们创建 `renderer` 需要一个页面模板，简单的示例如下：

```html
<!DOCTYPE html>
<html lang="en">
  <head><title>Hello</title></head>
  <body>
    <!--vue-ssr-outlet-->
  </body>
</html>
```

与 CSR 渲染模版不同，SSR 渲染模版中需要提供一个特殊的 `<!--vue-ssr-outlet-->`注释，标记 SSR 渲染产物的插入位置，如使用 `@mpxjs/cli` 脚手架创建 SSR 项目，该模版已经内置于脚手架中。

#### 集成启动 SSR 服务 {#ssr-service-integration}

当我们准备好页面模版和双端构建产物后，我们就可以创建 `renderer` 并与 Node 服务进行集成，启动 SSR 服务，下面以 `express` 为例：

```js
//server.js
const app = require('express')()
const { createBundleRenderer } = require('vue-server-renderer')
// 通过 vue-server-renderer/server-plugin 生成的文件
const serverBundle = require('../dist/server/vue-ssr-server-bundle.json')
// 通过 vue-server-renderer/client-plugin 生成的文件
const clientManifest = require('../dist/client/vue-ssr-client-manifest.json')
 // 页面模版文件
const template = require('fs').readFileSync('../src/index.template.html', 'utf-8')
// 创建 renderer 渲染器
const renderer = createBundleRenderer(serverBundle, {
    runInNewContext: false,
    template,
    clientManifest,
});
// 注册启动 SSR 服务
app.get('*', (req, res) => {
  const context = { url: req.url }
  renderer.renderToString(context, (err, html) => {
  	if (err) {
  	  res.status(500).end('Internal Server Error')
      return
    }
  	res.end(html);
  })
})
app.listen(8080)
```

### SSR 生命周期 {#ssr-lifecycle}

在 Mpx 2.9 的版本中，我们提供了三个全新用于 SSR 的生命周期，分别是`onAppInit`、`serverPrefetch` 和 `onSSRAppCreated`，以统一服务端与客户端的构建入口，下面展开介绍：

#### onAppInit

在 SSR 中用户每发出一个请求，我们都会为其生成一个新的应用实例，`onAppInit` 生命周期会在应用创建 `new Vue(...)` 前被调用，其执行的返回结果会被合并到创建应用的 `options` 中

很常见的使用场景在于返回新的全局状态管理实例，Mpx 中提供了 `@mpxjs/pinia` 作为全局状态管理工具，我们可以在 `onAppInit` 中返回全新的 `pinia` 示例避免产生跨请求状态污染，示例如下：

```js
// app.mpx
import mpx, { createApp } from '@mpxjs/core'
import { createPinia } from '@mpxjs/pinia'

createApp({
  // ...
  onAppInit () {
    const pinia = createPinia()
    return {
      pinia
    }
  }
})
```

#### serverPrefetch

当我们需要在 SSR 使用数据预拉取时，可以使用这个生命周期进行，使用方法与 Vue 一致, 示例如下：

选项式 API：

```js
import { createPage } from '@mpxjs/core'
import useStore from '../store/index'

createPage({
  //...
  serverPrefetch () {
    const query = this.$route.query
    const store = useStore(this.$pinia)
    // return the promise from the action, fetch data and update state
    return store.fetchData(query)
  }
})
```

组合式 API：

```js
import { onServerPrefetch, getCurrentInstance, createPage } from '@mpxjs/core'
import useStore from '../store/index'

createPage({
  setup () {
    const store = userStore()
    onServerPrefetch(() => {
      const query = getCurrentInstance().proxy.$route.query
      // return the promise from the action, fetch data and update state
      return store.fetchData(query)
    })
  }
})
```

关于数据预拉取更详细的说明可以查看[这里](https://v2.ssr.vuejs.org/guide/data.html)。

#### onSSRAppCreated

在 Vue SSR 项目中，我们会在 `entry-server.js` 中导出一个工厂函数，在该函数中实现创建应用实例、路由匹配和状态同步等逻辑，并返回应用实例 `app`。

在 Mpx SSR 中，我们将这部分逻辑整合在 `onSSRAppCreated` 中执行，该生命周期执行时用户可以从参数中获取应用实例 `app`、路由实例 `router`、数据管理实例 `pinia` 和 SSR 上下文 `context`，在完成必要的操作后，该生命周期需要返回一个 `resolve(app)` 的 promise。

通常我们会在 `onSSRAppCreated` 中进行路由路径设置和数据预拉取后的状态同步工作，示例如下：

```js
// app.mpx
createApp({
    // ...,
    onSSRAppCreated ({ pinia, router, app, context }) {
      return new Promise((resolve, reject) => {
        // 设置服务端路由路径
        router.push(context.url)
        router.onReady(() => {
          // 应用完成渲染时执行
          context.rendered = () => {
            // 将服务端渲染后得到的 pinia.state 同步到 context.state 中，
            // context.state 会被自动序列化并通过 `window.__INITIAL_STATE__`
            // 注入到 HTML 中，并在客户端运行时再读取同步
            context.state = pinia.state.value
          }
          // 返回应用程序实例
          resolve(app)
        }, reject)
      })
    }
})
```

如用户没有配置 onSSRAppCreated，框架内部会执行兜底逻辑，以保障 SSR 的正常运行。

### 其他注意事项 {#ssr-other-notes}

1. Mpx SSR 渲染支持 i18n 的功能，但为了防止内存泄漏，当前 i18n 实例不会随着每次请求而重新创建，这是由于 Vue2.x 版本插件机制的设计缺陷所造成的，因此在使用 i18n 进行 SSR 时可能会产生跨请求状态污染的问题，这个问题会在未来 Mpx 输出 web 切换为 Vue3 后完全解决。

2. 在服务端渲染阶段，对于 global 全局对象访问修改，如\_\_mpx, \_\_mpxRouter, \_\_mpxPinia 都可能导致全局状态污染，所以在服务端渲染阶段请尽量避免进行相关操作；对于存在全局访问修改的方法，如 getApp(), getCurrentPages() 等在服务端渲染中被调用时，会产生相关报错提示。

3. 由于服务器无法收到 URL 中的 hash 信息，使用 SSR 时需要通过修改 `mpx.config.webRouteConfig` 将路由模式设置成 `history` 模式。

## 包体积优化 {#bundle-size-optimization}

近几年来随着集团超级 App 战略的推进，滴滴出行主小程序中集成了越来越多的业务线，主小程序的包体积也随之呈现爆炸式增长，到今天主小程序里已经集成了集团内大部分核心业务，但其总包体积也从 21 年的 12MB 增长至触达微信上限 30MB，成为一个页面数量400+，组件数量3600+，JS模块数40000+的“大程序”。在此期间，我们通过统一技术框架、分包异步改造和低效页面下线/改造等技术手段，对主小包体积进行一轮又一轮优化，并沉淀了分包异步构建、包体积分析管控和冗余包检测等一系列技术能力，累计优化总包体积超过 **8MB**。

Mpx 在设计之初就考虑了包体积问题，完整继承了 webpack 已有的代码优化能力，如公共模块抽离、tree shaking、混淆压缩等。除此之外，我们还设计开发了业内最完善的分包构建流程，完整支持基于配置声明和依赖分析的普通分包、独立分包及分包异步化的构建输出，极大地缓解了复杂小程序中的主包和总包体积过大的问题。在 Mpx2.9 版本中，我们针对复杂小程序页面组件和 JS 模块众多的特点，对构建产物进行了针对性地优化，进一步降低了构建产物体积，当前版本在主小程序中实测能够在不做任何业务改造的情况下节省了约 **2MB** 总包体积，收效显著，主要优化项如下：

### 模版代码优化 {#template-code-optimization}

Mpx 基于 webpack 进行打包构建，并基于小程序原生 commonjs 支持进行适配改造，以实现 webpack 构建产物在小程序环境下运行，为了将构建产物中的模块和 chunk 链接到一起，webpack 和 mpx 会在构建产物生成一些模版代码进行相关工作，下面是一个页面 js 中包含的模版代码示例：

```js
var self = {}
self.webpackChunkmpx_test_2_8 = require('../bundle.js')
(self.webpackChunkmpx_test_2_8 = self.webpackChunkmpx_test_2_8 || []).push([[405], {
  1307: function (t, e, o) {
    // ...
  },
  4236: function (t) {
    // ...
  },
  // ...
}, function (t) {
  var e
  e = 1307, t(t.s = e)
}])
```

可以看出模版代码主要由 chunk 链接代码，chunk id，模块 id 和模块包装函数组成，对于中小项目来说，这些模版代码一般不会占用太多体积，但是在滴滴出行主小程序这样的大体量项目下，这部分体积就变得不可忽视，`@mpxjs/size-report` 的分析结果显示，生产模式下主小程序中模版代码占用体积约为 1.2MB，相当于一个中等复杂度业务的占用体积。

我们对模版代码的生成逻辑和生成产物进行分析，发现 webpack 生产模式的默认配置中，很多配置项并不是体积最优的选项，一个典型的例子在于模块/chunk id：为了保障生成产物的内容稳定，来尽可能提升浏览器的缓存利用率，webpack 默认的模块/chunk id 采用 `deterministic` 模式进行生成，该模式下模块 id 为模块源路径的定长数字 hash，比项目模块总数长 1 位。由于在小程序中代码包按照版本的维度进行全量管理，保证文件局部的内容稳定在小程序环境下无正向意义，这就有了优化空间，我们可以简单将模块/chunk id 的生成逻辑改为数字自增，在主小程序中就能节省出上百 KB 总包体积。

类似的可优化点还存在于 chunk 链接代码和模块包装函数当中，我们在 `@mpxjs/webpack-plugin@2.9` 版本中提供了一个新的配置项 [optimizeSize](../api/compile.md#optimizesize)，其中整合了一系列模版代码体积优化配置，开启后就能自动优化构建产物中的模版代码体积，在主小程序中，我们开启 `optimizeSize` 后可以减少总包体积约 **540KB**，效果非常显著，下面是上述示例在开启 `optimizeSize` 后的产物对比：

```js
var g = {}
g.c = require('../bundle.js'), (g.c = g.c || []).push([[8], {
  448: function (t, e, o) {
    // ...
  },
  463: function (t) {
    // ...
  }
  // ...
}, function (t) {
  var e
  e = 448, t(t.s = e)
}])
```

### 空模块移除 {#empty-module-removal}

Mpx 在处理 `.mpx` 单文件时会将其分拆为 `template/js/style/json` 四个新模块来进行分别处理，其中 `template/style/json` 部分的内容会在处理后通过内置的 `extractor` 抽取输出为静态文件，抽取之后原本分拆出来的模块就会以空模块的形式残留在构建产物中（template 模块在抽取后还需要保留 render 函数和 refs 等信息所以不会成为空模块），如下所示：

```js
/***/ 533:
/***/ (function(__unused_webpack_module, __unused_webpack_exports, __webpack_require__) {
// ...
/* template */
__webpack_require__(535)
/* styles */
__webpack_require__(536)
/* json */
__webpack_require__(537)
/* script */
__webpack_require__(534)
/***/ }),
/***/ 536:
/***/ (function() {
/***/ }),
/***/ 537:
/***/ (function() {
/***/ })
```

从上面示例中可以看出 `536/537` 模块的定义和引用都是完全不必要的，但由于 webpack 本身对于空模块没有进行识别和优化的手段，在过去的版本中这些空模块代码会占用我们一部分总包体积。在 Mpx2.9 版本中，我们定义了全新的依赖类型 `CommonjsExtractDependency` 对于这类可能被抽取成为空模块的 `request` 进行识别处理，当模块内容在完成抽取后为空时，自动将其从模块图中移除，并在产物生成时不再生成其引用代码。该项优化措施内置开启，升级后自动生效，可减少主小程序总包体积约 **232KB**。

### Render函数优化 {#render-function-optimization}

Render 函数是 Mpx 运行时 `setData` 优化的一项核心设计，我们在模版编译时将用户模版转换为简易的 render 函数，该函数执行时能够完全模拟视图渲染的数据访问过程，正确地收集当前视图的数据依赖，避免将视图不需要的数据通过 `setData` 发送到视图中。

![render函数](https://dpubstatic.udache.com/static/dpubimg/ZQ6p8Rs2m7QCumOll3nmd.jpg)

虽然我们生成的简化版 render 函数仅保留了数据访问逻辑，在代码体积上并不算大，但是仍然存在着一定的优化空间，我们来看下面这个例子：

```js
function render(){
  this.a
  if(this.c){
    this.a
    this.b
    this.c.a
    this.c.b
    this.d
  }
  this.b
}
```

可以看出 `if block` 下存在着大量冗余不必要的数据访问，例如 `this.a` 和 `this.b` 在父级 `block` 中已经进行过访问，`this.c.a` 和 `this.c.b` 由于在 `if condition` 中进行过 `this.c` 的访问也不再必要（render函数执行时会对模版依赖数据进行深度diff，父路径访问后子路径就无需再进行访问），上述 render 函数可以优化为：

```js
function render(){
  this.a
  if(this.c){
    this.d
  }
  this.b
}
```

在 Mpx2.9 版本中，我们通过两轮 `ast` 遍历（`2 pass ast travese`）的方式实现了这个优化，在第一轮遍历中，我们收集了数据访问信息并按照 `block` 结构存储在 `blockVisitTree` 中，第二轮遍历时依据 `blockVisitTree` 中的信息对不必要的数据访问进行剪枝优化。

除此之外，我们也大幅优化了 render 函数中的数据收集代码，有效地降低了 render 函数的体积占用。

该优化目前没有默认开启，可以通过 `@mpxjs/webpack-plugin` 中的 [optimizeRenderRules](../api/compile.md#optimizerenderrules) 配置项配置生效范围进行开启，
全量开启后在主小程序中实测可节省总包体积约 **1507KB**。

## 未来规划 {#future-plan}

在未来，我们对 Mpx 构建产物还有进一步的优化方案可以探索实施，主要分为两个方向：

* 编译注入代码优化，在功能不变的情况下简化编译注入的代码，对于 render 函数也有一种运行时有损的方案（略微增大运行时开销）可以尝试
* 模版和JSON压缩，对模版和JSON中的组件名及组件路径进行短哈希压缩，缺点是丢失dist产物的可读性，可能需要对其提供 sourceMap 支持

除此之外，我们近期的框架升级计划还包括：

* 局部运行时渲染增强
* 数据响应升级为 proxy 实现，输出 web 升级为 vue3
* 支付宝 2.0 基础库适配优化
* 微信 skyline 适配优化
* 输出 Hummer 能力完善

在构建提速方面，我们也会在以下方向进行探索：

* 输出 web 支持 vite 构建
* 基于模块联邦的分布式构建
* 基于 Rust 的高性能构建探索

最后，特别感谢@徐伟东、@闫宇和@朱志恒对于 2.9 版本功能开发的突出贡献，也欢迎大家使用 Mpx 进行小程序跨端开发并加入社区共建。

Github：https://github.com/didi/mpx

官网/文档：https://mpxjs.cn/

---

---
url: /articles.md
---

# Mpx框架相关文章 {#mpx-articles}

* [滴滴开源小程序框架Mpx](1.0.md)
* [Mpx发布2.0，完美支持跨平台开发](2.0.md)
* [小程序框架运行时性能大测评](performance.md)
* [Mpx框架初体验](mpx1.md)
* [Mpx框架技术揭秘](mpx2.md)
* [基于Mpx框架做体积优化](size-control.md)
* [Mpx中基于 Typescript Template Literal Types 实现链式key的类型推导](ts-derivation.md)
* [Mpx2.7 版本正式发布，大幅提升编译构建速度](2.7-release.md)
* [Mpx2.8 版本正式发布，使用组合式 API 开发小程序](2.8-release.md)
* [Mpx2.9 版本正式发布，支持原子类、SSR 和包体积优化](2.9-release.md)
* [Mpx 2.11.0 版本正式发布，Mpx2RN 样式一致性与运行时性能系统升级](2.11-release.md)
* [Mpx-cli 插件化改造](mpx-cli-next.md)
* [Mpx 小程序单元测试能力建设与实践](unit-test.md)

---

---
url: /CLAUDE.md
---
参考[AGENTS.md](AGENTS.md)

---

---
url: /api-proxy/media/video/createVideoContext.md
---
## [VideoContext](https://developers.weixin.qq.com/miniprogram/dev/api/media/video/VideoContext.html) mpx.createVideoContext(string id, Object this)

创建 video 上下文 VideoContext 对象。建议使用 wx.createSelectorQuery 获取 context 对象。

支持情况： 微信、支付宝、web

[参考文档](https://developers.weixin.qq.com/miniprogram/dev/api/media/video/wx.createVideoContext.html)

### 参数 {#parameters}

**string id**

video 组件的 id

**Object this**

在自定义组件下，当前组件实例的this，以操作组件内 video 组件

### 返回值 {#return-value}

[VideoContext](https://developers.weixin.qq.com/miniprogram/dev/api/media/video/VideoContext.html)

---

---
url: /guide/advance/dll-plugin.md
---
# 使用 DllPlugin {#use-dll-plugin}

### 相关插件简述 {#plugin-summary}

#### DllPlugin

> DllPlugin 和 DllReferencePlugin 用某种方法实现了拆分 bundles，同时还大大提升了构建的速度，这个插件是在一个额外的独立的 webpack 设置中创建一个只有 dll 的 bundle(dll-only-bundle)。并且会生成一个名为 manifest.json的文件，这个文件是用来让 DLLReferencePlugin 映射到相关的依赖上去的。

DllPlugin 用来将我们某些长时间不变更的资源，独立拆分出去，之后项目的每次构建这部分资源都不需要重新编译，而是直接通过 DLLReferencePlugin 引入 dll bundle, 大大的节省了构建时间。

构建生成对应的 dll bundle 和 manifest.json 文件，manifest 文件中是模块 id 与请求路径的关系映射。

#### DllReferencePlugin

> 这个插件是在 webpack 主配置文件中设置的， 这个插件把只有 dll 的 bundle(们)(dll-only-bundle(s)) 引用到需要的预编译的依赖

通过引用 dll 的 manifest 文件来把依赖的名称映射到模块的 id 上，之后再在需要的时候通过内置的 **webpack\_require** 函数来 require 他们。

### Mpx中 DllPlugin 的使用 {#use-dll-plugin-in-mpx}

**1.通过 @mpxjs/cli init 生成项目**

初始化选项中选择使用dll功能。

**2.在项目中 build/dll.config.js 进行 dll 文件配置**

```js
const path = require('path')

// 这里是一个用法示例
function resolve (file) {
  return path.resolve(__dirname, '..', file || '')
}
module.exports = [
  {
    cacheGroups: [
      {
        entries: [resolve('node_modules/@someNpmGroup/someNpmPkgName/dist/wx/static/js/common.js')],
        name: 'test',
        root: 'testSomeDllFile'
      },
    ],
    modes: ['wx'],
    entryOnly: true,
    format: true,
    webpackCfg: {
      mode: 'none', // 不使用任何默认优化选项
    }
  },
  {
    cacheGroups: [
      {
        entries: [resolve('node_modules/@someNpmGroup/someNpmPkgName/dist/ali/static/js/common.js')],
        name: 'test',
        root: 'testSomeDllFile'
      },
    ],
    modes: ['ali'],
    entryOnly: true,
    format: true,
    webpackCfg: {
      mode: 'none', // 不使用任何默认优化选项
    }
  }

]
```

DllPlugin 的配置项详见[文档](https://webpack.docschina.org/plugins/dll-plugin/)，Mpx 中相关配置项依据小程序环境做了相关调整。

* **cacheGroups**
  * 类型: `Array<object>`
    * entries
      * 类型: `Array`dll

        构建入 dll 的文件入口
    * name
      * 类型: `String`

        生成的 dll 文件名
    * root
      * 类型: `String`

        生成的 dll 文件夹名

* **modes**
  * 类型: `Array`

    构建 dll 产物对应的平台

    ```js
    // 配置多平台输出，例如：
    [
      'wx', // 微信平台
      'ali' // 支付宝平台
    ]
    ```

* **entryOnly**
  * 类型: `Boolean`

    如果为true，则仅暴露入口

    这里建立使用entryOnly: true 配置

    > 如果为 false 时，dllPlugin 中的 tree shakeing 功能就不再起作用

    另外如果为false，如果是将分包资源打入dll bundle，会存在将全局方法打入分包 dll 中的可能性，这样主包在使用该方法被映射到 dll bundle 中时，会因为分包未加载而报错

* **webpackCfg**
  * 类型: `Object`

    构建 dll 时可添加其他的 webpack 配置

* **format**
  * 类型: `Boolean`

    生成的 manifest json 文件 是否进行格式化

### Mpx 中对 DllPlugin 配置所做的相关处理 {#dll-plugin-config-process}

正常使用 DllPlugin 是单独创建一个 webpack 配置文件，配置文件中加入 DllPlugin，然后运行 webpack 编译构建生成 dll 文件。

考虑到 Mpx 在编译时需要跨平台输出，所以 Mpx 的配置项是 `Array<object>` 类型，同时增加了 modes 配置项，可以自主控制输出不同平台版本 dll 文件。

构建生成 dll bundle 的主要逻辑在 buildDll.js 中，通过对 dll.config 中数组的循环处理，生成 webpackCfgs 数组。

```js
dllConfigs.forEach((dllConfig) => {
  const entries = getDllEntries(dllConfig.cacheGroups, dllConfig.modes)
  // 根据配置的 mode 以及 cacheGroups 生成 entry，结果例如：
  /**
  *{
        'somePkgRoot/wx.somePkgName': [
            '/Users/didi/didiProject/mp-apphome/node_modules/@someNpmGroup/somNpmName/dist/wx/static/js/common.js'
        ]
    }
  **/
  if (Object.keys(entries).length) {
    webpackCfgs.push(merge({
      entry: entries,
      output: {
        path: config.dllPath,
        filename: path.join('lib', dllName),
        libraryTarget: 'commonjs2'
      },
      mode: 'production',
      plugins: [
        new webpack.DllPlugin({
          path: path.join(config.dllPath, manifestName),
          format: dllConfig.format,
          entryOnly: dllConfig.entryOnly,
          name: dllName,
          type: 'commonjs2',
          context: config.context
        })
      ]
    }, dllConfig.webpackCfg))
  }
})
```

生成的 webpackCfgs 数组配置项，传入 webpack 执行，最终在 dll 文件夹下生成 dll bundle 和 manifest.json 文件

之后在 build.js 中使用 DllReferencePlugin 将编译中的依赖项与 dll bundle 的模块 id 关联起来，这里我们通过多个 DllReferencePlugin 实例来将可能存在的多个 manifest 文件关联引入，具体在项目 build.js 文件中：

```js
plugins.push(new webpack.DllReferencePlugin({
    context: config.context, //（绝对路径） manifest (或者是内容属性)中请求的上下文
    manifest: manifest.content // 请求到模块 id 的映射（默认值为 manifest.content）
}))
```

DllReferencePlugin 的其他配置项详见[文档](https://webpack.docschina.org/plugins/dll-plugin/)

### 总结 {#summary}

综上所述，在 Mpx 中使用 dllPlugin 时，只需要进行 build/dll.config.js 文件的配置，然后通过 build:dll 命令生成 dll bundle，之后就可以正常的进行代码的 build 了。不过每次 build 需要检查下项目中使用的 npm 包版本与 dll bundle 中的 npm 包版本是否一致，避免因为包版本的滞后更新导致线上 bug，这里我们后续也会提供相应的包版本比对插件。

---

---
url: /guide/advance/ts.md
---
# 使用TypeScript开发小程序 {#use-ts}

## 什么是TypeScript {#what-is-ts}

TypeScript 是一个开源的编程语言，通过在 JavaScript（世界上最常用的语言之一） 的基础上添加静态类型定义构建而成。

类型提供了一种描述对象形状的方法。可以帮助提供更好的文档，还可以让 TypeScript 验证你的代码可以正常工作。

在 TypeScript 中，不是每个地方都需要标注类型，因为类型推断允许您无需编写额外的代码即可获得大量功能。

## TypeScript优势 {#ts-advantage}

1. 静态类型检查
   静态类型检查可以避免很多不必要类型的错误，在编译阶段提前发现问题；

2. 强大的类型推断能力
   除了类型声明外，`TypeScript` 提供了强大的类型推断能力，该能力能够大大减少我们需要编写的类型声明，有效地减少我们使用 `TypeScript` 的额外压力；

3. IDE 智能提示
   目前主流的 IDE 都对 `TypeScript` 提供了良好的支持，基于 `TypeScript` 的类型系统提供友好准确的编码提示与错误检查。

## 使用方式 {#usage}

### 编写ts前的准备工作 {#preparation}

由于对 store 做类型推导使用了最新的 `TypeScript` 特性，因此需要将编辑器的 `TypeScript` 版本升级至 **4.1.3** 及以上版本。以下是 VSCode 配置示例：

1. 更新项目中的TypeScript为 4.1.3 及以上版本。

2. 在VSCode中打开一个 .js/.ts/.tsx 后缀的文件，使用 `Shift+Command+P` 唤出 VSCode 命令行，输入 `TypeScript` ，选择 `Select TypeScript Version`，选择使用工作区版本，将版本切换至 4.1.3 及以上版本。

3) 在 VSCode 编辑器中安装 mpx 插件，来支持在.mpx单文件中编写 ts 时的代码提示和实时报错等优秀体验。

::: warning
使用 @typescript/eslint-plugin 对 ts 代码进行检查，当在.mpx文件中使用全局类型时，eslint 会抛出 no-undef 错误，可以关闭相关 eslint 规则校验
:::

### .mpx中编写ts（推荐） {#write-ts-in-mpx}

目前 Mpx 已经支持在.mpx文件的 script 标签中编写 ts 代码，需要在 script 标签上添加 `lang="ts"` 属性，在编译时会自动这部分 script 中的内容进行 ts 类型检查。

```html
<script lang="ts">
// 内联编写ts代码
</script>
```

当然，由于大部分IDE对 ts 的语法支持都只对 .ts 和 .d.ts 文件生效，因此 Mpx 也支持创建一个 .ts 文件进行 ts 代码编写，在.mpx文件中，通过 src 的方式引入。

```html
<script lang="ts" src="./index.ts"></script>
```

### 为.ts文件添加loader {#add-ts-loader}

在 Webpack 配置中添加如下 rules 以配置 ts-loader

```js
{
  test: /\.ts$/,
  use: [
    'babel-loader',
    'ts-loader'
  ]
}
```

### 编写tsconfig.json文件 {#write-tsconfig}

对相关配置不熟悉的同学可以直接采用下面配置，能够最大限度发挥 Mpx 中强大的 ts 类型推导能力

```json
{
  "compilerOptions": {
    "target": "es6",
    "allowJs": true,
    "noImplicitThis": true,
    "noImplicitAny": true,
    "strictNullChecks": true,
    "moduleResolution": "node",
    "lib": [
      "dom",
      "es6",
      "dom.iterable"
    ]
  }
}
```

### 增强类型 {#enhanced-types}

如果需要增加 Mpx 的属性和选项，可以自定义声明 `TypeScript` 补充现有的类型。

例如，首先创建一个 types.d.ts 文件

```ts
// types.d.ts

import { Mpx } from '@mpxjs/core'

declare module '@mpxjs/core' {
  // 声明为 Mpx 补充的属性
  interface Mpx {
    $myProperty: string
  }
}
```

之后在任意文件只需引用一次 types.d.ts 声明文件即可，例如在 app.mpx 中引用

```ts
// app.mpx

/// <reference path="./types.d.ts" />
import mpx from '@mpxjs/core'

mpx.$myProperty = 'my-property'
```

## 类型推导及注意事项 {#type-inference-notes}

Mpx 基于泛型函数提供了非常方便用户使用的反向类型推导能力，简单来说，就是用户可以用非常接近于 js 的方式调用 Mpx 提供的 api ，就能够获得大量基于用户输入参数反向推导得到的类型提示及检查。但是由于 ts 本身的能力限制，我们在 Mpx 的运行时中添加了少量辅助函数和变种api，便于用户最大程度地享受反向类型推导带来的便利性，简单的使用示例如下：

```typescript
import {createComponent, getMixin, createStoreWithThis} from '@mpxjs/core'

// createStoreWithThis作为createStore的变种方法，主要变化在于定义getters，mutations和actions时，
// 获取自身的state，getters等属性不再通过参数传入，而是通过this.state或者this.getters等属性进行访问，
// 由于TS的能力限制，getters/mutations/actions只有使用对象字面量的方式直接传入createStoreWithThis时
// 才能正确推导出this的类型，当需要将getters/mutations/actions拆解为对象编写时，
// 需要用户显式地声明this类型，无法直接推导得出。

const store = createStoreWithThis({
  state: {
    aa: 1,
    bb: 2
  },
  getters: {
    cc() {
      return this.state.aa + this.state.bb
    }
  },
  actions: {
    doSth3() {
      console.log(this.getters.cc)
      return false
    }
  }
})

createComponent({
  data: {
    a: 1,
    b: '2'
  },
  computed: {
    c() {
      return this.b
    },
    d() {
      // data, mixin, computed中定义的数据能够被推导到this中
      return this.a + this.aaa + this.c
    },
    // 从store上map过来的计算属性或者方法同样能够被推导到this中
    ...store.mapState(['aa'])
  },
  mixins: [
    // 使用mixins，需要对每一个mixin子项进行getMixin辅助函数包裹，支持嵌套mixin
    getMixin({
      computed: {
        aaa() {
          return 123
        }
      },
      methods: {
        doSth() {
          console.log(this.aaa)
          return false
        }
      }
    })
  ],
  methods: {
    doSth2() {
      this.a++
      console.log(this.d)
      console.log(this.aa)
      this.doSth3()
    },
    ...store.mapActions(['doSth3'])
  }
})
```

### getMixin

为 ts 项目提供的反向推导 mixin 的辅助函数，getMixin 接收一个对象作为参数，使用 mixins 时，支持嵌套 mixin。具体用法见[getMixin](../../api/global-api.md#getmixin)。

### createStoreWithThis

为了在 ts 项目中更好的支持 store 的类型推导，提供了 createStoreWithThis 进行 store 的创建，createStoreWithThis 接收一个 options 对象作为参数。通过 createStoreWithThis 创建 store 时，使用`this.state`，`this.getters`，`this.commit`, `this.dispatch`对自身的相关属性进行获取。具体用法见[createStoreWithThis](../../api/store-api.md#createstorewiththis)。

### createStateWithThis

创建一个 state，支持 state 类型推导的辅助函数，具体用法见[createStateWithThis](../../api/store-api.md#createstatewiththis)

### createGettersWithThis

创建一个 getters，支持 getters 类型推导的辅助函数，具体用法见[createGettersWithThis](../../api/store-api.md#creategetterswiththis)

### createMutationsWithThis

创建一个 mutations，支持 mutations 类型推导的辅助函数，具体用法见[createMutationsWithThis](../../api/store-api.md#createmutationswiththis)

### createActionsWithThis

创建一个 actions，支持 actions 类型推导的辅助函数，具体用法见[createActionsWithThis](../../api/store-api.md#createactionswiththis)

---

---
url: /guide/extend.md
---
# 扩展mpx {#extend-mpx}

## 开发插件 {#develop-plugin}

mpx支持使用mpx.use使用插件来进行扩展。插件本身需要提供一个install方法或本身是一个function，该函数接收一个proxyMPX。插件将采用直接在proxyMPX挂载新api属性或在prototype上挂属性。需要注意的是，一定要在app创建之前进行mpx.use。

简单示例如下：

```js
export default function install(proxyMPX) {
  proxyMPX.newApi = () => console.log('is new api')
  proxyMPX
    .mixin({
      onLaunch() {
        console.log('app onLaunch')
      }
    }, 'app')
    .mixin({
      onShow() {
        console.log('page onShow')
      }
    }, 'page') // proxyMPX.injectMixins === proxyMPX.mixin

    //  注意：proxyMPX.prototype上挂载的属性都将挂载到组件实例（page实例、app实例上，可以直接通过this访问）, 可以看mixin中的case
    proxyMPX.prototype.testHello = function() {
      console.log('hello')
    }
}
```

## 目前已有插件 {#existing-plugins}

* 网络请求库fetch: @mpxjs/fetch [详细介绍](#fetch) [源码地址](https://github.com/didi/mpx/tree/master/packages/fetch)

* 小程序API转换及promisify：@mpxjs/api-proxy [详细介绍](#api-proxy) [源码地址](https://github.com/didi/mpx/tree/master/packages/api-proxy)

* mock数据：@mpxjs/mock [详细介绍](#mock) [源码地址](https://github.com/didi/mpx/tree/master/packages/mock)

## 扩展组件 {#extend-components}

Mpx 提供跨端扩展组件能力，详见 [Mpx 扩展组件](./extend-component)。

---

---
url: /desc.md
---
# 文档写作指南

该文档使用 [vitepress](https://vitepress.dev/zh/) 生成

## 该项目指南

```sh
# 写作时
npm run docs:dev

# 部署时
npm run docs:build
# 将在 docs-vitepress/.vitepress/dist 下生成静态文件，部署到相应服务器即可，部署参考下方链接
```

## 编写格式指南

* 对于引用的文档或资料使用[链接]()指明出处
* 中英文混排时为了阅读体验使用空格对于英文单词进行包裹，在标点符号边缘或句首时可省略该侧空格，例如：这是一个 word 而不是 world。
* 句首的英文单词首字母大写
* Mpx 正确的写法为 `Mpx`，首字母大写，任何地方都应该这样书写，其余的专业名称参考原始的写法进行书写
* 除英文段落外，所有标点符号使用中文半角
* 能使用示例代码描述的部分都**尽量添加示例代码**进行说明，show me the code
* 对于文档内容拓展说明的部分使用>引用的方式进行编写，like this

> 我们来聊聊人生吧，这个地方你可以不看但没必要

## 参考

* [部署指南](https://vitepress.dev/zh/guide/deploy)
* [Vitepress 文档](https://vitepress.dev/zh/)

---

---
url: /AGENTS.md
---
# 文档开发指南

`docs-vitepress/` 是 Mpx 官方文档站点，基于 [VitePress](https://vitepress.dev/zh/) 构建，部署后即 <https://mpxjs.cn/>。本文档面向 Agent，描述文档站点的整体组织结构、内容归档原则与索引位置，便于新增、修改、迁移文档时快速定位。

## 本地开发

```sh
# 写作时
npm run docs:dev

# 部署时构建静态产物（输出到 .vitepress/dist）
npm run docs:build
```

## 编写规范

参考 [desc.md](desc.md)。要点：

* 中英文混排时英文单词两侧加空格（标点边缘或句首可省略）；句首英文单词首字母大写
* 框架名统一写作 `Mpx`（首字母大写）
* 除英文段落外，标点统一使用中文半角
* 优先用示例代码说明（show me the code）
* 拓展说明用 `>` 引用块

### 中文标题哈希锚点

新增或修改中文标题时，使用 `{#simple-hash}` 语法显式指定英文锚点，避免默认生成的 `#中文标题` 形式：

```markdown
# 文档标题 {#simple-hash}
```

约束：

* 锚点只能包含小写字母、数字和短横线（`-`），不能含空格或其它特殊字符
* 不能以短横线开头或结尾
* 同一文档内不能重复
* 锚点应根据中文标题语义命名

## 顶层目录结构

| 目录 | 内容定位 | 备注 |
| --- | --- | --- |
| [.vitepress/](.vitepress/) | VitePress 配置：导航、侧边栏、主题、PWA、搜索翻译等 | 新增文档需同步更新 [.vitepress/config.ts](.vitepress/config.ts) 的 `sidebar` |
| [guide/](guide/) | 使用指南：基础、进阶、跨端、组合式 API、工具、拓展、原理、迁移 | 站点主入口，承载教程类内容 |
| [api/](api/) | 框架 API 参考：全局/实例/编译/响应式/组合式/选项式 API、指令、内建组件 | `@mpxjs/core` 与 `@mpxjs/webpack-plugin` 的 API 字典 |
| [api-proxy/](api-proxy/) | 环境 API 参考：`@mpxjs/api-proxy` 跨端宿主能力，按 base/route/interface/network/media/device/storage/location/open-api/payment/ext/canvas/wxml 分类 | 每个 API 一个 `.md` 文件 |
| [articles/](articles/) | 文章合辑：版本发布说明、技术揭秘、性能/包体积/单测等专题 | 时间线归档，包含历次 release 文章 |
| [assets/](assets/) | 文档内引用的图片、示意图等静态资源 | 仅用于文档内 `![]()` 引用 |
| [public/](public/) | 公共静态资源（logo、favicon、PWA icon 等） | 由 VitePress 直接复制到产物根目录 |
| [index.md](index.md) | 站点首页（`home: true`）：hero、特性、案例、生态、社区、资源 | 内容以 frontmatter 数据驱动主题渲染 |
| [desc.md](desc.md) | 面向人类作者的写作规范说明 | 与本文件互补，本文面向 Agent |

## 内容归档原则

新增或迁移文档时，先按"读者意图"判断归属，再决定落地目录：

### `guide/` —— 使用指南（教程视角）

教读者「怎么用 Mpx 完成某件事」。文件按主题分组，组与 `.vitepress/config.ts` 中的侧边栏分组一一对应：

* [guide/basic/](guide/basic/) —— 基础：项目结构、App/Page/Component、模板/样式/事件/绑定/生命周期
* [guide/advance/](guide/advance/) —— 进阶：状态管理、分包、i18n、SSR、TS、原子类、size-report、CLI、自定义路径等
* [guide/cross-platform/](guide/cross-platform/) —— 跨端基础：跨端配置、条件编译
* [guide/rn/](guide/rn/) —— 跨端 RN：RN 输出相关的快速开始、组件、模板、样式、应用能力、混编
* [guide/composition-api/](guide/composition-api/) —— 组合式 API、响应式 API
* [guide/tool/](guide/tool/) —— 工具：单元测试、E2E
* [guide/extend/](guide/extend/) —— 周边拓展：fetch、mock、webview-bridge
* [guide/understand/](guide/understand/) —— 原理：运行时增强、编译构建
* [guide/migrate/](guide/migrate/) —— 版本迁移指南

判断依据：内容是「面向场景的操作步骤」就放 `guide/`；如果是「字典式 API 罗列」放 `api/` 或 `api-proxy/`。

### `api/` —— 框架 API 参考（字典视角）

`@mpxjs/core` / `@mpxjs/webpack-plugin` 暴露的 API、配置项、指令、内建组件、生命周期钩子等。每个文件聚焦一类 API（如 [api/composition-api.md](api/composition-api.md)、[api/directives.md](api/directives.md)）。新增 API 时优先追加到既有文件，避免碎片化。

### `api-proxy/` —— 环境 API 参考

`@mpxjs/api-proxy` 提供的跨端宿主能力。组织遵循微信小程序 API 分类：

* `base/`（含 `app/`、`system/`）、`route/`、`interface/`（含 `interactive/`、`navigation-bar/`、`tab-bar/`、`pull-down-refresh/`、`scroll/`、`animation/`、`custom-component/`、`menu/`、`window/`）
* `network/`（含 `request/`、`download/`、`upload/`、`websocket/`）
* `media/`（含 `image/`、`audio/`、`video/`）、`device/`（含 `bluetooth-ble/`、`clipboard/`、`contacts/`、`keyboard/`、`network/`、`phone/`、`scan/`、`screen/`、`vibrate/`）
* `storage/`、`location/`、`open-api/`（含 `login/`、`setting/`、`user-info/`）、`payment/`、`ext/`、`canvas/`、`wxml/`

约定：一个 API 一个 `.md`，文件名与 API 同名（驼峰）。新增能力分类时同步在 `.vitepress/config.ts` 的 `'/api-proxy/'` 侧边栏树补充节点。

### `articles/` —— 文章与 release notes

按时间线归档的专题文章和版本发布说明（`2.x-release.md`、`mpx1.md`、`performance.md`、`unit-test.md` 等）。新增 release 文章时同步在 `.vitepress/config.ts` 的 `'/articles/'` 侧边栏补充入口。

### `assets/` 与 `public/`

* 文档正文引用的图片放 [assets/](assets/)
* 站点级静态资源（logo、favicon、PWA 图标）放 [public/](public/)，由 VitePress 直接复制到产物根目录

## 索引（必须同步维护）

新增、删除、重命名 `.md` 文件时，必须同步更新：

1. **[.vitepress/config.ts](.vitepress/config.ts)** —— `sidebar` 对象
   * `'/guide/'`、`'/api/'`、`'/api-proxy/'`、`'/articles/'` 四个侧边栏入口
   * 顶部导航 `themeConfig.nav` 中的相关链接（如有跨区跳转）
2. **目录内的 `index.md`**（部分目录有，如 [api/index.md](api/index.md)、[api-proxy/index.md](api-proxy/index.md)、[guide/extend/index.md](guide/extend/index.md)、[articles/index.md](articles/index.md)）—— 内部目录列表
3. **跨文档链接** —— 移动或重命名文件后，使用全局搜索更新引用：

   ```sh
   grep -r "/old/path" docs-vitepress
   ```

## 更新文档的标准动作

1. 判断内容归属（按上面的「内容归档原则」）
2. 在对应目录新增或修改 `.md`
3. 同步 [.vitepress/config.ts](.vitepress/config.ts) 的侧边栏与导航
4. 如新增子目录，同步对应目录的 `index.md`
5. 全局检查跨文档链接是否需要修正
6. `npm run docs:dev` 本地预览，确认侧边栏、链接、图片均渲染正常

## 路径指引

* 修改某个特性的使用方式 → `guide/` 对应分组
* 新增/修改框架 API → `api/` 中相应文件，避免新建零散文件
* 新增/修改环境 API → `api-proxy/<分类>/<apiName>.md`
* 撰写版本发布说明、技术专题 → `articles/`
* 调整侧边栏、导航、主题、搜索翻译、PWA → `.vitepress/`
* 调整首页 hero/特性/案例 → [index.md](index.md) 的 frontmatter
* 调整写作风格规范 → [desc.md](desc.md)

---

---
url: /guide/advance/accessibility.md
---
# 无障碍访问{#accessibility}

---

---
url: /guide/advance/resource-resolve.md
---
# 资源路径获取 {#resource-path-resolve}

Mpx在构建时，如果引用的页面不存在于当前 app.mpx 所在的上下文中，例如存在于 npm 包中，为避免和本地声明的其他 page 路径冲突，Mpx 会对页面路径进行 hash 化处理；
处理组件路径时也会添加 hash 防止路径名冲突，hash 化处理后最终的文件名是 name+hash+ext 的格式；对于图片等资源路径输出也会进行 hash 化处理。

开发者经常会面临以下问题：

* 希望获取 hash 化之后的页面/组件/图片路径
* 在页面路径变化时(分包名更改或页面名修改)，需要手动修改散落在代码中各处写死的资源路径

## ?resolve

为了解决以上开发者痛点，Mpx 框架提供了资源路径自动获取能力，只需要在资源引用路径后加上?resolve，
Mpx 在编译时会生成一个资源路径处理模块，该模块暴露出资源对应的真实输出路径，从而可以实现在页面/组件/图片路径变化时正确获取输出路径，并避免写死资源路径。

获取并使用页面路径

```js
// app.json 中注册分包，此处仅列出 packages 语法示例
{
    packages: [
        '@someNpm/app.mpx?root=someNpm'
    ]
}

// import 语法获取并使用页面路径
import subPackageIndexPage from '@someNpm/subpackage/pages/index.mpx?resolve'
mpx.navigateTo({
    url: subPackageIndexPage
})

// require 语法获取并使用页面路径
mpx.navigateTo({
    url: require('@someNpm/subpackage/pages/index.mpx?resolve')
})
```

获取并使用组件资源路径

> 我们在使用小程序 relations 语法时，需要获取组件路径，这时就可使用 ?resolve 语法

```js
import { createComponent } from '@mpxjs/core'
import someComponentItem from './some-component-item?resolve'

createComponent({
    relations: {
        [someComponentItem]: {
            type: 'child'
        }
    }
})
```

获取并使用图像资源路径

```html
<template>
    <view wx:style="{{someStyle}}">test</view>
</template>

<script>
    import mpx, { createPage } from '@mpxjs/core'
    import iconPath from '../assets/icon.png?resolve'
    
    createPage({
        computed: {
            someStyle() {
                return `background-image url(${iconPath})`
            }
        }
    })
</script>
```

---

---
url: /guide/advance/platform.md
---
# 跨平台 {#cross-platform}

## 多平台支持 {#multi-platform-support}

Mpx支持在多个小程序平台中进行增强，目前支持的小程序平台包括微信，支付宝，百度，qq和头条，不过自2.0版本后，Mpx支持了以微信增强语法为base的跨平台输出，实现了一套业务源码在多端输出运行的能力，大大提升了多小程序平台业务的开发效率，详情可以查看[跨平台编译](#跨平台编译)

### template增强特性 {#template-enhancement}

不同平台上的模板增强指令按照平台的指令风格进行设计，文档和代码示例为了方便统一采用微信小程序下的书写方式。

模板增强指令对应表：

增强指令|微信|支付宝|百度|qq|头条
\----|----|----|----|----|----
双向绑定|wx:model|a:model|s-model|qq:model|tt:model
双向绑定辅助属性|wx:model-prop|a:model-prop|s-model-prop|qq:model-prop|tt:model-prop
双向绑定辅助属性|wx:model-event|a:model-event|s-model-event|qq:model-event|tt:model-event
双向绑定辅助属性|wx:model-value-path|a:model-value-path|s-model-value-path|qq:model-value-path|tt:model-value-path
双向绑定辅助属性|wx:model-filter|a:model-filter|s-model-filter|qq:model-filter|tt:model-filter
动态样式绑定|wx:class|a:class|s-class|qq:class|暂不支持
动态样式绑定|wx:style|a:style|s-style|qq:style|暂不支持
获取节点/组件实例|wx:ref|a:ref|s-ref|qq:ref|tt:ref
显示/隐藏|wx:show|a:show|s-show|qq:show|tt:show

### script增强特性 {#script-enhancement}

增强字段|微信|支付宝|百度|qq|头条
\----|----|----|----|----|----
computed|支持|支持|支持|支持|部分支持，无法作为props传递(待头条修复生命周期执行顺序可完整支持)
watch|支持|支持|支持|支持|支持
mixins|支持|支持|支持|支持|支持

### style增强特性 {#style-enhancement}

无平台差异

### json增强特性 {#json-enhancement}

增强字段|微信|支付宝|百度|qq|头条
\----|----|----|----|----|----
packages|支持|支持|支持|支持|部分支持，无法分包

## 跨平台输出小程序 {#cross-platform-output}

自2.0版本开始，mpx开始支持跨小程序平台编译，不同于常规跨平台框架重新定义一套DSL的方式，mpx支持基于现有平台的源码编译为其他已支持平台的目标代码。跨平台编译能力依赖于mpx的多平台支持，目前mpx已经支持将微信小程序跨平台编译为支付宝、百度、qq和头条小程序。

### 使用方法 {#usage}

如果你是使用`mpx init xxx`新生成的项目，package.json里script部分有`npm run build:cross`，直接执行`npm run build:cross`（watch同理），如果仅需构建某几个平台的，可以修改该script，按已有的格式删除或增添某些某些平台

如果你是自行搭建的mpx项目，你只需要进行简单的配置修改，打开项目的webpack配置，找到@mpxjs/webpack-plugin的声明位置，传入mode和srcMode参数即可，示例如下

```javascript
new MpxwebpackPlugin({
  // mode为mpx编译的目标平台，可选值有(wx|ali|swan|qq|tt|jd|web|ios|android)
  mode: 'ali',
  // srcMode为mpx编译的源码平台，目前仅支持wx   
  srcMode: 'wx'
})
```

使用 @mpxjs/cli 创建的项目，可以通过在 `npm script` 当中定义 `targets` 来设置编译的目标平台

```javascript
// 项目 package.json
{
  "script": {
    "build:cross": "mpx-cli-service build --targets=wx,ali"
  }
}
```

### 跨平台差异抹平 {#cross-platform-diff-flatten}

为了实现小程序的跨平台编译，我们在编译和运行时做了很多工作以抹平小程序开发中各个方面的跨平台差异

#### 模板语法差异抹平 {#template-syntax-diff}

对于通用指令/事件处理的差异，mpx提供了统一的编译转换抹平操作；而对于平台组件和组件属性的差异，我们也在力所能及的范围内进行了转换抹平，对于平台差异性过大无法转换的部分会在编译阶段报错指出。

#### 组件/页面对象差异抹平 {#component-page-object-diff}

不同平台间组件/页面对象的差异主要体现在生命周期上，我们在支持多平台能力时已经将不同平台的生命周期映射到mpx框架的一套内部生命周期中，基于这个统一的映射，不同平台的生命周期差异也得到了抹平。

此外，我们还进行了一系列运行时增强来模拟微信平台中提供而其他平台中未提供的能力，例如：

* 在支付宝组件实例中提供了this.triggerEvent方法模拟微信中的自定义组件事件；
* 提供了this.selectComponent/this.selectAllComponents方法模拟微信中获取子组件实例的能力；
* 重写了createSelectorQuery方法抹平了微信/支付宝平台间的使用差异；
* 转换抹平了微信/支付宝中properties定义的差异；
* 利用mpx本身的数据响应能力模拟了微信中的observers/property observer能力等;
* 提供了this.getRelationNodes方法并支持了微信中组件间关系relations的能力

对于原生小程序组件的转换，还会进行一些额外的抹平，已兼容一些已有的原生组件库，例如：

* 将支付宝组件中的props数据挂载到this.data中以模拟微信平台中的表现；
* 利用mpx本身的mixins能力模拟微信中的behaviors能力。

对于一些无法进行模拟的跨平台差异，会在运行时进行检测并报错指出，例如微信转支付宝时使用moved生命周期等。

#### json配置差异抹平 {#json-config-diff}

类似于模板语法，会在编译阶段进行转换抹平，无法转换的部分会在编译阶段报错指出。

#### api调用差异抹平 {#api-diff-flatten}

对于api调用，mpx提供了一个api调用代理插件来抹平跨平台api调用的差异，使用时需要在项目中安装使用`@mpxjs/api-proxy`，可以通过两种方式使用

#### 方式一：在调用小程序api时统一使用mpx对象进行调用，示例如下： {#method-1-use-mpx-object}

安装插件支持options传入，options说明如下：

| 参数名称         | 类型                | 含义                       | 是否必填  | 默认值                    | 备注                    |
|--------------|-------------------|--------------------------|-------|------------------------|-----------------------|
| ~~platform~~ | ~~Object~~        | ~~各平台之间的转换~~	            | ~~否~~ | ~~{ from:'', to:'' }~~ | 已删除                   |
| usePromise   | Boolean           | 是否将 api 转化为 promise 格式使用 | -     | -                      | -                     |
| ~~exclude~~  | ~~Array(String)~~ | ~~跨平台时不需要转换的 api~~       | -     | -                      | 已删除                     |
| whiteList    | Array(String)     | 强行转化为 promise 格式的 api    | 否     | \[]                     | 需要 usePromise 设为 true |
| blackList    | Array(String)     | 不转换 promise 格式的 api      | 否     | \[]                     | 需要 usePromise 设为 true |
| custom       | Object            | 提供用户在各渠道下自定义api开放能力      | 否     | \[]                     | -                     |

#### 普通形式 {#normal-form}

```js
import mpx from '@mpxjs/core'
import apiProxy from '@mpxjs/api-proxy'

mpx.use(apiProxy)

mpx.showModal({
  title: '标题',
  content: '这是一个弹窗',
  success (res) {
    if (res.cancel) {
      console.log('用户点击取消')
    }
  }
})
```

#### 使用promise形式 {#use-promise}

```js
import mpx from '@mpxjs/core'
import apiProxy from '@mpxjs/api-proxy'

mpx.use(apiProxy, {
  usePromise: true
})

mpx.showActionSheet({
  itemList: ['A', 'B', 'C']
})
.then(res => {
  console.log(res.tapIndex)
})
.catch(err => {
  console.log(err)
})
```

#### 用户自定义 {#user-custom}

```js
import mpx from '@mpxjs/core'
import apiProxy from '@mpxjs/api-proxy'
import { scanCode } from '@test/scanCode'

mpx.use(apiProxy, {
  custom: {
    web: {
      scanCode
    }
  }
})
// 在web下调用的实际是用户自定义部分的scanCode
mpx.scanCode({
  onlyFromCamera: true,
  success (res) {
    console.log(res, 'scanCode, success')
  },
  fail (res) {
    console.log(res, 'scanCode, fail')
  }
})
```

#### 方式二：直接在`@mpxjs/api-proxy`导出想使用的方法 {#method-2-import-from-api-proxy}

```js
// 独立使用 支持treesharking能力
import { showModal } from '@mpxjs/api-proxy'

showModal({
  title: '标题',
  content: '这是一个弹窗',
  success (res) {
    console.log('弹框展示成功')
  }
})
```

对于无法转换抹平的api调用会在运行时阶段报错指出。

#### webview bridge差异抹平 {#webview-bridge-diff-flatten}

Mpx支持小程序跨平台后，多个平台的小程序里都有webview组件，webview打开的页面和小程序可以通过API来通信以及调用一些小程序能力，但是各方webview提供的API是不一样的。

比如微信是用 wx.miniProgram.navigateTo 来跳转到别的小程序页面，而支付宝里是 my.navigateTo ，那么我们开发H5时候为了让H5能适应各家小程序平台就需要写多份对应逻辑。

为解决这个问题，Mpx提供了用于运行在小程序的webview里的H5抹平平台差异的bridge库：@mpxjs/webview-bridge

使用方式很简单，不过注意这个库是给H5用的，不是给小程序用的。在H5项目中引入。

[使用示例](https://github.com/didi/mpx/tree/master/examples/mpx-webview)

支持script标签引入和npm引入，标签引入的话，全局实例是mpx（npm模块使用下也鼓励import mpx from '@mpxjs/webview-birdge'），使用就例如 mpx.navigateTo ，能保持整个项目风格完全一致。

提供的API如下：`navigateTo, navigateBack, switchTab, reLaunch, redirectTo, getEnv, postMessage, getLoadError`

## 跨平台条件编译 {#cross-platform-conditional-compile}

Mpx跨平台编译的原则在于，`能转则转，转不了则报错提示`，对于无法抹平差异的部分，我们提供了完善的跨平台条件编译机制便于用户处理因平台差异而无法相互转换的部分，也能够用于实现具有平台差异性的业务逻辑。

mpx中我们支持了三种维度的条件编译，分别是文件维度，区块维度和代码维度，其中，文件维度和区块维度主要用于处理一些大块的平台差异性逻辑，而代码维度主要用于处理一些局部简单的平台差异。

### 文件维度条件编译 {#file-conditional-compile}

文件维度条件编译简单的来说就是文件为维度进行跨平台差异代码的编写，例如在微信->支付宝的项目中存在一个业务地图组件map.mpx，由于微信和支付宝中的原生地图组件标准差异非常大，无法通过框架转译方式直接进行跨平台输出，这时你可以在相同的位置新建一个map.ali.mpx，在其中使用支付宝的技术标准进行开发，编译系统会根据当前编译的mode来加载对应模块，当mode为ali时，会优先加载map.ali.mpx，反之则会加载map.mpx。

文件维度条件编译能够与webpack alias结合使用，对于npm包的文件我们并不方便在原本的文件位置创建.ali的条件编译文件，但我们可以通过webpack alias在相同位置创建一个`虚拟的`.ali文件，并将其指向项目中的其他文件位置。

```js
  // 对于npm包中的文件依赖
  import npmModule from 'somePackage/lib/index'

  // 配置以下alias后，当mode为ali时，会优先加载项目目录中定义的projectRoot/somePackage/lib/index文件
  // vue.config.js
  module.exports = defineConfig({
    configureWebpack() {
      return {
        resolve: {
          alias: {
            'somePackage/lib/index.ali': 'projectRoot/somePackage/lib/index'
          }
        }
      }
    }
  })
```

### 区块维度条件编译 {#block-conditional-compile}

在.mpx单文件中一般存在template、js、stlye、json四个区块，mpx的编译系统支持以区块为维度进行条件编译，只需在区块标签中添加`mode`属性定义该区块的目标平台即可，示例如下：

```html
<!--编译mode为ali时使用如下区块-->
<template mode="ali">
<!--该区块中的所有代码需采用支付宝的技术标准进行编写-->
  <view>支付宝环境</view>
</template>

<!--其他编译mode时使用如下区块-->
<template>
  <view>其他环境</view>
</template>
```

### 代码维度条件编译 {#code-conditional-compile}

如果只有局部的代码存在跨平台差异，mpx同样支持在代码内使用if/else进行局部条件编译，用户可以在js代码和template插值中访问`__mpx_mode__`获取当前编译mode，进行平台差异逻辑编写，js代码中使用示例如下。

除了 `__mpx_mode__` 这个默认插值以外，有别的环境变量需要的话可以在mpx.plugin.conf.js里通过defs进行配置。

```js
if(__mpx_mode__ === 'ali') {
  // 执行支付宝环境相关逻辑
} else {
  // 执行其他环境相关逻辑
}
```

template代码中使用示例如下

```html
<!--此处的__mpx_mode__不需要在组件中声明数据，编译时会基于当前编译mode进行替换-->
<view wx:if="{{__mpx_mode__ === 'ali'}}">支付宝环境</view>
<view wx:else>其他环境</view>
```

JSON中的条件编译（注意，这个依赖JSON的动态方案，得通过name="json"这种方式来编写，其实写的是js代码，最终module.exports导出一个可json化的对象即可）：

```html
<script name="json">
const pages = __mpx_mode__ === 'wx' ? [
  'main/xxx',
  'sub/xxx'
] : [
  'test/xxx'
] // 可以为不同环境动态书写配置
module.exports = {
  usingComponents: {
    aComponents: '../xxxxx' // 可以打注释 xxx组件
  }
}
</script>
```

样式的条件编译：

```css
/*
  @mpx-if (__mpx_env__ === 'someEvn')
*/
  /* @mpx-if (__mpx_mode__ === 'wx') */
  .backColor {
    background: green;
  }
  /*
    @mpx-elif (__mpx_mode__ === 'qq')
  */
  .backColor {
    background: black;
  }
  /* @mpx-endif */

  /* @mpx-if (__mpx_mode__ === 'swan') */
  .backColor {
    background: cyan;
  }
  /* @mpx-endif */
  .textSize {
    font-size: 18px;
  }
/*
  @mpx-else
*/
.backColor {
  /* @mpx-if (__mpx_mode__ === 'swan') */
  background: blue;
  /* @mpx-else */
  background: red;
  /* @mpx-endif */
}
/*
  @mpx-endif
*/
```

### 属性维度条件编译 {#attr-conditional-compile}

属性维度条件编译允许用户在组件上使用 `@` 和 `|` 符号来指定某个节点或属性只在某些平台下有效。

对于同一个 button 组件，微信小程序支持 `open-type="getUserInfo"`，但是支付宝小程序支持 `open-type="getAuthorize" `。如果不使用任何维度的条件编译，则在编译的时候会有警告和报错信息。

比如业务中需要通过 button 按钮获取用户信息，虽然可以使用代码维度条件编译来解决，但是增加了很多代码量：

```html
<button
  wx:if="{{__mpx_mode__ === 'wx' || __mpx_mode__ === 'swan'}}"
  open-type="getUserInfo"
  bindgetuserinfo="getUserInfo">
  获取用户信息
</button>

<button
  wx:elif="{{__mpx_mode__ === 'ali'}}"
  open-type="getAuthorize"
  scope="userInfo"
  onTap="onTap">
  获取用户信息
</button>
```

而用属性维度的编译则方便很多：

```html
<button
  open-type@wx|swan="getUserInfo"
  bindgetuserinfo@wx|swan="getUserInfo"
  open-type@ali="getAuthorize"
  scope@ali="userInfo"
  onTap@ali="onTap">
  获取用户信息
</button>
```

属性维度的编译也可以对整个节点进行条件编译，例如只想在支付宝小程序中输出某个节点：

```html
<view @ali>this is view</view>
```

需要注意使用上述用法时，节点自身在构建时框架不会对节点属性进行平台语法转换，但对于其子节点，框架并不会继承父级节点 mode，会进行正常跨平台语法转换。

```html
<!--错误示例-->
<view @ali bindtap="otherClick">
    <view bindtap="someClick">tap click</view>
</view>
// srcMode 为 wx 跨端输出 ali 结果为
<view @ali bindtap="otherClick">
    <view onTap="someClick">tap click</view>
</view>
```

上述示例为错误写法，假如srcMode为微信小程序，用上述写法构建输出支付宝小程序时，父节点 bindtap 不会被转为 onTap，在支付宝平台执行时事件会无响应。

正确写法如下：

```html
<!--正确示例-->
<view @ali onTap="otherClick">
    <view bindtap="someClick">tap click</view>
</view>
// 输出 ali 产物
<view @ali onTap="otherClick">
    <view onTap="someClick">tap click</view>
</view>
```

有时开发者期望使用 @ali 这种方式仅控制节点的展示，保留节点属性的平台转换能力，为此 Mpx 实现了一个隐式属性条件编译能力

```html
<!--srcMode为 wx，输出 ali 时，bindtap 会被正常转换为 onTap-->
<view @_ali bindtap="someClick">test</view>
```

在对应的平台前加一个\_，例如@\_ali、@\_swan、@\_tt等，使用该隐式规则仅有条件编译能力，节点属性语法转换能力依旧。

有时候我们不仅需要对节点属性进行条件编译，可能还需要对节点标签进行条件编译。

为此，我们支持了一个特殊属性 `mpxTagName`，如果节点存在这个属性，我们会在最终输出时将节点标签修改为该属性的值，配合属性维度条件编译，即可实现对节点标签进行条件编译，例如在百度环境下希望将某个 view 标签替换为 cover-view，我们可以这样写：

```html
<view mpxTagName@swan="cover-view">will be cover-view in swan</view>
```

### 通过 env 实现自定义目标环境的条件编译 {#use-env}

Mpx 支持在以上四种条件编译的基础上，通过自定义 env 的形式实现在不同环境下编译产出不同的代码。

实例化 MpxWebpackPlugin 的时候，传入配置 env。

```javascript
// vue.config.js
module.exports = defineConfig({
  pluginOptions: {
    mpx: {
      srcMode: 'wx' // srcMode为mpx编译的源码平台，目前仅支持wx
      plugin: {
        env: "didi" // env为mpx编译的目标环境，需自定义
      }
    }
  }
})
```

#### 文件维度条件编译 {#file-conditional-compile-1}

微信转支付宝的项目中存在一个业务地图组件map.mpx，由于微信和支付宝中的原生地图组件标准差异非常大，无法通过框架转译方式直接进行跨平台输出，而且这个地图组件在不同的目标环境中也有很大的差异，这时你可以在相同的位置新建一个 map.ali.didi.mpx 或 map.ali.qingju.mpx，在其中使用支付宝的技术标准进行开发，编译系统会根据当前编译的 mode 和 env 来加载对应模块，当 mode 为 ali，env 为 didi 时，会优先加载 map.ali.didi.mpx、map.ali.mpx，如果没有定义 env，则会优先加载 map.ali.mpx，反之则会加载 map.mpx。

#### 区块维度条件编译 {#block-conditional-compile-1}

在.mpx单文件中一般存在template、js、stlye、json四个区块，mpx的编译系统支持以区块为维度进行条件编译，只需在区块标签中添加`mode`或`env`属性定义该区块的目标平台即可，示例如下：

```html
<!--编译mode为ali且env为didi时使用如下区块，优先级最高是4-->
<template mode="ali" env="didi">
  <view>该区块中的所有代码需采用支付宝的技术标准进行编写</view>
</template>

<!--编译mode为ali时使用如下区块，优先级是3-->
<template mode="ali">
  <view>该区块中的所有代码需采用支付宝的技术标准进行编写</view>
</template>

<!--编译env为didi时使用如下区块，优先级是2-->
<template env="didi">
  <view>该区块中的所有代码需采用支付宝的技术标准进行编写</view>
</template>

<!--其他环境，优先级是1-->
<template>
  <view>该区块中的所有代码需采用支付宝的技术标准进行编写</view>
</template>
```

注意，如果多个相同的区块写相同的 mode 和 env，默认会用最后一个，如：

```html
<template mode="ali">
  <view>该区块会被忽略</view>
</template>

<template mode="ali">
  <view>默认会用这个区块</view>
</template>
```

#### 代码维度条件编译 {#code-conditional-compile-1}

如果在 MpxWebpackPlugin 插件初始化时自定义了 env，你可以访问`__mpx_env__`获取当前编译env，进行环境差异逻辑编写。使用方法与`__mpx_mode__`相同。

#### 属性维度条件编译 {#attr-conditional-compile-1}

env 属性维度条件编译与 mode 的用法大致相同，使用 `:` 符号与 mode 和其他 env 进行串联，与 mode 组合使用格式形如 `attr@mode:env:env|mode:env`，为了不与 mode 混淆，当条件编译中仅存在 env 条件时，也需要添加 `:` 前缀，形如 `attr@:env`。

对于同一个 button 组件，微信小程序支持 `open-type="getUserInfo"`，但是支付宝小程序支持 `open-type="getAuthorize" `。如果不使用任何维度的条件编译，则在编译的时候会有警告和报错信息。

如果当前编译的目标平台是 wx，以下写法 open-type 属性将被忽略

```html
<button open-type@swan:didi="getUserInfo">获取用户信息</button>
```

如果当前 env 不是 didi，以下写法 open-type 属性也会被忽略

```html
<button open-type@:didi="getUserInfo">获取用户信息</button>
```

如果只想在 mode 为 wx 且 env 为 didi 或 qingju 的环境下使用 open-type 属性，则可以这样写：

```html
<button open-type@wx:didi:qingju="getUserInfo">获取用户信息</button>
```

env 属性维度的编译同样支持对整个节点或者节点标签名进行条件编译：

```html
<view @:didi>this is a  view component</view>
<view mpxTagName@:didi="cover-view">this is a  view component</view>
```

如果只声明了 env，没有声明 mode，跨平台输出时框架对于节点属性默认会进行转换：

```html
<!--srcMode为wx，跨平台输出ali时，bindtap会被转为onTap-->
<view @:didi bindtap="someClick">this is a  view component</view>
<view bindtap@:didi ="someClick">this is a  view component</view>
```

### 其他注意事项 {#other-notes}

* 当目标平台为支付宝时，需要启用支付宝最新的component2编译才能保障框架正常工作，关于component2[点此查看详情](https://docs.alipay.com/mini/framework/custom-component-overview)；
* 跨平台源码中自定义组件的标签名不能使用驼峰形式`myComponent`，请使用横杠形式`my-component`来书写；
* 生成的目标代码中文件名和文件夹名不能带有`@`符号，目前媒体文件和原生自定义组件在编译时不会修改文件名，需要重点关注。

## 跨平台输出web {#cross-platform-web}

从2.3.0版本开始，Mpx开始支持将已有项目跨平台输出web平台中运行的能力，目前输出web能力完备，能够支持直接转换大型复杂项目，我们会持续对输出web的能力进行优化，不断的建全更全面的适用范围和开发体验。

### 技术实现 {#tech-implementation}

与小程序平台间的差异相比，web平台和小程序平台间的差异要大很多，小程序相当于是基于web技术的上层封装，所以不同于我们跨平台输出其他小程序平台时以编译转换为主的思路，在输出web时，我们更多地采用了封装的方式来抹平组件/Api和底层环境的差异，与当前大部分的跨平台框架相仿。但与当前大部分跨平台框架以web MVVM框架为base输出到小程序上运行的思路不同，我们是以Mpx小程序增强语法为基础输出到web中运行，前面说过小程序本身是基于web技术进行的实现，小程序->web的转换在可行性和兼容性上会好一些。

在具体实现上，Mpx项目输出到web中运行时在组件化和路由层面都是基于Vue生态实现，所以可以将Mpx的跨端输出产物整合到既有的Vue项目中，或者在条件编译中直接使用Vue语法进行web端的实现。

### 使用方法 {#usage-1}

使用@mpxjs/cli创建新项目时选择跨平台并选择输出web后，即可生成可输出web的示例项目，运行`npm run build:web`，就会在dist/web下输出构建后的web项目，并启动静态服务预览运行。

### 支持范围 {#support-scope}

目前对输出web的通用能力支持已经非常完备，下列表格中显示了当前版本中已支持的能力范围

#### 模板指令 {#template-directives}

指令名称|是否支持
:----|----
Mustache数据绑定|是
wx:for|是
wx:for-item|是
wx:for-index|是
wx:key|是
wx:if|是
wx:elif|是
wx:else|是
wx:model|是
wx:model-prop|是
wx:model-event|是
wx:model-value-path|是
wx:model-filter|是
wx:class|是
wx:style|是
wx:ref|是
wx:show|是

#### 事件绑定方式 {#event-binding}

绑定方式|是否支持
:----|----
bind|是
catch|是
capture-bind|是
capture-catch|是

#### 事件名称 {#event-name}

事件名称|是否支持
:----|----
tap|是
longpress|是
longtap|是

web同名事件默认全部支持，已支持组件的特殊事件默认为支持，不支持的情况下会在编译时抛出异常

#### 基础组件 {#basic-components}

组件名称|是否支持|说明
:----|---- |----
audio|是
block|是
button|是
canvas|是
checkbox|是
checkbox-group|是
cover-view|是
form|是
image|是
input|是
movable-area|是
movable-view|是
navigator|是
picker|是
picker-view|是
progress|是
radio|是
radio-group|是
rich-text|是
scroll-view|是|scroll-view 输出 web 底层滚动依赖 [BetterScroll](https://better-scroll.github.io/docs/zh-CN/guide/base-scroll-options.html) 实现，支持额外传入以下属性： `scroll-options`: object 可重写 BetterScroll 初始化基本配置若出现无法滚动，可尝试手动传入 `{ observeDOM: true }`  `update-refresh`: boolean Vue updated 钩子函数触发时，可用于重新计算 BetterScrolltips: 当使用下拉刷新相关属性时，由于 Vue 数据响应机制的限制，在 web 侧可能出现下拉组件状态无法复原的问题，可尝试在 `refresherrefresh` 事件中，手动将 refresher-triggered 属性值设置为 true
swiper|是|swiper 输出 web 底层滚动依赖 [BetterScroll](https://better-scroll.github.io/docs/zh-CN/guide/base-scroll-options.html) 实现，支持额外传入以下属性： `scroll-options`: object 可重写 BetterScroll 初始化基本配置当滑动方向为横向滚动，希望在另一方向保留原生的滚动时，scroll-options 可尝试传入 `{ eventPassthrough: vertical }`，反之可将 eventPassthrough 设置为 `horizontal`
swiper-item|是
switch|是
slider|是
text|是
textarea|是
video|是
view|是
web-view|是
在项目的app.json 中配置 "style": "v2"启用新版的组件样式，涉及的组件有 button icon radio checkbox switch slider在输出web时也与小程序保持了一致

#### 生命周期 {#lifecycle}

生命周期名称|是否支持
:----|----
onLaunch|是
onLoad|是
onReady|是
onShow|是
onHide|是
onUnload|是
onError|是
onServerPrefetch|是
created|是
attached|是
ready|是
detached|是
updated|是
serverPrefetch|是

#### 应用级事件 {#app-events}

应用级事件名称|是否支持
:----|----
onPageNotFound|是
onPageScroll|是
onPullDownRefresh|是
onReachBottom|是
onResize|是
onTabItemTap|是

#### 组件配置 {#component-config}

配置项|支持度
:----|----
properties|部分支持，observer不支持，请使用watch代替
data|支持
watch|支持
computed|支持
relations|支持
methods|支持
mixins|支持
pageLifetimes|支持
observers|不支持，请使用watch代替
behaviors|不支持，请使用mixins代替

#### 组件API {#component-api}

api名称|支持度
:----|----
triggerEvent|支持
$nextTick|支持
createSelectorQuery/selectComponent|支持

#### 全局API {#global-api}

api名称|支持度
:----|----
navigateTo|支持
navigateBack|支持
redirectTo|支持
request|支持
connectSocket|支持
SocketTask|支持
EventChannel|支持
createSelectorQuery|支持
base64ToArrayBuffer|支持
arrayBufferToBase64|支持
nextTick|支持
set|支持
setNavigationBarTitle|支持
setNavigationBarColor|支持
setStorage|支持
setStorageSync|不支持，请使用 setStorage
getStorage|支持
getStorageSync|不支持，请使用 getStorage
getStorageInfo|支持
getStorageInfoSync|不支持，请使用 getStorageInfo
removeStorage|支持
removeStorageSync|不支持，请使用 removeStorage
clearStorage|支持
clearStorageSync|不支持，请使用 clearStorage
getSystemInfo|支持
getSystemInfoSync|支持
showModal|支持
showToast|支持
hideToast|支持
showLoading|支持
hideLoading|支持
onWindowResize|支持
offWindowResize|支持
createAnimation|支持

#### JSON配置 {#json-config}

配置项|是否支持
:----|----
backgroundColor|是
backgroundTextStyle|是
disableScroll|是
enablePullDownRefresh|是
onReachBottomDistance|是
packages|是
pages|是
navigationBarBackgroundColor|是
navigationBarTextStyle|是
navigationBarTitleText|是
networkTimeout|是
subpackages|是
tabBar|是
usingComponents|是

#### 拓展能力 {#extended-abilities}

能力|是否支持
:---|---
fetch|是
i18n|是

#### 小程序其他原生能力 {#other-native-abilities}

能力|支持度
:---|---
wxs|支持
animation|支持组件的animation属性，支持所有animation对象方法(export、step、width、height、rotate、scale、skew、translate等等)

---

---
url: /articles/2.8-release-alter.md
---
# 通过 Mpx 使用组合式 API 进行小程序开发

滴滴开源小程序跨端框架 [Mpx](https://www.mpxjs.cn/) 自18年立项开源以来，如今已经进入第五个年头，期间 Mpx 在有效支持了公司内外小程序业务开发的同时，也因其高性能、优体验、跨平台的特性获得了开发者用户的一致好评。

为了不辜负开发者用户对我们的信赖，更好地支持小程序业务开发，一方面我们对 Mpx 的稳定版本进行着高频的维护迭代，快速响应处理开发者用户在框架使用过程中遇到的问题；另一方面我们持续跟进探索业内最新动态，力求带给用户更好的开发体验与更强大的开发能力。继我们在 [2.7 版本](../guide/migrate/2.7.md)中对 Mpx 的编译系统进行 Webpack5 适配 ，完整支持持久化缓存并大幅提升编译速度后，在 [2.8 版本](../guide/migrate/2.8.md)中，我们对 Mpx 的框架运行时也进行了重构改造，完整支持 Vue3 中的组合式 API 开发范式，让用户能够使用时下最热门的开发方式进行小程序业务开发。

我们先来简单感受一下组合式 API 的使用：

```html
<template>
  <view>{{ collectionName }}: {{ book.title }}({{ readersNumber }})</view>
  <button bindtap="addReaders">addReaders</button>
</template>

<script>
  import { createComponent, ref, reactive, onMounted } from '@mpxjs/core'

  createComponent({
    properties: {
      collectionName: String
    },
    setup () {
      const readersNumber = ref(0)
      const book = reactive({ title: 'Mpx' })

      onMounted(() => {
        console.log('Component mounted.')
      })

      // 暴露给 template
      return {
        readersNumber,
        book,
        addReaders () {
          readersNumber.value++
        }
      }
    }
  })
</script>
```

可以看出和 Vue3 组合式 API 的使用是高度类似的，利用框架导出的一系列响应式 API 和 生命周期钩子函数在 `setup` 中编写业务逻辑，并将模板依赖的数据与方法作为返回值返回，与传统的选项式 API 相比，组合式 API 具备以下优势：

* 更好的逻辑复用，通过函数包装复用逻辑，显式引入调用，方便简洁且符合直觉，规避消除了 mixins 复用中存在的缺陷；
* 更灵活的代码组织，相比于选项式 API 提前规定了代码的组织方式，组合式 API 在这方面几乎没有做任何限制与规定，更加灵活自由，在功能复杂的庞大组件中，我们能够通过组合式 API 让我们的功能代码更加内聚且有条理，不过这也会对开发者自身的代码规范意识提出更高要求；
* 更好的类型推导，虽然基于 `this` 的选项式 API 通过 `ThisType` 类型体操的方式也能在一定程度上实现 TS 类型推导，但推导和实现成本较高，同时仍然无法完美覆盖一些复杂场景（如嵌套 mixins 等）；而组合式 API 以本地变量和函数为基础，本身就是类型友好的，我们在类型方面几乎不需要做什么额外的工作就能享受到完美的类型推导。

同时与 React Hooks 相比，组合式 API 中的 `setup` 函数只在初始化时单次执行，在数据响应能力的加持下大大降低了理解与使用成本，基于以上原因，我们决定为 Mpx 添加组合式 API 能力，让用户能够用组合式 API 方式进行小程序开发。

## 组合式 API 实现

从上面的简单示例中可以看出，抛开响应式 API 和生命周期注册模式的变化，组合式 API 的实现要点在于动态添加模板依赖的数据和方法，这也是我们在小程序中实现组合式 API 可能遇到的核心技术卡点。

对于动态添加模板依赖数据，我们在过去的实践中已经充分证明了其可行性，事实上，从 Mpx 最初的版本开始，我们就充分利用了这项能力来实现我们对计算属性和 `dataFn` （类似于 Vue 使用函数定义 `data`）的支持，这项能力的关键在于存在合适的生命周期用于动态添加初始化数据，这里对于初始化数据的定义是能够影响组件树的初始渲染，举个简单的例子：存在一对父子组件 parent/child，parent 使用 `props` 向 child 传递数据，当我们在 parent 初始创建时使用 `setData` 动态添加 `props` 数据，同时 child 在初始创建时能够通过 `props` 正确获取到这部分的数据时，我们就可以将这部分动态添加的数据视作初始化数据，这是我们在小程序中实现完备数据响应支持的基础。

幸运的是，目前业内所有主流小程序平台（微信/支付宝/百度/字节/QQ）都支持了上述能力，微信从一开始就支持在 `attached` 生命周期中调用 `setData` 函数动态添加初始化数据，在上述的父子 `props` 传递场景中，也能够在子组件的 `attached` 中正确获取这部分数据，支付宝和字节小程序一开始并不支持该能力，不过支付宝在 `component2` 组件系统重构后，字节在橙心合作项目中与我们沟通后，都成功支持了该能力。

而对于动态返回的方法，最简单能想到的方案就是直接挂载到组件实例上，经过我们的完整测试，上述业内主流小程序平台都支持使用这种方式动态添加方法，基于以上事实，我们非常确定组合式 API 能够在小程序环境中顺利实现，下图简要展示了 Mpx 支持组合式 API 的初始化流程：

![composition-api-init](https://dpubstatic.udache.com/static/dpubimg/0bxxw8bB9PJxXLeiMQ__6_composition-api-init.png)

### 生命周期钩子函数

在组合式 API 中，`setup` 函数只有在组件创建时初始化单次执行，因此需要提供一系列生命周期钩子函数来代替选项式 API 中的生命周期钩子选项，由于小程序原生只支持选项式的生命周期注册方式，我们通过`预注册 -> 驱动`的方式来实现 `setup` 中函数式注册生命周期钩子的语法糖，简单来讲就是使用选项式 `mixins` 的方式提前注册所有需要的生命周期钩子，在选项式生命周期钩子执行时驱动对应在 `setup` 中使用生命周期钩子函数注册的代码逻辑执行，如下图所示：

![composition-api-hook](https://dpubstatic.udache.com/static/dpubimg/2nmOjxvubyk6H32yP5cFc_composition-api-hook.png)

作为跨端小程序框架，Mpx 需要兼容不同小程序平台不同的生命周期，在选项式 API 中，我们在框架中内置了一套统一的生命周期，将不同小程序平台的生命周期转换映射为内置生命周期后再进行统一的驱动，以抹平不同小程序平台生命周期钩子的差异，如微信小程序的 `attached` 钩子和支付宝小程序的 `onInit` 钩子，在组合式 API 中，我们沿用了同样的逻辑，设计了一套与框架内置生命周期对应的生命周期钩子函数，以相同的方式进行驱动，因此这些生命周期钩子函数天然具备了跨平台特性，下表显示了在组件 / 页面中框架生命周期与原生平台生命周期的对应关系：

|框架内置生命周期|Hooks in `setup`|微信原生|支付宝原生|
|:------------|:------------------|:-----|:-------|
| BEFORECREATE | `null` |attached（数据响应初始化前）|onInit（数据响应初始化前）|
| CREATED | `null` |attached（数据响应初始化后）|onInit（数据响应初始化后）|
| BEFOREMOUNT | onBeforeMount |ready（`MOUNTED` 执行前）|didMount（`MOUNTED` 执行前）|
| MOUNTED | onMounted |ready（`BEFOREMOUNT` 执行后）|didMount（`BEFOREMOUNT` 执行后）|
| BEFOREUPDATE | onBeforeUpdate |`null`（`setData` 执行前）|`null`（`setData` 执行前）|
| UPDATED | onUpdated |`null`（`setData` callback）|`null`（`setData` callback）|
| BEFOREUNMOUNT | onBeforeUnmount |detached（数据响应销毁前）|didUnmount（数据响应销毁前）|
| UNMOUNTED | onUnmounted |detached（数据响应销毁后）|didUnmount（数据响应销毁后）|
| ONLOAD | onLoad |onLoad|onLoad|
| ONSHOW | onShow |onShow|onShow|
| ONHIDE | onHide |onHide|onHide|
| ONRESIZE | onResize |onResize|events.onResize|

> 同 Vue3 一样，Mpx 在组合式 API 中没有提供 `BEFORECREATE` 和 `CREATED` 对应的生命周期钩子函数，用户可以直接在 `setup` 中编写相关逻辑。

#### 具有副作用的页面事件

在小程序中，一些页面事件的注册存在副作用，即该页面事件注册与否会产生实质性的影响，比如微信中的 `onShareAppMessage` 和 `onPageScroll`，前者在不注册时会禁用当前页面的分享功能，而后者在注册时会带来视图与逻辑层之间的线程通信开销，对于这部分页面事件，我们无法通过`预注册 -> 驱动`方式提供组合式 API 的注册方式，用户可以通过选项式 API 的方式来注册使用，通过 `this` 访问组合式 API `setup` 函数的返回。

然而这种使用方式显然不够优雅，我们考虑是否可以通过一些非常规的方式提供这类副作用页面事件的组合式 API 注册支持，例如，借助编译手段。我们在运行时提供了副作用页面事件的注册函数，并在编译时通过 `babel` 插件的方式解析识别到当前页面中存在这些特殊注册函数的调用时，通过框架已有的`编译 -> 运行时注入`的方式将事件驱动逻辑添加到当前页面当中，以提供相对优雅的副作用页面事件在组合式 API 中的注册方式，同时不产生非预期的副作用影响，简单示例如下：

```js
import { createPage, ref, onShareAppMessage } from '@mpxjs/core'

createPage({
  setup () {
    const count = ref(0)

    onShareAppMessage(() => {
      return {
        title: '页面分享'
      }
    })

    return {
      count
    }
  }
})
```

目前我们通过这种方式支持的页面事件如下：

| 页面事件 | Hooks in `setup` | 平台支持 |
|:------------|:------------------|:-----|
| onPullDownRefresh | onPullDownRefresh | 全小程序平台 + web |
| onReachBottom | onReachBottom | 全小程序平台 + web |
| onPageScroll | onPageScroll | 全小程序平台 + web |
| onShareAppMessage | onShareAppMessage | 全小程序平台 |
| onTabItemTap | onTabItemTap | 微信/支付宝/百度/QQ |
| onAddToFavorites | onAddToFavorites | 微信 / QQ |
| onShareTimeline | onShareTimeline | 微信 |
| onSaveExitState | onSaveExitState | 微信 |

> **特别注意**，由于静态编译分析实现方式的限制，这类页面事件的组合式 API 使用需要满足页面事件注册函数（如`onShareAppMessage`）的调用和 `createPage` 的调用位于同一个 js 文件当中。

关于生命周期钩子函数的更多信息可以查看[这里](../guide/composition-api/composition-api.md#lifecycle-hooks)。

### `<script setup>`

同 Vue3 一样，我们在 `.mpx` 单文件组件 / 页面中实现了 `<script setup>` 的组合式 API 编译语法糖，相较于常规的写法，`<script setup>` 具备以下优势：

* 更少的样板内容，更简洁的代码
* 能够使用纯 TypeScript 声明 props 类型
* 更好的 IDE 类型推导性能

简单使用示例如下：

```html
<script setup>
  import { ref } from '@mpxjs/core'

  const msg = ref('hello')

  function log () {
    console.log(msg.value)
  }
</script>
<template>
  <view>msg: {{msg}}</view>
  <view ontap="log">click</view>
</template>
```

可以看到使用方式与 Vue3 基本一致，不过由于 Mpx 的组合式 API 设计实现与 Vue3 存在差异，对应 `<script setup>` 也与 Vue3 中存在一些差异：

* 不支持 `import` 快捷注册组件
* 没有 `defineEmits()` 编译宏
* 没有 `useSlots()` 和 `useAttrs()` 运行时函数
* 以编译宏的形式提供了 `useContext()`，获取 `setup` 函数的第二个参数 `context`
* `defineExpose()` 编译宏的作用与 Vue3 中有所差别，能够限定模板中能访问的变量范围

> **特别注意**，受小程序底层技术限制，我们在 Mpx 的实现中无法像 Vue3 那样将模板编译的渲染函数和 `<script setup>` 放置到同一作用域下进行变量访问，而是通过静态编译分析提取出 `<script setup>` 的顶层作用域变量，再以上文中提到的动态添加数据与方法的方式将其设置到模板当中，如果 `<script setup>` 中声明了较多顶层作用域变量，它们并不一定都会被模板访问，就会带来无效的性能开销，因此我们强烈建议使用 `defineExpose()` 限定模板中能访问的变量范围，你可以把它等同于 `setup` 函数中的 `return`。

关于 `<script setup>` 的更多信息可以查看[这里](../guide/composition-api/composition-api.md#script-setup)。

### 组合式 API 与 Vue3 中的差异

我们来总结一下 Mpx 中组合式 API 与 Vue3 中的区别：

* `setup` 的 `context` 参数不同，详见[这里](../guide/composition-api/composition-api.md#context)
* `setup` 不支持返回**渲染函数**
* `setup` 不能是异步函数
* `<script setup>` 提供的宏方法不同，详见[这里](../guide/composition-api/composition-api.md#script-setup)
* `<script setup>` 不支持 `import` 快捷注册组件
* 支持的生命周期钩子不同，详见[这里](../guide/composition-api/composition-api.md#lifecycle-hooks)
* 模板引用的方式不同，详见[这里](../guide/composition-api/composition-api.md#template-ref)

关于组合式 API 的更多信息可以查看[这里](../guide/composition-api/composition-api.md)。

## 响应式 API 实现

组合式 API 的正常工作离不开响应式 API 的支持，下面我们来聊聊 Mpx 中响应式 API 的设计实现。我们知道 Vue3 中响应式 API 基于 `proxy` 进行了重构实现，但是目前 `proxy` 的浏览器兼容占比仍然无法达到我们对于线上可用性的要求，因此在 Mpx 中，我们仍然基于 `Object.defineProperty` 进行核心数据响应能力的实现，同时借鉴了 Vue3 中优秀的代码设计与实现，如 `reactiveEffect` 和 `effectScope` 等，尽可能实现与 Vue3 中响应式 API 能力对齐。

说到这里，很多同学可能会想到 `@vue/composition-api` 这个库，该库提供的关键能力正是基于 Vue2 的数据响应系统模拟实现 Vue3 中的响应式 API，我们在前期也对 `@vue/composition-api` 在 Mpx 中的复用进行了非常有价值的探索尝试。不过最终我们还是决定在 Mpx 的运行时框架中进行独立实现，原因主要在于：`@vue/composition-api` 是作为一个 Vue2 插件存在，无法直接侵入 Vue2 源码，导致部分能力无法实现或会带来额外的性能开销，例如 `flush: 'post'` 和 `ref` 自动解包等。我们也看到在最新的 Vue2.7 版本中，也是在运行时框架里重新实现了这部分内容，以规避上述问题。

下图展示了 Mpx 中响应式 API 核心模块依赖关系：

![composition-api-reactive](https://dpubstatic.udache.com/static/dpubimg/4ySdEqTRhc_DRWWCJWrhJ_composition-api-reactive.png)

### 数据响应限制带来的差异

由于 `Object.defineProperty` 的能力限制，Mpx 存在和 Vue2 一致的数据响应限制，无法感知到对象 property 的添加和删除以及数组的索引赋值，与 Vue2 一致，我们暴露了 `set` 和 `del` API 来让用户显式地进行相关操作。除此之外，由于使用方式发生了变化，我们在使用 `reactive` API 创建响应式数据时，还会遇到新的限制，我们来看一下代码示例：

```js
import { reactive, watchSyncEffect, set } from '@mpxjs/core'

const state = reactive([0, 1, 2, 3])

watchSyncEffect(() => {
  console.log(JSON.stringify(state)) // [0,1,2,3]
})

set(state, 1, 3) // 不会触发 watchEffect

state.push(4) // 不会触发 watchEffect
```

可以看出，即使我们使用了 `set` API 和数组原型方法对数组进行修改，我们仍然无法监听到数据变化。

> 相同的限制在使用 `Object.defineProperty` 的 Vue2.7 中也同样存在。

为什么会存在这个限制呢？原因在于：基于 `Object.defineProperty` 实现的数据响应系统中，我们会对对象的每个已有属性创建了一个 `Dep` 对象，在对该属性进行 `get` 访问时通过这个对象将其与依赖它的观察者 `ReactiveEffect` 关联起来，并在 `set` 操作时触发关联 `ReactiveEffect` 的更新，这是我们大家都知道的数据响应的基本原理。但是对于新增/删除对象属性和修改数组的场景，我们无法事先定义当前不存在属性的 `get/set` (当然这在 `proxy` 当中是可行的)，因此我们会把对象或者数组本身作为一个数据依赖创建 `Dep` 对象，**通过父级访问**该数据时定义的 `get/set` 将其关联到对应的 `ReactiveEffect`，并在对数据进行新增/删除属性或数组操作时通过数据本身持有的 `Dep` 对象触发关联 `ReactiveEffect` 的更新，如下图所示：

![数据响应原理](https://dpubstatic.udache.com/static/dpubimg/XkI9cQBsLy_7np-T3rt56_composition-api-reactive2.png)

需要注意的是，**通过父级访问**是建立 `Dep` 与 `ReactiveEffect` 关联关系的先决条件，在选项式 API 中，我们访问组件的响应式数据都需要通过 `this` 进行访问，相当于这些数据都存在 `this` 这个必要的**父级**，因此我们在使用 `$set/$delete` 进行对对象进行新增/删除属性或对数组进行修改时都能得到符合预期的结果，唯一的限制在于不能新增/删除根级数据属性，原因就在于 `this` 不存在访问它的父级。

但是在组合式 API 中，我们不需要通过 `this` 访问响应式数据，因此通过 `reactive()` 创建的响应式数据本身就是根级数据，我们自然无法通过上述方式感知到根级数据自身的变化（在 Vue3 中，基于 `proxy` 提供的强大能力响应式系统能够精确地感知到数据属性，甚至是当前不存在属性的访问与修改，不需要为数据自身建立 `Dep` 对象，自然也不存在相关问题）。

在这种情况下，我们就需要用 `ref()` 创建响应式数据，因为 `ref` 创建了一个包装对象，我们永远需要通过 `.value` 来访问其持有的数据（不管是显式访问还是隐式自动解包），这样就能保证 `ref` 数据自身的变化能够被响应式系统感知，因此也不会遇到上面描述的问题，如下所示：

```js
import { ref, watchSyncEffect, set } from '@mpxjs/core'

const state = ref([0, 1, 2, 3])

watchSyncEffect(() => {
  console.log(JSON.stringify(state.value)) // [0,1,2,3]
})

set(state.value, 1, 3) // [0,3,2,3]

state.value.push(4) // [0,3,2,3,4]
```

### 响应式 API 与 Vue3 中的区别

我们来总结一下 Mpx 中响应式 API 与 Vue3 中的区别：

* 不支持 `raw` 相关 API（`markRaw` 除外，我们提供了该 API 用于跳过部分数据的响应式转换）
* 不支持 `readonly` 相关 API
* 不支持 `watchEffect`、`watch`、`computed` 的调试选项
* 不支持对 `map`、`set` 等集合类型进行响应式转换
* 受到 `Object.defineProperty` 实现带来的数据响应限制影响

关于响应式 API 的更多信息可以查看[这里](../guide/composition-api/reactive-api.md)。

## 生态周边适配

除了 Mpx 运行时核心提供了组合式 API 支持外，我们对 Mpx 的周边生态能力也都进行了组合式 API 适配支持，包括 `store`、`i18n`、`fetch` 等。

### Pinia store 支持

Pinia 是基于组合式 API 设计的全新数据管理方案，目前已经取代 Vuex 成为 Vue3 官方推荐的 store，我们在研究了 pinia 的设计实现后，对其简练优雅的设计思想及其与组合式 API 的高度适配非常满意（特别是在使用 `setup` 函数创建 store 时，使用心智与编写组件完全一致，可以将其视作是没有视图的组件）。因此我们 fork 了 pinia 的源码仓库，基于 Mpx 提供的数据响应能力对其进行了适配改造，使其在 Mpx 环境下也能正常运行，目前相关代码维护在 `@mpxjs/pinia` 中，在组合式 API 中的简单使用示例如下：

```js
import { createComponent, ref, computed, toRefs } from '@mpxjs/core'
import { defineStore } from '@mpxjs/pinia'

// 使用组合式 API 创建 pinia store 的使用心智与 setup 函数完全一致，强烈推荐
const useSetupStore = defineStore('setup', () => {
  const count = ref(0)
  const doubleCount = computed(() => count.value * 2)

  function increment () {
    count.value++
  }

  return { count, doubleCount, increment }
})

createComponent({
  setup () {
    const store = useSetupStore()
    // store 同 props 类似是一个 reactive 对象，解构数据需使用 toRefs 以保持数据响应性
    const { count, doubleCount } = toRefs(store)
    // 方法可以直接解构
    const { increment } = store
  
    return { count, doubleCount, increment }
    //
  }
})
```

Mpx 中通过 `createStore` 创建的类 Vuex store 在组合式 API 中仍然可以使用，我们可以在 `setup` 函数中引用 store 实例进行[数据读取与方法调用](../guide/advance/store.md#use-store-in-composition-api)，不过整体使用体验与 pinia store 存在较大差距，我们还是推荐在组合式 API 开发中优先使用 pinia store 作为数据管理方案。

### I18n 支持

传统选项式 API 中，我们使用 `this.$t` 方法在组件内调用翻译函数，但在组合式 API 中我们无法访问 `this`，为此我们参考了 Vue I18n 最新的 9.x 版本，该版本针对 Vue3 及组合式 API 进行了重构适配，提供了全新的 `useI18n` API，简单使用示例如下：

```html
<template>
  <view>{{t('message.hello')}}</view>
  <button bindtap="changeLocale">change locale</button>
</template>

<script>
  import { createComponent, useI18n } from '@mpxjs/core'

  createComponent({
    setup () {
      // useI18n 不传参数时指向全局 i18n 对象，也可以传递 locale 和 messages 配置创建局部 i18n 对象
      const { t, locale } = useI18n()

      function changeLocale () {
        locale.value = locale.value === 'zh-CN' ? 'en-US' : 'zh-CN'
      }
      // 返回的翻译方法名必须为 t，不能进行重命名
      return { t, changeLocale }
    }
  })
</script>
```

> 上面示例代码看上去像是我们在模板上直接调用 setup() 返回的 t 翻译方法，但是熟悉小程序开发的同学都知道在小程序架构下这是不可能的，示例中的写法其实由框架通过编译 + 运行时手段实现的语法糖，我们会在模板编译时定向扫描 t/te/tm 等 i18n 方法，将其转换为计算属性注入到运行时当中，这就意味着如果我们对翻译方法进行重命名，模板编译时无法识别出 i18n 方法调用，自然也就无法正常运行。

Mpx 中 i18n 提供了两种实现模式，分别是 wxs 和 computed，可以使用编译选项中的 `i18n.isComputed` 进行切换，两种方式各有优劣，其中：

* wxs 模式的优势在于逻辑层和视图层独立维护语言集，无额外运行时性能开销，且使用没有任何限制；劣势同样源于语言集同时存在于逻辑层（js）和视图层（wxs）当中，这部分的包体积占用翻倍；
* computed 模式的优势在于语言集只存在于逻辑层中，无额外包体积占用，且可以通过动态添加语言集的方式进一步减少包体积占用；劣势则是会产生额外的运行时性能开销，且使用上存在限制，模板调用时无法直接访问 `wx:for` 中的 `item` 和 `index`。

在组合式 API 中模板上使用 `useI18n()` 返回的翻译函数 `t/te/tm` 时，为了完整实现 `useI18n` API的功能，会强制使用 computed 模式进行实现，这也意味着该用法会受到 computed 模式使用限制的影响。不过当你不需要使用 `useI18n` 接受 `messages` 参数创建局部语言集作用域功能时，你也完全可以在模板中继续使用原有的 `$t/$tc/$te/$tm` 方法，这些方法受编译选项 `i18n.isComputed` 的影响，同时指向全局语言集作用域。

更多关于生态周边的组合式 API 使用指南可以点击下方链接查看详情：

* [store](../guide/advance/store.md#use-store-in-composition-api)
* [i18n](../guide/advance/i18n.md#composition-api-usage)
* [fetch](../guide/extend/fetch.md#composition-api-usage)

## 输出 web 适配

跨端输出 web 作为 Mpx 的一大核心特性，在业务中存在广泛使用，同时也是我们设计实现任何框架新特性需要优先考虑的事项。在本次组合式 API 支持中，我们从设计之初就考虑了跨端输出 web 的适配支持，保障使用 Mpx 组合式 API 开发的业务代码都能在 web 环境中正常运行。

我们输出 web 的整体技术方向在于尽可能复用 Vue 已有的生态能力，为了实现这个目标，我们需要提供尽可能与 Vue 保持一致的 API 设计，以降低抹平适配成本。在输出 web 时，核心组合式 API 基于 Vue2.7 版本中的已有能力进行适配提供，简单举个例子：对于 `import { ref } from 'mpxjs/core'` 这行语句，在小程序中会指向 Mpx 内部维护的 `ref` 实现，而在输出 web 时会指向 Vue 中维护的 `ref` 实现，两者的实现虽然不仅相同，但只要保障对外函数签名一致，对于开发者用户来说就无感知。

我们借助了 Mpx 强大的条件编译能力进行上述实现，对运行时导出根据输出平台进行重定向，这样还能保障跨端输出产物干净简洁，仅包含当前输出环境下必要的逻辑，如下图所示：

![composition-api-web](https://dpubstatic.udache.com/static/dpubimg/E0FojaPKOxZOa5h5OEPQk_composition-api-web.png)

同理，我们也采用了类似的方式实现了组合式 API 周边能力对于输出 web 的适配支持，如pinia store 使用 pinia 原始版本进行适配实现，而 i18n 能力则是使用 vue-i18n@8.x + vue-i18n-bridge 进行适配实现。

## 性能表现

性能是 Mpx 一直以来的核心关注点，我们对组合式 API 的最终实现版本进行了一系列性能评估测试，我们使用组合式 API 版本对业务中的评价组件进行了重构，评价组件属于我们业务中交互及功能相对比较复杂的组件，源码行数约 1000 行，组件数据 27 项，组件方法 18 个，我们在测试项目中对选项式 API 和组合式 API 两个版本实现的组件进行了一系列测试。

### 组件初始化耗时

由于组合式 API 改变了原有的组件初始化流程，我们对组件的初始化耗时进行了重点测试，测试口径如下：

* 耗时计算以挂载组件为起点，以组件 `ready` 执行为终点
* 测试结果为10次手工测试排除最大最小值后求均值
* IOS 测试机型为 iPhone 13 pro max，安卓测试机型为 OPPO R9

结果显示两个版本的组件初始化耗时大抵持平，不分优劣。

|    |IOS  |安卓  |
|----|-----|-----|
|选项式 API|42.5ms|366.6ms|
|组合式 API|42.4ms|370.1ms|

### 组件 JS 体积

在构建产物体积方面，由于组合式 API 的写法对于 JS 代码压缩更加有利，同样的逻辑实现下，组合式 API 版本的组件构建压缩后 JS 体积略胜一筹。

|    |组件 JS 体积|
|----|-----|
|选项式 API|15.67KB|
|组合式 API|13.60KB|

### 框架运行时体积 {#framework-runtime-size}

在 Mpx2.8 版本中，我们在框架运行时中新增了组合式 API 相关实现，不过通过优化运行时导出，使其对 tree shaking 更加友好，我们的框架运行时体积在实际构建产物中没有产生太大增长。

|    |框架运行时体积|
|----|-----|
|选项式 API|51.66KB|
|组合式 API|57.47KB|

综上所述，组合式 API 版本的运行时性能与选项式 API 大抵持平，在包体积占用方面，新版框架运行时体积占用略有提升，不过由于组合式 API 开发模式对代码压缩更友好，加上组合式 API 更易进行逻辑复用的特点，我们预计在实际业务项目中，组合式 API 的包体积占用会更小。

## 破坏性改变

Mpx 组合式 API 版本完全兼容原有的选项式 API 开发方式，不过我们在运行时重构过程中依然带来了少量的破坏性改变，详情如下：

* 框架过往提供的组件增强生命周期 `pageShow/pageHide` 与微信原生提供的 `pageLifetimes.show/hide` 完全对齐，不再提供组件初始挂载时必定执行 `pageShow` 的保障（因为组件可能在后台页面进行挂载），相关初始化逻辑一定不要放置在 `pageShow` 当中；
* 取消了框架过去提供的基于内部生命周期实现的非标准增强生命周期，如 `beforeCreate/onBeforeCreate` 等，直接将内部生命周期变量导出提供给用户使用，详情查看[这里](../api/global-api.md#built-in-lifecycle-variable);
* 为了优化 tree shaking，作为框架运行时 `default export` 的 `Mpx` 对象不再挂载 `createComponent/createStore` 等运行时方法，一律通过 `named export` 提供，`Mpx` 对象上仅保留 `set/use` 等全局 API，详情查看[这里](../api/global-api.md#global-mpx)；
* 使用 I18n 能力时，为了与新版 vue-i18n 保持对齐，`this.$i18n` 对象指向全局作用域，如需创建局部作用域需要使用组合式 API `useI18n` 的方式进行创建。
* `watch` API 不再接受第二个参数为带有 `handler` 属性的对象形式（该参数形式只应存在于 `watch` option 中），第二个参数必须为回调函数，与 [Vue](https://vuejs.org/api/reactivity-core.html#watch) 对齐。

更详细的迁移指南请点击查看[这里](../guide/migrate/2.8.md)。

## 未来规划 {#future-plan}

目前 Mpx2.8 版本已经在以滴滴出行小程序和花小猪小程序为代表的集团小程序业务中稳定全面落地，并在新的业务迭代中大范围使用了组合式 API，使用反馈良好，在社区内也产出了多个成功案例。

在完成持久化构建缓存和组合式 API 两个重大技术升级后，我们未来的技术规划如下：

* 组合式 API 工具库 @mpxjs/use
* 内置原子类支持
* 输出 web 支持 SSR
* 输出 web 支持使用 Vite 构建
* 跨端输出 Hummer 合入主干正式 release
* 优化运行时 render 函数，降低包体积占用
* 跨端库 @mpxjs/cube-ui 开源

最后，再次感谢所有参与 Mpx 组合式 API 技术建设的同学们，也欢迎社区同学一同加入 Mpx 项目开源共建。