react-admin `＜TreeInput＞` 树形节点选择组件完整指南：从树数据到外键选择

react-adminTreeInput树形节点选择组件完整指南从树数据到外键选择【免费下载链接】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-adminTreeInput是 react-admin 生态中react-admin/ra-treeEnterprise Edition 组件专用于在表单中从一个树形结构里选择一个或多个节点的输入组件适合为产品选择分类这类层级数据建模场景。阅读本文后你将掌握树数据结构TreeRecord的约定、TreeInput全部核心 Props 的含义与默认值、如何通过dataProvider.getTree()/useGetTree拉取选项以及如何配合ReferenceNodeInput声明式地完成多对一/一对一外键选择。什么是TreeInput在什么场景下使用它TreeInput的作用是在 react-admin 表单中渲染一棵可勾选/可点选的树让用户从树形选项中选择一个或多个节点。官方文档对其定位是用于选择树节点Tree node数据类型的输入组件——在 docs/Inputs.md 的按数据类型选择输入组件对照表中数据类型Tree node示例值42对应的输入组件正是TreeInput。典型场景包括给商品选择一个所属分类分类本身是一棵多级树服装 → 男装 → 西服 → 西裤/夹克为组织架构、权限菜单、地区编码等层级数据指定父级或归属节点在树形参考资源reference resource上设置外键字段。与普通的SelectInput、AutocompleteInput不同TreeInput面向的是具有父子层级关系的数据用户可以在展开/折叠的树中直观地完成选择而不是在扁平的选项列表中查找。安装与引入TreeInput由ra-tree模块提供react-admin 官方 Enterprise Edition 功能引入方式如下import { TreeInput } from react-admin/ra-tree; import { SimpleForm } from react-admin;在文章所依托的仓库中TreeInput与Tree、ReferenceNodeInput、TreeWithDetails等组件一起出现在 docs/Reference.md 的参考资源列表中docs/Features.md 也将其归类为用于树形结构的输入组件。ra-tree同时提供dataProvider树方法扩展与配套 Hooks详见 docs/useGetTree.md。树数据结构TreeRecordTreeInput的dataprop 接收的是dataProvider.getTree()返回格式的数组由若干节点对象组成的数组每个节点含id、children字段其中children是子节点 id 组成的数组可嵌套形成多级树。一份典型的树数据来自官方文档示例如下const data [ { id: 1, title: Clothing, isRoot: true, children: [2, 6] }, { id: 2, title: Men, children: [3] }, { id: 3, title: Suits, children: [4, 5] }, { id: 4, title: Slacks, children: [] }, { id: 5, title: Jackets, children: [] }, { id: 6, title: Women, children: [7, 10, 11] }, { id: 7, title: Dresses, children: [8, 9] }, { id: 8, title: Evening Gowns, children: [] }, { id: 9, title: Sun Dresses, children: [] }, { id: 10, title: Skirts, children: [] }, { id: 11, title: Blouses, children: [] }, ];这种平铺数组 children存子节点 id的结构称为TreeRecord。相关文档 docs/useGetTree.md 对这种格式有进一步说明一个TreeRecord至少包含id字段和children字段子节点 id 数组例如[{ id: 1, title: foo1, children: [3, 4] }, ...]。isRoot字段用于标识根节点TreeInput的hideRootNodes会用到它见下文。节点标题默认读取title字段可通过titleField修改。基础用法在表单中渲染一棵可选择的树将TreeInput放入 react-admin 表单组件如SimpleForm即可import { TreeInput } from react-admin/ra-tree; import { SimpleForm } from react-admin; export const SimpleTreeForm () ( SimpleForm TreeInput sourcecategory data{[ { id: 1, title: Clothing, isRoot: true, children: [2, 6] }, { id: 2, title: Men, children: [3] }, { id: 3, title: Suits, children: [4, 5] }, { id: 4, title: Slacks, children: [] }, { id: 5, title: Jackets, children: [] }, { id: 6, title: Women, children: [7, 10, 11] }, { id: 7, title: Dresses, children: [8, 9] }, { id: 8, title: Evening Gowns, children: [] }, { id: 9, title: Sun Dresses, children: [] }, { id: 10, title: Skirts, children: [] }, { id: 11, title: Blouses, children: [] }, ]} / /SimpleForm );用户选中节点后选中的节点 id 会被写入source指定的字段单选时值为一个 idmultiple多选时值为 id 数组。选中值如何与表单状态交互遵循 react-admin 输入组件通用的source/parse/format机制见下文通用输入属性。Tip如果希望自动从参考资源reference resource拉取树数据请将TreeInput放进ReferenceNodeInput中使用见选择外键一节无需手动传data。Props 完整参考TreeInput的专属 props 如下表官方文档原始表格字段说明已补充取值范围Prop必填类型默认值说明source必填string-表单中该输入对应记录的字段名当用于ReferenceNodeInput内部时可不填checkStrictly可选booleantrue严格勾选模式父节点与子节点的勾选状态互不关联data可选对象数组-树数据格式为dataProvider.getTree()的返回值含children字段的节点数组id可选string-输入框的 HTML idhideRootNodes可选booleanfalse设为true隐藏所有根节点margin可选stringdense输入框外边距可取值none、dense、normal对应 MUI Input marginsmultiple可选booleanfalse设为true允许多选此时每行渲染一个复选框size可选stringsmall输入框尺寸可取值small、medium、large对应 MUI Input sizestitleField可选stringtitle存放节点标题的字段名variant可选stringfilled外观变体可取值standard、outlined、filled对应 MUI Input variants除此之外TreeInput还接受react-admin 的通用输入属性common input props底层 rc-treeTree组件的全部 propsTreeInput内部正是基于 rc-tree 的Tree实现的。下面逐个讲解核心 props。source与通用输入属性source指定表单记录中承载所选节点 id 的字段名是唯一必填 prop只有当TreeInput被包在ReferenceNodeInput内部由外层控制器提供上下文时才可省略。作为 react-admin 标准输入组件TreeInput同样接受 docs/Inputs.md 中列出的通用输入属性className、defaultValue、readOnly、disabled、format、fullWidth、helperText、label、parse、sx、validate等。例如可以用validate做必填校验、用label{false}隐藏标签、用sx定制样式。react-admin 使用 react-hook-form 控制表单输入因此TreeInput也接受useController的所有选项未被消费的 props 会继续向下透传给底层的 Material UI / rc-tree 组件。data树数据的两种来源data是TreeInput的选项数据源必须是以children字段关联的节点数组格式见上文树数据结构。TreeInput sourcecategory data{[ { id: 1, title: Clothing, isRoot: true, children: [2, 6] }, { id: 2, title: Men, children: [3] }, { id: 3, title: Suits, children: [4, 5] }, { id: 4, title: Slacks, children: [] }, { id: 5, title: Jackets, children: [] }, { id: 6, title: Women, children: [7, 10, 11] }, { id: 7, title: Dresses, children: [8, 9] }, { id: 8, title: Evening Gowns, children: [] }, { id: 9, title: Sun Dresses, children: [] }, { id: 10, title: Skirts, children: [] }, { id: 11, title: Blouses, children: [] }, ]} /直接写死的data适合静态数据。如果你正在编辑的是一个关联关系更推荐用ReferenceNodeInput在组件挂载时从参考资源拉取data从而省去手动获取数据的样板代码详见选择外键一节。checkStrictly父子节点勾选是否联动默认情况下TreeInput使用 rc-treeTree的checkStrictly特性允许叶子节点与父节点相互独立地勾选勾选父节点不会自动带上全部子节点反之亦然。文档给出的默认值为true。如果你希望遵循勾选父节点即全选子节点的级联逻辑可显式关闭TreeInput sourcecategory data{treeData} multiple checkStrictly{false} /需要说明的是checkStrictly只在multiple多选带复选框模式下才有实际意义单选模式下不存在父子级联问题。multiple多选模式默认单选。设置multiple后树中每行会渲染一个复选框用户可以同时勾选多个节点表单值变为 id 数组import { SimpleForm } from react-admin; import { TreeInput } from react-admin/ra-tree; import treeData from ./treeData; export const SimpleTreeForm () ( SimpleForm TreeInput sourcecategory data{treeData} multiple / /SimpleForm );多选模式下树数据量较大时可搭配checkStrictly决定是否允许父子节点分别勾选从而精确控制用户的可选粒度。hideRootNodes隐藏根节点当树数据中的根节点带isRoot: true标记或由ra-tree数据提供者约定时设置hideRootNodes会隐藏所有根节点只展示其子孙节点适合根节点只是一个容器、不应被选中的业务模型TreeInput sourcecategory data{treeData} hideRootNodes /titleField指定节点标题字段节点在树中显示的文字默认取自title字段。如果树记录用其他字段存放标题例如name通过titleField指定即可TreeInput sourcecategory data{treeData} titleFieldname /margin/size/variantMUI 外观定制这三个 props 直接映射 Material UI 输入框的外观体系margin默认dense可选none/dense/normal控制输入框外边距MUI Input marginssize默认small可选small/medium/large控制输入框尺寸MUI Input sizesvariant默认filled可选standard/outlined/filled控制输入框边框样式MUI Input variants。由此可以推断TreeInput外壳是一个 MUI 风格的可展开下拉容器内嵌 rc-tree 渲染的树。这与 react-admin每个输入组件内部通常是 MUI 组件、多余 props 透传的设计一致见 docs/Inputs.md。获取选项dataProvider.getTree()与useGetTree实际项目中树数据通常来自后端 API。ra-tree扩展了 dataProvider新增了getTree(resource)方法docs/useGetTree.md 列出了ra-tree推荐的整套树方法读取类的getTree、getRootNodes、getParentNode、getChildNodes写入类的moveAsNthChildOf、moveAsNthSiblingOf、addRootNode、addChildNode、deleteBranch。手动获取树数据的标准做法是使用useGetTreeHook它会在组件挂载时调用dataProvider.getTree()返回TreeRecord数组import { useGetTree, TreeInput } from react-admin/ra-tree; const CategoryInput () { const { isLoading, data: tree } useGetTree(categories); if (isLoading) return Loading /; return ( TreeInput sourcecategory data{tree} / ); };isLoading用于在数据加载期间显示加载指示器。useGetTree返回的data是TreeRecord平铺数组至少含id与children字段正好就是TreeInput的data所需格式。不过官方文档明确指出如果是为了给另一个资源设置外键而填充TreeInput的选项大多数情况下应该用ReferenceNodeInput而非手动useGetTree——前者把拉取参考资源树这件事声明式地封装好了。选择外键配合ReferenceNodeInput当使用TreeInput为一个多对一many-to-one或一对一one-to-one关系设置外键时手动获取选项上一节的useGetTree方案固然可行但 react-admin 为此提供了声明式的捷径——ReferenceNodeInputimport { Edit, SimpleForm, TextInput } from react-admin; import { ReferenceNodeInput, TreeInput } from react-admin/ra-tree; const ProductEdit () ( Edit SimpleForm TextInput sourcename / ReferenceNodeInput sourcecategory_id referencecategories TreeInput / /ReferenceNodeInput /SimpleForm /Edit );ReferenceNodeInput是一个控制器组件挂载时从reference指定的资源调用dataProvider.getTree()拉取整棵树创建树选项上下文然后渲染子组件。默认子组件就是一个不带 props 的TreeInput当你需要自定义TreeInput的 props例如multiple时显式传入子元素即可ReferenceNodeInput sourcecategory_id referencecategories TreeInput multiple checkStrictly{false} / /ReferenceNodeInputReferenceNodeInput还支持metaprop用于在调用getTree()时向 dataProvider 传递元数据ReferenceNodeInput sourcecategory_id referencecategories meta{{ foo: bar }} /在 docs/Inputs.md 的类型对照表中ReferenceNodeInput被归类为处理关联记录Related records的输入组件之一与ReferenceManyInput、ReferenceManyToManyInput、ReferenceOneInput并列而 docs/ReferenceInput.md 也建议当参考资源本身是一棵树时用ReferenceNodeInput替代ReferenceInput。这与TreeInput的设计意图完全一致——树形外键是它最核心的实战场景。底层实现rc-tree 之上的表单化封装从文档与仓库可以梳理出TreeInput的分层实现结构渲染层TreeInput内部使用 rc-tree 的Tree组件该库是 React 生态中广泛使用的树组件因此它接受 rc-treeTree的所有 props——defaultExpandedKeys、expandedKeys、defaultSelectedKeys、selectedKeys、onCheck、onSelect、onExpand、onDrop、motion、sx等均可按需透传这些 props 的语义可在 docs/Tree.md 的Tree组件 props 表中对照查看表单层TreeInput按 react-admin 输入组件约定接入 react-hook-form通过source读写表单值接受通用输入属性与useController选项因此可以无缝嵌入SimpleForm、Edit等表单结构数据层选项来自datagetTree()格式的TreeRecord[]既可以直接传字面量也可以用useGetTree拉取或者由ReferenceNodeInput作为控制器提供。小结TreeInput是 react-admin 中处理层级/树形数据选择的专用输入组件核心要点可概括为数据契约data必须使用dataProvider.getTree()返回的TreeRecord格式平铺数组 children子节点 id 数组核心 Propssource必填multiple开启多选复选框checkStrictly默认true控制父子节点是否独立勾选hideRootNodes隐藏根节点titleField指定标题字段margin/size/variant对齐 MUI 外观体系选项获取静态数据直接传data动态数据用useGetTree设置外键则优先用ReferenceNodeInput声明式完成可扩展性底层基于 rc-tree全部 rc-tree props 均可透传配合通用输入属性可以满足大部分表单场景。相关延伸阅读ReferenceNodeInput树形外键输入、useGetTree树数据 Hook 与 dataProvider 树方法、Tree纯展示型树组件、TreeWithDetails树 详情布局。【免费下载链接】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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考