Merge branch '2.x' into dev

AydenGen · Oct 24, 2020 · 5e00ab9 · 5e00ab9
2 parents 5ebecc6 + 386956b
commit 5e00ab9
Show file tree

Hide file tree

Showing 36 changed files with 222 additions and 162 deletions.
diff --git a/README.md b/README.md
@@ -29,8 +29,9 @@
 
 ## Features
 
-- 60+ Reusable components
-- 90% Unit test coverage
+- 65+ Reusable components
+- 4kb Component average size
+- 90%+ Unit test coverage
 - Extensive documentation and demos
 - Support [babel-plugin-import](https://github.com/ant-design/babel-plugin-import)
 - Support Custom Theme

diff --git a/README.zh-CN.md b/README.zh-CN.md
@@ -26,19 +26,20 @@
 
 ### 介绍
 
-Vant 是**有赞前端团队**开源的移动端组件库，于 2016 年开源，已持续维护 4 年时间。Vant 对内承载了有赞所有核心业务，对外服务十多万开发者，是业界主流的移动端组件库之一。
+Vant 是**有赞前端团队**开源的移动端组件库，于 2017 年开源，已持续维护 4 年时间。Vant 对内承载了有赞所有核心业务，对外服务十多万开发者，是业界主流的移动端组件库之一。
 
 目前 Vant 官方提供了 [Vue 版本](https://vant-contrib.gitee.io/vant)和[微信小程序版本](http://vant-contrib.gitee.io/vant-weapp)，并由社区团队维护 [React 版本](https://github.com/mxdi9i7/vant-react)。
 
 ## 特性
 
-- 60+ 高质量组件，覆盖移动端各类场景
-- 90%+ 单元测试覆盖率，提供稳定性保障
+- 提供 60 多个高质量组件，覆盖移动端各类场景
+- 性能极佳，组件平均体积不到 4kb
+- 单元测试覆盖率 90%+，提供稳定性保障
 - 完善的中英文文档和示例
 - 支持按需引入
 - 支持主题定制
 - 支持国际化
-- 支持 TS
+- 支持 TypeScript
 - 支持 SSR
 
 ## 安装

diff --git a/docs/markdown/advanced-usage.en-US.md b/docs/markdown/advanced-usage.en-US.md
@@ -0,0 +1,42 @@
+# Advanced Usage
+
+## Browser adaptation
+
+### Rem Units
+
+Vant uses `px` unit 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: ['*'],
+    },
+  },
+};
+```
+
+### Adapt to PC Browsers
+
+Vant is a mobile-first component library, if you want to use Vant in PC browsers, you can use the [@vant/touch-emulator](https://github.com/youzan/vant/tree/dev/packages/vant-touch-emulator) module. This module will automatically convert the mouse events of the PC browser into the touch events of the mobile browser.
+
+```bash
+# Install
+npm i @vant/touch-emulator -S
+```
+
+```js
+// Just import this module, then Vant works in PC browser
+import '@vant/touch-emulator';
+```
diff --git a/docs/markdown/advanced-usage.zh-CN.md b/docs/markdown/advanced-usage.zh-CN.md
@@ -0,0 +1,120 @@
+# 进阶用法
+
+### 介绍
+
+通过本章节你可以了解到 Vant 的一些进阶用法，比如组件插槽用法、多种浏览器适配方式。
+
+## 组件用法
+
+### 组件插槽
+
+Vant 提供了丰富的组件插槽，通过插槽可以对组件的某一部分进行个性化定制。如果你对 Vue 的插槽不太熟悉，可以阅读 Vue 官方文档中的[插槽章节](https://cn.vuejs.org/v2/guide/components-slots.html)。下面是通过插槽来定制 Checkbox 图标的示例：
+
+```html
+<van-checkbox v-model="checked">
+  <!-- 使用组件提供的 icon 插槽 -->
+  <!-- 将默认图标替换为个性化图片 -->
+  <template #icon="props">
+    <img :src="props.checked ? activeIcon : inactiveIcon" />
+  </template>
+</van-checkbox>
+```
+
+```js
+export default {
+  data() {
+    return {
+      checked: true,
+      activeIcon: 'https://img.yzcdn.cn/vant/user-active.png',
+      inactiveIcon: 'https://img.yzcdn.cn/vant/user-inactive.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();
+  },
+};
+```
+
+## 浏览器适配
+
+### 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://img.yzcdn.cn/vant/safearea.png">
diff --git a/docs/markdown/home.en-US.md b/docs/markdown/home.en-US.md
@@ -8,8 +8,9 @@
 
 ### Features
 
-- 60+ Reusable components
-- 90% Unit test coverage
+- 65+ Reusable components
+- 4kb Component average size
+- 90%+ Unit test coverage
 - Extensive documentation and demos
 - Support [babel-plugin-import](https://github.com/ant-design/babel-plugin-import)
 - Support Custom Theme

diff --git a/docs/markdown/home.zh-CN.md b/docs/markdown/home.zh-CN.md
@@ -8,14 +8,15 @@
 
 ### 介绍
 
-Vant 是**有赞前端团队**开源的移动端组件库，于 2016 年开源，已持续维护 4 年时间。Vant 对内承载了有赞所有核心业务，对外服务十多万开发者，是业界主流的移动端组件库之一。 <br><br>
+Vant 是**有赞前端团队**开源的移动端组件库，于 2017 年开源，已持续维护 4 年时间。Vant 对内承载了有赞所有核心业务，对外服务十多万开发者，是业界主流的移动端组件库之一。 <br><br>
 
 目前 Vant 官方提供了 [Vue 版本](https://vant-contrib.gitee.io/vant)和[微信小程序版本](http://vant-contrib.gitee.io/vant-weapp)，并由社区团队维护 [React 版本](https://github.com/mxdi9i7/vant-react)。
 
 ### 特性
 
-- 60+ 高质量组件，覆盖移动端各类场景
-- 90%+ 单元测试覆盖率，提供稳定性保障
+- 提供 60 多个高质量组件，覆盖移动端各类场景
+- 性能极佳，组件平均体积不到 4kb
+- 单元测试覆盖率 90%+，提供稳定性保障
 - 完善的中英文文档和示例
 - 支持按需引入
 - 支持主题定制

diff --git a/docs/markdown/quickstart.en-US.md b/docs/markdown/quickstart.en-US.md
@@ -124,30 +124,3 @@ app.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
@@ -2,7 +2,7 @@
 
 ### 介绍
 
-通过本章节你可以了解到 Vant 的安装方式和组件使用方法。
+通过本章节你可以了解到 Vant 的安装方法和基本使用姿势。
 
 ## 安装
 
@@ -151,93 +151,6 @@ app.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
-<!-- 在 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 中无法正确渲染组件？

diff --git a/src/action-bar/README.zh-CN.md b/src/action-bar/README.zh-CN.md
@@ -87,7 +87,7 @@ export default {
 
 | 参数 | 说明 | 类型 | 默认值 |
 | --- | --- | --- | --- |
-| safe-area-inset-bottom | 是否开启[底部安全区适配](#/zh-CN/quickstart#di-bu-an-quan-qu-gua-pei) | _boolean_ | `true` |
+| safe-area-inset-bottom | 是否开启[底部安全区适配](#/zh-CN/advanced-usage#di-bu-an-quan-qu-gua-pei) | _boolean_ | `true` |
 
 ### ActionBarIcon Props
 

diff --git a/src/action-sheet/README.zh-CN.md b/src/action-sheet/README.zh-CN.md
@@ -172,7 +172,7 @@ export default {
 | close-on-popstate `v2.5.3` | 是否在页面回退时自动关闭 | _boolean_ | `false` |
 | close-on-click-action | 是否在点击选项后关闭 | _boolean_ | `false` |
 | close-on-click-overlay | 是否在点击遮罩层后关闭 | _boolean_ | `true` |
-| safe-area-inset-bottom | 是否开启[底部安全区适配](#/zh-CN/quickstart#di-bu-an-quan-qu-gua-pei) | _boolean_ | `true` |
+| safe-area-inset-bottom | 是否开启[底部安全区适配](#/zh-CN/advanced-usage#di-bu-an-quan-qu-gua-pei) | _boolean_ | `true` |
 | teleport | 指定挂载的节点，[用法示例](#/zh-CN/popup#zhi-ding-gua-zai-wei-zhi) | _string \| Element_ | - |
 
 ### Action 数据结构

diff --git a/src/address-edit/README.zh-CN.md b/src/address-edit/README.zh-CN.md
@@ -117,7 +117,7 @@ export default {
 
 ### 方法
 
-通过 ref 可以获取到 AddressEdit 实例并调用实例方法，详见[组件实例方法](#/zh-CN/quickstart#zu-jian-shi-li-fang-fa)。
+通过 ref 可以获取到 AddressEdit 实例并调用实例方法，详见[组件实例方法](#/zh-CN/advanced-usage#zu-jian-shi-li-fang-fa)。
 
 | 方法名           | 说明         | 参数                  | 返回值 |
 | ---------------- | ------------ | --------------------- | ------ |