级联选择 cascader

数据录入组件。三层同源：无头内核给出解剖与状态机，Vue 组件与自定义元素只是它的两层外壳，行为完全一致。

示例

基础用法

collection 是层级、显示文本与禁用的唯一事实源；levels 按深度摊开，每层一个 column

收货地区

当前路径：（未选）

<script setup lang="ts">
import { ref } from "vue";
import {
  XhCascaderColumn,
  XhCascaderContent,
  XhCascaderIndicator,
  XhCascaderItem,
  XhCascaderItemIndicator,
  XhCascaderItemText,
  XhCascaderLabel,
  XhCascaderPositioner,
  XhCascaderRoot,
  XhCascaderTrigger,
  XhCascaderValueText,
} from "@xihan-ui/vue";

const regions = [
  {
    value: "zhejiang",
    label: "浙江",
    children: [
      {
        value: "hangzhou",
        label: "杭州",
        children: [
          { value: "xihu", label: "西湖区" },
          { value: "binjiang", label: "滨江区" },
        ],
      },
      {
        value: "ningbo",
        label: "宁波",
        children: [{ value: "haishu", label: "海曙区" }],
      },
    ],
  },
  {
    value: "jiangsu",
    label: "江苏",
    children: [
      {
        value: "nanjing",
        label: "南京",
        children: [
          { value: "xuanwu", label: "玄武区" },
          { value: "gulou", label: "鼓楼区（暂不开放）", disabled: true },
        ],
      },
    ],
  },
];

const area = ref<string[][]>([]);
</script>

<template>
  <XhCascaderRoot v-slot="{ levels }" v-model:value="area" :collection="regions" placeholder="请选择地区">
    <XhCascaderLabel>收货地区</XhCascaderLabel>
    <XhCascaderTrigger>
      <XhCascaderValueText />
      <XhCascaderIndicator>▾</XhCascaderIndicator>
    </XhCascaderTrigger>
    <XhCascaderPositioner>
      <XhCascaderContent>
        <XhCascaderColumn v-for="lv in levels" :key="lv.level" :level="lv.level">
          <XhCascaderItem v-for="node in lv.items" :key="node.value" :value="node.value">
            <XhCascaderItemText>{{ node.label }}</XhCascaderItemText>
            <XhCascaderItemIndicator>✓</XhCascaderItemIndicator>
          </XhCascaderItem>
        </XhCascaderColumn>
      </XhCascaderContent>
    </XhCascaderPositioner>
  </XhCascaderRoot>
  <p>当前路径：{{ area.length ? area[0].join(" / ") : "（未选）" }}</p>
</template>

中间层可选

change-on-select 让分支自己也能落值；选中分支后浮层不收起，还能接着往下挑

栏目

当前路径：（未选）

<script setup lang="ts">
import { ref } from "vue";
import {
  XhCascaderClearTrigger,
  XhCascaderColumn,
  XhCascaderContent,
  XhCascaderIndicator,
  XhCascaderItem,
  XhCascaderItemIndicator,
  XhCascaderItemText,
  XhCascaderLabel,
  XhCascaderPositioner,
  XhCascaderRoot,
  XhCascaderTrigger,
  XhCascaderValueText,
} from "@xihan-ui/vue";

const catalog = [
  {
    value: "docs",
    label: "文档",
    children: [
      { value: "guide", label: "指南" },
      { value: "api", label: "接口" },
    ],
  },
  {
    value: "design",
    label: "设计",
    children: [
      { value: "token", label: "设计令牌" },
      { value: "icon", label: "图标" },
    ],
  },
];

const path = ref<string[][]>([]);
</script>

<template>
  <XhCascaderRoot
    v-slot="{ levels }"
    v-model:value="path"
    :collection="catalog"
    change-on-select
    separator=" › "
    placeholder="选一个栏目"
  >
    <XhCascaderLabel>栏目</XhCascaderLabel>
    <XhCascaderTrigger>
      <XhCascaderValueText />
      <XhCascaderIndicator>▾</XhCascaderIndicator>
    </XhCascaderTrigger>
    <XhCascaderClearTrigger>✕</XhCascaderClearTrigger>
    <XhCascaderPositioner>
      <XhCascaderContent>
        <XhCascaderColumn v-for="lv in levels" :key="lv.level" :level="lv.level">
          <XhCascaderItem v-for="node in lv.items" :key="node.value" :value="node.value">
            <XhCascaderItemText>{{ node.label }}</XhCascaderItemText>
            <XhCascaderItemIndicator>✓</XhCascaderItemIndicator>
          </XhCascaderItem>
        </XhCascaderColumn>
      </XhCascaderContent>
    </XhCascaderPositioner>
  </XhCascaderRoot>
  <p>当前路径：{{ path.length ? path[0].join(" › ") : "（未选）" }}</p>
</template>

悬停展开

expand-trigger 改成 hover 后，指针划过分支即开子列，只挪展开路径不抢焦点；键盘仍走右方向键

方向

当前路径：（未选）

<script setup lang="ts">
import { ref } from "vue";
import {
  XhCascaderColumn,
  XhCascaderContent,
  XhCascaderIndicator,
  XhCascaderItem,
  XhCascaderItemIndicator,
  XhCascaderItemText,
  XhCascaderLabel,
  XhCascaderPositioner,
  XhCascaderRoot,
  XhCascaderTrigger,
  XhCascaderValueText,
} from "@xihan-ui/vue";

const menu = [
  {
    value: "frontend",
    label: "前端",
    children: [
      { value: "vue", label: "Vue" },
      { value: "wc", label: "Web Components" },
    ],
  },
  {
    value: "backend",
    label: "后端",
    children: [
      { value: "dotnet", label: ".NET" },
      { value: "node", label: "Node.js" },
    ],
  },
];

const picked = ref<string[][]>([]);
</script>

