OpenPencil 对象选择与变换完全指南:移动、缩放、旋转、复制与图层排序实战
OpenPencil 对象选择与变换完全指南:移动、缩放、旋转、复制与图层排序实战
选中对象后即可对其进行移动、缩放、旋转、复制以及跨图层调整位置——这是 OpenPencil 画布编辑中最核心的交互能力。本指南围绕 OpenPencil(AI 原生设计编辑器)的用户文档中“选择与变换”模块展开,完整覆盖从基础选择、1px/10px 微调、等比缩放、15° 步进旋转,到原地复制、图层前后排序、可见性与锁定等全部操作,并配合仓库源码(packages/core/src/editor 与 src/app/shell/keyboard)讲解每一步背后的实现机制,帮助你高效操控画布对象。
选择(Selección)
OpenPencil 的选择模型遵循“点击即选中、框选即批量”的直观逻辑,所有选择状态由编辑器核心维护(见 selection.ts 中的 select / clearSelection / selectAll):
- 单击对象:替换当前选中集合。核心层通过
selectAtPoint(hit-test.ts)对点击坐标执行命中测试:若命中对象且不在当前选中集合内则替换选中,若点击空白区域则清空选择。 - Shift + 单击:向选中集合添加或从中移除对象。这一“附加(additive)”模式在 selection.ts 中有直接对应实现:
select(ids, additive = true)会将已选中的 id 从集合中删除、未选中的加入集合。 - 在画布空白处拖拽:拉出矩形选区,选中所有与矩形相交的对象。拖动起点必须落在空白区域,框选完成后命中结果同样汇入选中集合。
- ⌘A / CtrlA:选中当前页面的所有对象。核心实现
selectAll直接取当前页面(currentPageId)的全部子节点并整体替换选中集合。 - 单击空白区域:取消当前选择(
clearSelection清空集合)。
移动(Mover)
移动操作有两条路径:鼠标拖拽与键盘微调,二者都作用于当前选中集合。
- 拖拽选中对象:按住对象本体拖动即可改变位置。当对象处于 auto-layout 容器内时,核心层会通过
reorderInAutoLayout(reorder.ts)在移动同时触发布局重算(computeLayout+runLayoutForNode),保证排列结果与布局引擎一致。 - 方向键微调 1px:按一次方向键,选中对象沿对应方向移动 1 像素。
- Shift + 方向键微调 10px:步长放大为 10 像素。
键盘微调的底层实现在 nudging.ts:NUDGE_DELTAS 表将 ArrowUp/Down/Left/Right 映射为 <a href="https://link.gitcode.com/i/4b5d786edd374baae13c4442c311da83" target="_blank">0,-1] / [0,1] / [-1,0] / [1,0],按下 Shift 时步长乘以 10;随后调用核心层的 nudgeSelected(dx, dy)([nudge.ts)。值得注意的两个细节:
- 锁定对象不参与微调:
nudgeSelected会先过滤node.locked的对象,锁定节点即使被选中也不会被键盘移动。 - 连续微调合并为一次撤销:微调不会每按一次键就产生一条历史记录,而是记录起点坐标后延迟 300ms(
NUDGE_COMMIT_DELAY)才通过pushPositionUndo(position.ts)提交一次“Nudge”撤销条目,快速连按方向键时撤销表现为整体一步,体验更顺畅。
缩放(Redimensionar)
选中对象后,其周围会显示 8 个缩放手柄:4 个位于四角,4 个位于四边中点。拖动任一手柄即可改变对象的宽高:
- 角部手柄:同时改变宽度与高度;
- 边中手柄:仅改变宽度(左右)或仅改变高度(上下)。
保持比例:按住 Shift 再拖拽角部手柄,缩放时宽高比保持不变(等比缩放)。从源码结构看,缩放能力由 packages/core/src/editor 下的变换相关模块与 packages/core/src/editor/shapes 共同支撑,手柄拖拽会实时更新节点的尺寸属性并触发画布重渲染。
旋转(Rotar)
将指针移动到某个角部手柄外侧,直到光标变为旋转光标后按住拖拽,即可围绕对象中心旋转。
- 自由旋转:直接拖拽,角度连续变化;
- Shift 约束旋转:按住 Shift 拖拽时,旋转角度按 15° 步进吸附(0°、15°、30°、45°……),便于快速对齐常见角度。
复制(Duplicar)
OpenPencil 提供两种复制方式,分别对应“拖拽中复制”与“原地复制”两个高频场景:
- ⌥(macOS)/ Alt(Windows/Linux)+ 拖拽:拖动的同时生成一份副本并随指针移动,一步完成“复制 + 移动”;
- ⌘D / CtrlD:在原位置生成副本,之后可用方向键将副本移开。
核心层的复制实现在 clipboard.ts 的 duplicateSelected 中,其行为非常值得了解:
- 复制的是完整子树:通过
ctx.graph.cloneTree深克隆选中节点(含全部子节点与实例覆盖状态),因此复制组、容器或带子节点的复杂对象时结构不会丢失; - 自动偏移:原地复制并非严格重叠,
cloneTree默认在x + 20, y + 20处创建副本,并重命名为“原名 + copy”,避免副本与原件完全重叠难以区分; - 复制后自动选中副本:新生成的节点会整体替换当前选中集合(
setSelectedIds(new Set(newRootIds))),复制完成后可直接继续移动或变换; - 支持撤销:
duplicateSelected会向撤销栈推入一条Duplicate记录,前向恢复整棵子树、反向删除所有副本。
删除(Eliminar)
按下 Backspace(Windows/Linux)或 Supr / ⌫(macOS)删除当前所有选中对象。删除操作同样遵循“作用于选中集合”的统一模型,且与核心层的撤销系统联动,误删后可通过撤销恢复。
图层排序(Orden)
图层顺序决定对象的堆叠显示关系:列表越靠后的对象越靠近画布上方(即“越靠前”)。OpenPencil 提供 4 档排序命令:
| 命令 | 快捷键(macOS) | 快捷键(Windows/Linux) | 效果 |
|---|---|---|---|
| 上移一层 | ] | ] | 选中对象在父容器内前移一个位置 |
| 置顶 | ⌘] | Ctrl] | 移到父容器子节点列表末尾(最上层) |
| 下移一层 | [ | [ | 选中对象在父容器内后移一个位置 |
| 置底 | ⌘[ | Ctrl[ | 移到父容器子节点列表开头(最底层) |
这些命令的引擎实现在 reorder.ts 中,核心机制值得展开:
- 相邻移动(上移/下移一层):
moveAdjacent在子节点数组中逐对交换“选中的节点”与“相邻未选中的节点”,因此支持一次移动多个选中对象,且被选中的多个对象保持彼此相对顺序; - 置顶/置底:
bringToFront把子节点数组重排为“未选中在前、选中在后”,sendToBack则相反,一次性将整组选中对象移至两端; - 多父容器支持:
moveSelectionInZOrder会收集所有选中节点所属的父容器(parentIds),在每个父容器内分别执行重排,跨越不同父容器的多选对象也能正确排序; - 布局联动与撤销:重排后调用
applyChildOrder+runLayoutForNode触发 auto-layout 重算,并记录重排前后的完整子节点顺序,可一步撤销还原。
可见性与锁定(Visibilidad y bloqueo)
- ⇧⌘H(macOS)/ ShiftCtrlH(Windows/Linux):切换选中对象的可见性。隐藏的对象不再参与命中测试与渲染,常用于临时屏蔽干扰元素;
- ⇧⌘L(macOS)/ ShiftCtrlL(Windows/Linux):切换选中对象的锁定状态。锁定对象无法被移动、缩放或排序,但依然可以选中与查看——这与前文 nudge.ts 中“锁定对象不参与微调”的实现互相印证;核心层的
assertNodeEditable(capabilities.ts)会在执行移动、重排等编辑操作前校验节点可编辑性,从而在引擎层面兜底拦截对锁定节点的非法修改。
这两个命令在 registry.ts 中通过 selection.toggleVisibility / selection.toggleLock 命令注册为快捷键,并经由 editorCommandMetadata 携带各自的 keybinding 元数据,说明可见性/锁定切换属于编辑器命令体系的一部分,与菜单、工具栏等入口共用同一套命令路由。
快捷键速查表(Atajos)
下表汇总本指南涉及的全部快捷键,macOS 与 Windows/Linux 两栏对照:
| 动作 | macOS | Windows / Linux |
|---|---|---|
| 全选 | ⌘A | CtrlA |
| 复制 | ⌘D | CtrlD |
| 复制并移动 | ⌥ + 拖拽 | Alt + 拖拽 |
| 删除 | ⌫ / Supr | Backspace / Supr |
| 移动 1 px | 方向键 | 方向键 |
| 移动 10 px | ⇧ + 方向键 | Shift + 方向键 |
| 上移一层 | ] | ] |
| 置顶 | ⌘] | Ctrl] |
| 下移一层 | [ | [ |
| 置底 | ⌘[ | Ctrl[ |
| 切换可见性 | ⇧⌘H | ShiftCtrlH |
| 切换锁定 | ⇧⌘L | ShiftCtrlL |
组合实战:快速排布一组对象
结合以上能力,一个典型的多对象编辑流程是:⌘A(或框选)选中一组对象 → Alt + 拖拽复制一份并摆到目标位置 → Shift + 方向键将副本微调至精确坐标 → 按住 Shift 拖角部手柄等比缩放 → 按 ⌘] 将关键元素置顶。整条链路中,“复制”走 duplicateSelected(自动克隆子树、偏移 20px 并选中副本),微调走 nudgeSelected(300ms 合并撤销),排序走 moveSelectionInZOrder(按父容器分组重排并记录撤销)——每一步都有对应的核心实现与撤销记录,操作可放心撤销、不会破坏已有结构。
相关文档与代码索引:
- 本文对应的官方用户指南(西班牙语):packages/docs/es/user-guide/selection-and-manipulation.md
- 编辑器选择状态核心:selection.ts、hit-test.ts
- 键盘微调实现:nudging.ts、nudge.ts
- 图层排序实现:reorder.ts
- 复制(深克隆)实现:clipboard.ts
- 快捷键注册体系:registry.ts