如何让 Quickdraw 白板内容永不丢失:完整持久化方案指南
如何让 Quickdraw 白板内容永不丢失:完整持久化方案指南
Quickdraw 是一款 MIT 协议的开源无限画布白板 SDK(tldraw 的免费替代品),支持 React、React Native 和原生 JavaScript。很多新手最担心的一件事就是:用户画了半天,刷新页面内容全没了? 本指南给出 Quickdraw 白板内容持久化的完整方案——从浏览器本地存储(localStorage)自动保存,到 React 组件两个属性搞定,再到数据库云端保存,让你彻底告别白板数据丢失。
一、核心原理:整个白板就是一个纯 JSON 对象
Quickdraw 的持久化设计非常友好:没有复杂的序列化格式,整个文档就是一个普通 JSON 对象。
在数据模型层面,白板由一条条不可变记录(笔画、图形、文本、图片)组成,存储在 Store 中。任何一次修改都会产生一个纯 JSON 的 diff(增量),而完整文档则通过快照(snapshot)表达:
store.getSnapshot()—— 取回整个文档,返回{ document: { store: { id: record } } }结构的 JSONstore.loadSnapshot(snap, 'remote')—— 用快照整体恢复文档
这两个方法就定义在 store.js 中,实现一目了然。
💡 第二个参数
source传'remote'很关键:恢复操作不会被计入撤销(Undo)历史,避免用户按 Ctrl+Z 时把刚恢复的文档"撤销没"。
二、方案一:localStorage 自动保存 + 刷新自动恢复
最轻量的做法:每次内容变化就存到浏览器本地,下次打开自动恢复。核心套路是"变化时保存,加载时恢复",并加 400ms 防抖避免高频写入。
原生 JS 下大概只需要 10 行:
const { store } = board.editor
// 恢复:读取后加载快照,并自动适配视图
const saved = localStorage.getItem('doc')
if (saved) {
store.loadSnapshot(JSON.parse(saved), 'remote')
board.editor.fitContent()
}
// 保存:监听变化,防抖后写入
let t
store.listen(() => {
clearTimeout(t)
t = setTimeout(() => {
localStorage.setItem('doc', JSON.stringify(store.getSnapshot()))
}, 400)
})
⚠️ 注意容量上限:大多数浏览器对 localStorage 的限制约为 5 MB。由于粘贴/拖入的图片会以压缩后的 data URL 形式直接存在文档里(快照完全自包含,无需单独管理素材),如果用户经常粘贴大截图,建议改用下面的数据库方案。
三、方案二:React 组件只需两个属性
如果你用 React 版(@quickdrawjs/react),同样的模式浓缩为 snapshot + onChange 两个属性:
<Quickdraw
snapshot={saved} // 挂载时自动恢复
autoFit // 恢复后自动缩放适配内容
onChange={(diff, source, editor) =>
debouncedSave(editor.store.getSnapshot())} // 每次变化防抖保存
/>
组件内部会在挂载时调用 loadSnapshot 恢复文档(见 index.js),之后通过 onChange 回调把每次变化交给你处理。对于需要文档生命周期长于组件的场景(多视图共享、渲染前预加载),还可以用 useQuickdrawStore 传外部 store,细节见 react.mdx。
四、方案三:保存到数据库,多设备、多用户永不丢
快照是标准 JSON 对象,可以原样放进任何存储:PostgreSQL 的 jsonb 列、MongoDB 文档库、S3 对象存储都行。典型的服务端往返:
// 保存:整个快照 PUT 上去
await fetch(`/api/boards/${id}`, {
method: 'PUT',
headers: { 'content-type': 'application/json' },
body: JSON.stringify(store.getSnapshot()),
})
// 加载:取回快照后整体恢复
const snap = await fetch(`/api/boards/${id}`).then((r) => r.json())
store.loadSnapshot(snap, 'remote')
这样做的好处:
- 🔄 跨设备同步:手机上画一半,电脑上无缝续画
- 🧑🤝🧑 多人协作:配合 diff 广播即可实现实时协作(
store.listen过滤source === 'user'只广播本地修改,防止回环) - 🗄️ 不受 5 MB 限制,大截图、大画板都能存
五、超大白板进阶:只存增量 diff
对于非常大的白板,可以不用每次存全量快照,而是持久化 diff 流——每次修改都是一个小 JSON 增量,重放这些增量即可重建文档:
import { applyDiff, composeDiff } from '@quickdrawjs/core'
diff 的结构是 { added, removed, updated },天然支持 invertDiff(撤销)和 composeDiff(合并连续修改为一个操作)。把 diff 流记录下来,你还能逐笔画回放整块白板的编辑过程。完整数据结构说明见 data-model.mdx。
六、避免数据丢失的 5 条实用建议
- 务必防抖:一笔自由手绘会产生几十次 pointer 事件,直接同步保存会卡死页面,400ms 左右的防抖是安全值
- 恢复用
'remote'来源:loadSnapshot(snap, 'remote')保证恢复不进撤销栈 - 恢复后调用
fitContent():让镜头自动缩放适配内容,避免用户打开白板后看到空白区域 - 估算快照体积:图片存在文档内部,快照自包含但也意味着体积随行;大图片场景优先数据库
- 提供导出兜底:工具栏默认支持整板/选区导出 PNG(文件名形如
quickdraw-<时间戳>.png),可用onSave回调拦截上传到自己的服务器,作为最终备份
更多细节可参考官方文档 persistence.mdx 与 data-model.mdx,以及核心引擎源码 store.js。

