Craft.js 图层面板完全指南:使用 @craftjs/layers 构建 Photoshop 式节点管理界面

原创2026-09-24 13:11:501,884 阅读
文章标签:前端

Craft.js 图层面板完全指南:使用 @craftjs/layers 构建 Photoshop 式节点管理界面

导读

@craftjs/layers 是 Craft.js 官方提供的图层管理扩展包,为页面编辑器带来类似 Photoshop 的图层面板体验:以树状结构展示编辑器中的全部节点,支持悬停高亮、点击选中、拖拽重排、展开/折叠,以及直接双击重命名图层。本文以 packages/layers/README.md 为骨架,结合 packages/layers/src 的源码实现与 site/docs/additional/layers.md 官方 API 文档,完整讲解安装接入、<Layers /> 配置、useLayer Hook、自定义渲染组件与底层状态机原理,读完即可在自己的 Craft.js 编辑器中落地一个可用的图层面板。

Craft.js 图层面板实际交互演示,包含树状图层列表、选中高亮与拖拽移动

什么是 @craftjs/layers

@craftjs/layers 是 Craft.js 生态中面向“页面编辑器”场景的图层面板组件(见 packages/layers/package.json 中的描述 “A Photoshop-like layers panel for your page editor”)。它本身不依赖任何第三方 UI 库,只要求宿主环境提供 styled-components,并且以 @craftjs/core 的编辑器状态为唯一数据源。

从源码结构看,包内主要分为四块(packages/layers/src):

  • manager/:图层状态管理。LayerManagerProvider 维护一个独立的图层 store,通过 useMethods 暴露 registerLayer、toggleLayer、setLayerEvent、setIndicator 等动作;
  • layers/:图层树的递归渲染。LayerContextProvider 为每个节点建立上下文,LayerNode 递归渲染子树;
  • events/:图层事件体系。LayerHandlers 从核心编辑器事件处理器派生,接管图层的 hover、选中与拖拽;
  • layers/DefaultLayer/:开箱即用的默认渲染组件(含头部、可编辑名称、隐藏按钮)。

安装与基础接入

README 给出的安装命令同时安装 @craftjs/layers 与其 peer 依赖 styled-components:

yarn add @craftjs/layers styled-components

从 packages/layers/package.json 可以看到其依赖约束:@craftjs/core >= 0.2.0、react ^16.8.0 || ^17 || ^18 || ^19、styled-components >= 6.1,运行时还依赖 @craftjs/utils 与 react-contenteditable(后者用于图层名内联编辑)。当前仓库中该包版本为 0.2.7。

接入方式非常简洁——将 <Layers /> 作为 <Editor> 的子组件即可,README 给出了完整示例:

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 /> 会自动以根节点为起点,把整个节点树渲染为图层列表。其入口实现位于 packages/layers/src/index.tsx:内部由 LayerManagerProvider 包裹一个 LayerContextProvider,后者以 ROOT_NODE 作为初始 id、depth = 0 启动整棵树的递归渲染——因此它必须位于 <Editor> 内部,才能通过上下文拿到编辑器 store。

图层数据结构:Layer 与 LayerState

图层面板的每个条目对应一个 Layer 对象(定义见 packages/layers/src/interfaces.tsx):

属性 类型 含义
id NodeId 对应编辑器节点的唯一 id
dom HTMLElement 当前图层整体(含头部与子层)的 DOM,由 layer 连接器绑定
headingDom HTMLElement 当前图层头部(标题栏)的 DOM,由 layerHeader 连接器绑定
expanded boolean 是否展开,控制子层是否可见
event LayerRefEvents 事件标记,包含 selected 与 hovered 两个布尔值

整个图层面板的状态被组织为 LayerState(见 interfaces.tsx):

export type LayerState = {
  layers: Record<NodeId, Layer>;
  events: Record<LayerEvents, NodeId | null> & {
    indicator: LayerIndicator;
  };
  options: LayerOptions;
};

