Cấu hình Snapzy bằng mã thông qua tệp config.toml để quản lý cài đặt di động, tự động hóa sao lưu và đồng bộ dotfiles.
Tổng quan
Đối với người dùng nâng cao, lập trình viên và quản trị viên hệ thống, Snapzy hỗ trợ cấu hình lập trình thông qua một tệp TOML tiêu chuẩn (config.toml). Điều này cho phép bạn quản lý tất cả các cài đặt ứng dụng dưới dạng văn bản thuần túy, đồng bộ hóa chúng thông qua các kho lưu trữ dotfiles và thiết lập triển khai tự động trên các môi trường macOS khác nhau.
Bắt đầu nhanh
1. Cấp quyền truy cập cấu hình
Mở Snapzy Cài đặt (Cmd + ,) và điều hướng đến tab Nâng cao (Advanced).
Nhấp vào Thiết lập config.toml.
Một hộp thoại hệ thống sẽ xuất hiện để yêu cầu bạn chọn thư mục lưu trữ cấu hình. Chọn thư mục cấu hình mong muốn (thường là ~/.config/snapzy/) và nhấp vào Cấp quyền truy cập (Grant Access).
Sau khi quyền được cấp, Snapzy sẽ tự động tạo tệp config.toml mặc định tại đường dẫn:
~/.config/snapzy/config.toml
2. Cơ chế đồng bộ hóa & Tải nền
Áp dụng khi khởi chạy: Snapzy phân tích cú pháp và kiểm tra tính hợp lệ của tệp config.toml mỗi khi ứng dụng khởi chạy.
Đồng bộ nền tự động: Ứng dụng theo dõi các thay đổi trên tệp config.toml trong nền. Các chỉnh sửa được lưu trực tiếp từ trình soạn thảo của bạn sẽ được tự động áp dụng sau vài giây (đã được debounce để tránh đọc tệp khi đang ghi dở).
Đồng bộ thủ công: Bạn có thể nhấp vào nút Đồng bộ hóa config.toml trong tab Nâng cao để tải lại cài đặt ngay lập tức.
Khôi phục mặc định: Nhấp vào nút Khôi phục mặc định sẽ ghi đè các cấu hình hiện tại trong tệp TOML bằng các giá trị gốc mặc định của nhà sản xuất.
Ví dụ tệp TOML mẫu đầy đủ
Dưới đây là một tệp mẫu config.toml hợp lệ với tất cả các trường cấu hình có sẵn cùng các ghi chú giải thích chi tiết.
# Phiên bản cấu trúc Snapzy TOML (Bắt buộc phải là 1)
schema_version = 1
# Phiên bản Snapzy tối thiểu được hỗ trợ cho tệp này
snapzy_min_version = "1.20.0"
[general]
language = "system" # "system" hoặc mã ngôn ngữ: "en", "vi", "ja", "ko", "ru", "zh", "zh-tw"
appearance = "system" # Chủ đề giao diện: "system", "light", hoặc "dark"
play_sounds = true # Phát âm thanh khi chụp ảnh hoặc ghi video màn hình
start_at_login = false # Tự động khởi chạy Snapzy cùng hệ thống macOS
export_location = "~/Pictures" # Thư mục lưu trữ hình ảnh/video đầu ra (hỗ trợ ký tự ~)
[updates]
check_automatically = true # Tự động kiểm tra bản cập nhật mới qua Sparkle
download_automatically = false # Tự động tải bản cập nhật trong nền mà không hiển thị thông báo
[diagnostics]
enabled = true # Bật ghi log chẩn đoán lỗi tại chỗ
retention_days = 7 # Số ngày lưu trữ các tệp log (từ 1 đến 30)
[capture]
hide_desktop_icons = false # Tạm thời ẩn các biểu tượng trên màn hình nền khi chụp/ghi
hide_desktop_widgets = false # Tạm thời ẩn các tiện ích (widgets) trên màn hình khi chụp/ghi
[capture.naming]
screenshot_template = "Snapzy_{year}-{month}-{day}_{hour}-{minute}-{second}_{milliseconds}" # Định dạng tên ảnh chụp
recording_template = "Snapzy_{year}-{month}-{day}_{hour}-{minute}-{second}_{milliseconds}" # Định dạng tên video ghi hình
[capture.screenshot]
format = "png" # Định dạng tệp ảnh chụp: "png", "jpeg", hoặc "webp"
include_snapzy = false # Chụp cả các cửa sổ điều khiển của ứng dụng Snapzy
show_cursor = false # Chụp kèm con trỏ chuột hệ thống trên ảnh
[capture.scrolling]
show_hints = true # Hiển thị các hướng dẫn tương tác trong quá trình chụp cuộn trang
[capture.ocr]
success_notification = false # Hiển thị thông báo hệ thống khi trích xuất văn bản (OCR) thành công
[capture.object_cutout]
auto_crop = true # Tự động cắt sát các phần rìa trống bao quanh đối tượng được tách
[capture.after.screenshot]
save = true # Lưu tệp ảnh chụp vào thư mục xuất
quick_access = true # Hiển thị bảng Xem nhanh (Quick Access) sau khi chụp
copy_file = true # Sao chép đường dẫn tệp vào clipboard hệ thống
open_annotate = false # Tự động mở ảnh trong trình chú thích (Annotate) sau khi chụp
upload_to_cloud = false # Tải ảnh lên kho lưu trữ đám mây đã cấu hình ngay lập tức
[capture.after.recording]
save = true # Lưu tệp video ghi hình vào thư mục xuất
quick_access = true # Hiển thị bảng Xem nhanh sau khi ghi xong
copy_file = true # Sao chép đường dẫn video vào clipboard
open_annotate = false # Tự động mở video trong trình biên tập video (Video Editor) sau khi ghi
upload_to_cloud = false # Tự động tải video lên đám mây ngay lập tức
[recording]
format = "mov" # Định dạng tệp video đầu ra: "mov" hoặc "mp4"
quality = "high" # Mức chất lượng video: "high", "medium", hoặc "low"
fps = 30 # Số khung hình trên giây (từ 1 đến 120)
output_mode = "video" # Chế độ xuất: "video" (MP4/MOV) hoặc "gif" (ảnh GIF động)
capture_system_audio = true # Ghi âm thanh hệ thống (yêu cầu cài đặt driver âm thanh ảo)
capture_microphone = false # Ghi âm thanh từ micrô ngoài
microphone_device_id = "" # UID thiết bị micrô CoreAudio chỉ định ghi âm
remember_last_area = true # Ghi nhớ tọa độ vùng chụp gần nhất cho các lần chụp tiếp theo
include_snapzy = false # Ghi kèm các thanh công cụ điều khiển của Snapzy vào video
show_cursor = true # Hiện con trỏ chuột hệ thống trong video ghi hình
highlight_clicks = false # Hiển thị vòng tròn hiệu ứng trực quan tại điểm nhấp chuột
show_keystrokes = false # Hiển thị phím đang gõ trên màn hình khi ghi hình
[recording.mouse_highlight]
size = 50 # Đường kính vòng tròn nhấp chuột tính bằng pixel (từ 20 đến 120)
animation_duration = 0.7 # Thời gian diễn ra hiệu ứng sóng nhấp chuột tính bằng giây (từ 0.1 đến 3.0)
color = "#FF000080" # Mã màu HEX của vòng tròn nhấp chuột (#RRGGBB hoặc #RRGGBBAA)
opacity = 0.5 # Độ mờ của hiệu ứng nhấp chuột (từ 0.0 đến 1.0)
ripple_count = 3 # Số lớp sóng lan tỏa trên mỗi lần nhấp chuột (từ 1 đến 6)
[recording.keystrokes]
font_size = 18.0 # Cỡ chữ của phím bấm hiển thị tính bằng point (từ 10.0 đến 48.0)
position = "bottomCenter" # Vị trí hiển thị phím gõ: "topLeft", "topRight", "bottomLeft", "bottomRight", "bottomCenter", v.v.
display_duration = 2.0 # Thời gian phím hiển thị trên màn hình trước khi ẩn tính bằng giây (từ 0.3 đến 10.0)
[recording.annotation_shortcuts]
modifier = "shift" # Phím giữ để kích hoạt thanh chú thích nhanh khi ghi hình: "shift", "option", "command", "control"
hold_duration = 1.0 # Thời gian nhấn giữ tối thiểu để kích hoạt tính bằng giây (từ 0.1 đến 5.0)
[quick_access]
enabled = true # Bật bảng xem nhanh thu nhỏ ở góc màn hình sau khi chụp/ghi
position = "bottomRight" # Góc neo bảng xem nhanh: "topLeft", "topRight", "bottomLeft", "bottomRight"
auto_dismiss = true # Tự động ẩn bảng xem nhanh sau một khoảng thời gian
auto_dismiss_delay = 10.0 # Thời gian chờ trước khi tự động ẩn tính bằng giây (từ 3.0 đến 30.0)
pause_countdown_on_hover = true # Tạm dừng đếm ngược tự ẩn khi di chuột vào bảng xem nhanh
overlay_scale = 1.0 # Tỷ lệ phóng to/thu nhỏ của bảng xem nhanh (từ 0.75 đến 1.5)
drag_drop = true # Hỗ trợ kéo thả đường dẫn tệp trực tiếp từ bảng xem nhanh sang app khác
actions_order = ["copy", "annotate", "save", "cloud", "delete"] # Thứ tự hiển thị các nút thao tác nhanh
enabled_actions = ["copy", "annotate", "save", "cloud", "delete"] # Các nút thao tác nhanh được hiển thị
[quick_access.slots]
center_top = "copy" # Gán chức năng cho ô thao tác trung tâm phía trên
center_bottom = "annotate" # Gán chức năng cho ô thao tác trung tâm phía dưới
top_trailing = "save" # Gán chức năng cho ô thao tác góc trên bên phải
top_leading = "cloud" # Gán chức năng cho ô thao tác góc trên bên trái
bottom_leading = "delete" # Gán chức năng cho ô thao tác góc dưới bên trái
bottom_trailing = "" # Bỏ trống nếu không muốn gán chức năng cho ô góc dưới bên phải
[history]
enabled = true # Lưu lịch sử chụp ảnh/video màn hình trên ứng dụng
retention_days = 30 # Số ngày lưu lịch sử trước khi tự dọn dẹp (0 nghĩa là lưu vô hạn)
max_count = 500 # Số lượng bản ghi lịch sử tối đa cho phép (từ 0 đến 1000)
background_style = "hud" # Kiểu nền bảng lịch sử: "hud" (mờ ảo) hoặc "solid" (nền đặc)
open_on_launch = false # Tự động mở cửa sổ lịch sử mỗi khi khởi chạy Snapzy
[history.floating]
enabled = true # Hiển thị thanh lịch sử nổi trên màn hình
position = "topCenter" # Vị trí thanh lịch sử nổi: "topCenter", "bottomCenter", "center"
default_filter = "all" # Bộ lọc mặc định ban đầu: "all", "screenshot", "recording", "ocr", "cutout"
max_displayed_items = 10 # Số lượng ảnh hiển thị tối đa trên thanh nổi (từ 3 đến 20)
scale = 1.0 # Tỷ lệ thu phóng kích thước thanh lịch sử nổi (từ 0.8 đến 1.2)
auto_clear_days = 0 # Tự động xóa các bản ghi lịch sử cũ hơn số ngày chỉ định (từ 0 đến 365)
[cloud]
provider = "aws_s3" # Nhà cung cấp đám mây: "aws_s3" hoặc "cloudflare_r2"
bucket = "my-snapzy-bucket" # Tên bucket AWS S3 hoặc Cloudflare R2
region = "us-east-1" # Định danh vùng lưu trữ bucket (bắt buộc với S3)
endpoint = "" # URL endpoint tùy chỉnh (bắt buộc với Cloudflare R2)
custom_domain = "" # Tên miền tùy chỉnh dùng để tạo các liên kết chia sẻ công khai ngắn gọn
expire_time = "7d" # Thời hạn khả dụng của liên kết tạm thời/quy tắc lưu trữ: "1d", "3d", "7d", "14d", "30d", "60d", "90d", "permanent"
uploads_window_position = "center" # Vị trí thanh tiến trình tải lên đám mây: "top", "center", "bottom"
[annotate]
clipboard_image_open_behavior = "ask" # Cách xử lý khi mở trình biên tập trống và có ảnh trong clipboard: "ask", "loadAutomatically", "doNothing"
close_after_drag = true # Tự động đóng cửa sổ chú thích sau khi kéo ảnh ra ứng dụng khác
bring_forward_after_drag = false # Chuyển tiêu điểm (focus) về ứng dụng đích sau khi kéo thả tệp chú thích xong
quick_properties_sync = true # Đồng bộ hóa kích cỡ nét bút và màu sắc giữa các công cụ chú thích ngay lập tức
[shortcuts]
enabled = true # Kích hoạt tính năng phím tắt toàn cục (phải bật để có thể đăng ký phím tắt bàn phím)
[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" # Phím tắt phụ trợ trong chế độ chọn vùng chụp màn hình
modifiers = []
[shortcuts.overlay.recording_application_capture]
enabled = true
key = "SPACE"
modifiers = []
[shortcuts.annotate_tools]
disabled = []
# Gán phím tắt số từ "1" đến "8" để kích hoạt nhanh các công cụ vẽ chú thích
"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"]
Thời hạn tối đa khả dụng của liên kết chia sẻ trước khi hết hạn.
uploads_window_position
Chuỗi
"center"
"top", "center", "bottom"
Vị trí neo của khung giám sát tiến trình tải lên đám mây.
Trình chú thích hình ảnh ([annotate])
Tên thuộc tính
Kiểu dữ liệu
Giá trị mặc định
Giá trị hợp lệ / Khoảng cho phép
Mô tả
clipboard_image_open_behavior
Chuỗi
"ask"
"ask", "loadAutomatically", "doNothing"
Cách xử lý khi mở bảng chú thích trống trong lúc có ảnh ở clipboard.
close_after_drag
Boolean
true
true, false
Tự động đóng cửa sổ sau khi kéo ảnh ra ứng dụng khác thành công.
bring_forward_after_drag
Boolean
false
true, false
Tự động chuyển ứng dụng đích lên trước sau khi kéo thả tệp.
quick_properties_sync
Boolean
true
true, false
Đồng bộ nhanh thông số nét vẽ và màu sắc tức thì giữa các công cụ.
Kiểm tra lỗi & Cảnh báo cấu hình
Snapzy thực hiện kiểm tra nghiêm ngặt tính hợp lệ của tệp config.toml khi tải:
Giới hạn giá trị: Nếu một thuộc tính vượt quá giới hạn cho phép (Ví dụ: đặt fps = 150 hoặc overlay_scale = 3.0), Snapzy sẽ đưa ra cảnh báo, bỏ qua thuộc tính không hợp lệ đó và tự động áp dụng giá trị mặc định.
Sai kiểu dữ liệu: Đặt sai định dạng dữ liệu (Ví dụ: truyền một chuỗi văn bản cho thuộc tính dạng Boolean) sẽ gây ra lỗi nghiêm trọng. Snapzy sẽ từ chối áp dụng tệp cấu hình đó và giữ nguyên các cài đặt trước đó của ứng dụng.
Xem danh sách cảnh báo: Bạn có thể xem trực tiếp các lỗi hoặc cảnh báo liên quan đến tệp config.toml trong tab Nâng cao (Advanced) của phần Cài đặt ứng dụng.