From 4c1c786ae62fc79cd15a951aec3328bc63a1fe3c Mon Sep 17 00:00:00 2001
From: chenjiahan <chenjiahan@youzan.com>
Date: Sun, 20 Dec 2020 20:15:59 +0800
Subject: [PATCH] docs(Cascader): add demos

---
 src/cascader/README.md                       |  82 +++++++++++--
 src/cascader/README.zh-CN.md                 |  53 +++++++-
 src/cascader/demo/area-en-US.js              | 122 +++++++++++++++++++
 src/cascader/demo/{area.js => area-zh-CN.js} |   0
 src/cascader/demo/index.vue                  |   4 +-
 src/cascader/index.js                        |   2 +-
 src/cascader/index.less                      |   4 +
 src/locale/lang/zh-CN.ts                     |   2 +-
 8 files changed, 255 insertions(+), 14 deletions(-)
 create mode 100644 src/cascader/demo/area-en-US.js
 rename src/cascader/demo/{area.js => area-zh-CN.js} (100%)

diff --git a/src/cascader/README.md b/src/cascader/README.md
index f530c2937..bdedcb349 100644
--- a/src/cascader/README.md
+++ b/src/cascader/README.md
@@ -1,7 +1,5 @@
 # Cascader
 
-### Intro
-
 ### Install
 
 ```js
@@ -16,7 +14,64 @@ Vue.use(Cascader);
 ### Basic Usage
 
 ```html
-<van-area title="Title" :area-list="areaList" />
+<van-field
+  is-link
+  readonly
+  label="Area"
+  :value="fieldValue"
+  placeholder="Select Area"
+  @click="show = true"
+/>
+<van-popup v-model="show" round position="bottom">
+  <van-cascader
+    v-model="cascaderValue"
+    title="Select Area"
+    @close="show = false"
+    @finish="onFinish"
+  />
+</van-popup>
+```
+
+```js
+export default {
+  data() {
+    return {
+      show: false,
+      fieldValue: '',
+      cascaderValue: '',
+      options: [
+        {
+          text: 'Zhejiang',
+          value: '330000',
+          children: [{ text: 'Hangzhou', value: '330100' }],
+        },
+        {
+          text: 'Jiangsu',
+          value: '320000',
+          children: [{ text: 'Nanjing', value: '320100' }],
+        },
+      ],
+    };
+  },
+  methods: {
+    onFinish(params) {
+      const { selectedOptions } = params;
+      this.fieldValue = selectedOptions.map((option) => option.text).join('/');
+    },
+  },
+};
+```
+
+### Custom Color
+
+```html
+<van-cascader
+  v-model="cascaderValue"
+  title="Select Area"
+  active-color="#1989fa"
+  @close="show = false"
+  @finish="onFinish"
+/>
 ```
 
 ## API
@@ -24,17 +79,24 @@ Vue.use(Cascader);
 ### Props
 
 | Attribute | Description | Type | Default |
-| --------- | ----------- | ---- | ------- |
-
+| --- | --- | --- | --- |
+| title | Title | _string_ | - |
+| value | Values of selected options | _string \| number_ | - |
+| options | Options | _Option[]_ | `[]` |
+| placeholder | Placeholder of unselected tab | _string_ | `Select` |
+| active-color | Active color | _string_ | `#ee0a24` |
+| closeable | Whether to show close icon | _boolean_ | `true` |
 
 ### Events
 
 | Event | Description | Arguments |
-| ----- | ----------- | --------- |
-
+| --- | --- | --- |
+| change | Emitted when active option changed | `{ value, selectedOptions, tabIndex }` |
+| finish | Emitted when all options is selected | `{ value, selectedOptions, tabIndex }` |
+| close | Emmitted when the close icon is clicked | - |
 
 ### Slots
 
-| Name | Description |
-| ---- | ----------- |
-
+| Name  | Description  |
+| ----- | ------------ |
+| title | Custom title |
diff --git a/src/cascader/README.zh-CN.md b/src/cascader/README.zh-CN.md
index ddcce28e2..7784b9893 100644
--- a/src/cascader/README.zh-CN.md
+++ b/src/cascader/README.zh-CN.md
@@ -17,9 +17,24 @@ Vue.use(Cascader);
 
 ### 基础用法
 
+级联选择组件可以搭配 Field 和 Popup 组件使用，示例如下：
+
 ```html
+<van-field
+  is-link
+  readonly
+  label="地区"
+  :value="fieldValue"
+  placeholder="请选择地区"
+  @click="show = true"
+/>
 <van-popup v-model="show" round position="bottom">
-  <van-cascader title="请选择地区" />
+  <van-cascader
+    v-model="cascaderValue"
+    title="请选择地区"
+    @close="show = false"
+    @finish="onFinish"
+  />
 </van-popup>
 ```
 
