高级配置 (config.toml)

概述

针对高级用户、开发者和系统管理员，Snapzy 支持使用标准的 TOML 文件 (config.toml) 进行高级编程化配置。这使你能够以纯文本形式管理所有应用程序偏好设置，使用 dotfiles 仓库进行同步，并在 macOS 环境中实现自动化部署。

初始化要求 — 由于 macOS 沙盒安全限制，Snapzy 需要一次性授予文件夹访问权限，才能读写你主目录下的文件。请在“偏好设置”的“高级”选项卡中完成此设置。

快速入门

1. 授予配置访问权限

打开 Snapzy 偏好设置 (Cmd + ,) 并导航到 高级 (Advanced) 选项卡。
点击 设置 config.toml (Set Up config.toml)。
系统将弹出原生文件对话框，提示你选择或授予配置目录的访问权限。选择配置目录（通常为 ~/.config/snapzy/）并点击 授予访问权限 (Grant Access)。

授予访问权限后，Snapzy 会在以下路径自动生成默认的 config.toml 文件：

~/.config/snapzy/config.toml

2. 同期与后台加载

启动时自动应用: Snapzy 在每次应用程序启动时解析并验证 config.toml。
后台自动同步: 应用在后台监控 config.toml 文件的更改。直接在编辑器中保存的修改会在几秒钟内自动完成验证并应用（已进行防抖处理以避免读取正在写入的残缺文件）。
手动同步: 你可以点击高级设置选项卡中的 同步 config.toml (Sync config.toml) 按钮来立即重新加载配置。
恢复默认设置: 点击 恢复默认设置 会覆盖现有的 TOML 文件，重置为出厂默认值。

完整注释的 TOML 示例

以下是包含所有可配置项和各属性注释说明的完整 config.toml 文件模板。

# Snapzy TOML 配置结构版本 (必须为 1)
schema_version = 1

# 此文件所需的最低 Snapzy 版本
snapzy_min_version = "1.20.0"

[general]
language = "system"                # "system" 或语言代码: "en", "vi", "ja", "ko", "ru", "zh", "zh-tw"
appearance = "system"              # 主题外观: "system", "light" 或 "dark"
play_sounds = true                 # 捕获或录制时播放音效
start_at_login = false             # macOS 启动时自动运行 Snapzy
export_location = "~/Pictures"     # 截图和视频的本地保存文件夹 (支持 ~ 路径展开)

[updates]
check_automatically = true         # 使用 Sparkle 自动检查更新
download_automatically = false     # 在后台自动下载更新而不显示提示

[diagnostics]
enabled = true                     # 启用本地诊断日志以进行故障排除
retention_days = 7                 # 诊断日志文件保留天数 (1 到 30 天)

[capture]
hide_desktop_icons = false         # 捕获时临时隐藏桌面图标
hide_desktop_widgets = false       # 捕获时临时隐藏桌面小部件

[capture.naming]
screenshot_template = "Snapzy_{year}-{month}-{day}_{hour}-{minute}-{second}_{milliseconds}" # 截图命名模板
recording_template = "Snapzy_{year}-{month}-{day}_{hour}-{minute}-{second}_{milliseconds}"  # 视频命名模板

[capture.screenshot]
format = "png"                     # 截图保存格式: "png", "jpeg" 或 "webp"
include_snapzy = false             # 截图包含 Snapzy 自身的辅助窗口
show_cursor = false                # 截图包含 macOS 鼠标指针

[capture.scrolling]
show_hints = true                  # 在滚动截屏期间显示引导提示

[capture.ocr]
success_notification = false       # 文本提取 (OCR) 成功时发送系统通知

[capture.object_cutout]
auto_crop = true                   # 自动裁剪抠图主体周围的空白边缘

[capture.after.screenshot]
save = true                        # 自动将截图保存到本地输出文件夹
quick_access = true                # 捕获后在屏幕上显示快速访问（预览）面板
copy_file = true                   # 复制已保存文件的完整路径到系统剪贴板
open_annotate = false              # 捕获后自动在标注编辑器 (Annotate) 中打开
upload_to_cloud = false            # 捕获后立即上传到配置的云存储

