mirror of
https://gitee.com/vant-contrib/vant.git
synced 2025-04-06 03:57:59 +08:00
docs: add advanced usage guide
This commit is contained in:
chenjiahan
parent
b1183b99d3
commit
000ea342a8
28
docs/markdown/advanced-usage.en-US.md
Normal file
28
docs/markdown/advanced-usage.en-US.md
Normal file
@ -0,0 +1,28 @@
|
|||||||
|
# Advanced Usage
|
||||||
|
|
||||||
|
## Browser adaptation
|
||||||
|
|
||||||
|
### Rem units
|
||||||
|
|
||||||
|
Vant use `px` as size units by default，you can use tools such as `postcss-pxtorem` to transform units to `rem`.
|
||||||
|
|
||||||
|
- [postcss-pxtorem](https://github.com/cuth/postcss-pxtorem)
|
||||||
|
- [lib-flexible](https://github.com/amfe/lib-flexible)
|
||||||
|
|
||||||
|
#### PostCSS Config
|
||||||
|
|
||||||
|
postcss config example:
|
||||||
|
|
||||||
|
```js
|
||||||
|
module.exports = {
|
||||||
|
plugins: {
|
||||||
|
autoprefixer: {
|
||||||
|
browsers: ['Android >= 4.0', 'iOS >= 8'],
|
||||||
|
},
|
||||||
|
'postcss-pxtorem': {
|
||||||
|
rootValue: 37.5,
|
||||||
|
propList: ['*'],
|
||||||
|
},
|
||||||
|
},
|
||||||
|
};
|
||||||
|
```
|
||||||
94
docs/markdown/advanced-usage.zh-CN.md
Normal file
94
docs/markdown/advanced-usage.zh-CN.md
Normal file
@ -0,0 +1,94 @@
|
|||||||
|
# 进阶用法
|
||||||
|
|
||||||
|
### 介绍
|
||||||
|
|
||||||
|
通过本章节你可以了解到 Vant 的一些进阶用法，比如浏览器适配、组件实例方法调用等。
|
||||||
|
|
||||||
|
## 浏览器适配
|
||||||
|
|
||||||
|
### Rem 布局适配
|
||||||
|
|
||||||
|
Vant 中的样式默认使用 `px` 作为单位，如果需要使用 `rem` 单位，推荐使用以下两个工具：
|
||||||
|
|
||||||
|
- [postcss-pxtorem](https://github.com/cuth/postcss-pxtorem) 是一款 postcss 插件，用于将单位转化为 rem
|
||||||
|
- [lib-flexible](https://github.com/amfe/lib-flexible) 用于设置 rem 基准值
|
||||||
|
|
||||||
|
#### PostCSS 配置
|
||||||
|
|
||||||
|
下面提供了一份基本的 postcss 配置，可以在此配置的基础上根据项目需求进行修改。
|
||||||
|
|
||||||
|
```js
|
||||||
|
module.exports = {
|
||||||
|
plugins: {
|
||||||
|
autoprefixer: {
|
||||||
|
browsers: ['Android >= 4.0', 'iOS >= 8'],
|
||||||
|
},
|
||||||
|
'postcss-pxtorem': {
|
||||||
|
rootValue: 37.5,
|
||||||
|
propList: ['*'],
|
||||||
|
},
|
||||||
|
},
|
||||||
|
};
|
||||||
|
```
|
||||||
|
|
||||||
|
> Tips: 在配置 postcss-loader 时，应避免 ignore node_modules 目录，否则将导致 Vant 样式无法被编译。
|
||||||
|
|
||||||
|
### 桌面端适配
|
||||||
|
|
||||||
|
Vant 是一个面向移动端的组件库，因此默认只适配了移动端设备，这意味着组件只监听了移动端的`touch`事件，没有监听桌面端的`mouse`事件。
|
||||||
|
|
||||||
|
如果你需要在桌面端使用 Vant，可以引入我们提供的 [@vant/touch-emulator](https://github.com/youzan/vant/tree/dev/packages/vant-touch-emulator)，这个库会在桌面端自动将`mouse`事件转换成对应的`touch`事件，使得组件能够在桌面端使用。
|
||||||
|
|
||||||
|
```bash
|
||||||
|
# 安装模块
|
||||||
|
npm i @vant/touch-emulator -S
|
||||||
|
```
|
||||||
|
|
||||||
|
```js
|
||||||
|
// 引入模块后自动生效
|
||||||
|
import '@vant/touch-emulator';
|
||||||
|
```
|
||||||
|
|
||||||
|
### 底部安全区适配
|
||||||
|
|
||||||
|
iPhone X 等机型底部存在底部指示条，指示条的操作区域与页面底部存在重合，容易导致用户误操作，因此我们需要针对这些机型进行底部安全区适配。Vant 中部分组件提供了`safe-area-inset-bottom`属性，设置该属性后，即可在对应的机型上开启适配，如下示例：
|
||||||
|
|
||||||
|
```html
|
||||||
|
<!-- 在 head 标签中添加 meta 标签，并设置 viewport-fit=cover 值 -->
|
||||||
|
<meta
|
||||||
|
name="viewport"
|
||||||
|
content="width=device-width, initial-scale=1.0, maximum-scale=1.0, minimum-scale=1.0, viewport-fit=cover"
|
||||||
|
/>
|
||||||
|
|
||||||
|
<!-- 开启 safe-area-inset-bottom 属性 -->
|
||||||
|
<van-number-keyboard safe-area-inset-bottom />
|
||||||
|
```
|
||||||
|
|
||||||
|
<img src="https://b.yzcdn.cn/vant/safearea.png">
|
||||||
|
|
||||||
|
## 组件用法
|
||||||
|
|
||||||
|
### 组件实例方法
|
||||||
|
|
||||||
|
Vant 中的许多组件提供了实例方法，调用实例方法时，我们需要通过 [ref](https://cn.vuejs.org/v2/api/#ref) 来注册组件引用信息，引用信息将会注册在父组件的`$refs`对象上。注册完成后，我们可以通过`this.$refs.xxx`访问到对应的组件实例，并调用上面的实例方法。
|
||||||
|
|
||||||
|
```html
|
||||||
|
<!-- 通过 ref 属性将组件绑定到 this.$refs.checkbox 上 -->
|
||||||
|
<van-checkbox v-model="checked" ref="checkbox">
|
||||||
|
复选框
|
||||||
|
</van-checkbox>
|
||||||
|
```
|
||||||
|
|
||||||
|
```js
|
||||||
|
export default {
|
||||||
|
data() {
|
||||||
|
return {
|
||||||
|
checked: false,
|
||||||
|
};
|
||||||
|
},
|
||||||
|
// 注意：组件挂载后才能访问到 ref 对象
|
||||||
|
mounted() {
|
||||||
|
this.$refs.checkbox.toggle();
|
||||||
|
},
|
||||||
|
};
|
||||||
|
```
|
||||||
@ -122,30 +122,3 @@ Vue.use(Vant);
|
|||||||
```
|
```
|
||||||
|
|
||||||
> If you configured babel-plugin-import, you won't be allowed to import all components.
|
> If you configured babel-plugin-import, you won't be allowed to import all components.
|
||||||
|
|
||||||
## Other
|
|
||||||
|
|
||||||
### Rem units
|
|
||||||
|
|
||||||
Vant use `px` as size units by default，you can use tools such as `postcss-pxtorem` to transform units to `rem`.
|
|
||||||
|
|
||||||
- [postcss-pxtorem](https://github.com/cuth/postcss-pxtorem)
|
|
||||||
- [lib-flexible](https://github.com/amfe/lib-flexible)
|
|
||||||
|
|
||||||
#### PostCSS Config
|
|
||||||
|
|
||||||
postcss config example:
|
|
||||||
|
|
||||||
```js
|
|
||||||
module.exports = {
|
|
||||||
plugins: {
|
|
||||||
autoprefixer: {
|
|
||||||
browsers: ['Android >= 4.0', 'iOS >= 8'],
|
|
||||||
},
|
|
||||||
'postcss-pxtorem': {
|
|
||||||
rootValue: 37.5,
|
|
||||||
propList: ['*'],
|
|
||||||
},
|
|
||||||
},
|
|
||||||
};
|
|
||||||
```
|
|
||||||
|
|||||||
@ -2,7 +2,7 @@
|
|||||||
|
|
||||||
### 介绍
|
### 介绍
|
||||||
|
|
||||||
通过本章节你可以了解到 Vant 的安装方式和组件使用方法。
|
通过本章节你可以了解到 Vant 的安装方法和基本使用姿势。
|
||||||
|
|
||||||
## 安装
|
## 安装
|
||||||
|
|
||||||
@ -149,93 +149,6 @@ Vue.use(Vant);
|
|||||||
|
|
||||||
> Tips: 配置按需引入后，将不允许直接导入所有组件。
|
> Tips: 配置按需引入后，将不允许直接导入所有组件。
|
||||||
|
|
||||||
## 进阶用法
|
|
||||||
|
|
||||||
### Rem 适配
|
|
||||||
|
|
||||||
Vant 中的样式默认使用 `px` 作为单位，如果需要使用 `rem` 单位，推荐使用以下两个工具：
|
|
||||||
|
|
||||||
- [postcss-pxtorem](https://github.com/cuth/postcss-pxtorem) 是一款 postcss 插件，用于将单位转化为 rem
|
|
||||||
- [lib-flexible](https://github.com/amfe/lib-flexible) 用于设置 rem 基准值
|
|
||||||
|
|
||||||
#### PostCSS 配置
|
|
||||||
|
|
||||||
下面提供了一份基本的 postcss 配置，可以在此配置的基础上根据项目需求进行修改。
|
|
||||||
|
|
||||||
```js
|
|
||||||
module.exports = {
|
|
||||||
plugins: {
|
|
||||||
autoprefixer: {
|
|
||||||
browsers: ['Android >= 4.0', 'iOS >= 8'],
|
|
||||||
},
|
|
||||||
'postcss-pxtorem': {
|
|
||||||
rootValue: 37.5,
|
|
||||||
propList: ['*'],
|
|
||||||
},
|
|
||||||
},
|
|
||||||
};
|
|
||||||
```
|
|
||||||
|
|
||||||
> Tips: 在配置 postcss-loader 时，应避免 ignore node_modules 目录，否则将导致 Vant 样式无法被编译。
|
|
||||||
|
|
||||||
### 在桌面端使用
|
|
||||||
|
|
||||||
Vant 是一个面向移动端的组件库，因此默认只适配了移动端设备，这意味着组件只监听了移动端的`touch`事件，没有监听桌面端的`mouse`事件。
|
|
||||||
|
|
||||||
如果你需要在桌面端使用 Vant，可以引入我们提供的 [@vant/touch-emulator](https://github.com/youzan/vant/tree/dev/packages/vant-touch-emulator)，这个库会在桌面端自动将`mouse`事件转换成对应的`touch`事件，使得组件能够在桌面端使用。
|
|
||||||
|
|
||||||
```bash
|
|
||||||
# 安装模块
|
|
||||||
npm i @vant/touch-emulator -S
|
|
||||||
```
|
|
||||||
|
|
||||||
```js
|
|
||||||
// 引入模块后自动生效
|
|
||||||
import '@vant/touch-emulator';
|
|
||||||
```
|
|
||||||
|
|
||||||
### 底部安全区适配
|
|
||||||
|
|
||||||
iPhone X 等机型底部存在底部指示条，指示条的操作区域与页面底部存在重合，容易导致用户误操作，因此我们需要针对这些机型进行底部安全区适配。Vant 中部分组件提供了`safe-area-inset-bottom`属性，设置该属性后，即可在对应的机型上开启适配，如下示例：
|
|
||||||
|
|
||||||
```html
|
|
||||||
<!-- 在 head 标签中添加 meta 标签，并设置 viewport-fit=cover 值 -->
|
|
||||||
<meta
|
|
||||||
name="viewport"
|
|
||||||
content="width=device-width, initial-scale=1.0, maximum-scale=1.0, minimum-scale=1.0, viewport-fit=cover"
|
|
||||||
/>
|
|
||||||
|
|
||||||
<!-- 开启 safe-area-inset-bottom 属性 -->
|
|
||||||
<van-number-keyboard safe-area-inset-bottom />
|
|
||||||
```
|
|
||||||
|
|
||||||
<img src="https://b.yzcdn.cn/vant/safearea.png">
|
|
||||||
|
|
||||||
### 组件实例方法
|
|
||||||
|
|
||||||
Vant 中的许多组件提供了实例方法，调用实例方法时，我们需要通过 [ref](https://cn.vuejs.org/v2/api/#ref) 来注册组件引用信息，引用信息将会注册在父组件的`$refs`对象上。注册完成后，我们可以通过`this.$refs.xxx`访问到对应的组件实例，并调用上面的实例方法。
|
|
||||||
|
|
||||||
```html
|
|
||||||
<!-- 将该组件绑定到 this.$refs.checkbox 上 -->
|
|
||||||
<van-checkbox v-model="checked" ref="checkbox">
|
|
||||||
复选框
|
|
||||||
</van-checkbox>
|
|
||||||
```
|
|
||||||
|
|
||||||
```js
|
|
||||||
export default {
|
|
||||||
data() {
|
|
||||||
return {
|
|
||||||
checked: false,
|
|
||||||
};
|
|
||||||
},
|
|
||||||
// 注意：组件挂载后才能访问到 ref 对象
|
|
||||||
mounted() {
|
|
||||||
this.$refs.checkbox.toggle();
|
|
||||||
},
|
|
||||||
};
|
|
||||||
```
|
|
||||||
|
|
||||||
## 常见问题
|
## 常见问题
|
||||||
|
|
||||||
### 在 HTML 中无法正确渲染组件？
|
### 在 HTML 中无法正确渲染组件？
|
||||||
|
|||||||
@ -63,6 +63,10 @@ module.exports = {
|
|||||||
path: 'quickstart',
|
path: 'quickstart',
|
||||||
title: '快速上手',
|
title: '快速上手',
|
||||||
},
|
},
|
||||||
|
{
|
||||||
|
path: 'advanced-usage',
|
||||||
|
title: '进阶用法',
|
||||||
|
},
|
||||||
{
|
{
|
||||||
path: 'changelog',
|
path: 'changelog',
|
||||||
title: '更新日志',
|
title: '更新日志',
|
||||||
@ -422,6 +426,10 @@ module.exports = {
|
|||||||
path: 'quickstart',
|
path: 'quickstart',
|
||||||
title: 'Quickstart',
|
title: 'Quickstart',
|
||||||
},
|
},
|
||||||
|
{
|
||||||
|
path: 'advanced-usage',
|
||||||
|
title: 'Advanced Usage',
|
||||||
|
},
|
||||||
{
|
{
|
||||||
path: 'changelog',
|
path: 'changelog',
|
||||||
title: 'Changelog',
|
title: 'Changelog',
|
||||||
|
|||||||
Loading…
x
Reference in New Issue
Block a user