前端UI组件【免费下载链接】rsuite A suite of React components .项目地址https://gitcode.com/gh_mirrors/rs/rsuite点击查看免费下载本篇技术指南聚焦 React 组件库 rsuite 中的Cascader级联选择器组件围绕其对有层级关系结构的数据进行单项选择这一核心能力展开从组件获取、基础用法到外观、尺寸、异步加载、受控与非受控、响应式降级再到完整的 ARIA 属性与键盘交互可访问性设计最后逐项解读全部 Props 配置。读者读完本文能够基于源码级实现细节独立完成级联选择器的接入、定制与无障碍优化。组件概述与获取Cascader用于在具有层级关系的数据结构中完成单项选择典型的业务场景包括地区省/市/区、组织架构、商品分类、职位类别等多级联动选择。它的交互形态是一个可点击的输入框combobox点击后弹出一个多列联动的树形列表框每一列展示当前层级的子节点选择后进入下一层级最终得到一条完整的选中路径。组件的引入方式与 rsuite 其他组件一致支持从主包整体引入import { Cascader } from rsuite;在 rsuite 的文档站点中组件演示均通过!--{include:import-guide}--自动注入导入引导代码实际项目中可直接使用上述 import 语句。Cascader的源码实现位于 src/Cascader核心文件为 Cascader.tsx样式定义在 src/Cascader/styles/index.scss其 popup 部分复用了combobox样式 mixin。基础用法从数据定义到默认交互准备层级数据Cascader的数据通过data属性传入是一个Option[]数组。每个选项的字段名通过labelKey默认label、valueKey默认value、childrenKey默认children来约定因此可以直接使用任意符合约定的树形结构例如const data [ { label: 华南, value: south, children: [ { label: 广东, value: guangdong, children: [{ label: 广州, value: guangzhou }, { label: 深圳, value: shenzhen }] } ] } ];文档演示中使用mockTreeData工具生成三层树形模拟数据limits: [3, 3, 4]表示每层节点数量labels按层级映射为不同字段const data mockTreeData({ limits: [3, 3, 4], labels: (layer, value, faker) { const methodName [jobArea, jobType, firstName]; return faker.person[methodName[layer]](); } });默认用法与搜索最基础的用法只需传入dataconst App () { return ( VStack Cascader data{data} w{224} / Cascader data{data} searchable{false} w{224} placeholderSelect without search / /VStack ); };可以看到searchable默认值为true即在弹出层顶部提供搜索框用于按labelKey过滤节点将其设为false可以关闭搜索。placeholder默认为Select。外观、尺寸与撑满布局外观appearanceappearance属性支持default与subtle两种取值默认default。subtle外观下输入框采用更轻量的底部线条样式适合嵌入表单或工具栏Cascader data{data} appearancedefault placeholderDefault w{224} / Cascader data{data} appearancesubtle placeholderSubtle w{224} /尺寸sizesize支持lg | md | sm | xs四档默认mdCascader 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} /撑满block设置block后组件将撑满整行宽度适合表单布局中需要占满一行或多列栅格的场景Cascader block data{data} /弹出位置与防止溢出placement控制弹出层的打开位置默认bottomStart底部左对齐。完整取值集合由Placement类型定义见下文 Props 说明包括topStart、topEnd、bottomStart、bottomEnd、leftStart、leftEnd、rightStart、rightEnd以及对应的auto*自适应组合。preventOverflow用于防止浮动元素溢出容器边界开启后弹出层会在空间不足时自动翻转方向。container属性则用于指定渲染容器可传HTMLElement或返回元素的函数与preventOverflow搭配可在受限容器内实现安全定位。文档演示中的完整模式为PlacementContainer {({ container, placement, preventOverflow }) ( Cascader w{224} preventOverflow{preventOverflow} data{data} placement{placement} container{preventOverflow ? container : undefined} placeholder{Will pop from ${placement}} / )} /PlacementContainer从源码结构看Cascader的弹出定位复用 rsuite 内部基于 Overlay 的定位机制placement决定浮层锚点方向preventOverflow触发边界检测与位置修正二者共同保证浮层在滚动容器、页面边缘等场景下的可用性。父节点可选parentSelectable默认情况下Cascader只能选择叶子节点展开下一级后父节点不可作为最终选中值。当需要允许用户选择任意层级的节点例如不限下级或选择整个部门时设置parentSelectableCascader data{data} parentSelectable w{224} /开启后点击父节点即可将其作为选中值结束选择流程。自定义渲染选项、列、值与选中展示Cascader提供了多个渲染钩子允许深度定制每一列的内容。文档演示展示了四种能力组合使用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 }) Column header{headers[layer]}{childNodes}/Column} renderValue{(value, activePaths, activeItemLabel) activePaths.map(item item.label).join( )} / );renderTreeNode(node, item)自定义单个选项节点的渲染参数为默认节点 ReactNode 与当前选项对象示例中为每个选项前加图标renderColumn(childNodes, column)自定义整列渲染column包含{ items, parentItem, layer }示例中按layer为每一列添加不同列头renderValue(value, selectedPaths, selected)自定义选中后的输入框展示示例中将完整选中路径用连接显示如华南 广东 广州columnWidth/columnHeight分别设置选项列表的列宽与列高实现多列等宽布局renderExtraFooter()在弹出层底部追加自定义页脚renderSearchItem(node, items)自定义搜索结果项的渲染。禁用与只读组件支持整体禁用、指定选项禁用、只读与纯文本Plaintext四种状态const Field ({ label, children, ...rest }) ( HStack alignstart Text muted w{120}{label}/Text Cascader {...rest} w{180} / /HStack ); const App () ( VStack divider{Divider /} VStack Field labelDisabled disabled defaultValue1-1 data{data} / Field labelDisabled option data{data} defaultValue1-1 disabledItemValues{[2, 1-1]} / /VStack Field labelReadOnly readOnly defaultValue1-1 data{data} / Field labelPlaintext plaintext defaultValue1-1 data{data} / /VStack );disabled整体禁用阻止一切交互disabledItemValues传入一个由选项valueKey值组成的数组用于禁用指定选项示例中禁用了2与1-1两个节点readOnly只读不允许修改值但保留样式plaintext纯文本模式组件退化为展示选中路径的普通文本适合详情页/导出场景。异步加载子级数据当子级数据需要按需从服务端获取时可通过getChildren属性配合树节点上children字段length为0的约定实现异步加载点击带空children数组的节点时组件调用getChildren(item)获取子级并回填。const [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 fetchNodes(node.id)} renderTreeNode{(label, item) ( {item.children ? FolderFillIcon / : PageIcon /} {label} / )} / ); };实现要点getChildren签名(item: Option) PromiseOption[]接收当前节点返回下一级选项的 Promise判定可展开加载的条件是节点children字段的length 0因此初始数据中应给待加载节点设置children: []loading属性默认false用于展示加载中状态指示器异步场景下可配合getChildren传入从 Cascader.tsx 可以看到getChildren与loading在组件状态中的流转示例中用renderTreeNode根据item.children是否存在区分文件夹/页面图标直观标识可展开节点。受控与不受控模式Cascader同时支持受控与非受控两种用法非受控defaultValue只提供初始值后续由组件内部维护状态Cascader data{data} defaultValue1-1 /受控value onChange由外部完全控制当前值适合与表单状态管理联动const App () { const [value, setValue] React.useState(1-2-2); return Cascader value{value} onChange{setValue} data{data} w{224} /; };value与defaultValue的类型均为string即最终选中的叶子或父节点开启parentSelectable时节点的valueKey值。onChange回调签名为(value: string, event) void。响应式超小屏幕降级为全宽 Drawerresponsive属性默认true。开启后在超小屏幕上Cascader的弹出层会自动降级为全宽 Drawer底部抽屉以提供更适合触控的大面积选择区域。需要注意的边界情况当选择器本身已经位于 Modal 或 Drawer 内部时应设置responsive{false}保持定位浮层避免嵌套遮罩导致的层级与交互问题。示例见 examples/responsive.tsxBox p{20} Cascader data{data} block / /Box在 Modal / Drawer 内使用时改为Cascader data{data} block responsive{false} /。可访问性AccessibilityCascader遵循 WAI-ARIA Combobox Tree 的组合模式设计兼顾屏幕阅读器与键盘用户。ARIA 属性组件根元素的role为combobox带有aria-haspopuptree向辅助技术声明 combobox 弹出的是树形列表框aria-expanded指示树形列表框当前是否打开aria-controls指向树形列表框元素的 IDaria-activedescendant指向当前焦点选项的 ID用于在弹出列表中同步朗读焦点项当设置了label时aria-labelledby会被同时添加到 combobox 元素和 tree 元素上其值取label的id保证两个区域都有可访问名称。源码层佐证在 src/Cascader/test/Cascader.spec.tsx 的测试中通过screen.getByRole(combobox)获取组件根元素并断言其渲染行为验证了 combobox 角色在实际 DOM 中的存在。键盘交互按键行为↓移动焦点到下一个树节点↑移动焦点到上一个树节点→展开当前树节点←收起当前树节点Enter选择当前聚焦的树节点Esc关闭树形列表框这组键位与 rsuite 的Tree/CheckTree等树形组件保持一致降低用户在不同组件间的学习成本。Props 全览Cascader属性表属性名称类型默认值描述appearancedefault \| subtle(default)设置外观blockboolean撑满整行caretAsElementType自定义右侧箭头图标组件childrenKeystring(children)设置选项子节点在data中的keyclassPrefixstring(picker)组件 CSS 类的前缀cleanableboolean(true)是否可以清除已选值columnHeightnumber设置选项列表的高度columnWidthnumber设置选项列表的宽度containerHTMLElement \| (() HTMLElement)设置渲染容器data *Option[]组件数据必填defaultValuestring默认值非受控disabledboolean禁用组件disabledItemValuesstring[]禁用指定选项getChildren(item: Option) PromiseOption[]异步加载树节点的子级heightnumber(320)设置 Dropdown 的高度labelKeystring(label)设置选项显示内容在data中的keyloadingboolean(false)是否显示加载中状态指示器localePickerLocaleType本地化设置使组件文本按用户地区显示参见 国际化指南 中pickers分类onChange(value: string, event) voidvalue发生改变时的回调onClean(event) void清除值后的回调onClose() void关闭回调onEnter() void显示前动画过渡回调onEntered() void显示后动画过渡回调onEntering() void显示中动画过渡回调onExit() void退出前动画过渡回调onExited() void退出后动画过渡回调onExiting() void退出中动画过渡回调onOpen() void打开回调onSearch(search: string, event) void搜索回调onSelect(item: Option, selectedPaths: Option[], event) void选项被点击选择后的回调selectedPaths为完整选中路径openboolean是否打开受控parentSelectableboolean设置父节点为可选placeholderReactNode(Select)占位符placementPlacement(bottomStart)弹出位置popupClassNamestring设置弹出层的 CSS 类名popupStyleCSSProperties设置弹出层的样式preventOverflowboolean防止浮动元素溢出renderColumn(childNodes: ReactNode, column: { items, parentItem, layer }) ReactNode自定义渲染选项列表renderExtraFooter() ReactNode自定义弹出层页脚renderSearchItem(node: ReactNode, items: Option[]) ReactNode自定义搜索结果选项renderTreeNode(node: ReactNode, item: Option) ReactNode自定义选项渲染renderValue(value: string, selectedPaths: Option[], selected: ReactNode) ReactNode自定义被选中值的展示responsiveboolean(true)是否在超小屏幕上将弹出层显示为全宽 Drawersearchableboolean(true)是否可以搜索sizelg \| md \| sm \| xs(md)设置组件尺寸toggleAsElementType(a)自定义组件渲染元素类型valuestring当前值受控valueKeystring(value)设置选项值在data中的key配套类型说明Option即数据项类型item-data-type 说明核心结构为interface Option { label: ReactNode; value: string; children?: Option[]; // 可附带任意业务字段 [key: string]: any; }Placement类型placement-start 说明涵盖全部十二种定位方向及其auto自适应变体例如topStart | topEnd | bottomStart | bottomEnd | leftStart | leftEnd | rightStart | rightEnd及对应auto*形式默认取bottomStart。实战小结综合来看接入Cascader的关键决策点如下数据契约data使用label/value/children三层约定通过labelKey/valueKey/childrenKey可适配任意后端字段命名选择语义默认仅叶子可选parentSelectable开启后支持任意层级选中disabledItemValues实现精细化禁用异步场景children: []getChildrenloading组合即可实现按需加载注意getChildren返回 Promise布局与定位size/appearance/block负责外观placementpreventOverflowcontainer负责浮层安全定位Modal/Drawer 内务必设置responsive{false}无障碍组件自带完整的 combobox/tree ARIA 语义与方向键/Enter/Esc 键盘交互无需额外实现但自定义渲染toggleAs、renderTreeNode等时需保持语义标签不被破坏。如需深入源码验证上述行为可继续阅读 src/Cascader/Cascader.tsx、src/Cascader/index.tsx 以及 src/Cascader/test/Cascader.spec.tsx 中的测试用例包括getChildren异步加载与 combobox 角色断言。赞分享前端UI组件【免费下载链接】rsuite A suite of React components .项目地址https://gitcode.com/gh_mirrors/rs/rsuite点击查看免费下载相关推荐rsuite Cascader 级联选择器异步数据加载getChildren 懒加载实战指南rsuite Cascader 级联选择器异步数据加载getChildren 懒加载实战指南 本篇技术指南聚焦 rsuite 的 Cascader 级联选择前端UI组件rsuite CheckTreePicker 树形多项选择器完整指南从级联、异步加载到可访问性rsuite CheckTreePicker 树形多项选择器完整指南从级联、异步加载到可访问性 CheckTreePicker 是 rsuite 中用于在树形前端UI组件Naive UI Cascader 级联选择组件完全指南单选、多选、异步加载与勾选策略实战Naive UI Cascader 级联选择组件完全指南单选、多选、异步加载与勾选策略实战 级联选择Cascader是 Naive UI 中用于从树形层级前端UI组件创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考