开发网页在线绘图工具,如何保存画布状态并在刷新后还原图形?
刷新网页后,canvas 往往会重新变成空白,并不是绘图指令失效,而是画布中的像素和 JavaScript 内存都会随着页面重新加载被销毁。要实现刷新后还原图形,需要在绘制过程中保存一份可重新绘制的数据,并在页面初始化时读取数据、重新执行绘制流程。
实际项目中,建议保存“图形对象数据”,而不是只保存画布截图。这样不仅能恢复画面,还能继续支持撤销、编辑、移动、修改颜色和调整尺寸。
先确定保存像素还是保存绘图状态
Canvas 属于即时绘图模型。调用 fillRect()、stroke() 或 drawImage() 后,浏览器只保留当前画布像素,并不会自动记录“这些像素是由哪些图形生成的”。
常见保存方式有三种:
| 保存方式 | 主要内容 | 刷新后的恢复方式 | 适用场景 |
|---|---|---|---|
| 保存图形对象 | 线条、矩形、文字、图片等结构化数据 | 读取 JSON 后重新绘制 | 需要编辑、撤销或继续绘图 |
| 保存 PNG 或 JPEG | 当前画布的像素快照 | 创建图片后绘制到 Canvas | 只需要展示或导出最终效果 |
| 图形对象加图片资源 | 图形 JSON 与图片地址、资源编号 | 先加载资源,再按顺序绘制 | 在线白板、流程图、设计编辑器 |
例如,下面这种数据可以描述一个简单画布:

{
"version": 1,
"width": 900,
"height": 600,
"items": [
{
"type": "stroke",
"color": "#1f2937",
"lineWidth": 4,
"points": [
{ "x": 120, "y": 100 },
{ "x": 130, "y": 108 },
{ "x": 145, "y": 121 }
]
},
{
"type": "rect",
"x": 300,
"y": 180,
"width": 160,
"height": 90,
"color": "#2563eb",
"lineWidth": 3
}
]
}
截图方式实现简单,但存在几个限制:
- 无法直接知道图片中有哪些独立图形;
- 不能只选中某一个矩形进行移动;
- 撤销通常只能恢复整张图片;
- 图片尺寸较大时,数据量会明显增加;
- 如果画布中有跨域图片,导出图片还可能受到 Canvas 跨域限制。
因此,本文使用“图形对象 JSON + 重绘函数”的方式保存状态。PNG 导出可以作为额外功能,而不作为恢复画布的主要数据来源。
让保存数据独立于 Canvas 像素
保存的数据最好使用逻辑坐标,例如画布设计尺寸固定为 900 × 600。页面显示时,可以根据容器宽度缩放;用户操作时,再把鼠标或触摸坐标转换回逻辑坐标。
这样处理有两个好处:
- 页面在不同屏幕尺寸下显示时,图形不会因为 CSS 缩放而改变数据;
- 高分辨率屏幕上的
devicePixelRatio变化,不会导致图形位置发生偏移。
数据结构建议至少包含以下内容:
version:数据版本,方便以后升级格式;width、height:逻辑画布尺寸;items:所有图形对象;type:对象类型,如stroke、rect、text或image;- 对象的坐标、颜色、线宽和其他绘制参数。
不要直接把以下对象保存到 localStorage:
CanvasRenderingContext2D;Image实例;- DOM 节点;
- 事件对象;
- JavaScript 函数。
这些对象不能通过 JSON 正确恢复。应当保存它们对应的普通数据,例如图片地址、文字内容和坐标,恢复时重新创建运行时对象。
用 localStorage 实现刷新后恢复
如果需求只是“同一浏览器、同一个网站中刷新后继续编辑”,可以先使用 localStorage。它保存的是字符串,因此需要在写入时调用 JSON.stringify(),读取时调用 JSON.parse()。
下面是一份可以直接放入网页中运行的最小示例。示例包含画笔、矩形、撤销和清空功能,并将每个已经完成的图形保存到浏览器本地。

