前端UI组件【免费下载链接】react-toolboxA set of React components implementing Googles Material Design specification with the power of CSS Modules项目地址https://gitcode.com/gh_mirrors/re/react-toolbox点击查看免费下载React Toolbox 是遵循 Google Material Design 规范、以 CSS Modules 为样式方案的 React 组件库而List是其用于展示同质化数据集合如联系人、菜单项、设置项的核心组件。本文以仓库内 components/list/readme.md 为骨架结合 components/list/ 目录下的实现源码、spec/components/list.js 场景用例与 TypeScript 定义完整讲解List、ListItem、ListCheckbox、ListSubHeader、ListDivider等组件的属性、主题键与底层原理帮助你直接基于该仓库写出可运行、可深度定制的列表界面。一、组件定位与设计思路Material Design 规范中的 List列表由等宽细分单元格行rows组成单一连续列行作为内容块tiles的容器行高可在列表中变化。列表最适合呈现同质化的数据类型或数据集如图片与文本组合其目标是帮助阅读者在同一数据类型中区分不同数据或品质。React Toolbox 的 List 组件严格遵循这一规范并且采用组合式子组件composable subcomponents的设计你可以基于List、ListItem、ListSubHeader、ListDivider、ListCheckbox等部件自由拼装列表。从 components/list/index.js 的导出可以看到除了上述组件外还额外导出了ListItemActions、ListItemContent、ListItemLayout、ListItemText等底层部件用于构建更复杂、更自定义的行内容。// components/list/index.js 的导出集合节选 export { ThemedListItemActions as ListItemActions }; export { ThemedListItemContent as ListItemContent }; export { ThemedListItemLayout as ListItemLayout }; export { ThemedListSubHeader as ListSubHeader }; export { ThemedListItemText as ListItemText }; export { ThemedListCheckbox as ListCheckbox }; export { ThemedListDivider as ListDivider }; export { ThemedListItem as ListItem }; export { ThemedList as List };二、快速上手一个完整的组合示例官方文档给出的经典示例角色名单 配置项覆盖了列表的大多数典型用法头像 主标题 副标题 右侧图标、分组小标题、复选框行、分隔线、左图标操作项import { List, ListItem, ListSubHeader, ListDivider, ListCheckbox } from react-toolbox/lib/list; const ListTest () ( List selectable ripple ListSubHeader captionExplore characters / ListItem avatarhttps://placeimg.com/80/80/animals captionDr. Manhattan legendJonathan Jon Osterman rightIconstar / ListItem avatarhttps://placeimg.com/80/80/animals captionOzymandias legendAdrian Veidt rightIconstar / ListItem avatarhttps://placeimg.com/80/80/animals captionRorschach legendWalter Joseph Kovacs rightIconstar / ListSubHeader captionConfiguration / ListCheckbox checked captionNotify new comics legendYou will receive a notification when a new one is published / ListDivider / ListItem captionContact the publisher leftIconsend / ListItem captionRemove this publication leftIcondelete / /List );在这个示例中selectable ripple让所有行获得悬停高亮、指针光标与点击波纹ListSubHeader为分区提供标题ListCheckbox生成带复选框的行ListDivider用于视觉分隔avatar / caption / legend / leftIcon / rightIcon分别指定头像、主文本、副文本与两侧图标。仓库的交互演示spec/components/list.js进一步展示了五类更具体的场景带图标的导航型列表、双行文本 头像 星标的联系人列表、带复选框的设置列表含checked状态受控与非受控混合、头像 单行文本 邮件图标以及最简单的纯文本单行列表。三、List 容器组件List是整个列表的包装器wrapper负责渲染ul根节点并把影响整表的行为属性下发给子项。属性Properties名称类型默认值说明classNameString为列表根节点附加自定义样式类。rippleBooleanfalse为true时列表中每个元素点击都会产生波纹ripple效果。selectableBooleanfalse为true时列表元素显示悬停效果与指针光标。主题键Theme名称说明list用于列表根节点。源码级原理属性继承prop merging从 components/list/List.js 的实现可以看到List并非简单地把 props 透传下去而是通过React.Children.map遍历子元素并对类型为ListItem的子项执行属性合并const mergeProp (propName, child, parent) ( child[propName] ! undefined ? child[propName] : parent[propName] ); // ... } if (item.type ListItem) { const selectable mergeProp(selectable, item.props, this.props); const ripple mergeProp(ripple, item.props, this.props); return React.cloneElement(item, { selectable, ripple }); }合并规则是子项显式定义了属性值不为undefined时优先使用子项自己的值否则继承父级List的值。这正是文档中ListItem的ripple、selectable描述为默认继承自父元素By default its inherited from the parent的底层原因也解释了如何在整表开启ripple/selectable的同时对个别行单独关闭——在 spec/components/list.js 中就出现了selectable{false} ripple{false}的特例行。注意mergeProp判定的是undefined而非 falsy因此显式传false可以有效覆盖父级为true的设定。四、ListItem 列表项ListItem是列表的核心行组件可以包含头像、图标、标题、副标题等内容。注意它必须是List的直接子组件immediate child。属性Properties名称类型默认值说明avatarString或Element—头像图片的 URL显示在条目左侧。captionString或Element—条目的主文本。classNameString为列表项附加自定义样式类。disabledStringfalse为true时条目显示为禁用态且不可点击。itemContentElement—自定义内容元素一旦设置会覆盖caption与legend。leftActionsArray of Elements—放置在条目左侧头像之后的一组元素。leftIconString或Element—字体图标 key 或元素显示在条目左侧。legendString或Element—显示在 caption 下方的次要文本。onClickFunction—条目被点击时且未禁用触发的回调。rightIconString或Element—与leftIcon相同但图标显示在右侧。rightActionsArray of Elements—放置在条目右侧rightIcon 之后的一组元素。rippleBooleanfalse为true时条目点击产生波纹效果默认继承自父元素。selectableBooleanfalse为true时显示悬停效果与指针光标继承自父元素。toString—若希望条目表现为链接传入该属性指定 href。主题键Theme名称说明disabled附加在禁用条目的内部内容上。item用于列表项的内部内容。itemAction用于每个操作元素左/右。itemContentRoot用于列表项的内容包装元素。itemText附加在列表项内的文本上。large尺寸为 large 时附加到内容包装元素。left用于包裹左侧操作的元素。listItem用于列表项根节点。primary文本为 primary主文本时附加到列表项内的文本。right用于包裹右侧操作的元素。selectable附加在可选中条目的内部内容上。源码级原理布局装配与链接支持从 components/list/ListItem.js 的groupChildren可以看出ListItem会把直系子元素自动归类到左侧操作 / 右侧操作两个桶中一旦出现ListItemContent类型的子元素后续子元素便归入rightActions否则归入leftActions带listItemIgnore标记的子元素则被忽略不参与布局。渲染时li className{${theme.listItem} ${className}} onClick{this.handleClick} ... {to ? a href{this.props.to}{content}/a : content} {children.ignored} /li即to属性存在时行内容会被包进a href中使整行表现为可点击链接点击回调handleClick也做了禁用保护——只有!disabled时才触发外部onClickListItem.js。行内部的真实排版由 components/list/ListItemLayout.js 完成左右操作区按固定顺序组装const leftActions [ props.leftIcon FontIcon value{props.leftIcon} keyleftIcon /, props.avatar Avatar image{props.avatar} keyavatar /, ...props.leftActions, ]; const rightActions [ props.rightIcon FontIcon value{props.rightIcon} keyrightIcon /, ...props.rightActions, ];由此可以确认左右两侧的视觉顺序左侧依次是leftIcon→avatar→leftActions中的元素右侧依次是rightIcon→rightActions中的元素。caption与legend会被渲染为ListItemContent其中caption作为 primary 文本、legend作为次要文本components/list/ListItemContent.js。五、ListCheckbox 复选框列表项ListCheckbox是左侧带复选框控件的特殊列表项。它实现了与ListItem类似的方法并额外提供控制复选框的接口。底层它直接复用Checkbox组件并把caption/legend包装成 labelcomponents/list/ListCheckbox.js因此行为与表单中的 Checkbox 完全一致。属性Properties名称类型默认值说明captionString—条目的主文本必填。classNameString—为组件附加自定义样式类。checkedBooleanfalse为true时复选框默认处于勾选状态。disabledStringfalse为true时条目显示为禁用态且不可点击。legendString—显示在 caption 下方的次要文本。nameString—复选框 input 元素的 name。onBlurFunction—input 元素失焦时调用。onChangeFunction—input 元素变化时调用。onFocusFunction—input 元素聚焦时调用。主题键Theme名称说明checkbox作为复选框的包装类。checkboxItem附加在复选框元素上。disabled组件禁用时附加到根元素。item根元素包装类与 List 相同。itemContentRoot用于列表项的内容包装元素。itemText附加在列表项内的文本上。large尺寸为 large 时附加到内容包装元素。primary文本为 primary 时附加到列表项内的文本。在受控场景下需要像 spec/components/list.js 那样用组件 state 保存勾选状态并在onChange中更新handleCheckboxChange (field) { const newState {}; newState[field] !this.state[field]; this.setState(newState); }; // ... ListCheckbox captionNotifications checked{this.state.checkbox1} legendAllow notifications onChange{this.handleCheckboxChange.bind(this, checkbox1)} /同时该用例也演示了checked与disabled组合使用的静态行Video sounds。六、ListSubHeader 分组小标题ListSubHeader是极简的子组件用于给列表分区提供标题文本。其实现仅渲染一个h5components/list/ListSubHeader.js。属性Properties名称类型默认值说明captionString—要显示的文本。classNameString为列表小标题附加自定义样式类。主题键Theme名称说明subheader小标题元素的包装类。七、ListDivider 分隔线ListDivider用于分隔列表分区或条目只有一个属性insetBoolean指示分隔线是占满整行宽度还是在左侧留出缩进空间。它对应两个主题键inset留空版本与divider完整宽度版本。其实现按inset条件拼接类名components/list/ListDivider.jshr className{inset ? ${theme.divider} ${theme.inset} : theme.divider} /名称类型默认值说明insetBooleanfalse为true时左侧留出缩进空间否则占满整行。在 CSS 层面inset通过左右外边距实现缩进components/list/theme.module.css完整宽度版本以负外边距抵消行高参与布局inset版本则分别设置margin-left: var(--list-content-left-spacing)与margin-right: var(--list-horizontal-padding)。八、进阶部件自由定制行内容当默认的caption legend无法满足需求时可以组合使用ListItemContent、ListItemText、ListItemActions等底层部件。spec/components/list.js 给出了大量这类自定义组件行的实战写法List ripple selectable {/* 在 ListItem 中直接放子元素会自动归入左右操作区 */} ListItem rightIcondone captionItem with custom left icons FontIcon valuesend / Avatar imagehttps://placeimg.com/80/80/people / /ListItem {/* 用 ListItemContent 显式划分内容区后续子元素归入右侧 */} ListItem leftIconsend ListItemContent captioncustom right icons legendListItemContent acts as a divider / FontIcon valuedone / FontIcon valueundo / /ListItem {/* ListItemContent ListItemText 逐行控制主/次文本 */} ListItem leftIconmail rightIconcreate ListItemContent ListItemText primary Custom Caption /ListItemText /ListItemContent /ListItem /List这些部件的职责划分如下导出与类型定义见 components/list/index.d.tsListItemContent内容包装层根据caption、legend、children的数量自动推断行类型auto | normal | large见 ListItemContent.jslarge对应带副文本的更高行ListItemText单行文本primary属性控制主文本样式ListItemText.jsListItemActions按typeleft/right聚合操作元素ListItemActions.jsListItemAction单个操作包装负责事件冒泡隔离——当操作元素带onClick时它会在mouseDown/click阶段调用stopPropagation避免触发整行的点击与波纹ListItemAction.js。这一点尤其重要如果你在列表项内放入可点击的按钮或图标组件会默认拦截其事件向行级冒泡防止点图标却触发行点击的误操作spec/components/list.js中的 Item with overlayed click events 场景正是为了验证这条行为。九、主题定制RTList 上下文键与 CSS Modules与 React Toolbox 其他组件一致List 系列组件通过react-css-themr注入样式。若你希望通过 Context 向这些组件提供样式应使用上下文键RTList对应 components/identifiers.js 中的export const LIST RTList。例如在使用ThemeProvider时import ThemeProvider from react-toolbox/lib/ThemeProvider; import theme from ./my-theme; // 其中需包含 RTList 对应的 CSS Modules 类名映射 ThemeProvider theme{theme} List selectable ripple{/* ... */}/List /ThemeProvider主题对象中应包含本文各组件小节列出的全部主题键如list、listItem、item、itemContentRoot、itemText、itemAction、left、right、subheader、divider、inset、checkbox、checkboxItem、primary、large、disabled、selectable未提供的键将回退到组件内置的 components/list/theme.module.css。若想从零改写 List 的视觉风格内置样式文件的定制变量可作参考components/list/config.module.css--list-vertical-padding: calc(0.8 * var(--unit)); --list-horizontal-padding: calc(1.6 * var(--unit)); --list-content-left-spacing: calc(7.2 * var(--unit)); --list-subheader-height: calc(4.8 * var(--unit)); --list-subheader-font-size: calc(1.4 * var(--unit)); --list-subheader-font-weight: 500; --list-divider-height: calc(0.1 * var(--unit)); --list-item-min-height: calc(4.8 * var(--unit)); --list-item-min-height-legend: calc(7.2 * var(--unit)); --list-item-hover-color: var(--palette-grey-200); --list-item-legend-margin-top: calc(0.3 * var(--unit)); --list-item-icon-font-size: calc(2.4 * var(--unit)); --list-item-icon-size: calc(1.8 * var(--unit)); --list-item-right-icon-margin: ...; --list-item-right-checkbox-margin: ...; --list-item-avatar-height: calc(4 * var(--unit)); --list-item-avatar-margin: calc(0.8 * var(--unit)); --list-item-child-margin: calc(0.8 * var(--unit));这些基于--unit基础密度单位与调色板变量如--palette-grey-200悬停色、--color-text-secondary副文本色推导的尺寸决定了行高、间距、图标尺寸等 Material 风格的度量体系。禁用态在样式层通过pointer-events: none与opacity: 0.5实现theme.module.cssselectable行的悬停背景则在.item.selectable:not(.disabled):hover中定义theme.module.css这印证了属性表中 hover 效果与指针光标的说法。十、TypeScript 支持List 系列组件提供完整的 TypeScript 类型定义均声明于各组件同名.d.ts文件中并从 components/list/index.d.ts 统一导出List、ListCheckbox、ListDivider、ListItem、ListItemAction、ListItemActions、ListItemContent、ListItemLayout、ListItemText、ListSubHeader及各自的Props/Theme接口。例如 ListItem.d.ts 定义了ListItemProps的disabled、ripple、to、theme等字段theme聚合了内容、布局、文本、操作区的全部主题接口ListCheckbox.d.ts 则给出了checked、onChange、onBlur、onFocus等复选框相关签名。类型定义与文档属性表高度一致可作为属性取值范围的权威参考。十一、小结List 的最佳实践组合综合官方文档与仓库源码使用 React Toolbox List 的要点可归纳为容器先行始终用List包裹需要全局交互时在容器上开启selectable/ripple个别行用显式false覆盖继承值按需选型静态文本用ListItem的caption/legend/avatar/leftIcon/rightIcon需要复选框时换ListCheckbox并配合受控checked需要超链接行时传to自由组装复杂行内容直接用ListItemContent、ListItemText、FontIcon、Avatar、Button等作为ListItem的子元素组件会自动完成左右操作区归类与事件冒泡隔离主题统一通过ThemeProvider以RTList上下文键整体替换样式或基于 config.module.css 的变量体系微调间距、颜色与图标尺寸。赞分享前端UI组件【免费下载链接】react-toolboxA set of React components implementing Googles Material Design specification with the power of CSS Modules项目地址https://gitcode.com/gh_mirrors/re/react-toolbox点击查看免费下载相关推荐Windows Btrfs驱动终极指南如何在Windows上无缝访问Linux文件系统Windows Btrfs驱动终极指南如何在Windows上无缝访问Linux文件系统 你是否曾为在Windows和Linux双系统之间共享文件而感到困扰你前端UI组件shadcn-vue Sidebar 组件完全指南从安装、组合式 API 到主题定制shadcn vue Sidebar 组件完全指南从安装、组合式 API 到主题定制 Sidebar侧边栏是 shadcn vue 中最复杂的组件之一它UI组件前端Ant Design Card 卡片组件完全指南API 详解、组合模式与主题定制Ant Design Card 卡片组件完全指南API 详解、组合模式与主题定制 Card卡片是 Ant Design 数据展示组件中最基础也最通用的容器前端UI组件设计系统上一篇5分钟快速搭建Sunshine自托管游戏串流服务器的终极指南下一篇CANN HCCL 故障检测与维测环境变量 HCCL_DFS_CONFIG 完全指南创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考