<template>
  <XhCascaderRoot
    v-slot="{ levels }"
    v-model:value="picked"
    :collection="menu"
    expand-trigger="hover"
    placeholder="划过即展开"
  >
    <XhCascaderLabel>方向</XhCascaderLabel>
    <XhCascaderTrigger>
      <XhCascaderValueText />
      <XhCascaderIndicator>▾</XhCascaderIndicator>
    </XhCascaderTrigger>
    <XhCascaderPositioner>
      <XhCascaderContent>
        <XhCascaderColumn v-for="lv in levels" :key="lv.level" :level="lv.level">
          <XhCascaderItem v-for="node in lv.items" :key="node.value" :value="node.value">
            <XhCascaderItemText>{{ node.label }}</XhCascaderItemText>
            <XhCascaderItemIndicator>✓</XhCascaderItemIndicator>
          </XhCascaderItem>
        </XhCascaderColumn>
      </XhCascaderContent>
    </XhCascaderPositioner>
  </XhCascaderRoot>
  <p>当前路径：{{ picked.length ? picked[0].join(" / ") : "（未选）" }}</p>
</template>

多选

选中的是一组路径，落值后浮层不收起、焦点留在列里接着挑；再点一次即取消

采购清单

已选 1 条：fruit/apple

<script setup lang="ts">
import { ref } from "vue";
import {
  XhCascaderClearTrigger,
  XhCascaderColumn,
  XhCascaderContent,
  XhCascaderIndicator,
  XhCascaderItem,
  XhCascaderItemIndicator,
  XhCascaderItemText,
  XhCascaderLabel,
  XhCascaderPositioner,
  XhCascaderRoot,
  XhCascaderTrigger,
  XhCascaderValueText,
} from "@xihan-ui/vue";

const catalog = [
  {
    value: "fruit",
    label: "水果",
    children: [
      { value: "apple", label: "苹果" },
      { value: "banana", label: "香蕉" },
    ],
  },
  {
    value: "vegetable",
    label: "蔬菜",
    children: [
      { value: "tomato", label: "番茄" },
      { value: "potato", label: "土豆" },
    ],
  },
];

const picked = ref<string[][]>([["fruit", "apple"]]);
</script>

<template>
  <XhCascaderRoot
    v-slot="{ levels }"
    v-model:value="picked"
    :collection="catalog"
    multiple
    placeholder="可以多挑几条"
  >
    <XhCascaderLabel>采购清单</XhCascaderLabel>
    <XhCascaderTrigger>
      <XhCascaderValueText />
      <XhCascaderIndicator>▾</XhCascaderIndicator>
    </XhCascaderTrigger>
    <XhCascaderClearTrigger>✕</XhCascaderClearTrigger>
    <XhCascaderPositioner>
      <XhCascaderContent>
        <XhCascaderColumn v-for="lv in levels" :key="lv.level" :level="lv.level">
          <XhCascaderItem v-for="node in lv.items" :key="node.value" :value="node.value">
            <XhCascaderItemText>{{ node.label }}</XhCascaderItemText>
            <XhCascaderItemIndicator>✓</XhCascaderItemIndicator>
          </XhCascaderItem>
        </XhCascaderColumn>
      </XhCascaderContent>
    </XhCascaderPositioner>
  </XhCascaderRoot>
  <p>已选 {{ picked.length }} 条：{{ picked.map((p) => p.join("/")).join("、") || "（无）" }}</p>
</template>

形态

variant 只改触发框的底色与描边用法，浮层与列不跟着变

outline

subtle

ghost

<script setup lang="ts">
import {
  XhCascaderColumn,
  XhCascaderContent,
  XhCascaderIndicator,
  XhCascaderItem,
  XhCascaderItemText,
  XhCascaderLabel,
  XhCascaderPositioner,
  XhCascaderRoot,
  XhCascaderTrigger,
  XhCascaderValueText,
} from "@xihan-ui/vue";

const variants = ["outline", "subtle", "ghost"] as const;

const regions = [
  {
    value: "zhejiang",
    label: "浙江",
    children: [
      { value: "hangzhou", label: "杭州" },
      { value: "ningbo", label: "宁波" },
    ],
  },
  {
    value: "jiangsu",
    label: "江苏",
    children: [{ value: "nanjing", label: "南京" }],
  },
];
</script>

<template>
  <div style="display: grid; gap: 16px; justify-items: start">
    <XhCascaderRoot
      v-for="v in variants"
      :key="v"
      v-slot="{ levels }"
      :variant="v"
      :collection="regions"
      placeholder="请选择地区"
    >
      <XhCascaderLabel>{{ v }}</XhCascaderLabel>
      <XhCascaderTrigger>
        <XhCascaderValueText />
        <XhCascaderIndicator>▾</XhCascaderIndicator>
      </XhCascaderTrigger>
      <XhCascaderPositioner>
        <XhCascaderContent>
          <XhCascaderColumn v-for="lv in levels" :key="lv.level" :level="lv.level">
            <XhCascaderItem v-for="node in lv.items" :key="node.value" :value="node.value">
              <XhCascaderItemText>{{ node.label }}</XhCascaderItemText>
            </XhCascaderItem>
          </XhCascaderColumn>
        </XhCascaderContent>
      </XhCascaderPositioner>
    </XhCascaderRoot>
  </div>
</template>

语气

tone 决定用哪族颜色，与 variant 正交；这里固定 subtle 形态，只看语气这一轴

brand

neutral

success

warning

danger

info

<script setup lang="ts">
import {
  XhCascaderColumn,
  XhCascaderContent,
  XhCascaderIndicator,
  XhCascaderItem,
  XhCascaderItemText,
  XhCascaderLabel,
  XhCascaderPositioner,
  XhCascaderRoot,
  XhCascaderTrigger,
  XhCascaderValueText,
} from "@xihan-ui/vue";

const tones = ["brand", "neutral", "success", "warning", "danger", "info"] as const;

const regions = [
  {
    value: "zhejiang",
    label: "浙江",
    children: [
      { value: "hangzhou", label: "杭州" },
      { value: "ningbo", label: "宁波" },
    ],
  },
  {
    value: "jiangsu",
    label: "江苏",
    children: [{ value: "nanjing", label: "南京" }],
  },
];
</script>

