OpenPencil 选择与变换完全指南:对象选中、移动、缩放、旋转与图层排序的源码级解析

原创2026-10-08 20:22:491,951 阅读
文章标签:桌面应用开发工具前端人工智能AI 应用MCP 服务代码生成CLI插件系统

OpenPencil 选择与变换完全指南:对象选中、移动、缩放、旋转与图层排序的源码级解析

在 OpenPencil(开源 Figma 替代设计工具)中,画布上的一切编辑操作都始于选择,并围绕**变换(transform)**展开:你可以对选中对象进行移动、缩放、旋转、复制、删除与图层排序。本文以官方用户指南 selection-and-manipulation.md(及其意大利文版 packages/docs/it/user-guide/selection-and-manipulation.md)为骨架,结合 core 包与编辑器前端的真实源码与测试,完整讲解每一类操作的交互规则、快捷键映射与底层实现,让你既能立刻上手,也能深入理解 OpenPencil 的场景图编辑机制。

选择(Selection):从单击到框选、全选

对象被选中之后才能被移动、缩放、旋转、复制与重新排序。OpenPencil 提供与 Figma 一致的多层次选择方式:

  • 单击一个对象:替换当前选择(取消选中其他所有对象)。与 Figma 一致,单击顶层 frame 内部,选中的是该 frame 的直接子节点(如嵌套的 frame 或 group),而不是最深层图层;单击顶层 frame 的标题、空白区域、或(开启 auto layout 时)其间距与 padding 区域,才选中该 frame 本身。
  • 双击:向下一层进入;或在已选中的 frame、组件、实例内部再次单击,从而选中其子层;一旦某个图层被选中,后续单击可直接命中它的兄弟与堂兄弟图层。
  • ⌘ + 单击(Windows/Linux 为 Ctrl + 单击):直接选中光标下的最深层图层,跳过中间的嵌套层级。
  • Shift + 单击:将对象加入或移出当前选择(多选的基础)。
  • 拖拽框选(marquee):在空白画布上拖拽画出选择矩形,松开鼠标时,与矩形相交的节点被选中。若在无 auto layout 的顶层 frame 或 section 内部开始拖拽,则选中该容器内的图层;若从页面空白处开始,则只有被矩形完全包含的 frame/section 才会被选中。框选的绘制由画布覆盖层完成——drawMarquee 在 packages/core/src/canvas/overlays/feedback.ts 中根据缩放与平移将 marquee 矩形投射到屏幕坐标。
  • ⌘A(Windows/Linux 为 Ctrl + A):选中当前页面的全部对象。
  • 单击空白画布:取消所有选择。

与选择相关的视图状态(selectedIds、hoveredNodeId、marquee 等)集中维护在编辑器的 pane 状态中,见 src/app/editor/panes/state.ts:每次克隆画布 pane 时都会重置 selectedIds、marquee、dropTargetId、rotationPreview、snapGuides、autoLayoutHover 等交互现场。悬停 auto layout frame 时,其直接子节点会以虚线轮廓描出;当只选中单个图层时,其 auto layout 父级的边框会显示为虚线——这些视觉反馈在交互层持续更新。

移动(Moving):拖拽、微调与修饰键

移动是所有变换操作中最频繁的一种:

  • 拖拽一个选中对象即可移动,多个选中对象会一起移动。
  • 方向键:按 1 px 微调选中对象。
  • Shift + 方向键:按 10 px 大步微调。
  • Shift + 拖拽:将移动锁定在单一轴(水平或垂直)。
  • 拖拽时按住 Space:保持节点在当前父容器中,不被拖入其他 frame(见下文重父级规则)。
  • ⌃ + 拖拽(Windows/Linux 为 Ctrl + 拖拽):关闭吸附;若被放入 auto layout frame,节点会以绝对定位(ABSOLUTE)方式放置。

微调在 core 层有独立的 nudgeSelected 动作,其行为被 packages/core/tests/editor/nudge.test.ts 完整覆盖:

  • 1 px 微调精确写入节点坐标(x: 100 → 101);
  • Shift 10 px 微调同样由 nudgeSelected(10, 0) 实现;
  • 连续多次微调通过 flushNudge() 合并为单条 undo 记录,一次 undo() 即可回退整段连续移动;
  • 锁定(locked)节点会被跳过——即使混在选择里,锁定的节点原地不动(对应文档中“锁定节点在选择中保持不动”的规则);
  • 无选择时微调不产生任何操作,也不会污染 undo 历史。

