企业官网建设流程全解析

Refine 实战指南：深入理解 React Fragments 的用法、原理与常见坑

【免费下载链接】refineA React Framework for building internal tools, admin panels, dashboards & B2B apps with unmatched flexibility.项目地址: https://gitcode.com/GitHub_Trending/re/refine

React Fragment 是 React 16.2 引入的核心特性，用于在不向 DOM 添加额外节点的情况下分组返回多个元素。本篇技术指南以 Refine 开源仓库（React 生态下的内部工具与后台面板框架）为背景，讲解 Fragment 与<div>的本质差异、key 的正确用法、快捷语法<></>的局限，并结合 Refine 源码与文档站点中的真实使用案例，帮助你写出结构合法、渲染高效、易于维护的 JSX。

引言：为什么组件不能直接返回多个元素

在 React 中，从一个组件返回多个元素历来是个难题。原因是 React 依赖一棵树状结构（Virtual DOM 树）来完成 reconciliation（协调）过程：渲染方法返回多个元素时，协调算法无法按预期工作，因为“每个组件只有一个根节点”的假设不再成立。

React 在16.2 版本通过引入 Fragment 解决了这一问题。Fragment 允许你在不向 DOM 增加额外节点的情况下，把一组子元素分组返回，从而维持组件树根节点的唯一性，同时保持最终 HTML 结构的干净与合法。

什么是 React Fragment

React Fragment 允许你从组件中返回多个元素：只需把一组 children 包裹在 Fragment 里，它不会向 DOM 添加任何真实节点。

在 Fragment 出现之前，返回多个元素必须用根元素包裹。这种做法并不高效，在某些场景下还会引发结构性问题。例如下面的表格场景：

function TableData() { return ( <div> <td>Eat</td> <td>Learn</td> <td>Code</td> </div> ); } function Table() { return ( <table> <tr> <TableData /> </tr> </table> ); }

上述代码会渲染出如下 HTML：

<table> <tr> <div> <td>Eat</td> <td>Learn</td> <td>Code</td> </div> </tr> </table>

可以看到，用<div>包裹<td>破坏了<table>与<td>之间的父子关系，生成的是非法 HTML（<div>不能直接作为<tr>的子元素）。要让表格按预期工作，<td>必须各自独立渲染、不能被<div>包裹。在这种场景下，使用 React Fragment 才是正确选择。

React Fragment 与 Div 元素的区别

在 React 中，“Fragment”和“Div”经常被交替使用，但二者有本质区别：

• Fragment：从 DOM 树中“清除”掉多余的容器节点，不产生任何实际 DOM 元素；
• Div：向 DOM 树中真实添加一个<div>节点。

使用 Fragment 可以让代码更简洁、更易读，组件渲染更快、占用内存更少，每个元素都按设计意图渲染。而<div>会因嵌套层级过深导致 DOM 膨胀。

从原型链角度看内存差异也很直观：

• <div>元素的原型链：HTMLDivElement -> HTMLElement -> Element -> Node -> EventTarget，方法多、属性多、内存占用更大，过多嵌套会拖慢页面加载；
• Fragment 的原型链：DocumentFragment -> Node -> EventTarget，方法更少、更轻量。

用 Fragment 可以复用应用中的一部分结构（如前文表格例子中的单元格组），而<div>会让这种复用变得困难。但反过来，也存在必须使用<div>的场景：Fragment 无法直接承载样式或充当可设计的容器，必须在目标元素外加<div>；要给元素加 key 时，也通常需要容器元素配合。因此，应根据具体需求在两者间灵活选择。

使用 div 的弊端

深入剖析滥用<div>的问题：

• <div>会扩大 HTML DOM 规模，导致浏览器消耗超出预期的资源；
• DOM 过大时占用大量内存，页面在浏览器中加载变慢；
• 随着 DOM 变大、嵌套加深，调试和追踪多余节点的来源变得更加困难；
• 用<div>包裹渲染组件可能因阻塞 HTML 而引发性能问题。

React Fragment 的优势

用 React Fragment 替代可能引发非法 HTML 问题的<div>，带来以下好处：