<template>
  <div style="display: flex; flex-wrap: wrap; gap: 16px">
    <XhCascaderRoot
      v-for="t in tones"
      :key="t"
      v-slot="{ levels }"
      variant="subtle"
      :tone="t"
      :collection="regions"
      placeholder="请选择地区"
    >
      <XhCascaderLabel>{{ t }}</XhCascaderLabel>
      <XhCascaderTrigger>
        <XhCascaderValueText />
        <XhCascaderIndicator>▾</XhCascaderIndicator>
      </XhCascaderTrigger>
      <XhCascaderPositioner>
        <XhCascaderContent>
          <XhCascaderColumn v-for="lv in levels" :key="lv.level" :level="lv.level">
            <XhCascaderItem v-for="node in lv.items" :key="node.value" :value="node.value">
              <XhCascaderItemText>{{ node.label }}</XhCascaderItemText>
            </XhCascaderItem>
          </XhCascaderColumn>
        </XhCascaderContent>
      </XhCascaderPositioner>
    </XhCascaderRoot>
  </div>
</template>

尺寸

不传 size 即默认档；触发框与列里的条目一起换档

sm

默认

lg

<script setup lang="ts">
import {
  XhCascaderColumn,
  XhCascaderContent,
  XhCascaderIndicator,
  XhCascaderItem,
  XhCascaderItemText,
  XhCascaderLabel,
  XhCascaderPositioner,
  XhCascaderRoot,
  XhCascaderTrigger,
  XhCascaderValueText,
} from "@xihan-ui/vue";

const sizes = [
  { size: "sm", label: "sm" },
  { size: undefined, label: "默认" },
  { size: "lg", label: "lg" },
];

const regions = [
  {
    value: "zhejiang",
    label: "浙江",
    children: [
      { value: "hangzhou", label: "杭州" },
      { value: "ningbo", label: "宁波" },
    ],
  },
  {
    value: "jiangsu",
    label: "江苏",
    children: [{ value: "nanjing", label: "南京" }],
  },
];
</script>

<template>
  <div style="display: flex; flex-wrap: wrap; align-items: flex-end; gap: 16px">
    <XhCascaderRoot
      v-for="s in sizes"
      :key="s.label"
      v-slot="{ levels }"
      :size="s.size"
      :collection="regions"
      placeholder="请选择地区"
    >
      <XhCascaderLabel>{{ s.label }}</XhCascaderLabel>
      <XhCascaderTrigger>
        <XhCascaderValueText />
        <XhCascaderIndicator>▾</XhCascaderIndicator>
      </XhCascaderTrigger>
      <XhCascaderPositioner>
        <XhCascaderContent>
          <XhCascaderColumn v-for="lv in levels" :key="lv.level" :level="lv.level">
            <XhCascaderItem v-for="node in lv.items" :key="node.value" :value="node.value">
              <XhCascaderItemText>{{ node.label }}</XhCascaderItemText>
            </XhCascaderItem>
          </XhCascaderColumn>
        </XhCascaderContent>
      </XhCascaderPositioner>
    </XhCascaderRoot>
  </div>
</template>

校验状态

invalid 让 trigger 报 aria-invalid、描边换成错误色；浮层照常展开，判定归宿主，这里是没选就报错

所属部门

这一项必填

<script setup lang="ts">
import { computed, ref } from "vue";
import {
  XhCascaderClearTrigger,
  XhCascaderColumn,
  XhCascaderContent,
  XhCascaderIndicator,
  XhCascaderItem,
  XhCascaderItemIndicator,
  XhCascaderItemText,
  XhCascaderLabel,
  XhCascaderPositioner,
  XhCascaderRoot,
  XhCascaderTrigger,
  XhCascaderValueText,
} from "@xihan-ui/vue";

const departments = [
  {
    value: "product",
    label: "产品线",
    children: [
      { value: "design", label: "设计组" },
      { value: "research", label: "用研组" },
    ],
  },
  {
    value: "tech",
    label: "技术线",
    children: [
      { value: "web", label: "前端组" },
      { value: "server", label: "服务端组" },
    ],
  },
];

const dept = ref<string[][]>([]);
// 校验归宿主，组件只负责把这个结论铺成属性
const invalid = computed(() => dept.value.length === 0);
</script>

<template>
  <XhCascaderRoot
    v-slot="{ levels }"
    v-model:value="dept"
    :collection="departments"
    :invalid="invalid"
    placeholder="请选到具体的组"
  >
    <XhCascaderLabel>所属部门</XhCascaderLabel>
    <XhCascaderTrigger>
      <XhCascaderValueText />
      <XhCascaderIndicator>▾</XhCascaderIndicator>
    </XhCascaderTrigger>
    <XhCascaderClearTrigger>✕</XhCascaderClearTrigger>
    <XhCascaderPositioner>
      <XhCascaderContent>
        <XhCascaderColumn v-for="lv in levels" :key="lv.level" :level="lv.level">
          <XhCascaderItem v-for="node in lv.items" :key="node.value" :value="node.value">
            <XhCascaderItemText>{{ node.label }}</XhCascaderItemText>
            <XhCascaderItemIndicator>✓</XhCascaderItemIndicator>
          </XhCascaderItem>
        </XhCascaderColumn>
      </XhCascaderContent>
    </XhCascaderPositioner>
  </XhCascaderRoot>
  <p v-if="invalid" style="color: var(--xh-fg-danger)">这一项必填</p>
</template>

后端字段映射

collection 只认 value / label / disabled / children 这几个名字，后端字段不一致就在进组件前转一道

服务区域

选中的是转换后的 value：（未选）

<script setup lang="ts">
import { ref } from "vue";
import {
  XhCascaderColumn,
  XhCascaderContent,
  XhCascaderIndicator,
  XhCascaderItem,
  XhCascaderItemIndicator,
  XhCascaderItemText,
  XhCascaderLabel,
  XhCascaderPositioner,
  XhCascaderRoot,
  XhCascaderTrigger,
  XhCascaderValueText,
} from "@xihan-ui/vue";

// 后端原样返回的树：键名与组件对不上
interface RawNode {
  code: string;
  name: string;
  frozen?: boolean;
  sub?: RawNode[];
}

interface RegionNode {
  value: string;
  label: string;
  disabled?: boolean;
  children?: RegionNode[];
}

