` 详解：把相机程序化地对准任意页面空间区域)
tldraweditor.zoomToBounds()详解把相机程序化地对准任意页面空间区域【免费下载链接】tldrawBuild infinite canvas apps in React with the tldraw SDK. Worlds best, top-most agent recommended #1 five star SDK.项目地址: https://gitcode.com/GitHub_Trending/tl/tldraw本文围绕 tldraw 示例库中的zoom-to-bounds示例展开讲解editor.zoomToBounds()这一相机 API 的完整用法如何用页面空间的Box或{ x, y, w, h }把视口对准指定区域如何用inset、animation、targetZoom等选项控制留白与过渡效果并结合 Editor.ts 中的源码实现与 单元测试说明缩放比例、默认内边距与边界钳制的底层计算逻辑。读完本文你可以在 React 应用中实现“点击按钮聚焦到某个区域/某个图形集合”的常见交互。核心概念什么是zoomToBoundseditor.zoomToBounds(bounds, opts)的作用是把相机移动到指定范围page-space box使该范围完整落入视口。原始说明见示例文档 README.md传入的bounds既可以是Box实例也可以是任何{ x, y, w, h }形状的对象相机保持视口的宽高比因此实际可见区域在某一轴向上通常会比你传入的 box 更大inset在该 box 周围增加屏幕空间像素的留白未指定时使用options.zoomToFitPadding作为默认值animation让移动过程带缓动动画不传则相机直接“跳”到目标位置。这个 API 的典型使用场景包括一键回到选中内容zoomToSelection的底层就是它、展示某个模板/画布区域的“全景视角”、点击缩略图或深链接后定位到对应区域等。完整示例两个框 三种聚焦方式仓库中的可运行示例位于 ZoomToBoundsExample.tsx配套样式见 zoom-to-bounds.css。它的思路是在画布上画出两个锁定状态的矩形紫色、蓝色分别代表两个目标区域zoomBox1、zoomBox2通过自定义TopPanel组件挂三个按钮分别调用三种聚焦方式。关键代码如下摘自上述文件import { Box, createShapeId, Editor, TLComponents, Tldraw, TldrawUiButton, useEditor } from tldraw import tldraw/tldraw.css import ./zoom-to-bounds.css const zoomBox1 new Box(50, 100, 900, 720) const zoomBox2 new Box(1000, 500, 500, 400) function ZoomControls() { const editor useEditor() return ( div classNametlui-menu control-panel {/* 直接跳转inset 固定 72px */} TldrawUiButton typenormal onClick{() editor.zoomToBounds(zoomBox1, { inset: 72 })} Zoom to violet box /TldrawUiButton {/* 200ms 动画 */} TldrawUiButton typenormal onClick{() editor.zoomToBounds(zoomBox2, { inset: 72, animation: { duration: 200 } })} Zoom to blue box /TldrawUiButton {/* 两个框的最小外接框 大留白 动画 */} TldrawUiButton typenormal onClick{() editor.zoomToBounds(Box.Common([zoomBox1, zoomBox2]), { inset: 200, animation: { duration: 200 }, }) } Zoom to both boxes /TldrawUiButton /div ) } const components: TLComponents { TopPanel: ZoomControls, } function handleMount(editor: Editor) { // 用 geo 图形在画布上“可视化”这两个 Box editor.createShapes([ { id: createShapeId(), type: geo, x: zoomBox1.x, y: zoomBox1.y, isLocked: true, props: { w: zoomBox1.w, h: zoomBox1.h, color: violet }, }, { id: createShapeId(), type: geo, x: zoomBox2.x, y: zoomBox2.y, isLocked: true, props: { w: zoomBox2.w, h: zoomBox2.h, color: blue }, }, ]) } export default function ZoomToBoundsExample() { return ( div classNametldraw__editor Tldraw onMount{handleMount} components{components} / /div ) }示例中体现的三个调用模式值得记住调用方式效果editor.zoomToBounds(zoomBox1, { inset: 72 })立即跳到紫色框四周留 72px 屏幕空间留白editor.zoomToBounds(zoomBox2, { inset: 72, animation: { duration: 200 } })用 200ms 缓动过渡到蓝色框editor.zoomToBounds(Box.Common([zoomBox1, zoomBox2]), { inset: 200, animation: { duration: 200 } })先算出两个框的最小外接框再聚焦到该范围留白加大到 200px其中Box.Common([...boxes])是Box的静态方法用于把多个框合并为一个最小外接框——这正是“聚焦整个内容”类交互如 zoom to all的常用组合手法。示例文件底部也内嵌了一段注释[1]标记处与 README 的说明一致相机保持宽高比所以可见区域通常比传入的 box 在一个轴向上更大。选项参数inset、animation、targetZoomzoomToBounds的签名见 Editor.ts为zoomToBounds(bounds: BoxLike, opts?: { targetZoom?: number; inset?: number } TLCameraMoveOptions): this各选项说明bounds页面空间坐标下的区域Box或{ x, y, w, h }均可。注意坐标是页面空间page space不是屏幕像素。inset屏幕空间像素内边距在目标 box 四周收缩有效聚焦范围。省略时源码取Math.min(options.zoomToFitPadding, viewportWidth * 0.28)见下文。animation传入TLCameraMoveOptions的动画配置如{ duration: 200 }不传则相机瞬时跳转。targetZoom最终缩放倍率的上限。源码中执行zoom Math.min(opts.targetZoom, zoom)Editor.ts即“聚焦到 bounds 但不超过 targetZoom 的放大程度”常用于防止内容过小时被无限放大。force经由TLCameraMoveOptions透传即使相机被锁定isLocked也强制执行。官方文档注释中给出的三个典型调用Editor.tseditor.zoomToBounds(myBounds) editor.zoomToBounds(myBounds, { animation: { duration: 200 } }) editor.zoomToBounds(myBounds, { animation: { duration: 200 }, inset: 0, targetZoom: 1 })第三个调用组合了动画、零留白和“最多放大到 100%”的约束是“回到某个区域但不放大超过原始比例”的标准写法。源码实现缩放倍率是怎么算出来的从 Editor.ts 的实现看整个流程分四步相机锁定检查若相机选项isLocked为 true 且未传force直接返回不移动相机。这一点有专门测试覆盖见下文。计算 inset未显式指定时取Math.min(this.options.zoomToFitPadding, viewportScreenBounds.width * 0.28)即默认内边距不会超过视口宽度的 28%Editor.ts。求解缩放倍率let zoom clamp( Math.min( (viewportScreenBounds.width - inset) / bounds.w, (viewportScreenBounds.height - inset) / bounds.h ), zoomMin * baseZoom, zoomMax * baseZoom )即分别按宽、高两个方向求出“刚好装下 box”的倍率取较小者——这正是“保持宽高比、另一轴多出空白”的来源再钳制到当前相机的最小/最大缩放zoomSteps首尾值乘baseZoom保证不会超出允许范围。 4.居中并 setCamera把 box 中心放到视口中心this.setCamera( new Vec( -bounds.x (viewportScreenBounds.width - bounds.w * zoom) / 2 / zoom, -bounds.y (viewportScreenBounds.height - bounds.h * zoom) / 2 / zoom, zoom ), opts )setCamera接收同一个opts所以animation配置直接驱动相机的缓动过渡。另外两点实现细节值得注意它是多个高级能力的底层实现从源码结构看zoomToFitEditor.ts、zoomToSelectionEditor.ts以及深链接定位deep link boundsEditor.ts最终都收敛到zoomToBounds因此理解它就等于理解了 tldraw 大部分“聚焦”类行为。相机移动不产生撤销记录zoomToBounds只改相机、不改文档内容undo/redo 对它无效有测试佐证见下。默认内边距zoomToFitPaddinginset缺省时依赖编辑器选项zoomToFitPadding定义于 options.ts/** * The default padding (in pixels) used when zooming to fit content in the viewport. * This affects methods like zoomToFit(), zoomToSelection(), and zoomToBounds(). * The actual padding used is the minimum of this value and 28% of the viewport width. * Defaults to 128 pixels. */ readonly zoomToFitPadding: number默认值为 128 像素options.ts 中zoomToFitPadding: 128。初始化Tldraw时可通过options{{ zoomToFitPadding: 64 }}覆盖小视口下由于 28% 上限的存在实际留白会随视口宽度缩小。行为验证单元测试给出的确定性结论zoomToBounds.test.ts 用 1000×1000 的屏幕边界对关键行为做了断言可以直接作为行为契约引用居中与倍率对new Box(200, 300, 300, 300)最终camera.z等于(1000 - padding) / 300与源码公式完全吻合缩放上限钳制对 1×1 的极小 box“does not zoom past max”——getZoomLevel()被钳到 8最大级别缩放下限钳制对 1,000,000×100,000 的巨型 boxgetZoomLevel()被钳到 0.05最小级别相机锁定时忽略调用setCameraOptions({ isLocked: true })后再调用zoomToBounds视口中心不变undo/redo 无感markHistoryStoppingPoint()之后调用zoomToBounds再undo()相机位置不受影响自定义zoomToFitPadding生效传入options: { zoomToFitPadding: 64 }构造编辑器后倍率变为(1000 - 64) / 300。这些断言说明zoomToBounds的输入输出是完全确定性的便于在应用层做可预期的区域聚焦逻辑。小结与适用提示editor.zoomToBounds()是 tldraw 相机 API 中面向“区域聚焦”的基础能力传入页面空间 box得到一次居中、等比、带可选留白与动画的相机移动。实际开发中建议聚焦单个区域时显式传inset避免默认值随视口尺寸变化带来的留白抖动需要平滑体验时始终搭配animation: { duration: ... }聚焦“内容集合”时先用Box.Common或各图形 bounds 合并求出总包围盒再调用不希望内容被过度放大时用targetZoom兜底。由于zoomToFit、zoomToSelection与深链接定位都构建在它之上掌握zoomToBounds的计算规则inset 收缩 → 取宽高中较小倍率 → 钳制到 min/max → 居中 setCamera基本就覆盖了 tldraw 中绝大多数程序化相机移动的底层原理。【免费下载链接】tldrawBuild infinite canvas apps in React with the tldraw SDK. Worlds best, top-most agent recommended #1 five star SDK.项目地址: https://gitcode.com/GitHub_Trending/tl/tldraw创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