[capture.after.recording]
save = true                        # 自动将录像保存到本地输出文件夹
quick_access = true                # 录制完成后在屏幕上显示快速访问面板
copy_file = true                   # 复制视频文件的完整路径到系统剪贴板
open_annotate = false              # 录制后自动在视频编辑器 (Video Editor) 中打开
upload_to_cloud = false            # 录制完成后立即上传到配置的云存储

[recording]
format = "mov"                     # 视频封装格式: "mov" 或 "mp4"
quality = "high"                   # 视频压缩质量预设: "high", "medium" 或 "low"
fps = 30                           # 目标视频录制帧率 (1 到 120)
output_mode = "video"              # 导出媒体形式: "video" (MP4/MOV) 或 "gif" (动态 GIF)
capture_system_audio = true        # 录制系统输出的声音 (需要安装虚拟声卡驱动)
capture_microphone = false         # 录制外部麦克风声音
microphone_device_id = ""          # 音频输入的 CoreAudio 麦克风设备 UID 字符串
remember_last_area = true          # 记住上次录制区域的坐标，用于后续录制
include_snapzy = false             # 录屏视频中包含 Snapzy 的控制工具栏与层
show_cursor = true                 # 录屏视频中包含 macOS 鼠标指针
highlight_clicks = false           # 录屏时在鼠标点击位置绘制高亮环动画
show_keystrokes = false            # 录屏时在屏幕上悬浮显示按键组合

[recording.mouse_highlight]
size = 50                          # 鼠标点击高亮圆环的像素直径 (20 到 120)
animation_duration = 0.7           # 点击波纹动画持续时间 (秒，0.1 到 3.0)
color = "#FF000080"                # 高亮圆环的十六进制颜色代码 (#RRGGBB 或 #RRGGBBAA)
opacity = 0.5                      # 圆环的透明度 (0.0 到 1.0)
ripple_count = 3                   # 每次点击产生的波纹层数 (1 到 6)

[recording.keystrokes]
font_size = 18.0                   # 按键显示的字体大小 (磅，10.0 到 48.0)
position = "bottomCenter"          # 显示位置: "topLeft", "topRight", "bottomLeft", "bottomRight", "bottomCenter" 等
display_duration = 2.0             # 按键显示在屏幕上的停留时间 (秒，0.3 到 10.0)

[recording.annotation_shortcuts]
modifier = "shift"                 # 录制中调用快捷标注栏的辅助键: "shift", "option", "command", "control"
hold_duration = 1.0                # 辅助键长按以激活的时间门槛 (秒，0.1 到 5.0)

[quick_access]
enabled = true                     # 捕获后激活快速访问预览面板
position = "bottomRight"           # 面板停靠的屏幕角: "topLeft", "topRight", "bottomLeft", "bottomRight"
auto_dismiss = true                # 启用倒计时自动关闭预览面板
auto_dismiss_delay = 10.0          # 自动关闭等待时间 (秒，3.0 到 30.0)
pause_countdown_on_hover = true    # 鼠标悬停在面板上时暂停倒计时关闭
overlay_scale = 1.0                # 预览面板的整体缩放倍数 (0.75 到 1.5)
drag_drop = true                   # 允许从面板直接拖拽文件导出到其他应用
actions_order = ["copy", "annotate", "save", "cloud", "delete"] # 快捷按钮排序顺序
enabled_actions = ["copy", "annotate", "save", "cloud", "delete"] # 要显示的快捷功能列表

[quick_access.slots]
center_top = "copy"                # 映射操作到中央顶部槽位
center_bottom = "annotate"         # 映射操作到中央底部槽位
top_trailing = "save"              # 映射操作到右顶部槽位
top_leading = "cloud"              # 映射操作到左顶部槽位
bottom_leading = "delete"          # 映射操作到左底部槽位
bottom_trailing = ""               # 留空表示不分配

[history]
enabled = true                     # 开启应用程序内的截图与视频历史记录保存
retention_days = 30                # 历史记录保存天数限制 (0 表示无限期保留)
max_count = 500                    # 最大历史记录保存条数限制 (0 到 1000)
background_style = "hud"           # 历史记录面板背景风格: "hud" (毛玻璃效果) 或 "solid" (不透明)
open_on_launch = false             # 启动 Snapzy 时自动打开历史记录浏览器窗口