const raw: RawNode[] = [
  {
    code: "east",
    name: "华东",
    sub: [
      {
        code: "shanghai",
        name: "上海",
        sub: [
          { code: "pudong", name: "浦东新区" },
          { code: "xuhui", name: "徐汇区" },
        ],
      },
      {
        code: "hangzhou",
        name: "杭州",
        sub: [{ code: "xihu", name: "西湖区" }],
      },
    ],
  },
  {
    code: "south",
    name: "华南",
    sub: [
      {
        code: "guangzhou",
        name: "广州",
        sub: [{ code: "tianhe", name: "天河区" }],
      },
      { code: "shenzhen", name: "深圳", frozen: true },
    ],
  },
];

function toNodes(list: RawNode[]): RegionNode[] {
  return list.map((item) => ({
    value: item.code,
    label: item.name,
    disabled: item.frozen,
    children: item.sub ? toNodes(item.sub) : undefined,
  }));
}

const regions = toNodes(raw);
const area = ref<string[][]>([]);
</script>

<template>
  <XhCascaderRoot
    v-slot="{ levels }"
    v-model:value="area"
    :collection="regions"
    placeholder="请选择服务区域"
  >
    <XhCascaderLabel>服务区域</XhCascaderLabel>
    <XhCascaderTrigger>
      <XhCascaderValueText />
      <XhCascaderIndicator>▾</XhCascaderIndicator>
    </XhCascaderTrigger>
    <XhCascaderPositioner>
      <XhCascaderContent>
        <XhCascaderColumn v-for="lv in levels" :key="lv.level" :level="lv.level">
          <XhCascaderItem v-for="node in lv.items" :key="node.value" :value="node.value">
            <XhCascaderItemText>{{ node.label }}</XhCascaderItemText>
            <XhCascaderItemIndicator>✓</XhCascaderItemIndicator>
          </XhCascaderItem>
        </XhCascaderColumn>
      </XhCascaderContent>
    </XhCascaderPositioner>
  </XhCascaderRoot>
  <p>选中的是转换后的 value：{{ area.length ? area[0].join(" / ") : "（未选）" }}</p>
</template>

条目自定义内容

条目里放什么由作者定：文本两侧各加一段，是不是分支直接读 item 的 branch

团队

当前团队：（未选）

<script setup lang="ts">
import { ref } from "vue";
import {
  XhCascaderColumn,
  XhCascaderContent,
  XhCascaderIndicator,
  XhCascaderItem,
  XhCascaderItemIndicator,
  XhCascaderItemText,
  XhCascaderLabel,
  XhCascaderPositioner,
  XhCascaderRoot,
  XhCascaderTrigger,
  XhCascaderValueText,
} from "@xihan-ui/vue";

const org = [
  {
    value: "product",
    label: "产品线",
    children: [
      { value: "design", label: "设计组" },
      { value: "research", label: "用研组" },
    ],
  },
  {
    value: "tech",
    label: "技术线",
    children: [
      { value: "web", label: "前端组" },
      { value: "server", label: "服务端组" },
    ],
  },
];

// 条目上的附加信息由作者自己按值查，组件只管值与层级
const headcount: Record<string, number> = {
  product: 18,
  design: 11,
  research: 7,
  tech: 32,
  web: 14,
  server: 18,
};

const dept = ref<string[][]>([]);
</script>

<template>
  <XhCascaderRoot
    v-slot="{ levels }"
    v-model:value="dept"
    :collection="org"
    placeholder="请选择团队"
  >
    <XhCascaderLabel>团队</XhCascaderLabel>
    <XhCascaderTrigger>
      <XhCascaderValueText />
      <XhCascaderIndicator>▾</XhCascaderIndicator>
    </XhCascaderTrigger>
    <XhCascaderPositioner>
      <XhCascaderContent>
        <XhCascaderColumn v-for="lv in levels" :key="lv.level" :level="lv.level">
          <XhCascaderItem v-for="node in lv.items" :key="node.value" :value="node.value">
            <span aria-hidden="true" style="flex: none; color: var(--xh-fg-subtle)">
              {{ node.branch ? "▸" : "·" }}
            </span>
            <XhCascaderItemText>{{ node.label }}</XhCascaderItemText>
            <span style="flex: none; color: var(--xh-fg-subtle); font-size: 12px">
              {{ headcount[node.value] }} 人
            </span>
            <XhCascaderItemIndicator>✓</XhCascaderItemIndicator>
          </XhCascaderItem>
        </XhCascaderColumn>
      </XhCascaderContent>
    </XhCascaderPositioner>
  </XhCascaderRoot>
  <p>当前团队：{{ dept.length ? dept[0].join(" / ") : "（未选）" }}</p>
</template>

子节点按需加载

先给分支塞一个禁用的占位子节点让子列开得出来，展开到它时才去取真数据换掉占位

收货地区

当前路径：（未选）

<script setup lang="ts">
import { ref } from "vue";
import {
  XhCascaderColumn,
  XhCascaderContent,
  XhCascaderIndicator,
  XhCascaderItem,
  XhCascaderItemIndicator,
  XhCascaderItemText,
  XhCascaderLabel,
  XhCascaderPositioner,
  XhCascaderRoot,
  XhCascaderTrigger,
  XhCascaderValueText,
} from "@xihan-ui/vue";

interface RegionNode {
  value: string;
  label: string;
  disabled?: boolean;
  children?: RegionNode[];
}

// 下一层的数据在后端，这里用定时器代替一次请求
const remote: Record<string, RegionNode[]> = {
  zhejiang: [
    { value: "hangzhou", label: "杭州" },
    { value: "ningbo", label: "宁波" },
    { value: "wenzhou", label: "温州" },
  ],
  jiangsu: [
    { value: "nanjing", label: "南京" },
    { value: "suzhou", label: "苏州" },
  ],
};

// 占位子节点：children 非空才算分支，子列才开得出来；禁用让方向键跳过它，也点不动
function pending(parent: string): RegionNode {
  return { value: `${parent}:pending`, label: "加载中…", disabled: true };
}

