ScreenPin 是我用 Tauri 2、React 和 TypeScript 写的截图编辑器。核心需求是箭头、文字和高亮保存后还能继续修改,这决定了数据模型不能只存一张合成后的图片。
本系列第一篇从工程结构入手,解释原图、标注对象和导出图片之间的关系。坐标变换与拖拽性能、Wayland 快捷键分别放到后两篇。
一、原图和标注分开保存
如果画一条箭头就直接修改原图像素,下次打开导出的图片,箭头已经成为图片的一部分。可以撤销当前操作,却很难在关闭应用后继续修改。
ScreenPin 因此把原图和标注分开保存。原图提供背景,标注保存类型、坐标、颜色、线宽、透明度和顺序,在编辑阶段由 SVG 展示。
当前支持矩形、椭圆、箭头、画笔、荧光笔、区域高亮、文字和马赛克。选中后可以移动、缩放、改样式或调整图层。
.screenpin 工程是版本化 JSON,保留原图和标注对象。下面是删去部分字段后的结构示意:
{
"format": "screenpin-project",
"version": 1,
"image": {
"dataUrl": "...",
"width": 1920,
"height": 1080,
"name": "screenshot.png"
},
"annotations": [
{
"id": "arrow-1",
"type": "arrow",
"x": 120,
"y": 80,
"endX": 420,
"endY": 250
}
]
}
这段示意不能直接作为完整工程导入;实际文件还包含时间、标题和完整样式等字段。
导出 PNG、JPEG 或 WebP 时,再把原图和对象合成一张图片。因此,导出用于分享,保存工程用于继续编辑。导出了图片,不应自动清除“工程尚未保存”的提示。
src/types.ts 中,工程的核心数据关系如下,省略时间和标题字段:
interface ScreenPinProject {
format: 'screenpin-project';
version: 1;
image: ImageSource;
annotations: Annotation[];
}
对象数组同时保存图层顺序,所以调整层级可以改变数组顺序,不必修改原图。撤销、重做和工程保存围绕同一份标注数据展开,而导出只是把这份数据渲染成位图的另一个出口。
二、导出失败时,不能继续生成错误文件
工程和导出也补了一些边界处理。
打开工程时会实际解码图片,核对真实尺寸,并验证标注类型、数值范围、对象 ID 和时间字段。仅仅能解析 JSON,不足以说明工程有效。
马赛克纹理生成失败时,项目会阻止相关导出,避免把未遮挡的原图作为结果写出去。但可编辑工程仍然保留原图,马赛克对象不能把工程里的原始内容删除。分享时应导出检查后的图片;需要彻底移除敏感内容时,应先移除相应区域。
JPEG 编码前铺白底,处理不支持透明通道的情况;如果请求 WebP 等格式时浏览器实际回退成 PNG,则报错,避免文件扩展名与内容不一致。
这些行为都围绕一个要求:写出的文件要符合用户选择,失败时要有明确结果。
三、用同一份模型连接编辑和导出
读代码可以从 src/types.ts 中的 ScreenPinProject 与 Annotation 开始,再看画布如何把对象渲染为 SVG。导出阶段会克隆 SVG,移除选择框和编辑元素,再通过 Canvas 编码成位图。
工程保存保留数据结构,图片导出生成分享结果,两者必须有不同的未保存状态判断。模型和导出逻辑在当前 Linux 环境有自动化验证记录,但本文没有重新执行这些检查,也不代表其他平台的完整桌面验收。
本系列对应仓库目前为私有,代码片段取自已核对的实现;删去的字段或流程已在相关段落注明。