[history.floating]
enabled = true                     # 在屏幕上显示历史记录悬浮 HUD 条
position = "topCenter"             # 悬浮条的屏幕对齐方式: "topCenter", "bottomCenter", "center"
default_filter = "all"             # 初始过滤类型: "all", "screenshot", "recording", "ocr", "cutout"
max_displayed_items = 10           # 悬浮 HUD 里的最大预览卡片数 (3 到 20)
scale = 1.0                        # 历史记录悬浮 HUD 的缩放比例 (0.8 到 1.2)
auto_clear_days = 0                # 自动清理早于指定天数的历史条目 (0 到 365)

[cloud]
provider = "aws_s3"                # 云端存储提供商: "aws_s3" 或 "cloudflare_r2"
bucket = "my-snapzy-bucket"        # 云存储桶名称
region = "us-east-1"               # 存储桶区域代码 (AWS S3 必须配置)
endpoint = ""                      # 存储 API 端点 URL 地址 (Cloudflare R2 必须配置)
custom_domain = ""                 # 用于生成共享公共链接的自定义域名
expire_time = "7d"                 # 预签名链接的有效期/生命周期: "1d", "3d", "7d", "14d", "30d", "60d", "90d", "permanent"
uploads_window_position = "center" # 悬浮云端上传状态面板的屏幕位置: "top", "center", "bottom"

[annotate]
clipboard_image_open_behavior = "ask" # 启动空编辑器时处理剪贴板图片的动作: "ask", "loadAutomatically", "doNothing"
close_after_drag = true            # 通过拖拽完成文件复制后，自动关闭标注窗口
bring_forward_after_drag = false   # 拖拽完成后，将目标接收软件窗口移动到前台
quick_properties_sync = true       # 画笔粗细和颜色属性在各标注工具之间即时同步

[shortcuts]
enabled = true                     # 全局快捷键监听开关 (注册快捷键所必需)

[shortcuts.global.fullscreen]
enabled = true
key = "3"
modifiers = ["command", "shift"]

[shortcuts.global.area]
enabled = true
key = "4"
modifiers = ["command", "shift"]

[shortcuts.global.areaAnnotate]
enabled = true
key = "7"
modifiers = ["command", "shift"]

[shortcuts.global.scrollingCapture]
enabled = true
key = "6"
modifiers = ["command", "shift"]

[shortcuts.global.recording]
enabled = true
key = "5"
modifiers = ["command", "shift"]

[shortcuts.global.annotate]
enabled = true
key = "A"
modifiers = ["command", "shift"]

[shortcuts.global.videoEditor]
enabled = true
key = "E"
modifiers = ["command", "shift"]

[shortcuts.global.cloudUploads]
enabled = true
key = "L"
modifiers = ["command", "shift"]

[shortcuts.global.shortcutList]
enabled = true
key = "K"
modifiers = ["command", "shift"]

[shortcuts.global.ocr]
enabled = true
key = "2"
modifiers = ["command", "shift"]

[shortcuts.global.objectCutout]
enabled = true
key = "1"
modifiers = ["command", "shift"]

[shortcuts.global.history]
enabled = true
key = "H"
modifiers = ["command", "shift"]

[shortcuts.overlay.area_application_capture]
enabled = true
key = "SPACE"                      # 处于区域截图覆盖层时的特殊按键控制
modifiers = []

[shortcuts.overlay.recording_application_capture]
enabled = true
key = "SPACE"
modifiers = []

[shortcuts.annotate_tools]
disabled = []
# 绑定键盘数字键「1」到「8」以快速切换标注绘画工具
"1" = "pen"
"2" = "arrow"
"3" = "rect"
"4" = "oval"
"5" = "text"
"6" = "blur"

[shortcuts.annotate_actions.copyAndClose]
enabled = true
key = "C"
modifiers = ["command"]

[shortcuts.annotate_actions.toggleSidebar]
enabled = true
key = "B"
modifiers = ["command"]

[shortcuts.annotate_actions.togglePin]
enabled = true
key = "P"
modifiers = ["command"]

[shortcuts.annotate_actions.cloudUpload]
enabled = true
key = "U"
modifiers = ["command"]

配置属性参考指南

常规项目 (`[general]`)

