From d6a3bcbb1606507b3a15ebe7c30d6b5a8990bcd7 Mon Sep 17 00:00:00 2001
From: xiaodemen <fuq_pr@163.com>
Date: Thu, 6 May 2021 12:14:38 +0800
Subject: [PATCH] docs: add docs for cascader

Change-Id: Id5f4d5287f18417e91ff3986f1ab48354ab5bba8
---
 one/docs/components/cascader.md       | 278 ++++++++++++++++++++++++++
 one/docs/demo/cascader/inline.vue     | 128 ++++++++++++
 one/docs/demo/cascader/multiple.vue   | 194 ++++++++++++++++++
 one/docs/demo/cascader/searchable.vue | 128 ++++++++++++
 one/docs/demo/cascader/size.vue       | 153 ++++++++++++++
 one/docs/nav.json                     |   4 +
 6 files changed, 885 insertions(+)
 create mode 100644 one/docs/components/cascader.md
 create mode 100644 one/docs/demo/cascader/inline.vue
 create mode 100644 one/docs/demo/cascader/multiple.vue
 create mode 100644 one/docs/demo/cascader/searchable.vue
 create mode 100644 one/docs/demo/cascader/size.vue

diff --git a/one/docs/components/cascader.md b/one/docs/components/cascader.md
new file mode 100644
index 0000000..25ee219
--- /dev/null
+++ b/one/docs/components/cascader.md
@@ -0,0 +1,278 @@
+# Cascader <small>级联器</small>
+
+
+## 示例
+
+### 尺寸
+
+可选的尺寸 `ui` 属性值：`xs`/`s`/`m`/`l`。
+
+[[ demo src="/demo/cascader/size.vue" ]]
+
+### 内联模式
+
+使用 `inline` 属性来开启内联模式。
+
+[[ demo src="/demo/cascader/inline.vue" ]]
+
+### 搜索选项
+
+使用 `searchable` 属性来开启选项搜索。
+
+[[ demo src="/demo/cascader/searchable.vue" ]]
+
+### 多选
+
+使用 `multiple` 属性来开启多选模式。
+
+[[ demo src="/demo/cascader/multiple.vue" ]]
+
+## API
+
+### 属性
+
+| 名称 | 类型 | 默认值 | 描述 |
+| -- | -- | -- | -- |
+| `ui` | `string=` | - | [^ui] |
+| `options` | `Array<Object>` | - | [^options] |
+| `value` | `Array<*>|*` | - | [^value] |
+| `multiple` | `boolean` | `false` | 是否允许多选。 |
+| `inline` | `boolean` | `false` | 下拉面板是否内联展示。 |
+| `max` | `number` | - | 多选时允许选择的项目上限。 |
+| `placeholder` | `string` | `cascader.placeholder` | 未选择时的占位文本。 |
+| `clearable` | `boolean` | `false` | 是否可以清除已选内容。 |
+| `searchable` | `boolean` | `false` | 是否允许搜索选项。 |
+| `filter` | `function` | - | 选项过滤函数，签名为 `function(option: Object): boolean`。`option` 类型与 `options` 属性中的项相同。返回值表示是否将结果保留在下拉选项列表中。 |
+| `expanded` | `boolean=` | `false` | [^expanded] |
+| `column-trigger` | `hover | click` | `click` | [^column-trigger] |
+| `select-mode` | `'leaf-only' | 'any'` | `any` | [^select-mode] |
+| `column-width` | `number|string` | - | [^column-width] |
+| `show-select-all` | `boolean` | `false` | 在多选模式下是否有全选按钮。 |
+| `value-display` | `'complete' | 'simple'` | `simple` | [^value-display] |
+| `disabled` | `boolean=` | `false` | 是否为禁用状态。 |
+| `readonly` | `boolean=` | `false` | 是否为只读状态。 |
+| `overlay-class` | `string|Array|Object=` | - | 参考 [Overlay](./overlay) 组件的 [`overlay-class` 属性](./overlay#属性)。 |
+
+^^^ui
+预设样式。
+
++++枚举值
+| 值 | 描述 |
+| -- | -- |
+| `xs` | 超小尺寸样式。 |
+| `s` | 小尺寸样式。 |
+| `m` | 中尺寸样式。 |
+| `l` | 大尺寸样式。 |
++++
+^^^
+
+^^^options
+选项列表，项目的类型为 `{label, value, options, disabled, position, ...}`。
+
++++字段详情
+| 名称 | 类型 | 描述 |
+| -- | -- | -- |
+| `label` | `string` | 选项的文字说明。 |
+| `value` | `*` | 选项对应的值。 |
+| `position` | `string` | 下级节点如何展示，默认弹出，可以设置 `inline` 来内联显示。 |
+| `options` | `Array<Object>=` | 选项的子选项数组，数组项类型同 `options` 属性数组项。 |
+| `disabled` | `boolean=` | 选项是否为禁用。 |
++++
+^^^
+
+^^^value
+:::badges
+`v-model`
+:::
+
+已选值。
+^^^
+
+^^^expanded
+:::badges
+`.sync`
+:::
+
+下拉菜单是否展开。
+^^^
+
+^^^column-trigger
+下拉面板中下级的展开时机。
+
++++枚举值
+| 值 | 描述 |
+| -- | -- |
+| `hover` | hover展开下一级。 |
+| `click` | 点击展开下一级。 |
++++
+^^^
+
+^^^select-mode
+在单选模式下控制哪些项目可以选中。
+
++++枚举值
+| 值 | 描述 |
+| -- | -- |
+| `leaf-only` | 只有叶子节点可以选中。 |
+| `any` | 每一级都可以选中。 |
++++
+^^^
+
+^^^column-width
+当下拉面板中有多列时，统一控制除了最后一列之外的列宽度。
+
+当该值是数值或者能转换成数值时，会当成像素值。
+^^^
+
+^^^value-display
+控制选中值如何展示。
+
++++枚举值
+| 值 | 描述 |
+| -- | -- |
+| `complete` | 完整展示选中值的父子路径，如`中国 > 上海`。 |
+| `simple` | 仅仅展示选中值。 |
++++
+^^^
+
+### 插槽
+
+| 名称 | 描述 |
+| -- | -- |
+| `trigger` | [^slot-trigger] |
+| `pane` | 下拉面板中的内容插槽。用域参数同 `trigger` 插槽。 |
+| `before` | 选项列表前的内容。无默认内容。作用域参数同 `trigger` 插槽。 |
+| `after` | 选项列表后的内容。无默认内容。作用域参数同 `trigger` 插槽。 |
+| `column-before` | [^slot-column-before] |
+| `column-after` | 下拉面板中每列后的区域。无默认内容。作用域参数同 `column-before` 插槽。 |
+| `label` | [^slot-label] |
+| `option-label` | [^slot-option-label] |
+| `option` | [^slot-option] |
+| `selected` | [^slot-selected] |
+
+^^^slot-trigger
+整个下拉触发区域。
+
+默认内容：下拉按钮。
+
++++作用域参数
+| 名称 | 类型 | 描述 |
+| -- | -- | -- |
+| `value` | `*` | 已选项值。 |
+| `selected` | `object` | 已选项 |
+| `expanded` | `boolean` | 下拉菜单是否展开。 |
+| `keyword` | `string` | 搜索值。 |
+| `select` | `function(value: *): void` | 用于设置已选项。 |
+| `updateExpanded` | `function(expanded: boolean): void` | 用于切换下拉菜单展开状态。 |
+| `clearSelected` | `function(): void` | 用于清除已选项。 |
+| `removeSelected` | `function(option: object): void` | 用于删除某个已选项，参数 `option` 是该已选项。 |
+| `updateKeyword` | `function(keyword: string): void` | 用于修改搜索值。 |
++++
+^^^
+
+^^^slot-column-before
+下拉面板中每列前的区域。无默认内容。
+
++++作用域参数
+| 名称 | 类型 | 描述 |
+| -- | -- | -- |
+| `option` | `object` | 该列的父选项，其中 `options` 属性可以拿到当前列的数据。 |
++++
+^^^
+
+^^^slot-label
+下拉按钮文本区域。
+
+默认内容：已选项对应的 `label` 属性值或内联模式下已选项的文本内容。
+
++++作用域参数
+| 名称 | 类型 | 描述 |
+| -- | -- | -- |
+| `label` | `string` | 已选项文本。 |
+| `value` | `*` | 已选项值。 |
+| `checked` | `boolean` | 是否已选择某个值。 |
+| `disabled` | `boolean=` | 选项是否禁用。 |
++++
+
+另外，当前选项数据中除了上面描述的字段之外的其它字段也会自动通过 `v-bind` 进行绑定到作用域参数上。
+^^^
+
+
+^^^slot-option-label
+下拉选项（不带 `options` 的选项）的文本区域。
+
+默认内容：选项的 `label` 属性值。
+
++++作用域参数
+| 名称 | 类型 | 描述 |
+| -- | -- | -- |
+| `option` | `object` | 当前选项。 |
+| `select` | `function(option: object): void` | 选中当前选项。 |
+| `expand` | `function(option: object): void` | 展开当前选项。 |
+| `click` | `function(option: object): void` | 点击当前选项内容区，会按情况选中和(或)展开当前选项。 |
++++
+^^^
+
+^^^slot-option
+可供选择的下拉选项的整个区域。
+
+默认内容：`Option` 内的组件默认结构。
+
+作用域参数同 `option-label` 插槽。
+^^^
+
+^^^slot-selected
+选中值渲染区域。
+
+默认内容：单选时渲染选中项目的标签；多选时将每个选中项目的标签渲染成`Tag`。
+
++++单选时的作用域参数
+| 名称 | 类型 | 描述 |
+| -- | -- | -- |
+| `label` | `string` | 选项文本。 |
+| `value` | `*` | 选项值。 |
+| `checked` | `boolean` | 是否已选择。 |
+| `disabled` | `boolean=` | 选项是否禁用。 |
++++
+
++++多选时的作用域参数
+| 名称 | 类型 | 描述 |
+| -- | -- | -- |
+| `selected` | `Array<Object>` | 选中项数据的数组。 |
++++
+^^^
+
+### 事件
+
+| 名称 | 描述 |
+| -- | -- |
+| `select` | [^event-select] |
+| `afteropen` | 下拉打开后触发。 |
+| `afterclose` | 下拉关闭后触发。 |
+
+^^^event-select
+:::badges
+`v-model`
+:::
+
+选中状态变化后触发，回调参数为 `(value: *)`。`value` 为当前已选项 `value` 字段的值。
+^^^
+
+### 全局配置
+
+| 配置项 | 类型 | 默认值 | 描述 |
+| -- | -- | -- | -- |
+| `cascader.placeholder` | `string` | `@@cascader.placeholder` | 未选择时的占位内容。 |
+
+:::tip
+`@@` 开头的值表示引用多语言配置中的相应字段。
+:::
+
+### 图标
+
+| 名称 | 描述 |
+| -- | -- |
+| `expand` | 展开下拉。 |
+| `collapse` | 收起下拉。 |
+| `clear` | 清除。 |
+| `separator` | 分隔符。 |
diff --git a/one/docs/demo/cascader/inline.vue b/one/docs/demo/cascader/inline.vue
new file mode 100644
index 0000000..627a5cb
--- /dev/null
+++ b/one/docs/demo/cascader/inline.vue
@@ -0,0 +1,128 @@
+<template>
+<article>
+  <veui-cascader
+    v-model="value"
+    searchable
+    :options="options"
+  />
+</article>
+</template>
+
+<script>
+import { Cascader } from 'veui'
+
+const options = [
+  {
+    label: '浙江',
+    value: '浙江',
+    options: [
+      {
+        label: '威海',
+        value: '威海'
+      },
+      {
+        label: '滨州',
+        value: '滨州'
+      },
+      {
+        label: '临沂',
+        value: '临沂'
+      },
+      {
+        label: '东营',
+        value: '东营'
+      },
+      {
+        label: '济南',
+        value: '济南'
+      }
+    ]
+  },
+  {
+    label: '山东',
+    value: '山东',
+    options: [
+      {
+        label: '菏泽',
+        value: '菏泽',
+        options: [
+          {
+            label: '菏泽1',
+            value: '菏泽1'
+          }
+        ]
+      },
+      {
+        label: '潍坊',
+        value: '潍坊',
+        options: [
+          {
+            label: '潍坊1',
+            value: '潍坊1'
+          }
+        ]
+      },
+      {
+        label: '泰山',
+        value: '泰山'
+      },
+      {
+        label: '烟台',
+        value: '烟台'
+      },
+      {
+        label: '华山',
+        value: '华山'
+      },
+      {
+        label: '衡山',
+        value: '衡山'
+      },
+      {
+        label: '嵩山',
+        value: '嵩山'
+      },
+      {
+        label: '恒山',
+        value: '恒山'
+      },
+      {
+        label: '大雪山',
+        value: '大雪山'
+      }
+    ]
+  },
+  {
+    label: '上海',
+    value: '上海',
+    disabled: true
+  },
+  {
+    label: '北京',
+    value: '北京'
+  },
+  {
+    label: '海外',
+    value: '海外',
+    disabled: true,
+    options: [
+      {
+        label: '日本',
+        value: '日本'
+      }
+    ]
+  }
+]
+
+export default {
+  components: {
+    'veui-cascader': Cascader
+  },
+  data () {
+    return {
+      value: null,
+      options
+    }
+  }
+}
+</script>
diff --git a/one/docs/demo/cascader/multiple.vue b/one/docs/demo/cascader/multiple.vue
new file mode 100644
index 0000000..6179da4
--- /dev/null
+++ b/one/docs/demo/cascader/multiple.vue
@@ -0,0 +1,194 @@
+<template>
+<article>
+  <section class="cascader-config">
+    <veui-checkbox v-model="clearable2">Clearable</veui-checkbox>
+    <veui-checkbox v-model="showSelectAll2">有全选</veui-checkbox>
+    <veui-radio
+      v-model="trigger2"
+      value="click"
+      name="columnTrigger2"
+    >点击展开</veui-radio>
+    <veui-radio
+      v-model="trigger2"
+      value="hover"
+      name="columnTrigger2"
+    >hover展开</veui-radio>
+    <label>
+      Max:
+      <veui-number-input v-model="max2"/>
+    </label>
+    <label>
+      列宽度:
+      <veui-input v-model="columnWidth2"/>
+    </label>
+  </section>
+  <veui-cascader
+    class="mt-3p"
+    v-model="value2"
+    :options="options"
+    :searchable="searchable2"
+    :column-trigger="trigger2"
+    :clearable="clearable2"
+    :inline="inline2"
+    :show-select-all="showSelectAll2"
+    :max="max2"
+    :column-width="getRealColumnWidth(columnWidth2)"
+    multiple
+  />
+</article>
+</template>
+
+<script>
+import { Cascader, Checkbox, Radio, NumberInput, Input } from 'veui'
+
+const options = [
+  {
+    label: '浙江',
+    value: '浙江',
+    options: [
+      {
+        label: '威海',
+        value: '威海'
+      },
+      {
+        label: '滨州',
+        value: '滨州'
+      },
+      {
+        label: '临沂',
+        value: '临沂'
+      },
+      {
+        label: '东营',
+        value: '东营'
+      },
+      {
+        label: '济南',
+        value: '济南'
+      }
+    ]
+  },
+  {
+    label: '山东',
+    value: '山东',
+    options: [
+      {
+        label: '菏泽',
+        value: '菏泽',
+        options: [
+          {
+            label: '菏泽1',
+            value: '菏泽1'
+          }
+        ]
+      },
+      {
+        label: '潍坊',
+        value: '潍坊',
+        options: [
+          {
+            label: '潍坊1',
+            value: '潍坊1'
+          }
+        ]
+      },
+      {
+        label: '泰山',
+        value: '泰山'
+      },
+      {
+        label: '烟台',
+        value: '烟台'
+      },
+      {
+        label: '华山',
+        value: '华山'
+      },
+      {
+        label: '衡山',
+        value: '衡山'
+      },
+      {
+        label: '嵩山',
+        value: '嵩山'
+      },
+      {
+        label: '恒山',
+        value: '恒山'
+      },
+      {
+        label: '大雪山',
+        value: '大雪山'
+      }
+    ]
+  },
+  {
+    label: '上海',
+    value: '上海',
+    disabled: true
+  },
+  {
+    label: '北京',
+    value: '北京'
+  },
+  {
+    label: '海外',
+    value: '海外',
+    disabled: true,
+    options: [
+      {
+        label: '日本',
+        value: '日本'
+      }
+    ]
+  }
+]
+
+export default {
+  components: {
+    'veui-cascader': Cascader,
+    'veui-checkbox': Checkbox,
+    'veui-radio': Radio,
+    'veui-number-input': NumberInput,
+    'veui-input': Input
+  },
+  data () {
+    return {
+      value2: null,
+      searchable2: true,
+      trigger2: 'click',
+      clearable2: true,
+      inline2: false,
+      columnWidth2: '',
+      showSelectAll2: false,
+      max2: null,
+      options
+    }
+  },
+  methods: {
+    getRealColumnWidth (val) {
+      if (val && !isNaN(+val)) {
+        return `${+val}px`
+      }
+      return val
+    }
+  }
+}
+</script>
+
+<style lang="less" scoped docs>
+.cascader-config {
+  display: flex;
+  align-items: center;
+  height: 32px;
+  & > * {
+    margin-right: 32px;
+  }
+  .veui-input {
+    width: 80px;
+  }
+}
+.mt-3p {
+  margin-top: 12px;
+}
+</style>
\ No newline at end of file
diff --git a/one/docs/demo/cascader/searchable.vue b/one/docs/demo/cascader/searchable.vue
new file mode 100644
index 0000000..627a5cb
--- /dev/null
+++ b/one/docs/demo/cascader/searchable.vue
@@ -0,0 +1,128 @@
+<template>
+<article>
+  <veui-cascader
+    v-model="value"
+    searchable
+    :options="options"
+  />
+</article>
+</template>
+
+<script>
+import { Cascader } from 'veui'
+
+const options = [
+  {
+    label: '浙江',
+    value: '浙江',
+    options: [
+      {
+        label: '威海',
+        value: '威海'
+      },
+      {
+        label: '滨州',
+        value: '滨州'
+      },
+      {
+        label: '临沂',
+        value: '临沂'
+      },
+      {
+        label: '东营',
+        value: '东营'
+      },
+      {
+        label: '济南',
+        value: '济南'
+      }
+    ]
+  },
+  {
+    label: '山东',
+    value: '山东',
+    options: [
+      {
+        label: '菏泽',
+        value: '菏泽',
+        options: [
+          {
+            label: '菏泽1',
+            value: '菏泽1'
+          }
+        ]
+      },
+      {
+        label: '潍坊',
+        value: '潍坊',
+        options: [
+          {
+            label: '潍坊1',
+            value: '潍坊1'
+          }
+        ]
+      },
+      {
+        label: '泰山',
+        value: '泰山'
+      },
+      {
+        label: '烟台',
+        value: '烟台'
+      },
+      {
+        label: '华山',
+        value: '华山'
+      },
+      {
+        label: '衡山',
+        value: '衡山'
+      },
+      {
+        label: '嵩山',
+        value: '嵩山'
+      },
+      {
+        label: '恒山',
+        value: '恒山'
+      },
+      {
+        label: '大雪山',
+        value: '大雪山'
+      }
+    ]
+  },
+  {
+    label: '上海',
+    value: '上海',
+    disabled: true
+  },
+  {
+    label: '北京',
+    value: '北京'
+  },
+  {
+    label: '海外',
+    value: '海外',
+    disabled: true,
+    options: [
+      {
+        label: '日本',
+        value: '日本'
+      }
+    ]
+  }
+]
+
+export default {
+  components: {
+    'veui-cascader': Cascader
+  },
+  data () {
+    return {
+      value: null,
+      options
+    }
+  }
+}
+</script>
diff --git a/one/docs/demo/cascader/size.vue b/one/docs/demo/cascader/size.vue
new file mode 100644
index 0000000..e139dcd
--- /dev/null
+++ b/one/docs/demo/cascader/size.vue
@@ -0,0 +1,153 @@
+<template>
+<div class="cascader-wrap">
+  <veui-cascader
+    v-model="value"
+    ui="l"
+    :options="options"
+  />
+  <veui-cascader
+    v-model="value"
+    :options="options"
+  />
+  <veui-cascader
+    v-model="value"
+    ui="s"
+    :options="options"
+  />
+  <veui-cascader
+    v-model="value"
+    ui="xs"
+    :options="options"
+  />
+</div>
+</template>
+
+<script>
+import { Cascader } from 'veui'
+
+const options = [
+  {
+    label: '浙江',
+    value: '浙江',
+    options: [
+      {
+        label: '威海',
+        value: '威海'
+      },
+      {
+        label: '滨州',
+        value: '滨州'
+      },
+      {
+        label: '临沂',
+        value: '临沂'
+      },
+      {
+        label: '东营',
+        value: '东营'
+      },
+      {
+        label: '济南',
+        value: '济南'
+      }
+    ]
+  },
+  {
+    label: '山东',
+    value: '山东',
+    options: [
+      {
+        label: '菏泽',
+        value: '菏泽',
+        options: [
+          {
+            label: '菏泽1',
+            value: '菏泽1'
+          }
+        ]
+      },
+      {
+        label: '潍坊',
+        value: '潍坊',
+        options: [
+          {
+            label: '潍坊1',
+            value: '潍坊1'
+          }
+        ]
+      },
+      {
+        label: '泰山',
+        value: '泰山'
+      },
+      {
+        label: '烟台',
+        value: '烟台'
+      },
+      {
+        label: '华山',
+        value: '华山'
+      },
+      {
+        label: '衡山',
+        value: '衡山'
+      },
+      {
+        label: '嵩山',
+        value: '嵩山'
+      },
+      {
+        label: '恒山',
+        value: '恒山'
+      },
+      {
+        label: '大雪山',
+        value: '大雪山'
+      }
+    ]
+  },
+  {
+    label: '上海',
+    value: '上海',
+    disabled: true
+  },
+  {
+    label: '北京',
+    value: '北京'
+  },
+  {
+    label: '海外',
+    value: '海外',
+    disabled: true,
+    options: [
+      {
+        label: '日本',
+        value: '日本'
+      }
+    ]
+  }
+]
+
+export default {
+  components: {
+    'veui-cascader': Cascader
+  },
+  data () {
+    return {
+      value: null,
+      options
+    }
+  }
+}
+</script>
+
+<style lang="less" scoped docs>
+.cascader-wrap {
+  display: flex;
+  flex-direction: column;
+  align-items: flex-start;
+  .veui-cascader + .veui-cascader{
+      margin-top: 12px;
+  }
+}
+</style>
diff --git a/one/docs/nav.json b/one/docs/nav.json
index 9210262..a941f30 100644
--- a/one/docs/nav.json
+++ b/one/docs/nav.json
@@ -306,6 +306,10 @@
         {
           "title": "Lightbox - 灯箱",
           "slug": "lightbox"
+        },
+        {
+          "title": "Cascader - 级联器",
+          "slug": "cascader"
         }
       ]
     },