微信小程序开发之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-D5CCc:\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.js4 个文件          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 iadded 91 packages, and audited 92 packages in 43s17 packages are looking for fundingrun `npm fund` for detailsfound 0 vulnerabilities

大约一两分钟，就安装好了。

再次查看目录：

c:\temp\test0216\vant-demo\vant\vite>dir驱动器 C 中的卷是 OS卷的序列号是 F238-D5CCc:\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.js5 个文件         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 ，查看帮助：

  Shortcutspress r to restart the serverpress u to show server urlpress o to open in browserpress c to clear consolepress 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 5sfound 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">btn1</van-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">btn1</van-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,});},
......