const regions = ref<RegionNode[]>([
  { value: "zhejiang", label: "浙江", children: [pending("zhejiang")] },
  { value: "jiangsu", label: "江苏", children: [pending("jiangsu")] },
]);

const loading = ref<string[]>([]);
const loaded = ref<string[]>([]);

// 点开或键盘走到这一支时才取它的子节点，取回来把占位那一条整个换掉
function load(value: string) {
  const children = remote[value];
  if (!children || loading.value.includes(value) || loaded.value.includes(value)) {
    return;
  }
  loading.value = [...loading.value, value];
  setTimeout(() => {
    const node = regions.value.find((item) => item.value === value);
    if (node) {
      node.children = children;
    }
    loading.value = loading.value.filter((v) => v !== value);
    loaded.value = [...loaded.value, value];
  }, 800);
}

const area = ref<string[][]>([]);
</script>

<template>
  <XhCascaderRoot
    v-slot="{ levels }"
    v-model:value="area"
    :collection="regions"
    placeholder="请选择地区"
  >
    <XhCascaderLabel>收货地区</XhCascaderLabel>
    <XhCascaderTrigger>
      <XhCascaderValueText />
      <XhCascaderIndicator>▾</XhCascaderIndicator>
    </XhCascaderTrigger>
    <XhCascaderPositioner>
      <XhCascaderContent>
        <XhCascaderColumn v-for="lv in levels" :key="lv.level" :level="lv.level">
          <XhCascaderItem
            v-for="node in lv.items"
            :key="node.value"
            :value="node.value"
            @click="load(node.value)"
            @focus="load(node.value)"
          >
            <XhCascaderItemText>{{ node.label }}</XhCascaderItemText>
            <span
              v-if="loading.includes(node.value)"
              style="flex: none; color: var(--xh-fg-subtle); font-size: 12px"
            >
              取数中
            </span>
            <XhCascaderItemIndicator>✓</XhCascaderItemIndicator>
          </XhCascaderItem>
        </XhCascaderColumn>
      </XhCascaderContent>
    </XhCascaderPositioner>
  </XhCascaderRoot>
  <p>当前路径：{{ area.length ? area[0].join(" / ") : "（未选）" }}</p>
</template>

长列表只渲可视区

列自己就是滚动容器：按滚动位置切一段挂出来，其余交给撑高块，焦点那一条无论在不在窗口里都挂着

货位（每仓 1000 条）

当前货位：（未选）

<script setup lang="ts">
import { nextTick, ref } from "vue";
import {
  XhCascaderColumn,
  XhCascaderContent,
  XhCascaderIndicator,
  XhCascaderItem,
  XhCascaderItemIndicator,
  XhCascaderItemText,
  XhCascaderLabel,
  XhCascaderPositioner,
  XhCascaderRoot,
  XhCascaderTrigger,
  XhCascaderValueText,
} from "@xihan-ui/vue";

// 行高与列高写死，窗口才算得出来
const ROW = 32;
const VIEW = 256;
const OVERSCAN = 6;

interface ColumnItem {
  value: string;
  label: string;
}

interface Column {
  level: number;
  items: ColumnItem[];
}

interface Row extends ColumnItem {
  index: number;
}

function shelves(prefix: string, name: string): ColumnItem[] {
  return Array.from({ length: 1000 }, (_, i) => ({
    value: `${prefix}-${i + 1}`,
    label: `${name}货位 ${String(i + 1).padStart(4, "0")}`,
  }));
}

const warehouses = [
  { value: "east", label: "华东仓", children: shelves("east", "华东") },
  { value: "south", label: "华南仓", children: shelves("south", "华南") },
];

// 每一列自己的滚动位置：列号 → scrollTop
const scrolled = ref<Record<number, number>>({});
const shell = ref<HTMLElement | null>(null);

function onScroll(level: number, event: Event) {
  scrolled.value = {
    ...scrolled.value,
    [level]: (event.target as HTMLElement).scrollTop,
  };
}

// 展开那一刻以列真实的滚动位置为准，重算一遍窗口
function onOpenChange(details: { open: boolean }) {
  if (!details.open) {
    return;
  }
  nextTick(() => {
    const next: Record<number, number> = {};
    shell.value
      ?.querySelectorAll<HTMLElement>('[data-part="column"]')
      .forEach((el, level) => {
        next[level] = el.scrollTop;
      });
    scrolled.value = next;
  });
}

// 方向键把焦点挪到了窗口外的一条：等它渲染出来再把浏览器焦点补上去，滚动随之跟到位
function syncFocus(event: KeyboardEvent) {
  const content = event.currentTarget as HTMLElement;
  nextTick(() => {
    const el = content.querySelector<HTMLElement>(
      '[data-part="item"][data-highlighted]',
    );
    if (el && el !== document.activeElement) {
      el.focus();
    }
  });
}

// 该挂出来的那一段：可视区前后各多铺几条，再补上焦点所在的一条——
// 它一旦离开 DOM，方向键就接不下去了
function windowOf(column: Column, focusedPath: string[] | null): Row[] {
  const max = Math.max(0, column.items.length * ROW - VIEW);
  const top = Math.min(scrolled.value[column.level] ?? 0, max);
  const start = Math.max(0, Math.floor(top / ROW) - OVERSCAN);
  const end = Math.min(
    column.items.length,
    Math.ceil((top + VIEW) / ROW) + OVERSCAN,
  );
  const rows: Row[] = column.items
    .slice(start, end)
    .map((item, i) => ({ ...item, index: start + i }));

  const anchor = focusedPath?.[column.level];
  const hit =
    anchor == null
      ? undefined
      : column.items.find((item) => item.value === anchor);
  if (hit) {
    const at = column.items.indexOf(hit);
    if (at < start || at >= end) {
      rows.push({ ...hit, index: at });
    }
  }
  return rows;
}

const shelf = ref<string[][]>([]);
</script>

