KeepingYouAwake 1.4.0 版本解析:偏好设置窗口、显示器休眠与电池电量阈值机制

原创2026-10-14 10:43:181,739 阅读
文章标签:桌面应用

KeepingYouAwake 1.4.0 版本解析:偏好设置窗口、显示器休眠与电池电量阈值机制

KeepingYouAwake 是一款防止 Mac 自动睡眠的菜单栏小工具,其核心机制是通过调用系统自带 caffeinate 命令维持系统清醒。本文以版本发布说明文档 docs/Versions/v1.4.0.md 为主体,结合当前仓库源码,深入讲解 1.4.0(发布于 2016-04-16,版本元数据见 docs/Versions/v1.4.0.json)这一关键版本引入的偏好设置窗口、默认激活时长、显示器休眠选项与电池电量阈值自动停用机制。读完本文,你将理解这些偏好的完整配置方式、对应的 NSUserDefaults 存储键,以及它们是如何在 KYASleepWakeTimer 与 KYAAppController 等核心模块中被解析和执行的。

一、版本概览:从"裸菜单"走向"偏好设置窗口"

1.4.0 的发布主题是 "Preferences Update",核心变化是把此前零散分布在菜单栏菜单中的少量设置项收拢到一个独立的偏好设置窗口中,并借此机会加入实验性与高级设置。发布说明原文包含以下 6 条变更:

  1. 新增偏好设置窗口(preferences window),取代使用频率较低的菜单项,并对外暴露高级(advanced)与实验性(experimental)偏好;
  2. 可在偏好设置中为菜单栏图标设置默认激活时长(default activation duration);
  3. 移除了高级偏好 info.marcel-dierkes.KeepingYouAwake.PreventSleepOnACPower;
  4. 新增高级偏好:允许显示器休眠、同时继续防止系统睡眠(对应 Issue #25);
  5. 在 MacBook 上可设置电池电量阈值,电量低于该值时应用自动停用自身(对应 Issue #24,由 timbru31 建议);
  6. 将 Sparkle 升级到 1.14.0,以修复潜在安全问题。

从当前仓库结构看,这次重构的成果至今仍是设置功能的骨架:KeepingYouAwake/Settings 目录下已经形成了以 KYASettingsWindow 为窗口容器、KYASettingsContentViewController 为内容宿主、多个 KYA*SettingsViewController 为标签页的完整体系,标签页覆盖 General(KYAGeneralSettingsViewController.m)、Battery(KYABatterySettingsViewController.m)、Durations、Advanced(KYAAdvancedSettingsViewController.m)与 Updates 等维度。

二、偏好设置窗口:收纳低频菜单项,暴露高级与实验性偏好

2.1 设计动机

在 1.4.0 之前,部分设置项(如是否随登录启动、图标高亮等)只能通过菜单栏菜单操作,入口分散且对普通用户不友好。1.4.0 用偏好设置窗口统一收纳这些"很少用到"的菜单项,同时给高级用户留出"实验性开关"的入口。

2.2 当前的窗口与内容组织

从源码结构看,该偏好设置窗口由 KYASettingsWindow 提供,内容页通过 KYASettingsContentViewController 在多个标签页之间切换。各标签页控制器统一实现 tabViewItemImage 与 preferredTitle 两个类方法,例如 Advanced 页在 macOS 11+ 使用 SF Symbols 的 gearshape.2 图标(KYAAdvancedSettingsViewController.m),Battery 页使用 battery.100(KYABatterySettingsViewController.m)。

高级设置页通过 configureAdvancedSettings 动态构建设置项列表(KYAAdvancedSettingsViewController.m),每个开关都是 KYAUserDefaultsSetting 的实例,包含标题与对应的 NSUserDefaults 键。KYAUserDefaultsSetting 的读写实现(KYAUserDefaultsSetting.m)值得注意:当开关被置为 NO 时,它并不是写入 false,而是直接调用 removeObjectForKey: 删除该键——这保证了"恢复默认"与"清除个性化设置"在数据层面的一致性;reset 方法同样使用删除键的方式还原设置。

三、默认激活时长:在偏好设置中统一管理

3.1 功能说明

1.4.0 允许用户为菜单栏图标设置"默认激活时长"。此前点击图标会直接进入"无限期保持清醒"状态,而现在可以指定一个常用时长(如 30 分钟、1 小时),使点击图标后的行为更可控。

3.2 实现与存储键

默认激活时长对应的存储键定义于 NSUserDefaults+KYADefaultTimeInterval.m:

NSString * const KYAUserDefaultsKeyDefaultTimeInterval =
    @"info.marcel-dierkes.KeepingYouAwake.TimeInterval";

取值通过 integerForKey: 读取,以秒为单位;写入时使用 setInteger:,因此小数位会被截断(源码注释明确标注了这一点)。

在菜单交互层面,KYAActivationDurationsMenuController.m 提供了 setDefaultActivationDuration: 方法:用户按住 Option 键点击某个时长菜单项(alternate 状态菜单项),即可将该时长设为默认值;被设为默认的时长菜单项标题后会追加 "Is Default" 后缀,并以次级标签颜色渲染(KYAActivationDurationsMenuController.m)。

KYAAppController 在启动定时器时通过 defaultTimeInterval 读取该偏好(KYAAppController.m),作为"点击图标"与"启动时自动激活"(kya_activateOnLaunch)的默认时长。

四、移除 PreventSleepOnACPower 偏好

4.1 变更内容

1.4.0 移除了高级偏好 info.marcel-dierkes.KeepingYouAwake.PreventSleepOnACPower(直译为"接入电源时防止睡眠")。这一键名带有明显的历史包袱——它把"防止睡眠"与"是否使用电源"耦合在一起,粒度粗糙,容易让用户困惑。

4.2 当前源码中的印证

在 1.4.0 之后的源码中,该键已完全消失:当前仓库中 NSUserDefaults+KYAKeys.h(NSUserDefaults+KYAKeys.h)列出的全部用户默认键中不再包含 PreventSleepOnACPower。取而代之的是更明确的独立开关,例如电池阈值(BatteryCapacityThresholdEnabled)、低电量模式(LowPowerModeMonitoringEnabled)等——这一演进体现了 1.4.0 将"粗粒度预设行为"拆解为"可组合的细粒度偏好"的设计思路。

五、允许显示器休眠:暴露 caffeinate -i 的力量

5.1 需求背景

KeepingYouAwake 的默认行为是同时阻止系统睡眠与显示器睡眠(即 caffeinate -di)。但在观看视频、长时间下载等场景下,用户往往希望显示器可以按节能设置自动熄灭,而系统本身保持清醒。1.4.0 新增的高级偏好"允许显示器休眠"正是为此而生(对应 Issue #25)。

5.2 底层原理:从偏好到 caffeinate 参数

这一功能的核心实现在 KYASleepWakeTimer.m。定时器激活时会构建 caffeinate 的命令行参数:

Auto defaults = NSUserDefaults.standardUserDefaults;
Auto arguments = [NSMutableArray<NSString *> new];
if([defaults kya_shouldAllowDisplaySleep])
{
    [arguments addObject:@"-i"];      // 仅阻止系统睡眠,允许显示器休眠
}
else
{
    [arguments addObject:@"-di"];     // 同时阻止系统睡眠与显示器睡眠
}

if(timeInterval != KYASleepWakeTimeIntervalIndefinite)
{
    [arguments addObject:[NSString stringWithFormat:@"-t %.f", timeInterval]];
}

[arguments addObject:[NSString stringWithFormat:@"-w %i",
                      NSProcessInfo.processInfo.processIdentifier]];

关键点在于:

  • -i:仅阻止 idle system sleep,显示器可以按系统节能设置正常熄灭;
  • -di:同时阻止 idle system sleep 与 display sleep;
  • -t:指定保持清醒的秒数,0 或 KYASleepWakeTimeIntervalIndefinite 表示无限期;
  • -w:绑定到 KeepingYouAwake 自身的进程标识符,进程退出时 caffeinate 自动随之结束。

任务通过 NSTask 以 /usr/bin/caffeinate 启动,并注册 terminationHandler 处理结束回调;应用退出时(NSApplicationWillTerminateNotification)会统一 invalidate 并终止任务(KYASleepWakeTimer.m),避免留下孤儿进程。

5.3 存储键

该开关对应键 info.marcel-dierkes.KeepingYouAwake.AllowDisplaySleep,在 NSUserDefaults+KYAKeys.h 中以注释明确标注:"允许显示器休眠的同时保持系统清醒,这暴露的是 caffeinate -i 命令"。读取侧通过 kya_shouldAllowDisplaySleep 属性完成布尔值转换,实现见 NSUserDefaults+KYAKeys.m。

顺带一提:该偏好曾一度在 1.4.1 被临时移除(当时实现效果不佳),随后以更完善的形态回归,最终成为当前版本高级设置中的常驻开关——这也是 1.4.0 首次引入它时的定位。

六、电池电量阈值:MacBook 上的自我保护

6.1 功能说明

1.4.0 新增了一项对笔记本用户非常实用的高级偏好:设定一个电池电量阈值,当 MacBook 电量降到该值以下时,应用自动停用(即终止防睡眠定时器)。这样既能在需要时保持系统清醒,又不会让笔记本在无人看管时因电量耗尽而强制关机(对应 Issue #24)。

6.2 存储键与默认约束

相关键定义于 NSUserDefaults+KYAKeys.m:

NSString * const KYAUserDefaultsKeyBatteryCapacityThresholdEnabled =
    @"info.marcel-dierkes.KeepingYouAwake.BatteryCapacityThresholdEnabled";

NSString * const KYAUserDefaultsKeyBatteryCapacityThreshold =
    @"info.marcel-dierkes.KeepingYouAwake.BatteryCapacityThreshold";

- (CGFloat)kya_batteryCapacityThreshold
{
    CGFloat threshold = [self floatForKey:KYAUserDefaultsKeyBatteryCapacityThreshold];
    return MAX(10.0f , threshold);   // 读取时强制下限 10%
}

注意读取时的 MAX(10.0f, threshold):无论用户写入多小的值,读取到的阈值最低为 10%,避免误设 0 导致应用一激活就立刻停用。

6.3 电量监控:IOKit 与运行循环通知

电量数据由 KYABatteryMonitor 提供(KYABatteryMonitor.m)。它通过 IOKit 的电源管理框架读取电量信息:

  • IOPSCopyPowerSourcesInfo() / IOPSCopyPowerSourcesList() 获取电源信息列表;
  • IOPSGetPowerSourceDescription() 取出电源描述字典;
  • kIOPSCurrentCapacityKey 对应当前电量百分比,kIOPSTypeKey 与 kIOPSInternalBatteryType 用于判断是否内置电池(hasBattery)。

为了在电量变化时及时响应,KYABatteryMonitor 通过 IOPSNotificationCreateRunLoopSource 注册一个 RunLoop Source,电量变化时触发 KYABatteryMonitorChangeHandler 回调(KYABatteryMonitor.m),进而驱动 KYADevice 发出 KYADeviceParameterDidChangeNotification。

6.4 停用决策链路

决策逻辑集中在 KYAAppController.m:

  • checkAndEnableBatteryOverride(KYAAppController.m)在启用监控时立即比对 currentCapacity <= threshold,设置电池覆盖状态;
  • deviceParameterDidChange:(KYAAppController.m)监听 KYADeviceParameterDidChangeNotification:当参数为电池且 kya_isBatteryCapacityThresholdEnabled 为 YES 时,若定时器仍在运行、当前电量不高于阈值且尚未启用覆盖,则调用 terminateTimer 立即停用防睡眠;
  • 阈值设置变化时,batteryCapacityThresholdDidChange:(KYAAppController.m)会先终止当前定时器,避免旧阈值下的决策继续生效。

6.5 当前版本中的 UI 位置

在 1.4.0 中,电池阈值以高级偏好形式出现;随着版本演进,仓库中已出现独立的电池设置页 KYABatterySettingsViewController.m(文件头注释显示其创建于 2021 年),并在阈值改变时通过 NSNotificationCenter 广播 kKYABatteryCapacityThresholdDidChangeNotification(常量定义于 KYABatteryCapacityThreshold.h),与 KYAAppController 保持联动。可以推断,电池相关设置最终从高级设置中独立出来,成为单独的标签页,方便笔记本用户集中管理。

七、Sparkle 1.14.0:自动更新的安全修复

发布说明的最后一条变更将 Sparkle(macOS 上流行的软件自动更新框架)从旧版本升级到 1.14.0,目的是修复潜在的安全问题。这属于依赖层面的加固:通过升级自动更新框架,避免旧版本中可能存在的漏洞被利用。当前仓库中仍有 KYAAppUpdater 模块负责与 Sparkle 的集成,以及 docs/appcast.xml 与 docs/prerelease-appcast.xml 作为更新源的 appcast 描述,说明该自动更新链路至今仍在持续使用。

八、总结

KeepingYouAwake 1.4.0 是一次典型的"体验收敛 + 能力外放"版本:

  • 体验层面:引入偏好设置窗口,把低频菜单项收纳进统一界面,并新增"默认激活时长"这一高频设置;
  • 能力层面:通过"允许显示器休眠"暴露 caffeinate -i,通过"电池电量阈值"为笔记本用户提供自动停用的保护机制,同时移除语义混乱的 PreventSleepOnACPower;
  • 工程层面:升级 Sparkle 修复安全问题。

这些偏好的存储键、默认值与读取约束至今仍可追溯:布尔型偏好统一以 info.marcel-dierkes.KeepingYouAwake. 为前缀(NSUserDefaults+KYAKeys.m),时长类偏好以秒为单位存入 TimeInterval 键,电池阈值读取时强制不低于 10%。对于想要深入了解或二次开发 KeepingYouAwake 的读者,建议从 KYAAppController.m(决策中枢)、KYASleepWakeTimer.m(caffeinate 调度)与 KYABatteryMonitor.m(电源监控)三条主线入手,即可完整还原 1.4.0 引入的所有机制。

登录后查看全文
KeepingYouAwake