tldraw 精确箭头绑定完全指南：用 `ArrowShapeUtil.configure` 让精确箭头始终“刺入”目标图形内部

tldraw 的箭头工具在绘制时会自动检测可绑定的目标图形，并根据鼠标停留的精细程度决定箭头的停靠位置。本文以仓库中 arrows-precise-exact 官方示例为线索，深入讲解 tldraw 箭头绑定中「不精确（imprecise）/ 精确（precise）/ 精确且深入（exact）」三层状态的区别，以及如何通过 ArrowShapeUtil.configure({ shouldBeExact }) 自定义箭头端点的吸附行为，让每个精确箭头自动深入目标图形内部、直达绑定点，彻底摆脱对 Alt 键的依赖。

为什么需要阅读本文

在 tldraw 中绘制连接线（箭头）时，绝大多数用户只会下意识地使用默认行为，却不知道箭头与图形之间的吸附深度完全可以通过 SDK 暴露的配置项自定义。如果你的产品需要更强调"端点要实实在在扎进卡片里"，而不是停在卡片边缘，就需要理解并覆盖 ArrowShapeUtil 的 shouldBeExact 选项。本文结合源码逐层拆解其判定链路，并提供可直接复制运行的 React 代码。

三个核心概念：imprecise、precise 与 exact

在 arrows-precise-exact 示例的 README 中，官方首先定义了三个容易混淆的概念：

• 不精确（imprecise）箭头：绑定到目标图形时，箭头指向图形的中心。
• 精确（precise）箭头：箭头指向目标图形内部的某个具体点。
• 精确且深入（exact）箭头：在精确的基础上更进一步——箭头不再停在图形的边缘，而是穿过边缘、一直延伸到被绑定的那个具体点（即"深入图形内部到底"）。

需要说明的是，精确与否描述的是“吸附对象是中心还是具体点”，而 exact 描述的是“端点是否穿透边缘抵达绑定点”。

默认行为

tldraw 的默认交互约定如下：

场景	结果
慢速悬停在目标图形上方	箭头变为精确（precise）
在已精确的基础上按住 Alt 键	箭头再变为 exact（深入图形）
不按任何修饰键快速拖动	箭头保持不精确，指向图形中心

也就是说，默认情况下“exact”需要同时满足“慢速悬停/精确瞄准 + 按住 Alt” 这两个条件。这对很多用户并不直观，也增加了记忆负担。

如何让所有精确箭头都自动 exact

ArrowShapeUtil 提供的 shouldBeExact 配置项，接收 editor 实例 与 当前绑定是否精确（isPrecise） 两个参数，并返回一个布尔值决定该绑定是否应同时设为 exact。示例中的实现最为直白：

const shapeUtils = [
	ArrowShapeUtil.configure({
		shouldBeExact: (editor, isPrecise) => isPrecise,
	}),
]

这段代码的逻辑是：只要箭头已经精确（isPrecise 为 true），就无条件让它 exact。于是“按住 Alt”这个额外步骤被完全省略——只要慢速悬停命中，箭头尖端就一定会没入图形内部，直达绑定点，而不是停在图形边缘。

完整的可运行组件如下，来自 ArrowsPreciseExactExample.tsx：

import { ArrowShapeUtil, Tldraw } from 'tldraw'
import 'tldraw/tldraw.css'

const shapeUtils = [
	ArrowShapeUtil.configure({
		shouldBeExact: (editor, isPrecise) => isPrecise,
	}),
]

export default function ArrowsPreciseExactExample() {
	return (
		<div className="tldraw__editor">
			<Tldraw shapeUtils={shapeUtils} />
		</div>
	)
}

体验要点：向一个图形内绘制箭头，在松开鼠标前稍作停顿。由于悬停停顿会让绑定进入精确状态，此时松手你会发现箭头尖端已经落在图形内部，而不再停在图形的边缘。这正是 shouldBeExact 返回 isPrecise 后的直接效果。

