前端UI组件【免费下载链接】rsuite A suite of React components .项目地址https://gitcode.com/gh_mirrors/rs/rsuite点击查看免费下载导读MultiCascader是 rsuite 提供的级联多项选择器用于在具有层级关系的数据中一次选择多个值例如地区 → 公司 → 员工的三级结构。本指南以 受控模式示例 为主线讲解如何通过valueonChange让组件状态完全交由 React 状态管理受控组件并对比defaultValue非受控用法深入useCascadeValue源码剖析级联状态下值的归一化规则。读完本文你将掌握 MultiCascader 受控用法、级联行为差异及源码级原理可直接复用到表单、搜索筛选等场景。一、受控模式的完整示例MultiCascader的受控模式与原生 React 表单控件一致由外部提供value组件在用户勾选时通过onChange回传新值组件自身不再维护选中状态。以下是 controlled.md 中的完整示例import { MultiCascader } 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 () { const [value, setValue] React.useState([1-1, 1-2]); return MultiCascader value{value} onChange{setValue} data{data} minw{224} /; }; ReactDOM.render(App /, document.getElementById(root));关键点valuestring[]当前选中的值数组。受控模式下完全由useState等外部状态驱动onChange(value: string[], event) void用户每次勾选/取消勾选后触发将归一化后的完整值数组回传。示例中直接传入setValue写法最简洁data必填的层级数据minw{224}设置浮层最小宽度保证列式树形布局有足够展示空间。初始值[1-1, 1-2]表示第一层第 1 个节点下的两个二级节点默认处于选中状态数据生成规则见下文。二、数据准备理解mockTreeData的生成规则示例使用mockTreeData生成三层树形数据其实现位于 docs/utils/mock.tsexport function mockTreeData(options: { limits: number[]; labels: string | string[] | ((layer: number, value: string, faker) string); getRowData?: (layer: number, value: string) any[]; }) { ... }limits: [3, 3, 4]定义了树的深度与每层节点数量第一层 3 个节点、第二层每节点 3 个子节点、第三层每节点 4 个子节点值value的生成规则首层为1、2、3子节点以父值-序号拼接如1-1、1-2、1-2-1。所以示例中的[1-1, 1-2]是第二层的两个节点labels可传函数按layer取对应字段名jobArea地区/职位领域→jobType职位类型→firstName人名配合 faker 生成真实感文案最终每条数据形如{ label: string, value: string, children: [...] }与组件的默认键名labelKeylabel、valueKeyvalue、childrenKeychildren完全对应。生产环境中你完全可以用自己的接口数据替换mockTreeData只需保证每条记录包含label、value、children可用labelKey/valueKey/childrenKey自定义键名。三、受控 vs 非受控value与defaultValue的分工与value配套组件还提供了非受控入口defaultValue。对照 default-value.mdconst App () ( div pCascade:/p MultiCascader data{data} defaultValue{[1-1, 1-2, 2]} minw{224} / hr / pNot cascaded:/p MultiCascader data{data} defaultValue{[1-1, 1-2, 2]} cascade{false} minw{224} / /div );两条规则的选用建议场景推荐用法值由 React 状态统一管理如表单联动、提交前预处理valueonChange受控仅需初始选中值、之后交给组件内部维护仅传defaultValue非受控两者的值都会经过级联归一化处理见第四节。从源码看组件通过useControlled(valueProp, defaultValue)统一管理两种模式见 src/MultiCascader/MultiCascader.tsx。四、级联cascade与受控值的关系源码级解析MultiCascader默认cascadetrue即父子节点双向联动选中父节点会选中其全部子孙选中子节点时若兄弟全部选中则自动选中父节点。这直接影响value的形态——级联模式下value会经过归一化只保留最顶层的选中节点。4.1 归一化逻辑transformValue受控值进入组件后会先经过 src/MultiCascadeTree/hooks/useCascadeValue.ts 中的transformValue处理const transformValue useCallback( (value: T[] []) { if (!cascade) { return value; } // ... 逐项 splitValue收集关联节点与待删除节点 // 最后若某节点的父节点也在 value 中则该节点被过滤掉 return nextValue.filter(v { const item flattenData.find(n n[valueKey] v); if (item?.parent nextValue.some(v v item.parent?.[valueKey])) { return false; } return true; }); }, [cascade, flattenData, splitValue, valueKey] );含义当cascadetrue时若同时选中了父节点1与子节点1-1归一化结果只保留1——因为父节点已覆盖子孙。这就是示例中defaultValue{[1-1, 1-2, 2]}而非[1, 1-1, ...]的原因。当cascadefalse时value原样保留允许父与子各自独立勾选。4.2 勾选回调handleCheck用户勾选复选框时useCascadeValue.ts 的handleCheck负责计算下一个值if (cascade) { nextValue splitValue(node, checked, value).value; // 级联联动增删子孙/祖先 } else { nextValue [...value]; if (checked) nextValue.push(nodeValue); else nextValue nextValue.filter(n n ! nodeValue); // 非级联仅增删自身 } setValue(nextValue); onChange?.(nextValue, event); // 回传受控回调 onCheck?.(nextValue, node, checked, event); // 额外的勾选明细回调这里有两处值得注意onChange始终收到归一化后的完整数组受控父组件无需自行处理级联细节onCheck额外提供node当前勾选项与checked状态适合仅在勾选某类节点时做埋点或联动的场景。4.3 受控 动态级联开关cascade.md 展示了一个典型的受控组合用Toggle动态切换级联切换时清空已选值const App () { const [cascade, setCascade] React.useState(true); const [value, setValue] React.useState([]); const handleToggle checked { setCascade(checked); setValue([]); // 级联规则变化后旧值语义不再成立主动清空 }; return ( div Toggle checked{cascade} onChange{handleToggle}Cascade/Toggle hr / MultiCascader w{280} data{data} value{value} cascade{cascade} onChange{setValue} / /div ); };这个模式很有工程价值当切换级联开关时setValue([])保证value与新的cascade语义一致避免非级联值数组被带入级联模式造成冗余项。五、受控行为如何被测试验证仓库测试 src/MultiCascader/test/MultiCascader.spec.tsx 使用testControlledUnControlled用例同时覆盖受控与非受控两种模式testControlledUnControlled(MultiCascader, { componentProps: { data: items, defaultOpen: true }, value: [1], defaultValue: [2], changedValue: [3], simulateEvent: { changeValue: (prevValue: any) { fireEvent.click(screen.getByRole(checkbox, { name: 3 })); return { changedValue: [...prevValue, 3] }; } }, expectedValue: (value: string[]) { const input screen.getByTestId(picker-toggle-input); expect(input).to.have.attribute(value, value.toString()); } });测试通过点击复选框模拟用户操作断言picker-toggle-input的值为最新数组——印证了受控组件在用户操作后必须把新值同步到value绑定这一契约。此外测试还覆盖了testFormControl与Form.Control集成以及aria-haspopuptree等无障碍属性。六、受控相关 Props 速查以下为与受控用法强相关的 Props完整清单见 英文文档 与 中文文档属性类型默认值说明valuestring[]指定已选项的值受控数组元素对应数据中的valueKey字段值defaultValuestring[]指定默认选中的值非受控初始值onChange(value: string[], event) void值变化时触发返回归一化后的完整数组onCheck(value: string, item, checked, event) void复选框状态变化时触发含节点与勾选态明细cascadebooleantrue是否父子节点双向级联直接影响value的归一化规则data*Option[]必填层级数据源valueKey/labelKey/childrenKeystringvalue/label/children自定义数据键名uncheckableItemValuesstring[]不可勾选的节点值如只看部门、不选具体人场景disabledItemValuesstring[]禁用的节点值cleanablebooleantrue是否允许清空已选值清空时onChange会收到[]七、小结受控核心valueonChange外部状态全权决定选中项示例见 controlled.md级联归一化cascadetrue默认时值数组只保留顶层节点由 useCascadeValue.ts 的transformValue与splitValue实现切换cascade时应同步重置value非受控替代仅需初始值时使用defaultValue测试保障testControlledUnControlled验证了受控模式下用户操作与value同步的契约参考 MultiCascader.spec.tsx。受控模式让MultiCascader可以无缝接入表单状态库如 Form 组件、Redux、Zustand并让搜索筛选、级联联动、值预处理等业务逻辑集中在组件外部统一处理是复杂选择场景下的推荐写法。赞分享前端UI组件【免费下载链接】rsuite A suite of React components .项目地址https://gitcode.com/gh_mirrors/rs/rsuite点击查看免费下载相关推荐rsuite DateRangePicker 受控与非受控模式完全指南value、onChange 与 defaultValue 实战rsuite DateRangePicker 受控与非受控模式完全指南value、onChange 与 defaultValue 实战 本篇技术指南围绕 rs前端UI组件rsuite DatePicker 受控与非受控模式完全指南value / defaultValue / onChange 的源码级解析rsuite DatePicker 受控与非受控模式完全指南value / defaultValue / onChange 的源码级解析 在 React 生态前端UI组件RSuite Cascader 受控模式实战用 value 与 onChange 掌控级联选择状态RSuite Cascader 受控模式实战用 value 与 onChange 掌控级联选择状态 本指南聚焦 RSuite 级联选择器Cascader的前端UI组件上一篇5分钟掌握哔咔漫画下载器打造你的专属离线漫画图书馆终极指南下一篇m4s-converter如何永久保存B站视频的完整指南创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