属性名称	数据类型	默认值	允许的选项 / 范围	详细说明
`language`	字符串	`"system"`	`"system"`, `"en"`, `"vi"`, `"ja"`, `"ko"`, `"ru"`, `"zh"`, `"zh-tw"`	界面显示的语言配置设置。
`appearance`	字符串	`"system"`	`"system"`, `"light"`, `"dark"`	UI 颜色主题模式选择。
`play_sounds`	布尔值	`true`	`true`, `false`	截图或录屏操作成功时的声音反馈。
`start_at_login`	布尔值	`false`	`true`, `false`	在 macOS 登录时自动启动程序。
`export_location`	字符串	`"~/Pictures"`	有效文件夹路径	捕获文件的本地默认存放目标文件夹。

更新与诊断日志

属性名称	数据类型	默认值	允许的选项 / 范围	详细说明
`updates.check_automatically`	布尔值	`true`	`true`, `false`	使用 Sparkle 服务自动在线检测最新版本。
`updates.download_automatically`	布尔值	`false`	`true`, `false`	自动下载新版本，无需用户确认。
`diagnostics.enabled`	布尔值	`true`	`true`, `false`	写入故障诊断用的本地运行日志记录。
`diagnostics.retention_days`	整数	`7`	`1` 到 `30`	诊断日志文件在硬盘上的保留天数上限。

捕获屏幕和命名规则 (`[capture]`)

属性名称	数据类型	默认值	允许的选项 / 范围	详细说明
`hide_desktop_icons`	布尔值	`false`	`true`, `false`	捕获截图或视频时，临时隐藏桌面文件图标。
`hide_desktop_widgets`	布尔值	`false`	`true`, `false`	捕获截图或视频时，临时隐藏桌面小部件。
`naming.screenshot_template`	字符串	`"Snapzy_{year}...`	模板格式字符串	截图自动保存的文件命名规则设计。
`naming.recording_template`	字符串	`"Snapzy_{year}...`	模板格式字符串	录像自动保存的文件命名规则设计。
`screenshot.format`	字符串	`"png"`	`"png"`, `"jpeg"`, `"webp"`	捕获的屏幕图像格式。
`screenshot.include_snapzy`	布尔值	`false`	`true`, `false`	允许在截屏中拍下 Snapzy 自身的辅助面板和窗口。
`screenshot.show_cursor`	布尔值	`false`	`true`, `false`	在截图图片上显示系统鼠标指针。
`scrolling.show_hints`	布尔值	`true`	`true`, `false`	在滚动截屏执行中展示操作指引。
`ocr.success_notification`	布尔值	`false`	`true`, `false`	文本提取 (OCR) 成功后发出通知提示。
`object_cutout.auto_crop`	布尔值	`true`	`true`, `false`	完成对象抠图后自动裁剪多余的透明边缘。

捕获后后续事件 (After Capture)

属性名称	数据类型	默认值	允许的选项 / 范围	详细说明
`capture.after.screenshot.save`	布尔值	`true`	`true`, `false`	自动写入文件到输出目标文件夹。
`capture.after.screenshot.quick_access`	布尔值	`true`	`true`, `false`	捕获后在屏幕上显示快速访问预览窗口。
`capture.after.screenshot.copy_file`	布尔值	`true`	`true`, `false`	将生成文件的本地绝对路径复制到系统剪贴板。
`capture.after.screenshot.open_annotate`	布尔值	`false`	`true`, `false`	自动将截图载入标注编辑器进行标注。
`capture.after.screenshot.upload_to_cloud`	布尔值	`false`	`true`, `false`	截图完成后自动开始上传云存储。
`capture.after.recording.save`	布尔值	`true`	`true`, `false`	自动将视频保存到本地输出文件夹。
`capture.after.recording.quick_access`	布尔值	`true`	`true`, `false`	录制完成后在屏幕上显示快速访问面板。
`capture.after.recording.copy_file`	布尔值	`true`	`true`, `false`	将生成视频文件的本地路径复制到剪贴板。
`capture.after.recording.open_annotate`	布尔值	`false`	`true`, `false`	录制结束后，自动载入视频裁剪剪辑面板。
`capture.after.recording.upload_to_cloud`	布尔值	`false`	`true`, `false`	视频录制完成后自动开始上传云存储。

屏幕录制 (`[recording]`)

