add cascader doc

components/cascader/demo/index.vue

@@ -0,0 +1,59 @@
+<script>
+import Basic from './basic'
+import ChangeOnSelect from './change-on-select'
+import CustomRender from './custom-render'
+import CustomTrigger from './custom-trigger'
+import DefaultValue from './default-value'
+import DisabledOption from './disabled-option'
+import Hover from './hover'
+import Lazy from './lazy'
+import Search from './search'
+import Size from './size'
+
+import CN from '../index.zh-CN.md'
+import US from '../index.en-US.md'
+const md = {
+  cn: `# Cascader 级联选择
+          级联选择框。
+## 何时使用
+- 需要从一组相关联的数据集合进行选择，例如省市区，公司层级，事物分类等。
+- 从一个较大的数据集合中进行选择时，用多级分类进行分隔，方便选择。
+- 比起 Select 组件，可以在同一个浮层中完成选择，有较好的体验。
+          ## 代码演示`,
+  us: `# Cascader
+          Cascade selection box.
+## When To Use
+- When you need to select from a set of associated data set. Such as province/city/district, company level, things classification.
+- When selecting from a large data set, with multi-stage classification separated for easy selection.
+- Chooses cascade items in one float layer for better user experience.
+          `,
+}
+export default {
+  render () {
+    return (
+      <div>
+        <md cn={md.cn} us={md.us}/>
+        <Basic />
+        <ChangeOnSelect/>
+        <CustomRender/>
+        <CustomTrigger/>
+        <DefaultValue/>
+        <DisabledOption/>
+        <Hover/>
+        <Lazy/>
+        <Search/>
+        <Size/>
+        <api>
+          <CN slot='cn' />
+          <US/>
+        </api>
+      </div>
+    )
+  },
+}
+</script>
+<style>
+.ant-cascader-picker {
+  width: 300px;
+}
+</style>

components/cascader/index.en-US.md

@@ -0,0 +1,51 @@
+
+## API
+
+````html
+<a-cascader :options="options" @change="onChange" />
+````
+
+| Property | Description | Type | Default |
+| -------- | ----------- | ---- | ------- |
+| allowClear | whether allow clear | boolean | true |
+| autoFocus | get focus when component mounted | boolean | false |
+| changeOnSelect | change value on each selection if set to true, see above demo for details | boolean | false |
+| defaultValue | initial selected value | string\[] | \[] |
+| disabled | whether disabled select | boolean | false |
+| displayRender | render function of displaying selected options, you can use slot="displayRender" and slot-scope="props" | `({labels, selectedOptions}) => vNode` | `labels => labels.join(' / ')` |
+| expandTrigger | expand current item when click or hover, one of 'click' 'hover' | string | 'click' |
+| getPopupContainer | Parent Node which the selector should be rendered to. Default to `body`. When position issues happen, try to modify it into scrollable content and position it relative. | Function(triggerNode) | () => document.body |
+| loadData | To load option lazily, and it cannot work with `showSearch` | `(selectedOptions) => void` | - |
+| notFoundContent | Specify content to show when no result matches. | string | 'Not Found' |
+| options | data options of cascade | object | - |
+| placeholder | input placeholder | string | 'Please select' |
+| popupClassName | additional className of popup overlay | string | - |
+| popupStyle | additional style of popup overlay | object | {} |
+| popupPlacement | use preset popup align config from builtinPlacements：`bottomLeft` `bottomRight` `topLeft` `topRight` | string | `bottomLeft` |
+| popupVisible | set visible of cascader popup | boolean | - |
+| showSearch | Whether show search input in single mode. | boolean\|object | false |
+| size | input size, one of `large` `default` `small` | string | `default` |
+| value(v-model) | selected value | string\[] | - |
+
+Fields in `showSearch`:
+
+| Property | Description | Type | Default |
+| -------- | ----------- | ---- | ------- |
+| filter | The function will receive two arguments, inputValue and option, if the function returns true, the option will be included in the filtered set; Otherwise, it will be excluded. | `function(inputValue, path): boolean` |  |
+| matchInputWidth | Whether the width of result list equals to input's | boolean |  |
+| render | Used to render filtered options, you can use slot="showSearchRender" and slot-scope="props" | `function({inputValue, path}): vNode` |  |
+| sort | Used to sort filtered options. | `function(a, b, inputValue)` |  |
+
+### events
+| Events Name | Description | Arguments |
+| --- | --- | --- |
+| change | callback when finishing cascader select | `(value, selectedOptions) => void` | - |
+| popupVisibleChange | callback when popup shown or hidden | `(value) => void` | - |
+
+## Methods
+
+| Name | Description |
+| ---- | ----------- |
+| blur() | remove focus |
+| focus() | get focus |
+

components/cascader/index.vue

@@ -122,7 +122,7 @@ export default {
         ])
     },
 
