craft.js 0.2.x 核心包版本演进全解:React 19 支持、SSR、DnD 细节与 API 增强

原创2026-09-24 16:53:051,924 阅读
文章标签:前端

craft.js 0.2.x 核心包版本演进全解:React 19 支持、SSR、DnD 细节与 API 增强

本指南以 packages/core/CHANGELOG.md 为主体脉络,系统梳理 @craftjs/core 从 0.2.1 到 0.2.12 的每一个实质性变更:从 React 19 支持、SSR 渲染、DnD 指示器定制,到 <Element /> 的 hidden 属性、UserComponent 的 info 元数据、resolver 性能优化与事件处理细节。读完本文,你将能准确判断哪些版本修复了哪些问题、如何在自己的编辑器中启用这些新能力,以及每个变更背后的源码实现逻辑。

版本总览:0.2.1 → 0.2.12 的演进主线

craft.js 是一个用于构建可扩展拖拽式页面编辑器的 React 框架。@craftjs/core 是其核心包,其版本演进直接决定了编辑器在兼容性、交互体验与 API 能力上的边界。从 0.2.1 到 0.2.12,核心包的变更可以归纳为四条主线:

  • 框架兼容性:React 19 支持(0.2.12)、React Strict Mode 下节点创建/解析的修复(0.2.7、0.2.1)、SSR 支持(0.2.6);
  • 拖拽交互体验:DnD 指示器样式定制(0.2.9)、Safari 拖拽阴影修复(0.2.4)、拖出 Editor 画布时消除延迟(0.2.6)、鼠标离开时清除 hover 状态(0.2.2、0.2.3);
  • API 与数据模型:<Element /> 新增 hidden 属性(0.2.6)、UserComponent 新增 info 属性(0.2.5)、actions.add() 的 parentId 变为可选(0.2.6);
  • 工程与性能:resolver 性能优化(0.2.6)、lodash 按需导入(0.2.1)、npm 包 typings 修复(0.2.10)、源码映射导出(0.2.9)。
版本 关键变更 关联依赖更新
0.2.1 修复 Strict Mode 下从 Frame children 解析产生的孤立节点;resolver prop 空值保护;lodash 按需导入 @craftjs/utils@0.2.1
0.2.2 mouseleave 时移除节点 hovered 状态 —
0.2.3 新增 removeHoverOnMouseleave 选项 —
0.2.4 修复 Safari 拖拽阴影 —
0.2.5 UserComponent 新增 info 属性,复制到 Node 但不参与序列化 —
0.2.6 SSR 支持;<Element /> 新增 hidden 属性;actions.add() 的 parentId 可选;resolver 性能优化;拖出画布不再延迟 —
0.2.7 修复 React Strict Mode 下 <Element /> linked node 创建;清理 React.FC 类型 @craftjs/utils@0.2.2
0.2.8 导出 Positioner 与 createShadow —
0.2.9 注入 Craft 包版本;导出 sourcemaps;DnD 指示器样式/类名可定制 @craftjs/utils@0.2.3
0.2.10 修复 npm 包缺失 typings 的回归 @craftjs/utils@0.2.4
0.2.11 layers 包使用 removeHoverOnMouseleave 选项 —
0.2.12 支持 React 19 @craftjs/utils@0.2.5

每个 Patch 版本都通过 changesets 同步更新了依赖的 @craftjs/utils,这意味着核心包的变更往往伴随事件处理、历史记录等底层工具的配套升级。

兼容性与渲染:React 19、Strict Mode 与 SSR

React 19 支持(0.2.12)

0.2.12 是核心包近期最重要的兼容性里程碑:Add support for react 19。在此之前,craft.js 内部通过 ReactDOM 的 legacy API 和特定生命周期行为来驱动编辑器渲染,而 React 19 对渲染器 API、类型声明与 Strict Mode 语义都做了调整。升级到 0.2.12 后,使用 React 19 的项目可以在 peer dependencies 层面获得官方支持,配套的 @craftjs/utils@0.2.5 也同步更新。

需要说明的是:该版本仅声明支持 React 19,并不改变既有的 API 形态。现有基于 Editor、Frame、Element 的代码无需改动即可运行。

Strict Mode 下 linked node 创建修复(0.2.7)