拖入与拖出 Frame(重父级行为)

移动对象到另一个 frame 上时,OpenPencil 有一套可预测的重父级(reparent)规则,官方指南的描述如下:

  • 松手时,只要对象有一小部分在光标下的 frame 内,它就会被放入该 frame;一旦光标完全离开某个 frame,它就会脱离该 frame。
  • group 和锁定(locked)的 frame 从不接收被拖放的节点;component set 只回收属于它自己的变体。
  • 位于 group 内的节点会一直留在该 group 中,除非你把它放到另一个 frame 上;group 会随之自动调整大小以适配内容。当 group 的最后一个节点被移走时,该 group 会被删除。
  • 在已选中的 frame、group 或 component set 内部按下并拖拽,拖动的是容器本身而非光标下的子节点。

重父级与重新排序在 core 层由 packages/core/src/editor/structure/reorder.ts 实现:跨父级移动时,先通过绝对坐标换算子节点的相对偏移(getAbsolutePosition 差值),再调用 reorderChild 并把改动记入 undo(支持 forward/inverse 双向回放);对于 auto layout 父容器,移动会触发 computeLayout 重新布局。这解释了为什么拖入 auto layout frame 后节点会参与自动排版,而按住 Ctrl 拖入的节点则被绝对定位。

缩放(Resizing):八个手柄与等比约束

选中对象后,其定界框四周会出现八个缩放手柄(4 个角点 + 4 条边中点),拖拽任意手柄即可改变宽高:

  • 拖拽角点手柄时按住 Shift:保持宽高比(等比缩放);
  • 手柄交互与旋转预览、吸附参考线(snapGuides)等状态一同由编辑器视图状态驱动,相关状态字段见 src/app/editor/panes/state.ts。

旋转(Rotating):旋转光标与 15° 吸附

  • 将指针移到某个角点手柄外侧,直到出现旋转光标,再拖拽即可旋转对象。
  • 按住 Shift 拖拽:旋转角度吸附到 15° 的整数倍。

