From 000ea342a8a4f74e2ce612c1318c6d097320e510 Mon Sep 17 00:00:00 2001 From: chenjiahan Date: Sat, 24 Oct 2020 17:20:04 +0800 Subject: [PATCH] docs: add advanced usage guide --- docs/markdown/advanced-usage.en-US.md | 28 ++++++++ docs/markdown/advanced-usage.zh-CN.md | 94 +++++++++++++++++++++++++++ docs/markdown/quickstart.en-US.md | 27 -------- docs/markdown/quickstart.zh-CN.md | 89 +------------------------ vant.config.js | 8 +++ 5 files changed, 131 insertions(+), 115 deletions(-) create mode 100644 docs/markdown/advanced-usage.en-US.md create mode 100644 docs/markdown/advanced-usage.zh-CN.md diff --git a/docs/markdown/advanced-usage.en-US.md b/docs/markdown/advanced-usage.en-US.md new file mode 100644 index 000000000..67bcf2556 --- /dev/null +++ b/docs/markdown/advanced-usage.en-US.md @@ -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: ['*'], + }, + }, +}; +``` diff --git a/docs/markdown/advanced-usage.zh-CN.md b/docs/markdown/advanced-usage.zh-CN.md new file mode 100644 index 000000000..d68d94c7c --- /dev/null +++ b/docs/markdown/advanced-usage.zh-CN.md @@ -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 + + + + + +``` + + + +## 组件用法 + +### 组件实例方法 + +Vant 中的许多组件提供了实例方法，调用实例方法时，我们需要通过 [ref](https://cn.vuejs.org/v2/api/#ref) 来注册组件引用信息，引用信息将会注册在父组件的`$refs`对象上。注册完成后，我们可以通过`this.$refs.xxx`访问到对应的组件实例，并调用上面的实例方法。 + +```html + + + 复选框 + +``` + +```js +export default { + data() { + return { + checked: false, + }; + }, + // 注意：组件挂载后才能访问到 ref 对象 + mounted() { + this.$refs.checkbox.toggle(); + }, +}; +``` diff --git a/docs/markdown/quickstart.en-US.md b/docs/markdown/quickstart.en-US.md index 76cd26308..4fbd04b8c 100644 --- a/docs/markdown/quickstart.en-US.md +++ b/docs/markdown/quickstart.en-US.md @@ -122,30 +122,3 @@ Vue.use(Vant); ``` > 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: ['*'], - }, - }, -}; -``` diff --git a/docs/markdown/quickstart.zh-CN.md b/docs/markdown/quickstart.zh-CN.md index 352df67c6..78e2f4ca0 100644 --- a/docs/markdown/quickstart.zh-CN.md +++ b/docs/markdown/quickstart.zh-CN.md @@ -2,7 +2,7 @@ ### 介绍 -通过本章节你可以了解到 Vant 的安装方式和组件使用方法。 +通过本章节你可以了解到 Vant 的安装方法和基本使用姿势。 ## 安装 @@ -149,93 +149,6 @@ Vue.use(Vant); > 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 - - - - - -``` - - - -### 组件实例方法 - -Vant 中的许多组件提供了实例方法，调用实例方法时，我们需要通过 [ref](https://cn.vuejs.org/v2/api/#ref) 来注册组件引用信息，引用信息将会注册在父组件的`$refs`对象上。注册完成后，我们可以通过`this.$refs.xxx`访问到对应的组件实例，并调用上面的实例方法。 - -```html - - - 复选框 - -``` - -```js -export default { - data() { - return { - checked: false, - }; - }, - // 注意：组件挂载后才能访问到 ref 对象 - mounted() { - this.$refs.checkbox.toggle(); - }, -}; -``` - ## 常见问题 ### 在 HTML 中无法正确渲染组件？ diff --git a/vant.config.js b/vant.config.js index 713773291..e009c8527 100644 --- a/vant.config.js +++ b/vant.config.js @@ -63,6 +63,10 @@ module.exports = { path: 'quickstart', title: '快速上手', }, + { + path: 'advanced-usage', + title: '进阶用法', + }, { path: 'changelog', title: '更新日志', @@ -422,6 +426,10 @@ module.exports = { path: 'quickstart', title: 'Quickstart', }, + { + path: 'advanced-usage', + title: 'Advanced Usage', + }, { path: 'changelog', title: 'Changelog',