React Strict Mode 会在开发环境对组件渲染进行"双重调用"以暴露副作用问题。在 0.2.7 之前,<Element /> 在 Strict Mode 下可能创建出重复的 linked node。修复位于 Element.tsx:

const [linkedNodeId] = useState<NodeId | null>(() => {
  invariant(!!id, ERROR_TOP_LEVEL_ELEMENT_NO_ID);
  const node = query.node(nodeId).get();

  if (inNodeContext) {
    const existingNode = node.data.linkedNodes[id]
      ? query.node(node.data.linkedNodes[id]).get()
      : null;

    // 若 linked node 已存在且类型一致,直接复用
    if (existingNode && existingNode.data.type === is) {
      return existingNode.id;
    }

    // 否则创建新的 linked Node
    const linkedElement = React.createElement(Element, elementProps, children);
    const tree = query.parseReactElement(linkedElement).toNodeTree();
    actions.history.ignore().addLinkedNodeFromTree(tree, nodeId, id);
    return tree.rootNodeId;
  }
  return null;
});

关键设计是使用 useState 的惰性初始化函数来存放 linkedNodeId——该函数只在组件首次挂载时执行一次,Strict Mode 的二次渲染不会重新触发创建逻辑。创建后,通过 linkedNodes 记录 id → nodeId 的映射,并在 JSX 中通过 NodeElement 渲染。同类型复用、不同类型重建的判断逻辑保证了"同一位置多次渲染同一 <Element />"的幂等性。

与此同源的是 0.2.1 修复的 Strict Mode 下从 Frame children 解析产生孤立节点(orphaned nodes) 问题:当 Frame 直接接收 JSX children 时,parseReactElement 会把 JSX 树反序列化为节点树,Strict Mode 的双重调用曾导致部分节点丢失 parent 引用。0.2.1 同时确保了 Editor 组件 resolver prop 的非空值(non-null resolver prop value),避免因空 resolver 导致反序列化时抛错;并顺手将 lodash 改为按需导入(import specific lodash methods),降低打包体积。

SSR 支持(0.2.6)

0.2.6 引入 SSR(服务端渲染)支持,这是面向文档站点、博客、营销落地页等需要首屏 SEO 场景的关键能力。其实现要点可以从渲染管线推断:

  • Frame 的 children 解析(parseNodeFromJSX / deserializeNode)在服务端可执行,不依赖 DOM;
  • 渲染节点时通过 RenderNodeToElement(RenderNode.tsx)包裹,服务端只输出静态 HTML,不触发拖拽事件绑定。

在 Next.js 项目中启用 SSR 时,建议将编辑器组件作为客户端组件加载,并通过 dynamic 关闭 SSR 的方式配合服务端输出——具体参考 examples/landing(基于 Next.js + TypeScript 的落地页编辑器示例,含完整的 Editor、Toolbox、Viewport 实现)。

拖拽交互:指示器定制、hover 清理与 Safari 修复

DnD 指示器样式与类名定制(0.2.9)

0.2.9 允许开发者自定义拖拽放置指示器(dnd indicator)的样式与类名。指示器是拖拽过程中显示"可以放置在此"的高亮区域。从 store.tsx 的默认配置可见其颜色体系:

indicator: {
  error: 'red',
  success: 'rgb(98, 196, 98)',
},

Editor 组件接收 indicator 选项,可分别覆盖 success(合法放置点)与 error(非法放置点)的颜色;该配置同样支持传入自定义类名以接入自己的 CSS 体系。指示器的状态由 actions.setIndicator()(actions.ts)维护,其内部会做防御性检查——当父节点 DOM 不存在或当前节点无 DOM 时直接忽略,防止在未渲染的节点上显示指示器。

同版本还完成了两件工程化事项:向运行时代码中注入 Craft 包版本号(便于调试与版本诊断),以及导出 sourcemaps(便于在浏览器 devtools 中调试打包后的源码)。

导出 Positioner 与 createShadow(0.2.8)

0.2.8 将 Positioner 与 createShadow 加入公开导出(见 events/index.tsx)。这两个工具分别负责:

  • Positioner:根据拖拽过程中的鼠标位置、源节点与目标节点计算放置位置(computeIndicator()),是"拖到哪就高亮哪"的核心算法模块;
  • createShadow:创建拖拽时跟随鼠标的节点阴影快照。

