企业官网建设流程全解析

用 registerExternalContentHandler 定制 tldraw 的粘贴行为：实现类 Figma 的画框错位粘贴

【免费下载链接】tldrawBuild infinite canvas apps in React with the tldraw SDK. World's best, top-most agent recommended #1 five star SDK.项目地址: https://gitcode.com/GitHub_Trending/tl/tldraw

导读

默认情况下，tldraw 把一个 tldraw 文档里复制的画框（frame）粘贴回画布时，新副本会与原始画框完全重叠。本篇文章以仓库 apps/examples/src/examples/data/assets/custom-paste 目录下的完整示例为主线，深入讲解如何通过editor.registerExternalContentHandler('tldraw', ...)替换 tldraw 内置的"外部内容处理器"，实现"粘贴的副本落到原始画框右侧的空闲位置、并自动让开路上其他画框"的类 Figma 行为。读完你将掌握 tldraw 外部内容（external content）处理机制的入口、内置默认处理器defaultHandleExternalTldrawContent的实现细节，以及如何用不到 60 行代码优雅地劫持并回退默认粘贴逻辑。

一、问题背景：粘贴副本为什么会叠在原件上

先看示例文档（README.md）给出的核心说明：

Replace the built-in paste handler so a copied frame lands in free space beside the original. Pasted tldraw content goes through the'tldraw'external content handler. This example overrides it witheditor.registerExternalContentHandler('tldraw', ...)to add one rule: when the clipboard holds a single page-level frame, place the pasted copy to the right of the original (and past any other frames in the way), the way Figma does. Everything else falls through todefaultHandleExternalTldrawContent.

它点出了三个关键事实：

1. 从 tldraw 内部复制出来的内容，在粘贴时走的是'tldraw'类型的 external content handler，而不是普通文本、图片或文件粘贴所走的路径；
2. 想让粘贴行为"智能化"，最干净的做法不是自己重写整套粘贴流程，而是注册一个同名处理器覆盖默认行为，只在需要特殊处理的场景接管逻辑，其余一律回退给内置的defaultHandleExternalTldrawContent；
3. 示例想复刻的产品交互是 Figma 的做法：把新副本放到原件右侧的空白处，而不是盖在原件上方。

示例的验证方法也写在 README 里：创建一张画框，然后连续按Cmd + C、Cmd + V几次，每次粘贴出的副本都会依次排到右侧，而不是原地堆叠。

二、前置知识：tldraw 的 external content 处理器机制

2.1 处理器按内容类型注册，粘贴/拖放统一分发

在 tldraw 中，一切"从编辑器外部进入画布的内容"——无论是粘贴的文本、拖入的图片、贴入的 URL、粘贴的 SVG，还是从另一个 tldraw 页面复制来的图形——都会先被抽象为"外部内容（external content）"，然后交给注册在对应type上的处理器。内置的默认注册函数是registerDefaultExternalContentHandlers，位于 packages/tldraw/src/lib/defaultExternalContentHandlers.ts，它一次性注册了这些类型：

其中'tldraw'类型专门服务于"tldraw 文档内部复制的内容"——也就是本示例要拦截的目标。

2.2registerExternalContentHandler的 API 与语义

registerExternalContentHandler是Editor实例上的公开方法，定义在 packages/editor/src/lib/editor/Editor.ts：

registerExternalContentHandler<T extends TLExternalContent<E>['type'], E>( type: T, handler: | null | (( info: T extends TLExternalContent<E>['type'] ? Extract<TLExternalContent<E>, { type: T }> : TLExternalContent<E> ) => void) ): this { this.externalContentHandlers[type] = handler as any return this }

结合其上的文档注释（Editor.ts）可以归纳出三条实用语义：