@@ -28,11 +43,47 @@ export default {
   data() {
     return {
       show: false,
+      fieldValue: '',
+      cascaderValue: '',
+      // 选项列表，children 代表子选项，支持多级嵌套
+      options: [
+        {
+          text: '浙江省',
+          value: '330000',
+          children: [{ text: '杭州市', value: '330100' }],
+        },
+        {
+          text: '江苏省',
+          value: '320000',
+          children: [{ text: '南京市', value: '320100' }],
+        },
+      ],
     };
   },
+  methods: {
+    // 全部选项选择完毕后，会触发 finish 事件
+    onFinish(params) {
+      const { selectedOptions } = params;
+      this.fieldValue = selectedOptions.map((option) => option.text).join('/');
+    },
+  },
 };
 ```
 
+### 自定义颜色
+
+通过 `active-color` 属性来设置选中状态的高亮颜色。
+
+```html
+<van-cascader
+  v-model="cascaderValue"
+  title="请选择地区"
+  active-color="#1989fa"
+  @close="show = false"
+  @finish="onFinish"
+/>
+```
+
 ## API
 
 ### Props
diff --git a/src/cascader/demo/area-en-US.js b/src/cascader/demo/area-en-US.js
new file mode 100644
index 000000000..8f0fa88be
--- /dev/null
+++ b/src/cascader/demo/area-en-US.js
@@ -0,0 +1,122 @@
+export default [
+  {
+    text: 'Zhejiang',
+    value: '330000',
+    children: [
+      {
+        text: 'Hangzhou',
+        value: '330100',
+        children: [
+          {
+            text: 'Shangcheng',
+            value: '330102',
+          },
+          {
+            text: 'Xiacheng',
+            value: '330103',
+          },
+          {
+            text: 'Jianggan',
+            value: '330104',
+          },
+        ],
+      },
+      {
+        text: 'Ningbo',
+        value: '330200',
+        children: [
+          {
+            text: 'Haishu',
+            value: '330203',
+          },
+          {
+            text: 'Jiangbei',
+            value: '330205',
+          },
+          {
+            text: 'Beilun',
+            value: '330206',
+          },
+        ],
+      },
+      {
+        text: 'Wenzhou',
+        value: '330300',
+        children: [
+          {
+            text: 'Lucheng',
+            value: '330302',
+          },
+          {
+            text: 'Longwan',
+            value: '330303',
+          },
+          {
+            text: 'Ouhai',
+            value: '330304',
+          },
+        ],
+      },
+    ],
+  },
+  {
+    text: 'Jiangsu',
+    value: '320000',
+    children: [
+      {
+        text: 'Nanjing',
+        value: '320100',
+        children: [
+          {
+            text: 'Xuanwu',
+            value: '320102',
+          },
+          {
+            text: 'Qinghuai',
+            value: '320104',
+          },
+          {
+            text: 'Jianye',
+            value: '320105',
+          },
+        ],
+      },
+      {
+        text: 'Wuxi',
+        value: '320200',
+        children: [
+          {
+            text: 'Xishan',
+            value: '320205',
+          },
+          {
+            text: 'Huishan',
+            value: '320206',
+          },
+          {
+            text: 'Binhu',
+            value: '320211',
+          },
+        ],
+      },
+      {
+        text: 'Xuzhou',
+        value: '320300',
+        children: [
+          {
+            text: 'Gulou',
+            value: '320302',
+          },
+          {
+            text: 'Yunlong',
+            value: '320303',
+          },
+          {
+            text: 'Jiawang',
+            value: '320305',
+          },
+        ],
+      },
+    ],
+  },
+];
diff --git a/src/cascader/demo/area.js b/src/cascader/demo/area-zh-CN.js
similarity index 100%
rename from src/cascader/demo/area.js
rename to src/cascader/demo/area-zh-CN.js
diff --git a/src/cascader/demo/index.vue b/src/cascader/demo/index.vue
index 7ae0bf22b..69f2c9246 100644
--- a/src/cascader/demo/index.vue
+++ b/src/cascader/demo/index.vue
@@ -44,7 +44,8 @@
 </template>
 
 <script>
-import zhCNOptions from './area';
+import zhCNOptions from './area-zh-CN';
+import enUSOptions from './area-en-US';
 
 export default {
   i18n: {
@@ -56,6 +57,7 @@ export default {
     },
     'en-US': {
       area: 'Area',
+      options: enUSOptions,
       selectArea: 'Select Area',
       customColor: 'Custom Color',
     },
diff --git a/src/cascader/index.js b/src/cascader/index.js
index b8c3e155d..949da0ce9 100644
--- a/src/cascader/index.js
+++ b/src/cascader/index.js
@@ -197,7 +197,7 @@ export default createComponent({
       const { options, selectedOption } = item;
       const title = selectedOption
         ? selectedOption.text
-        : this.placeholder || this.t('placeholder');
+        : this.placeholder || this.t('select');
 
       return (
         <Tab
diff --git a/src/cascader/index.less b/src/cascader/index.less
index d1728d543..ace475d9c 100644
--- a/src/cascader/index.less
+++ b/src/cascader/index.less
@@ -18,6 +18,10 @@
   &__close-icon {
     color: @gray-5;
     font-size: 22px;
+
+    &:active {
+      color: @gray-6;
+    }
   }
 
   &__tabs {
diff --git a/src/locale/lang/zh-CN.ts b/src/locale/lang/zh-CN.ts
index 3adfbdc84..35692b09e 100644
--- a/src/locale/lang/zh-CN.ts
+++ b/src/locale/lang/zh-CN.ts
@@ -23,7 +23,7 @@ export default {
     rangePrompt: (maxRange: number) => `选择天数不能超过 ${maxRange} 天`,
   },
   vanCascader: {
-    placeholder: '请选择',
+    select: '请选择',
   },
   vanContactCard: {
     addText: '添加联系人',