属性名称	数据类型	默认值	允许的选项 / 范围	详细说明
`format`	字符串	`"mov"`	`"mov"`, `"mp4"`	视频封装文件后缀。
`quality`	字符串	`"high"`	`"high"`, `"medium"`, `"low"`	视频压缩清晰度预设级别。
`fps`	整数	`30`	`1` 到 `120`	录制时所需的目标帧率。
`output_mode`	字符串	`"video"`	`"video"`, `"gif"`	最终保存文件的格式。
`capture_system_audio`	布尔值	`true`	`true`, `false`	捕获录音系统内部播放的声音。
`capture_microphone`	布尔值	`false`	`true`, `false`	捕获录制外部麦克风输入的人声。
`microphone_device_id`	字符串	`""`	有效声卡设备 UID	录制所要调用的具体外置麦克风硬件设备。
`remember_last_area`	布尔值	`true`	`true`, `false`	记住上一次的自定义屏幕录屏选区坐标。
`show_cursor`	布尔值	`true`	`true`, `false`	将鼠标光标路径存入视频画面。
`highlight_clicks`	布尔值	`false`	`true`, `false`	在视频画面上点击鼠标时闪烁突出圈。
`show_keystrokes`	布尔值	`false`	`true`, `false`	录屏时，在屏幕下方悬浮显示按键输入。
`mouse_highlight.size`	双精度浮点型	`50.0`	`20.0` 到 `120.0`	鼠标点击波纹环的像素直径。
`mouse_highlight.color`	字符串	`"#FF000080"`	十六进制颜色值 (`#RRGGBBAA`)	点击指示标记的颜色设计。
`mouse_highlight.opacity`	双精度浮点型	`0.5`	`0.0` 到 `1.0`	点击波纹图层的透明度。
`mouse_highlight.ripple_count`	整数	`3`	`1` 到 `6`	每次鼠标点击在屏幕散发的波纹个数。
`keystrokes.font_size`	双精度浮点型	`18.0`	`10.0` 到 `48.0`	组合按键字体的磅值大小。
`keystrokes.position`	字符串	`"bottomCenter"`	屏幕对齐定位词	按键悬浮提示层所摆放的位置。
`keystrokes.display_duration`	双精度浮点型	`2.0`	`0.3` 到 `10.0`	按键指示图层在屏幕上存在的时间门槛。
`annotation_shortcuts.modifier`	字符串	`"shift"`	修饰键单词	录制过程中调用标注控制条的触发辅助按键。
`annotation_shortcuts.hold_duration`	双精度浮点型	`1.0`	`0.1` 到 `5.0`	长按以完成标注面板调用的触发秒数。

快速访问预览层 (`[quick_access]`)

属性名称	数据类型	默认值	允许的选项 / 范围	详细说明
`enabled`	布尔值	`true`	`true`, `false`	是否在操作后调出快速访问侧边框。
`position`	字符串	`"bottomRight"`	屏幕角单词	预览框附着在哪一个屏幕边缘位置。
`auto_dismiss`	布尔值	`true`	`true`, `false`	是否开启预览面板延时自动渐隐。
`auto_dismiss_delay`	双精度浮点型	`10.0`	`3.0` 到 `30.0`	侧边栏隐退前在屏幕上浮现的停留时间。
`pause_countdown_on_hover`	布尔值	`true`	`true`, `false`	鼠标移入预览窗口时自动暂停关闭的倒计时。
`overlay_scale`	双精度浮点型	`1.0`	`0.75` 到 `1.5`	预览图层卡片的整体缩放缩尺系数。
`drag_drop`	布尔值	`true`	`true`, `false`	允许通过拖拽将图片等直接发送至其他聊天/办公软件。
`actions_order`	字符串数组	默认值	功能组件 UIDs 列表	控制排版按键的顺序次序。
`enabled_actions`	字符串数组	默认值	功能组件 UIDs 列表	实际开启并可供点击的快捷功能按键。

历史文件夹 (`[history]`)