如果你需要实现自定义的拖拽视觉反馈(比如复制式拖拽、不同的阴影形态),可以直接基于这两个导出构建,而不必修改框架内部。

鼠标离开时清除 hover 状态(0.2.2 / 0.2.3)

0.2.2 修复了节点 hovered 状态在 mouseleave 后不清理的问题,0.2.3 则进一步将行为可配置化——新增 removeHoverOnMouseleave 选项。从 DefaultEventHandlers.ts 可以看到其实际工作方式:

export type DefaultEventHandlersOptions = {
  isMultiSelectEnabled: (e: MouseEvent) => boolean;
  removeHoverOnMouseleave: boolean;
};

当 removeHoverOnMouseleave 为 true 时,事件处理器会在节点的 mouseleave 事件上注册清理逻辑(unbindMouseleave = this.addCraftEventListener(el, 'mouseleave', ...)),把该节点从 hovered 集合中移除;默认值为 false(见 store.tsx 中的 removeHoverOnMouseleave: false)。0.2.11 将这一选项同步应用到 layers 包(LayerHandlers.ts),使图层面板中的节点 hover 行为与画布保持一致。

自定义事件处理器时,CoreEventHandlers 的类型签名强制要求提供该选项({ store: EditorStore; removeHoverOnMouseleave: boolean } & O),这保证了任何继承默认事件体系的手写 handler 都不会遗漏 hover 清理逻辑。

Safari 拖拽阴影修复(0.2.4)

0.2.4 修复了 Safari 下的拖拽阴影问题。Safari 对 HTML5 drag & drop 的 drag image 支持与 Chrome/Firefox 存在差异,导致拖拽时跟随鼠标的阴影位置偏移或缺失。该修复位于 createShadow 相关逻辑中,建议在 Safari 中实际拖拽测试阴影的跟随行为,确认无误后再发布。

拖出画布不再延迟(0.2.6)

0.2.6 修复了"将元素拖出 Editor 画布时产生延迟"的问题。此前在元素被拖出画布边界、drop 事件无法命中任何合法放置点时,编辑器需要等待一系列事件回调超时才能复位;修复后拖出画布会立即触发事件清理(clearEvents),用户不会感到卡顿。

API 与数据模型增强

<Element /> 的 hidden 属性(0.2.6)

0.2.6 为 <Element /> 组件新增了 hidden 属性,用于声明式地隐藏某个节点。默认值与类型定义在 Element.tsx:

export const defaultElementProps = {
  is: 'div',
  canvas: false,
  custom: {},
  hidden: false,
};

export type ElementProps<T extends React.ElementType> = {
  id?: NodeId;
  is?: T;
  custom?: Record<string, any>;
  children?: React.ReactNode;
  canvas?: boolean;
  hidden?: boolean;
} & React.ComponentProps<T>;

hidden 会经由 elementPropToNodeData 写入节点数据(data.hidden)。渲染端 RenderNodeToElement 读取该字段并直接跳过渲染:

const { hidden } = useInternalNode((node) => ({
  hidden: node.data.hidden,
}));

// don't display the node since it's hidden
if (hidden) {
  return null;
}

return React.createElement(onRender, { render: render || <DefaultRender /> });

注意:隐藏节点不会调用 onRender——这一点有对应测试覆盖(RenderNode.test.tsx 中 "When the node is hidden" 用例断言 onRender 未被调用)。因此 hidden 适合用于"结构上存在但视觉上不渲染"的场景,例如条件容器的占位。

与此同时,运行时也可以通过 actions.setHidden(id, bool)(actions.ts)命令式地切换节点的隐藏状态,data.hidden 同时存在于 NodeData 接口(nodes.ts)。

UserComponent 的 info 属性(0.2.5)

0.2.5 为 UserComponent 新增了 info 属性:会被复制到对应的 Node 上,但不会参与序列化。这意味着你可以把调试信息、版本标记、内部元数据等附加到节点上,而不用担心它们被写入保存的 JSON 状态中。

从 nodes.ts 的接口可以看到 info 同时存在于两个层面:

// NodeData 层:组件声明 -> 节点数据的映射
export type UserComponent<T = any> = {
  info: Record<string, any>;
  // ...rules / related / props / custom / isCanvas / name
};

// Node 层:序列化后的节点实例
export type Node = {
  id: NodeId;
  data: NodeData;
  info: Record<string, any>;
  // ...
};