其中 events 记录当前选中/悬停的节点 id,indicator 保存拖拽时的放置指示器(LayerIndicator 在 Indicator 基础上增加了 onCanvas: boolean 标记,用于区分“落在画布内”还是“落在图层列表内”)。这些状态全部由 packages/layers/src/manager/actions.tsx 中的 LayerMethods 操作,例如 setLayerEvent 会在切换选中/悬停目标时自动清理旧目标的标记,setDOM 通过 layer/layerHeader 连接器回填每个图层的 DOM 引用。

配置项:<Layers /> 的 Props

<Layers /> 接收的 props 类型为 Partial<LayerOptions>(见 packages/layers/src/index.tsx),官方文档(site/docs/additional/layers.md)列出的可配置项如下:

Props 类型 说明
expandRootOnLoad? boolean 可选。启用后,加载时根节点默认展开
renderLayer? React.ElementType 可选。指定每个图层条目如何渲染的自定义组件,默认使用 DefaultLayer

expandRootOnLoad 的生效逻辑

该选项在 packages/layers/src/layers/LayerNode.tsx 中生效:组件挂载时会记录 shouldBeExpandedOnLoad = expandRootOnLoad && id === ROOT_NODE,随后在 useEffect 中调用 toggleLayer(id) 展开根节点。值得注意的是,即使不设置该选项,当你在画布中选中某个深层节点时,面板也会自动展开其全部祖先层级——LayerNode 会通过 query.node(selected).ancestors(true).includes(id) 判断当前节点是否为选中节点的祖先(见 LayerNode.tsx),这一联动行为来自 useEditor 对核心编辑器状态的收集。

renderLayer 的默认值

从 packages/layers/src/manager/LayerManagerProvider.tsx 可以看到,store 初始化时 options.renderLayer 的默认值就是 DefaultLayer,外部传入的 options 会通过对象展开覆盖默认值:

options: {
  renderLayer: DefaultLayer,
  ...options,
},

LayerNode 渲染时会用 React.createElement(renderLayer, {}, children) 创建每个图层条目,并把递归生成的下层 LayerContextProvider 作为 children 传入(见 LayerNode.tsx)——因此自定义渲染组件只要负责展示自身,再透传 children 即可保留树形结构。

在自定义组件中读取图层状态:useLayer

useLayer 是图层面板的“组件侧”核心 Hook,用于在自定义渲染组件内获取当前图层的数据与操作能力。官方文档(site/docs/additional/layers.md)给出其完整 API:

参数:collector?: (layer: Layer) => Collected——一个收集函数,从对应的 Layer 对象中挑选需要的状态;返回的收集值变化时组件才会重渲染(底层经由 useCollector 实现,见 packages/layers/src/layers/useLayer.tsx)。

返回值(见 useLayer.tsx):

返回字段 说明
id 当前图层的节点 id
depth 当前图层在树中的深度(根节点为 0)
children 当前节点的后代节点 id 数组(来自核心编辑器的 query.node(id).descendants())
actions.toggleLayer 切换当前图层的展开状态
connectors.layer 绑定到整个图层条目的 DOM,用于选中、悬停、拖拽
connectors.drag 绑定到可拖拽区域(默认是图层头部),用于拖拽重排
connectors.layerHeader 绑定到图层头部 DOM,用于计算放置位置

连接器的绑定方式与核心包一致:在 JSX 的 ref 回调中调用,例如 ref={(dom) => { layer(dom); }}。useLayer 内部通过 wrapConnectorHooks 把 LayerHandlers 中的 layer/drag/layerHeader 三个处理器包装为可绑定形式(见 useLayer.tsx)。

自定义图层渲染与默认组件族

如果默认样式不满足需求,可以通过 renderLayer 传入自定义组件。官方文档给出了最简用法——完全替换条目但复用默认头部:

const Layer = () => {
  return (
    <div>
      <DefaultLayerHeader />
    </div>
  )
}

const App = () => {
  return (
    <Editor>
      <Frame>
        ...
      </Frame>
      <Layers
        renderLayer={Layer}
      />
    </Editor>
  )
}

