表单组件版本 0.1.0

Cascader 级联选择

按列逐级选择具有明确父子关系的分类或区域路径。

使用概览

适合使用

  • 省市区、产品分类等层级路径需要逐层确认时。

不建议使用

  • 用户需要同时浏览整棵树,或节点不存在稳定层级关系时。

真实示例

商品分类级联选择

从办公分类逐级选择办公椅。

正在加载示例…

安装

本地候选警告Registry 地址仅指向当前本地文档站;npm 包也只用于本地候选验证,尚未公开发布。
pnpm dlx shadcn@4.16.0 add http://127.0.0.1:3000/r/cascader.json

基础用法

导入

import { Cascader } from "@richardqiu/quartz/cascader";

JSX

<Cascader aria-label="商品分类" placeholder="选择分类" nodes={[{ id: "office", label: "办公", children: [{ id: "chair", label: "办公椅" }] }]} />

状态与控制摘要

默认
键盘焦点可见
已打开
已选择
已禁用
label · textactive · boolean

API 参考

属性类型默认值说明
valuereadonly string[][]以各层节点标识组成的数组表示当前选择路径。

组合结构

  1. 01Cascader

键盘约定

  • Tab 与方向键在各选项列内保持原生行为,Escape 关闭并恢复触发器焦点。

可访问性契约

  • 具名列表框暴露选中与禁用状态。
  • 公开值是稳定且有序的 ID 路径。