用 tldraw 构建 AI 聊天应用白板绘画、图片标注与多模态上下文实战指南chat 模板全解析【免费下载链接】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/chat 模板展开讲解如何搭建一个白板 对话深度融合的 AI 聊天应用用户既可以用自然语言与 Gemini 模型对话也可以一键打开 tldraw 画布绘制草图、标注图片再把画布快照作为视觉上下文发送给模型。读完本文你将掌握该模板的完整目录结构、本地运行与 API Key 配置方法并理解其底层实现——从useChat消息流、Google GenAI 文件上传到 tldraw 白板快照与图像导出的完整调用链。模板定位tldraw 生态中的 AI 聊天 Starter Kittemplates/chat是 tldraw 仓库提供的一个 Next.js Starter Kit在package.json的tldraw_template字段中标注为 Create an AI chat that uses tldraw for sketches and annotations。它的核心思路是把 tldraw 白板作为 AI 对话的视觉输入通道让模型能够看见用户画的图。这个模板演示了三个核心能力集成白板提供视觉上下文聊天过程中随时打开 tldraw 画布作画草图随消息一起发给模型图片标注与二次编辑上传的图片先进入白板可裁剪、标注后再加入对话历史消息中的图片也能点击重新打开画布继续编辑文本聊天与画布输入无缝切换输入框同时承载文字、图片和白板入口发送时统一组装为消息内容。其技术栈在 templates/chat/package.json 中清晰可见Next.js 16、React 19、Vercel AI SDKai、ai-sdk/react、ai-sdk/google、Google GenAI 官方库google/genai以及tldraw通过workspace:*直接引用仓库内源码。响应端使用react-markdown渲染 Markdown并用zod做数据校验。本地开发三步跑起来按 README 的说明本地启动非常直接安装依赖使用yarn或npm install该模板是 tldraw monorepo 的一部分仓库根目录使用 yarn workspace 管理推荐yarn启动开发服务器运行yarn dev或npm run devpackage.json中该脚本为next dev -H 0.0.0.0会监听所有网卡地址方便容器或局域网访问打开应用浏览器访问http://localhost:3000/即可看到聊天界面。生产构建则使用yarn buildyarn start。值得注意的是dev脚本显式加了-H 0.0.0.0这是为远程/容器化开发环境准备的在纯本地开发时同样适用。环境变量配置 Gemini API Key模板默认使用 Google 的 Gemini 模型需要在项目根目录创建.env.local并写入 API KeyGOOGLE_GENERATIVE_AI_API_KEYyour_gemini_api_key_hereKey 的获取方式为 Google AI Studio。模板同时说明如果你不想用 Google可以通过 Vercel AI SDK 的 Providers 机制切换到其他模型提供商例如 OpenAI、Anthropic 等只需修改 聊天 API 路由 中streamText的model参数。从源码看这个 Key 有两处消费方聊天接口ai-sdk/google的google(gemini-3.7-flash)模型调用文件上传接口google/genai的GoogleGenAI客户端用于上传图片文件若未配置 Key 会直接返回 500 错误。文件结构每个文件负责什么README 给出了模板的顶层文件地图结合源码可以进一步明确各自职责文件仓库相对路径职责src/app/page.tsx应用入口渲染Chat /外层包tl-theme__light类名套用 tldraw 亮色主题src/components/Chat.tsx聊天主容器用 Vercel AI SDK 的useChat管理对话流src/components/MessageList.tsx可滚动的消息历史列表带加载状态src/components/ChatMessage.tsx单条消息渲染文本用 Markdown图片用可点击的imgsrc/components/ChatInput.tsx输入区文本框、图片上传、白板按钮、发送按钮src/components/WhiteboardModal.tsx集成 tldraw 的画布弹窗负责绘画、标注与图像导出src/app/api/chat/route.tsNext.js API 路由用 Vercel AI SDK 对接 Gemini 并流式返回src/app/api/upload/route.ts图片上传 API把图片托管到 Google GenAI 文件服务src/app/styles.css全部组件的响应式样式README 未列出的支撑文件同样关键useChatInputState.ts 用useReducer统一管理输入框/白板弹窗/拖拽状态useChatMessageStorage.tsx 用浏览器 OPFS 持久化消息useScrollToBottom.ts 维护消息自动滚动uploadMessageContents.ts 负责消息中图片的本地 URL → 远端 URL转换。另有 icons 目录提供 Upload / Whiteboard / Send / Image / X 等 SVG 图标组件。核心交互流程从画布到模型README 描述的关键交互包括自然语言聊天、点击白板按钮打开画布、绘画与画图补充对话、在画布上标注图片。下面按代码路径拆解这条主链路。1. 打开白板ChatInput.tsx 底部有三个按钮图片上传ImageIcon、白板绘图WhiteboardIcon、发送SendIcon。点击白板按钮触发dispatch({ type: openWhiteboard })由 useChatInputState.ts 中的chatInputReducer把openWhiteboard置为非空对象从而渲染WhiteboardModal。上传图片走的也是白板点击图片按钮后创建隐藏的input typefile acceptimage/*选中的文件同样以openWhiteboard动作携带uploadedFile进入白板弹窗——这意味着任何图片都会先经白板再进对话。此外还支持把图片文件直接拖拽到输入区域dragEnter/dragLeave/drop三个动作维护拖拽状态拖入后同样打开白板。2. 画布内的处理WhiteboardModal.tsx 是集成 tldraw 的核心。它用useMemo缓存TLComponents覆盖了右上角的SharePanel替换为 Cancel / Add(Save) 两个按钮——注释明确指出 components 必须 memoize 或定义在组件外部避免 tldraw 频繁重渲染。模板通过PartialTldrawOptions定制了画布行为const options: PartialTldrawOptions { // 禁用新建页面画布始终只有 1 页 maxPages: 1, // 操作快捷键始终显示在右上角菜单区而不是工具栏上 actionShortcutsLocation: menu, // 禁用字体预加载避免弹窗出现后 UI 才弹出来 maxFontsToLoadBeforeRender: 0, }如果是从图片上传进入的InsideOfTldrawContext组件会在 tldraw 上下文内完成图片插入先通过notifyIfFileNotAllowed校验文件合法性不合法时用 tldraw 的 toast 提示再editor.getAssetForExternalContent生成图片 asset按最长边 1000px 缩放居中创建imageshape 并选中最后setCurrentTool(select.crop)直接进入裁剪工具——这就是上传即标注交互的实现。3. 保存画布为图片点击 Save 后handleSave会检查editor.getCurrentPageShapes()画布为空则直接取消避免发送空白图用editor.toImageDataUrl(shapes, { format: png })把当前画布渲染为 PNG 的 data URL用editor.getSnapshot()保存完整画布状态快照TLEditorSnapshot这样图片加入对话后仍可重新打开继续编辑组装WhiteboardImage含id、name、url、snapshot、type: image/png、宽高等交给父组件加入输入区。4. 组装消息并发送Chat.tsx 的handleSendMessage把输入区的文本与所有白板图片组装为 AI SDK 的 UI Parts每张图片是一个FileUIPart携带url、filename、mediaType以及providerMetadata.tldraw中的快照与图片名文本则是TextUIPart。随后调用useChat返回的sendMessage({ parts })。消息发送前还经过DefaultChatTransport的prepareSendMessagesRequest钩子先调用uploadMessageContents把消息里所有data:开头的图片 URL 上传为远端 URL详见下一节再把处理后的消息放入请求体发给/api/chat。5. 服务端流式回复route.ts 接收UIMessage[]用streamText组合模型与系统提示词export const maxDuration 60 // 允许流式响应最长 60 秒 const result streamText({ model: google(gemini-3.7-flash), system: [ Youre a friendly AI chatbot., The user can send you images, sketches and diagrams using your built-in tldraw whiteboard., You cannot create or edit whiteboards yourself., // ... ].join( ), messages: convertToModelMessages(messages), }) return result.toUIMessageStreamResponse()系统提示词明确告知模型用户会通过内置 tldraw 白板发送图片、草图和示意图模型自身不能创建或编辑白板。回复经toUIMessageStreamResponse以流式 UI 消息返回前端 ChatMessage.tsx 用react-markdown渲染文本部分。6. 历史消息中的图片回看聊天记录里的白板图片都带有providerMetadata.tldraw快照。点击图片时ChatMessage.tsx 会优先把快照交给白板弹窗onImageClick触发openWhiteboard实现点击历史图片 → 在白板中继续编辑 → 重新加入对话的闭环若图片没有 tldraw 快照例如普通上传图则先用FileHelpers.urlToBlob转成File再传入白板。图片上传的工程细节绕开 4.5MB 限制多模态消息必然涉及图片字节流。模板的 uploadMessageContents.ts 注释解释了关键约束与对策Vercel 限制请求体最大 4.5MB因此图片不能直接塞进聊天请求而是改走/api/upload上传到 Google GenAI 文件服务Google 只保存文件 24 小时Google 托管的是私有 URL不能直接用于前端img展示。解决方案是一图两版发送给服务端的版本用data:URL 换成 Google 返回的uploadedUrl并剔除tldraw等 providerMetadata本地保存的版本保留原始 URL 用于 UI 展示同时把上传元数据uploadedUrl、expiresAt暂存在providerMetadata.tldraw_uploaded中。下次发送时若上传未过期expiresAt now则直接复用过期则重新上传——这就是useChatMessageStorage里消息可长期复用、图片仍能显示的原因。对应的 upload/route.ts 读取content-type与x-file-name请求头缺失返回 400然后用GoogleGenAI的files.upload上传并返回{ uploadedUrl, expiresAt }。上传所用依赖FileHelpers.urlToBlob来自 tldraw 的tldraw/utils在 packages/utils 中实现负责把 data URL 还原为 Blob。消息持久化浏览器本地的聊天记忆useChatMessageStorage.tsx 用浏览器 Origin Private File SystemOPFS把聊天记录存为chat-messages.json。代码注释说明了选型理由OPFS 容量比 localStorage 大且比 IndexedDB 更易用。加载navigator.storage.getDirectory()→getFileHandle(chat-messages.json)→FileHelpers.blobToText读出文本 →JSON.parse→ 用 AI SDK 的validateUIMessages校验后作为initialMessages保存Chat.tsx中监听chat.status ready在每次对话完成后把chat.messages写入文件createWritable({ keepExistingData: false })覆盖写。当消息为空时界面进入空聊天态标题显示 How can I help?输入框居中展示有历史消息时则切换到聊天头含清空按钮ClearChatIcon 消息列表 底部输入区的标准布局。状态管理一个 Reducer 管住所有输入态输入区相关的全部状态都被收拢在 useChatInputState.ts 的chatInputReducer中动作类型覆盖了完整交互矩阵setInput更新文本输入值setImage按id新增或更新输入区的图片去重逻辑存在则替换不存在则追加removeImage/clear删除单张图片 / 清空全部输入openWhiteboard携带snapshot、id、uploadedFile、imageName/closeWhiteboard打开与关闭白板弹窗snapshot的存在让历史图片重新编辑成为可能dragEnter/dragLeave/drop拖拽上传的三态流转drop直接把文件存入openWhiteboard触发白板。Chat.tsx的拖拽处理器还做了细节防御仅在拖入的是文件dataTransfer.types.includes(Files)且白板未打开时才进入拖拽态drop时校验file.type.startsWith(image/)非图片则退出拖拽态。可扩展方向基于模板源码可以自然延伸出以下改造点更换模型修改 chat 路由 的google(gemini-3.7-flash)为其他 Vercel AI SDK 提供商模型并同步调整系统提示词更换文件托管/api/upload的 Google GenAI 上传可替换为任意对象存储S3、R2 等只需保持返回{ uploadedUrl, expiresAt }的结构前端uploadMessageContents无需改动开放画布给模型当前系统提示词明确禁止模型操作白板若想让 AI 反向生成草图可在此基础上接入 tldraw 的文档快照写入能力如editor.loadSnapshot自行扩展自定义画布选项WhiteboardModal中的TldrawOptionsmaxPages、actionShortcutsLocation、maxFontsToLoadBeforeRender是理解 tldraw 配置入口的良好起点可依需调整。许可证说明模板以 MIT 协议发布见 templates/chat/LICENSE.mdtldraw SDK 本身遵循仓库根目录 LICENSE.md 的 tldraw 许可tldraw 名称与 Logo 为 tldraw Inc. 的商标使用需遵守 TRADEMARKS.md 中的商标指南。【免费下载链接】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），仅供参考