Vant4官方文档阅读记录

Vant4官方文档阅读记录

Vant是Vue的一个开源UI库，我打算看看官方文档简单的了解一下它的使用方法，这个库主要是支持移动端组件的，不过也可以在PC使用

一. Vant的安装

我自己是打算在Vue3的项目中使用Vant，所以安装命令是

npm install vant -g

如果打算在Vue2里面用的话，需要的安装命令是

npm install vant@latest-v2 -g

这篇笔记用的都是Vue3中的使用

二.Vant的基本使用

首先，创建一个vue3的项目，我用的vite作为包管理器，所以命令是npm init vue@latest，Vant官方建议的也是vite

然后在我们的vue3项目里面添加Vant

import {createApp} from 'vue'
import App from './App.vue'
import {Button} from 'vant'
import 'vant/lib/index.css'

const app = createApp(App)
app.use(Button)
app.mount('#app')

然后在App.vue页面就可以直接使用了

<van-button type="primary">普通按钮</van-button>

官方文档里有这么一句话

Tip: Vant supports Tree Shaking by default, so you don't need to configure any plugins, the unused JS code will be removed by Tree Shaking, but CSS styles cannot be optimized by it.

说在默认设置的情况下，也就是没有安装其他插件的情况下，我们不需要配置更多的插件，来使用Vant，他默认会自动去除不被调用的js代码，但是css代码不会优化

官方文档后面还提到了，如果想要按需引入css，需要配置其他的插件

三.插件的配置

虽然官方文档中说明可以不用配置额外插件，常规的用法就已经可以了，但在学嘛，就尽可能多做尝试了

官方文档提到的插件有下面两个：

1.unplugin-vue-components插件，这个插件可以帮我们自动引入组件

2.@vant/auto-import-resolver插件，这个插件是基于第一个插件开发的，可以用来自动引入vant的样式

先下载这两个插件,作为开发环境依赖

npm i @vant/auto-import-resolver unplugin-vue-components unplugin-auto-import -D

然后在vite.config.js中进行配置

先添加下面三个引入

import AutoImport from 'unplugin-auto-import/vite';
import Components from 'unplugin-vue-components/vite';
import { VantResolver } from '@vant/auto-import-resolver';

然后添加插件

plugins: [
    vue(),
    vueDevTools(),
    AutoImport({//第一个插件
      resolvers: [VantResolver()],
    }),
    Components({//第二个插件
      resolvers: [VantResolver()],
    }),
  ],

这样就可以在我们写模板组件的时候，自动引入了，

官方还给出了提醒：

1.按需引入和全局引入，不能同时使用，不然会导致代码重复，样式覆盖之类的问题

2.在使用过程中，出现无法引入的问题，可以在unplugin-vue-components组件的官方进行反馈，这个插件不是Vant官方来维护的

其他的提示如下：

Tips

• “Full Import” and “On-demand Import” should not be used at the same time, otherwise it will lead to problems such as code duplication and style overrides.
• During use, if the component cannot be imported, because unplugin-vue-components is not a plug-in officially maintained by Vant, it is recommended to give feedback under the unplugin/unplugin-vue-components repository.
• when the version number of unplugin-vue-components is >= 0.26.0, for webpack, vue-cli, and rspack, you need to use ComponentsPlugin.default to register.
• @vant/auto-import-resolver provides some configuration options. Please refer to the README document for more information.
• If it is a similar problem that the style does not take effect, feedback under the Vant repository.

四.高级用法

1.组件注册

(1) 全局注册

有两种方法

import { Button } from 'vant';
import { createApp } from 'vue';

const app = createApp();
// Method 1. 通过app.use来进行注册
app.use(Button);

// Method 2. 通过app.componet来进行注册
app.component(Button.name, Button);

(2) 一次性全局注册所有Vant组件

import Vant from 'vant';
import { createApp } from 'vue';

const app = createApp();

app.use(Vant);

// The Lazyload directive needs to be registered separately
//懒加载注册需要分开来进行注册
app.use(vant.Lazyload);

官方说明：一次性注册所有组件会导致打包文件变得更大

Note: Registering all components will introduce the code of all components, leading to larger bundle size.

(3)局部注册

可以在我们的页面中进行注册

