Skip to content

配置文件字段参考 ​

ZoneDeck 的配置保存在 config.json 中,便携版存在程序目录,安装版存在 %APPDATA%\ZoneDeck,详见数据目录。位置变动时旧配置会自动迁移过去。结构与旧版完全兼容,旧用户配置可直接沿用。首次运行若不存在则使用默认值。字段定义见 crates/common/src/config.rs。

一般无需手改

配置由配置界面自动读写并保存,通常无需手动编辑。本页面向需要理解字段含义的开发者。

顶层结构 ​

字段类型说明
versionstring配置 schema 版本,结构变动时才动
app_versionstring上次运行过的程序版本;与当前程序版本不符即「更新后首次启动」,核心据此自动弹出配置界面。缺省置空
historynumber[]历史记录(时间戳)
frozen_pidsnumber[]当前被冻结的进程 PID(用于恢复)
hotkeyobject键盘热键,见下
settingobject主要设置,见下
notificationsobject通知开关,见下
verhubobject更新 / 公告相关,见下
window_rulesobject[]窗口规则(细粒度)
process_rulesobject[]进程规则(粗粒度)
whitelistobject[]白名单:逐进程声明忽略隐藏 / 冻结 / 静音
hide_bindingobject[]V2版扁平绑定,仅用于迁移,迁移后清空、不再写回

hotkey ​

字段默认说明
hide_hotkey"Ctrl+Q"隐藏 / 显示窗口
close_hotkey"Win+Esc"关闭核心
hide_only_hotkey""仅隐藏窗口,置空为关闭
show_only_hotkey""仅显示窗口,置空为关闭
hide_foreground_hotkey""隐藏前台窗口,置空为关闭
hide_hookfalse隐藏热键改用低级键盘钩子触发
close_hookfalse关闭热键改用低级键盘钩子触发
hide_only_hookfalse仅隐藏热键改用低级键盘钩子触发
show_only_hookfalse仅显示热键改用低级键盘钩子触发
hide_foreground_hookfalse隐藏前台窗口热键改用低级键盘钩子触发
hide_interceptfalse隐藏热键不传递;为真时 hide_hook 也会被置真
close_interceptfalse关闭热键不传递
hide_only_interceptfalse仅隐藏热键不传递
show_only_interceptfalse仅显示热键不传递
hide_foreground_interceptfalse隐藏前台窗口热键不传递

热键字符串支持 更丰富的组合:多个主键用 + 相连(最多四个,如 "Q+W"),只有修饰键则是纯修饰键热键(如 "Ctrl+Shift")。这两类只有键盘钩子承载得了,配置里对应的 *_hook 未开时核心也会自动走钩子。符号键存按键位置名(OEM_1、OEM_PLUS 等),不随键盘布局变化。

setting ​

字段类型默认对应功能
mute_after_hidebooltrue隐藏后静音
send_before_hideboolfalse同时暂停播放:隐藏同时尝试暂停正在播放的媒体
resume_media_after_showboolfalse恢复时继续播放:依附于 send_before_hide,是否续播在隐藏那一刻定下
minimize_before_hideboolfalse隐藏前先最小化窗口
hide_currentbooltrue同时隐藏当前活动窗口
hide_icon_after_hideboolfalse同时隐藏 ZoneDeck 托盘图标
hide_config_after_hidebooltrue同时隐藏 ZoneDeck 配置窗口:只对触发那一刻可见的配置窗口生效
tray_enabledbooltrue显示托盘图标;为假时图标一直不显示,气泡与角标一并失效
tray_clicksobject见下托盘图标点击行为
tray_badgesobject见下图标状态提示
tray_show_tooltipbooltrue显示图标悬浮名称
freeze_after_hideboolfalse进程冻结总开关
enhanced_freezeboolfalse增强冻结
power_scopestring"self"冻结及内存控制范围:self(仅目标进程)|tree(及所有子进程)|image(同映像名的所有实例);决定冻结与降低内存占用的覆盖面,未知取值归一为 self
efficiency_after_hideboolfalse效率模式:隐藏后把进程降为 EcoQoS + 低优先级,与冻结相互独立
efficiency_scopestring"self"效率模式范围,取值同 power_scope,与冻结的范围互不影响
trim_memory_after_freezeboolfalse降低内存占用(仅对被冻结的进程生效)
show_float_windowboolfalse悬浮窗(开发中)
mouseobject见下鼠标按键隐藏
auto_hide_enabledboolfalse空闲自动隐藏
auto_hide_timenumber5空闲时长(分钟,1–120)
top_left_hide 等四角boolfalse四角隐藏
corner_fast_onlybooltrue仅快速移动触发
allow_move_restoreboolfalse角落恢复
log_retention_daysnumber7日志保留天数(0 = 关闭)
log_levelstring"warn"日志输出等级:debug|info|warn|error
autostart_adminboolfalse以管理员身份自启(仅计划任务方式生效)
languagestring"auto"界面语言:auto|zh-CN|en|zh-TW
旧版扁平鼠标开关(已废弃)

middle_button_hide / side_button1_hide / side_button2_hide 仅用于反序列化迁移,迁移后清零、不再写回文件。请使用 mouse 结构。

旧版「冻结完整进程」开关(已废弃)

