xtf-linkui

Appearance

xtf-cascader ​

组件说明 ​

xtf-cascader 是级联选择器组件，用于多级数据的选择。支持多级 Tab 切换、搜索过滤、多选、父子节点不关联、自定义字段映射和底部操作栏，适用于省市区选择、分类选择和组织架构选择等场景。

基础用法 ​

1. 最简示例 ​

通过 options 传入级联数据，v-model 绑定选中值路径：

vue
<template>
  <xtf-cascader v-model="selected" :options="options" title="选择地区" closeable />
</template>

<script>
export default {
  data() {
    return {
      selected: [],
      options: [
        {
          text: '浙江省',
          value: 'zhejiang',
          children: [
            {
              text: '杭州市',
              value: 'hangzhou',
              children: [
                { text: '西湖区', value: 'xihu' },
                { text: '余杭区', value: 'yuhang' }
              ]
            },
            {
              text: '宁波市',
              value: 'ningbo',
              children: [
                { text: '海曙区', value: 'haishu' },
                { text: '江北区', value: 'jiangbei' }
              ]
            }
          ]
        },
        {
          text: '江苏省',
          value: 'jiangsu',
          children: [
            {
              text: '南京市',
              value: 'nanjing',
              children: [
                { text: '玄武区', value: 'xuanwu' },
                { text: '鼓楼区', value: 'gulou' }
              ]
            }
          ]
        }
      ]
    }
  }
}
</script>

2. 搜索过滤 ​

通过 filterable 启用搜索功能：

vue
<template>
  <xtf-cascader v-model="selected" :options="options" title="选择分类" filterable closeable />
</template>

3. 多选模式 ​

通过 multiple 启用多选，通过 checkStrictly 允许父子节点不关联：

vue
<template>
  <xtf-cascader
    v-model="selected"
    :options="options"
    title="选择分类"
    multiple
    check-strictly
    show-actions
    closeable
  />
</template>

<script>
export default {
  data() {
    return {
      selected: [],
      options: [
        {
          text: '电子产品',
          value: 'electronics',
          children: [
            { text: '手机', value: 'phone' },
            { text: '电脑', value: 'computer' },
            { text: '平板', value: 'tablet' }
          ]
        },
        {
          text: '服装',
          value: 'clothing',
          children: [
            { text: '男装', value: 'men' },
            { text: '女装', value: 'women' }
          ]
        }
      ]
    }
  }
}
</script>

4. 自定义字段映射 ​

通过 fieldNames 映射数据字段名：

vue
<template>
  <xtf-cascader
    v-model="selected"
    :options="options"
    title="选择部门"
    :field-names="{ text: 'name', value: 'id', children: 'subs' }"
    closeable
  />
</template>

<script>
export default {
  data() {
    return {
      selected: [],
      options: [
        {
          name: '技术部',
          id: 'tech',
          subs: [
            { name: '前端组', id: 'frontend' },
            { name: '后端组', id: 'backend' }
          ]
        }
      ]
    }
  }
}
</script>

全部属性 ​

属性类型默认值作用描述适用范围
modelValueArray[]选中值路径双向绑定
optionsArray[]级联数据数据源
showBooleanfalse是否显示弹出层控制显示
titleString''弹出层标题标题
placeholderString''占位文本占位提示
activeColorString''选中高亮色自定义高亮色
closeableBooleanfalse是否显示关闭按钮关闭按钮
ellipsisBooleantrue选项文字是否省略文字省略
fieldNamesObject{ text: 'text', value: 'value', children: 'children' }字段名映射自定义字段
popupHeightString | Number560弹出层选项滚动区的基准高度（rpx），组件会扣除标题区高度控制高度
zIndexNumber100弹出层层级层级控制
multipleBooleanfalse是否多选多选
checkStrictlyBooleanfalse父子节点选择是否不关联父子不关联
showActionsBooleanfalse是否显示底部操作按钮操作按钮
useFieldBooleantrue是否显示字段触发器字段模式
filterableBooleanfalse是否可搜索过滤搜索过滤
filterPlaceholderString''搜索占位文本搜索提示
customClassString''自定义类名样式覆盖
customStyleString | Object''自定义样式动态样式覆盖

事件 ​

事件名称触发时机回调参数参数说明
update:modelValue选中值变更时触发(value: Array)新的选中值路径
update:show弹出层显示状态变更时触发(show: Boolean)新的显示状态
change选择任一级节点或切换多选叶子节点时触发(payload: Object)单选时为 { value, selected }；多选叶子节点时为 { value, selected, multiple: true }
finish完成叶子节点选择或点击确认时触发(payload: { value: Array, selected: Object, path: Array })value 为完整值路径，selected 为最后选中项，path 为完整节点路径
close关闭弹出层时触发--
tab-changeTab 切换时触发(payload: { index: Number, tab: Object })index 为新 Tab 索引，tab 为当前 Tab 数据

事件使用示例 ​

vue
<template>
  <xtf-cascader
    v-model="selected"
    :options="options"
    title="选择地区"
    @change="onChange"
    @finish="onFinish"
    @tab-change="onTabChange"
    @close="onClose"
  />
</template>

<script>
export default {
  data() {
    return {
      selected: [],
      options: [{ text: '浙江省', value: 'zj', children: [{ text: '杭州市', value: 'hz' }] }]
    }
  },
  methods: {
    onChange({ value, selected }) {
      console.log('当前选择', value, selected)
    },
    onFinish({ value, path }) {
      console.log('完成选择', value, path)
    },
    onTabChange({ index, tab }) {
      console.log('切换层级', index, tab)
    },
    onClose() {
      console.log('选择器已关闭')
    }
  }
}
</script>

主题说明 ​

  • 选中高亮色使用 --xtf-cascader-active-color，默认取 var(--xtf-color-primary)
  • popupHeight 已在组件源码中定义并用于计算选项滚动区高度。
  • 弹出层使用 xtf-popup 组件的底部弹出样式
  • Tab 使用 xtf-tabs 的 line 变体
  • 搜索框使用 xtf-input 组件

如需全局调整主题，请在 xtf-config-provider 或主题配置中覆盖上述 CSS 变量。

MIT Licensed

Copyright © 2026 xtf-linkui