configure 与 shapeUtils：如何把配置注入编辑器

从上面代码可以看到，配置箭头行为走的是两层结构：

1. ArrowShapeUtil.configure({...})：克隆默认的 ArrowShapeUtil，并用传入的部分配置项覆盖原有 options，返回一个定制版的 shape util 类；
2. <Tldraw shapeUtils={shapeUtils} />：把定制后的 util 数组传入 Tldraw 组件，替换掉默认的箭头工具实现。

这是 tldraw SDK 中所有内置工具自定义的统一入口模式（ArrowShapeUtil 是一个静态类，configure 由框架提供并作用于其 options 字段）。在 ArrowShapeUtil.tsx 中可以看到该 util 的完整默认 options：

static override type = 'arrow' as const

override options: ArrowShapeOptions = {
	// ...（肘形/弧形箭头吸附距离等参数）
	hoverPreciseTimeout: 600,      // 悬停多久后判定为精确，单位毫秒
	pointingPreciseTimeout: 320,   // 按住拖动端点时多久判定为精确
	shouldBeExact(editor: Editor) {
		return editor.inputs.getAltKey()   // 默认：按下 Alt 才 exact
	},
	shouldIgnoreTargets(editor: Editor) {
		return editor.inputs.getCtrlKey()  // 默认：按下 Ctrl 忽略所有吸附目标
	},
	// ...
}

也就是说，默认的 shouldBeExact 本质上等价于 (editor) => editor.inputs.getAltKey()，精确状态本身并不触发深入——深入必须由 Alt 键显式确认。这也是示例选择覆盖它的原因。

源码级解读：shouldBeExact 在判定链路中的位置

仅仅替换一个回调还不够，想要准确预测其行为，需要理解绑定判定的完整调用链。箭头工具的目标吸附判定集中在 arrowTargetState.ts 的 updateArrowTargetState 函数中，这里展示了 precise 与 exact 的关系如何被最终计算：

const util = editor.getShapeUtil<ArrowShapeUtil>('arrow')

// 按住 Ctrl（shouldIgnoreTargets 为真）时完全跳过目标吸附
if (util.options.shouldIgnoreTargets(editor)) {
	getArrowTargetAtom(editor).set(null)
	return null
}

// ... 命中检测、几何求交、肘形箭头锚点计算 ...

let precise = isPrecise

// 精确性会被多个条件自动修正，例如：
if (!targetGeometryInTargetSpace.isClosed) {
	precise = true   // 目标是不闭合图形（如线段）时强制精确
}
// 防止在同一目标上重复不精确吸附产生零长度箭头
if (oppositeBinding && target.id === oppositeBinding.toId && oppositeBinding.props.isPrecise) {
	precise = true
}

// 关键一步：把“最终计算的 precise”交给 shouldBeExact 决策
const isExact = util.options.shouldBeExact(editor, precise)
if (isExact) precise = true   // exact 必然伴随 precise

从 arrowTargetState.ts 的实现可以提炼出几个重要结论：

1. 传入 shouldBeExact 的 isPrecise 是经过层层修正后的最终值，而不是最初传入的原始值。测试用例 ArrowShapeOptions.test.ts 特别强调 "shouldBeExact gets the final computed precise value"，例如当目标是不闭合图形时会自动强制 precise，此时 shouldBeExact 同样会收到 true。
2. isExact 为真时会反向把 precise 置为 true，即 exact 隐含精确，二者不会出现"exact 但不精确"的矛盾状态。
3. isExact 直接影响后续吸附策略：源码中 shouldSnapNone = precise && (isClosed || isExact)，当箭头为 exact 时会跳过“吸附到中心”等中间状态，端点直接落到指针所在的具体点，从而实现“深入图形到绑定点”的效果。

精确状态从何而来：两个超时配置

shouldBeExact 收到的 isPrecise 并非凭空产生，而是由箭头工具状态机中的两个计时器驱动：