freeze_whole_tree 仅用于反序列化迁移:读取时若配置里没有 power_scope,true 迁移为 power_scope: "tree"、false 迁移为 "self",随后清零、不再写回文件。已显式配过 power_scope 的文件不受它影响。

旧版「单击托盘切换隐藏」开关(已废弃)

click_to_hide 仅用于反序列化迁移:读取时若配置里没有 tray_clicks,true 迁移为 tray_clicks.left: "toggle"、false 迁移为 "none",随后清零、不再写回文件。老配置压根没有这个键时按 true 处理(旧版默认开启)。已显式配过 tray_clicks 的文件不受它影响。

setting.tray_clicks ​

托盘图标点击行为:三种点击各绑一个动作,取值为 none(无操作)|toggle(隐藏 / 显示窗口)|menu(显示托盘菜单)|settings(打开配置界面),未知取值归一为 none。

字段默认说明
left"toggle"左键单击
double"settings"左键双击。非 none 时单击须等过系统双击判定时间才执行
right"menu"右键单击

setting.mouse ​

每颗按键为一个 MouseButton:{ enabled: bool, clicks: 1..=3, modifiers: string }。

字段默认说明
left / middle / right / side1 / side2见下五颗按键各自的触发条件
multi_click_ms350连击判定窗口(毫秒,150–1000)
allow_click_restoretrue允许再按一次恢复

全新安装默认

全新安装默认开启中键双击(middle.enabled = true,clicks = 2),其余四颗关闭。配置文件缺 mouse 一节的老配置读进来则全关。

setting.tray_badges ​

图标状态提示:四种颜色的圆点角标各自绑定一个状态源,多个状态同时活跃时按红 > 绿 > 黄 > 蓝的优先级只显示一个圆点。

字段默认默认含义
red"hidden"存在隐藏中的窗口
green"auto_hide"启用了自动隐藏
yellow"hide_current"启用了同时隐藏当前窗口
blue"freeze"启用了进程冻结

每项取值:hidden(存在隐藏中的窗口)|auto_hide(启用了自动隐藏)|hide_current(启用了同时隐藏当前窗口)|freeze(启用了进程冻结)|elevated(以管理员身份运行)|monitor_paused(热键监控已暂停)|""(置空 = 不显示该颜色);未知取值读取时归一为置空。

notifications ​

字段默认说明
on_starttrue核心启动通知
on_quittrue核心退出通知
on_autostarttrue开机自启状态变更通知
on_hidefalse每次隐藏通知
on_showfalse每次显示通知
on_recovery_mismatchtrue上次异常退出后接管隐藏记录时,有记录与当初对不上就通知

verhub ​

字段默认说明
include_previewfalse更新检查是否纳入预览版
seen_announcement_id""已读的最新公告 id
analyticsnull匿名使用统计的授权:null 表示还没问过用户,首次启动时弹窗征求同意;true 同意,false 拒绝
analytics_consent_sentfalse「同意参与」是否已上报过。同一台设备只报一次,反复开关不再重复

window_rules(窗口规则) ​

细粒度规则,按句柄 + 标题锁定单个窗口;regex 为 Some 时按标题正则命中。

字段说明
title窗口标题
hwnd窗口句柄
process进程名
PID进程 ID(大写 key,兼容旧配置)
path可执行文件路径
regex标题正则(高级模式;省略表示精确规则)
include_untitled正则是否纳入无标题窗口
include_background正则是否纳入后台窗口

process_rules(进程规则) ​

粗粒度规则,按可执行文件隐藏该程序的所有窗口。

字段默认说明
process进程名
path可执行文件路径
regex正则(作用于路径或文件名)
by_namefalse只按文件名匹配,忽略路径
include_untitledtrue是否纳入无标题窗口(进程规则默认纳入)
include_backgroundfalse是否纳入后台窗口

whitelist(白名单) ​

按进程声明在哪些模式下跳过,见白名单。匹配方式与 process_rules 同构,但默认按文件名匹配;文件名与路径的比较不区分大小写。

字段默认说明
process进程名
path可执行文件路径
regex正则(作用于路径或文件名)
by_nametrue只按文件名匹配,忽略路径
ignore_hidefalse隐藏时跳过该程序的窗口
ignore_freezefalse隐藏后不冻结该程序的进程
ignore_mutefalse隐藏后不静音该程序的进程

键缺失 vs 空数组

whitelist 键不存在(老配置 / 全新配置)时会播种一条默认的 explorer.exe;写成 [] 表示用户清空了列表,不会再被播种。归一后该字段恒为数组,不会是 null。

ZoneDeck 自身的核心与配置程序(ZoneDeck.exe / core.exe / config.exe / zonedeck-config.exe)恒被排除在冻结之外。该保护写死在 crates/common/src/matching.rs 的 BUILTIN_FREEZE_GUARDS 里,不出现在配置文件中,手改配置也绕不过去。

兼容与迁移 ​

  • 未知字段被忽略:未来新增字段不会导致旧核心解析失败。
  • 缺失字段用默认值:任意字段缺失都回退到默认值。
  • 解析失败先备份:整份配置解析失败时回退默认值启动,原文件先改名为同目录 config.json.bad 备份,规则可从中手工找回;备份去向记录在日志里。
  • 旧绑定自动迁移:hide_binding → window_rules;旧鼠标开关 → mouse 连击触发。迁移是幂等的。
  • PID 大写:序列化输出使用大写 PID,与旧 Python 版本兼容。