docs_vue2/one/docs/components/cascader.md
Justineo 32632e796e docs: update docs
Change-Id: I76d0f72679cd75085f5ffd42f641daa198cafe11

docs: update docs for alert/autocomplete/carousel, etc.

Change-Id: Ib7507f4979024f53c127e4b64b88560b93999db7

fix: update for autocomplete filter

Change-Id: Ie54556715fa52838aeb6caaa19b4f9a9f14b490f

docs: add docs for calendar/transfer/cascader

Change-Id: I655b3cb3d25dd0649de9ae7e224e7063a40dd079

fix: add more demos for input/textarea

Change-Id: Iada527ca82643a435a4775110b332155512d62a7

docs: add docs for uploader,select,table, etc.

Change-Id: Ib034fd5cc9d9a420d4e002956ae925175783c5f3

docs: adjust formatting and punc.

docs: adjust docs for uploader, etc.

Change-Id: If06c8c1102eafce43f5802a333676fc9e62cd474

docs: add docs for nav

Change-Id: If56a653ec53f19239606128fd30cae80f8e10025

docs: improve anchor demos

Change-Id: I6ac1c08cc8905924d0062def1f8921fe1f302f15

docs: refine wording and format

docs: update docs for check-button-group desc

Change-Id: Ica7d6d0692250f0be6bd330b1ad4cc41938afd46
2021-10-25 20:10:29 +08:00

300 lines
8.9 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters

This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

