微信小程序入门学习教程，从入门到精通，自定义组件与第三方 UI 组件库（以 Vant Weapp 为例） (16）

自定义组件与第三方 UI 组件库（以 Vant Weapp 为例）

适用于微信小程序开发

---

一、组件化开发

1.1 什么是组件化开发

组件化开发是将 UI 拆分为独立、可复用的模块（组件），每个组件拥有自己的结构（WXML）、样式（WXSS）、逻辑（JS）和配置（JSON）。组件之间通过 属性（properties）、事件（events） 和 插槽（slots） 进行通信。

1.2 组件化开发的优势

• 提高代码复用性
• 便于团队协作
• 降低维护成本
• 逻辑清晰，结构解耦

---

二、自定义组件

2.1 创建自定义组件

步骤：

1. 在项目中新建文件夹（如 components/my-button）
2. 创建四个文件：my-button.js、my-button.json、my-button.wxml、my-button.wxss

案例：自定义按钮组件

components/my-button/my-button.json

{"component": true,"usingComponents": {}
}

component: true 表示这是一个组件。

components/my-button/my-button.js

Component({// 组件属性定义properties: {text: {type: String,value: '默认按钮'},type: {type: String,value: 'primary' // primary / default}},// 组件内部数据data: {isClicked: false},// 组件方法methods: {handleClick() {this.setData({ isClicked: true });// 触发自定义事件，通知父组件this.triggerEvent('tap', { text: this.properties.text });}}
});

components/my-button/my-button.wxml

<view class="my-button {{type}} {{isClicked ? 'clicked' : ''}}" bindtap="handleClick"
>{{text}}
</view>

components/my-button/my-button.wxss

.my-button {padding: 10rpx 20rpx;border-radius: 8rpx;display: inline-block;text-align: center;
}.primary {background-color: #1989fa;color: white;
}.default {background-color: #f5f5f5;color: #333;
}.clicked {opacity: 0.7;
}

2.2 使用自定义组件

pages/index/index.json

{"usingComponents": {"my-button": "/components/my-button/my-button"}
}

pages/index/index.wxml

<view class="container"><my-button text="点击我" type="primary" bind:tap="onMyButtonTap"/>
</view>

pages/index/index.js

Page({onMyButtonTap(e) {console.log('按钮被点击，内容：', e.detail.text);}
});

---

三、Vant Weapp 组件库

3.1 安装 Vant Weapp

方法一：通过 npm（推荐）

1. 初始化 npm（如未初始化）：

   npm init -y
   

2. 安装 vant-weapp：

   npm i @vant/weapp -S --production
   

3. 微信开发者工具 → 工具 → 构建 npm

4. 勾选“使用 npm 模块”

方法二：手动下载（不推荐）

从 GitHub 下载 dist 目录，放入项目如 miniprogram_npm/@vant/weapp/

3.2 引入组件

pages/index/index.json

{"usingComponents": {"van-button": "@vant/weapp/button/index","van-cell": "@vant/weapp/cell/index","van-cell-group": "@vant/weapp/cell-group/index"}
}

---

四、Vant Weapp 核心组件介绍

4.1 Button 按钮

属性（properties）

• type: 按钮类型（primary / success / danger / default）
• loading: 是否加载中
• disabled: 是否禁用

事件（events）

• bind:click：点击事件

插槽（slots）

• 默认插槽：按钮内容

案例：

<van-button type="primary" bind:click="handleVantClick">Vant 按钮
</van-button>

Page({handleVantClick() {wx.showToast({ title: 'Vant 按钮被点击' });}
});

4.2 Cell 单元格

常用属性：

• title：左侧标题
• value：右侧内容
• is-link：是否展示右侧箭头

案例：

<van-cell-group><van-cell title="用户名" value="张三" /><van-cell title="设置" is-link bind:click="goToSetting" />
</van-cell-group>

---

五、组件的属性、事件与插槽

5.1 属性（Properties）

• 父组件通过属性向子组件传递数据
• 支持类型校验、默认值、观察器（observer）

示例：带 observer 的属性

properties: {count: {type: Number,value: 0,observer(newVal, oldVal) {console.log('count 从', oldVal, '变为', newVal);}}
}

5.2 事件（Events）

• 子组件通过 triggerEvent 触发事件
• 父组件通过 bind:eventName 监听

示例：

// 子组件
this.triggerEvent('change', { id: 123 });// 父组件
<my-component bind:change="handleChange" />

5.3 插槽（Slots）

• 默认插槽：<slot />
• 具名插槽：<slot name="header" />

子组件模板：

<view class="card"><slot name="header"></slot><slot></slot> <!-- 默认插槽 -->
</view>

父组件使用：

<my-card><view slot="header">标题</view><text>内容区域</text>
</my-card>

---

六、业务组件开发实践

场景：封装一个“用户信息卡片”业务组件

components/user-card/user-card.json

{"component": true,"usingComponents": {"van-button": "@vant/weapp/button/index"}
}

components/user-card/user-card.js

Component({properties: {avatar: String,name: String,level: {type: Number,value: 1}},methods: {onEdit() {this.triggerEvent('edit', { name: this.data.name });}}
});

components/user-card/user-card.wxml

<view class="user-card"><image class="avatar" src="{{avatar}}" mode="aspectFill" /><view class="info"><text class="name">{{name}}</text><text class="level">等级：{{level}}</text></view><van-button size="mini" bind:click="onEdit">编辑</van-button>
</view>

components/user-card/user-card.wxss

.user-card {display: flex;align-items: center;padding: 20rpx;border-bottom: 1rpx solid #eee;
}
.avatar {width: 80rpx;height: 80rpx;border-radius: 50%;margin-right: 20rpx;
}
.info {flex: 1;
}
.name {font-weight: bold;display: block;
}

父页面使用：

<user-cardavatar="/images/avatar.png"name="李四"level="5"bind:edit="handleEditUser"
/>

---

七、综合性案例：商品列表页（结合自定义组件 + Vant）

功能：

• 使用 Vant 的 Cell 展示商品
• 自定义“加入购物车”按钮
• 点击商品跳转详情

页面结构：

pages/product-list/product-list.json

{"usingComponents": {"van-cell": "@vant/weapp/cell/index","van-cell-group": "@vant/weapp/cell-group/index","add-cart-btn": "/components/add-cart-btn/add-cart-btn"}
}

pages/product-list/product-list.js

Page({data: {products: [{ id: 1, name: 'iPhone 15', price: 5999 },{ id: 2, name: 'MacBook Pro', price: 12999 }]},onAddToCart(e) {const product = this.data.products.find(p => p.id === e.detail.id);wx.showToast({ title: `已添加 ${product.name}` });},goToDetail(e) {const id = e.currentTarget.dataset.id;wx.navigateTo({ url: `/pages/detail/detail?id=${id}` });}
});

pages/product-list/product-list.wxml

<van-cell-group><van-cell wx:for="{{products}}" wx:key="id"title="{{item.name}}"value="¥{{item.price}}"is-linkdata-id="{{item.id}}"bind:click="goToDetail"><add-cart-btn slot="right-icon" product-id="{{item.id}}" bind:add="onAddToCart"/></van-cell>
</van-cell-group>

components/add-cart-btn/add-cart-btn.js

Component({properties: {productId: Number},methods: {handleAdd() {this.triggerEvent('add', { id: this.properties.productId });}}
});

components/add-cart-btn/add-cart-btn.wxml

<van-button size="mini" type="success" bind:click="handleAdd">+</van-button>

---

八、本章小结

知识点	说明
组件化开发	模块化、复用、解耦
自定义组件	四文件结构，properties/events/slots
Vant Weapp	丰富 UI 组件，提升开发效率
属性	父传子，支持类型校验与 observer
事件	子传父，通过 triggerEvent
插槽	内容分发，支持默认与具名
业务组件	封装领域逻辑，提升复用性

建议：在实际项目中，优先使用成熟的 UI 库（如 Vant Weapp），对高频业务逻辑封装为自定义业务组件，实现“原子组件 + 业务组件”双层架构。

---

✅ 以上内容涵盖语法细节、完整案例、注释说明及综合实战，适用于微信小程序开发者系统学习组件开发。