• 悬停计时：使用箭头工具在空中悬停时，Idle 状态会检测是否进入新的目标图形，并在 hoverPreciseTimeout（默认 600ms）后把 isPrecise 置为 true；一旦移出目标区域立即复位为 false 并清除计时器。
• 拖动计时：按住端点开始拖动箭头时，Pointing 状态会在 pointingPreciseTimeout（默认 320ms）内持续把端点在目标图形附近按住，计时结束后标记为精确。

这也解释了示例 README 中的操作提示——"draw an arrow into a shape and pause before releasing"（绘制箭头后停顿再松手）：600ms 的悬停计时（或拖动时的 320ms 计时）被触发后，目标绑定进入 precise 状态，而示例又通过 shouldBeExact: (_, isPrecise) => isPrecise 让每一个 precise 绑定都顺理成章地变为 exact，于是箭头尖端便扎进图形内部。速度过快的快速拖拽则会因计时未满而保持 imprecise，箭头仍会回到中心吸附模式。

行为验证：官方测试如何锁定该语义

仓库内部不仅通过示例演示了该配置，还专门编写了单元测试来锁定 shouldBeExact 的语义边界：

• ArrowShapeOptions.test.ts 断言默认 shouldBeExact 行为为“仅 Alt 键触发”，默认 shouldIgnoreTargets 为“仅 Ctrl 键触发”；
• ArrowShapeOptions.test.ts 展示了更激进的替换玩法——用 Shift 键替代 Alt 键触发 exact（(editor) => editor.inputs.getShiftKey()），证明该回调完全由使用者自定义；
• ArrowShapeOptions.test.ts 直接复刻了本示例的 shouldBeExact: (_, isPrecise) => isPrecise 逻辑，断言“当输入为精确时 targetState.isExact === true 且 isPrecise === true”；
• ArrowShapeTool.test.ts 与 ArrowShapeTool.test.ts 在工具交互层验证 shouldBeExact（Alt 键）与 shouldIgnoreTargets（Ctrl 键）在真实绘制流程中的作用。

同族选项：shouldIgnoreTargets 与判定超时

如果你已经掌握了 shouldBeExact，顺带了解其“同族兄弟”会让自定义更完整。在 ArrowShapeOptions 接口中，绑定行为相关的核心 options 包括：

配置项	默认值	作用
shouldBeExact(editor, isPrecise)	按下 Alt 键为 true	是否让绑定深入图形直至具体点
shouldIgnoreTargets(editor)	按下 Ctrl 键为 true	为 true 时完全不吸附任何目标图形（相当于自由绘制）
hoverPreciseTimeout	600ms	空中悬停多久后进入精确状态
pointingPreciseTimeout	320ms	拖拽箭头端点按住多久后进入精确状态

示例只覆盖了 shouldBeExact 一个键，其余选项保持默认，这也体现了 configure 的“局部覆盖、其余继承”特性。你可以在此基础上继续组合：例如同时覆盖 shouldBeExact 与 shouldIgnoreTargets，让自家交互中 Shift 键承担“不吸附”的职责（正如测试所演示），从而打造与 tldraw 默认习惯不同但完全可控的产品级箭头体验。

小结

想要的效果	配置写法
精确箭头自动深入目标内部（本文主题）	shouldBeExact: (_, isPrecise) => isPrecise
保持默认：Alt 键才深入	不传该选项
换成其他修饰键触发深入	shouldBeExact: (editor) => editor.inputs.getShiftKey()
任何绑定都不吸附目标	shouldIgnoreTargets: () => true

本文所涉及的示例源码位于 apps/examples/src/examples/configuration/arrows-precise-exact 目录，可直接在 examples 应用中运行体验；想验证配置行为与默认语义的差异，可前往 packages/tldraw/src/lib/shapes/arrow/ 阅读 ArrowShapeUtil.tsx、arrowTargetState.ts 及配套测试继续深入。