属性名称	数据类型	默认值	允许的选项 / 范围	详细说明
`enabled`	布尔值	`true`	`true`, `false`	是否将文件创建历史归入归档记录存储。
`retention_days`	整数	`30`	`0` 到 `90`	历史记录在本地存放的最大时间 (0 表示永不清理)。
`max_count`	整数	`500`	`0` 到 `1000`	允许的备份历史上限行数。
`background_style`	字符串	`"hud"`	`"hud"`, `"solid"`	历史页面底板的磨砂半透或实色设计。
`open_on_launch`	布尔值	`false`	`true`, `false`	开启 Snapzy 软件时自动载入查看历史页。
`floating.enabled`	布尔值	`true`	`true`, `false`	屏幕是否显示快速浮现历史 HUD。
`floating.position`	字符串	`"topCenter"`	对齐单词	历史浮现 HUD 的对齐与坐标设置。
`floating.max_displayed_items`	整数	`10`	`3` 到 `20`	快速悬浮 HUD 内最大的历史记录项显示数目。
`floating.scale`	双精度浮点型	`1.0`	`0.8` 到 `1.2`	历史记录悬浮框大小缩放乘数。

云端传输 (`[cloud]`)

属性名称	数据类型	默认值	允许的选项 / 范围	详细说明
`provider`	字符串	`"aws_s3"`	`"aws_s3"`, `"cloudflare_r2"`	使用的目标云端网络存储提供方。
`bucket`	字符串	`""`	存储桶字符	S3 或者 R2 云存储所归属的桶目录。
`region`	字符串	`"us-east-1"`	S3 的地区码	云主机的地理位置名称代码 (S3 必须参数)。
`endpoint`	字符串	`""`	接口地址 URL	API 连接和访问的目标 endpoint 域 (R2 必须参数)。
`custom_domain`	字符串	`""`	主机域名	绑定以输出自定义简洁链接域。
`expire_time`	字符串	`"7d"`	`"1d"`, `"3d"`, `"7d"`, `"14d"`, `"30d"`, `"60d"`, `"90d"`, `"permanent"`	签发的临时图片/视频连接有效期时长设置。
`uploads_window_position`	字符串	`"center"`	`"top"`, `"center"`, `"bottom"`	传输状态 HUD 窗口在屏幕显示的位置重心。

安全提示 — AWS Access Key, Secret Token 等敏感验证密钥信息绝不会以明文形式写入 config.toml 中，以防止你不小心将配置文件公开在 GitHub 等公共仓库。此类私钥信息默认由 macOS 鑰匙圈 (Keychain) 服务进行高强度安全加密存储。

图片标注画板 (`[annotate]`)

属性名称	数据类型	默认值	允许的选项 / 范围	详细说明
`clipboard_image_open_behavior`	字符串	`"ask"`	`"ask"`, `"loadAutomatically"`, `"doNothing"`	打开空白编辑器而剪贴板内有图片数据时的导入响应逻辑。
`close_after_drag`	布尔值	`true`	`true`, `false`	将图片通过拖拽完成发送后，是否自动关闭标注面板。
`bring_forward_after_drag`	布尔值	`false`	`true`, `false`	完成拖放后，将接收目标文件的应用置于屏幕前台。
`quick_properties_sync`	布尔值	`true`	`true`, `false`	画笔参数（大小、颜色）在各类画笔和线条工具间即时共享。

验证与配置排错

Snapzy 在载入 config.toml 文件时会进行严密的语法和数据规则校对：

约束超限: 当你配置的值超越了系统设定的最大/最小允许限度（例如设置 fps = 150 或 overlay_scale = 3.0），Snapzy 将在后台日志记录 Warning 警告，并自动将该字段强制重置为默认值。
类型错乱: 拼写错误导致的参数格式类型偏差（例如对于布尔型属性参数写入了普通文字），解析过程将报错（Error），Snapzy 会停止载入并直接回滚为原有的系统设置。
检阅问题: 因 config.toml 生成的校对警告和问题列表，你可以直接进入设置面板的**高级(Advanced)**选项卡下进行查看。

概述

快速入门

1. 授予配置访问权限

2. 同期与后台加载

完整注释的 TOML 示例

配置属性参考指南

常规项目 ([general])

更新与诊断日志

捕获屏幕和命名规则 ([capture])

捕获后后续事件 (After Capture)

屏幕录制 ([recording])

快速访问预览层 ([quick_access])

历史文件夹 ([history])

云端传输 ([cloud])

图片标注画板 ([annotate])