前端UI组件【免费下载链接】rsuite A suite of React components .项目地址https://gitcode.com/gh_mirrors/rs/rsuite点击查看免费下载本篇文章以 RSUITE 官方文档中 List 组件的默认用法片段为起点系统讲解 List 组件在 RSUITEReact 组件库中的完整能力基础列表渲染、尺寸与边框控制、悬停交互、拖拽排序、分组排序collection、固定项排序以及全部 Props 与回调 Payload 的类型定义。读完你将能够在实际项目中直接用ListList.Item快速搭建带交互的列表界面并掌握拖拽排序底层实现的基本原理。组件定位与使用场景RSUITE 的 List 组件用于展示一组数据适合呈现类似列表形式的内容并内置了拖拽排序能力对应文档 docs/pages/components/list/zh-CN/index.md 的定位描述。它由两个子组件构成List列表容器负责布局、尺寸、边框、悬停、排序等全局配置List.Item列表项负责单条数据的渲染与索引/分组信息注册。典型的应用场景包括消息会话列表、待办事项清单、商品清单、联系人分组列表、可拖拽调整顺序的配置项等。快速开始渲染一个默认列表关联文档default.mddocs/pages/components/list/fragments/default.md给出了最基础的用法定义一组消息数据用Array.prototype.map渲染出多个List.Item。import { List } from rsuite; const messages [ { id: 1, sender: Alice, content: Hey, are we still meeting tomorrow?, time: 2024-12-05 10:15 }, { id: 2, sender: Bob, content: Yes, let’s meet at 3 PM., time: 2024-12-05 10:18 }, { id: 3, sender: Charlie, content: Can you send me the report?, time: 2024-12-05 11:00 }, { id: 4, sender: David, content: I will, no worries., time: 2024-12-05 11:05 } ]; const App () ( List {messages.map(message ( List.Item key{message.id} strong{message.sender}/strong: {message.content} small({message.time})/small /List.Item ))} /List ); ReactDOM.render(App /, document.getElementById(root));要点说明List.Item的key建议使用数据中唯一标识如id避免使用数组索引默认情况下列表项之间会显示分割线divider默认值为true见 List.tsx不传任何配置时列表采用默认尺寸md、默认过渡时长300ms。引入方式RSUITE 的组件均支持按需引入。List 组件可以从包根入口导入import { List } from rsuite;同时List.Item作为静态子组件挂载在List上源码见 List.tsx 的Subcomponents定义因此无需单独引入直接通过List.Item使用即可。列表尺寸size通过size属性可以统一控制列表项的尺寸支持lg | md | sm | xs四个档位默认值为md。演示片段size.mddocs/pages/components/list/fragments/size.md展示了与SegmentedControl联动切换尺寸的完整做法import { List, SegmentedControl } from rsuite; const data [Roses are red, Violets are blue, Sugar is sweet, And so are you]; const App () { const [size, setSize] React.useState(sm); return ( SegmentedControl data{[ { value: xs, label: Extra Small }, { value: sm, label: Small }, { value: md, label: Medium }, { value: lg, label: Large } ]} value{size} onChange{setSize} / hr / List size{size} {data.map((item, index) ( List.Item key{index} index{index} {item} /List.Item ))} /List / ); };补充说明List.Item自身也接受size属性且优先级高于父级源码中const size sizeProp || parentSize;ListItem.tsx表明单项自定义尺寸 列表统一尺寸渲染时尺寸会以data-size{size}的形式写到列表项 DOM 上ListItem.tsx样式层据此控制内边距与字体大小。边框与分割线bordered / divider边框borderedbordered为布尔属性用于为列表项显示边框。演示片段bordered.mddocs/pages/components/list/fragments/bordered.md用法如下import { List } from rsuite; const App () ( List bordered List.ItemRoses are red/List.Item List.ItemViolets are blue/List.Item List.ItemSugar is sweet/List.Item List.ItemAnd so are you/List.Item /List );分割线divider与无分割线列表divider属性控制列表项之间是否显示分割线自版本 5.75.0 起提供默认值为true。当需要紧凑的信息型列表如联系信息、资料项时可以显式关闭分割线见演示片段no-divider.mddocs/pages/components/list/fragments/no-divider.mdimport { List, HStack, Text } from rsuite; import PeoplesIcon from rsuite/icons/Peoples; import LocationIcon from rsuite/icons/Location; import EmailIcon from rsuite/icons/Email; import GlobalIcon from rsuite/icons/Global; const data [ { id: 1, icon: PeoplesIcon /, value: rsuite/team }, { id: 2, icon: LocationIcon /, value: Shanghai, China }, { id: 3, icon: EmailIcon /, value: a hrefmailto:john.doersuitejs.comjohn.doersuitejs.com/a }, { id: 4, icon: GlobalIcon /, value: a hrefhttp://rsuitejs.comrsuitejs.com/a } ]; const App () ( List divider{false} sizexs {data.map(item ( List.Item key{item.id} HStack {item.icon} Text{item.value}/Text /HStack /List.Item ))} /List );divider最终会以data-divider{divider}的形式写入列表容器 DOMList.tsx分割线样式由 SCSS 层根据该属性开关。悬停效果hoverhover为布尔属性开启后列表项在鼠标悬停时有动画反馈。演示片段hover.mddocs/pages/components/list/fragments/hover.md用法import { List } from rsuite; const App () ( List hover List.ItemRoses are red/List.Item List.ItemViolets are blue/List.Item List.ItemSugar is sweet/List.Item List.ItemAnd so are you/List.Item /List );悬停状态同样通过data-hover{hover}属性下发到容器List.tsx由样式表实现具体的过渡动画。拖拽排序sortablesortable开启后列表项即可通过鼠标或触摸拖拽改变顺序。排序时必须为每个List.Item传入index组内唯一这是排序逻辑定位从哪个位置移到哪个位置的依据。基础排序与回调演示片段sortable.mddocs/pages/components/list/fragments/sortable.md给出了最完整的可控排序写法排序结束后通过onSort回调拿到oldIndex与newIndex用splice更新本地数据实现视图与数据同步import { List } from rsuite; const defaultData [ { text: Finish the project report }, { text: Attend team meeting at 3 PM }, { text: Buy groceries for the week }, { text: Call mom to check in } ]; const App () { const [data, setData] React.useState(defaultData); const handleSortEnd ({ oldIndex, newIndex }) setData(prvData { const moveData prvData.splice(oldIndex, 1); const newData [...prvData]; newData.splice(newIndex, 0, moveData[0]); return newData; }, []); return ( List sortable bordered onSort{handleSortEnd} {data.map(({ text }, index) ( List.Item key{index} index{index} {text} /List.Item ))} /List ); };注意示例中使用onSort但组件同时提供onSortStart、onSortMove、onSortEnd四个排序生命周期回调可按需选用。RSUITE 只负责拖拽过程中的视觉与索引计算数据数组的最终重排需要开发者自己在回调中完成。分组排序collectioncollection属性用于把列表项划分到不同的独立分组每个分组内的排序互不影响。同一分组内index必须唯一。演示片段collection.mddocs/pages/components/list/fragments/collection.md给出了商品分组场景并用不同背景色区分分组、用disabled锁定单个项const defaultData [ { text: Apple iPhone 15, collection: 0, price: 999, status: In Stock }, // ... 更多数据 { text: Oculus Quest 2, collection: 3, price: 299, status: In Stock, disabled: true } ]; const App () { const [data, setData] React.useState(defaultData); const handleSortEnd ({ oldIndex, newIndex }) setData(prvData { const moveData prvData.splice(oldIndex, 1); const newData [...prvData]; newData.splice(newIndex, 0, moveData[0]); return newData; }); const getCollectionStyle collection { return { backgroundColor: colors[collection], color: black }; }; return ( List sortable bordered onSort{handleSortEnd} {data.map(({ text, collection, disabled, status, price }, index) ( List.Item key{text} index{index} disabled{disabled} collection{collection} style{getCollectionStyle(collection)} {text} - ${price} - Status: {status} /List.Item ))} /List ); };结合源码看分组机制useSortHelper在移动过程中通过getOrderedItems(curManagedItem.info.collection)只取当前分组内的项参与位移计算useSortHelper.ts因此分组之间天然隔离。固定项排序disabled 项disabled属性禁止该列表项被拖拽移动。在基于分组排序之上可以用disabled项充当分组中的固定位置占位如固定序号标签。演示片段sort-fixed.mddocs/pages/components/list/fragments/sort-fixed.md把每个浏览器名称项前插入一个禁用态的序号项序号项固定不动浏览器项在间隔中排序const BrowserList [Chrome, Edge, FireFox, Safari]; const App () { const [data, setData] React.useState(BrowserList); const handleSortEnd ({ oldIndex, newIndex }) setData(prvData { const moveData prvData.splice((oldIndex - 1) / 2, 1); const newData [...prvData]; newData.splice((newIndex - 1) / 2, 0, moveData[0]); return newData; }, []); return ( List sortable bordered onSort{handleSortEnd} {data.flatMap((browser, index) [ List.Item key{index} index{index * 2} collectionorder disabled {index 1} /List.Item, List.Item key{browser} index{index * 2 1} {browser} /List.Item ])} /List ); };实现上useSortHelper的handleStart/handleTouchStart会读取被按下的列表项若其disabled为真则直接跳过拖拽启动useSortHelper.ts渲染时disabled也会以data-disabled与aria-disabled标记到 DOMListItem.tsx。带自定义项的列表List.Item内部可以自由组合任意 RSUITE 组件。演示片段custom.mddocs/pages/components/list/fragments/custom.md用AvatarHStackText拼出了带头像的消息卡片import { List, HStack, Text, Avatar } from rsuite; // messages 数据含 avatar 头像地址字段 const App () ( List {messages.map(message ( List.Item key{message.id} HStack spacing{15} alignItemscenter Avatar src{message.avatar} alt{message.sender} circle / HStack.Item flex{1} HStack justifyContentspace-between Text strong{message.sender}/Text Text muted sizesm {message.time} /Text /HStack Text{message.content}/Text /HStack.Item /HStack /List.Item ))} /List );从源码结构看List.Item直接渲染为Box底层为div rolelistitemListItem.tsx内部内容完全由开发者掌控因此可实现任意复杂的自定义布局。Props 完整参考以下属性表完整继承自组件文档 docs/pages/components/list/en-US/index.md中英双语版本见 zh-CN/index.md。List属性属性类型默认值说明版本autoScrollboolean(true)列表溢出时自动滚动borderedboolean为列表项显示边框dividerboolean在列表项之间显示分割线![][5.75.0]hoverboolean启用列表项悬停动画onSort(payload: Payload) void排序结束时的回调onSortEnd(payload: Payload) void排序操作结束后的回调onSortMove(payload: Payload) void列表项移动时的回调onSortStart(payload: Payload) void排序开始时的回调pressDelaynumber(0)按下后触发排序的延迟毫秒sizelg | md | sm | xs(md)定义列表项尺寸sortableboolean启用列表项排序功能transitionDurationnumber(300)排序动画时长毫秒源码佐证这些默认值divider true、size md、pressDelay 0、transitionDuration 300、autoScroll true均在 List.tsx 中解构赋值随后全部传给useSortHelper与列表上下文。List.Item属性属性类型默认值说明collectionnumber | string(0)列表项所属分组标识disabledboolean禁用该项禁止其被移动index *number该项在分组内的唯一索引排序时必选sizelg | md | sm | xs(md)单个列表项的尺寸Payload类型四个排序回调均接收同一结构的Payloadinterface Payload { collection: number | string; node: HTMLElement; newIndex: number; oldIndex: number; }字段含义collection标识当前拖拽项所属分组node是被拖拽项的 DOM 节点oldIndex为拖拽前的索引newIndex为拖拽结束后的目标索引。开发者只需依据oldIndex/newIndex重排数据数组即可。源码中该类型在 useSortHelper.ts 以MovedItemInfo名称定义回调触发顺序为onSortStart→onSortMove多次→onSortEnd→onSort。拖拽排序的底层实现原理结合源码可以进一步理解排序的完整工作链路核心实现集中在 useSortHelper.ts 与 helper 目录注册机制每个List.Item挂载后通过register把自己的 DOM 节点、index、collection、disabled注册进管理器ListItem.tsx卸载时自动注销拖拽启动鼠标按下onMouseDown或触摸开始onTouchStart时handleStart/handleTouchStart向上查找最近的已注册列表项校验非右键、非disabled、非正在排序、且不包含输入类交互元素后依据pressDelay延时启动handlePressuseSortHelper.ts克隆跟随拖拽开始后被拖拽项被克隆成一个rs-list-item-helper辅助节点position: fixed跟随指针移动原节点加上rs-list-item-holder占位useSortHelper.ts位移计算与动画在mousemove/touchmove期间遍历同分组有序项根据指针偏移与各节点edgeOffset计算translate3d位移并设置过渡时长占位节点随之移动形成其他项让位的动画效果useSortHelper.ts自动滚动autoScroll开启时由AutoScrollerAutoScroller.ts在容器溢出时自动滚动视口触摸拖拽期间会临时禁用页面滚动document.body.style.overflow hidden结束后恢复useSortHelper.ts结束清理mouseup/touchend后等待transitionDuration毫秒完成归位动画随后移除辅助节点、清空所有位移/过渡内联样式、停止自动滚动并依次触发onSortEnd与onSort回调useSortHelper.ts。这也是文档属性表中transitionDuration控制动画时长与pressDelay控制触发延迟两项配置的实际作用位置。小结RSUITE List 组件用极简的ListList.Item 两层结构覆盖了从静态列表到复杂拖拽排序的完整需求尺寸size、边框bordered、分割线divider、悬停hover控制外观sortableindex 分组collection 禁用disabled支撑排序交互四个排序生命周期回调配合Payload类型让数据同步清晰可控。配合 List.stories.tsx 的交互演示与 List.spec.tsx 的测试用例可以在任何 React 项目中放心使用。赞分享前端UI组件【免费下载链接】rsuite A suite of React components .项目地址https://gitcode.com/gh_mirrors/rs/rsuite点击查看免费下载相关推荐rsuite List 组件完全指南从基础渲染到拖拽排序与分组管理rsuite List 组件完全指南从基础渲染到拖拽排序与分组管理 导读 List 是 rsuite 中用于展示列表型数据、并原生支持拖拽排序的容器组件。本文前端UI组件Semi Design List 列表组件完全指南从基础渲染到虚拟滚动、拖拽排序与键盘交互Semi Design List 列表组件完全指南从基础渲染到虚拟滚动、拖拽排序与键盘交互 列表List是 Semi Designsemi ui中最常前端UI组件设计系统Semi Design List 列表组件实战指南从基础用法到虚拟滚动、拖拽排序与组合增强Semi Design List 列表组件实战指南从基础用法到虚拟滚动、拖拽排序与组合增强 Semi Design douyinfe/semi ui ht前端UI组件设计系统上一篇从慢到快Mamba如何解决神经网络架构搜索的效率难题下一篇Genesis安装与快速入门指南创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考