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 级联器 + + +## 示例 + +### 尺寸 + +可选的尺寸 `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` | - | [^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=` | 选项的子选项数组,数组项类型同 `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` | 选中项数据的数组。 | ++++ +^^^ + +### 事件 + +| 名称 | 描述 | +| -- | -- | +| `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 @@ + + + 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 @@ + + + + + \ 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 @@ + + + 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 @@ + + + + + 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" } ] },