前端UI组件【免费下载链接】react-adminA frontend Framework for single-page applications on top of REST/GraphQL APIs, using TypeScript, React and Material Design项目地址https://gitcode.com/gh_mirrors/re/react-admin点击查看免费下载SimpleFormIterator是 react-admin 中用于编辑对象数组的核心组件它把ArrayInput与ReferenceManyInput的值渲染为每行一个子记录的可编辑列表并内置添加、删除、清空与排序能力。本文以 react-admin 仓库中 docs/SimpleFormIterator.md 为骨架结合ra-core与ra-ui-materialui的源码实现系统讲解其全部 Props、自定义按钮模式、FormDataConsumer行内联动、布局与样式以及底层 Context 与react-hook-form的协作原理帮助你写出真正可落地、可定制的行级数组表单。你的浏览器不支持 video 标签。组件定位与适用场景SimpleFormIterator让用户能够对子记录进行编辑、添加、删除和重排。它的设计定位是作为以下组件的子组件使用ArrayInput最常见的用法绑定一个对象数组字段例如订单的 items 列表ReferenceManyInput以多对一关联的方式编辑关联记录数组。此外你也可以把它放在一个包含field array的ArrayInputContext中使用——即由 react-hook-form 的useFieldArrayhook 返回的值所驱动的上下文环境。从源码结构看该组件分为两层实现逻辑层SimpleFormIteratorBasepackages/ra-core/src/controller/input/SimpleFormIteratorBase.tsx与 UI 无关负责从useArrayInput取出append / fields / move / remove并通过SimpleFormIteratorContext暴露操作能力同时支持disableAutoFocus与getItemDefaultsUI 层SimpleFormIteratorpackages/ra-ui-materialui/src/input/ArrayInput/SimpleFormIterator.tsx负责ul列表渲染、每行的SimpleFormIteratorItem、Add / Clear 按钮区以及全部样式规则。这种分层意味着你完全可以在 headless 场景如ra-core的测试环境复用同一套迭代逻辑这也是它被设计为基类 具体实现的原因。基本用法默认布局与 inline 紧凑布局SimpleFormIterator默认不需要任何必填 prop只要把一组 Input 作为 children 传入即可。它会为每一行渲染这些 Input并自动为每一行计算不同的 source 前缀如items[0].name、items[1].name。下面是一个典型的订单编辑表单——每行包含名称、单价、数量三个输入并通过inline让它们排在同一行同时关闭 helperText 以获得密集排版import { Edit, SimpleForm, TextInput, DateInput, ArrayInput, NumberInput, SimpleFormIterator } from react-admin; const OrderEdit () ( Edit SimpleForm TextInput sourcecustomer / DateInput sourcedate / ArrayInput sourceitems SimpleFormIterator inline TextInput sourcename helperText{false} / NumberInput sourceprice helperText{false} / NumberInput sourcequantity helperText{false} / /SimpleFormIterator /ArrayInput /SimpleForm /Edit );在inline布局下每行的输入水平排列行与行之间更加紧凑适合字段较窄、行数较多的场景。如果字段较多、需要更宽松的编辑空间则省略inlineprop让每个 Input 独占一行const OrderEdit () ( Edit SimpleForm TextInput sourcecustomer / DateInput sourcedate / ArrayInput sourceitems SimpleFormIterator TextInput sourcename / NumberInput sourceprice / NumberInput sourcequantity / /SimpleFormIterator /ArrayInput /SimpleForm /Edit );默认布局每个输入独占一行的渲染效果如下Props 一览表以下为SimpleFormIterator支持的全部 Props来源docs/SimpleFormIterator.md 及 SimpleFormIterator.tsx 的 Props 接口Prop必填类型默认值说明addButton否ReactElement-用于渲染添加按钮的自定义元素children否ReactElement-每行要显示的 Input 列表className否string-应用到根元素ul的 CSS 类disableAdd否booleanfalse为 true 时用户无法添加新行disableAutoFocus否booleanfalse阻止添加新行时自动聚焦第一个输入disableClear否booleanfalse为 true 时用户无法清空整个数组disabled否booleanfalse为 true 时禁用所有按钮子输入不可变、不可聚焦、不随表单提交disableRemove否booleanfalse为 true 时用户无法删除行亦支持函数形式见下文disableReordering否booleanfalse为 true 时用户无法对行进行排序fullWidth否booleantrue设为 false 时把行操作按钮粘到最后一个输入后面getItemLabel否functionfalse回调用于渲染每一行前面的标签inline否booleanfalse为 true 时同一行的输入放在同一行removeButton否ReactElement-用于渲染删除按钮的自定义元素reOrderButtons否ReactElement-用于渲染上移/下移按钮的自定义元素readOnly否booleanfalse为 true 时子输入不可编辑但仍可聚焦、随表单提交sx否SxProps-Material UI 的自定义样式快捷方式说明Props 表中原文档将getItemLabel默认值写作x x而当前仓库源码SimpleFormIterator.tsx第 53 行实际默认值为false不渲染标签本文以源码为准。disableRemove除boolean外还支持record boolean函数形式详见下文。自定义按钮addButton / removeButton / reOrderButtons三个按钮类 Props 允许你完全替换默认的 Add、Remove 与 Reorder 按钮。替换组件的关键是调用对应的 Context hook来触发真正的数组操作。addButton自定义添加按钮addButton传入的自定义元素在被点击时必须触发useSimpleFormIterator暴露的add函数SimpleFormIterator addButton{MyAddButton label{Add a line} /} TextInput sourcename / NumberInput sourceprice / NumberInput sourcequantity / /SimpleFormIteratorMyAddButton的实现示例import { ButtonProps, useSimpleFormIterator, useTranslate } from react-admin; import React from react; import Button from mui/material/Button; export const MyAddButton (props: ButtonProps) { const { add } useSimpleFormIterator(); const translate useTranslate(); return ( Button onClick{() add()} {...props} {translate(props.label ?? ra.action.add)} /Button ); };从源码看add最终会调用SimpleFormIteratorBase中的addField其内部执行append(getItemDefaults(item), { shouldFocus: !disableAutoFocus })见 SimpleFormIteratorBase.tsx。getItemDefaults用于在新增行时注入默认值——这也是新行可自动填充默认值的入口。removeButton自定义删除按钮删除按钮需要调用useSimpleFormIteratorItem暴露的remove函数注意与add的 hook 不同remove是针对当前行的SimpleFormIterator removeButton{MyRemoveButton labelRemove this line /} TextInput sourcename / NumberInput sourceprice / NumberInput sourcequantity / /SimpleFormIteratorimport * as React from react; import clsx from clsx; import { ButtonProps, useSimpleFormIteratorItem, useTranslate } from react-admin; import Button from mui/material/Button; export const MyRemoveButton (props: OmitButtonProps, onClick) { const { remove } useSimpleFormIteratorItem(); const translate useTranslate(); return ( Button onClick{() remove()} colorwarning {...props} {translate(props.label ?? ra.action.remove)} /Button ); };reOrderButtons自定义上移/下移按钮重排按钮需要同时访问当前行的index、总行数total以及reOrder回调。useSimpleFormIteratorItem恰好返回这三者const ReOrderButtons () { const { index, total, reOrder } useSimpleFormIteratorItem(); return ( IconButton sizesmall onClick{() reOrder(index - 1)} disabled{index 0} ArrowUpwardIcon / /IconButton IconButton sizesmall onClick{() reOrder(index 1)} disabled{total null || index total - 1} ArrowDownwardIcon / /IconButton / ); }; const OrderEdit () ( Edit SimpleForm TextInput sourcecustomer / DateInput sourcedate / ArrayInput sourceitems SimpleFormIterator reOrderButtons{ReOrderButtons /} TextInput sourcename / NumberInput sourceprice / NumberInput sourcequantity / /SimpleFormIterator /ArrayInput /SimpleForm /Edit );Hook 与 Context 的对应关系两个 Hook 的取值来源非常清晰见 useSimpleFormIterator.ts 与 useSimpleFormIteratorItem.tsuseSimpleFormIterator()读取SimpleFormIteratorContextSimpleFormIteratorContext.ts提供{ add, clear, remove, reOrder, source, total }useSimpleFormIteratorItem()读取SimpleFormIteratorItemContextSimpleFormIteratorItemContext.ts提供{ index, total, remove, reOrder }。两个 Hook 在脱离对应 Context 使用时都会直接抛出Error因此只能在上文所述的对应组件内部调用。children 与 FormDataConsumer 行内联动每行输入列表children是一组 Input 元素会渲染在每一行上SimpleFormIterator TextInput sourcename / NumberInput sourceprice / NumberInput sourcequantity / /SimpleFormIterator默认每个输入独占一行配合inlineprop 可改为水平排列。通过 scopedFormData 实现行内字段联动SimpleFormIterator也接受FormDataConsumer作为子组件。此时FormDataConsumer会额外向其函数子元素提供一个scopedFormData属性——一个包含当前正在渲染的那一项值的对象。这允许你在迭代器内部建立输入之间的依赖关系例如只有填了作者姓名才显示角色选择框import { FormDataConsumer } from react-admin; const PostEdit () ( Edit SimpleForm ArrayInput sourceauthors SimpleFormIterator TextInput sourcename / FormDataConsumer {({ formData, // 整个表单数据 scopedFormData, // 当前 ArrayInput 项的数据 }) scopedFormData scopedFormData.name ? ( SelectInput sourcerole // 会被转换为 authors[0].role choices{[{ id: 1, name: Head Writer }, { id: 2, name: Co-Writer }]} / ) : null } /FormDataConsumer /SimpleFormIterator /ArrayInput /SimpleForm /Edit );TypeScript 提示scopedFormData的类型是可选的。这是因为FormDataConsumer也可能在ArrayInput之外使用此时该参数为undefined。如果你确定自己在ArrayInput内部可以放心假定该参数有值。在行内展示 Field而非 InputSimpleFormIterator只接受 Input 组件作为 children。如果你想在行内展示只读的 Field如TextField需要借助FormDataConsumer把当前行的记录传给 Field 的recordimport { ArrayInput, SimpleFormIterator, DateInput, TextField, FormDataConsumer, Labeled } from react-admin; ArrayInput sourcebacklinks SimpleFormIterator disableRemove DateInput sourcedate / FormDataConsumer {({ scopedFormData }) ( Labeled labelUrl TextField sourceurl record{scopedFormData} / /Labeled )} /FormDataConsumer /SimpleFormIterator /ArrayInput行行为控制禁用与只读disableAdd禁止添加新行为 true 时Add 按钮不会被渲染用户无法新增行SimpleFormIterator disableAdd TextInput sourcename / NumberInput sourceprice / NumberInput sourcequantity / /SimpleFormIterator从源码看SimpleFormIterator.tsx按钮区的渲染条件为!disabled !(disableAdd (disableClear || disableRemove))即disableAdd生效时整个底部按钮区都可能被隐藏。disableRemove禁止删除行为 true 时Remove 按钮不会被渲染SimpleFormIterator disableRemove TextInput sourcename / NumberInput sourceprice / NumberInput sourcequantity / /SimpleFormIterator增强能力函数形式的 disableRemove。从源码SimpleFormIteratorItem.tsx可以看到disableRemove除了布尔值还接受(record: RaRecord) boolean的函数形式用于按当前行的记录内容逐行决定是否禁用删除SimpleFormIterator disableRemove{record record.immutable} TextInput sourcename / /SimpleFormIterator该行为在 SimpleFormIterator.spec.tsx 中有对应测试用例disableRemove为布尔值与返回值为 truthy 的函数两种情形均被覆盖。disableReordering禁止重排行为 true 时上移/下移按钮不会被渲染SimpleFormIterator disableReordering TextInput sourcename / NumberInput sourceprice / NumberInput sourcequantity / /SimpleFormIteratordisableClear禁止清空数组为 true 时清空整个数组的按钮Clear不会被渲染SimpleFormIterator disableClear TextInput sourcename / NumberInput sourceprice / NumberInput sourcequantity / /SimpleFormIteratordisabled整体禁用disabled置为 true 时所有按钮被禁用且子输入不可修改、不可聚焦、也不会随表单提交SimpleFormIterator disabled TextInput sourcename / NumberInput sourceprice / NumberInput sourcequantity / /SimpleFormIterator与只读控件相反disabled 控件无法获得焦点且不会随表单提交。源码中disabled会同时抑制按钮区与每行操作区的渲染并给根元素追加disabledclass。readOnly只读模式readOnly置为 true 时子输入不可编辑但仍然可聚焦且会随表单提交SimpleFormIterator readOnly TextInput sourcename / NumberInput sourceprice / NumberInput sourcequantity / /SimpleFormIteratordisabled与readOnly的区别是所有原生表单控件的基础语义前者完全退出表单后者只是不让改。该 Props 在SimpleFormIteratorProps接口SimpleFormIterator.tsx中被显式声明。自动聚焦与 disableAutoFocus默认情况下SimpleFormIterator会在添加新行后自动聚焦新行中的第一个输入。这个行为来自 react-hook-form 的useFieldArray的append()方法。从源码可以精确看到这一机制的落点SimpleFormIteratorBase.tsx 中的addField执行const addField useEvent((item: any undefined) { append(getItemDefaults(item), { shouldFocus: !disableAutoFocus }); });disableAutoFocus默认为false因此shouldFocus默认为true即自动聚焦一旦你显式设置disableAutoFocusshouldFocus变为false新行不再抢焦点ArrayInput sourceitems SimpleFormIterator disableAutoFocus TextInput sourcename / NumberInput sourceprice / NumberInput sourcequantity / /SimpleFormIterator /ArrayInput这个细节说明disableAutoFocus并不是 react-admin 自己实现的聚焦逻辑开关而是直接透传给了useFieldArray.append的shouldFocus选项。布局与样式inline / fullWidth / getItemLabel / className / sxinline同排输入inline为 true 时同一行的输入放在同一行适合子输入较窄、需要压缩行高的场景SimpleFormIterator inline TextInput sourcename / NumberInput sourceprice / NumberInput sourcequantity / /SimpleFormIterator不传inline时每个输入独占一行SimpleFormIterator TextInput sourcename / NumberInput sourceprice / NumberInput sourcequantity / /SimpleFormIterator从样式源码看SimpleFormIterator.tsxinline作用于SimpleFormIteratorClasses.inline类flexDirection: row且columnGap: 1em而SimpleFormIteratorItem内部也把输入容器Stack的方向切换为{ xs: column, sm: row }。fullWidth行操作按钮的位置默认fullWidth为 true时每行的操作按钮Remove / Reorder出现在行尾如果表单较窄可以把fullWidth设为false让操作按钮粘在最后一个输入后面压缩水平空间SimpleFormIterator fullWidth{false} TextInput sourcename / NumberInput sourceprice / NumberInput sourcequantity / /SimpleFormIterator其底层实现是根元素上的fullwidthclass 配合选择器.fullwidth ul li .form { flex: 2 }即让输入区域在 fullWidth 时占据行内剩余弹性空间。getItemLabel每行前置标签SimpleFormIterator可以基于行索引为每一行添加一个前置标签。传入一个回调即可开启SimpleFormIterator getItemLabel{index #${index 1}} TextInput sourcename / NumberInput sourceprice / NumberInput sourcequantity / /SimpleFormIterator源码中标签通过SimpleFormIteratorClasses.index类渲染为Typography并且getItemLabel的回调签名在 SimpleFormIteratorItem.tsx 中被声明为(index: number) string | ReactNode——这意味着除了字符串你甚至可以返回任意 React 节点作为行标签。className根元素类名className会被传递到根元素ulSimpleFormIterator classNamedummy TextInput sourcename / NumberInput sourceprice / NumberInput sourcequantity / /SimpleFormIterator建议要定制字段样式优先使用sxprop而不是className。sx样式定制规则你可以通过sx覆盖根元素一个div及内部组件的样式。它支持以下子类规则规则名称说明RaSimpleFormIterator-action应用于每行的操作区包含 Remove 按钮的区域RaSimpleFormIterator-add应用于底部包含 Add 按钮的行RaSimpleFormIterator-form应用于每一行的子表单区域RaSimpleFormIterator-index应用于设置了getItemLabel时的行标签RaSimpleFormIterator-inline应用于inline为 true 时的行RaSimpleFormIterator-line应用于每一行liRaSimpleFormIterator-list应用于ul元素例如通过sx{{ .RaSimpleFormIterator-line: { backgroundColor: grey.100 } }}即可统一给每行加底色。这些 class 由useThemeProps的PREFIX生成并注册进 MUI 主题因此也可以在主题层通过components.MuiRaSimpleFormIterator.styleOverrides做全局定制见 SimpleFormIterator.tsx 的组件类型声明。获取当前行索引useSimpleFormIteratorItem在SimpleFormIterator内部你可以用useSimpleFormIteratorItemhook 访问当前元素的行索引import { TextInput, ArrayInput, SimpleFormIterator, useSimpleFormIteratorItem, } from react-admin; import { Typography } from mui/material; const IndexField () { const { index } useSimpleFormIteratorItem(); return ( Typography variantbody2 sx{{ alignSelf: center }} #{index 1}: /Typography ); }; const UserArray () ( ArrayInput sourceitems SimpleFormIterator inline IndexField / TextInput sourcename helperText{false} / TextInput sourcerole helperText{false} / /SimpleFormIterator /ArrayInput );提示该 hook 还返回当前数组的元素总数total上文ReOrderButtons示例就同时用到了index与total。提示如果你需要在编程层面根据索引去改变某个输入的值应该使用useSourceContexthook而非手动拼接items[3].name这样的路径。源码深挖行渲染与 Source 前缀机制理解SimpleFormIterator最核心的源码细节是它如何为每一行生成独立的字段路径。整条调用链如下SimpleFormIterator (UI) └─ SimpleFormIteratorBase (逻辑append/move/remove/clear) └─ SimpleFormIteratorItem (每行 li标签 Stack 操作区) └─ SimpleFormIteratorItemBase ├─ SimpleFormIteratorItemContext (index/total/remove/reOrder) └─ SourceContextProvider (行内字段路径前缀)SimpleFormIteratorItemBasepackages/ra-core/src/controller/input/SimpleFormIteratorItemBase.tsx是路径前缀机制的关键。它为每一行包了一层SourceContextProvider其getSource逻辑为子输入未传source标量数组如ArrayInput sourcetags /下的文本输入返回父级 source ${index}最终路径形如tags.0子输入带source如DateInput sourcedate /返回父级 source ${index}.${source}最终路径形如orders.0.date。同时getLabel不会把索引拼进翻译 key避免翻译键里出现序号标签仍保持orders.date这样的形式。另外两个值得注意的源码行为幽灵校验错误处理SimpleFormIteratorBase的removeField在删除行后会检查当前数组是否全部为标量值typeof value ! object若是则对数组字段触发一次trigger(finalSource)校验避免已删除字段的历史校验错误仍被展示见 SimpleFormIteratorBase.tsx。新行默认值注入getItemDefaults通过useGetArrayInputNewItemDefaults(fields)计算可以依据子输入的parse/format等信息为新行生成合理默认值。测试验证仓库中 SimpleFormIterator.spec.tsx 对该组件的行为做了系统性验证例如disableRemove为布尔值时不渲染删除按钮第 146 行起disableRemove为函数且返回 truthy 时不渲染删除按钮第 167 行起getItemLabel回调被正确调用并渲染行标签第 891 行起。如果你需要查看更多真实运行场景可参考 SimpleFormIterator.stories.tsx 中的 Storybook 示例。小结SimpleFormIterator是一个开箱即用、深度可定制的行级数组编辑器默认零配置即可获得添加、删除、重排、清空完整能力通过inline、fullWidth、getItemLabel、sx控制布局与观感通过addButton、removeButton、reOrderButtons结合useSimpleFormIterator/useSimpleFormIteratorItem两个 Context Hook 实现完全自定义的操作按钮通过disableAdd、disableRemove含函数形式、disableReordering、disableClear、disabled、readOnly精确控制行行为。理解其背后SimpleFormIteratorBase→SimpleFormIteratorItemBase的分层与SourceContext前缀机制你就能在复杂的嵌套表单场景中游刃有余。赞分享前端UI组件【免费下载链接】react-adminA frontend Framework for single-page applications on top of REST/GraphQL APIs, using TypeScript, React and Material Design项目地址https://gitcode.com/gh_mirrors/re/react-admin点击查看免费下载相关推荐react-beautiful-dnd 核心组件 DragDropContext / 完全指南Props、Responders 与源码级原理react beautiful dnd 核心组件 DragDropContext / 完全指南Props、Responders 与源码级原理 DragDrreact-datepicker 的 InputTime 组件时间输入框的 Props、源码原理与自定义实践react datepicker 的 InputTime 组件时间输入框的 Props、源码原理与自定义实践 InputTime 是 react datepi前端UI组件React Native Elements Tooltip 组件完全指南全部 Props、ref 手动控制与源码级定位原理React Native Elements Tooltip 组件完全指南全部 Props、ref 手动控制与源码级定位原理 Tooltip气泡提示是 ReUI组件移动开发前端上一篇5分钟掌握智能涂装转换让普通图片秒变专业赛车涂装下一篇Firebase-queue核心架构解析如何实现多阶段作业管道的容错机制创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考