• 代码可读性更高；
• 由于 DOM 更小，渲染更快、内存占用更少；
• 组件可以按设计意图渲染，不会破坏父子关系；
• Fragment 允许返回多个 JSX 元素，解决了此前“每个组件只能返回一个元素”导致 React 应用中非法 HTML 标记的问题。

React Fragment 的局限性

Fragment 虽然擅长在不增加 DOM 节点的情况下分组元素，但也有明显限制：

1. 无法直接应用 CSS 样式：Fragment 不是真实的 DOM 元素，不会渲染任何实际节点，因此无法直接给它设置样式。当需要给一组元素统一加样式时，仍必须用<div>或其他容器包裹；
2. 无法使用 key（在快捷语法下）：处理子元素列表时，key 用于帮助 React 识别哪些项被修改、新增或删除；无法给 Fragment 传 key 会让动态列表的管理变得棘手（注意：标准写法<React.Fragment key={...}>是支持 key 的，局限的是快捷语法<></>，详见下文）；
3. 过度使用会降低 JSX 可读性：清理 DOM 的同时，滥用 Fragment 反而会让 JSX 更难阅读。应当明智地使用，不是每个<div>都必须替换成 Fragment。

在 Fragment 上使用 key prop

在某些场景下，React 应用需要 key prop。React 用 key 控制组件实例，识别列表中哪些项被修改、移除或新增。在 Fragment 上使用 key 的写法如下：

function TableData() { return ( data.map((rec) => ( <React.Fragment key={rec.id}> <td>{rec.hobby}</td> </React.Fragment> )) ); }

注意：这里必须使用完整写法<React.Fragment>（或者从 React 导入Fragment后使用<Fragment key={...}>），因为只有完整写法才能接收key属性。

使用快捷语法 <></>

除了<React.Fragment>，React 还提供简写形式<></>来包裹多个元素，行为与 Fragment 类似且内存负载更低：

function TableData() { return ( <> <td>Eat</td> <td>Learn</td> <td>Code</td> </> ); }

此时渲染出的 HTML 是干净的、无多余容器节点的表格结构：

<table> <tr> <td>Eat</td> <td>Learn</td> <td>Code</td> </tr> </table>

但快捷语法有明确的缺点：无法传任何属性，因此不能使用 key。需要 key 时必须退回完整写法。

Fragment 实战示例

下面是一个完整的 React 应用示例，用 Fragment 渲染表格数据列表：

import "./App.css"; import React from "react"; const Table = ({ children, style }) => { return <div>{children}</div>; }; const TableData = () => { return ( <React.Fragment> <td>John Doe</td> <td>16</td> <td>Developer</td> </React.Fragment> ); }; function App() { return ( <Table> <tr> <th>Name</th> <th>Age</th> <th>Occupation</th> </tr> <TableData /> </Table> ); } export default App;

上例中创建了两个组件：Table负责接收并渲染 children，TableData在渲染时用React.Fragment而不是<div>包裹<td>，从而保证表格数据按预期渲染、HTML 结构合法。

React Fragment 的更多使用场景

Fragment 在处理列表、表单和复杂布局时非常实用：

• 列表：用 Fragment 渲染列表项可以清理 DOM，避免创建无意义的包裹元素，提升性能；
• 表单：多个<input>元素需要分组时，Fragment 在不增加节点的情况下简化结构；
• 复杂布局：元素嵌套较深时，Fragment 有助于控制和管理布局，便于正确设置样式；渲染表格的行与单元格时，Fragment 能确保表格结构合法，避免布局问题；
• 条件渲染：根据某些条件返回多个元素而不污染 DOM，让组件更易读、易维护。

总体而言，在这些场景中使用 Fragment 能显著提升可读性、性能与可维护性。

Refine 仓库中的 Fragment 实践

作为基于 React 的框架，Refine 自身大量使用 Fragment，可以在仓库中看到多种典型用法，验证了上文提到的各项特性：