<!doctype html>
<html lang="zh-CN">
<head>
<meta charset="UTF-8">
<meta name="viewport" content="width=device-width, initial-scale=1">
<title>Canvas 状态恢复示例</title>
<style>
* {
box-sizing: border-box;
}
body {
margin: 24px;
color: #1f2937;
font-family: system-ui, -apple-system, BlinkMacSystemFont, "Segoe UI", sans-serif;
}
.toolbar {
display: flex;
flex-wrap: wrap;
align-items: center;
gap: 12px;
margin-bottom: 14px;
}
.toolbar label {
display: inline-flex;
align-items: center;
gap: 6px;
}
.toolbar button,
.toolbar select,
.toolbar input {
font: inherit;
}
#status {
color: #64748b;
font-size: 14px;
}
#board {
display: block;
width: min(100%, 900px);
height: auto;
border: 1px solid #cbd5e1;
border-radius: 6px;
background: #ffffff;
touch-action: none;
}
</style>
</head>
<body>
<div class="toolbar">
<label>
工具
<select id="tool">
<option value="pen">画笔</option>
<option value="rect">矩形</option>
</select>
</label>
<label>
颜色
<input id="color" type="color" value="#1f2937">
</label>
<label>
线宽
<input id="size" type="range" min="1" max="40" value="4">
</label>
<button id="undo" type="button">撤销</button>
<button id="clear" type="button">清空</button>
<span id="status" role="status"></span>
</div>
<canvas id="board" width="900" height="600"></canvas>
<script>
(() => {
const STORAGE_KEY = "canvas-scene-demo:v1";
const canvas = document.querySelector("#board");
const ctx = canvas.getContext("2d");
const tool = document.querySelector("#tool");
const color = document.querySelector("#color");
const size = document.querySelector("#size");
const undoButton = document.querySelector("#undo");
const clearButton = document.querySelector("#clear");
const status = document.querySelector("#status");
if (!ctx) {
status.textContent = "当前浏览器无法创建 Canvas 2D 上下文";
return;
}
let dpr = 1;
let drawing = false;
let activeItem = null;
let startPoint = null;
const scene = readScene() || {
version: 1,
width: 900,
height: 600,
items: []
};
function setStatus(message) {
status.textContent = message;
}
function setupCanvas() {
dpr = Math.max(1, window.devicePixelRatio || 1);
// backing store 使用高分辨率,逻辑坐标仍然是 900 × 600
canvas.width = Math.round(scene.width * dpr);
canvas.height = Math.round(scene.height * dpr);
render();
}
function render() {
// 后续绘制统一使用逻辑坐标
ctx.setTransform(dpr, 0, 0, dpr, 0, 0);
ctx.clearRect(0, 0, scene.width, scene.height);
ctx.fillStyle = "#ffffff";
ctx.fillRect(0, 0, scene.width, scene.height);
for (const item of scene.items) {
drawItem(item);
}
// 正在绘制的对象只作为预览,不立即写入正式数据
if (activeItem) {
drawItem(activeItem);
}
}
function drawItem(item) {
ctx.save();
if (item.type === "stroke") {
if (!Array.isArray(item.points) || item.points.length === 0) {
ctx.restore();
return;
}
ctx.strokeStyle = item.color;
ctx.fillStyle = item.color;
ctx.lineWidth = item.lineWidth;
ctx.lineCap = "round";
ctx.lineJoin = "round";
if (item.points.length === 1) {
const point = item.points[0];
ctx.beginPath();
ctx.arc(
point.x,
point.y,
item.lineWidth / 2,
0,
Math.PI * 2
);
ctx.fill();
} else {
ctx.beginPath();
ctx.moveTo(item.points[0].x, item.points[0].y);
for (let i = 1; i < item.points.length; i += 1) {
ctx.lineTo(item.points[i].x, item.points[i].y);
}
ctx.stroke();
}
}
if (item.type === "rect") {
ctx.strokeStyle = item.color;
ctx.lineWidth = item.lineWidth;
ctx.strokeRect(item.x, item.y, item.width, item.height);
}
ctx.restore();
}
function getLogicalPoint(event) {
const rect = canvas.getBoundingClientRect();
const rawX = (event.clientX - rect.left) / rect.width * scene.width;
const rawY = (event.clientY - rect.top) / rect.height * scene.height;
return {
x: Math.max(0, Math.min(scene.width, rawX)),
y: Math.max(0, Math.min(scene.height, rawY))
};
}
function getStyle() {
const lineWidth = Number(size.value) || 1;
return {
color: color.value,
lineWidth: Math.max(1, Math.min(40, lineWidth))
};
}
function startDrawing(event) {
if (!event.isPrimary) {
return;
}
if (event.button !== undefined && event.button !== 0) {
return;
}
event.preventDefault();
drawing = true;
canvas.setPointerCapture(event.pointerId);
const point = getLogicalPoint(event);
const style = getStyle();
if (tool.value === "pen") {
activeItem = {
type: "stroke",
color: style.color,
lineWidth: style.lineWidth,
points: [point]
};
} else {
startPoint = point;
activeItem = {
type: "rect",
x: point.x,
y: point.y,
width: 0,
height: 0,
color: style.color,
lineWidth: style.lineWidth
};
}
render();
}
function moveDrawing(event) {
if (!drawing || !activeItem) {
return;
}
const point = getLogicalPoint(event);
if (activeItem.type === "stroke") {
activeItem.points.push(point);
} else {
activeItem.width = point.x - startPoint.x;
activeItem.height = point.y - startPoint.y;
}
render();
}
function finishDrawing(event) {
if (!drawing) {
return;
}
drawing = false;
if (canvas.hasPointerCapture(event.pointerId)) {
canvas.releasePointerCapture(event.pointerId);
}
if (activeItem) {
const shouldCommit =
activeItem.type === "stroke"
? activeItem.points.length > 0
: Math.abs(activeItem.width) >= 1 ||
Math.abs(activeItem.height) >= 1;
if (shouldCommit) {
scene.items.push(activeItem);
saveScene();
}
}
activeItem = null;
startPoint = null;
render();
}
function cancelDrawing(event) {
if (!drawing) {
return;
}
drawing = false;
if (canvas.hasPointerCapture(event.pointerId)) {
canvas.releasePointerCapture(event.pointerId);
}
activeItem = null;
startPoint = null;
render();
}
function saveScene() {
try {
const serialized = JSON.stringify(scene);
localStorage.setItem(STORAGE_KEY, serialized);
setStatus(`已保存 ${new Date().toLocaleTimeString()}`);
return true;
} catch (error) {
console.error(error);
setStatus("保存失败:浏览器存储不可用或空间不足");
return false;
}
}
function readScene() {
try {
const raw = localStorage.getItem(STORAGE_KEY);
if (!raw) {
return null;
}
const data = JSON.parse(raw);
if (!validScene(data)) {
setStatus("本地画布数据格式无效,已使用空白画布");
return null;
}
return data;
} catch (error) {
console.error(error);
setStatus("读取本地画布失败,已使用空白画布");
return null;
}
}
function validScene(data) {
if (!data || data.version !== 1) {
return false;
}
if (
!Number.isFinite(data.width) ||
!Number.isFinite(data.height) ||
data.width <= 0 ||
data.height <= 0 ||
data.width > 5000 ||
data.height > 5000
) {
return false;
}
if (!Array.isArray(data.items) || data.items.length > 5000) {
return false;
}
return data.items.every((item) => {
if (
item.type === "stroke" &&
typeof item.color === "string" &&
Number.isFinite(item.lineWidth) &&
item.lineWidth >= 1 &&
item.lineWidth <= 100 &&
Array.isArray(item.points) &&
item.points.length > 0 &&
item.points.length <= 100000
) {
return item.points.every((point) => {
return (
point &&
Number.isFinite(point.x) &&
Number.isFinite(point.y) &&
point.x >= 0 &&
point.x <= data.width &&
point.y >= 0 &&
point.y <= data.height
);
});
}
if (
item.type === "rect" &&
typeof item.color === "string" &&
Number.isFinite(item.lineWidth) &&
item.lineWidth >= 1 &&
item.lineWidth <= 100 &&
Number.isFinite(item.x) &&
Number.isFinite(item.y) &&
Number.isFinite(item.width) &&
Number.isFinite(item.height)
) {
return (
item.x >= 0 &&
item.x <= data.width &&
item.y >= 0 &&
item.y <= data.height &&
Math.abs(item.width) <= data.width &&
Math.abs(item.height) <= data.height
);
}
return false;
});
}
undoButton.addEventListener("click", () => {
if (scene.items.length === 0) {
return;
}
scene.items.pop();
saveScene();
render();
});
clearButton.addEventListener("click", () => {
if (scene.items.length === 0) {
return;
}
const confirmed = window.confirm(
"确定清空当前画布吗?清空后会覆盖本地保存的数据。"
);
if (!confirmed) {
return;
}
scene.items = [];
saveScene();
render();
});
canvas.addEventListener("pointerdown", startDrawing);
canvas.addEventListener("pointermove", moveDrawing);
canvas.addEventListener("pointerup", finishDrawing);
canvas.addEventListener("pointercancel", cancelDrawing);
window.addEventListener("resize", setupCanvas);
setupCanvas();
setStatus(
scene.items.length > 0
? `已恢复 ${scene.items.length} 个图形`
: "当前为新画布"
);
})();
</script>
</body>
</html>
这段代码的核心不是工具栏,而是以下几个处理过程:

