开发预览更新于 2026-05-10

Cascader 级联选择

多级选项的逐列展开选择器，路径式选取，常用于地区 / 部门 / 分类筛选。

基础用法

options 是一棵树，叶节点点击后选中整条路径；v-model / value 是 string[]，从根到选中节点的 value 序列。

背景视口

选中：(无)

src/App.vue

<script setup lang="ts">
import { ref } from 'vue';
import { CfCascader, type CascaderOption } from '@chufix-design/vue';

const options: CascaderOption[] = [
  {
    value: 'cn',
    label: '中国',
    children: [
      {
        value: 'sh',
        label: '上海',
        children: [
          { value: 'pudong', label: '浦东新区' },
          { value: 'huangpu', label: '黄浦区' },
        ],
      },
      {
        value: 'bj',
        label: '北京',
        children: [
          { value: 'haidian', label: '海淀区' },
          { value: 'chaoyang', label: '朝阳区' },
        ],
      },
    ],
  },
  {
    value: 'us',
    label: '美国',
    children: [
      { value: 'ny', label: '纽约', children: [{ value: 'manhattan', label: 'Manhattan' }] },
    ],
  },
];

const value = ref<string[]>([]);
</script>
<template>
  <div style="display: flex; flex-direction: column; gap: 8px; align-items: flex-start;">
    <CfCascader v-model="value" :options="options" clearable />
    <span style="font-size: 12px; color: var(--fg-3);">选中：<code>{{ value.join(' / ') || '(无)' }}</code></span>
  </div>
</template>

<script setup>
import { ref } from 'vue';
import { CfCascader } from '@chufix-design/vue';

const options= [
  {
    value: 'cn',
    label: '中国',
    children: [
      {
        value: 'sh',
        label: '上海',
        children: [
          { value: 'pudong', label: '浦东新区' },
          { value: 'huangpu', label: '黄浦区' },
        ],
      },
      {
        value: 'bj',
        label: '北京',
        children: [
          { value: 'haidian', label: '海淀区' },
          { value: 'chaoyang', label: '朝阳区' },
        ],
      },
    ],
  },
  {
    value: 'us',
    label: '美国',
    children: [
      { value: 'ny', label: '纽约', children: [{ value: 'manhattan', label: 'Manhattan' }] },
    ],
  },
];

const value = ref<string[]>([]);
</script>
<template>
  <div style="display: flex; flex-direction: column; gap: 8px; align-items: flex-start;">
    <CfCascader v-model="value" :options="options" clearable />
    <span style="font-size: 12px; color: var(--fg-3);">选中：<code>{{ value.join(' / ') || '(无)' }}</code></span>
  </div>
</template>

import { useState } from 'react';
import { CfCascader } from '@chufix-design/react';

export default function Demo() {
  const options: CascaderOption[] = [
    {
      value: 'cn',
      label: '中国',
      children: [
        {
          value: 'sh',
          label: '上海',
          children: [
            { value: 'pudong', label: '浦东新区' },
            { value: 'huangpu', label: '黄浦区' },
          ],
        },
        {
          value: 'bj',
          label: '北京',
          children: [
            { value: 'haidian', label: '海淀区' },
            { value: 'chaoyang', label: '朝阳区' },
          ],
        },
      ],
    },
    {
      value: 'us',
      label: '美国',
      children: [
        { value: 'ny', label: '纽约', children: [{ value: 'manhattan', label: 'Manhattan' }] },
      ],
    },
  ];

  const [value, setValue] = useState<string[]>([]);
  return (
    <>
      <div style={{ display: "flex", flexDirection: "column", gap: 8, alignItems: "flex-start" }}>
          <CfCascader value={value} onChange={setValue} options={options} clearable />
          <span style={{ fontSize: 12, color: "var(--fg-3)" }}>选中：<code>{value.join(' / ') || '(无)'}</code></span>
        </div>
    </>
  );
}

import { useState } from 'react';
import { CfCascader } from '@chufix-design/react';

export default function Demo() {
  const options= [
    {
      value: 'cn',
      label: '中国',
      children: [
        {
          value: 'sh',
          label: '上海',
          children: [
            { value: 'pudong', label: '浦东新区' },
            { value: 'huangpu', label: '黄浦区' },
          ],
        },
        {
          value: 'bj',
          label: '北京',
          children: [
            { value: 'haidian', label: '海淀区' },
            { value: 'chaoyang', label: '朝阳区' },
          ],
        },
      ],
    },
    {
      value: 'us',
      label: '美国',
      children: [
        { value: 'ny', label: '纽约', children: [{ value: 'manhattan', label: 'Manhattan' }] },
      ],
    },
  ];

  const [value, setValue] = useState<string[]>([]);
  return (
    <>
      <div style={{ display: "flex", flexDirection: "column", gap: 8, alignItems: "flex-start" }}>
          <CfCascader value={value} onChange={setValue} options={options} clearable />
          <span style={{ fontSize: 12, color: "var(--fg-3)" }}>选中：<code>{value.join(' / ') || '(无)'}</code></span>
        </div>
    </>
  );
}

API

属性	类型	默认值	说明
`options`	`CascaderOption[]`	`—`	级联选项树
`value` / `modelValue`	`string[]`	`—`	受控选中路径
`defaultValue`	`string[]`	`[]`	非受控初始值
`placeholder`	`string`	`'请选择'`	未选中时占位文案
`separator`	`string`	`' / '`	触发器中显示的路径分隔符
`size`	`'sm' \| 'md' \| 'lg'`	`'md'`	触发器尺寸
`disabled`	`boolean`	`false`	禁用
`clearable`	`boolean`	`false`	显示清除按钮

CascaderOption

字段	类型	说明
`value`	`string`	唯一值
`label`	`string`	显示文本
`disabled`	`boolean`	禁用此项
`children`	`CascaderOption[]`	下一级选项；省略代表叶节点

Events

Vue 事件	React 回调	载荷类型	说明
`update:modelValue`	`onChange`	`string[]`	选中路径变化时触发，载荷是从根到叶的 value 序列
`change`	`onChange`	`string[]`	与 `update:modelValue` 同步触发，载荷相同