macshot开发指南基于Tool Handler模式为截屏工具添加一个新标注工具【免费下载链接】macshotFeature-packed native macOS screenshot recording tool: annotate, auto-redact PII, record GIFs, OCR translate, scroll capture, beautify, and more. No Electron, no subscription.项目地址: https://gitcode.com/gh_mirrors/mac/macshotmacshot 是一款功能丰富的原生 macOS 截屏与录屏工具支持标注、PII 自动脱敏、GIF 录制、OCR 翻译、滚动截屏等功能无 Electron、无订阅。它的标注系统箭头、矩形、画笔、马赛克等采用一套清晰的Tool Handler 模式每个工具是一个独立的小文件只负责按下—拖动—抬起三个动作画布状态由统一的AnnotationCanvas协议暴露。理解这套模式后你只需四步就能为 macshot 截屏工具添加自己的新标注工具。一、先理解 Tool Handler 模式的两个协议macshot 把工具拆成了两部分都在 AnnotationToolHandler.swift 中定义协议职责AnnotationCanvas画布视图遵守的协议向工具暴露共享状态当前颜色、线宽、annotations数组、撤销栈、对齐吸附辅助线等。工具拿不到整个OverlayView只看见它需要的那部分AnnotationToolHandler每个工具遵守的协议只有 4 个成员tool属于哪个工具枚举值、start鼠标按下创建标注、update拖动中更新、finish抬起后提交finish阶段最常用的是协议扩展里提供的commitAnnotation(_:canvas:)它会处理入撤销栈、清空活动标注、增量更新标注图层缓存等收尾工作——新工具直接调用它就自动获得了撤销/重做能力。二、添加新标注工具的完整四步第 1 步在 AnnotationTool 枚举中注册工具所有工具共用一个枚举 AnnotationTool它同时是工具身份、工具栏按钮和序列化持久化的依据enum AnnotationTool: Int, CaseIterable { case pencil // freeform draw case line case arrow // ...在这里添加例如 case crosshair // 自定义十字线工具 }第 2 步编写你的 Handler 类新建一个macshot/UI/Tools/下的文件参考最简范本 ArrowToolHandler.swift。核心骨架如下final class CrosshairToolHandler: AnnotationToolHandler { let tool: AnnotationTool .crosshair func start(at point: NSPoint, canvas: AnnotationCanvas) - Annotation? { let ann Annotation(tool: .crosshair, startPoint: point, endPoint: point, color: canvas.opacityAppliedColor(for: .crosshair), strokeWidth: canvas.currentStrokeWidth) return ann } func update(to point: NSPoint, shiftHeld: Bool, canvas: AnnotationCanvas) { guard let ann canvas.activeAnnotation else { return } ann.endPoint point // 拖动时实时刷新 } func finish(canvas: AnnotationCanvas) { guard let ann canvas.activeAnnotation else { return } commitAnnotation(ann, canvas: canvas) // 免费获得撤销栈支持 } }三个小技巧均来自现有 Handler 的成熟做法按住 Shift 吸附 45°文件内提供了snap45(_:)与snapSquare(_:)两个工具函数直接调用即可智能对齐辅助线canvas.snapPoint(_:excluding:)可让新标注自动对齐到已有标注的边缘与中线点击太短视为误触在finish中判断位移小于 2pt 就直接丢弃避免误点留下小残点。第 3 步把 Handler 注册进工具字典OverlayView.swift 中有一个按工具枚举分发的字典把新 Handler 加进数组即可let handlers: [AnnotationToolHandler] [ PencilToolHandler(), MarkerToolHandler(), // ... CrosshairToolHandler(), ]注册完成后画布上选中新工具时的点击、拖动、抬起事件会自动路由到你刚写的三个方法不需要改动任何鼠标事件代码。第 4 步在工具栏加上按钮ToolbarDefinitions.swift 的bottomButtons里维护着底部工具栏的工具列表每个条目是工具、SF Symbol 图标名、本地化提示语三元组(.measure, ruler, L(Measure (px))), (.crosshair, plus.viewfinder, L(Crosshair)), // 新增一行加入AnnotationTool.allCases后ToolbarLayout 的迁移逻辑会自动把它视为新引入的工具默认对所有老用户启用无需手动改 UserDefaults。三、别忘了渲染与持久化Handler 只负责交互真正把标注画出来的是 Annotation.swift 中Annotation的绘制逻辑draw相关方法里按tool分支。若你的新图形无法复用现有分支需要在那里补一个绘制分支——矩形、椭圆、箭头等图形都能从这里抄到现成的贝塞尔路径写法。得益于Annotation的可编码设计见 AnnotationCodable.swift新标注会随截图历史、分离式编辑器窗口一起自动保存与恢复历史面板中也能正常回放四、相关文件与延伸阅读清单内容路径工具枚举与 Annotation 数据模型macshot/Model/Annotation.swiftHandler 协议与画布协议macshot/UI/Tools/AnnotationToolHandler.swift现有工具实现16 个 Handlermacshot/UI/Tools/Handler 注册与画布状态macshot/UI/Overlay/OverlayView.swift工具栏按钮定义macshot/UI/Toolbar/ToolbarDefinitions.swift工具选项行颜色/线宽控件macshot/UI/Toolbar/ToolOptionsRowView.swift历史恢复机制说明docs/history-recovery.md五、小结macshot 的 Tool Handler 模式把加一个标注工具变成了四个可预期的动作枚举注册 → 写 Handler → 加入字典 → 工具栏按钮撤销、持久化、图层缓存都由框架层统一兜底。建议先从最简单的LineToolHandler读起它不到 50 行是理解整套模式的最佳入口。动手试试吧——下一个出现在 macshot 工具栏里的按钮可能就是你的作品 ✨【免费下载链接】macshotFeature-packed native macOS screenshot recording tool: annotate, auto-redact PII, record GIFs, OCR translate, scroll capture, beautify, and more. No Electron, no subscription.项目地址: https://gitcode.com/gh_mirrors/mac/macshot创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 macshot开发指南：基于Tool Handler模式为截屏工具添加一个新标注工具
macshot开发指南基于Tool Handler模式为截屏工具添加一个新标注工具【免费下载链接】macshotFeature-packed native macOS screenshot recording tool: annotate, auto-redact PII, record GIFs, OCR translate, scroll capture, beautify, and more. No Electron, no subscription.项目地址: https://gitcode.com/gh_mirrors/mac/macshotmacshot 是一款功能丰富的原生 macOS 截屏与录屏工具支持标注、PII 自动脱敏、GIF 录制、OCR 翻译、滚动截屏等功能无 Electron、无订阅。它的标注系统箭头、矩形、画笔、马赛克等采用一套清晰的Tool Handler 模式每个工具是一个独立的小文件只负责按下—拖动—抬起三个动作画布状态由统一的AnnotationCanvas协议暴露。理解这套模式后你只需四步就能为 macshot 截屏工具添加自己的新标注工具。一、先理解 Tool Handler 模式的两个协议macshot 把工具拆成了两部分都在 AnnotationToolHandler.swift 中定义协议职责AnnotationCanvas画布视图遵守的协议向工具暴露共享状态当前颜色、线宽、annotations数组、撤销栈、对齐吸附辅助线等。工具拿不到整个OverlayView只看见它需要的那部分AnnotationToolHandler每个工具遵守的协议只有 4 个成员tool属于哪个工具枚举值、start鼠标按下创建标注、update拖动中更新、finish抬起后提交finish阶段最常用的是协议扩展里提供的commitAnnotation(_:canvas:)它会处理入撤销栈、清空活动标注、增量更新标注图层缓存等收尾工作——新工具直接调用它就自动获得了撤销/重做能力。二、添加新标注工具的完整四步第 1 步在 AnnotationTool 枚举中注册工具所有工具共用一个枚举 AnnotationTool它同时是工具身份、工具栏按钮和序列化持久化的依据enum AnnotationTool: Int, CaseIterable { case pencil // freeform draw case line case arrow // ...在这里添加例如 case crosshair // 自定义十字线工具 }第 2 步编写你的 Handler 类新建一个macshot/UI/Tools/下的文件参考最简范本 ArrowToolHandler.swift。核心骨架如下final class CrosshairToolHandler: AnnotationToolHandler { let tool: AnnotationTool .crosshair func start(at point: NSPoint, canvas: AnnotationCanvas) - Annotation? { let ann Annotation(tool: .crosshair, startPoint: point, endPoint: point, color: canvas.opacityAppliedColor(for: .crosshair), strokeWidth: canvas.currentStrokeWidth) return ann } func update(to point: NSPoint, shiftHeld: Bool, canvas: AnnotationCanvas) { guard let ann canvas.activeAnnotation else { return } ann.endPoint point // 拖动时实时刷新 } func finish(canvas: AnnotationCanvas) { guard let ann canvas.activeAnnotation else { return } commitAnnotation(ann, canvas: canvas) // 免费获得撤销栈支持 } }三个小技巧均来自现有 Handler 的成熟做法按住 Shift 吸附 45°文件内提供了snap45(_:)与snapSquare(_:)两个工具函数直接调用即可智能对齐辅助线canvas.snapPoint(_:excluding:)可让新标注自动对齐到已有标注的边缘与中线点击太短视为误触在finish中判断位移小于 2pt 就直接丢弃避免误点留下小残点。第 3 步把 Handler 注册进工具字典OverlayView.swift 中有一个按工具枚举分发的字典把新 Handler 加进数组即可let handlers: [AnnotationToolHandler] [ PencilToolHandler(), MarkerToolHandler(), // ... CrosshairToolHandler(), ]注册完成后画布上选中新工具时的点击、拖动、抬起事件会自动路由到你刚写的三个方法不需要改动任何鼠标事件代码。第 4 步在工具栏加上按钮ToolbarDefinitions.swift 的bottomButtons里维护着底部工具栏的工具列表每个条目是工具、SF Symbol 图标名、本地化提示语三元组(.measure, ruler, L(Measure (px))), (.crosshair, plus.viewfinder, L(Crosshair)), // 新增一行加入AnnotationTool.allCases后ToolbarLayout 的迁移逻辑会自动把它视为新引入的工具默认对所有老用户启用无需手动改 UserDefaults。三、别忘了渲染与持久化Handler 只负责交互真正把标注画出来的是 Annotation.swift 中Annotation的绘制逻辑draw相关方法里按tool分支。若你的新图形无法复用现有分支需要在那里补一个绘制分支——矩形、椭圆、箭头等图形都能从这里抄到现成的贝塞尔路径写法。得益于Annotation的可编码设计见 AnnotationCodable.swift新标注会随截图历史、分离式编辑器窗口一起自动保存与恢复历史面板中也能正常回放四、相关文件与延伸阅读清单内容路径工具枚举与 Annotation 数据模型macshot/Model/Annotation.swiftHandler 协议与画布协议macshot/UI/Tools/AnnotationToolHandler.swift现有工具实现16 个 Handlermacshot/UI/Tools/Handler 注册与画布状态macshot/UI/Overlay/OverlayView.swift工具栏按钮定义macshot/UI/Toolbar/ToolbarDefinitions.swift工具选项行颜色/线宽控件macshot/UI/Toolbar/ToolOptionsRowView.swift历史恢复机制说明docs/history-recovery.md五、小结macshot 的 Tool Handler 模式把加一个标注工具变成了四个可预期的动作枚举注册 → 写 Handler → 加入字典 → 工具栏按钮撤销、持久化、图层缓存都由框架层统一兜底。建议先从最简单的LineToolHandler读起它不到 50 行是理解整套模式的最佳入口。动手试试吧——下一个出现在 macshot 工具栏里的按钮可能就是你的作品 ✨【免费下载链接】macshotFeature-packed native macOS screenshot recording tool: annotate, auto-redact PII, record GIFs, OCR translate, scroll capture, beautify, and more. No Electron, no subscription.项目地址: https://gitcode.com/gh_mirrors/mac/macshot创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考