@craftjs/layers 版本演进与源码剖析:Craft.js 图层面板的 0.2.x 升级指南
@craftjs/layers 版本演进与源码剖析:Craft.js 图层面板的 0.2.x 升级指南
@craftjs/layers 是 Craft.js 生态中专用于页面编辑器场景的"Photoshop 式"图层面板:它以树形结构展示编辑器中的每一个节点,支持展开/折叠、拖拽重排、重命名、隐藏节点与选中联动。本文以 packages/layers/CHANGELOG.md 为脉络,逐一拆解 0.2.1 → 0.2.7 各版本的关键变更(React 19 支持、styled-components 6 迁移、removeHoverOnMouseleave 选项、类型与构建产物修复等),并结合仓库源码讲解 Layers 组件的内部架构、完整 API 与自定义渲染方式。读完本文,你将能够基于当前仓库的源码证据,准确评估该包各版本的行为差异,并快速把它集成进自己的 Craft.js 页面编辑器。
一、版本演进总览:0.2.x 全貌
@craftjs/layers 目前发布到 0.2.7(见 packages/layers/package.json),其 CHANGELOG.md 记录了 0.2.1 至 0.2.7 的全部 Patch 变更。以下是各版本的核心内容一览:
| 版本 | 核心变更 | 关联依赖 |
|---|---|---|
| 0.2.7 | 新增 React 19 支持(PR #726) | @craftjs/utils@0.2.5 |
| 0.2.6 | styled-components 从 4.x 升级到 6.x;接入 removeHoverOnMouseleave 选项(PR #707、#705) |
— |
| 0.2.5 | 修复回归:在 npm 包中包含类型声明(typings) | @craftjs/utils@0.2.4 |
| 0.2.4 | 注入 Craft 包版本号并导出 sourcemap | @craftjs/utils@0.2.3 |
| 0.2.3 | 清理 React.FC 的 prop 类型 |
@craftjs/utils@0.2.2 |
| 0.2.2 | 改进 DefaultLayerHeader 的 chevron(箭头)旋转(PR #604) |
— |
| 0.2.1 | 提升 @craftjs/core peer 依赖版本 |
@craftjs/utils@0.2.1 |
从变更记录可以看到一个清晰的演进方向:先解决依赖与发布质量(0.2.1–0.2.5),再完成样式库与 React 版本兼容(0.2.6–0.2.7),中间穿插 UI 细节与交互体验打磨(0.2.2、0.2.6)。下面按变更主题逐个深入。
二、0.2.7:React 19 支持
0.2.7 最重要的变更是 Add support for react 19(PR #726)。这意味着 @craftjs/layers 已进入 React 19 兼容行列。查看 packages/layers/package.json 中的 peer 依赖声明,可以确认其支持的 React 范围:
"peerDependencies": {
"@craftjs/core": ">=0.2.0",
"react": "^16.8.0 || ^17 || ^18 || ^19",
"styled-components": ">= 6.1"
}
也就是说,从 React 16.8(hooks 引入版本)一直到 React 19 都在支持范围内,同时要求 @craftjs/core 不低于 0.2.0、styled-components 不低于 6.1。该版本同时将 @craftjs/utils 提升到 0.2.5 —— layers 包内部的 wrapConnectorHooks、useMethods 等工具都来自这一依赖(见 useLayer.tsx 与 LayerManagerProvider.tsx),因此 utils 版本对齐是保证 hooks 行为一致的前提。
三、0.2.6:styled-components 6 迁移与 removeHoverOnMouseleave
0.2.6 包含两项值得关注的变更。
3.1 styled-components 从 4.x 升级到 6.x
PR #707 将 styled-components 从 4.x.x 升级到 6.x.x(当前仓库中 devDependencies 声明为 styled-components: 6.1.13,见 package.json),同时 peer 依赖收紧为 >= 6.1。这一迁移直接影响面板的样式实现——DefaultLayer 与 DefaultLayerHeader 均使用 styled 编写(如 DefaultLayer.tsx 中的 LayerNodeDiv、LayerChildren 以及 DefaultLayerHeader.tsx 中的 StyledDiv、Expand、Hide、TopLevelIndicator)。若你的项目仍停留在 styled-components 4.x,升级到 0.2.6+ 前需要一并处理。
3.2 removeHoverOnMouseleave:hover 悬停状态的生命周期管理
PR #705 为 layers 包接入了 removeHoverOnMouseleave 选项。这个选项本身定义于 @craftjs/core(即 <Editor> 的配置项),其默认值为 false(见 packages/core/src/editor/store.tsx)。在 layers 中,它控制 hover 事件的清理时机:
- 当
removeHoverOnMouseleave为false(默认):鼠标移出图层面板条目后,hover 状态会保留; - 当为
true:鼠标移出时立即清除对应 Layer 的 hover 状态。
从源码证据看,该开关在 layers 的事件处理器 LayerHandlers.ts 中被读取——mouseover 时设置 hovered 事件,mouseleave 时(若开启该选项)通过 layerStore.actions.setLayerEvent('hovered', null) 将其复位:
const unbindMouseOver = this.addCraftEventListener(el, 'mouseover', (e) => {
e.craft.stopPropagation();
layerStore.actions.setLayerEvent('hovered', layerId);
});
if (this.derived.options.removeHoverOnMouseleave) {
unbindMouseleave = this.addCraftEventListener(el, 'mouseleave', (e) => {
e.craft.stopPropagation();
layerStore.actions.setLayerEvent('hovered', null);
});
}
setLayerEvent 的实现位于 manager/actions.tsx:它会先清除旧元素的事件标记,再为新元素写入 event.hovered = true,从而保证同一时刻只有一个 Layer 处于 hover 态。对于 hover 高亮易造成视觉残留的复杂编辑器界面,开启此选项可以获得更干净的交互反馈。
四、0.2.4–0.2.5:构建产物与发布质量修复
这两个版本专注于 npm 包产物的可靠性:
- 0.2.4:向产物注入 Craft 包版本号,并导出 sourcemap。版本号注入通常用于运行时诊断——当面板行为异常时,可以通过该标识快速定位是哪个版本的 layers/core 在协作。
- 0.2.5:修复回归——在 npm 包中包含 typings。此前类型声明可能因构建配置未包含
lib目录而缺失,导致 TypeScript 项目无法获得Layers、useLayer、DefaultLayer等符号的类型提示。当前 package.json 明确声明"types": "./lib/index.d.ts"并将dist、lib一起纳入发布文件(files字段),即是对该修复的最终确认。
五、0.2.2–0.2.3:UI 细节与类型清理
- 0.2.2:改进
DefaultLayerHeader的 chevron 旋转(PR #604)。折叠箭头在展开/收起之间通过 CSStransform: rotate(...)平滑旋转(过渡曲线为cubic-bezier(0.19, 1, 0.22, 1),时长 0.4s),见 DefaultLayerHeader.tsx。该 PR 修正了旋转角度与原点,使箭头方向在不同层级下保持一致。 - 0.2.3:清理
React.FC的 prop 类型(PR 相关提交9eff6b8)。它让renderLayer等以组件形式传入的 prop 在 TS 下更精确,避免React.FC隐式children造成的类型膨胀。
六、0.2.1:peer 依赖对齐
0.2.1 将 @craftjs/core 的 peer 依赖提升至 >=0.2.0(见 package.json)。layers 包重度依赖 core 的 useEditor、useMethods、wrapConnectorHooks 以及 ROOT_NODE 常量,版本对齐可避免因 core 侧事件系统(DerivedCoreEventHandlers、select/hover/drag 连接器)接口变化导致的运行时错误。
七、源码视角:Layers 面板是如何工作的
理解版本变更的底层影响,需要先看清 layers 包的整体架构。它的入口在 src/index.tsx:
export const Layers = ({ ...options }: LayersProps) => {
return (
<LayerManagerProvider options={options}>
<LayerContextProvider id={ROOT_NODE} depth={0} />
</LayerManagerProvider>
);
};
整个面板由两个 Provider 驱动:
LayerManagerProvider(manager/LayerManagerProvider.tsx):通过useMethods(LayerMethods, ...)初始化全局 store,默认renderLayer为DefaultLayer,并包裹LayerEventContextProvider用于注入事件处理;LayerContextProvider:从根节点ROOT_NODE(depth 0)开始递归渲染每一层的 Layer 节点。
store 的方法集合定义在 manager/actions.tsx:registerLayer 注册节点、setDOM 绑定 dom/headingDom、toggleLayer/setExpandedState 控制展开态、setLayerEvent 维护 selected/hovered 事件、setIndicator 维护拖拽插入指示器。第 0.2.6 节提到的 hover 清理,正是 setLayerEvent 与事件处理器协同的结果。
拖拽与放置逻辑由 events/LayerHandlers.ts 实现:drag 连接器为节点 DOM 设置 draggable 并监听 dragstart/dragend;dragenter/dragover 通过 core 的 query.getDropPlaceholder() 计算放置位置(before/after、父级 Canvas),最终在 dragend 时调用 editorStore.actions.move(draggedElement, parentId, index + (where === 'after' ? 1 : 0)) 完成节点重排。这也是图层面板"所见即所得"拖拽的核心链路。
八、集成与使用指南
8.1 安装
yarn add @craftjs/layers
安装后请确认项目满足 peer 依赖:@craftjs/core >= 0.2.0、react ^16.8 || ^17 || ^18 || ^19、styled-components >= 6.1。
8.2 最小集成
将 <Layers /> 作为 <Editor> 的子组件渲染即可(完整示例见 site/docs/additional/layers.md):
import React from "react";
import {Editor} from "@craftjs/core";
import {Layers} from "@craftjs/layers";
export default function App() {
return (
<div style={{margin: "0 auto", width: "800px"}}>
<Typography variant="h5" align="center">A super simple page editor</Typography>
<Editor resolver={...}>
<Layers />
</Editor>
</div>
);
}
<Layers /> 的 props 定义在 interfaces.tsx:
| Prop | 类型 | 说明 |
|---|---|---|
expandRootOnLoad? |
boolean |
可选。开启后,根节点(Root Node)默认展开 |
renderLayer? |
React.ElementType |
可选。指定每个 Layer 的自定义渲染组件,默认 DefaultLayer |
8.3 Layer 数据类型
useLayer 的 collector 接收的 Layer 对象(见 interfaces.tsx)包含以下字段:
| 字段 | 类型 | 说明 |
|---|---|---|
id |
NodeId |
随机生成的唯一节点 id |
depth |
number |
当前 Layer 的嵌套深度 |
expanded |
boolean |
该 Layer 是否展开 |
events |
{ selected, hovered } |
selected 表示该 Layer 是否被点击选中;hovered 表示鼠标是否悬停其上 |
dom |
HTMLElement |
整个 Layer(含 header 与 children)的 DOM,由 connectLayer 连接器绑定 |
headingDom |
HTMLElement |
Layer 标题栏的 DOM,由 connectLayerHeader 连接器绑定 |
其中 depth 并不直接存在 Layer 类型中,而是由 LayerContextProvider 逐层传入(根节点 depth 0),在 useLayer 中通过 context 读取,见 useLayer.tsx。
8.4 useLayer API
useLayer(collector) 的参数是一个收集函数 (layer: Layer) => Collected:它从对应 Layer 中提取所需状态,返回值变化时组件会重新渲染(与 core 的 useEditor/useNode 收集模式一致)。返回值包含:
connectorsdrag(dom, nodeId):将该 DOM 标记为可拖拽(内部会设置draggable="true");layer(dom, nodeId):将该 DOM 标记为整个 Layer 的载体(绑定选中、悬停、拖拽事件与dom);layerHeader(dom, nodeId):标记标题栏 DOM(绑定headingDom)。
actionstoggleLayer():切换当前 Layer 的展开/折叠状态;setExpandedState(expanded):显式设置展开状态。
这两组返回值在 useLayer.tsx 中通过 useMemo 生成,并依赖 wrapConnectorHooks 包装内部连接器。
8.5 自定义渲染组件
官方文档(site/docs/additional/layers.md)提供了可直接扩展的默认组件链:<DefaultLayer /> → <DefaultLayerHeader /> → <EditableLayerName>。其中 EditableLayerName 允许最终用户双击重命名图层,值会写入对应 Node 的 custom.displayName(实现见 EditableLayerName.tsx,通过 actions.setCustom(id, custom => custom.displayName = ...) 持久化)。
自定义示例:
const Layer = () => {
return (
<div>
<DefaultLayerHeader />
</div>
);
};
const App = () => {
return (
<Editor>
<Frame>
...
</Frame>
<Layers renderLayer={Layer} />
</Editor>
);
};
默认 header 还内置了隐藏切换按钮(眼睛图标,点击调用 actions.setHidden(id, !hidden))与顶层 Canvas 指示器(Linked 图标,当 query.node(id).isTopLevelCanvas() 为真时渲染),见 DefaultLayerHeader.tsx。这些组件均可作为自定义 Layer 的参照或子组件复用。
九、结语
从 0.2.1 到 0.2.7,@craftjs/layers 的每一次 Patch 都对应可回溯的源码改动:React 19 与 styled-components 6 的支持扩大了集成面;removeHoverOnMouseleave 让 hover 交互更可控;typings 与 sourcemap 修复保证了 TypeScript 与调试体验;chevron 旋转优化则体现 UI 细节的持续打磨。对于正在集成该面板的开发者,建议以 0.2.7 为基准,并对照 packages/layers/CHANGELOG.md 与本文给出的源码路径逐项验证依赖版本,即可在 Craft.js 编辑器中获得稳定、可定制的图层面板能力。