为了便于二次开发,官方文档声明了以下可复用组件(导出自 packages/layers/src/layers/index.ts):

  • <DefaultLayer />:完整图层条目,内部包含头部与子层容器。它通过 useLayer 收集 hovered/expanded 状态,并通过 query.node(id).isParentOfTopLevelNodes() 判断自己是否是顶层画布的直接父级(hasChildCanvases),据此决定子层容器的缩进、圆角卡片样式与左侧连接线(见 packages/layers/src/layers/DefaultLayer/DefaultLayer.tsx);
  • <DefaultLayerHeader />:图层头部,自左向右依次是“隐藏/显示”眼睛图标、顶层画布链接指示图标、可编辑名称、展开箭头(见 packages/layers/src/layers/DefaultLayer/DefaultLayerHeader.tsx)。眼睛图标读取节点的 data.hidden 并调用核心动作 actions.setHidden(id, !hidden) 切换画布内元素的可见性;顶层链接指示图标(Linked svg)仅在 query.node(id).isTopLevelCanvas() 为真时显示;
  • <EditableLayerName>:内联编辑组件。用户双击名称后进入编辑态(基于 react-contenteditable),输入内容通过核心动作 actions.setCustom(id, (custom) => custom.displayName = e.target.value) 持久化到节点数据的 custom.displayName 字段(见 packages/layers/src/layers/DefaultLayer/EditableLayerName.tsx),点击组件外部自动退出编辑。setCustom 对应的核心实现在 packages/core/src/editor/actions.ts 附近。

底层原理:事件派生与拖拽放置

图层面板并非独立子系统,而是深度复用了核心编辑器的事件机制。LayerEventContextProvider 通过 useEventHandler() 取得核心事件处理器,再调用 coreEventHandler.derive(LayerHandlers, { layerStore }) 派生出图层专用处理器(见 packages/layers/src/events/LayerEventContextProvider.tsx)。

LayerHandlers(packages/layers/src/events/LayerHandlers.ts)提供了三个连接器:

  • layer:绑定整个条目。内部通过 this.inherit(...) 继承核心的 select、hover、drag 能力,并额外监听 mouseover/mouseleave 来写入 setLayerEvent('hovered', ...);同时监听 dragover/dragenter,借助核心查询 editorStore.query.getDropPlaceholder(dragId, target, pos, nodesToDOM) 计算精确的放置位置(getDropPlaceholder 的核心实现见 packages/core/src/editor/query.tsx),其中 nodesToDOM 回调把节点映射为图层 DOM,从而让画布上的放置计算也能复用图层布局;还会识别“悬停在折叠的 Canvas 头部上下 10px 内”的情况,把放置位置自动提升到父级 Canvas(见 LayerHandlers.ts);
  • layerHeader:绑定头部 DOM 并写入 headingDom,供指示器定位;
  • drag:设置 draggable="true",在 dragstart 记录被拖节点,在 dragend 时若无错误则执行核心动作 editorStore.actions.move(draggedElement, parentId, index + (where === 'after' ? 1 : 0)) 完成重排(见 LayerHandlers.ts)。

拖拽过程中,RenderLayerIndicator(packages/layers/src/events/RenderLayerIndicator.tsx)会读取图层 store 的 events.indicator,根据 onCanvas 标记分两种情况渲染:落在画布内时高亮目标图层整个头部区域(边框样式),落在列表内时在插入位置绘制一条 2px 的横线。颜色取自核心编辑器的 query.getOptions() 中的 indicator.success / indicator.error(即核心包 indicator 选项),错误时显示为错误色;LayerIndicator 组件也直接使用 useEditor 的 state.options.indicator 读取同款颜色(见 packages/layers/src/layers/LayerIndicator.tsx)。

小结

@craftjs/layers 的价值在于把“节点树的展示与操作”从画布内抽象出来:接入只需一步安装、一个组件;扩展则围绕 renderLayer、useLayer 与默认组件族展开;而选中联动、拖拽重排、放置指示等交互能力全部由 LayerHandlers 派生自核心事件系统,保证图层面板与画布编辑状态始终同步。对于需要层级管理、批量结构调整或“大纲视图”的 Craft.js 编辑器而言,这是官方推荐且实现完整的现成方案。

登录后查看全文
craft.js