- 页面加载时调用
readScene(); - 读取并校验 JSON;
- 将数据放入
scene.items; - 调用
render()遍历所有图形; - 每次完成一条线或一个矩形后调用
saveScene(); - 刷新页面时再次读取相同数据。
为什么要在 pointerup 时保存
画笔绘制过程中,pointermove 事件可能在很短时间内触发数十次甚至更多。如果每次移动都执行:
localStorage.setItem(key, JSON.stringify(scene));
就会频繁进行 JSON 序列化和同步存储,复杂画布可能出现输入延迟。
示例代码在 pointerup 时才把当前对象加入 scene.items,因此一次完整操作只保存一次。这种方式适合线条、矩形、圆形等“完成后提交”的对象。
如果项目中的对象会在拖拽过程中持续修改,例如移动已有图形、旋转对象或调整尺寸,可以采用延迟保存:
let saveTimer = null;
function scheduleSave() {
window.clearTimeout(saveTimer);
saveTimer = window.setTimeout(() => {
saveScene();
}, 300);
}
拖拽过程中只更新内存中的 scene 并重新渲染,拖拽停止后再调用 scheduleSave()。这样可以减少存储操作,同时保留较好的恢复能力。
需要注意,示例中的策略只会保存已经完成的对象。如果用户正在绘制一条线时直接刷新页面,这条尚未触发 pointerup 的线可能不会保存。若这类场景不能接受,可以单独保存一个 draft 草稿对象,或者在绘制过程中使用节流后的临时保存。
Canvas 尺寸、CSS 尺寸和高清屏处理
代码中有两组尺寸:
canvas.width = scene.width * dpr;
canvas.height = scene.height * dpr;
这里的 canvas.width 和 canvas.height 是实际像素缓冲区尺寸。与此同时,绘制代码使用的仍然是 900 × 600 的逻辑坐标:
ctx.setTransform(dpr, 0, 0, dpr, 0, 0);
如果设备像素比为 2,画布实际可能使用 1800 × 1200 的像素缓冲区,但逻辑坐标仍然是:
左上角:0, 0
右下角:900, 600
鼠标坐标也必须转换为逻辑坐标。示例中的 getLogicalPoint() 使用 Canvas 在页面中的实际显示区域进行比例换算:
const rawX = (event.clientX - rect.left) / rect.width * scene.width;
const rawY = (event.clientY - rect.top) / rect.height * scene.height;
如果直接把 clientX 和 clientY 保存下来,窗口缩放、移动设备显示或高分辨率屏幕都可能造成图形偏移。
对于响应式画布,推荐保存设计坐标,而不是保存页面中的 CSS 像素坐标。这样画布即使从桌面端缩小到手机端,数据仍然可以继续使用。
处理数据版本和损坏数据
示例中使用了:
{
"version": 1
}
这是为了给后续格式升级留下空间。例如,第一版矩形使用 width 和 height,以后可能改成两个角点;文字对象也可能增加字体、对齐方式和旋转角度。如果直接修改旧数据结构,旧用户的本地数据可能无法读取。
更稳妥的做法是根据版本执行迁移:
function migrateScene(data) {
if (!data || !Number.isFinite(data.version)) {
return null;
}
if (data.version === 1) {
return data;
}
if (data.version === 2) {
return {
version: 1,
width: data.canvasWidth,
height: data.canvasHeight,
items: data.objects
};
}
return null;
}
实际项目中不应无条件信任本地存储内容。虽然这些数据通常由当前网站自己写入,但同源脚本、浏览器扩展或手动修改都可能让数据变得异常。至少应检查:
version是否是支持的版本;- 画布宽高是否在合理范围;
- 图形数量是否超过上限;
- 点数量是否过大;
- 坐标和线宽是否为有限数字;
- 图形类型是否属于允许的集合。
如果数据格式无效,应该跳过这份数据并显示提示,不要让一次解析错误阻止整个页面初始化。
增加文字、图片和其他图形
文字对象
文字不应只保存绘制后的像素,而应保存文字本身和绘制参数:
{
"type": "text",
"text": "在线绘图",
"x": 120,
"y": 100,
"fontSize": 24,
"fontFamily": "Arial",
"color": "#111827",
"align": "left"
}
恢复时根据这些字段重新设置 Canvas 状态:
function drawText(item) {
ctx.save();
ctx.fillStyle = item.color;
ctx.font = `${item.fontSize}px ${item.fontFamily}`;
ctx.textAlign = item.align || "left";
ctx.textBaseline = "alphabetic";
ctx.fillText(item.text, item.x, item.y);
ctx.restore();
}
如果使用网络字体,必须考虑字体尚未加载完成的情况。字体加载前后,文字宽度可能不同,导致换行、对齐和位置发生变化。需要等待字体加载完成后再进行最终渲染,或者使用项目能够稳定提供的字体。
图片对象
图片对象应保存资源标识和显示区域,而不是保存 Image 实例:
{
"type": "image",
"src": "/uploads/example.png",
"x": 80,
"y": 120,
"width": 240,
"height": 160
}
恢复过程通常是异步的:
function loadImage(item) {
return new Promise((resolve, reject) => {
const image = new Image();
image.onload = () => {
resolve({
item,
image
});
};
image.onerror = reject;
image.src = item.src;
});
}
读取场景后,应先加载所有图片,再执行最终绘制。否则页面可能先恢复线条和矩形,但图片在稍后才出现,用户会看到短暂的不完整画面。
如果图片来自其他域名,还要确认图片服务器允许当前页面跨域读取。否则图片可能能够显示,但画布导出为 PNG 时会触发安全限制。图片资源来自用户上传时,建议保存资源编号或受控地址,不要直接把未经检查的外部地址当作可信数据。
localStorage、IndexedDB 和服务端如何选择
localStorage 适合保存少量、结构简单的绘图状态,但不应把它当作所有场景的永久数据库。