• 无 key 的多子元素分组：在 RefineProvider 容器 中，<React.Fragment>同时包裹了{children}、<Telemetry />和<RouteChangeHandler />三个子树，且不向 DOM 添加多余节点——这是 Fragment 最典型的“无副作用分组”用法；
• 带 key 的动态列表渲染：在 kbar 命令面板的结果项组件 中，ancestors.map对每个祖先渲染一个<React.Fragment key={ancestor.id}>，这正是文档所述“用完整写法在 Fragment 上加 key”的实战场景；
• 测试中的占位节点：在 antd 通知 Provider 的测试用例 中，closeIcon: <React.Fragment />用 Fragment 作为“空节点”断言，验证了 Fragment 不渲染任何可见内容的特性；
• 作为第三方库的as属性值：在 Refine 文档站点的 doc-sidebar-modal.tsx 中，Fragment被传给 Headless UI 的as属性，配合Transition实现过渡动画——这展示了 Fragment 在“只分组不渲染”场景下对动画/样式库的兼容价值；
• 文档站点的作者列表：在 authors-page 组件 中，用带 key 的<Fragment>渲染每个作者区块及其分隔线，同样是“分组 + key”的组合用法。

这些用例表明：无论框架内部、UI 组件还是文档站点，Fragment 的三大核心价值（不增加节点、支持 key 的完整写法、可与第三方库协作）都是可验证的工程实践。

常见问题与解决方案

以下是在实际开发中使用 React Fragment 时容易遇到的问题及解决方法。

1. 非法 HTML 结构

问题：使用 Fragment 后 HTML 结构仍然非法。

解决：确保没有破坏 HTML 规则。例如把表格单元格（<td>）放在表格行（<tr>）之外就是非法的；应正确使用 Fragment 维护结构合法性。

function TableData() { return ( <> <td>Eat</td> <td>Learn</td> <td>Code</td> </> ); }

2. 无法应用样式

问题：无法给 Fragment 设置样式。

解决：因为 Fragment 不渲染任何 DOM 元素，无法直接应用样式。需要样式时，用<div>或其他合适的容器包裹这些元素。

function StyledComponent() { return ( <div className="styled-container"> <h1>Title</h1> <p>Paragraph</p> </div> ); }

3. 需要 key 的 Fragment

问题：需要给 Fragment 传 key，但快捷语法<></>不支持。

解决：需要传 key 时，使用 Fragment 的完整写法。

function ListItems({ items }) { return ( <> {items.map((item) => ( <React.Fragment key={item.id}> <li>{item.name}</li> <li>{item.description}</li> </React.Fragment> ))} </> ); }

4. Fragment 过度使用

问题：JSX 中 Fragment 过多，代码难以阅读。

解决：谨慎使用 Fragment，仅在必要时使用，避免无谓地让 JSX 变得复杂。

5. 意外的渲染行为

问题：被 Fragment 包裹的内容没有按预期显示。

解决：确认 Fragment 的位置是否正确，是否遗漏了闭合标签，并检查组件逻辑是否正确。

6. 调试困难

问题：Fragment 在 DOM 中不可见，导致调试困难。

解决：调试时使用描述性注释或临时包裹层定位问题，解决后移除临时包裹。

function DebugComponent() { return ( // <div> /* debugging temporary wrapper */ <> <h1>Title</h1> <p>Paragraph</p> </> // </div> ); }

结论

通过本篇指南，你已经全面了解了 React Fragment：从它解决“组件只能返回一个根元素”问题的原理，到与<div>在内存与原型链上的差异；从标准写法<React.Fragment>与快捷语法<></>的选择，到 key 的正确使用方式，以及列表、表单、复杂布局和条件渲染中的实际用例。结合 Refine 仓库中的真实代码（RefineProvider 容器、kbar 结果项）可以看到，Fragment 是保证 React 应用 HTML 结构合法、渲染高效、代码易维护的基础设施。记住它的三条使用准则：需要分组但不想增加 DOM 节点时用 Fragment；需要 key 时用完整写法；需要样式或容器语义时老老实实用<div>。

【免费下载链接】refineA React Framework for building internal tools, admin panels, dashboards & B2B apps with unmatched flexibility.项目地址: https://gitcode.com/GitHub_Trending/re/refine