Cascader/CascaderPopup/CascaderView 级联选择
注:
- 这 3 个组件是渐进式组件,可查看 渐进式组件 了解。
Import
js
import { TaCascader, TaCascaderPopup, TaCascaderView } from 'tantalum-ui-mobile'
具体的引入方式可以参考引入组件。
Import Type
组件导出的类型定义:
ts
import type {
CascaderOnConfirm,
CascaderFieldNames,
SelectorOnChange,
SelectorModelValue,
CascaderDetail,
SelectorValueParser,
SelectorValueFormatter,
VisibleState,
PopupOnVisibleStateChange,
PopupOnCancel
} from 'tantalum-ui-mobile'
公共 Props
属性 | 类型 | 默认值 | 必填 | 说明 |
---|---|---|---|---|
options | Options | [] | 否 | 数据集 |
v-model | SelectorModelValue | [] | 否 | 选中值 |
field-names | CascaderFieldNames | { label: 'label', value: 'value', children: 'children' } | 否 | 自定义 options 中 label value children 的字段 key |
formatter | SelectorValueFormatter | 否 | 和 parser 成对设置,对于 v-model 和 change 的值进行转化 | |
parser | SelectorValueParser | 否 | 和 formatter 成对设置,对于 v-model 和 change 的值进行反转化 |
Options 的结构
js
const options = [
{
label: '空调',
value: 'kongtiao',
children: [
{
label: '家用空调',
value: 'jiayongkongtiao',
children: [
{
label: '挂式空调',
value: 'guashikongtiao'
},
{
label: '柜式空调',
value: 'guishikongtiao'
}
]
},
{
label: '厨房空调',
value: 'chufangkongtiao'
}
]
},
{
label: '冰箱',
value: 'bingxiang',
children: [
{
label: '双门',
value: 'shuangmen'
},
{
label: '三门',
value: 'sanmen'
}
]
}
]
Cascader 级联选择器
注:
- 支持表单,具体可参考 Form。
vue
<script setup lang="ts">
import { ref } from 'vue'
import { cascadeOptions, regionOptions } from '../Picker/data'
import {
showToast,
showCascader,
type SelectorModelValue,
type SelectorValueFormatter,
type SelectorValueParser
} from '@/index'
const separator = '-'
const placeholder = '选择家电'
const disableValue = ref(['bingxiang', 'sanmen'])
const formatValue = ref(`bingxiang${separator}duikaimen`)
const formatter: SelectorValueFormatter = (valueArray, labelArray) => {
return {
value: valueArray.join(separator),
label: labelArray.join(separator)
}
}
const parser: SelectorValueParser = value => {
return value ? (value as string).split(separator) : []
}
function onChange(res: SelectorModelValue) {
console.log('change', res)
showToast(`选择了 ${res}`)
}
function onCallApi() {
showCascader({
options: cascadeOptions,
success: res => {
console.log('success', res)
if (res.cancel) {
showToast('取消了')
} else {
showToast(`选择了 ${res.detail.label}`)
}
}
})
}
</script>
<script lang="ts">
export default {
name: 'ExpCascader'
}
</script>
<template>
<ta-group title="基础用法">
<ta-cell label="家电">
<ta-cascader :options="cascadeOptions" />
</ta-cell>
<ta-cell label="地区">
<ta-cascader :options="regionOptions" :fieldNames="{ value: 'label' }" />
</ta-cell>
<ta-cell label="placeholder">
<ta-cascader :options="cascadeOptions" :placeholder="placeholder" />
</ta-cell>
<ta-cell label="formatter/parser">
<ta-cascader
:options="cascadeOptions"
:placeholder="placeholder"
v-model="formatValue"
:formatter="formatter"
:parser="parser"
/>
</ta-cell>
<ta-cell label="禁用">
<ta-cascader :modelValue="disableValue" :options="cascadeOptions" disabled />
</ta-cell>
</ta-group>
<ta-group title="事件监听">
<ta-cell label="change">
<ta-cascader :options="cascadeOptions" @change="onChange" />
</ta-cell>
</ta-group>
<ta-group title="API">
<ta-cell label="showCascader" isLink @click="onCallApi()" />
</ta-group>
</template>
Cascader Props
属性 | 类型 | 默认值 | 必填 | 说明 |
---|---|---|---|---|
name | string | 否 | 标识 | |
placeholder | string | 否 | 没有选中值的提示 | |
disabled | boolean | false | 否 | 是否禁用 |
Cascader Events
事件 | 描述 | 回调函数参数 | 函数 TypeScript |
---|---|---|---|
change | 选择后 value 发生改变时触发 | payload: SelectorModelValue | SelectorOnChange |
select | 选择后触发 | payload: CascaderDetail | CascaderOnSelect |
CascaderPopup 级联选择弹窗
vue
<script setup lang="ts">
import { ref } from 'vue'
import { cascadeOptions } from '../Picker/data'
import {
showToast,
type SelectorModelValue,
type PopupOnVisibleStateChange,
type PopupOnCancel,
type CascaderOnConfirm
} from '@/index'
const popupValue = ref(['bingxiang', 'duikaimen'])
const visible = ref(false)
const clickEvent = ref(false)
const changeEvent = ref(false)
const visibleEvent = ref(false)
function onChange(res: SelectorModelValue) {
console.log('change', res)
showToast(`选择了 ${res}`)
}
const onVisibleStateChange: PopupOnVisibleStateChange = res => {
if (visibleEvent.value) {
console.log('visible-state-change', res)
showToast(`${res.state} 事件触发`)
}
if (res.state === 'hidden') {
clickEvent.value = false
visibleEvent.value = false
changeEvent.value = false
}
}
const onConfirm: CascaderOnConfirm = res => {
if (clickEvent.value) {
console.log('confirm', res)
showToast(`点击确定按钮`)
}
}
const onCancel: PopupOnCancel = res => {
if (clickEvent.value) {
console.log('cancel', res)
if (res.source === 'cancelClick') {
showToast('点击了取消按钮')
} else if (res.source === 'maskClick') {
showToast('点击了蒙层')
}
}
}
</script>
<script lang="ts">
export default {
name: 'ExpCascaderPopup'
}
</script>
<template>
<ta-notice-bar class="top-notice-bar" title="基础展示参数可以参考 Cascader" />
<ta-group title="基础用法">
<ta-cell label="v-model" isLink @click="visible = true">{{ popupValue }}</ta-cell>
</ta-group>
<ta-group title="事件监听">
<ta-cell
label="change"
isLink
@click="
() => {
changeEvent = true
visible = true
}
"
/>
<ta-cell
label="confirm/cancel"
isLink
@click="
() => {
clickEvent = true
visible = true
}
"
/>
<ta-cell
label="visible-state-change"
isLink
@click="
() => {
visibleEvent = true
visible = true
}
"
/>
</ta-group>
<ta-cascader-popup
v-model:visible="visible"
:options="cascadeOptions"
v-model="popupValue"
@change="onChange"
@confirm="onConfirm"
@cancel="onCancel"
@visibleStateChange="onVisibleStateChange"
/>
</template>
CascaderPopup Props
属性 | 类型 | 默认值 | 必填 | 说明 |
---|---|---|---|---|
v-model:visible | boolean | false | 否 | 是否显示弹窗 |
CascaderPopup Events
事件 | 描述 | 回调函数参数 | 函数 TypeScript |
---|---|---|---|
confirm | 点击确定按钮后触发 | payload: CascaderDetail | CascaderOnConfirm |
cancel | 点击蒙层关闭后触发 | PopupOnCancel | |
change | 选中值发生变化时触发 | payload: SelectorModelValue | SelectorOnChange |
visible-state-change | 展示隐藏时触发 | payload: { state: VisibleState } | PopupOnVisibleStateChange |
VisibleState 值说明
值 | 说明 | 备注 |
---|---|---|
show | 展示时触发 | |
shown | 展示且动画结束后触发 | |
hide | 隐藏时触发 | 可能携带其他参数 cancel, maskClick, closeClick 等 |
hidden | 隐藏且动画结束后触发 | 可能携带其他参数 cancel, maskClick, closeClick 等 |
CascaderView 级联选择面板
vue
<script setup lang="ts">
import { ref } from 'vue'
import { showToast, type SelectorModelValue, type CascaderOnSelect } from '@/index'
import { cascadeOptions } from '../Picker/data'
const changeValue = ref([])
const selectValue = ref([])
const baseValue = ref([])
function onChange(res: SelectorModelValue) {
console.log('change', res)
showToast(`change: ${res}`)
}
const onSelect: CascaderOnSelect = res => {
console.log('select', res)
showToast(`select: ${res.value}`)
}
</script>
<script lang="ts">
export default {
name: 'ExpCascaderView'
}
</script>
<template>
<ta-notice-bar class="top-notice-bar" title="基础展示参数可以参考 Cascader" />
<ta-group title="家电">
<ta-cascader-view :options="cascadeOptions" v-model="baseValue" />
</ta-group>
<ta-group title="空数据">
<ta-cascader-view :options="[]" />
</ta-group>
<ta-group title="change 事件">
<ta-cascader-view :options="cascadeOptions" @change="onChange" v-model="changeValue" />
</ta-group>
<ta-group title="select 事件(跟 change 的区别是重复选一样的也触发)">
<ta-cascader-view :options="cascadeOptions" @select="onSelect" v-model="selectValue" />
</ta-group>
</template>
CascaderView Events
事件 | 描述 | 回调函数参数 | 函数 TypeScript |
---|---|---|---|
change | 选择完毕后发生变化时触发 | payload: SelectorModelValue | SelectorOnChange |
select | 每次选择完毕时触发 | payload: CascaderDetail | CascaderOnSelect |
showCascader(object) 显示级联选择弹窗
object
属性 | 类型 | 默认值 | 必填 | 说明 |
---|---|---|---|---|
options | Options | [] | 否 | 数据集 |
value | (string | number)[] | [] | 否 | 选中值 |
fieldNames | CascaderFieldNames | { label: 'label', value: 'value', children: 'children' } | 否 | 自定义 options 中 label value children 的字段 key |
success | (payload: SuccessPayload) => void | 否 | 接口调用成功(在用户做出选择后,如取消,选择选项)的回调函数 | |
fail | (e: Error) => void | 否 | 接口调用失败(如传入错误的参数)的回调函数(不传入 fail 遇错误直接抛出) | |
complete | () => void | 否 | 弹窗关闭或调用失败的回调函数 |
SuccessPayload
属性 | 类型 | 说明 |
---|---|---|
confirm? | boolean | 为 true 时,表示点击了确定,此时返回 detail |
cancel? | boolean | 为 true 时,表示取消 |
detail? | CascaderDetail |
Usage
具体调用方式可以参考API 调用。
js
showCascader({
title: '植物',
options: cascadeOptions,
success: ({ confirm, cancel, detail }) => {
...
}
})
类型释义
SelectorValue
ts
type SelectorValue = string | number | Date
SelectorModelValue
ts
type SelectorModelValue = SelectorValue | SelectorValue[]
注:在不自定义 formatter/parser
的情况下,v-model 只有 (string | number)[]
这种情况。
CascaderDetail
ts
interface CascaderDetail {
label: string
value: (string | number)[]
}
CascaderFieldNames
ts
interface CascaderFieldNames {
label?: string
value?: string
children?: string
}
SelectorValueFormatter
ts
interface SelectorValueFormatter {
(valueArray: SelectorValue[], labelArray: string[]):
| { value: SelectorModelValue; label: string }
| SelectorModelValue
}
将 v-model 的原始值转为需要的自定义值,值需要满足 SelectorModelValue
的类型约束,可以返回 { value, label } 对两个数据进行修改,或者单独返回 value。
SelectorValueParser
ts
interface SelectorValueParser {
(value: unknown): SelectorValue[]
}
跟 SelectorValueFormatter
相反,将自定义 v-model 的值转为组件认识的原始数组。