旋转动作在 core 层由 packages/core/src/editor/alignment/flip-rotate.ts 的 rotateNodes 实现:它读取节点的 rotation 字段,以 (((rotation + degrees) % 360) + 360) % 360 的方式归一化到 <a href="https://link.gitcode.com/i/8abecdfbaf18d4d401d871b0c48acff0" target="_blank">0, 360),并将操作记录为可 undo/redo 的单条历史(标签为 Rotate)。同一文件中的 flipNodes 则负责水平/垂直翻转(flipX / flipY 切换)。此外,[packages/core/src/editor/alignment.ts 还导出 alignNodes、distributeNodes 等对齐分发辅助,供属性面板的布局工具调用。

复制(Duplicating):拖拽复制与原地复制

  • Alt + 拖拽(Mac 为 ⌥ + 拖拽):创建选中对象的副本并随之移动。
  • ⌘D(Windows/Linux 为 Ctrl + D):在原地复制;孤立的顶层 frame(在页面或 section 中)的副本会被放置到其右侧的第一个空白区域。

需要注意的两个细节:

  • 副本保留原名称;
  • 以这种方式复制主组件(main component)时,得到的是它的实例(instance),而不是普通节点。

粘贴(Pasting):保持位置

  • ⌘V(Windows/Linux 为 Ctrl + V):粘贴时保持复制时的坐标位置。
  • 粘贴进选中的 frame 时,节点保持与源 frame 的相对偏移;在放不下的轴上自动居中;会超出视口的节点则在视口内居中。
  • 如果想要在光标位置粘贴,请使用右键菜单中的 Paste here(详见 上下文菜单)。

删除(Deleting)

按 Backspace(⌫)或 Delete(Canc)删除所有选中对象。快捷键在 src/app/shell/keyboard/registry.ts 中注册,Backspace、Delete 均触发 smartDelete(false),而 Alt + Delete 触发 smartDelete(true)(区分删除方式的变体)。

图层顺序(Z-Order):置顶、置底与逐层移动

改变节点在父容器内的堆叠顺序:

  • ]:置于顶层(兄弟列表顶部);
  • [:置于底层(兄弟列表底部);
  • 菜单中还提供 Bring Forward / Send Backward(逐层移动,对应 ⌘] / ⌘[)。

底层实现位于 packages/core/src/editor/structure/reorder.ts:

  • moveSelectionInZOrder 收集所有选中节点所属的父容器,为每个父容器计算新的子节点顺序;
  • bringToFront / sendToBack 通过重排 childIds 数组把选中节点整体移到末尾/开头,并保持选中节点之间的相对顺序不变;
  • moveAdjacent 实现逐层上移/下移(一次只与一个未选中的邻居交换位置);
  • 每次顺序变化都通过 applyChildOrder 写入 graph 并记录 undo 历史(标签如 Bring to front)。

这些规则有直接的测试佐证:在 packages/core/tests/editor/structure/z-order.test.ts 中,连续选区(B、C)bringForward 后顺序变为 A, D, B, C;非连续选区(A、C)bringToFront 后为 B, D, A, C,验证了相对顺序保持与 undo/redo 回放;同文件还验证了分组(group)会占据顶层图层的位置,undo 后恢复原栈。

可见性与锁定(Visibility & Lock)

  • ⇧⌘H(Windows/Linux 为 Shift + Ctrl + H):切换可见性。隐藏的节点不再渲染,但仍保留在图层面板中(不会删除)。
  • ⇧⌘L(Windows/Linux 为 Shift + Ctrl + L):切换锁定。锁定节点无法在画布上被选中或移动(nudge 测试也验证了锁定节点被微调时原地不动)。

这两个动作在 src/app/shell/keyboard/registry.ts 中作为命令 selection.toggleVisibility / selection.toggleLock 注册,与其他 selection 系列命令(如 selection.flipHorizontal、selection.flipVertical)并列。

移动到其他页面与 Section

  • Move to Page:通过 上下文菜单 可将选中节点移动到另一个页面,节点会被重新挂载到目标页面画布(currentPageId 对应的 canvas)之下。
  • Sections:在绘制、移动或缩放 section 时,它会收纳被其完全覆盖的兄弟节点——即把完全处于区域内的兄弟节点收为子级,这是 section 与普通 frame 的核心区别之一。

完整快捷键速查表

下表汇总了选择与变换相关的全部快捷键(Mac 与 Windows/Linux 对照),亦可在 keyboard-shortcuts.md 中查看完整图例(⌘ = Cmd/ Ctrl,⇧ = Shift,⌥ = Alt/Option,⌃ = Ctrl,⌫ = Backspace):

操作 Mac Windows / Linux
全选 ⌘A Ctrl + A
原地复制 ⌘D Ctrl + D
复制并移动 ⌥ + 拖拽 Alt + 拖拽
沿单轴移动 ⇧ + 拖拽 Shift + 拖拽
保持当前父容器 拖拽时按 Space 拖拽时按 Space
关闭吸附移动 ⌃ + 拖拽 Ctrl + 拖拽
删除 ⌫ / Delete Backspace / Delete
微调 1 px 方向键 方向键
微调 10 px ⇧ + 方向键 Shift + 方向键
置于顶层 ] ]
置于底层 [ [
切换可见性 ⇧⌘H Shift + Ctrl + H
切换锁定 ⇧⌘L Shift + Ctrl + L

实用提示

  • 当对象相互重叠、难以在画布上点选时,使用左侧的 图层面板(Layers & Pages):它以可折叠树形结构展示文档层级,支持拖拽重排、眼睛图标切换可见性、双击重命名,并且面板与画布双向同步选择。
  • 更多动作(分组、创建组件、复制为 SVG/PNG/JSX、Paste here 等)可通过 右键上下文菜单 访问——在节点上右键会先选中它,在空白处右键会清空选择。
  • 若需要让选中对象按自动布局排版,可在属性面板使用 Add auto layout(⇧A),将选择包裹进新的 auto layout frame 中。

小结

OpenPencil 的选择与变换系统以“选中即操作、修饰键控制约束”为设计核心:单击/框选/全选构成选择体系,拖拽与方向键完成移动与微调,Shift 贯穿等比缩放、单轴移动与 15° 旋转吸附,Alt/⌘D 负责复制,]/<a href="https://link.gitcode.com/i/33390e4f9b73432e36375d8f61ef9210" target="_blank"> 与 ⇧⌘H/⇧⌘L 管理层级与状态。在实现层面,这些交互全部落在 core 包的 editor 动作上——nudgeSelected([nudge.test.ts)、reorderChild/bringToFront/sendToBack(reorder.ts)、rotateNodes/flipNodes(flip-rotate.ts)——每一次变换都可被精确记录、合并与回放进 undo 历史,这也正是 OpenPencil 作为 Figma 兼容编辑器的底层保障。

登录后查看全文
open-pencil