neverland
Binary file not shown.
File diff suppressed because it is too large
Load Diff
File diff suppressed because it is too large
Load Diff
@@ -31,7 +31,7 @@ Vant 是一个**轻量、可靠的移动端组件库**，于 2017 年开源。
|
||||
|
||||
### 版本提示
|
||||
|
||||
你当前浏览的是 **Vant 3.x 版本** 的文档，适用于 Vue 3 开发。如果你在使用 Vue 2，请浏览 [Vant 2 文档](https://vant-contrib.gitee.io/vant/v2)。
|
||||
你当前浏览的是 **Vant 4.x 版本** 的文档，适用于 Vue 3 开发。如果你在使用 Vue 2，请浏览 [Vant 2 文档](https://vant-contrib.gitee.io/vant/v2)。
|
||||
|
||||
### 快速上手
|
||||
|
||||
|
||||
@@ -1,4 +1,4 @@
|
||||
# 从 v2 升级
|
||||
# 从 v2 升级到 v3
|
||||
|
||||
### 介绍
|
||||
|
||||
|
||||
@@ -0,0 +1,365 @@
|
||||
# 从 v3 升级到 v4
|
||||
|
||||
### 介绍
|
||||
|
||||
本文档提供了从 Vant 3 到 Vant 4 的升级指南。
|
||||
|
||||
## 按需引入方式调整
|
||||
|
||||
### 移除 babel-plugin-import
|
||||
|
||||
从 Vant 4.0 版本开始，将不再支持 `babel-plugin-import`，请移除项目中依赖的 `babel-plugin-import` 插件。
|
||||
|
||||
只需要删除 `babel.config.js` 中的以下代码即可：
|
||||
|
||||
```diff
|
||||
module.exports = {
|
||||
plugins: [
|
||||
- ['import', {
|
||||
- libraryName: 'vant',
|
||||
- libraryDirectory: 'es',
|
||||
- style: true
|
||||
- }, 'vant']
|
||||
]
|
||||
};
|
||||
```
|
||||
|
||||
#### 收益
|
||||
|
||||
移除 `babel-plugin-import` 有以下收益：
|
||||
|
||||
- 不再强依赖 babel，项目可以使用 esbuild、swc 等更高效的编译工具，大幅度提升编译效率。
|
||||
- 不再受到 `babel-plugin-import` 的 import 写法限制，可以从 vant 中导入除了组件以外的其他内容，比如 Vant 4 中新增的 `showToast` 等方法：
|
||||
|
||||
```ts
|
||||
import { showToast, showDialog } from 'vant';
|
||||
```
|
||||
|
||||
#### 样式引入方案
|
||||
|
||||
移除 `babel-plugin-import` 对项目的 JS 体积不会有影响，因为 Vant 默认支持通过 Tree Shaking 优化来移除不需要的 JS 代码。
|
||||
|
||||
而 CSS 代码的引入方式可以从以下两种方式中进行选择：
|
||||
|
||||
- 通过 [unplugin-vue-components](https://github.com/antfu/unplugin-vue-components) 插件实现按需引入样式，详细用法参见 [快速上手](#/zh-CN/quickstart)。
|
||||
- 在项目中全量引入 Vant 的样式文件：
|
||||
|
||||
```js
|
||||
import 'vant/lib/index.css';
|
||||
```
|
||||
|
||||
## 组件重构
|
||||
|
||||
### 介绍
|
||||
|
||||
在 Vant 4 中，一共有三个组件被完全重构，它们是：
|
||||
|
||||
- `Area`
|
||||
- `Picker`
|
||||
- `DatetimePicker`
|
||||
|
||||
之所以重构这三个组件，是因为在之前的版本中，`Picker` 组件的 API 设计存在一些不合理的设计，导致大家在使用时经常遇到问题，比如：
|
||||
|
||||
- columns 数据格式定义不合理，容易产生误解
|
||||
- 数据流不清晰，暴露了过多的实例方法来对数据进行操作
|
||||
|
||||
为了解决上述问题，我们在 v4 版本中对 `Picker` 组件进行了重构，同时也重构了基于 `Picker` 派生出的 `Area` 和 `DatetimePicker` 组件。
|
||||
|
||||
### Picker 组件重构
|
||||
|
||||
#### 主要变更
|
||||
|
||||
- 支持通过 `v-model` 绑定当前选中的值，移除 `default-index` 属性
|
||||
- 重新定义了 `columns` 属性的结构
|
||||
- 移除了操作内部数据的实例方法，仅保留 `confirm` 方法
|
||||
- 新增 `getSelectedOptions` 实例方法
|
||||
- 调整了 `confirm`、`cancel`、`change` 事件的参数
|
||||
- 重命名 `item-height` 属性为 `option-height`
|
||||
- 重命名 `visible-item-count` 属性为 `visible-option-num`
|
||||
|
||||
> 详细用法请参见 [Picker 组件文档](#/zh-CN/picker)。
|
||||
|
||||
### DatetimePicker 组件重构
|
||||
|
||||
DatetimePicker 组件被拆分为：
|
||||
|
||||
- [TimePicker](#/zh-CN/time-picker): 用于时间选择。
|
||||
- [DatePicker](#/zh-CN/date-picker): 用于日期选择。
|
||||
- [PickerGroup](#/zh-CN/picker-group): 用于用于结合多个 Picker 选择器组件。
|
||||
|
||||
同时，TimePicker 和 DatePicker 组件也基于新版 Picker 组件进行重构，并优化了部分 API 设计。
|
||||
|
||||
#### 主要变更
|
||||
|
||||
以下是 TimePicker 和 DatePicker 的主要 API 变化，更多细节请参考 [TimePicker](#/zh-CN/time-picker) 和 [DatePicker](#/zh-CN/date-picker) 文档。
|
||||
|
||||
- `v-model` 绑定的值调整为数组格式
|
||||
- 新增 `columns-type` 属性，用于控制选项类型和顺序
|
||||
- 移除 `type` 属性和 `columns-order` 属性
|
||||
- 移除 `getPicker` 方法
|
||||
- 调整 `confirm`、`cancel`、`change` 事件的参数，与 Picker 组件保持一致
|
||||
|
||||
> Vant 4 不再提供旧版的 DatetimePicker 组件，使用 PickerGroup 组件可以实现更灵活、更丰富的交互效果，具体用法请参考 [PickerGroup](#/zh-CN/picker-group) 组件文档。
|
||||
|
||||
### Area 组件重构
|
||||
|
||||
Area 组件是基于 Picker 组件进行封装的，因此本次升级也对 Area 组件进行了内部逻辑的重构，并优化了部分 API 设计。
|
||||
|
||||
#### 主要变更
|
||||
|
||||
- 支持通过 `v-model` 绑定当前选中的值
|
||||
- 移除 `reset` 方法，现在可以通过修改 `v-model` 来进行重置
|
||||
- 移除 `is-oversea-code` 属性
|
||||
- 调整 `confirm`、`cancel`、`change` 事件的参数，与 Picker 组件保持一致
|
||||
- 重命名 `value` 属性为 `modelValue`
|
||||
- 重命名 `item-height` 属性为 `option-height`
|
||||
- 重命名 `visible-item-count` 属性为 `visible-option-num`
|
||||
|
||||
> 详细用法请参见 [Area 组件文档](#/zh-CN/area)。
|
||||
|
||||
## API 调整
|
||||
|
||||
### Dialog 调用方式调整
|
||||
|
||||
在 Vant 3 中，`Dialog` 是一个函数，调用函数可以快速唤起全局的弹窗组件，而 `Dialog.Component` 才是 `Dialog` 组件对象，这与大部分组件的用法存在差异，容易导致使用错误。
|
||||
|
||||
为了更符合直觉，我们在 Vant 4 中调整了 `Dialog` 的调用方式，将 `Dialog()` 函数重命名为 `showDialog()`。
|
||||
|
||||
```js
|
||||
// Vant 3
|
||||
Dialog(); // 函数调用
|
||||
Dialog.Component; // 组件对象
|
||||
|
||||
// Vant 4
|
||||
showDialog(); // 函数调用
|
||||
Dialog; // 组件对象
|
||||
```
|
||||
|
||||
`Dialog` 上挂载的其他方法也进行了重命名，新旧 API 的映射关系如下：
|
||||
|
||||
```js
|
||||
Dialog(); // -> showDialog()
|
||||
Dialog.alert(); // -> showDialog()
|
||||
Dialog.confirm(); // -> showConfirmDialog()
|
||||
Dialog.close(); // -> closeDialog();
|
||||
Dialog.setDefaultOptions(); // -> setDialogDefaultOptions()
|
||||
Dialog.resetDefaultOptions(); // -> resetDialogDefaultOptions()
|
||||
```
|
||||
|
||||
#### 兼容方案
|
||||
|
||||
为了便于代码迁移，我们提供了兼容方案，你可以使用 `@vant/compat` 中导出的 `Dialog` 对象来兼容原有代码。
|
||||
|
||||
```js
|
||||
import { Dialog } from '@vant/compat';
|
||||
|
||||
Dialog();
|
||||
Dialog.close();
|
||||
```
|
||||
|
||||
`@vant/compat` 中导出的 `Dialog` 与 Vant 3 中的 `Dialog` 拥有完全一致的 API 和行为，因此你只需要修改 `Dialog` 的引用路径，其他代码可以保持不变。
|
||||
|
||||
### Toast 调用方式调整
|
||||
|
||||
Vant 4 中，`Toast` 组件的调用方式也进行了调整，与 `Dialog` 组件的改动一致：
|
||||
|
||||
```js
|
||||
// Vant 3
|
||||
Toast(); // 函数调用
|
||||
|
||||
// Vant 4
|
||||
showToast(); // 函数调用
|
||||
Toast; // 组件对象
|
||||
```
|
||||
|
||||
`Toast` 上挂载的其他方法也进行了重命名，新旧 API 的映射关系如下：
|
||||
|
||||
```js
|
||||
Toast(); // -> showToast()
|
||||
Toast.fail(); // -> showFailToast()
|
||||
Toast.success(); // -> showSuccessToast()
|
||||
Toast.loading(); // -> showLoadingToast()
|
||||
Toast.clear(); // -> closeToast()
|
||||
Toast.setDefaultOptions(); // -> setToastDefaultOptions()
|
||||
Toast.resetDefaultOptions(); // -> resetToastDefaultOptions()
|
||||
```
|
||||
|
||||
同时，Vant 4 将不再在 `this` 对象上全局注册 `$toast` 方法，这意味着 `this` 对象上将无法访问到 `$toast`。
|
||||
|
||||
#### 兼容方案
|
||||
|
||||
为了便于代码迁移，我们提供了兼容方案，你可以使用 `@vant/compat` 中导出的 `Toast` 对象来兼容原有代码。
|
||||
|
||||
```js
|
||||
import { Toast } from '@vant/compat';
|
||||
|
||||
Toast();
|
||||
Toast.clear();
|
||||
```
|
||||
|
||||
`@vant/compat` 中导出的 `Toast` 与 Vant 3 中的 `Toast` 拥有完全一致的 API 和行为，因此你只需要修改 `Toast` 的引用路径，其他代码可以保持不变。
|
||||
|
||||
### Notify 调用方式调整
|
||||
|
||||
Vant 4 中，`Notify` 组件的调用方式也进行了调整，与 `Dialog` 组件的改动一致：
|
||||
|
||||
```js
|
||||
// Vant 3
|
||||
Notify(); // 函数调用
|
||||
Notify.Component; // 组件对象
|
||||
|
||||
// Vant 4
|
||||
showNotify(); // 函数调用
|
||||
Notify; // 组件对象
|
||||
```
|
||||
|
||||
`Notify` 上挂载的其他方法也进行了重命名，新旧 API 的映射关系如下：
|
||||
|
||||
```js
|
||||
Notify(); // -> showNotify()
|
||||
Notify.clear(); // -> closeNotify()
|
||||
Notify.setDefaultOptions(); // -> setNotifyDefaultOptions()
|
||||
Notify.resetDefaultOptions(); // -> resetNotifyDefaultOptions()
|
||||
```
|
||||
|
||||
同时，Vant 4 将不再在 `this` 对象上全局注册 `$notify` 方法，这意味着 `this` 对象上将无法访问到 `$notify`。
|
||||
|
||||
#### 兼容方案
|
||||
|
||||
为了便于代码迁移，我们提供了兼容方案，你可以使用 `@vant/compat` 中导出的 `Notify` 对象来兼容原有代码。
|
||||
|
||||
```js
|
||||
import { Notify } from '@vant/compat';
|
||||
|
||||
Notify();
|
||||
Notify.clear();
|
||||
```
|
||||
|
||||
`@vant/compat` 中导出的 `Notify` 与 Vant 3 中的 `Notify` 拥有完全一致的 API 和行为，因此你只需要修改 `Notify` 的引用路径，其他代码可以保持不变。
|
||||
|
||||
### ImagePreview 调用方式调整
|
||||
|
||||
Vant 4 中，`ImagePreview` 组件的调用方式也进行了调整，与 `ImagePreview` 组件的改动一致：
|
||||
|
||||
```js
|
||||
// Vant 3
|
||||
ImagePreview(); // 函数调用
|
||||
ImagePreview.Component; // 组件对象
|
||||
|
||||
// Vant 4
|
||||
showImagePreview(); // 函数调用
|
||||
ImagePreview; // 组件对象
|
||||
```
|
||||
|
||||
#### 兼容方案
|
||||
|
||||
为了便于代码迁移，我们提供了兼容方案，你可以使用 `@vant/compat` 中导出的 `ImagePreview` 对象来兼容原有代码。
|
||||
|
||||
```js
|
||||
import { ImagePreview } from '@vant/compat';
|
||||
|
||||
ImagePreview();
|
||||
```
|
||||
|
||||
`@vant/compat` 中导出的 `ImagePreview` 与 Vant 3 中的 `ImagePreview` 拥有完全一致的 API 和行为，因此你只需要修改 `ImagePreview` 的引用路径，其他代码可以保持不变。
|
||||
|
||||
### 事件命名调整
|
||||
|
||||
从 Vant 4 开始，所有的事件均采用 Vue 官方推荐的**驼峰格式**进行命名。
|
||||
|
||||
```js
|
||||
// Vant 3
|
||||
emit('click-input');
|
||||
|
||||
// Vant 4
|
||||
emit('clickInput');
|
||||
```
|
||||
|
||||
这项改动**不影响原有的模板代码**，Vue 会自动在模板中对事件名进行格式转换：
|
||||
|
||||
```html
|
||||
<!-- 以下代码可以照常运行，无须做任何更改 -->
|
||||
<van-field @click-input="onClick" />
|
||||
```
|
||||
|
||||
如果你在 JSX 中使用 Vant 组件，需要将监听的事件名调整为驼峰格式，新的监听方式更加符合 JSX 本身的规范：
|
||||
|
||||
```jsx
|
||||
// Vant 3
|
||||
<Field onClick-input={onClick} />
|
||||
|
||||
// Vant 4
|
||||
<Field onClickInput={onClick} />
|
||||
```
|
||||
|
||||
### 其他 API 调整
|
||||
|
||||
在 Vant 4.0 版本中，以下 API 进行了不兼容更新：
|
||||
|
||||
#### AddressEdit
|
||||
|
||||
- 移除 `show-postal` 属性
|
||||
- 移除 `postal-validator` 属性
|
||||
- `change-area` 事件的参数调整为 `PickerOption[]` 类型
|
||||
- 移除未在文档中标注的 `getArea` 实例方法
|
||||
|
||||
#### Popup
|
||||
|
||||
Popup 的 CSS 样式进行了一定调整，请确认是否对项目中的 UI 产生影响。
|
||||
|
||||
- 默认添加了 `box-sizing: border-box` 样式
|
||||
- 调整了 `position="center"` 时的水平居中方式，以解决弹窗宽度无法正确自适应的问题：
|
||||
|
||||
```less
|
||||
// Vant 3
|
||||
.van-popup--center {
|
||||
left: 50%;
|
||||
transform: translate3d(-50%, -50%, 0);
|
||||
}
|
||||
|
||||
// Vant 4
|
||||
.van-popup--center {
|
||||
left: 0;
|
||||
right: 0;
|
||||
width: fit-content;
|
||||
max-width: calc(100vw - var(--van-padding-md) * 2);
|
||||
margin: 0 auto;
|
||||
transform: translateY(-50%);
|
||||
}
|
||||
```
|
||||
|
||||
#### Tabs
|
||||
|
||||
- 移除了 `click` 和 `disabled` 事件，请使用 `click-tab` 事件代替
|
||||
|
||||
## 样式变量调整
|
||||
|
||||
### 移除 Less 变量
|
||||
|
||||
目前 Vant 已经支持了基于 CSS 变量的主题定制能力，因此后续将不再提供基于 Less 的主题定制方式。
|
||||
|
||||
这意味着 Vant 的 npm 包中将不再会包含 `.less` 样式源文件，只会提供编译后的 `.css` 样式文件。
|
||||
|
||||
如果你的项目正在使用旧版的 Less 主题定制，请使用 [ConfigProvider 全局配置](#/zh-CN/config-provider) 组件进行替换。
|
||||
|
||||
### 简化 CSS 变量名
|
||||
|
||||
考虑到 **代码体积** 和 **使用便捷性**，我们对部分 CSS 变量的名称进行了简化，在变量名中使用更简短的单词，涉及以下变更：
|
||||
|
||||
```less
|
||||
animation-duration -> duration
|
||||
animation-timing-function-enter -> ease-out
|
||||
animation-timing-function-leave -> ease-in
|
||||
background-color -> background
|
||||
background-color-light -> background-2
|
||||
border-radius -> radius
|
||||
border-width-base -> border-width
|
||||
box-shadow -> shadow
|
||||
font-family -> font
|
||||
font-weight-bold -> font-bold
|
||||
price-integer-font -> price-font
|
||||
text-link -> link
|
||||
transition-duration -> duration
|
||||
```
|
||||
|
||||
由于涉及的 CSS 变量较多，建议在代码仓库中进行全局匹配和替换。
|
||||
@@ -50,7 +50,7 @@ The easiest way to use Vant is to include a CDN link in the HTML file, after whi
|
||||
app.use(vant.Lazyload);
|
||||
|
||||
// Call function component
|
||||
vant.Toast('Message');
|
||||
vant.showToast('Message');
|
||||
|
||||
app.mount('#app');
|
||||
</script>
|
||||
@@ -195,19 +195,19 @@ Some components of Vant are provided as function, including `Toast`, `Dialog`, `
|
||||
|
||||
```js
|
||||
// Toast
|
||||
import { Toast } from 'vant';
|
||||
import { showToast } from 'vant';
|
||||
import 'vant/es/toast/style';
|
||||
|
||||
// Dialog
|
||||
import { Dialog } from 'vant';
|
||||
import { showDialog } from 'vant';
|
||||
import 'vant/es/dialog/style';
|
||||
|
||||
// Notify
|
||||
import { Notify } from 'vant';
|
||||
import { showNotify } from 'vant';
|
||||
import 'vant/es/notify/style';
|
||||
|
||||
// ImagePreview
|
||||
import { ImagePreview } from 'vant';
|
||||
import { showImagePreview } from 'vant';
|
||||
import 'vant/es/image-preview/style';
|
||||
```
|
||||
|
||||
|
||||
@@ -54,8 +54,8 @@ pnpm add vant
|
||||
// 可以通过下面的方式手动注册
|
||||
app.use(vant.Lazyload);
|
||||
|
||||
// 调用函数组件，弹出一个 Toast
|
||||
vant.Toast('提示');
|
||||
// 调用工具函数，弹出一个 Toast
|
||||
vant.showToast('提示');
|
||||
|
||||
app.mount('#app');
|
||||
</script>
|
||||
@@ -200,19 +200,19 @@ Vant 中有个别组件是以函数的形式提供的，包括 `Toast`，`Dialog
|
||||
|
||||
```js
|
||||
// Toast
|
||||
import { Toast } from 'vant';
|
||||
import { showToast } from 'vant';
|
||||
import 'vant/es/toast/style';
|
||||
|
||||
// Dialog
|
||||
import { Dialog } from 'vant';
|
||||
import { showDialog } from 'vant';
|
||||
import 'vant/es/dialog/style';
|
||||
|
||||
// Notify
|
||||
import { Notify } from 'vant';
|
||||
import { showNotify } from 'vant';
|
||||
import 'vant/es/notify/style';
|
||||
|
||||
// ImagePreview
|
||||
import { ImagePreview } from 'vant';
|
||||
import { showImagePreview } from 'vant';
|
||||
import 'vant/es/image-preview/style';
|
||||
```
|
||||
|
||||
|
||||
@@ -1,176 +0,0 @@
|
||||
# Custom Theme
|
||||
|
||||
### Deprecated
|
||||
|
||||
This document is deprecated. Vant provides a more convenient [ConfigProvider](#/en-US/config-provider) component for theme configuration. Less variables **will be removed in the next major version**.
|
||||
|
||||
### Intro
|
||||
|
||||
Vant use [Less](http://lesscss.org/) as css preprocessor，you can override the default less variables to custom theme.
|
||||
|
||||
### Less variables
|
||||
|
||||
There are some [basic variables](<(https://github.com/vant-ui/vant/blob/dev/packages/vant/src/style/var.less)>) below, for component less variables, please refer to the documentation of each component, or view the `var.less` file in the component source directory.
|
||||
|
||||
```less
|
||||
// Color Palette
|
||||
@black: #000;
|
||||
@white: #fff;
|
||||
@gray-1: #f7f8fa;
|
||||
@gray-2: #f2f3f5;
|
||||
@gray-3: #ebedf0;
|
||||
@gray-4: #dcdee0;
|
||||
@gray-5: #c8c9cc;
|
||||
@gray-6: #969799;
|
||||
@gray-7: #646566;
|
||||
@gray-8: #323233;
|
||||
@red: #ee0a24;
|
||||
@blue: #1989fa;
|
||||
@orange: #ff976a;
|
||||
@orange-dark: #ed6a0c;
|
||||
@orange-light: #fffbe8;
|
||||
@green: #07c160;
|
||||
|
||||
// Gradient Colors
|
||||
@gradient-red: linear-gradient(to right, #ff6034, #ee0a24);
|
||||
@gradient-orange: linear-gradient(to right, #ffd01e, #ff8917);
|
||||
|
||||
// Component Colors
|
||||
@text-color: @gray-8;
|
||||
@active-color: @gray-2;
|
||||
@active-opacity: 0.7;
|
||||
@disabled-opacity: 0.5;
|
||||
@background-color: @gray-1;
|
||||
@background-color-light: @white;
|
||||
@text-link-color: #576b95;
|
||||
|
||||
// Padding
|
||||
@padding-base: 4px;
|
||||
@padding-xs: @padding-base * 2;
|
||||
@padding-sm: @padding-base * 3;
|
||||
@padding-md: @padding-base * 4;
|
||||
@padding-lg: @padding-base * 6;
|
||||
@padding-xl: @padding-base * 8;
|
||||
|
||||
// Font
|
||||
@font-size-xs: 10px;
|
||||
@font-size-sm: 12px;
|
||||
@font-size-md: 14px;
|
||||
@font-size-lg: 16px;
|
||||
@font-weight-bold: 500;
|
||||
@line-height-xs: 14px;
|
||||
@line-height-sm: 18px;
|
||||
@line-height-md: 20px;
|
||||
@line-height-lg: 22px;
|
||||
@base-font-family: -apple-system, BlinkMacSystemFont, 'Helvetica Neue',
|
||||
Helvetica, Segoe UI, Arial, Roboto, 'PingFang SC', 'miui', 'Hiragino Sans GB',
|
||||
'Microsoft Yahei', sans-serif;
|
||||
@price-integer-font-family: Avenir-Heavy, PingFang SC, Helvetica Neue, Arial,
|
||||
sans-serif;
|
||||
|
||||
// Animation
|
||||
@animation-duration-base: 0.3s;
|
||||
@animation-duration-fast: 0.2s;
|
||||
@animation-timing-function-enter: ease-out;
|
||||
@animation-timing-function-leave: ease-in;
|
||||
|
||||
// Border
|
||||
@border-color: @gray-3;
|
||||
@border-width-base: 1px;
|
||||
@border-radius-sm: 2px;
|
||||
@border-radius-md: 4px;
|
||||
@border-radius-lg: 8px;
|
||||
@border-radius-max: 999px;
|
||||
```
|
||||
|
||||
## How to custom theme
|
||||
|
||||
### Step 1: import less file
|
||||
|
||||
First you should import the less source file to your project. you can use babel-plugin-import to automatically import or just manually import less file.
|
||||
|
||||
#### Automatically import style
|
||||
|
||||
Configure babel plugin in babel.config.js, if you are using babel6, please manually import less file.
|
||||
|
||||
```js
|
||||
module.exports = {
|
||||
plugins: [
|
||||
[
|
||||
'import',
|
||||
{
|
||||
libraryName: 'vant',
|
||||
libraryDirectory: 'es',
|
||||
// specify less file path
|
||||
style: (name) => `${name}/style/less`,
|
||||
},
|
||||
'vant',
|
||||
],
|
||||
],
|
||||
};
|
||||
```
|
||||
|
||||
#### Manually import style
|
||||
|
||||
```js
|
||||
// import all styles
|
||||
import 'vant/lib/index.less';
|
||||
|
||||
// import style of single component
|
||||
import 'vant/lib/button/style/less';
|
||||
```
|
||||
|
||||
### Step 2: modify less variables
|
||||
|
||||
Use [modifyVars](http://lesscss.org/usage/#using-less-in-the-browser-modify-variables) provided by less.js to modify less variables，webpack config for reference:
|
||||
|
||||
```js
|
||||
// webpack.config.js
|
||||
module.exports = {
|
||||
rules: [
|
||||
{
|
||||
test: /\.less$/,
|
||||
use: [
|
||||
// ...other loaders
|
||||
{
|
||||
loader: 'less-loader',
|
||||
options: {
|
||||
lessOptions: {
|
||||
modifyVars: {
|
||||
// override with less vars
|
||||
'text-color': '#111',
|
||||
'border-color': '#eee',
|
||||
// or override with less file
|
||||
hack: `true; @import "your-less-file-path.less";`,
|
||||
},
|
||||
},
|
||||
},
|
||||
},
|
||||
],
|
||||
},
|
||||
],
|
||||
};
|
||||
```
|
||||
|
||||
If you build a project by vue-cli,it can be configured in `vue.config.js`:
|
||||
|
||||
```js
|
||||
// vue.config.js
|
||||
module.exports = {
|
||||
css: {
|
||||
loaderOptions: {
|
||||
less: {
|
||||
lessOptions: {
|
||||
modifyVars: {
|
||||
// override with less vars
|
||||
'text-color': '#111',
|
||||
'border-color': '#eee',
|
||||
// or override with less file
|
||||
hack: `true; @import "your-less-file-path.less";`,
|
||||
},
|
||||
},
|
||||
},
|
||||
},
|
||||
},
|
||||
};
|
||||
```
|
||||
@@ -1,184 +0,0 @@
|
||||
# 定制主题
|
||||
|
||||
### 废弃提示
|
||||
|
||||
本文档已废弃，Vant 提供了更方便的 [ConfigProvider 全局配置](#/zh-CN/config-provider) 组件进行主题配置。基于 Less 变量进行定制的方式**将在下个大版本废弃**。
|
||||
|
||||
### 介绍
|
||||
|
||||
Vant 提供了一套默认主题，CSS 命名采用 BEM 的风格，方便使用者覆盖样式。如果你想完全替换主题色或者其他样式，可以按照本文档进行主题定制。
|
||||
|
||||
### 示例工程
|
||||
|
||||
我们提供了一个基于 Vue CLI 3 的示例工程，仓库地址为 [Vant Demo](https://github.com/vant-ui/vant-demo)，其中包含了定制主题的基本配置，可以作为参考。
|
||||
|
||||
### 样式变量
|
||||
|
||||
Vant 使用了 [Less](http://lesscss.org/) 对样式进行预处理，并内置了一些样式变量，通过替换样式变量即可定制你自己需要的主题。
|
||||
|
||||
下面是所有的[基础样式变量](https://github.com/vant-ui/vant/blob/dev/packages/vant/src/style/var.less)，组件的样式变量请参考各个组件的文档，或查看组件源码目录下的 `var.less` 文件。
|
||||
|
||||
```less
|
||||
// Color Palette
|
||||
@black: #000;
|
||||
@white: #fff;
|
||||
@gray-1: #f7f8fa;
|
||||
@gray-2: #f2f3f5;
|
||||
@gray-3: #ebedf0;
|
||||
@gray-4: #dcdee0;
|
||||
@gray-5: #c8c9cc;
|
||||
@gray-6: #969799;
|
||||
@gray-7: #646566;
|
||||
@gray-8: #323233;
|
||||
@red: #ee0a24;
|
||||
@blue: #1989fa;
|
||||
@orange: #ff976a;
|
||||
@orange-dark: #ed6a0c;
|
||||
@orange-light: #fffbe8;
|
||||
@green: #07c160;
|
||||
|
||||
// Gradient Colors
|
||||
@gradient-red: linear-gradient(to right, #ff6034, #ee0a24);
|
||||
@gradient-orange: linear-gradient(to right, #ffd01e, #ff8917);
|
||||
|
||||
// Component Colors
|
||||
@text-color: @gray-8;
|
||||
@active-color: @gray-2;
|
||||
@active-opacity: 0.7;
|
||||
@disabled-opacity: 0.5;
|
||||
@background-color: @gray-1;
|
||||
@background-color-light: @white;
|
||||
@text-link-color: #576b95;
|
||||
|
||||
// Padding
|
||||
@padding-base: 4px;
|
||||
@padding-xs: @padding-base * 2;
|
||||
@padding-sm: @padding-base * 3;
|
||||
@padding-md: @padding-base * 4;
|
||||
@padding-lg: @padding-base * 6;
|
||||
@padding-xl: @padding-base * 8;
|
||||
|
||||
// Font
|
||||
@font-size-xs: 10px;
|
||||
@font-size-sm: 12px;
|
||||
@font-size-md: 14px;
|
||||
@font-size-lg: 16px;
|
||||
@font-weight-bold: 500;
|
||||
@line-height-xs: 14px;
|
||||
@line-height-sm: 18px;
|
||||
@line-height-md: 20px;
|
||||
@line-height-lg: 22px;
|
||||
@base-font-family: -apple-system, BlinkMacSystemFont, 'Helvetica Neue',
|
||||
Helvetica, Segoe UI, Arial, Roboto, 'PingFang SC', 'miui', 'Hiragino Sans GB',
|
||||
'Microsoft Yahei', sans-serif;
|
||||
@price-integer-font-family: Avenir-Heavy, PingFang SC, Helvetica Neue, Arial,
|
||||
sans-serif;
|
||||
|
||||
// Animation
|
||||
@animation-duration-base: 0.3s;
|
||||
@animation-duration-fast: 0.2s;
|
||||
@animation-timing-function-enter: ease-out;
|
||||
@animation-timing-function-leave: ease-in;
|
||||
|
||||
// Border
|
||||
@border-color: @gray-3;
|
||||
@border-width-base: 1px;
|
||||
@border-radius-sm: 2px;
|
||||
@border-radius-md: 4px;
|
||||
@border-radius-lg: 8px;
|
||||
@border-radius-max: 999px;
|
||||
```
|
||||
|
||||
## 定制方法
|
||||
|
||||
### 步骤一 引入样式源文件
|
||||
|
||||
定制主题时，需要引入组件对应的 Less 样式文件，支持按需引入和手动引入两种方式。
|
||||
|
||||
#### 按需引入样式（推荐）
|
||||
|
||||
在 babel.config.js 中配置按需引入样式源文件，注意 babel 6 不支持按需引入样式，请手动引入样式。
|
||||
|
||||
```js
|
||||
module.exports = {
|
||||
plugins: [
|
||||
[
|
||||
'import',
|
||||
{
|
||||
libraryName: 'vant',
|
||||
libraryDirectory: 'es',
|
||||
// 指定样式路径
|
||||
style: (name) => `${name}/style/less`,
|
||||
},
|
||||
'vant',
|
||||
],
|
||||
],
|
||||
};
|
||||
```
|
||||
|
||||
#### 手动引入样式
|
||||
|
||||
```js
|
||||
// 引入全部样式
|
||||
import 'vant/lib/index.less';
|
||||
|
||||
// 引入单个组件样式
|
||||
import 'vant/lib/button/style/less';
|
||||
```
|
||||
|
||||
### 步骤二 修改样式变量
|
||||
|
||||
使用 Less 提供的 [modifyVars](http://lesscss.org/usage/#using-less-in-the-browser-modify-variables) 即可对变量进行修改，下面是参考的 webpack 配置。
|
||||
|
||||
```js
|
||||
// webpack.config.js
|
||||
module.exports = {
|
||||
rules: [
|
||||
{
|
||||
test: /\.less$/,
|
||||
use: [
|
||||
// ...其他 loader 配置
|
||||
{
|
||||
loader: 'less-loader',
|
||||
options: {
|
||||
// 若 less-loader 版本小于 6.0，请移除 lessOptions 这一级，直接配置选项。
|
||||
lessOptions: {
|
||||
modifyVars: {
|
||||
// 直接覆盖变量
|
||||
'text-color': '#111',
|
||||
'border-color': '#eee',
|
||||
// 或者可以通过 less 文件覆盖（文件路径为绝对路径）
|
||||
hack: `true; @import "your-less-file-path.less";`,
|
||||
},
|
||||
},
|
||||
},
|
||||
},
|
||||
],
|
||||
},
|
||||
],
|
||||
};
|
||||
```
|
||||
|
||||
如果 vue-cli 搭建的项目，可以在 `vue.config.js` 中进行配置。
|
||||
|
||||
```js
|
||||
// vue.config.js
|
||||
module.exports = {
|
||||
css: {
|
||||
loaderOptions: {
|
||||
less: {
|
||||
// 若 less-loader 版本小于 6.0，请移除 lessOptions 这一级，直接配置选项。
|
||||
lessOptions: {
|
||||
modifyVars: {
|
||||
// 直接覆盖变量
|
||||
'text-color': '#111',
|
||||
'border-color': '#eee',
|
||||
// 或者可以通过 less 文件覆盖（文件路径为绝对路径）
|
||||
hack: `true; @import "your-less-file-path.less";`,
|
||||
},
|
||||
},
|
||||
},
|
||||
},
|
||||
},
|
||||
};
|
||||
```
|
||||
@@ -52,6 +52,7 @@ export function initDemoLocale() {
|
||||
disabled: '禁用状态',
|
||||
uneditable: '不可编辑',
|
||||
basicUsage: '基础用法',
|
||||
usingUrl: '使用图片 URL',
|
||||
advancedUsage: '高级用法',
|
||||
loadingStatus: '加载状态',
|
||||
},
|
||||
@@ -78,6 +79,7 @@ export function initDemoLocale() {
|
||||
disabled: 'Disabled',
|
||||
uneditable: 'Uneditable',
|
||||
basicUsage: 'Basic Usage',
|
||||
usingUrl: 'Using URL',
|
||||
advancedUsage: 'Advanced Usage',
|
||||
loadingStatus: 'Loading',
|
||||
},
|
||||
|
||||
Reference in New Issue
Block a user