<script setup>
  //就和平常使用我们的Vue组件一样
  //这里我的示例是compositionAPI的，optionsAPI就安装optionsAPI的写法去注册组件就可以了
  import { Button } from 'vant';
</script>

<template>
  <Button />
</template>

(4)也可以在JSX中使用

import { Button } from 'vant';
export default {
  render() {
    return <Button />;
  },
};

2.浏览器适配（视口适配）

Vant默认的是px单位

如果需要的话，我们可以用postcss-px-to-viewport这个插件来将单位转化成视口单位(vw,vh,vmin,vmax)

// postcss.config.js
module.exports = {
  plugins: {
    'postcss-px-to-viewport': {
      viewportWidth: 375,
    },
  },
};

也可以用postcss-pxtorem转换成rem单位

// postcss.config.js
module.exports = {
  plugins: {
    'postcss-pxtorem': {
      rootValue: 37.5,
      propList: ['*'],
    },
  },
};

还可以自己定义rem的基准值

// postcss.config.js
module.exports = {
  plugins: {
    // postcss-pxtorem version >= 5.0.0
    'postcss-pxtorem': {
      rootValue({ file }) {
        return file.indexOf('vant') !== -1 ? 37.5 : 75;
      },
      propList: ['*'],
    },
  },
};

五.PC浏览器适配问题

默认事件都是手机端的事件，如果需要用pc端的话可以引入@vant/touch-emulator模块

Vant is a mobile-first component library, if you want to use Vant in PC browsers, you can use the @vant/touch-emulator module. This module will automatically convert the mouse events of the PC browser into the touch events of the mobile browser.

npm i @vant/touch-emulator -S

引入这个模块以后，就可以在PC端使用Vant

import '@vant/touch-emulator';

六.主题切换以及自定义颜色

1.主题切换

可以设置主题,需要全局引入ConfigProvider，可以用来改dark主题和light主题

import { createApp } from 'vue';
import { ConfigProvider } from 'vant';

const app = createApp();
app.use(ConfigProvider);

<van-config-provider theme="dark">...</van-config-provider>

主题不会更改字体颜色和页面背景颜色，可以通过css调整

.van-theme-dark body {
  color: #f5f5f5;
  background-color: black;
}

也可以通过v-bind动态绑定主题，实现主题的切换

<van-config-provider :theme="theme">...</van-config-provider>

2.自定义颜色

可以自己修改各种样式的颜色，只需要修改:root中的css变量就可以了

:root {
  --van-white: #fff;
  --van-blue: #1989fa;
  --van-button-primary-color: var(--van-white);
  --van-button-primary-background: var(--van-primary-color);
}

:root:root {
  --van-button-primary-background: red;
}

官方又给了说明:用两个:root可以提高我们自己设置的颜色的优先级，让我们自己定义的颜色能成功覆盖官方默认的颜色

Note: Why write two duplicate :root?

Since the theme variables in vant are also declared under :root, in some cases they cannot be successfully overwritten due to priority issues. Through :root:root you can explicitly make the content you write a higher priority to ensure the successful coverage of the theme variables.

3.另一种方法自定义样式

通过ConfigProvider组件来完成，在根节点的组件外包裹ConfigProvider组件，然后通过ConfigProvider组件的theme-vars进行配置，也是用动态绑定来实现的，官方示例如下：

<van-config-provider :theme-vars="themeVars">
  <van-form>
    <van-field name="rate" label="Rate">
      <template #input>
        <van-rate v-model="rate" />
      </template>
    </van-field>
    <van-field name="slider" label="Slider">
      <template #input>
        <van-slider v-model="slider" />
      </template>
    </van-field>
    <div style="margin: 16px">
      <van-button round block type="primary" native-type="submit">
        Submit
      </van-button>
    </div>
  </van-form>
</van-config-provider>

import { ref, reactive } from 'vue';

export default {
  setup() {
    const rate = ref(4);
    const slider = ref(50);

    // ThemeVars will be converted to the corresponding CSS variable
    // For example, sliderBarHeight will be converted to `--van-slider-bar-height`
    const themeVars = reactive({
      rateIconFullColor: '#07c160',
      sliderBarHeight: '4px',
      sliderButtonWidth: '20px',
      sliderButtonHeight: '20px',
      sliderActiveBackground: '#07c160',
      buttonPrimaryBackground: '#07c160',
      buttonPrimaryBorderColor: '#07c160',
    });

    return {
      rate,
      slider,
      themeVars,
    };
  },
};

