使用 tldraw SDK 构建 AI 图像生成管道可视化节点图编辑器image-pipeline 模板深度解析【免费下载链接】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 官方仓库templates/image-pipeline模板展开讲解如何基于 tldraw 的无限画布与自定义 Shape 系统构建一个面向 AI 图像生成工作流的可视化节点图编辑器类似 ComfyUI但完全由 React 与 tldraw 驱动。读完本文你将掌握该模板的三大核心概念节点、连接、端口、交互设计原理、DAG 执行引擎的工作方式以及基于 Cloudflare Worker R2 的完整部署流程可直接复制到自己的项目中二次开发。一、模板定位在 tldraw 之上搭建节点式图像生成工作流templates/image-pipeline位于仓库 templates/image-pipeline是一个官方 Starter Kit它把 tldraw 从白板升级为可运行的视觉编程环境。用户可以在无限画布上摆放节点、用带类型的端口连线、运行整个图graph来生成图片。README 明确将其定位为Users place nodes on an infinite canvas, wire up typed ports, and run the graph to generate images — similar to ComfyUI, but built with React and tldraw.从模板的package.jsontemplates/image-pipeline/package.json可以看到技术栈核心依赖tldrawworkspace 内联包、react/react-dom19.x、radix-uiUI 组件、itty-routerWorker 路由开发依赖vite8.x 构建、wrangler4.x Cloudflare 部署、cloudflare/vite-plugin、typescript脚本devvite --host、buildtsc vite build、previewvite preview模板的官方定位是Create a node-based builder for image generation pipelines部署目标为 Cloudflare托管地址为image-pipeline.templates.tldraw.dev。二、环境准备与本地开发2.1 配置 Replicate API Token后端图像生成能力由 Replicate 提供。在模板根目录创建.dev.vars文件并写入你的 API 密钥REPLICATE_API_TOKENyour_replicate_api_token_here注意没有该 Token 时生成请求会直接报错失败。.dev.vars仅用于本地开发部署后密钥通过wrangler secret put写入见第六节。2.2 安装依赖并启动# 安装依赖二选一 yarn # 或 npm install # 启动开发服务器 yarn dev # 或 npm run dev打开浏览器访问http://localhost:5173/即可看到应用。dev脚本使用vite --host允许局域网内其他设备访问。首次打开时画布并非空白——入口文件 templates/image-pipeline/src/App.tsx 中的createDefaultPipeline会在检测到画布上没有node形状时自动创建一个默认的文生图管道Model 节点provider: fluxmodelId: flux-devPrompt 节点提示词a photo of a cat sitting on a windowsillGenerate 节点steps: 20cfgScale: 7随机 seedPreview 节点用于展示生成结果四个节点按Model → Prompt → Generate → Preview的拓扑摆放开箱即用。三、三大核心概念节点、连接、端口README 将整个系统归纳为 3 个核心概念它们分别对应模板中三个独立目录src/nodes、src/connection、src/ports。3.1 Nodes节点接收输入、产出输出的形状节点是接收输入并产生输出的 tldraw 形状。README 概述为 16 种节点类型涵盖三类角色输入类Model模型、Prompt提示词、Load Image加载图片处理类Generate生成、ControlNet、Upscale放大展示类Preview预览节点注册表位于 templates/image-pipeline/src/nodes/nodeTypes.tsx 的NodeDefinitions对象从源码看共注册了 17 个节点定义README 以 16 种概括主要角色节点 key含义model选择图像生成模型如 flux-devprompt文生图提示词generate核心生成节点steps / cfgScale / seedgenerate_text多模态文本生成controlnetControlNet 条件控制load_image加载本地/远程图片preview展示生成的图片blend图片混合adjust图像调整upscale图片放大ip_adapterIP-Adapter 参考图引导生成style_transfer风格迁移prompt_concat提示词拼接number数值输入router路由/分派iterator迭代器capture捕获画布内容每种节点定义都位于 templates/image-pipeline/src/nodes/types/ 目录如GenerateNode.tsx、PromptNode.tsx它们继承自抽象基类NodeDefinitiontemplates/image-pipeline/src/nodes/types/shared.tsx。NodeDefinition规定了每个节点必须实现的能力abstract class NodeDefinitionNode extends { type: string } { readonly type: Node[type] // 节点类型标识 readonly validator: T.ValidatorNode // tlschema 校验器用于形状 props 持久化 abstract readonly title: string // 节点标题 abstract readonly icon: TLUiIconJsx // 图标 abstract readonly category: string // 工具栏分组类别 abstract getDefault(): Node // 默认 props abstract getBodyHeightPx(...): number // 节点主体高度影响形状尺寸 abstract getPorts(...): Recordstring, ShapePort // 端口布局 abstract getOutputInfo(...): InfoValues // 输出值信息含过期标记 abstract execute(shape, node, inputs): PromiseExecutionResult // 执行逻辑 abstract Component: React.ComponentType... // 节点 React 渲染组件 }节点形状本身由 templates/image-pipeline/src/nodes/NodeShapeUtil.tsx 中的NodeShapeUtil定义它注册了node形状类型props 为{ node: NodeType; isOutOfDate: boolean }并基于节点定义动态计算几何getGeometry由矩形主体 圆形端口组成。执行时节点会进入NodeShape_executing高亮态页脚提供Play from here按钮和更多操作菜单Duplicate / Download image / Copy text / Clear result。3.2 Ports端口带数据类型的端点端口是节点上的带类型端点。每个端口都有一种数据类型且只有类型兼容的端口才能连接。端口定义见 templates/image-pipeline/src/ports/Port.tsxinterface ShapePort extends VecModel { id: PortId terminal: start | end // start输出end输入 dataType: PortDataType // 数据类型 multi?: boolean // true 时该输入端口可接收多条连接 }数据类型共 6 种定义于 templates/image-pipeline/src/constants.tsx每种类型配有专属 CSS 颜色用于给端口和连接线上色让用户一眼看出哪些输出能与哪些输入对接类型颜色含义image#c060e0紫图像URLtext#4caf50绿文本model#2196f3蓝模型 IDnumber#9e9e9e灰数值latent#ff9800橙潜空间张量any#c08520棕任意类型万能适配类型兼容规则在 templates/image-pipeline/src/ports/portCompatibility.ts 中实现核心逻辑极简export function arePortDataTypesCompatible(a, b) { return a any || b any || a b }即any可以匹配任何类型其余类型必须完全一致image 不能连 model。findFirstCompatiblePort在自动接入时还会优先选择精确类型匹配的端口而不是any端口例如文本源会优先接入prompt端口而非通用any端口。3.3 Connections连接类型着色的贝塞尔曲线连接将一个节点的输出接到另一个节点的输入以贝塞尔曲线绘制并按数据类型着色。连接形状实现在 templates/image-pipeline/src/connection/ConnectionShapeUtil.tsxgetConnectionControlPoints根据起终点水平距离动态生成控制点正向连接取distance / 3反向连接取min(|distance| 30, 100)最小值 30px保证曲线始终平滑可读曲线颜色由起点绑定的端口数据类型决定PORT_TYPE_COLORS[dataType]连接中间有一个插入手柄ConnectionCenterHandleOverlayUtil点击曲线中点即可插入新节点当上游输出为STOP_EXECUTION时连接线进入ConnectionShape_inactive失活态。每条连接包含两个绑定binding——一个指向起始节点、一个指向结束节点由 templates/image-pipeline/src/connection/ConnectionBindingUtil.tsx 中的ConnectionBindingUtil管理。该 BindingUtil 的 props 为{ portId, terminal: start | end, order? }并在onAfterCreate/onAfterChange/onAfterDelete生命周期中自动回调节点的onNodePortConnect/onNodePortDisconnect让节点能感知连接变化例如prompt端口被连接后应禁用本地编辑。输入端口支持多连接时order属性会自动递增以维持输入顺序。四、交互设计端口拖拽、节点拾取与环路防护README 列出了用户可执行的关键交互每一项目前都有对应的源码实现4.1 从端口拖拽创建连接按住端口拖拽即可创建新连接。这一行为并非写在 shape util 中而是通过tldraw 交互状态树interaction state tree扩展实现入口 templates/image-pipeline/src/App.tsx 在onMount中执行editor.getStateDescendant(select)!.addChild(PointingPort)把 templates/image-pipeline/src/ports/PointingPort.tsx 挂到 select 工具的pointing_port子状态。PointingPort.onPointerMove检测到拖拽时会新建一个connection形状把当前端口绑定为起始/结束端然后转换到dragging_handle状态走 tldraw 标准手柄拖拽流程。若是从已连接的输入端口再次拖拽则复用已有连接进行重连。4.2 拖到空白处打开画布内节点拾取器从端口拖拽到空白处松开时isCreatingShape draggingTerminal endConnectionShapeUtil.onHandleDragEnd会调用 templates/image-pipeline/src/components/OnCanvasNodePicker.tsx在画布上弹出节点拾取面板按数据流方向自动挑选与源端口类型兼容的目标节点并自动接入第一个兼容输入端口。同样地单击输出端口不拖拽也会触发PointingPort.onClick在节点右侧预留间距处打开拾取器快速追加下游节点。4.3 点击连接中点插入节点每个连接渲染有中心手柄ConnectionCenterHandleOverlayUtil点击后调用 templates/image-pipeline/src/connection/insertNodeWithinConnection.tsx在曲线中点三次贝塞尔 t0.5 处getConnectionPageCenter按公式(P0 3·P1 3·P2 P3) / 8计算插入新节点并把原连接拆成两段。4.4 类型兼容强制与环路检测ConnectionShapeUtil.onHandleDrag在拖拽过程中实时计算三类约束类型检查若目标端口类型与对端类型不兼容则视为无效目标环路检测通过getAllConnectedNodes获取对端节点可达的全部节点集合若目标端口所在节点在该集合内则拒绝连接防止形成循环依赖端口占用替换若目标输入端口非multi已有连接先把待替换连接记录到pendingReplacementId拖拽完成提交时onHandleDragEnd再真正删除保证交互可撤销、无闪烁。拖拽过程中所有候选端口会通过portState被标记为Port_eligible可连接或Port_hinting当前悬停目标视觉反馈即时可见。4.5 细节优化keepConnectionsAtBottom.tsx通过副作用监听保持连接始终位于节点下方z-order避免遮挡App.tsx中调用disableTransparency(editor, [connection])确保导出图片时连接线不透明画布开启isSnapMode节点摆放时可对齐吸附maxPages: 1限制单页actionShortcutsLocation: menu收敛快捷键入口。五、执行引擎把节点图当作 DAG 运行模板会自动检测相连节点的分组在它们周围绘制区域覆盖层PipelineRegions并提供播放/停止控件每个节点自身也有Play from here按钮。这些控件最终都汇入 DAG 执行引擎 templates/image-pipeline/src/execution/ExecutionGraph.tsx。5.1 图构建从起点反向收集ExecutionGraph构造函数从起始节点集合出发做遍历沿着每个节点的start输出端口连接递归收集所有可达节点构建nodesByIdAtomMap每个节点记录状态waiting/executing/executed与其连接列表。若用户从中间某个节点播放引擎只收集该节点的下游子图执行。5.2 执行依赖就绪后并行推进execute()对所有起始节点并行调用executeNodeIfReady。每个节点执行前必须满足所有end输入连接的依赖节点均已executed依赖输出值不是STOP_EXECUTION符号常量见 shared.tsx节点可返回它以提前终止整条链路例如空输入时不调用付费 API未满足则直接返回等待依赖完成后再被唤醒由已执行节点沿输出连接递归触发。输入收集时按order排序若目标端口multi为 true多个来源的值会被聚合成数组传入节点。节点执行前后形状的isOutOfDate会被置 true/false驱动 UI 显示待刷新占位符显示...。执行状态哪些节点在跑、结果、错误统一由 templates/image-pipeline/src/execution/executionState.ts 管理支持startExecution/stopExecution停止时ExecutionGraph.stop()置状态为stopped正在等待的节点随即中止。节点执行结果如图片 URL、文本写回节点 props如lastResultUrl因此运行结果随 tldraw 文档持久化刷新页面依然可见也支持通过节点菜单下载图片、复制文本、清空结果。六、Cloudflare Worker 后端与部署模板采用Cloudflare Worker R2作为后端Worker 负责调用 Replicate 等 AI 服务R2 负责存储生成的图片保证图片跨会话持久。6.1 Worker 路由一览入口 templates/image-pipeline/worker/worker.ts 基于itty-router注册了 7 类 API方法与路径处理函数worker/routes/功能POST /api/generategenerate.ts图像生成prompt model 参数POST /api/upscaleupscale.ts图片放大URL scalePOST /api/ip-adapteripAdapter.tsIP-Adapter 参考图引导生成POST /api/style-transferstyleTransfer.ts风格迁移POST /api/generate-textgenerateText.ts多模态文本生成POST /api/images/:imageIdimages.ts上传生成图片到 R2GET /api/images/:imageIdimages.ts从 R2 下载图片对 Replicate 的调用被抽象在 worker/providers/ 中replicate.ts封装 API 调用types.ts定义类型便于替换或扩展其他 AI 提供商。6.2 本地密钥与部署命令部署前需创建 R2 bucket 并写入密钥完整流程README 原文步骤npx wrangler r2 bucket create image-pipeline npx wrangler secret put REPLICATE_API_TOKEN npm run build npx wrangler deploy对应的配置在 templates/image-pipeline/wrangler.tomlmain worker/worker.ts兼容日期2025-05-08开启nodejs_compat标志与 source maps[assets]将构建产物./dist/client以 SPA 方式托管not_found_handling single-page-application[[r2_buckets]]绑定IMAGE_BUCKET生产 bucket 名为image-pipeline预览环境为image-pipeline-preview生产密钥必须通过wrangler secret put设置本地开发则使用.dev.vars文件第二节。前端调用 Worker 的封装位于 templates/image-pipeline/src/api/pipelineApi.ts。前端build时cloudflare/vite-plugin负责把 Worker 与静态资源打包为一个可部署的 Worker。七、文件结构速查README 给出了模板的完整文件结构对照仓库templates/image-pipeline整理如下便于按图索骥src/App.tsx主入口渲染Tldraw /注入自定义 shape/binding/overlay utils、替换 Toolbar、侧边栏并创建默认管道src/nodes节点相关。NodeShapeUtil.tsx自定义node形状 utilnodeTypes.tsx全部节点定义注册表 executeNode等分发函数nodePorts.tsx端口与流经端口值的辅助函数types/每个节点类型的定义端口、默认 props、高度、执行逻辑、React 组件src/connection连接相关。ConnectionShapeUtil.tsx连接形状 util贝塞尔曲线、拖拽重连、插入拾取ConnectionBindingUtil.tsx连接绑定 utilstart/end 两个绑定insertNodeWithinConnection.tsx在连接中点插入节点keepConnectionsAtBottom.tsx保持连接在 z-order 底部src/ports端口相关。Port.tsx端口类型定义与渲染组件PointingPort.tsx扩展 select 工具的自定义端口交互状态portCompatibility.ts端口类型兼容规则src/execution工作流执行。ExecutionGraph.tsxDAG 执行引擎executionState.ts执行状态管理运行中节点、结果、错误src/componentsUI 与画布内组件。PipelineToolbar.tsx替换默认工具栏垂直布局 可拖拽节点类型ImagePipelineSidebar.tsx已保存模板与设置侧边栏OnCanvasNodePicker.tsx画布内节点拾取器PipelineRegions.tsx连接组包围盒与播放/停止控件src/templates子图模板的保存与恢复worker/Cloudflare Worker 后端。worker.ts主入口与 API 路由routes/generate / upscale / style transfer / IP adapter / text / images 路由处理providers/Replicate API 调用抽象。八、许可证与使用注意该模板属于 tldraw SDK 的一部分遵循 tldraw SDK 许可证见仓库根目录 LICENSE.md。免费使用含商业项目的前提是在画布上保留 Made with tldraw 水印如需去除水印可购买商业许可证。tldraw 名称与 Logo 为 tldraw Inc. 商标使用需遵守 TRADEMARKS.md 中的指南。结语templates/image-pipeline展示了 tldraw SDK 最有价值的一种用法把自定义形状、绑定bindings、交互状态树扩展与外部 AI 服务组合成一个完整的可视化编程产品。其节点定义NodeDefinition 类型端口ShapePort 绑定连接BindingUtil DAG 执行ExecutionGraph的四层架构具有清晰的可扩展边界——新增一种节点只需在src/nodes/types/添加一个定义并在nodeTypes.tsx注册新增一种 AI 能力只需在worker/routes/添加路由。基于本文对源码的剖析你可以直接以此模板为起点构建自己的图像、视频、3D 或其他领域的节点式工作流应用。【免费下载链接】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），仅供参考 使用 tldraw SDK 构建 AI 图像生成管道可视化节点图编辑器：image-pipeline 模板深度解析
使用 tldraw SDK 构建 AI 图像生成管道可视化节点图编辑器image-pipeline 模板深度解析【免费下载链接】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 官方仓库templates/image-pipeline模板展开讲解如何基于 tldraw 的无限画布与自定义 Shape 系统构建一个面向 AI 图像生成工作流的可视化节点图编辑器类似 ComfyUI但完全由 React 与 tldraw 驱动。读完本文你将掌握该模板的三大核心概念节点、连接、端口、交互设计原理、DAG 执行引擎的工作方式以及基于 Cloudflare Worker R2 的完整部署流程可直接复制到自己的项目中二次开发。一、模板定位在 tldraw 之上搭建节点式图像生成工作流templates/image-pipeline位于仓库 templates/image-pipeline是一个官方 Starter Kit它把 tldraw 从白板升级为可运行的视觉编程环境。用户可以在无限画布上摆放节点、用带类型的端口连线、运行整个图graph来生成图片。README 明确将其定位为Users place nodes on an infinite canvas, wire up typed ports, and run the graph to generate images — similar to ComfyUI, but built with React and tldraw.从模板的package.jsontemplates/image-pipeline/package.json可以看到技术栈核心依赖tldrawworkspace 内联包、react/react-dom19.x、radix-uiUI 组件、itty-routerWorker 路由开发依赖vite8.x 构建、wrangler4.x Cloudflare 部署、cloudflare/vite-plugin、typescript脚本devvite --host、buildtsc vite build、previewvite preview模板的官方定位是Create a node-based builder for image generation pipelines部署目标为 Cloudflare托管地址为image-pipeline.templates.tldraw.dev。二、环境准备与本地开发2.1 配置 Replicate API Token后端图像生成能力由 Replicate 提供。在模板根目录创建.dev.vars文件并写入你的 API 密钥REPLICATE_API_TOKENyour_replicate_api_token_here注意没有该 Token 时生成请求会直接报错失败。.dev.vars仅用于本地开发部署后密钥通过wrangler secret put写入见第六节。2.2 安装依赖并启动# 安装依赖二选一 yarn # 或 npm install # 启动开发服务器 yarn dev # 或 npm run dev打开浏览器访问http://localhost:5173/即可看到应用。dev脚本使用vite --host允许局域网内其他设备访问。首次打开时画布并非空白——入口文件 templates/image-pipeline/src/App.tsx 中的createDefaultPipeline会在检测到画布上没有node形状时自动创建一个默认的文生图管道Model 节点provider: fluxmodelId: flux-devPrompt 节点提示词a photo of a cat sitting on a windowsillGenerate 节点steps: 20cfgScale: 7随机 seedPreview 节点用于展示生成结果四个节点按Model → Prompt → Generate → Preview的拓扑摆放开箱即用。三、三大核心概念节点、连接、端口README 将整个系统归纳为 3 个核心概念它们分别对应模板中三个独立目录src/nodes、src/connection、src/ports。3.1 Nodes节点接收输入、产出输出的形状节点是接收输入并产生输出的 tldraw 形状。README 概述为 16 种节点类型涵盖三类角色输入类Model模型、Prompt提示词、Load Image加载图片处理类Generate生成、ControlNet、Upscale放大展示类Preview预览节点注册表位于 templates/image-pipeline/src/nodes/nodeTypes.tsx 的NodeDefinitions对象从源码看共注册了 17 个节点定义README 以 16 种概括主要角色节点 key含义model选择图像生成模型如 flux-devprompt文生图提示词generate核心生成节点steps / cfgScale / seedgenerate_text多模态文本生成controlnetControlNet 条件控制load_image加载本地/远程图片preview展示生成的图片blend图片混合adjust图像调整upscale图片放大ip_adapterIP-Adapter 参考图引导生成style_transfer风格迁移prompt_concat提示词拼接number数值输入router路由/分派iterator迭代器capture捕获画布内容每种节点定义都位于 templates/image-pipeline/src/nodes/types/ 目录如GenerateNode.tsx、PromptNode.tsx它们继承自抽象基类NodeDefinitiontemplates/image-pipeline/src/nodes/types/shared.tsx。NodeDefinition规定了每个节点必须实现的能力abstract class NodeDefinitionNode extends { type: string } { readonly type: Node[type] // 节点类型标识 readonly validator: T.ValidatorNode // tlschema 校验器用于形状 props 持久化 abstract readonly title: string // 节点标题 abstract readonly icon: TLUiIconJsx // 图标 abstract readonly category: string // 工具栏分组类别 abstract getDefault(): Node // 默认 props abstract getBodyHeightPx(...): number // 节点主体高度影响形状尺寸 abstract getPorts(...): Recordstring, ShapePort // 端口布局 abstract getOutputInfo(...): InfoValues // 输出值信息含过期标记 abstract execute(shape, node, inputs): PromiseExecutionResult // 执行逻辑 abstract Component: React.ComponentType... // 节点 React 渲染组件 }节点形状本身由 templates/image-pipeline/src/nodes/NodeShapeUtil.tsx 中的NodeShapeUtil定义它注册了node形状类型props 为{ node: NodeType; isOutOfDate: boolean }并基于节点定义动态计算几何getGeometry由矩形主体 圆形端口组成。执行时节点会进入NodeShape_executing高亮态页脚提供Play from here按钮和更多操作菜单Duplicate / Download image / Copy text / Clear result。3.2 Ports端口带数据类型的端点端口是节点上的带类型端点。每个端口都有一种数据类型且只有类型兼容的端口才能连接。端口定义见 templates/image-pipeline/src/ports/Port.tsxinterface ShapePort extends VecModel { id: PortId terminal: start | end // start输出end输入 dataType: PortDataType // 数据类型 multi?: boolean // true 时该输入端口可接收多条连接 }数据类型共 6 种定义于 templates/image-pipeline/src/constants.tsx每种类型配有专属 CSS 颜色用于给端口和连接线上色让用户一眼看出哪些输出能与哪些输入对接类型颜色含义image#c060e0紫图像URLtext#4caf50绿文本model#2196f3蓝模型 IDnumber#9e9e9e灰数值latent#ff9800橙潜空间张量any#c08520棕任意类型万能适配类型兼容规则在 templates/image-pipeline/src/ports/portCompatibility.ts 中实现核心逻辑极简export function arePortDataTypesCompatible(a, b) { return a any || b any || a b }即any可以匹配任何类型其余类型必须完全一致image 不能连 model。findFirstCompatiblePort在自动接入时还会优先选择精确类型匹配的端口而不是any端口例如文本源会优先接入prompt端口而非通用any端口。3.3 Connections连接类型着色的贝塞尔曲线连接将一个节点的输出接到另一个节点的输入以贝塞尔曲线绘制并按数据类型着色。连接形状实现在 templates/image-pipeline/src/connection/ConnectionShapeUtil.tsxgetConnectionControlPoints根据起终点水平距离动态生成控制点正向连接取distance / 3反向连接取min(|distance| 30, 100)最小值 30px保证曲线始终平滑可读曲线颜色由起点绑定的端口数据类型决定PORT_TYPE_COLORS[dataType]连接中间有一个插入手柄ConnectionCenterHandleOverlayUtil点击曲线中点即可插入新节点当上游输出为STOP_EXECUTION时连接线进入ConnectionShape_inactive失活态。每条连接包含两个绑定binding——一个指向起始节点、一个指向结束节点由 templates/image-pipeline/src/connection/ConnectionBindingUtil.tsx 中的ConnectionBindingUtil管理。该 BindingUtil 的 props 为{ portId, terminal: start | end, order? }并在onAfterCreate/onAfterChange/onAfterDelete生命周期中自动回调节点的onNodePortConnect/onNodePortDisconnect让节点能感知连接变化例如prompt端口被连接后应禁用本地编辑。输入端口支持多连接时order属性会自动递增以维持输入顺序。四、交互设计端口拖拽、节点拾取与环路防护README 列出了用户可执行的关键交互每一项目前都有对应的源码实现4.1 从端口拖拽创建连接按住端口拖拽即可创建新连接。这一行为并非写在 shape util 中而是通过tldraw 交互状态树interaction state tree扩展实现入口 templates/image-pipeline/src/App.tsx 在onMount中执行editor.getStateDescendant(select)!.addChild(PointingPort)把 templates/image-pipeline/src/ports/PointingPort.tsx 挂到 select 工具的pointing_port子状态。PointingPort.onPointerMove检测到拖拽时会新建一个connection形状把当前端口绑定为起始/结束端然后转换到dragging_handle状态走 tldraw 标准手柄拖拽流程。若是从已连接的输入端口再次拖拽则复用已有连接进行重连。4.2 拖到空白处打开画布内节点拾取器从端口拖拽到空白处松开时isCreatingShape draggingTerminal endConnectionShapeUtil.onHandleDragEnd会调用 templates/image-pipeline/src/components/OnCanvasNodePicker.tsx在画布上弹出节点拾取面板按数据流方向自动挑选与源端口类型兼容的目标节点并自动接入第一个兼容输入端口。同样地单击输出端口不拖拽也会触发PointingPort.onClick在节点右侧预留间距处打开拾取器快速追加下游节点。4.3 点击连接中点插入节点每个连接渲染有中心手柄ConnectionCenterHandleOverlayUtil点击后调用 templates/image-pipeline/src/connection/insertNodeWithinConnection.tsx在曲线中点三次贝塞尔 t0.5 处getConnectionPageCenter按公式(P0 3·P1 3·P2 P3) / 8计算插入新节点并把原连接拆成两段。4.4 类型兼容强制与环路检测ConnectionShapeUtil.onHandleDrag在拖拽过程中实时计算三类约束类型检查若目标端口类型与对端类型不兼容则视为无效目标环路检测通过getAllConnectedNodes获取对端节点可达的全部节点集合若目标端口所在节点在该集合内则拒绝连接防止形成循环依赖端口占用替换若目标输入端口非multi已有连接先把待替换连接记录到pendingReplacementId拖拽完成提交时onHandleDragEnd再真正删除保证交互可撤销、无闪烁。拖拽过程中所有候选端口会通过portState被标记为Port_eligible可连接或Port_hinting当前悬停目标视觉反馈即时可见。4.5 细节优化keepConnectionsAtBottom.tsx通过副作用监听保持连接始终位于节点下方z-order避免遮挡App.tsx中调用disableTransparency(editor, [connection])确保导出图片时连接线不透明画布开启isSnapMode节点摆放时可对齐吸附maxPages: 1限制单页actionShortcutsLocation: menu收敛快捷键入口。五、执行引擎把节点图当作 DAG 运行模板会自动检测相连节点的分组在它们周围绘制区域覆盖层PipelineRegions并提供播放/停止控件每个节点自身也有Play from here按钮。这些控件最终都汇入 DAG 执行引擎 templates/image-pipeline/src/execution/ExecutionGraph.tsx。5.1 图构建从起点反向收集ExecutionGraph构造函数从起始节点集合出发做遍历沿着每个节点的start输出端口连接递归收集所有可达节点构建nodesByIdAtomMap每个节点记录状态waiting/executing/executed与其连接列表。若用户从中间某个节点播放引擎只收集该节点的下游子图执行。5.2 执行依赖就绪后并行推进execute()对所有起始节点并行调用executeNodeIfReady。每个节点执行前必须满足所有end输入连接的依赖节点均已executed依赖输出值不是STOP_EXECUTION符号常量见 shared.tsx节点可返回它以提前终止整条链路例如空输入时不调用付费 API未满足则直接返回等待依赖完成后再被唤醒由已执行节点沿输出连接递归触发。输入收集时按order排序若目标端口multi为 true多个来源的值会被聚合成数组传入节点。节点执行前后形状的isOutOfDate会被置 true/false驱动 UI 显示待刷新占位符显示...。执行状态哪些节点在跑、结果、错误统一由 templates/image-pipeline/src/execution/executionState.ts 管理支持startExecution/stopExecution停止时ExecutionGraph.stop()置状态为stopped正在等待的节点随即中止。节点执行结果如图片 URL、文本写回节点 props如lastResultUrl因此运行结果随 tldraw 文档持久化刷新页面依然可见也支持通过节点菜单下载图片、复制文本、清空结果。六、Cloudflare Worker 后端与部署模板采用Cloudflare Worker R2作为后端Worker 负责调用 Replicate 等 AI 服务R2 负责存储生成的图片保证图片跨会话持久。6.1 Worker 路由一览入口 templates/image-pipeline/worker/worker.ts 基于itty-router注册了 7 类 API方法与路径处理函数worker/routes/功能POST /api/generategenerate.ts图像生成prompt model 参数POST /api/upscaleupscale.ts图片放大URL scalePOST /api/ip-adapteripAdapter.tsIP-Adapter 参考图引导生成POST /api/style-transferstyleTransfer.ts风格迁移POST /api/generate-textgenerateText.ts多模态文本生成POST /api/images/:imageIdimages.ts上传生成图片到 R2GET /api/images/:imageIdimages.ts从 R2 下载图片对 Replicate 的调用被抽象在 worker/providers/ 中replicate.ts封装 API 调用types.ts定义类型便于替换或扩展其他 AI 提供商。6.2 本地密钥与部署命令部署前需创建 R2 bucket 并写入密钥完整流程README 原文步骤npx wrangler r2 bucket create image-pipeline npx wrangler secret put REPLICATE_API_TOKEN npm run build npx wrangler deploy对应的配置在 templates/image-pipeline/wrangler.tomlmain worker/worker.ts兼容日期2025-05-08开启nodejs_compat标志与 source maps[assets]将构建产物./dist/client以 SPA 方式托管not_found_handling single-page-application[[r2_buckets]]绑定IMAGE_BUCKET生产 bucket 名为image-pipeline预览环境为image-pipeline-preview生产密钥必须通过wrangler secret put设置本地开发则使用.dev.vars文件第二节。前端调用 Worker 的封装位于 templates/image-pipeline/src/api/pipelineApi.ts。前端build时cloudflare/vite-plugin负责把 Worker 与静态资源打包为一个可部署的 Worker。七、文件结构速查README 给出了模板的完整文件结构对照仓库templates/image-pipeline整理如下便于按图索骥src/App.tsx主入口渲染Tldraw /注入自定义 shape/binding/overlay utils、替换 Toolbar、侧边栏并创建默认管道src/nodes节点相关。NodeShapeUtil.tsx自定义node形状 utilnodeTypes.tsx全部节点定义注册表 executeNode等分发函数nodePorts.tsx端口与流经端口值的辅助函数types/每个节点类型的定义端口、默认 props、高度、执行逻辑、React 组件src/connection连接相关。ConnectionShapeUtil.tsx连接形状 util贝塞尔曲线、拖拽重连、插入拾取ConnectionBindingUtil.tsx连接绑定 utilstart/end 两个绑定insertNodeWithinConnection.tsx在连接中点插入节点keepConnectionsAtBottom.tsx保持连接在 z-order 底部src/ports端口相关。Port.tsx端口类型定义与渲染组件PointingPort.tsx扩展 select 工具的自定义端口交互状态portCompatibility.ts端口类型兼容规则src/execution工作流执行。ExecutionGraph.tsxDAG 执行引擎executionState.ts执行状态管理运行中节点、结果、错误src/componentsUI 与画布内组件。PipelineToolbar.tsx替换默认工具栏垂直布局 可拖拽节点类型ImagePipelineSidebar.tsx已保存模板与设置侧边栏OnCanvasNodePicker.tsx画布内节点拾取器PipelineRegions.tsx连接组包围盒与播放/停止控件src/templates子图模板的保存与恢复worker/Cloudflare Worker 后端。worker.ts主入口与 API 路由routes/generate / upscale / style transfer / IP adapter / text / images 路由处理providers/Replicate API 调用抽象。八、许可证与使用注意该模板属于 tldraw SDK 的一部分遵循 tldraw SDK 许可证见仓库根目录 LICENSE.md。免费使用含商业项目的前提是在画布上保留 Made with tldraw 水印如需去除水印可购买商业许可证。tldraw 名称与 Logo 为 tldraw Inc. 商标使用需遵守 TRADEMARKS.md 中的指南。结语templates/image-pipeline展示了 tldraw SDK 最有价值的一种用法把自定义形状、绑定bindings、交互状态树扩展与外部 AI 服务组合成一个完整的可视化编程产品。其节点定义NodeDefinition 类型端口ShapePort 绑定连接BindingUtil DAG 执行ExecutionGraph的四层架构具有清晰的可扩展边界——新增一种节点只需在src/nodes/types/添加一个定义并在nodeTypes.tsx注册新增一种 AI 能力只需在worker/routes/添加路由。基于本文对源码的剖析你可以直接以此模板为起点构建自己的图像、视频、3D 或其他领域的节点式工作流应用。【免费下载链接】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），仅供参考