# Cascader <small>级联器</small>
## 示例
### 尺寸
可选的尺寸 [`ui`](#props-ui) 属性值:`xs` / `s` / `m` / `l`
[[ demo src="/demo/cascader/size.vue" ]]
### 内联模式
使用 [`inline`](#props-inline) 属性来开启内联模式。
[[ demo src="/demo/cascader/inline.vue" ]]
### 搜索选项
使用 [`searchable`](#props-searchable) 属性来开启选项搜索。
[[ demo src="/demo/cascader/searchable.vue" ]]
### 多选
使用 [`multiple`](#props-multiple) 属性来开启多选模式。
[[ demo src="/demo/cascader/multiple.vue" ]]
### 选择模式
使用 `select-mode` 属性来控制在单选模式下哪些项目可以被选中。
[[ demo src="/demo/cascader/select-mode.vue" ]]
### 子项展开时机
使用 `column-trigger` 属性来控制下拉面板中下级的展开时机。
[[ demo src="/demo/cascader/column-trigger.vue" ]]
### 渲染选中值
使用 `value-display` 属性来控制选中值如何展示。
[[ demo src="/demo/cascader/value-display.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` | 是否允许搜索选项。 |
| ``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#props-overlay-class) 属性。 |
| ``overlay-style`` | `string | Array | Object=` | - | 参考 [`Overlay`](./overlay) 组件的 [`overlay-style`](./overlay#props-overlay-style) 属性。 |
| ``match`` | `(item, keyword, { ancestors }) => boolean | Array<[number, number]>` | - | 支持自定义高亮逻辑, 默认大小写不敏感,参考 [`Autocomplete`](./Autocomplete#自定义搜索逻辑)。 |
| ``filter`` | `(item, keyword, { ancestors, offsets }) => boolean` | - | 支持自定义搜索命中逻辑,参考 [`Autocomplete`](./Autocomplete#自定义搜索逻辑)。 |
^^^ui
预设样式。
+++枚举值
| 值 | 描述 |
| -- | -- |
| `xs` | 超小尺寸样式。 |
| `s` | 小尺寸样式。 |
| `m` | 中尺寸样式。 |
| `l` | 大尺寸样式。 |
+++
^^^
^^^options
选项列表,项目的类型为 `{label, value, options, disabled, position, ...}`
+++字段详情
| 名称 | 类型 | 描述 |
| -- | -- | -- |
| `label` | `string` | 选项的文字说明。 |
| `value` | `*` | 选项对应的值。 |
| `position` | `string` | 下级节点如何展示,默认弹出,可以设置 `inline` 来内联显示。 |
| `options` | `Array<Object>=` | 选项的子选项数组,数组项类型同 [`options`](#props-options) 属性数组项。 |
| `disabled` | `boolean=` | 选项是否为禁用。 |
+++
^^^
^^^value
:::badges
`v-model`
:::
已选值。
^^^
^^^expanded
:::badges
`.sync`
:::
下拉菜单是否展开。
^^^
^^^column-trigger
下拉面板中下级的展开时机。
+++枚举值
| 值 | 描述 |
| -- | -- |
| `hover` | 光标悬浮展开下一级。 |
| `click` | 点击展开下一级。 |
+++
^^^
^^^select-mode
在单选模式下控制哪些项目可以选中。
+++枚举值
| 值 | 描述 |
| -- | -- |
| `leaf-only` | 只有叶子节点可以选中。 |
| `any` | 每一级都可以选中。 |
+++
^^^
^^^column-width
当下拉面板中有多列时,统一控制除了最后一列之外的列宽度。
当该值是数值或者能转换成数值时,会当成像素值。
^^^
^^^value-display
控制选中值如何展示。
+++枚举值
| 值 | 描述 |
| -- | -- |
| `complete` | 完整展示选中值的路径,如“中国 > 上海”。 |
| `simple` | 仅仅展示选中值文本。 |
+++
^^^
### 插槽
| 名称 | 描述 |
| -- | -- |
| ``trigger`` | [^slot-trigger] |
| ``pane`` | 下拉面板中的内容插槽。用域参数同 [`trigger`](#slots-trigger) 插槽。 |
| ``before`` | 选项列表前的内容。无默认内容。作用域参数同 [`trigger`](#slots-trigger) 插槽。 |
| ``after`` | 选项列表后的内容。无默认内容。作用域参数同 [`trigger`](#slots-trigger) 插槽。 |
| ``column-before`` | [^slot-column-before] |
| ``column-after`` | 下拉面板中每列后的区域。无默认内容。作用域参数同 [`column-before`](#slots-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(option: Object): void` | 用于设置已选项。 |
| `toggle` | `function(force: boolean): void` | 用于切换下拉菜单展开状态。 |
| `clear` | `function(): void` | 用于清除已选项。 |
| `remove` | `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`](#slots-option-label) 插槽。
^^^
^^^slot-selected
选中值渲染区域。
默认内容:单选时渲染选中项目的标签;多选时将每个选中项目的标签渲染成`Tag`。
+++单选时的作用域参数
| 名称 | 类型 | 描述 |
| -- | -- | -- |
| `label` | `string` | 选项文本。 |
| `value` | `*` | 选项值。 |
| `checked` | `boolean` | 是否已选择。 |
| `disabled` | `boolean=` | 选项是否禁用。 |
+++
+++多选时的作用域参数
| 名称 | 类型 | 描述 |
| -- | -- | -- |
| `selected` | `Array<Object>` | 选中项数据的数组。 |
+++
^^^
### 事件
| 名称 | 描述 |
| -- | -- |
| ``input`` | 输入搜索关键词时触发。回调参数为 `(value: string)``value` 为输入框的 `value` 值。 |
| ``select`` | [^event-select] |
| ``afteropen`` | 下拉打开后触发。 |
| ``afterclose`` | 下拉关闭后触发。 |
^^^event-select
:::badges
`v-model`
:::
选中状态变化后触发,回调参数为 `(value: *)`。`value` 为当前已选项 `value` 字段的值。
^^^
### 全局配置
| 配置项 | 类型 | 默认值 | 描述 |
| -- | -- | -- | -- |
| ``cascader.placeholder`` | `string` | `@@cascader.placeholder` | 未选择时的占位内容。 |
:::tip
`@@` 开头的值表示引用多语言配置中的相应字段。
:::
### 图标
| 名称 | 描述 |
| -- | -- |
| ``expand`` | 展开下拉。 |
| ``collapse`` | 收起下拉。 |
| ``clear`` | 清除。 |
| ``separator`` | 分隔符。 |