Cascader 级联选择

从相关联的数据集合中进行多级选择

何时使用

  • 需要在多层级数据中选择某一项时。
  • 数据结构为父子层级（如省市区、组织架构）时。

placeholder、notFoundContent 默认跟随全局语言（zh-CN / zh-TW / en-US），传 prop 可覆盖。

选中：（未选择）

导入

import { Cascader } from "@reglow/reui";
import type { CascaderOption } from "@reglow/reui";

基础用法

省市区级联。

<script setup lang="ts">
import { ref } from "vue";
import { Cascader } from "@reglow/reui";
import type { CascaderOption } from "@reglow/reui";

const value = ref<string[]>([]);

const options: CascaderOption[] = [
  {
    value: "zhejiang",
    label: "浙江",
    children: [
      {
        value: "hangzhou",
        label: "杭州",
        children: [
          { value: "xihu", label: "西湖" },
        ],
      },
    ],
  },
  {
    value: "jiangsu",
    label: "江苏",
    children: [
      {
        value: "nanjing",
        label: "南京",
        children: [
          { value: "zhonghuamen", label: "中华门" },
        ],
      },
    ],
  },
];
</script>

<template>
  <Cascader
    v-model="value"
    :options="options"
    placeholder="请选择"
    class="w-[300px]"
  />
</template>

更多示例

默认值

默认值通过数组的方式指定。

<template>
  <Cascader
    :default-value="['zhejiang', 'hangzhou', 'xihu']"
    :options="options"
    class="w-[300px]"
  />
</template>

选择即改变

允许只选中父级选项，不必选到叶子节点。

<Cascader :options="options" change-on-select />

移入展开

通过移入展开下级菜单，点击完成选择。

<Cascader :options="options" expand-trigger="hover" />

搜索

可以直接搜索选项并选择。

<script setup>
const filter = (input, path) =>
  path.some((option) =>
    option.label.toLowerCase().includes(input.toLowerCase())
  );
</script>

<template>
  <Cascader
    :options="options"
    :show-search="{ filter, onSearch: (val) => console.log(val) }"
    placeholder="请选择"
  />
</template>

自定义字段名

自定义字段名。

<script setup>
const options = [
  {
    code: "zhejiang",
    name: "浙江",
    items: [
      {
        code: "hangzhou",
        name: "杭州",
        items: [{ code: "xihu", name: "西湖" }],
      },
    ],
  },
];
</script>

<template>
  <Cascader
    :options="options"
    :field-names="{ label: 'name', value: 'code', children: 'items' }"
    placeholder="请选择"
  />
</template>

动态加载选项

使用 loadData 实现动态加载选项。

<script setup>
import { ref } from "vue";

const options = ref([
  { value: "zhejiang", label: "浙江", isLeaf: false },
  { value: "jiangsu", label: "江苏", isLeaf: false },
]);

const loadData = async (selectedOptions) => {
  const target = selectedOptions[selectedOptions.length - 1];
  // 模拟异步请求
  await new Promise((resolve) => setTimeout(resolve, 1000));
  target.children = [
    { label: `${target.label} 动态1`, value: "dynamic1" },
    { label: `${target.label} 动态2`, value: "dynamic2" },
  ];
};
</script>

<template>
  <Cascader
    :options="options"
    :load-data="loadData"
    change-on-select
    placeholder="请选择"
  />
</template>

大小

不同大小的级联选择器。

<template>
  <div class="flex flex-col gap-2 w-[300px]">
    <Cascader size="large" :options="options" placeholder="大型" />
    <Cascader :options="options" placeholder="默认" />
    <Cascader size="small" :options="options" placeholder="小型" />
  </div>
</template>

自定义触发器

通过默认 slot 自定义触发器。

<template>
  <Cascader :options="options" v-model="value">
    <Button variant="outline">
      {{ displayText || "请选择" }}
    </Button>
  </Cascader>
</template>

API

Props

参数说明类型默认值
options可选项数据源CascaderOption[]-
modelValue (v-model)当前值(string | number)[][]
defaultValue默认值(string | number)[][]
placeholder占位文字string请选择
disabled是否禁用booleanfalse
allowClear是否支持清除booleantrue
size输入框大小small | medium | largemedium
fieldNames自定义字段名CascaderFieldNames-
expandTrigger展开触发方式click | hoverclick
changeOnSelect选择即改变，允许只选中父级booleanfalse
showSearch是否支持搜索boolean | CascaderSearchConfigfalse
notFoundContent无数据时显示string无数据
separator分隔符string/
loadData动态加载选项(selectedOptions) => Promise<void>-
side弹出位置top | bottom | left | rightbottom
sideOffset偏移量number4
align对齐方式start | center | endstart

Events

事件说明回调参数
change选择完成后的回调(value, selectedOptions)
search搜索时的回调(value: string)

Slots

名称说明
default自定义触发器内容
suffixIcon自定义后缀图标
expandIcon自定义展开图标
notFoundContent自定义无数据内容

CascaderOption

参数说明类型
value值string | number
label标签string
disabled是否禁用boolean
isLeaf是否叶子节点boolean
children子选项CascaderOption[]

CascaderFieldNames

参数说明默认值
label标签字段名label
value值字段名value
children子选项字段名children
disabled禁用字段名disabled
isLeaf叶子节点字段名isLeaf

CascaderSearchConfig

参数说明类型
filter过滤函数(input, path) => boolean
onSearch搜索回调(value: string) => void
limit搜索结果限制number | false
AutoComplete 自动完成
本质是增强型 Input：监听输入给出建议列表，保留上次选中值，只允许字符串返回。
Checkbox 复选框
Checkbox 复选框