| 方案 | 适合情况 | 主要限制 |
|---|---|---|
localStorage | 小型画布、单设备恢复、少量图形 | 同步读写、容量受浏览器配额限制、不能直接存对象 |
| IndexedDB | 较大的图形 JSON、撤销历史、图片 Blob | API 异步,封装和调试成本更高 |
| 服务端数据库 | 登录用户、跨设备访问、团队协作 | 需要接口、权限控制、冲突处理和数据校验 |
localStorage 的容量由浏览器和站点配额决定,不应把某个固定的 MB 数当成所有环境都成立的规则。大量自由画笔点、高清图片或完整撤销历史都可能使写入失败。
当图形数据较大时,可以将对象数据存入 IndexedDB,将图片文件以 Blob 保存;如果用户需要登录后在多个设备之间继续编辑,则应把场景 JSON 保存到服务端。
服务端保存的基本形式可以是:
async function saveSceneToServer(drawingId, scene) {
const response = await fetch(
`/api/drawings/${encodeURIComponent(drawingId)}`,
{
method: "PUT",
headers: {
"Content-Type": "application/json"
},
body: JSON.stringify(scene)
}
);
if (!response.ok) {
throw new Error(`保存失败:HTTP ${response.status}`);
}
return response.json();
}
服务端不能只因为请求来自前端就信任全部字段,仍然需要验证:
- 当前用户是否有权修改这份画布;
drawingId是否属于当前用户;- 图形数量和点数量是否超过限制;
- 文本长度、图片地址和颜色字段是否符合规则;
- 是否存在旧版本覆盖新版本的问题。
如果多个页面或多个设备会同时编辑同一份画布,还需要在数据中增加修订号,例如 revision。提交时携带客户端读取到的版本,服务端发现版本已经变化时,返回冲突,而不是直接覆盖其他设备的修改。
当画布需要从浏览器本地存储扩展到服务端保存与多设备访问时,A5idc数据可提供香港、美国、日本等地区的物理服务器租用,为网页应用接口和场景数据服务提供不同的计算、存储与网络资源选择;域名和SSL证书业务可用于网站及接口的域名接入与HTTPS连接,静态画布资源也可结合CDN分发。
验证刷新恢复是否正常
可以按照下面的顺序验证:
- 打开运行页面,绘制一条线和一个矩形;
- 点击撤销,确认最后一个图形消失;
- 再绘制一个图形,确认状态栏出现保存时间;
- 刷新页面,确认之前的图形重新出现;
- 修改浏览器窗口宽度,确认图形仍然位于正确位置;
- 在移动端或触摸设备上绘制,确认页面不会因为手势滚动而中断;
- 打开浏览器开发者工具的存储面板,检查当前站点下是否存在对应键值;
- 点击清空并刷新,确认空白状态也被保存。
常见异常可以按以下方式定位:
| 现象 | 常见原因 | 处理方式 |
|---|---|---|
| 刷新后始终空白 | 页面没有写入数据,或访问了不同的协议、域名、端口 | 检查 STORAGE_KEY、当前站点来源和保存时机 |
| 只有同一页面有效,换设备没有数据 | localStorage 属于当前浏览器和当前来源 | 改用服务端保存 |
| 保存时报空间不足 | JSON、点数量或图片数据过大 | 压缩数据、减少采样点,或迁移到 IndexedDB |
| 刷新后线条位置偏移 | 保存了 CSS 坐标或没有处理设备像素比 | 统一使用逻辑坐标并在输入时换算 |
| 矩形能恢复,图片不显示 | 图片加载是异步的,渲染时资源还未准备好 | 等待图片加载完成后再渲染 |
| 正在画线时刷新,最后一条线丢失 | 代码只在 pointerup 时提交数据 | 增加草稿保存或使用节流保存 |
| 两个标签页修改后内容互相覆盖 | 两个页面都在写入同一个存储键 | 使用版本号、storage 事件或服务端冲突处理 |
还要注意来源必须一致。例如 http://localhost、http://127.0.0.1 和正式域名通常不是同一个存储空间,使用不同端口也可能得到不同的站点存储。开发阶段切换访问地址后看不到旧数据,并不一定是保存逻辑失效。
接入现有项目时的落地顺序
如果已有绘图页面,可以按这个顺序改造,而不必一次性重写整个绘图模块:
- 将现有的线条、矩形、文字等绘制操作转换为普通对象;
- 建立统一的
scene.items数据结构; - 把所有绘制逻辑集中到
render(scene); - 页面初始化时先读取数据,再调用一次
render(); - 每次完成新增、删除或修改图形后保存;
- 对本地数据增加版本号和基本校验;
- 数据量增大后再迁移到 IndexedDB 或服务端;
- 需要导出图片时,再单独调用
toBlob()或其他导出逻辑。
完成后,刷新页面不再依赖浏览器是否保留 Canvas 像素,而是依赖一份可校验、可迁移、可重新绘制的画布状态。这样后续增加撤销、图形选中、服务端同步和跨设备编辑时,都可以继续沿用同一套数据模型。
本文由A5数据原创发布,转载请注明出处:https://www.a5idc.com/helpcontent/10000.html