一、createElement 与 cloneElement 概览
1.1 两个 API 的定位
React 提供了两个用于操作元素的顶层 API: createElement 与 cloneElement。前者负责从无到有创建一个 React 元素,是 JSX 语法编译后的底层实现;后者负责以一个已存在的 React 元素为蓝本,克隆出带有新 props 的新元素。理解两者的差异,是掌握 React 元素模型、编写高阶组件与复合组件的基础。
1.2 元素的本质
在 React 中,元素(Element)是一个普通对象,描述了 DOM 节点或组件在某一时刻的样貌。它包含 type、props、key、ref 等字段。createElement 与 cloneElement 都返回这样的元素对象,但创建路径截然不同。
1.3 速览对比
| 维度 | createElement | cloneElement |
| --- | --- | --- |
| 输入 | type 字符串或组件 | 已存在的 React 元素 |
| 输出 | 全新元素 | 克隆元素(带新 props) |
| Props | 完全由调用方提供 | 合并原始 props 与新 props |
| 子元素 | 完全由调用方提供 | 默认保留原始子元素 |
| 典型场景 | JSX 编译、动态组件 | 注入 props、修改子元素 |
二、createElement 详解
2.1 API 签名
React.createElement(type, [props], [...children])type: 元素类型, 可以是标签字符串(如 "div")、React 组件(函数或类)、React Fragment 等。
props: 可选的对象, 包含属性与事件。
children: 可选的零到多个子节点, 会自动拼接到 props.children。
2.2 工作原理
createElement 会做三件事: 合并默认 props 与传入 props、提取并校验 key/ref、收集 children。最终返回一个冻结的 React 元素对象。
2.3 与 JSX 的关系
JSX 会被 Babel 编译为 createElement 调用。下面两段代码等价:
const el = <Button type="primary" onClick={handler}>Submit</Button>; // 等价于 const el = React.createElement(Button, { type: "primary", onClick: handler }, "Submit");2.4 使用场景
createElement 常用于以下场景:
- 动态渲染组件, type 在运行时确定。
- 编写不依赖 JSX 的工具函数或库。
- 在 Babel 插件、AST 转换中生成元素。
2.5 代码示例
import React from "react"; function DynamicRenderer({ component, ...rest }) { return React.createElement(component, rest); } function App() { return React.createElement( "div", { className: "wrapper" }, React.createElement("h1", null, "Title"), React.createElement(DynamicRenderer, { component: "p", children: "Hello" }) ); }三、cloneElement 详解
3.1 API 签名
React.cloneElement(element, [props], [...children])element: 要克隆的 React 元素。
props: 将与原始元素的 props 浅合并, 新值覆盖旧值。
children: 若提供, 则替换原始子元素; 若不提供, 则保留原始子元素。
3.2 工作原理
cloneElement 以原始元素的 type 为基础, 复制其 props, 再用新 props 覆盖, 保留原始 key 与 ref(可被新 props 覆盖), 并决定是否替换 children。
3.3 不可变性的体现
React 元素是不可变的。cloneElement 不会修改原元素, 而是返回一个新的元素对象。这一点与 React 的整体不可变数据哲学一致。
3.4 使用场景
cloneElement 主要用于以下场景:
- 向子组件注入额外的 props(如事件、样式、状态)。
- 复合组件(Compound Components)模式中父组件控制子组件。
- 高阶组件中增强被包裹元素的 props。
- 克隆并修改 key/ref。
3.5 代码示例
import React from "react"; function RadioGroup({ name, children }) { return ( <div className="radio-group"> {React.Children.map(children, (child) => React.cloneElement(child, { name }) )} </div> ); } function App() { return ( <RadioGroup name="lang"> <input type="radio" value="js" /> <input type="radio" value="ts" /> </RadioGroup> ); }四、核心区别对比
4.1 创建路径差异
createElement 从 type 出发, 所有 props 由调用方显式提供, 是一张白纸。cloneElement 从已有元素出发, 继承原始 props, 是增量修改。
4.2 Props 处理差异
createElement: 完全覆盖式, props 字段就是最终字段。
cloneElement: 浅合并式, newProps 覆盖原始同名字段, 其余字段保留。
4.3 Children 处理差异
createElement: children 必须由调用方提供, 否则为 undefined。
cloneElement: 若不传 children 参数, 则保留原始 children; 若传, 则完全替换。
4.4 Key 与 Ref 处理差异
createElement: key 与 ref 来自传入的 props 参数, 会被特殊提取。
cloneElement: 默认保留原元素的 key 与 ref; 若 newProps 中提供 key 或 ref, 则覆盖。
4.5 性能与开销
两者最终都生成新的元素对象, 开销相近。但 cloneElement 多一步浅拷贝与合并, 在大量克隆时需注意避免在 render 中重复克隆同一元素造成无谓开销。
五、实战案例
5.1 复合组件: cloneElement 注入 props
import React, { Children, cloneElement, useState } from "react"; function Tabs({ children }) { const [active, setActive] = useState(0); return ( <div> <div className="tab-bar"> {Children.map(children, (child, index) => cloneElement(child, { active: index === active, onClick: () => setActive(index) }) )} </div> </div> ); } function Tab({ active, onClick, children }) { return ( <button onClick={onClick} style={{ fontWeight: active ? "bold" : "normal" }}> {children} </button> ); } function App() { return ( <Tabs> <Tab>One</Tab> <Tab>Two</Tab> <Tab>Three</Tab> </Tabs> ); }5.2 动态组件: createElement 运行时构造
import React, { createElement } from "react"; const components = { primary: "button", link: "a", div: "div" }; function Polymorphic({ as = "div", ...rest }) { return createElement(components[as] || as, rest); }5.3 高阶组件中的选择
高阶组件通常用 createElement 包裹被传入组件, 而非 cloneElement, 因为高阶组件往往要重新组织渲染结构而非修改原元素。若只是注入 props, cloneElement 也适用, 但要注意 ref 转发问题。
六、常见误区与最佳实践
6.1 误区: cloneElement 会修改原元素
cloneElement 返回新元素, 原元素保持不变。若发现原元素被改动, 多半是其他副作用导致。
6.2 误区: 用 cloneElement 改 type
cloneElement 不直接支持改 type, 但可以通过 element.type 读取后用 createElement 重建。强行改 type 可能破坏 React 内部一致性。
6.3 最佳实践
- 优先使用 JSX, 仅在动态场景使用 createElement。
- cloneElement 用于"增强"已有子元素, 不要用于"替换"。
- 在复合组件中配合 React.Children.map 使用 cloneElement, 统一注入 props。
- 注意 ref 转发, React 19 中 ref 可作为普通 prop 传递, cloneElement 中 ref 处理更简单。
- 避免在每次 render 中无意义地克隆, 确保依赖关系稳定。
七、总结
createElement 与 cloneElement 是 React 元素模型的两块基石。前者负责"造", 从 type 出发全量构建; 后者负责"改", 从已有元素出发增量合并。掌握 createElement 有助于理解 JSX 本质与动态渲染; 掌握 cloneElement 有助于编写复合组件与 props 注入逻辑。两者配合使用, 能覆盖绝大多数元素操作需求。在实际开发中, 遵循"创建用 createElement、增强用 cloneElement"的原则, 即可写出清晰、可维护的 React 代码。