<template>
  <div ref="shell">
    <XhCascaderRoot
      v-slot="{ columns, focusedPath }"
      v-model:value="shelf"
      :collection="warehouses"
      placeholder="请选择货位"
      @open-change="onOpenChange"
    >
      <XhCascaderLabel>货位（每仓 1000 条）</XhCascaderLabel>
      <XhCascaderTrigger>
        <XhCascaderValueText />
        <XhCascaderIndicator>▾</XhCascaderIndicator>
      </XhCascaderTrigger>
      <XhCascaderPositioner>
        <XhCascaderContent @keydown="syncFocus">
          <XhCascaderColumn
            v-for="col in columns"
            :key="col.level"
            :level="col.level"
            style="
              --xh-cascader-column-max-h: 256px;
              position: relative;
              padding-block: 0;
            "
            @scroll="onScroll(col.level, $event)"
          >
            <!-- 撑高块把滚动条撑到全长，条目按各自的索引落位 -->
            <div
              aria-hidden="true"
              :style="{ flex: 'none', blockSize: `${col.items.length * ROW}px` }"
            />
            <XhCascaderItem
              v-for="row in windowOf(col, focusedPath)"
              :key="row.value"
              :value="row.value"
              :style="{
                position: 'absolute',
                insetInlineStart: 'var(--xh-space-1)',
                insetInlineEnd: 'var(--xh-space-1)',
                insetBlockStart: `${row.index * ROW}px`,
                blockSize: `${ROW}px`,
              }"
            >
              <XhCascaderItemText>{{ row.label }}</XhCascaderItemText>
              <XhCascaderItemIndicator>✓</XhCascaderItemIndicator>
            </XhCascaderItem>
          </XhCascaderColumn>
        </XhCascaderContent>
      </XhCascaderPositioner>
    </XhCascaderRoot>
    <p>当前货位：{{ shelf.length ? shelf[0].join(" / ") : "（未选）" }}</p>
  </div>
</template>

级联勾选与回显策略

multiple 加 cascade 内建父子传导：点分支整枝勾上、子全勾父勾、部分勾中半选；对外值按 checked-strategy 收敛（默认只收叶），半选标记从插槽作用域的 isIndeterminate 取

投放品类

选中值（默认只收叶）：iOS

<script setup lang="ts">
import { computed, ref } from "vue";
import {
  XhCascaderClearTrigger,
  XhCascaderColumn,
  XhCascaderContent,
  XhCascaderIndicator,
  XhCascaderItem,
  XhCascaderItemIndicator,
  XhCascaderItemText,
  XhCascaderLabel,
  XhCascaderPositioner,
  XhCascaderRoot,
  XhCascaderTrigger,
  XhCascaderValueText,
} from "@xihan-ui/vue";

interface CatalogNode {
  value: string;
  label: string;
  children?: CatalogNode[];
}

const catalog: CatalogNode[] = [
  {
    value: "digital",
    label: "数码",
    children: [
      {
        value: "phone",
        label: "手机",
        children: [
          { value: "ios", label: "iOS" },
          { value: "android", label: "Android" },
        ],
      },
      {
        value: "laptop",
        label: "笔记本",
        children: [
          { value: "light", label: "轻薄本" },
          { value: "game", label: "游戏本" },
        ],
      },
    ],
  },
  {
    value: "home",
    label: "家居",
    children: [
      {
        value: "kitchen",
        label: "厨房",
        children: [
          { value: "pot", label: "锅具" },
          { value: "knife", label: "刀具" },
        ],
      },
    ],
  },
];

const value = ref<string[][]>([["digital", "phone", "ios"]]);

function labelOf(path: readonly string[]): string {
  let nodes: CatalogNode[] | undefined = catalog;
  let hit: CatalogNode | undefined;
  for (const segment of path) {
    hit = nodes?.find((node) => node.value === segment);
    nodes = hit?.children;
  }
  return hit?.label ?? path[path.length - 1]!;
}

const text = computed(() => value.value.map(labelOf).join("、"));
</script>

<template>
  <XhCascaderRoot
    v-slot="{ levels, isIndeterminate }"
    v-model:value="value"
    :collection="catalog"
    multiple
    cascade
  >
    <XhCascaderLabel>投放品类</XhCascaderLabel>
    <XhCascaderTrigger>
      <XhCascaderValueText>
        {{ text || "请选择品类" }}
      </XhCascaderValueText>
      <XhCascaderIndicator>▾</XhCascaderIndicator>
    </XhCascaderTrigger>
    <XhCascaderClearTrigger>✕</XhCascaderClearTrigger>
    <XhCascaderPositioner>
      <XhCascaderContent>
        <XhCascaderColumn v-for="lv in levels" :key="lv.level" :level="lv.level">
          <XhCascaderItem
            v-for="node in lv.items"
            :key="node.value"
            :value="node.value"
          >
            <XhCascaderItemText>{{ node.label }}</XhCascaderItemText>
            <span
              v-if="isIndeterminate(node.value)"
              aria-hidden="true"
              style="flex: none; color: var(--xh-fg-subtle)"
            >
              －
            </span>
            <XhCascaderItemIndicator>✓</XhCascaderItemIndicator>
          </XhCascaderItem>
        </XhCascaderColumn>
      </XhCascaderContent>
    </XhCascaderPositioner>
  </XhCascaderRoot>
  <p>选中值（默认只收叶）：{{ text || "（未选）" }}</p>
</template>

浮层底栏

content 的子节点全由作者写：列装进一层横排容器，底栏与它并列，就横跨了全部列

采购清单

已选：fruit/apple

<script setup lang="ts">
import { ref } from "vue";
import {
  XhButton,
  XhCascaderColumn,
  XhCascaderContent,
  XhCascaderIndicator,
  XhCascaderItem,
  XhCascaderItemIndicator,
  XhCascaderItemText,
  XhCascaderLabel,
  XhCascaderPositioner,
  XhCascaderRoot,
  XhCascaderTrigger,
  XhCascaderValueText,
} from "@xihan-ui/vue";

const catalog = [
  {
    value: "fruit",
    label: "水果",
    children: [
      { value: "apple", label: "苹果" },
      { value: "banana", label: "香蕉" },
      { value: "grape", label: "葡萄" },
    ],
  },
  {
    value: "vegetable",
    label: "蔬菜",
    children: [
      { value: "tomato", label: "番茄" },
      { value: "potato", label: "土豆" },
    ],
  },
];

const picked = ref<string[][]>([["fruit", "apple"]]);
</script>

