docs: add docs for cascader

Change-Id: Id5f4d5287f18417e91ff3986f1ab48354ab5bba8
This commit is contained in:
xiaodemen 2021-05-06 12:14:38 +08:00 committed by GU Yiling
parent 50e1124467
commit d6a3bcbb16
6 changed files with 885 additions and 0 deletions

View File

@ -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` | 分隔符。 |

View File

@ -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>

View File

@ -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>

View File

@ -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>

View File

@ -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>

View File

@ -306,6 +306,10 @@
{
"title": "Lightbox - 灯箱",
"slug": "lightbox"
},
{
"title": "Cascader - 级联器",
"slug": "cascader"
}
]
},