微信小程序开发之Vant组件库
文章目录
- 环境
- Vant介绍
-
- 示例
- 微信小程序的npm支持
-
- 安装npm包
- 构建npm
- 在微信小程序开发中使用Vant
-
- 准备
- 安装和配置
-
- 一：安装
- 二：修改app.json
- 三：修改project.config.json
- 四：构建npm包
- 使用
- Button组件
- Calendar组件
- 参考
环境
- Windows 11 家庭中文版
- 微信开发者工具 Stable 1.06.2401020
- 调试基础库 3.3.4
- node v18.19.0
- npm 10.2.3
- Vant 1.11.3
Vant介绍
Vant 是一个轻量、可靠的移动端组件库，于 2017 年开源。
目前 Vant 官方提供了 Vue 2 版本、Vue 3 版本和微信小程序版本，并由社区团队维护 React 版本和支付宝小程序版本。
示例
参见 https://github.com/vant-ui/vant-demo 。
首先，把git repo克隆到本地：
git clone git@github.com:vant-ui/vant-demo.git
注：需要public key。
源码结构如下：
├── vant # Examples related to Vant
│ ├── rsbuild Building applications using Vue 3, Vant 4, and Rsbuild
│ ├── vite Building applications using Vue 3, Vant 4, and Vite
│ ├── nuxt3 Building applications using Nuxt 3 and Vant 4
│ ├── vue3 Building applications using Vue 3, Vant 4, and Vue Cli
│ ├── vue3-ts Building applications using Vue 3, Vant 4, TypeScript, Vite
│ ├── cdn Importing Vant through CDN
│ ├── rem Configuring rem adaptation
│ ├── viewport Configuring viewport settings
│ └── typescript Configuring TypeScript and importing on demand
│
├── vant-weapp # Examples related to Vant Weapp
│ └── base Building mini-programs using Vant Weapp
│
├── react-vant # Examples related to React Vant
│ └── rsbuild Building applications using React Vant and Rsbuild
│ └── modern-js Building applications using React Vant, Modern.js, and Rspack
│
└── vant-cli # Examples related to Vant Cli
└── base Building component libraries using Vant Cli
注：在Windows下， tree 命令无法指定级别的深度，估计得用第三方工具才行。该结构是从网站上直接复制的。
到 vant/vite 目录下，查看目录内容：
c:\temp\test0216\vant-demo\vant\vite>dir
驱动器 C 中的卷是 OS
卷的序列号是 F238-D5CC
c:\temp\test0216\vant-demo\vant\vite 的目录
2024-02-16 20:36 <DIR> .
2024-02-16 20:36 <DIR> ..
2024-02-16 20:36 48 .gitignore
2024-02-16 20:36 283 index.html
2024-02-16 20:36 408 package.json
2024-02-16 20:36 <DIR> src
2024-02-16 20:36 274 vite.config.js
4 个文件 1,013 字节
3 个目录 47,527,333,888 可用字节
其中， package.json 文件内容如下：
{
"name": "vite",
"private": true,
"version": "0.0.0",
"scripts": {
"dev": "vite",
"build": "vite build"
},
"dependencies": {
"vant": "^4.0.0",
"vue": "^3.2.45"
},
"devDependencies": {
"@vant/auto-import-resolver": "^1.0.1",
"@vitejs/plugin-vue": "^4.3.4",
"less": "^4.1.3",
"unplugin-vue-components": "^0.25.2",
"vite": "^4.4.9"
}
}
在此目录下，安装依赖包：
c:\temp\test0216\vant-demo\vant\vite>npm i
added 91 packages, and audited 92 packages in 43s
17 packages are looking for funding
run `npm fund` for details
found 0 vulnerabilities
大约一两分钟，就安装好了。
再次查看目录：
c:\temp\test0216\vant-demo\vant\vite>dir
驱动器 C 中的卷是 OS
卷的序列号是 F238-D5CC
c:\temp\test0216\vant-demo\vant\vite 的目录
2024-02-16 20:37 <DIR> .
2024-02-16 20:36 <DIR> ..
2024-02-16 20:36 48 .gitignore
2024-02-16 20:36 283 index.html
2024-02-16 20:37 <DIR> node_modules
2024-02-16 20:37 52,038 package-lock.json
2024-02-16 20:36 408 package.json
2024-02-16 20:36 <DIR> src
2024-02-16 20:36 274 vite.config.js
5 个文件 53,051 字节
4 个目录 47,468,183,552 可用字节
可见，多了 node_modules 目录和 package-lock.json 文件。
运行：
npm run dev
界面如下：
VITE v4.5.2 ready in 562 ms
➜ Local: http://localhost:5173/
➜ Network: use --host to expose
➜ press h to show help
输入 h ，查看帮助：
Shortcuts
press r to restart the server
press u to show server url
press o to open in browser
press c to clear console
press q to quit
输入 u ，显示URL：
➜ Local: http://localhost:5173/
➜ Network: use --host to expose
可以打开浏览器，访问该URL，也可以直接输入 o ，会自动打开浏览器，访问 http://localhost:5173/ ，如下：
最后，按 q 退出应用。
微信小程序的npm支持
参见 https://developers.weixin.qq.com/miniprogram/dev/devtools/npm.html 。
从小程序基础库版本 2.2.1 或以上、及开发者工具 1.02.1808300 或以上开始，小程序支持使用 npm 安装第三方包。
安装npm包
在小程序 package.json 所在的目录中执行命令安装npm包：
npm install
注意：此处要求参与构建npm的 package.json 需要在 project.config.json 定义的 miniprogramRoot 之内。
开发者工具 v1.02.1811150 版本开始，调整为根据 package.json 的 dependencies 字段构建，所以声明在 devDependencies 里的包也可以在开发过程中被安装使用而不会参与到构建中。如果是这之前的版本，则建议使用 --production 选项，可以减少安装一些业务无关的 npm 包，从而减少整个小程序包的大小。
miniprogramRoot 字段不存在时， miniprogramRoot 就是 project.config.js 所在的目录。
构建npm
在微信开发者工具中，工具 -> 构建 npm：
为何要构建npm？
首先 node_modules 目录不会参与编译、上传和打包中，所以小程序想要使用 npm 包必须走一遍“构建 npm”的过程，在每一份 miniprogramRoot 内开发者声明的 package.json 的最外层的 node_modules 的同级目录下会生成一个 miniprogram_npm 目录，里面会存放构建打包后的 npm 包，也就是小程序真正使用的 npm 包。
构建打包分为两种：小程序 npm 包会直接拷贝构建文件生成目录下的所有文件到 miniprogram_npm 中；其他 npm 包则会从入口 js 文件开始走一遍依赖分析和打包过程（类似 webpack）。
寻找 npm 包的过程和 npm 的实现类似，从依赖 npm 包的文件所在目录开始逐层往外找，直到找到可用的 npm 包或是小程序根目录为止。 下面简单介绍下构建打包前后的目录情况，构建之前的结构：
|--node_modules
| |--testComp // 小程序 npm 包
| | |--package.json
| | |--src
| | |--miniprogram_dist
| | |-index.js
| | |-index.json
| | |-index.wxss
| | |-index.wxml
| |--testa // 其他 npm 包
| |--package.json
| |--lib
| | |--entry.js
| |--node_modules
| |--testb
| |--package.json
| |--main.js
|--pages
|--app.js
|--app.wxss
|--app.json
|--project.config.js
构建之后的结构：
|--node_modules
|--miniprogram_npm
| |--testComp // 小程序 npm 包
| | |-index.js
| | |-index.json
| | |-index.wxss
| | |-index.wxml
| |--testa // 其他 npm 包
| |--index.js // 打包后的文件
| |--miniprogram_npm
| |--testb
| |--index.js // 打包后的文件
| |--index.js.map
|--pages
|--app.js
|--app.wxss
|--app.json
|--project.config.js
注意：打包生成的代码在同级目录下会生成 source map 文件，方便进行逆向调试。
在微信小程序开发中使用Vant
准备
在微信开发者工具中，新建项目 test0216 ：
点击右上角“详情” -> “本地设置” -> “基础调试库”，选择使用率最多的版本，本例中为“3.3.4”：
从导航条可以看到，源码中并没有 package.json 文件：
在项目根目录下运行 npm init ，生成 package.json 文件：
{
"name": "test0216",
"version": "1.0.0",
"description": "这是云开发的快速启动指引，其中演示了如何上手使用云开发的三大基础能力：",
"main": ".eslintrc.js",
"scripts": {
"test": "echo \"Error: no test specified\" && exit 1"
},
"author": "",
"license": "ISC"
}
安装和配置
一：安装
在项目根目录下运行 npm i @vant/weapp -S --production ：
c:\Users\duke_\WeChatProjects\test0216>npm i @vant/weapp -S --production
npm WARN config production Use `--omit=dev` instead.
added 1 package, and audited 2 packages in 5s
found 0 vulnerabilities
注：
-S：即--save，把package信息写入package.json的dependencies里（如果是-D，则是把package信息写入package.json的devDependencies里）--production：只安装dependencies里的package，不安装devDependencies里的package
安装好以后，在 package.json 文件里多出以下内容：
"dependencies": {
"@vant/weapp": "^1.11.4"
}
同时，多了 node_modules 目录，其中有 @vant 目录。
二：修改app.json
接下来，修改 app.json 文件，把其中的 "style": "v2", 删掉：
......
"sitemapLocation": "sitemap.json",
"style": "v2", <-- 把这一行删掉
"lazyCodeLoading": "requiredComponents"
}
注：JSON文件没法注释，只能删掉。
文档上说，小程序的新版基础组件强行加上了许多样式，难以覆盖，不关闭将造成部分组件样式混乱。
三：修改project.config.json
接下来，修改 project.config.json 文件。
在该文件中，有如下设置：
"miniprogramRoot": "miniprogram/",
而 package.json 文件在项目根目录里，不在 miniprogramRoot 里。
前面提到，参与构建 npm 的 package.json 需要在 project.config.json 定义的 miniprogramRoot 之内。
所以需要修改 project.config.json 文件。把：
{
...
"setting": {
...
"packNpmManually": false,
"packNpmRelationList": [],
...
}
}
修改为：
{
...
"setting": {
...
"packNpmManually": true,
"packNpmRelationList": [
{
"packageJsonPath": "./package.json",
"miniprogramNpmDistDir": "./miniprogram/"
}
],
...
}
}
如果不这么设置，则构建npm会报错：
message： 没有找到可以构建的 NPM 包，请确认需要参与构建的 npm 都在 `miniprogramRoot` 目录内，或配置 project.config.json 的 packNpmManually 和 packNpmRelationList 进行构建
appid: wxb6b7b29f5024c210
openid: o6zAJs-qiQCqPQ3F31epIHxEDy1A
ideVersion: 1.06.2401020
osType: win32-x64
time: 2024-02-16 23:17:09
注意： 由于目前新版开发者工具创建的小程序目录文件结构问题，npm构建的文件目录为 miniprogram_npm ，并且开发工具会默认在当前目录下创建 miniprogram_npm 的文件名，所以新版本的 miniprogramNpmDistDir 配置为 ./ 即可。
四：构建npm包
现在，就可以构建npm包了。
在微信开发者工具里，“工具” -> “构建 npm”，弹出对话框，显示构建完成：
可见，多了 miniprogram_npm 目录，这里存放了小程序真正使用的npm包：
使用
在使用组件前，还需要在项目的 app.json （全局）或者页面的 xxx.json （局部）文件中配置一下。声明要用的组件和路径。
Button组件
本例使用局部设置。在 index.json 中，添加如下代码：
"usingComponents": {
"van-button": "@vant/weapp/button/index"
}
在 index.wxml 中，添加如下代码：
<van-button block round type="info" icon="star-o">btn1van-button>
block：块级元素，每行只有一个元素，且居中对齐。若不设置，默认是行级元素，每行可有多个元素，且靠左对齐。round：圆角按钮。type="info"：蓝底白字，此外还有primary、warning、danger等选项。icon="star-o"：在按钮上显示指定的图标。
效果如下：
Calendar组件
本例使用全局设置。在 app.json 中，添加如下代码：
"usingComponents": {
"van-calendar": "@vant/weapp/calendar/index"
}
在 index.wxml 中，添加/修改如下代码：
<van-button block round type="info" icon="star-o" bindtap="onDisplay">btn1van-button>
<text>日期：{{ dateString }}，时间戳：{{ dateInt }}text>
<van-calendar show="{{ show }}" bind:close="onClose" bind:confirm="onConfirm" />
在 index.js 中，添加如下代码：
......
Page({
data: {
......
show: false,
dateString: '',
dateInt: undefined,
......
onDisplay() {
this.setData({ show: true });
},
onClose() {
this.setData({ show: false });
},
async onConfirm(event) {
let date = new Date(event.detail)
let dateString = date.getFullYear() + '-' + (date.getMonth() + 1) + '-' + date.getDate()
let dateInt = date.getTime()
console.log('dateInt = ' + dateInt)
this.setData({
show: false,
dateString: dateString,
dateInt: dateInt,
});
},
......
页面效果如下：
默认日历是隐藏的。点击 btn1 按钮，弹出日历：
选择日历中的某一天，然后点击“确定”：
可见，已经把从日历控件上选择的日期记录下来了。
参考
https://vant-contrib.gitee.io/vant-weapphttps://developers.weixin.qq.com/miniprogram/dev/devtools/npm.htmlhttps://github.com/vant-ui/vant-demo