由于 info 不参与序列化,序列化流程(serializeNode / deserializeNode)会将其排除在 nodes 数据之外,从而避免元数据污染通过 actions.serialize() 输出的 JSON。

actions.add() 的 parentId 变为可选(0.2.6)

0.2.6 让 actions.add() 的 parentId 参数变为可选。此前在编辑器根部(ROOT_NODE)以外添加节点必须显式传入父节点 ID;现在省略 parentId 时,节点会被添加到画布根节点之下。这一改动简化了"向编辑器注入一次性节点"的调用:

// 旧写法
actions.add(nodeTree, 'ROOT');

// 新写法:省略 parentId,默认挂到根节点
actions.add(nodeTree);

工程化与性能:resolver 优化与包分发

resolver 性能优化(0.2.6)

resolver 是 Editor 用于将节点类型名称映射回 React 组件的配置。0.2.6 的优化核心在于 resolveComponent.ts:维护了一个反向映射缓存,把 resolver 对象一次性转换为 Map<ComponentType, string>:

const getReversedResolver = (resolver: Resolver): ReversedResolver => {
  if (CACHED_RESOLVER_DATA && CACHED_RESOLVER_DATA.resolver === resolver) {
    return CACHED_RESOLVER_DATA.reversed;
  }
  // 首次构建反向 Map 并缓存
  CACHED_RESOLVER_DATA = {
    resolver,
    reversed: new Map(),
  };
  for (const [name, comp] of Object.entries(resolver)) {
    CACHED_RESOLVER_DATA.reversed.set(comp, name);
  }
  return CACHED_RESOLVER_DATA.reversed;
};

只有当传入的 resolver 引用发生变化时才重建缓存,否则直接复用,从而避免了每次节点渲染时线性扫描 resolver 的开销。resolver 里未注册的组件会在反序列化时触发 invariant 错误(ERROR_NOT_IN_RESOLVER),提示开发者将对应组件加入 resolver。

typings 回归修复与版本注入(0.2.10 / 0.2.9)

0.2.10 修复了"npm 包不包含 typings"的回归:某个发布步骤意外遗漏了 .d.ts 文件,导致 TypeScript 项目在升级后无法解析类型。若你的项目在 0.2.9 之后出现 Could not find a declaration file 错误,请升级至 0.2.10。结合 0.2.9 的"注入版本号 + 导出 sourcemaps"改动,@craftjs/core@0.2.10 起建议在打包工具中保留 sourcemap 配置,便于线上定位问题。

升级建议与验证清单

基于以上变更,从旧版本升级时建议按以下清单逐项验证:

  1. React 19 项目:升级到 0.2.12(配套 @craftjs/utils@0.2.5);
  2. 使用 Strict Mode:至少升级到 0.2.7,确认 linked node 与 Frame 解析不产生重复/孤立节点;
  3. 需要 SSR:升级到 0.2.6+,在 Next.js 等框架中验证服务端输出与客户端水合的一致性;
  4. 自定义拖拽指示器:0.2.9+,通过 indicator 选项覆盖 success/error 颜色或类名;
  5. hover 行为:0.2.3+,按需开启 removeHoverOnMouseleave(layers 面板需 0.2.11+);
  6. 自定义拖拽视觉:0.2.8+,直接使用导出的 Positioner 与 createShadow;
  7. TypeScript 类型解析:确认版本 ≥ 0.2.10,避免 typings 缺失。

每个版本的变更都伴随 @craftjs/utils 的同步升级(见各版本的 "Updated dependencies" 段落),因此在锁定版本时建议以 changesets 发布的同一批次为准,避免核心包与工具包版本错位。

结语

从 0.2.1 到 0.2.12,@craftjs/core 的演进体现了典型的"编辑器框架"成熟路径:先修补框架兼容性(Strict Mode、SSR、React 19),再开放能力(指示器定制、Positioner/createShadow 导出、hidden/info 属性),最后打磨体验与工程(hover 清理、Safari 阴影、resolver 缓存、typings 修复)。理解这些变更背后的源码逻辑,能帮助你在升级版本时准确评估影响面,并为自定义编辑器行为提供可靠的实现参考。完整的版本变更记录请查阅 packages/core/CHANGELOG.md,各模块源码位于 packages/core/src。

登录后查看全文
craft.js