~/notes/screenpin-editable-annotations-and-wayland-shortcuts.md1093 字

项目实战ScreenPin 桌面编辑器学习笔记 · 01/03

ScreenPin(一):可编辑标注、工程文件与图片导出

结合 ScreenPinProject 数据模型,理解原图与标注分离,以及工程保存、图像导出和失败处理的区别。

目录 4 节

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 环境有自动化验证记录,但本文没有重新执行这些检查,也不代表其他平台的完整桌面验收。

本系列对应仓库目前为私有,代码片段取自已核对的实现;删去的字段或流程已在相关段落注明。

系列阅读

下一章:ScreenPin(二):SVG 逆矩阵与拖拽事件合并

  1. ScreenPin(一):可编辑标注、工程文件与图片导出
  2. ScreenPin(二):SVG 逆矩阵与拖拽事件合并
  3. ScreenPin(三):Wayland 快捷键授权与会话切换