小程序自定义组件支持

uni-app 支持在 App 和 小程序 中使用小程序自定义组件，从HBuilderX2.4.7起，H5端也可以运行微信小程序组件。

小程序组件不是vue组件，并且每家小程序都有自己的组件规范，比如微信小程序的组件是wxml格式。

平台

支持情况

小程序组件存放目录

H5

支持微信小程序组件（2.4.7+）

wxcomponents

App（不含nvue）

支持微信小程序组件

wxcomponents

微信小程序

支持微信小程序组件

wxcomponents

支付宝小程序

支持支付宝小程序组件

mycomponents

百度小程序

支持百度小程序组件

swancomponents

字节跳动小程序

支持字节跳动小程序组件

ttcomponents

QQ小程序

支持QQ小程序组件

wxcomponents

快手小程序

支持快手小程序组件

kscomponents

┌─wxcomponents                  微信小程序自定义组件存放目录
│   └──custom                   微信小程序自定义组件
│        ├─index.js
│        ├─index.wxml
│        ├─index.json
│        └─index.wxss
├─mycomponents                  支付宝小程序自定义组件存放目录
│   └──custom                   支付宝小程序自定义组件
│        ├─index.js
│        ├─index.axml
│        ├─index.json
│        └─index.acss
├─swancomponents                百度小程序自定义组件存放目录
│   └──custom                   百度小程序自定义组件
│        ├─index.js
│        ├─index.swan
│        ├─index.json
│        └─index.css
├─pages
│  └─index
│        └─index.vue
│
├─static
├─main.js
├─App.vue
├─manifest.json
└─pages.json

使用方式

在 pages.json 对应页面的 style -> usingComponents 引入组件：

{
    "pages": [{
        "path": "index/index",
        "style": {
            // #ifdef APP-PLUS || H5 || MP-WEIXIN || MP-QQ
            "usingComponents": {
                "custom": "/wxcomponents/custom/index"
            },
            // #endif
            // #ifdef MP-BAIDU
            "usingComponents": {
                "custom": "/swancomponents/custom/index"
            },
            // #endif
            // #ifdef MP-ALIPAY
            "usingComponents": {
                "custom": "/mycomponents/custom/index"
            },
            // #endif
            "navigationBarTitleText": "uni-app"
        }
    }]
}
<view>
    <!-- 在页面中对自定义组件进行引用 -->
    <custom name="uni-app"></custom>
</view>

注意事项

  • 小程序组件需要放在项目特殊文件夹 wxcomponents（或 mycomponents、swancomponents）。HBuilderX 建立的工程 wxcomponents 文件夹在 项目根目录下。vue-cli 建立的工程 wxcomponents 文件夹在 src 目录下。可以在 vue.config.js 中自定义其他目录
  • 小程序组件的性能，不如vue组件。使用小程序组件，需要自己手动setData，很难自动管理差量数据更新。而使用vue组件会自动diff更新差量数据。所以如无明显必要，建议使用vue组件而不是小程序组件。比如某些小程序ui组件，完全可以用更高性能的uni ui替代。
  • 当需要在 vue 组件中使用小程序组件时，注意在 pages.json 的 globalStyle 中配置 usingComponents，而不是页面级配置。
  • 注意数据和事件绑定的差异，组件使用时应按照 vue 的数据和事件绑定方式
  • 属性绑定从 attr="{{ a }}"，改为 :attr=“a”；从 title=“复选框{{ item }}” 改为 :title="‘复选框’ + item"
  • 事件绑定从 bind:click=“toggleActionSheet1” 改为 @click=“toggleActionSheet1”，目前支付宝小程序不支持 vue 的事件绑定方式，具体参考：支付宝小程序组件事件监听示例
  • 阻止事件冒泡 从 catch:tap=“xx” 改为 @tap.native.stop=“xx”
  • wx:if 改为 v-if
  • wx:for="{{ list }}" wx:key="{{ index }}" 改为v-for="(item,index) in list"