Skip to content
On this page

Cascader/CascaderPopup/CascaderView 级联选择

注:

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

属性类型默认值必填说明
optionsOptions[]数据集
v-modelSelectorModelValue[]选中值
field-namesCascaderFieldNames{ label: 'label', value: 'value', children: 'children' }自定义 options 中 label value children 的字段 key
formatterSelectorValueFormatterparser 成对设置,对于 v-model 和 change 的值进行转化
parserSelectorValueParserformatter 成对设置,对于 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

属性类型默认值必填说明
namestring标识
placeholderstring没有选中值的提示
disabledbooleanfalse是否禁用

Cascader Events

事件描述回调函数参数函数 TypeScript
change选择后 value 发生改变时触发payload: SelectorModelValueSelectorOnChange
select选择后触发payload: CascaderDetailCascaderOnSelect

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:visiblebooleanfalse是否显示弹窗

CascaderPopup Events

事件描述回调函数参数函数 TypeScript
confirm点击确定按钮后触发payload: CascaderDetailCascaderOnConfirm
cancel点击蒙层关闭后触发PopupOnCancel
change选中值发生变化时触发payload: SelectorModelValueSelectorOnChange
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: SelectorModelValueSelectorOnChange
select每次选择完毕时触发payload: CascaderDetailCascaderOnSelect

showCascader(object) 显示级联选择弹窗

object

属性类型默认值必填说明
optionsOptions[]数据集
value(string | number)[][]选中值
fieldNamesCascaderFieldNames{ 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 的值转为组件认识的原始数组。