ARTICLE · 1049025
uni-app 支持原生小程序自定义组件
前言
uni-app 除了支持 vue 组件之外，也实现了对原生小程序自定义组件的兼容。小程序组件不是 vue 组件，每家小程序都有自己的组件规范，比如微信小程序的组件是 wxml、wxss ，支付宝小程序是 axml、acss。
下面介绍如何在 uni-app 中使用原生小程序自定义组件。
创建自定义小程序目录
原生小程序自定义组件需要放在 uni-app 项目 根路径 的特定名称目录中，项目结构如下：
text
├── wxcomponents # 微信小程序自定义组件存放目录
│ └── counter # 微信小程序自定义组件
│ ├── index.js
│ ├── index.wxml
│ ├── index.json
│ └── index.wxss
├── mycomponents # 支付宝小程序自定义组件存放目录
│ └── counter # 支付宝小程序自定义组件
│ ├── index.js
│ ├── index.axml
│ ├── index.json
│ └── index.acss
├── pages
│ └── index
│ └── index.vue
├── static
├── main.ts
├── App.vue
├── manifest.json
└── pages.json
目录名可以参考下方表格
此文档要求开发者对各端小程序的自定义组件有一定了解，没接触过小程序自定义组件的可以参考：
•微信小程序自定义组件[1]
•支付宝小程序自定义组件[2]
使用组件
在需要使用自定义小程序组件的页面中，添加 usingComponents 配置。例如，在微信小程序中：
json
// pages.json
{
"pages": [
{
"path": "index/index",
"style": {
"navigationBarTitleText": "首页",
"usingComponents": {
"counter": "/wxcomponents/counter/index"
}
}
}
]
}
页面使用自定义小程序组件
html
<template>
<view>
<counter :title="title" @change="handleChange"></counter>
</view>
</template>
<script setup lang="ts">
const title = ref("自定义组件标题");
function handleChange() {
// 处理自定义组件的变化事件
}
</script>
通过 ref 调用组件方法
原生小程序组件可以在 methods 中定义需要暴露给页面调用的方法。例如，下面的计数器组件提供了 increment 和 decrement 方法：
js
// wxcomponents/counter/index.js
Component({
data: {
value: 0
},
methods: {
updateValue(nextValue) {
this.setData({ value: nextValue });
this.triggerEvent('change', { value: nextValue });
},
increment() {
this.updateValue(this.data.value + 1);
},
decrement() {
this.updateValue(this.data.value - 1);
}
}
});
在页面配置中将组件注册为 counter：
json
{
"usingComponents": {
"counter": "/wxcomponents/counter/index"
}
}
然后给组件添加 ref，组件渲染完成后即可通过 ref.value 调用原生组件方法：
html
<template>
<view>
<counter ref="nativeCounter"></counter>
<button @click="increment">增加</button>
<button @click="decrement">减少</button>
</view>
</template>
<script setup lang="ts">
const nativeCounter = ref(null);
function increment() {
nativeCounter.value?.increment();
}
function decrement() {
nativeCounter.value?.decrement();
}
</script>
ref 的值需要等组件渲染完成后才可用，因此调用方法时建议使用可选链 ?.。原生组件的方法必须定义在组件自身的 methods 中。
引用链接
[1] https://developers.weixin.qq.com/miniprogram/dev/framework/custom-component/
[2] https://docs.alipay.com/mini/framework/custom-component-overview