<template>
  <XhCascaderRoot
    v-slot="{ levels, value, clear, setOpen }"
    v-model:value="picked"
    :collection="catalog"
    multiple
    placeholder="可以多挑几条"
  >
    <XhCascaderLabel>采购清单</XhCascaderLabel>
    <XhCascaderTrigger>
      <XhCascaderValueText />
      <XhCascaderIndicator>▾</XhCascaderIndicator>
    </XhCascaderTrigger>
    <XhCascaderPositioner>
      <!-- 浮层壳改成竖排：上半是并排的列，下半是横跨全宽的底栏 -->
      <XhCascaderContent style="flex-direction: column">
        <div style="display: flex; flex-direction: row; align-items: stretch">
          <XhCascaderColumn
            v-for="lv in levels"
            :key="lv.level"
            :level="lv.level"
          >
            <XhCascaderItem
              v-for="node in lv.items"
              :key="node.value"
              :value="node.value"
            >
              <XhCascaderItemText>{{ node.label }}</XhCascaderItemText>
              <XhCascaderItemIndicator>✓</XhCascaderItemIndicator>
            </XhCascaderItem>
          </XhCascaderColumn>
        </div>
        <div
          style="
            display: flex;
            gap: 8px;
            align-items: center;
            justify-content: space-between;
            padding: 8px;
            border-block-start: 1px solid var(--xh-border-subtle);
          "
        >
          <span style="color: var(--xh-fg-subtle); font-size: 12px">
            已选 {{ value.length }} 条
          </span>
          <span style="display: flex; gap: 8px">
            <XhButton size="sm" variant="ghost" @click="clear()">清空</XhButton>
            <XhButton size="sm" @click="setOpen(false)">完成</XhButton>
          </span>
        </div>
      </XhCascaderContent>
    </XhCascaderPositioner>
  </XhCascaderRoot>
  <p>已选：{{ picked.map((p) => p.join("/")).join("、") || "（无）" }}</p>
</template>

命令式聚焦与展开

trigger 部件渲染的就是原生按钮，模板 ref 拿到它即可 focus / blur；开合走根插槽的 setOpen

收货地区

<script setup lang="ts">
import { ref } from "vue";
import {
  XhButton,
  XhCascaderColumn,
  XhCascaderContent,
  XhCascaderIndicator,
  XhCascaderItem,
  XhCascaderItemIndicator,
  XhCascaderItemText,
  XhCascaderLabel,
  XhCascaderPositioner,
  XhCascaderRoot,
  XhCascaderTrigger,
  XhCascaderValueText,
} from "@xihan-ui/vue";

const regions = [
  {
    value: "zhejiang",
    label: "浙江",
    children: [
      { value: "hangzhou", label: "杭州" },
      { value: "ningbo", label: "宁波" },
    ],
  },
  {
    value: "jiangsu",
    label: "江苏",
    children: [{ value: "nanjing", label: "南京" }],
  },
];

const trigger = ref<InstanceType<typeof XhCascaderTrigger> | null>(null);
const area = ref<string[][]>([]);

// 组件实例的 $el 就是那个按钮
const triggerEl = () => trigger.value?.$el as HTMLButtonElement | undefined;
</script>

<template>
  <XhCascaderRoot
    v-slot="{ levels, open, setOpen }"
    v-model:value="area"
    :collection="regions"
    placeholder="请选择地区"
  >
    <XhCascaderLabel>收货地区</XhCascaderLabel>
    <XhCascaderTrigger ref="trigger">
      <XhCascaderValueText />
      <XhCascaderIndicator>▾</XhCascaderIndicator>
    </XhCascaderTrigger>
    <XhCascaderPositioner>
      <XhCascaderContent>
        <XhCascaderColumn v-for="lv in levels" :key="lv.level" :level="lv.level">
          <XhCascaderItem
            v-for="node in lv.items"
            :key="node.value"
            :value="node.value"
          >
            <XhCascaderItemText>{{ node.label }}</XhCascaderItemText>
            <XhCascaderItemIndicator>✓</XhCascaderItemIndicator>
          </XhCascaderItem>
        </XhCascaderColumn>
      </XhCascaderContent>
    </XhCascaderPositioner>
    <div style="display: flex; gap: 8px; margin-block-start: 12px">
      <XhButton size="sm" variant="outline" @click="triggerEl()?.focus()">
        聚焦
      </XhButton>
      <XhButton size="sm" variant="outline" @click="triggerEl()?.blur()">
        失焦
      </XhButton>
      <XhButton size="sm" variant="outline" @click="setOpen(!open)">
        {{ open ? "收起" : "展开" }}
      </XhButton>
    </div>
  </XhCascaderRoot>
</template>

产物

层	值
自定义元素	<xh-cascader>
Vue 组件	XhCascaderClearTrigger XhCascaderColumn XhCascaderContent XhCascaderIndicator XhCascaderItem XhCascaderItemIndicator XhCascaderItemText XhCascaderLabel XhCascaderPositioner XhCascaderRoot XhCascaderTrigger XhCascaderValueText
组合式函数	useCascader
状态机	cascaderMachine
皮肤	@xihan-ui/styles/cascader.css

解剖

部件名即 data-part 属性值，也是皮肤的选择器。加粗的是必备部件，不渲染它组件不工作（Web Components 适配器会在诊断通道上报 wc.missing-part）。

data-scope="cascader"：root · label · trigger · value-text · indicator · clear-trigger · positioner · content · column · item · item-text · item-indicator

Props

