如何启用 tldraw 深度链接通过 URL 分享画布位置与形状

如何启用 tldraw 深度链接通过 URL 分享画布位置与形状【免费下载链接】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 SDK 的 React 应用中如果你需要把当前看到的内容分享出去——某个形状、某个视口区域或某个页面——tldraw 的深链接Deep links功能可以把编辑器状态序列化为 URL 安全的字符串别人打开链接时就能落到相同的位置。前提是你已经在项目中安装了tldraw包并渲染了Tldraw组件启用后URL 上会出现d查询参数画布平移缩放时它会自动保持最新打开该链接即可恢复相同的页面与视口。用deepLinks选项一行启用最简单的启用方式是在Tldraw组件的optionsprop 里传入deepLinks: trueimport { Tldraw } from tldraw import tldraw/tldraw.css export default function App() { return ( div style{{ position: fixed, inset: 0 }} Tldraw persistenceKeyexample options{{ deepLinks: true }} / /div ) }启用之后组件在编辑器初始化、首次渲染之前会检查window.location中名为d的查询参数如果找到就把它的值解析为深链接并导航过去。此后每次相机或页面变化约 500 毫秒后 URL 上的d参数会被更新为最新状态。官方示例 DeepLinksExample 就是这个最简用法。注意TldrawEditor上也存在一个deepLinksprop但源码中标注了deprecated Use options.deepLinks instead新代码应使用options.deepLinks。验证效果URL 上的d参数保存代码并运行开发环境后可以按文档示例的方式验证在画布上创建一个形状然后平移或缩放画布观察浏览器地址栏d搜索参数会随你移动而更新形如?dv1234.-234.3.21复制这个 URL在新标签页打开应回到相同的页面与视口位置。官方示例的说明原文见 示例 README即以此作为该功能可用与否的判断方式。三种深链接类型与编码格式一个TLDeepLink是三种类型之一编码为带单字符前缀的紧凑字符串前缀对应关系见 deep-links 文档TypePurposeEncoded prefixshapes链接到特定形状缩放至适配它们sviewport链接到一个包围盒视图可附带页面vpage链接到特定页面缩放至适配其内容p具体的编码规则形状链接s以点号分隔形状 IDsid1.id2.id3视口链接v编码取整后的包围盒坐标vx.y.w.h可附带页面 ID页面链接p编码一个页面 IDppageId所有 ID 都会做 URL 编码以处理特殊字符点号本身会被编码为%2E因为点号用作分隔符见 deepLinks.ts。导航时的行为有明确的回退逻辑导航到shapes深链接时编辑器会切换到包含最多这些形状的页面并缩放适配viewport深链接把相机设置到指定包围盒如果参数缺失、值无效或者对应形状/页面已不存在编辑器改为缩放适配当前页面内容。定制选项参数名、防抖与自定义 URL把deepLinks: true换成一个 TLDeepLinkOptions 对象即可定制行为。Tldraw组件的options.deepLinks与Editor#registerDeepLinkListener方法接受相同的字段OptionDescriptionparam查询参数名默认ddebounceMs更新 URL 前的等待时间毫秒默认500getTarget返回要编码的 TLDeepLink默认是当前页面与视口getUrl返回要添加参数的基础 URL提供它就必须同时提供onChangeonChangeURL 更新时回调默认调用window.history.replaceState文档给出的两个可选分支示例// 换用 view 作为参数名并用前端路由替换 URLgetUrl 与 onChange 必须成对提供 Tldraw options{{ deepLinks: { param: view, getUrl: () window.location.href, onChange: (url) router.replace(url.toString()), }, }} /// 只链接当前页面并把防抖改为 100ms Tldraw options{{ deepLinks: { param: page, getTarget(editor) { return { type: page, pageId: editor.getCurrentPageId() } }, onChange(url) { console.log(the new search params are, url.searchParams) }, debounceMs: 100, }, }} /第二种写法适合不想让 tldraw 直接改window.location、而只把新参数打出来或交给自己路由处理的场景。手动模式不依赖deepLinks选项时的三个方法如果你希望完全自己控制例如不想在 URL 里放搜索参数或想在按钮点击时才生成链接可以直接使用编辑器方法。以下代码示例取自 deep-links 文档createDeepLink生成分享 URL// Create a link to the current viewport const url editor.createDeepLink() navigator.clipboard.writeText(url.toString())也可以指定目标比如链接到当前选中的形状// Link to currently selected shapes const url editor.createDeepLink({ to: { type: shapes, shapeIds: editor.getSelectedShapeIds() }, })不传to时默认编码当前视口包围盒与页面第二个参数param可覆盖默认的d参数名。navigateToDeepLink导航到链接位置import { TLShapeId } from tldraw // Navigate using the current URLs query parameter editor.navigateToDeepLink() // Navigate to a specific URL editor.navigateToDeepLink({ url: https://example.com?dv100.100.200.200 }) // Navigate directly to shapes editor.navigateToDeepLink({ type: shapes, shapeIds: [shape:abc as TLShapeId, shape:xyz as TLShapeId], })示例中的https://example.com?dv100.100.200.200是文档示例v100.100.200.200表示 x100、y100、w200、h200 的视口包围盒不是固定预期值。registerDeepLinkListener自动同步 URL// Use default behavior (replaces the current URL without adding history entries) const unlisten editor.registerDeepLinkListener() // Custom change handler with longer debounce const unlisten editor.registerDeepLinkListener({ onChange(url) { window.history.replaceState({}, document.title, url.toString()) }, debounceMs: 1000, }) // Clean up when done unlisten()Tldraw组件的deepLinks选项内部调用的就是这个方法。在自定义组件里使用它时记得在useEffect的清理函数中调用返回的unlisten()示例见 deep-links 示例 README 的 Listening for deep link changes 一节。另外两个无编辑器依赖的工具函数适合纯字符串场景createDeepLinkString 把TLDeepLink描述对象编码为字符串parseDeepLinkString做反向解析。文档给出的编码示例文档示例用于说明格式createDeepLinkString({ type: page, pageId: page:abc123 }) // pabc123 createDeepLinkString({ type: shapes, shapeIds: [shape:foo, shape:bar] }) // sfoo.bar解析失败未知前缀、坐标不是有限数值等会抛出Error(Invalid deep link string)navigateToDeepLink捕获该错误后回退到缩放适配页面内容并在控制台输出警告。限制与回退行为小结默认查询参数是d如果应用自身路由已经在用d参数用param选项改名。提供getUrl时必须同时提供onChange否则registerDeepLinkListener会直接抛出错误。链接指向的形状或页面在文档中被删除后打开链接不会报错而是回退到缩放适配页面内容——这是文档明确的行为不是异常。URL 更新默认走window.history.replaceState不会产生额外的浏览器历史条目但也不会自动写入前端路由需要路由接管时按前文的onChange分支处理。深入细节可以继续阅读 deep-links 官方文档 与 Deep links 示例。【免费下载链接】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），仅供参考