• 传入null即删除处理器。源码中externalContentHandlers初始映射表里每个类型默认都是null（见 Editor.ts），而registerDefaultExternalContentHandlers在挂载时把默认实现填进去。因此任何一次注册本质上都是"替换当前生效的实现"，这一机制为覆盖默认行为提供了直接入口。
• 泛型对 handler 做类型推导。例如registerExternalContentHandler<'embed', MyEmbedType>('embed', myHandler)这种形式可以针对自定义的 embed 类型传附加泛型参数；对本示例而言，'tldraw'对应载荷类型为TLTldrawExternalContent（即{ type: 'tldraw'; point?: VecLike; content: TLContent }这类结构）。
• 返回this，可以链式调用，便于在onMount中一次性注册多个类型。

示例代码（CustomPasteExample.tsx）的注册方式即是在<Tldraw onMount={...}>回调中完成的：

export default function CustomPasteExample() { return ( <div className="tldraw__editor"> <Tldraw onMount={(editor) => { // [1] editor.registerExternalContentHandler('tldraw', (content) => handleCustomTldrawPaste(editor, content) ) }} /> </div> ) }

文件底部注释对[1]的解释是：

registerExternalContentHandlerreplaces the handler for a content type.'tldraw'is the type used for content copied from tldraw itself, so this intercepts every internal paste.defaultHandleExternalTldrawContentis the built-in handler, which we fall back to for anything we don't want to special-case.

即：因为'tldraw'就是 tldraw 内部复制内容使用的类型，注册后会拦截每一次内部粘贴；而defaultHandleExternalTldrawContent则是内置处理器，作为我们不想特判情况下的兜底出口。

2.3 配套的"回退"出口：内置默认处理器做了什么

defaultHandleExternalTldrawContent的完整实现位于 packages/tldraw/src/lib/defaultExternalContentHandlers.ts。它本身就是一个很有参考价值的"标准粘贴流水线"，概括如下：

1. 在editor.run()事务中执行，并调用editor.markHistoryStoppingPoint('paste')把历史记录切出一个"粘贴"断点，便于用户一次undo撤销整批粘贴；
2. 解锁锁定的根图形：遍历content.shapes，凡属于rootShapeIds的根图形，粘贴时把isLocked置为false，否则锁定的图形粘贴后会无法操作；
3. 识别"交互中途粘贴"：通过editor.isInAny('select.dragging_handle', 'select.translating', 'select.resizing', 'select.rotating')判断用户是否正处在拖拽手柄、平移、缩放或旋转的中途。若在交互中途粘贴，不抢走选区（否则会打断正在进行的图形操作，例如箭头吸附的提示会消失），此时select: false；
4. 落位：调用editor.putContentOntoCurrentPage(content, { point, select: !isMidInteraction })，把剪贴板内容放到当前页。注意point参数——当粘贴带有明确的落点（例如右键菜单触发的"粘贴到此处"）时，内容会落在point指定的位置；示例正是抓住这一点来判断"是否为普通键盘粘贴"；
5. 重叠提示：若粘贴前后的选区边界发生碰撞（selectionBoundsBefore?.collides(selectedBoundsAfter)），则通过updateInstanceState({ isChangingStyle: true })触发一个短暂的 "puff" 视觉反馈（150ms 后复位），提示"内容已粘贴"，见 defaultExternalContentHandlers.ts。

理解这条内置流水线，是理解示例设计的关键：示例并没有重写"粘贴"本身，而是先让默认处理器完成真正的粘贴与选中，再对选中的新副本做位移修正。

三、核心实现逐段剖析

handleCustomTldrawPaste是示例的全部业务逻辑，位于 CustomPasteExample.tsx。先看完整代码：

const SPACING_BETWEEN_FRAMES = 50 function handleCustomTldrawPaste(editor: Editor, { content, point }: TLTldrawExternalContent) { // [2] const onlyCopiedShape = content.rootShapeIds.length === 1 ? content.shapes.find((shape) => shape.id === content.rootShapeIds[0]) : null const onlyCopiedFrame = onlyCopiedShape?.type === 'frame' ? (onlyCopiedShape as TLFrameShape) : null // only use the special behavior if the frame will be a direct child of the page (its // parentId isn't a shape in the document) const willPasteOnCurrentPage = onlyCopiedFrame ? !editor.getShape(onlyCopiedFrame.parentId) : false // [3] if (point || !onlyCopiedFrame || !willPasteOnCurrentPage) { defaultHandleExternalTldrawContent(editor, { content, point }) return } // [4] editor.putContentOntoCurrentPage(content, { select: true }) const newlyPastedFrame = editor.getOnlySelectedShape() if (!newlyPastedFrame || !editor.isShapeOfType(newlyPastedFrame, 'frame')) return const siblingIds = editor.getSortedChildIdsForParent(newlyPastedFrame.parentId) const pastedBounds = editor.getShapePageBounds(newlyPastedFrame.id)! let targetPosition = pastedBounds.minX const siblingBounds = siblingIds .map((id) => ({ id, bounds: editor.getShapePageBounds(id)! })) .sort((a, b) => a.bounds.minX - b.bounds.minX) for (const sibling of siblingBounds) { if (sibling.id === newlyPastedFrame.id) continue // if this sibling is above or below the copied frame, we don't need to take it into account if (sibling.bounds.minY > pastedBounds.maxY || sibling.bounds.maxY < pastedBounds.minY) continue // if the sibling is to the left of the copied frame, we don't need to take it into account if (sibling.bounds.maxX < targetPosition) continue // if the sibling is to the right of where the pasted frame would end up, we don't care about it if (sibling.bounds.minX > targetPosition + pastedBounds.w) continue // otherwise, we need to shift our target right edge to the right of this sibling targetPosition = sibling.bounds.maxX + SPACING_BETWEEN_FRAMES } editor.nudgeShapes([newlyPastedFrame.id], { x: targetPosition - pastedBounds.minX, y: 0, }) }

代码刻意做了"先判型、再落位、后平移"的三段式设计，下面按底部注释的[2]–[4]编号逐段解读。

3.1[2]判定：剪贴板里是否恰好是一张独立的画框

注释原文是：

Work out whether the clipboard holds exactly one root shape and that shape is a frame.

TLContent中，rootShapeIds表示剪贴板内容的根图形（顶层图形）集合，shapes是包含嵌套子图形在内的全部图形数组。判定逻辑分两步：

• 第一步先判断content.rootShapeIds.length === 1，即剪贴板中只有一个根图形，并在shapes中按根图形 id 找到它，得到onlyCopiedShape。若剪贴板里同时复制了多张画框或其他图形，直接不满足"单画框"条件；
• 第二步判断该图形的type === 'frame'，确认它确实是一张 frame 画框，得到onlyCopiedFrame；
• 第三步willPasteOnCurrentPage用!editor.getShape(onlyCopiedFrame.parentId)判断该画框的父级是页面本身还是另一个图形。这里getShape查的是"当前文档中是否存在这个父图形"——若原画框嵌套在另一个画框/编组内部，那么parentId对应的是一个真实存在的 shape，willPasteOnCurrentPage为false；只有当画框是页面的直接子级（其父级不是文档里的任何 shape）时，才走特殊逻辑。这也与注释 "only use the special behavior if the frame will be a direct child of the page" 完全对应。

3.2[3]回退：三种情况一律走默认行为

注释原文是：

If the paste has an explicitpoint(for example, a paste from the context menu, which lands at the pointer), or it isn't a lone page-level frame, use the default behavior.

if (point || !onlyCopiedFrame || !willPasteOnCurrentPage) { defaultHandleExternalTldrawContent(editor, { content, point }) return }

三个回退条件分别是：

注意这里回退时依然把原参数{ content, point }原样交给默认处理器，因此默认行为完全不受影响——这也正是registerExternalContentHandler覆盖模式的精髓：只拦截需要的子集，其余 100% 透传。

3.3[4]落位与避让：先按默认位置粘贴，再向右扫过重叠兄弟

注释原文是：

Paste with the default handler first, then walk the frame's siblings from left to right and slide the new frame past any that overlap it vertically, leaving a gap.

策略上有一个精妙的取舍：先调用editor.putContentOntoCurrentPage(content, { select: true })完成真正的粘贴，让新副本落到与原件相同的位置并自动选中；紧接着用editor.getOnlySelectedShape()拿到刚粘贴出来的那一个图形（因为select: true，且剪贴板只有一个根图形），再用editor.isShapeOfType(newlyPastedFrame, 'frame')做一次保险校验。

接下来是避让算法，它是整个示例的智力核心，可以拆成四个步骤：

① 收集同一父容器下的兄弟并排序

const siblingIds = editor.getSortedChildIdsForParent(newlyPastedFrame.parentId)

getSortedChildIdsForParent返回父容器内按索引排序的子图形 id（画框是页面直接子级，这里拿到的就是页面上所有顶层图形）。随后：

const siblingBounds = siblingIds .map((id) => ({ id, bounds: editor.getShapePageBounds(id)! })) .sort((a, b) => a.bounds.minX - b.bounds.minX)

用getShapePageBounds取每个兄弟的页面坐标包围盒，并按minX（左边缘）从左到右排序——这样后续扫描天然是从原件方向向右推进。

② 只关心与新副本有垂直重叠的兄弟

if (sibling.bounds.minY > pastedBounds.maxY || sibling.bounds.maxY < pastedBounds.minY) continue

若某兄弟完全位于新副本的上方或下方（垂直范围无交集），说明它不会挡路，直接跳过。这个判断让"右移"只在画框水平带内起作用，不会被页面上其他行、其他区域的图形干扰。

③ 只关心会撞上新副本的兄弟

if (sibling.bounds.maxX < targetPosition) continue // 完全在目标位置左侧，已让开 if (sibling.bounds.minX > targetPosition + pastedBounds.w) continue // 在新副本右边缘更右侧，不冲突

两个条件分别剔除"已经在新副本目标位置的左边"与"在新副本右边缘更右边"的兄弟——它们都不会与待放置的副本产生水平碰撞。

④ 需要避让时，把目标左边缘推到该兄弟右侧并留出间距

targetPosition = sibling.bounds.maxX + SPACING_BETWEEN_FRAMES

一旦某兄弟同时通过 ②③ 两道筛选（即垂直重叠、水平范围内），就把目标位置推到它的右边缘之外，并额外加上SPACING_BETWEEN_FRAMES = 50的间距。因为兄弟已按minX升序排列，这个循环天然实现"遇到一个挡路的就右移，再看下一个"，等价于把新副本依次让过所有挡路画框。

最后用nudgeShapes把刚粘贴出的副本沿 x 轴平移：

editor.nudgeShapes([newlyPastedFrame.id], { x: targetPosition - pastedBounds.minX, y: 0, })

位移量是新目标位置与当前落位的差值，y 方向保持为 0——即新副本只在水平方向移动，与原件保持同一垂直高度。

targetPosition的初值是pastedBounds.minX，因此当没有任何兄弟挡路时，位移量为 0，副本留在原地；但注意此时原件与副本位置相同——第一次粘贴会重叠吗？这正是示例有意思的地方：连续Cmd+C/Cmd+V多次时，第一次粘贴的副本仍叠在原件上，但它是"当前被选中的"、位于原件之上；第二次粘贴时，之前的副本已经作为一个兄弟存在，新副本会右移到它右侧 50px，从而逐渐排成一行。每次粘贴后新副本都处于选中态，便于继续操作。

四、边界行为与设计取舍

从源码可以提炼出这个示例在哪些边界上"刻意不做特殊处理"，这些取舍本身就是很好的设计参考：

• 带point的粘贴一律放行默认行为（右键菜单粘贴、API 指定落点的场景），保证"用户指哪打哪"的语义不被破坏；
• 只处理页面直接子级的画框：嵌套在父画框或编组中的画框、多选复制、文本复制都走默认逻辑。示例判断父级是否为"文档里的真实图形"而非父级类型是否为页面，写法上直接复用了getShape的存在性判断，简洁且稳健；
• 避让计算以页面包围盒为准（getShapePageBounds），自动考虑了形状的旋转、缩放对实际占用区域的贡献；而排序与推进都只看 x 轴，保证最终只产生水平位移；
• 间距常量SPACING_BETWEEN_FRAMES = 50是可调参数。把它独立提取为常量，是示例特意留给使用者的扩展点——想要更紧凑或更疏朗的排布，只需调整这一个值。

仓库测试代码也为这套覆盖模式提供了佐证：例如 packages/tldraw/src/test/commands/clipboardPaste.test.ts 在测试内部直接调用editor.registerExternalContentHandler('files', ...)来替换某类内容的粘贴实现；packages/editor/src/lib/editor/Editor.test.ts 也通过注册'text'的 mock 处理器来验证外部内容处理流程。这印证了"注册覆盖 + 回退默认"是 tldraw 生态中针对粘贴/外部内容的标准定制套路。

五、运行与验证

示例归属于仓库的 examples 工程目录（apps/examples），可按该目录 README 的方式启动示例应用，打开data / assets / custom-paste对应的示例页。验证步骤：

1. 在画布上用画框工具创建一张 frame（或直接绘制若干图形后用Shift把它们变成画框内的内容）；
2. 选中这张画框，按下Cmd + C；
3. 连续按下若干次Cmd + V；
4. 观察粘贴出的副本：默认情况下第一次粘贴会落在原件上并处于选中态，随后每次粘贴的新副本都会依次排到已有画框的右侧、留出 50px 空隙，最终形成一行水平排列的画框，行为与 Figma 一致。

若想验证回退分支，可以用右键菜单粘贴（此时携带point），新副本会落在指针位置而非被右移。

六、扩展思路：把这个模式推广到更多粘贴场景

示例展示的"注册'tldraw'处理器 + 条件分支 + 回退defaultHandleExternalTldrawContent"是一个可复用的骨架，按同样的思路还可以定制：

• 多张画框的网格化粘贴：把"单个根图形"改为"根图形数组"，在粘贴后按行列把每个根图形错开摆放；
• 嵌套画框的粘贴去重：对非页面级副本先提升（detach）到页面层级再避让，或调用editor.bringForward等层次 API 处理遮挡；
• 其他内容类型的定制：参考registerDefaultExternalContentHandlers的注册表（defaultExternalContentHandlers.ts），你可以同样覆盖'text'、'files'、'svg-text'、'excalidraw'等类型，例如"粘贴的图片自动落到某个固定区域"或"粘贴的文本自动拆成列表"；
• 移除某类默认处理：直接传null，如editor.registerExternalContentHandler('files', null)，可完全禁用某类外部内容的默认处理（需自行承担后续行为变化）。

关键约束始终是两条：只有'tldraw'类型会命中 tldraw 文档内部的复制粘贴；对自己不关心的分支，务必原样回退给defaultHandleExternalTldrawContent，以免破坏编辑器默认能力。

小结

这个示例虽然短小，却是理解 tldraw 外部内容处理机制的最佳切片：从registerExternalContentHandler的注册与覆盖语义、defaultHandleExternalTldrawContent内置流水线中的历史断点/解锁/选中/重叠反馈设计，到"先判型回退、再粘贴、后按包围盒避让平移"的实现策略，一层层展示出 SDK 在可定制性与默认行为完整性之间的平衡。全文核心代码与配套说明可直接在仓库中查阅：

• 示例 README：apps/examples/src/examples/data/assets/custom-paste/README.md
• 示例源码：apps/examples/src/examples/data/assets/custom-paste/CustomPasteExample.tsx
• 默认外部内容处理器（含'tldraw'默认实现）：packages/tldraw/src/lib/defaultExternalContentHandlers.ts
• registerExternalContentHandler定义： packages/editor/src/lib/editor/Editor.ts

【免费下载链接】tldrawBuild infinite canvas apps in React with the tldraw SDK. World's best, top-most agent recommended #1 five star SDK.项目地址: https://gitcode.com/GitHub_Trending/tl/tldraw