属性	类型	必填	说明
collection	CascaderNode[]		树数据，层级元信息与显示文本的唯一事实源。缺省为空树。
value	CascaderValue		选中路径。给定即受控：cell 直读 prop，写只发 onValueChange 不落内部值。 单条路径是简写，内部一律归一成路径集合。
defaultValue	CascaderValue
open	boolean		展开态。给定即受控：内部不再自改，只发 onOpenChange。
defaultOpen	boolean
expandTrigger	CascaderExpandTrigger		子列由什么展开，默认 click。
changeOnSelect	boolean		中间层（分支）也能落值。关掉时点分支只展开子列，不改选中值。
multiple	boolean		多选：选中是路径集合，选中后浮层不收起、焦点留在列里以便接着挑。
cascade	boolean		多选下父子级联勾选：点分支整枝传导、子全勾父勾、部分勾中半选， 禁用子树整棵冻结。默认 false（按路径原样翻转）；单选下无效。
checkedStrategy	CascadeStrategy		级联下对外值的收敛策略，默认 child（只收叶）；parent = 最高整枝，all = 全部勾中节点。
disabled	boolean		整个控件禁用：trigger 用原生 disabled，浮层展不开。
readOnly	boolean		只读：浮层照常展开与浏览，但选中值改不动、也清不掉。
invalid	boolean		校验失败：trigger 报 aria-invalid，各角色节点带 data-invalid。
variant	ControlVariant		形态：outline / subtle / ghost，决定触发框的描边与底色怎么用。
tone	Tone		语气：brand / neutral / success / warning / danger / info，决定聚焦与选中用哪族颜色。
size	Size		尺寸：sm / md / lg，决定触发框与条目的几何档位。
placeholder	string		无选中时 value-text 显示的占位文字。
separator	string		路径回显的连接符，默认 ' / '。
placement	Placement
offset	number
loop	boolean		列内上下键走到首尾是否回绕，默认 true。
dir	Direction		文字方向，默认 ltr；只对调左右方向键的「进子列/回上一列」语义。
onValueChange	(details: CascaderValueChangeDetails) => void		value 变化意图回调；受控时是唯一出口，非受控随内部写入一并通知。
onOpenChange	(details: CascaderOpenChangeDetails) => void		open 变化意图回调；受控时是唯一出口，非受控时随内部转移一并通知。

状态机

状态：open · closed

事件：OPEN · TOGGLE · CLOSE · CONTROLLED.OPEN · CONTROLLED.CLOSE · ITEM.FOCUS · ITEM.EXPAND · ITEM.LOST · ITEM.SELECT · VALUE.SET · VALUE.CLEAR · PATH.SET

判据：isOpenControlled · isMultiple · staysOpenOnSelect

connect API

useCascader 产出的对象。getXxxProps() 铺到对应部件的宿主元素上，其余是可读状态与操作入口。

成员	类型	说明
open	boolean
collection	readonly CascaderNode[]	作者给的原始树数据。
columns	readonly CascaderColumn[]	当下并排开着的列（含每列的条目）：列数 = 展开路径走得通的段数 + 1。
levels	readonly CascaderLevel[]	按深度摊开的静态列，与展开路径无关；不该露面的条目由连接层加 hidden 收起。
value	string[][]	选中路径集合；单选下长度 ≤ 1，形状不随模式变。
valuePath	string[] | null	单选便利读法：选中的那一条路径，无选中时为 null。
valueText	string | null	选中路径的显示文字（整条路径用分隔符连起来；多选各条之间用逗号）；无选中时为 null。
displayText	string	value-text 实际显示的文字：有选中取路径文本，否则取 placeholder。
activePath	string[]	展开路径：并排开着哪几列由它决定。
focusedPath	string[] | null	焦点锚点；收起、或它已不在任何可见列里时为 null。
multiple	boolean
disabled	boolean
readOnly	boolean
invalid	boolean
canClear	boolean	清空按钮此刻可不可按。
isSelected	(value: string) => boolean	该条目是否是某条选中路径的末项。
isIndeterminate	(value: string) => boolean	级联模式下该分支是否半选（有效叶后代有勾有不勾）；非级联恒 false。
isActive	(value: string) => boolean	该条目是否落在展开路径上（它的子列开着，或它自己就是最后一站）。
isVisible	(value: string) => boolean	该条目此刻是否落在某个可见列里。
setOpen	(next: boolean) => void
setValue	(next: string[][]) => void
setActivePath	(next: string[]) => void
select	(path: string[]) => void	选中一条路径，与点条目同一语义（分支是否落值仍看 changeOnSelect）。
clear	() => void
getRootProps	() => T['element']
getLabelProps	() => T['element']
getTriggerProps	() => T['button']
getValueTextProps	() => T['element']
getIndicatorProps	() => T['element']
getClearTriggerProps	() => T['button']
getPositionerProps	() => T['element']
getContentProps	() => T['element']
getColumnProps	(props: CascaderColumnProps) => T['element']
getItemProps	(props: CascaderItemProps) => T['element']
getItemTextProps	(props: CascaderItemProps) => T['element']
getItemIndicatorProps	(props: CascaderItemProps) => T['element']

键盘

规格出处：W3C APG

按键	生效条件	行为
Enter / Space	closed, focus in trigger	展开浮层并把焦点落到选中路径的末项（无选中或它已禁用则落该列首个可用条目）
ArrowDown	closed, focus in trigger	展开浮层并把焦点落到选中条目在它那一列里的下一个可用条目
ArrowUp	closed, focus in trigger	展开浮层并把焦点落到选中条目在它那一列里的上一个可用条目
ArrowDown	open, focus in content	焦点移到当前列的下一个条目（禁用条目跳过；loop 默认开，末项回绕到首项）；别的列不动
ArrowUp	open, focus in content	焦点移到当前列的上一个条目（禁用条目跳过；loop 默认开，首项回绕到末项）
Home	open, focus in content	焦点移到当前列的首个可用条目
End	open, focus in content	焦点移到当前列的末个可用条目
ArrowRight	open, 焦点条目有子节点（dir=rtl 时改由 ArrowLeft 承担）	焦点移进右边那一列的首个可用条目；叶子上什么都不做且不吞键
ArrowLeft	open, 焦点不在根列（dir=rtl 时改由 ArrowRight 承担）	焦点退回上一列的父条目，当前这一列随之收起；根列上什么都不做且不吞键
Enter / Space	open, 焦点条目未禁用	叶子：落值并收起浮层、焦点归还 trigger。分支：展开它的子列且浮层不收起，changeOnSelect 打开时同时落值
Escape	open	收起浮层并把焦点归还 trigger，选中值不变
Tab / Shift+Tab	open	收起浮层，焦点不归还 trigger，按 Tab 序列自然离开