ICEN UI

级联选择

在省市区、目录或分类中逐级选择一条路径。支持跨级搜索和完整键盘操作。

逐级选择，或搜索「深圳」直接找到完整路径。方向键移动，Enter 选择。

html
<div id="demo-cascader" style="width:100%;max-width:340px"></div><p class="demo-label" id="cascader-log" style="margin-top:8px">逐级选择，或搜索「深圳」直接找到完整路径。方向键移动，Enter 选择。</p>
行为与接口说明

createCascader 装配级联选择：路径型选择（省/市/区、类目/子类目），值 = 路径值数组。多列面板逐级展开（当前路径高亮、有子级的项带 chevron、列宽不足横向滚动），点中间级只展开、叶子才定值（changeOnSelect: true 时任意级即定值）；searchable 面板内搜索跨级过滤，命中显示完整路径（面包屑式 muted 分隔符），无命中 empty 态（emptyLabel）。键盘 → 进子级 / ← 回上级（RTL 镜像）/ ↑↓ 移动 / Enter 定值 / Esc 关闭；trigger role=combobox，列 role=listbox、项 role=option。面板 portal 到 body，尺寸走全库 PanelSizing 契约（根挂 data-icen-panel-*）。事件 icen:cascader-change { value, path }（path = 各级 label，与 onChange 双通道）；clearable 清除、disabled 置灰、同 el 重复 create 先销毁旧实例。

安装

bun add @icen.ai/ui

一行引入该组件（CSS 与 behavior 自动带上，无需关心内部 CSS 文件名）：

js
import '@icen.ai/ui/kit/cascader';

也可以用脚手架直接打印引入行：

bash
bunx --bun @icen.ai/ui add cascader

Astro 项目注意：kit 入口里的 CSS import 在页面 <script> 里会被 Astro 的 client bundle 摇掉——请改在布局 frontmatter 里引 CSS（import '@icen.ai/ui/components/cascader.css';），JS 行为仍可走 kit。Vite SPA / webpack 项目无此问题。

用法

js
import { createCascader } from '@icen.ai/ui/kit/cascader';const handle = createCascader(el, {  options: [                                  // CascaderOption 树    { value: 'zj', label: '浙江', children: [      { value: 'hz', label: '杭州' },      { value: 'nb', label: '宁波', disabled: true },    ] },  ],  value: ['zj', 'hz'],                        // 路径值数组（初值回填，无效路径忽略）  searchable: true,                           // 跨级过滤，命中显示完整路径  changeOnSelect: false,                      // true = 点中间级即定值；false = 必须选到叶子  clearable: true,  onChange: (value, path) => {},              // 与 icen:cascader-change { value, path } 双通道});handle.getValue();                            // ['zj', 'hz']handle.getPath();                             // ['浙江', '杭州']（各级 label）handle.setValue(['zj', 'hz']);                // 程序化回填（静默）handle.clear(); handle.open(); handle.close(); handle.destroy();