rsuite CheckPicker 基础使用指南：从多选数据绑定到完整交互配置

前端UI组件【免费下载链接】rsuite A suite of React components .项目地址https://gitcode.com/gh_mirrors/rs/rsuite点击查看免费下载本文以 rsuite 官方文档中 CheckPicker 的基础示例basic.md为核心系统讲解该多选下拉选择器组件的数据结构、搜索开关、受控用法、分组、置顶、虚拟化与无障碍交互并结合 CheckPicker 源码 剖析其底层实现。读完本文你将掌握 CheckPicker 从最小可用示例到生产级配置的完整实战方案。CheckPicker 是什么CheckPicker 是 rsuite 中用于多选的下拉选择组件官方文档en-US/index.md对其定位只有一句话Used for multiple data selection, support grouping——用于多项数据选择并支持分组。它区别于单选 SelectPicker 的核心特征在于每个选项带复选框可同时勾选多个值触发按钮上以计数countable或标签列表的形式展示已选项弹层listbox带有aria-multiselectabletrue属于可多选的组合框combobox。从源码结构看CheckPicker.tsx 组合了PickerToggleTrigger弹层触发器、Listbox选项列表、SearchBox搜索框与PickerToggle触发按钮等内部构件因此它天然继承了 rsuite 所有 picker 类组件的统一交互模型点击展开、键盘导航、搜索过滤、失焦关闭。快速上手最小可用示例基础用法basic.md演示了 CheckPicker 最核心的两种形态带搜索与不带搜索。完整示例代码如下import { CheckPicker, VStack } from rsuite; const data [ Eugenia, Bryan, Linda, Nancy, Lloyd, Alice, Julia, Albert, Louisa, Lester, Lola, Lydia, Hal, Hannah, Harriet, Hattie, Hazel, Hilda ].map(item ({ label: item, value: item })); const App () ( VStack CheckPicker data{data} w{224} / CheckPicker data{data} searchable{false} w{224} placeholderSelect without search / /VStack ); ReactDOM.render(App /, document.getElementById(root));其中w{224}是 rsuite 的简写属性等价于style{{ width: 224 }}用于固定选择器宽度VStack是 rsuite 提供的垂直堆叠布局容器让两个选择器纵向排布。关于ReactDOM.render的说明示例末尾使用ReactDOM.render(App /, document.getElementById(root))这是 rsuite 文档站点历史遗留的演示写法。在你的实际项目中应使用当前 React 版本的挂载方式例如createRoot(document.getElementById(root)).render(App /)并配合import { createRoot } from react-dom/client。组件的用法本身与挂载方式无关。数据源结构label 与 value 双键驱动上述示例展示了 CheckPicker 最基本的数据契约data是一个对象数组每个对象至少包含label展示文本与value实际值两个字段通过.map(item ({ label: item, value: item }))由纯字符串数组生成。底层实现中这两个字段名是可配置的对应两个核心属性见 CheckPicker.tsx 的默认值解构属性默认值作用labelKeylabel读取data中用作选项展示文本的字段valueKeyvalue读取data中用作选项值的字段例如数据项为{ name: Alan, firstName: Alan }时可设置labelKeyfirstName valueKeyname这在后续分组与 sticky 示例中都有体现。源码中selectedItems的计算正是通过shallowEqual(item[valueKey], val)来匹配已选项const selectedItems data.filter(item value?.some(val shallowEqual(item[valueKey], val))) || [];也就是说CheckPicker 的内部值Value类型是一个(string | number)[]数组type Value (string | number)[];当勾选某个选项时源码通过nextValue.push(nextItemValue)/remove(nextValue, ...)维护这个数组并通过onChange(value, event)回调抛给使用者。搜索能力searchable 与 searchBy示例中的第二个选择器通过searchable{false}关闭了搜索框占位文本改为Select without search。searchable的默认值为true见 CheckPicker.tsx源码中只有当它为真时才渲染SearchBox{searchable ( SearchBox placeholder{locale?.searchPlaceholder} onChange{handleSearch} value{searchKeyword} inputRef{searchInput} / )}搜索行为由useSearch(data, { labelKey, searchBy, callback })驱动输入关键词后对data进行过滤过滤后的第一项自动成为键盘焦点项setFocusItemValue(filteredData?.[0]?.[valueKey])并触发onSearch(search, event)回调。默认搜索逻辑是按labelKey指定的字段做不区分大小写的包含匹配。如果你需要自定义匹配规则可以传入searchBy函数CheckPicker data{data} searchBy{(keyword, label, item) String(item.value).startsWith(keyword.toLowerCase()) } /注意searchBy的签名是(keyword, label, item) boolean返回true表示该选项保留在过滤结果中。受控与非受控value 与 defaultValue基础示例是无状态非受控用法。生产环境中更常见的做法是受控模式让父组件完全掌管选中值controlled.mdimport { CheckPicker, RadioGroup, Radio } from rsuite; const data [Eugenia, Bryan, Linda, Nancy, Lloyd, Alice, Julia, Albert].map( item ({ label: item, value: item }) ); const App () { const [value, setValue] React.useState([]); return CheckPicker value{value} onChange{setValue} data{data} w{224} /; }; ReactDOM.render(App /, document.getElementById(root));传value即为受控组件选中状态完全由外部状态决定不传value而传defaultValue则为带默认值的非受控组件onChange(value, event)在每次勾选/取消勾选时触发value为最新的(string | number)[]。从源码看CheckPicker 通过useControlled(valueProp, defaultValue || [])实现受控/非受控的统一管理勾选与取消的增删逻辑位于handleItemSelectCheckPicker.tsxif (checked) { nextValue.push(nextItemValue); } else { remove(nextValue, itemVal shallowEqual(itemVal, nextItemValue)); }即同一选项再次点击会从数组中移除实现复选切换语义。分组显示groupByCheckPicker 支持按数据对象的某个字段分组展示group.md。分组示例用mockUsers(100)生成 100 条用户数据提取首字母作为分组键import { CheckPicker } from rsuite; import { mockUsers } from ./mock; const data mockUsers(100) .map(item { const firstLetter item.firstName[0].toUpperCase(); return { firstLetter, ...item }; }) .sort((a, b) -b.firstLetter.localeCompare(a.firstLetter)); const App () ( CheckPicker data{data} groupByfirstLetter labelKeyfirstName valueKeyname w{200} / ); ReactDOM.render(App /, document.getElementById(root));关键配置groupByfirstLetter告知组件按firstLetter字段的值对选项分组labelKeyfirstName选项展示firstNamevalueKeyname选项值取name。源码中分组发生在渲染弹层时通过getDataGroupBy(items, groupBy, sort)将扁平数组转换为树形分组结构并传给ListboxCheckPicker.tsx。分组标题也可通过renderOptionGroup(title, item)自定义渲染点击分组标题触发onGroupTitleClick(event)。已选项置顶stickysticky属性让已选中的选项在弹层重新打开时排在列表顶部便于用户快速确认与修改已选项sticky.mdCheckPicker sticky data{data} labelKeyfirstName valueKeyname w{224} /其实现思路清晰可见每次弹层打开onEnter时调用initStickyItems从data中筛出与当前value匹配的项存入stickyItemsCheckPicker.tsx渲染时把stickyItems拼接在列表最前面并从未置顶数据中剔除已置顶项避免重复const filteredStickyItems filterNodesOfTree(stickyItems, item checkShouldDisplay(item)); items filterNodesOfTree(data, item { return checkShouldDisplay(item) !stickyItems.some(v v[valueKey] item[valueKey]); });最终传给Listbox的数据为[...filteredStickyItems, ...items]。sticky 与groupBy可组合使用置顶区同样会按分组键聚合。长列表虚拟化virtualized当选项数量达到数千甚至上万时全量渲染会拖慢交互。CheckPicker 提供virtualized属性启用虚拟列表virtualized.md下方示例构造了 10000 条选项const data Array.from({ length: 10000 }).map((_, index) { return { label: Item ${index} is a long text, Used to test the virtualized list., value: Item ${index} }; }); const App () ( CheckPicker data{data} w{224} virtualized / );启用后Listbox只渲染可视区域内的行配合默认listboxMaxHeight 320最大高度与listProps透传给虚拟化列表的配置如行高即可流畅滚动万级数据。注意虚拟化要求选项高度固定或通过listProps明确告知行尺寸否则滚动定位可能不准确。响应式小屏自动变为 Drawer文档en-US/index.md明确说明在 extra-small超小屏幕上弹层默认以全宽 Drawer形式展示若选择器已位于 Modal 或 Drawer 内部可设置responsive{false}保持定位弹层。对应示例见 responsive.tsx其中使用了block让选择器占满整行CheckPicker data{data} block /该行为的开关正是 props 表中的responsive: boolean (true)从源码看它被透传给PickerToggleTriggerCheckPicker.tsx。无障碍与键盘交互作为可多选的 comboboxCheckPicker 内置了完整的 ARIA 语义与键盘支持详见 en-US/index.md 的 Accessibility 章节ARIA 属性根元素角色为comboboxaria-haspopuplistbox声明弹层是 listboxaria-expanded反映弹层开合状态aria-controls指向 listbox 元素的 IDaria-activedescendant指向当前聚焦选项的 ID设置label时combobox 与 listbox 均获得aria-labelledby指向 label 的 idlistbox 具有aria-multiselectabletrue表明支持多选。键盘交互按键行为↓焦点移到下一个选项↑焦点移到上一个选项Enter选中当前聚焦选项Esc关闭 listbox键盘事件的底层编排在useToggleKeyDownEvent中完成Enter 走handleMenuPressEnter切换勾选聚焦项退格键Backspace与清空操作走handleCleanCheckPicker.tsx。核心 Props 速查结合 en-US/index.md 的 Props 表与源码默认值整理高频配置项如下属性类型默认值说明data必填Option[]选项数据形如[{ label, value }]defaultValueValue非受控模式的默认选中值valueValue受控模式的选中值onChange(value, event) void值变化回调searchableboolean (true)是否显示搜索框searchBy(keyword, label, item) boolean自定义搜索匹配onSearch(search, event) void搜索回调groupBystring分组字段名stickyboolean已选项置顶virtualizedboolean虚拟滚动listboxMaxHeightnumber (320)列表最大高度listPropsListProps虚拟列表透传配置countableboolean (true)是否显示已选数量cleanableboolean (true)是否可一键清空disabledItemValuesValue禁用的选项值集合appearancedefault \| subtle (default)外观样式sizelg \| md \| sm \| xs (md)尺寸blockboolean是否占满整行placementPlacement (bottomStart)弹层方位preventOverflowboolean防止弹层溢出容器responsiveboolean (true)小屏是否切换为全宽 Drawerloadingboolean (false)加载态加载中点击不展开renderValue(value, items, selected) ReactNode自定义已选项展示renderExtraFooter() ReactNode自定义底部区域如全选按钮labelReactNode触发按钮前缀标签placeholderReactNode (Select)占位文本与类型相关的Option、Placement、ListProps定义可继续查看 item-data-type.md、placement.md 与 list-props.md。结语CheckPicker 以极简的数据契约[{ label, value }]onChange提供了覆盖绝大多数多选场景的能力基础多选、禁用搜索、受控管理、分组、已选项置顶、万级数据虚拟化、小屏响应式以及完整的无障碍支持。从 CheckPicker.tsx 的实现可以看出其内部统一复用了 rsuite picker 家族的PickerToggleTrigger、Listbox、SearchBox等构件因此如果你已经熟悉 SelectPicker 或其他 picker 组件迁移成本几乎为零。建议下一步阅读同目录下的 appearance.md外观、async.md异步加载、extra-footer.md自定义全选等进阶片段构建完整的多选交互方案。赞分享前端UI组件【免费下载链接】rsuite A suite of React components .项目地址https://gitcode.com/gh_mirrors/rs/rsuite点击查看免费下载相关推荐Roo Code 接入 OpenRouter单 API 键畅用 100 模型的配置与提示词缓存实战指南Roo Code 接入 OpenRouter单 API 键畅用 100 模型的配置与提示词缓存实战指南 Roo Code 内置 OpenRouter 提供方前端UI组件Handsontable 数据绑定完全指南从基础到高级应用Handsontable 数据绑定完全指南从基础到高级应用 前言 在现代 Web 开发中数据表格组件是展示和操作结构化数据的重要工具。Handsontabl前端UI组件抖音批量下载完整指南5 步跑通 douyin-downloader把无水印视频搬进硬盘抖音批量下载完整指南5 步跑通 douyin downloader把无水印视频搬进硬盘 douyin downloader 是开源抖音批量下载工具按无水印前端UI组件上一篇突破层级数据可视化难题Recharts树状图(Treemap)完全指南下一篇系统设计实战教程数据库分片策略详解与最佳实践创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考