-    defaultRenderFilteredOption (inputValue, path, prefixCls) {
+    defaultRenderFilteredOption ({ inputValue, path, prefixCls }) {
       return path.map(({ label }, index) => {
         const node = label.indexOf(inputValue) > -1
           ? this.highlightKeyword(label, inputValue, prefixCls) : label
@@ -222,12 +222,13 @@ export default {
     },
 
     generateFilteredOptions (prefixCls) {
-      const { showSearch, notFoundContent, flattenOptions, inputValue } = this
+      const { showSearch, notFoundContent, flattenOptions, inputValue, $scopedSlots } = this
       const {
         filter = defaultFilterOption,
-        render = this.defaultRenderFilteredOption,
+        // render = this.defaultRenderFilteredOption,
         sort = defaultSortFilteredOption,
       } = showSearch
+      const render = showSearch.render || $scopedSlots.showSearchRender || this.defaultRenderFilteredOption
       const filtered = flattenOptions.filter((path) => filter(inputValue, path))
         .sort((a, b) => sort(a, b, inputValue))
 
@@ -236,7 +237,7 @@ export default {
           return {
             __IS_FILTERED_OPTION: true,
             path,
-            label: render(inputValue, path, prefixCls),
+            label: render({ inputValue, path, prefixCls }),
             value: path.map((o) => o.value),
             disabled: path.some((o) => o.disabled),
           }

components/cascader/index.zh-CN.md

@@ -0,0 +1,52 @@
+
+## API
+
+````html
+<a-cascader :options="options" @change="onChange" />
+````
+
+| 参数 | 说明 | 类型 | 默认值 |
+| --- | --- | --- | --- |
+| allowClear | 是否支持清除 | boolean | true |
+| autoFocus | 自动获取焦点 | boolean | false |
+| changeOnSelect | 当此项为 true 时，点选每级菜单选项值都会发生变化，具体见上面的演示 | boolean | false |
+| defaultValue | 默认的选中项 | string\[] | \[] |
+| disabled | 禁用 | boolean | false |
+| displayRender | 选择后展示的渲染函数,可使用slot="displayRender" 和 slot-scope="props" | `({labels, selectedOptions}) => vNode` | `labels => labels.join(' / ')` |
+| expandTrigger | 次级菜单的展开方式，可选 'click' 和 'hover' | string | 'click' |
+| getPopupContainer | 菜单渲染父节点。默认渲染到 body 上，如果你遇到菜单滚动定位问题，试试修改为滚动的区域，并相对其定位。 | Function(triggerNode) | () => document.body |
+| loadData | 用于动态加载选项，无法与 `showSearch` 一起使用 | `(selectedOptions) => void` | - |
+| notFoundContent | 当下拉列表为空时显示的内容 | string | 'Not Found' |
+| options | 可选项数据源 | object | - |
+| placeholder | 输入框占位文本 | string | '请选择' |
+| popupClassName | 自定义浮层类名 | string | - |
+| popupStyle | 自定义浮层样式 | object | {} |
+| popupPlacement | 浮层预设位置：`bottomLeft` `bottomRight` `topLeft` `topRight` | Enum | `bottomLeft` |
+| popupVisible | 控制浮层显隐 | boolean | - |
+| showSearch | 在选择框中显示搜索框 | boolean | false |
+| size | 输入框大小，可选 `large` `default` `small` | string | `default` |
+| value(v-model) | 指定选中项 | string\[] | - |
+
+`showSearch` 为对象时，其中的字段：
+
+| 参数 | 说明 | 类型 | 默认值 |
+| --- | --- | --- | --- |
+| filter | 接收 `inputValue` `path` 两个参数，当 `path` 符合筛选条件时，应返回 true，反之则返回 false。 | `function(inputValue, path): boolean` |  |
+| matchInputWidth | 搜索结果列表是否与输入框同宽 | boolean |  |
+| render | 用于渲染 filter 后的选项,可使用slot="showSearchRender" 和 slot-scope="props" | `function({inputValue, path}): vNode` |  |
+| sort | 用于排序 filter 后的选项 | `function(a, b, inputValue)` |  |
+
+### 事件
+| 事件名称 | 说明 | 回调参数 |
+| --- | --- | --- |
+| change | 选择完成后的回调 | `(value, selectedOptions) => void` | - |
+| popupVisibleChange | 显示/隐藏浮层的回调 | `(value) => void` | - |
+
+## 方法
+
+| 名称 | 描述 |
+| --- | --- |
+| blur() | 移除焦点 |
+| focus() | 获取焦点 |
+
+> 注意，如果需要获得中国省市区数据，可以参考react组件的实现 [china-division](https://gist.github.com/afc163/7582f35654fd03d5be7009444345ea17)。

examples/demo.js

@@ -26,4 +26,5 @@ export { default as spin } from 'antd/spin/demo/index.vue'
 export { default as switch } from 'antd/switch/demo/index.vue'
 export { default as autoComplete } from 'antd/auto-complete/demo/index.vue'
 export { default as affix } from 'antd/Affix/demo/index.vue'
+export { default as cascader } from 'antd/cascader/demo/index.vue'