4.样式的作用域问题

默认情况下，在ConfigProvider组件中，themeVars生成的CSS变量只会对根节点起作用作用，不会对整个页面起作用，需要加一个属性来更改作用域，theme-vars-scope="global"

5.自定义颜色和dark,light主题同时使用

自定义颜色可以和dark以及light主题结合使用，通过以下几个attribute

<van-config-provider
  :theme-vars="themeVars"
  :theme-vars-dark="themeVarsDark"
  :theme-vars-light="themeVarsLight"
>
  ...
</van-config-provider>

也可以通过下面的class来更改颜色

.van-theme-light {
  --van-white: white;
}

.van-theme-dark {
  --van-white: black;
}

Vant的所有component的样式都继承于BasicVariables

但是我们只能在:root或者是ConfigProvider component中才能对其进行更改

所有的BasicVariables列表如下：

--van-black: #000;
--van-white: #fff;
--van-gray-1: #f7f8fa;
--van-gray-2: #f2f3f5;
--van-gray-3: #ebedf0;
--van-gray-4: #dcdee0;
--van-gray-5: #c8c9cc;
--van-gray-6: #969799;
--van-gray-7: #646566;
--van-gray-8: #323233;
--van-red: #ee0a24;
--van-blue: #1989fa;
--van-orange: #ff976a;
--van-orange-dark: #ed6a0c;
--van-orange-light: #fffbe8;
--van-green: #07c160;

// Gradient Colors
--van-gradient-red: linear-gradient(to right, #ff6034, #ee0a24);
--van-gradient-orange: linear-gradient(to right, #ffd01e, #ff8917);

// Component Colors
--van-primary-color: var(--van-blue);
--van-success-color: var(--van-green);
--van-danger-color: var(--van-red);
--van-warning-color: var(--van-orange);
--van-text-color: var(--van-gray-8);
--van-text-color-2: var(--van-gray-6);
--van-text-color-3: var(--van-gray-5);
--van-active-color: var(--van-gray-2);
--van-active-opacity: 0.6;
--van-disabled-opacity: 0.5;
--van-background: var(--van-gray-1);
--van-background-2: var(--van-white);

// Padding
--van-padding-base: 4px;
--van-padding-xs: 8px;
--van-padding-sm: 12px;
--van-padding-md: 16px;
--van-padding-lg: 24px;
--van-padding-xl: 32px;

// Font
--van-font-size-xs: 10px;
--van-font-size-sm: 12px;
--van-font-size-md: 14px;
--van-font-size-lg: 16px;
--van-font-bold: 600;
--van-line-height-xs: 14px;
--van-line-height-sm: 18px;
--van-line-height-md: 20px;
--van-line-height-lg: 22px;
--van-base-font: -apple-system, BlinkMacSystemFont, 'Helvetica Neue', Helvetica,
  Segoe UI, Arial, Roboto, 'PingFang SC', 'miui', 'Hiragino Sans GB', 'Microsoft Yahei',
  sans-serif;
--van-price-font: Avenir-Heavy, PingFang SC, Helvetica Neue, Arial, sans-serif;

// Animation
--van-duration-base: 0.3s;
--van-duration-fast: 0.2s;
--van-ease-out: ease-out;
--van-ease-in: ease-in;

// Border
--van-border-color: var(--van-gray-3);
--van-border-width: 1px;
--van-radius-sm: 2px;
--van-radius-md: 4px;
--van-radius-lg: 8px;
--van-radius-max: 999px;

六.一些问题处理

1.在HTML中使用Vant组件的时候，不能使用自闭合标签，因为HTML可能无法正确解析

就是不能使用下面这种样子的写法

<van-cell title="cell" value="content" />

要使用双标签，像下面这样

<van-cell title="cell" value="content"></van-cell>

2.在iOS端Safari浏览器默认无法触发:active 伪类，需要给body标签添加一个attribute ontouchstart=""

<body ontouchstart=""> ... </body>

3.没有Select组件，是因为手机端使用select交互起来不舒适，官方推荐使用 Picker selector component

4.官方不保证所有组件都能支持uni-app，主要是基于Vue的

目前只看到这边…
后面的内容一边写页面一边看吧