前端UI组件【免费下载链接】rsuite A suite of React components .项目地址https://gitcode.com/gh_mirrors/rs/rsuite点击查看免费下载级联选择器Cascader是 rsuite 中用于「对有层级关系的数据进行单项选择」的核心组件它把树形结构数据以多列联动的形式呈现选中上一级节点后下一列随之刷新。本文以 Cascader 官方文档 为骨架完整覆盖其导入方式、10 个核心示例外观、尺寸、异步加载、自定义渲染、受控等、响应式行为、可访问性规范与全部 Props并结合仓库源码src/Cascader、src/CascadeTree剖析其底层实现帮助你从「会用」进阶到「用得明白」。Cascader 是什么Cascader组件将「层级结构」的数据源渲染为一个分列的级联列表用户沿路径逐级选择最终得到一个叶子节点值。它适合省市县联动、组织架构选择、商品类目选择等典型场景。数据源是带children的树形数组结构与 Option 类型 对应组件出口位于 src/Cascader/index.tsx对外导出Cascader及CascaderProps类型其核心视图多列联动树、搜索视图由src/Cascader/Cascader.tsx组合 TreeView 与 SearchView 实现这套级联树逻辑与MultiCascader共享。快速上手导入与基础用法从rsuite包中直接导入组件import { Cascader } from rsuite;官方基础示例来源basic.md使用mockTreeData生成三层树数据并对比了默认可搜索与searchable{false}两种形态import { Cascader, VStack } from rsuite; import { mockTreeData } from ./mock; const data mockTreeData({ limits: [3, 3, 4], labels: (layer, value, faker) { const methodName [jobArea, jobType, firstName]; return faker.person[methodName[layer]](); } }); const App () { return ( VStack Cascader data{data} w{224} / Cascader data{data} searchable{false} w{224} placeholderSelect without search / /VStack ); }; ReactDOM.render(App /, document.getElementById(root));要点说明data是 Cascader 唯一必填标记*的属性mockTreeData是文档站用于演示的造数工具真实定义见 docs/utils/mock.tslimits: [3, 3, 4]表示三层分别有 3、3、4 个子节点默认开启搜索searchable默认true搜索在底层由 SearchView 提供它通过getPathTowardsItem回溯父节点路径从而把命中的叶子节点连同完整路径一起展示出来。外观Appearance与尺寸Size外观default 与 subtleappearance控制触发器的视觉样式取值为default | subtle默认default。示例appearance.mdconst App () ( Cascader data{data} appearancedefault placeholderDefault w{224} / hr / Cascader data{data} appearancesubtle placeholderSubtle w{224} / / );subtle外观弱化了边框与背景适合嵌入工具栏、导航等需要低视觉噪音的场景。尺寸lg / md / sm / xssize默认md支持四种规格size.mdVStack Cascader sizelg placeholderLarge data{data} w{224} / Cascader sizemd placeholderMedium data{data} w{224} / Cascader sizesm placeholderSmall data{data} w{224} / Cascader sizexs placeholderXsmall data{data} w{224} / /VStack撑满容器Blockblock为布尔属性设置后触发器将占据父容器的整行宽度block.mdCascader block data{data} /在表单布局、移动端适配等场景中block能让选择器与输入框视觉对齐。弹出位置与防止溢出Placement Prevent Overflow弹出层的位置由placement控制可选类型为type Placement bottomStart | topStart | autoVerticalStart;默认值为bottomStart。preventOverflow用于防止浮动元素溢出容器container可指定渲染容器。官方示例placement.md通过PlacementContainer在多个位置间切换演示其中关键连线是开启preventOverflow时把container传给组件让弹出层被约束在指定容器内Cascader w{224} preventOverflow{preventOverflow} data{data} placement{placement} container{preventOverflow ? container : undefined} placeholder{Will pop from ${placement}} /从源码看placement与preventOverflow经由PickerToggleTrigger透传给内部定位逻辑见 src/Cascader/Cascader.tsx 中PickerToggleTrigger的triggerPropKeys装配这一点与 SelectPicker、TreePicker 等所有 picker 类组件一致。父节点可选Parent Selectable默认情况下 Cascader 只允许选择叶子节点。设置parentSelectable后中间层级的父节点也可以被选中parent-selectable.mdCascader data{data} parentSelectable w{224} /该属性在CascaderProps中单独声明见 src/Cascader/Cascader.tsx选择行为由CascadeTree/hooks中的useSelect统一驱动。自定义选项渲染Custom RenderCascader 提供了四个渲染扩展点renderTreeNode自定义树节点、renderColumn自定义整列可拿到{ items, parentItem, layer }、renderValue自定义选中值显示、renderSearchItem自定义搜索结果。官方示例custom.md给每一列加上表头、节点前加图标并让触发器显示完整路径const headers [Job Area, Job Type, Name]; const Column ({ header, children }) ( div div style{{ background: #154c94, padding: 4px 10px, color: #fff, textAlign: center }} {header} /div {children} /div ); const App () ( Cascader data{data} w{224} columnWidth{160} renderTreeNode{(label, node) ( AdminIcon / {label} / )} renderColumn{(childNodes, { layer }) { return Column header{headers[layer]} {childNodes}/Column; }} renderValue{(value, activePaths, activeItemLabel) { return activePaths.map(item item.label).join( ); }} / );实现层面renderColumn与renderTreeNode都是 TreeView 的 props见TreeViewProps定义renderValue则由 Cascader 在usePaths提供的selectedPaths基础上调用——这正是「选中值显示为完整路径」能力的来源。禁用与只读Disabled Read Only示例disabled.md覆盖了四种状态disabled整个组件禁用disabledItemValues按值禁用指定选项可传入多个值组成的数组如[2, 1-1]readOnly只读不可修改但保持交互外观plaintext纯文本展示表单提交场景常用。Field labelDisabled disabled defaultValue1-1 data{data} / Field labelDisabled option data{data} defaultValue1-1 disabledItemValues{[2, 1-1]} / Field labelReadOnly readOnly defaultValue1-1 data{data} / Field labelPlaintext plaintext defaultValue1-1 data{data} /readOnly、plaintext等表单语义能力继承自FormControlPickerProps见 src/Cascader/Cascader.tsx与 rsuite 的 Form 表单体系FormControl无缝衔接disabledItemValues在 TreeView 中被用于过滤可点击节点。异步加载子级Async Data文档明确说明异步加载机制通过getChildren属性且树节点上children字段长度为0时触发按需加载子级。官方示例async.mdconst [getNodes, fetchNodes] mockAsyncData(); const initialData getNodes(5); const App () { const [value, setValue] React.useState(); return ( Cascader value{value} onChange{setValue} placeholderSelect w{224} data{initialData} columnWidth{200} getChildren{node { return fetchNodes(node.id); }} renderTreeNode{(label, item) ( {item.children ? FolderFillIcon / : PageIcon /} {label} / )} / ); };这里的renderTreeNode利用item.children是否存在来区分「文件夹/页面」图标配合getChildren形成典型的懒加载目录树体验。源码佐证getChildren的签名是(item: Option) PromiseOption[]见文档 Props 表Option 类型 中定义了loading?: boolean字段注释明确指出它「用于有级联关系并支持子级懒加载的组件如 Cascader、MultiCascader」——加载中的节点会显示 Spinner 指示器TreeView 接收loadingItemsSet用于标记哪些节点处于加载状态其加载图标使用SpinnerIcon渲染。受控组件ControlledCascader 同时支持受控与非受控模式。valueonChange构成受控用法defaultValue用于非受控初值。官方示例controlled.mdconst App () { const [value, setValue] React.useState(1-2-2); return Cascader value{value} onChange{setValue} data{data} w{224} /; };onChange签名为(value: string, event) void仅返回选中值本身若需要完整路径可结合onSelect(item, selectedPaths, event) void或renderValue获取selectedPaths。从源码看受控状态通过useControlledhook 管理见 src/Cascader/Cascader.tsx 的 hooks 装配选中路径则由CascadeTree/hooks的usePaths基于parentMap回溯计算。响应式超小屏幕自动变为全宽 Drawer文档明确在超小屏幕上extra-small screens弹出层默认显示为全宽 Drawer当选择器已经位于 Modal 或 Drawer 内部时应设置responsive{false}保持定位浮层避免嵌套遮罩冲突。Cascader data{data} block /responsive默认值为true。演示页位于 docs/pages/components/cascader/examples/responsive.tsx页面组装见 examples/index.tsx。这一行为是 rsuite 移动端适配的组成部分窄屏下全宽 Drawer 比小尺寸定位浮层更易点选而responsive{false}则保证了 Modal/Drawer 内的「弹出层套弹出层」体验。可访问性AccessibilityCascader 内置了完整的 ARIA 与键盘交互支持文档将其作为一等公民列出ARIA 属性rolecombobox声明组合框角色aria-haspopuptree指示 combobox 有一个弹出的树形列表框aria-expanded指示树形列表框是否展开aria-controls指示树形列表框元素的 IDaria-activedescendant指示当前焦点选项的 ID当设置了label时aria-labelledby会被同时添加到 combobox 元素与 tree 元素上值为label的id属性值。键盘交互按键行为↓焦点移动到下一个树节点↑焦点移动到上一个树节点→展开当前折叠状态的树节点←收起当前展开状态的树节点Enter选中焦点所在的树节点Esc关闭树形列表框实现上这些能力来自/internals/Picker的useCombobox上下文与useToggleKeyDownEvent键盘事件绑定见 src/Cascader/Cascader.tsx 的 import 与 TreeView 中的useCombobox()调用焦点节点通过useFocusItemValue跟踪并映射为aria-activedescendant。Props 完整说明Cascader下表完整继承自官方文档en-USindex.mdzh-CNindex.md属性类型默认值说明appearancedefault \| subtle(default)设置外观blockboolean占满父容器整行caretAsElementType自定义右侧箭头图标的组件childrenKeystring(children)设置选项子节点在data中的keyclassPrefixstring(picker)组件 CSS 类的前缀cleanableboolean(true)选中值是否可清除columnHeightnumber设置选项列的高度columnWidthnumber设置选项列的宽度TreeView 默认140containerHTMLElement \| (() HTMLElement)设置渲染的容器data *[Option][]组件数据必填defaultValuestring默认选中值非受控disabledboolean禁用整个组件disabledItemValuesstring[]禁用指定值的选项getChildren(item: Option) PromiseOption[]异步加载树节点的子级heightnumber(320)设置 Dropdown 的高度labelKeystring(label)设置选项显示内容在data中的keyloadingboolean(false)是否显示加载中状态指示器localePickerLocaleType本地化文案设置onChange(value: string, event) voidvalue改变时的回调onClean(event) void清除值后的回调onClose / onOpen() void关闭 / 打开回调onEnter / onEntering / onEntered() void弹出层过渡动画进入前 / 进入中 / 进入后onExit / onExiting / onExited() void弹出层过渡动画退出前 / 退出中 / 退出后onSearch(search: string, event) void搜索回调onSelect(item: Option, selectedPaths: Option[], event) void选项被点击选择后的回调openboolean是否打开受控弹出parentSelectableboolean设置父节点为可选placeholderReactNode(Select)占位符placementPlacement(bottomStart)弹出位置popupClassNamestring弹出层自定义 CSS 类名popupStyleCSSProperties弹出层自定义样式preventOverflowboolean防止浮动元素溢出renderColumn(childNodes, column: { items, parentItem, layer }) ReactNode自定义渲染选项列renderExtraFooter() ReactNode自定义弹出层页脚renderSearchItem(node, items: Option[]) ReactNode自定义搜索结果项renderTreeNode(node, item: Option) ReactNode自定义树节点renderValue(value, selectedPaths: Option[], selected: ReactNode) ReactNode自定义选中值显示responsiveboolean(true)超小屏幕是否以全宽 Drawer 显示弹出层searchableboolean(true)是否可搜索sizelg \| md \| sm \| xs(md)组件尺寸toggleAsElementType(a)自定义触发元素类型valuestring当前值受控valueKeystring(value)设置选项值在data中的key配套的两种共享类型定义如下。Option数据结构interface OptionV { /** 选项的值对应数据中的 valueKey。 */ value: V; /** 选项显示内容对应数据中的 labelKey。 */ label: ReactNode; /** 子选项数据对应数据中的 childrenKey为树形组件TreePicker、Cascader 等所拥有。 */ children?: OptionV[]; /** 分组功能组件CheckPicker、InputPicker 等的属性。 */ groupBy?: string; /** 当前节点的子级是否加载中用于有级联关系且懒加载子级的组件Cascader、MultiCascader。 */ loading?: boolean; }完整定义见 docs/pages/_common/types/item-data-type.md。Placement类型type Placement bottomStart | topStart | autoVerticalStart;完整定义见 docs/pages/_common/types/placement-start.md。源码结构Cascader 的实现骨架如果要在项目里深度定制 Cascader可以顺着以下源码路径继续探索src/Cascader/Cascader.tsx组件主文件。组合PickerToggle、PickerPopup、PickerToggleTrigger与CascadeTree的TreeView/SearchView状态管理使用useControlled、usePaths、useSelect、useSearch、useActive、useFocusItemValue等 hookssrc/CascadeTree/TreeView.tsx多列联动视图负责按cascadePaths逐列渲染默认columnWidth 140、columnHeight 200src/CascadeTree/SearchView.tsx搜索视图通过getPathTowardsItemparentMap回溯命中项的完整路径renderSearchItem在此生效src/Cascader/index.tsx对外导出入口同时导出CascaderProps类型src/CascadeTree/hooksusePaths路径计算、useSelect选择逻辑、useSearch搜索状态等核心 hooks 所在地。这套「Picker 触发器 级联树视图」的组合也是MultiCascader复用同一CascadeTree的原因理解 Cascader 后即可举一反三掌握 rsuite 全部级联类组件的用法。小结Cascader 是 rsuite 中数据驱动、开箱即用的层级选择组件data一份树形数据即可渲染联动多列parentSelectable控制父级可选getChildren实现按需懒加载renderColumn/renderTreeNode/renderValue提供从列头到选中值全链路的自定义能力responsive与内置 ARIA/键盘交互则覆盖了移动端与无障碍两大工程要求。无论你正在搭建行政区划选择器、组织架构树还是商品类目筛选本文的示例与 Props 明细都可以直接作为落地参考。赞分享前端UI组件【免费下载链接】rsuite A suite of React components .项目地址https://gitcode.com/gh_mirrors/rs/rsuite点击查看免费下载相关推荐rsuite Cascader 级联选择器异步数据加载getChildren 懒加载实战指南rsuite Cascader 级联选择器异步数据加载getChildren 懒加载实战指南 本篇技术指南聚焦 rsuite 的 Cascader 级联选择前端UI组件ElementVue 2.0Cascader 级联选择器完整实战指南从基础用法到动态加载与源码级原理ElementVue 2.0Cascader 级联选择器完整实战指南从基础用法到动态加载与源码级原理 Cascader 级联选择器是 Element UI前端UI组件设计系统Naive UI Cascader 级联选择器完全指南从基础用法到源码级原理Naive UI Cascader 级联选择器完全指南从基础用法到源码级原理 Cascader级联选择器是 Naive UI 中用于展示与选择 树形结构数前端UI组件创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考