iOS 26 新增了 AlarmKit。这是第一个能让第三方应用设定“和系统时钟同等地位”的闹钟的公开 API:全屏显示,在静音模式和专注模式下照样响,直到用户手动停止。我们用它做了 KeyAlarm——一个把日历日程变成真正闹钟的小应用,2026 年 8 月 27 日在 App Store 上架。

目前关于 AlarmKit 在正式产品中如何使用的资料还很少。下面是我们希望一开始就知道的几件事。

1. 准备工作只有两步

AlarmKit 需要的只有:

  • 在 Info.plist 里写上 NSAlarmKitUsageDescription(注意:xcodebuild -exportLocalizations 不会导出这个键,需要在每个语言的 InfoPlist.strings 里手动翻译)
  • 在运行时调用 AlarmManager.shared.requestAuthorization()

除此之外不需要在开发者网站上开启任何额外的功能。

2. 闹钟的 ID 必须是确定的

AlarmKit 的闹钟用你自己指定的 UUID 来标识。我们只用两样东西生成它:日历日程的标识符,和截断到“分钟”的响铃时间。

// PlannedAlarm.deterministicID — 类 UUIDv5,去掉秒,
// 这样 EventKit 开始时间里毫秒级的抖动不会改变 ID。
static func deterministicID(eventID: String, fireDate: Date) -> UUID {
    let fireMinute = Int(fireDate.timeIntervalSince1970.rounded(.down)) / 60
    return uuidV5(name: "\(eventID)|\(fireMinute)")
}

其他东西一概不放进去:不放命中的规则,不放日程标题,也不放“提前几分钟”。原因在于重新扫描时会发生什么:如果 ID 变了,就得先取消旧闹钟再注册新的;而一旦这一对“取消/注册”恰好跨过了响铃时间,闹钟就会悄无声息地消失。ID 稳定之后,重新扫描就变成了幂等的对账:算出“应该有的集合”,和 AlarmManager.shared.alarms 做差集,缺的补上,多的取消,其余一概不动。

铃声、稍后提醒和倒计时也刻意不放进 ID,而是放进另一个“配置指纹”,对账时用它判断已有的闹钟是否需要重新注册。有一个细节:倒计时的数值会随着响铃时间临近自然变小,所以指纹里只记录“有没有倒计时”,不记录长度。我们一开始比较的是数值,结果倒计时期间的每次同步都被当成配置变化,闹钟在实时活动显示的同时被取消又重建。

相关的规则:已经响过的闹钟永远不要取消。我们遇到过一个 bug:闹钟正在响时重新打开应用,启动时的同步把正在响的闹钟“对账掉”了。现在对账器会跳过响铃时间已过的闹钟的取消操作。

这些都由两组测试守着,我们把它们当作不可删改的底线:一组断言规则或标题改变时 ID 保持不变,另一组断言连续同步两次时,第二次对 AlarmKit 的调用为零。

3. 不要依赖后台刷新,提前两周注册

BGAppRefreshTask 只是“尽力而为”。手机一直开着低电量模式时,它可能好几天都不运行。如果闹钟是由后台任务创建的,失败的样子就是“什么都没响,也没人发现”。

所以我们不这么做。每当打开应用、日历数据库发生变化或编辑规则时,就把未来 14 天的闹钟全部直接注册到 AlarmKit。注册之后,不管应用以后还运不运行,闹钟都会按时响。后台刷新只是锦上添花,不是前提。

代价是同时存在的闹钟数量。AlarmKit 的上限没有公开文档。我们默认最多 30 个,优先最近的,并且会告诉用户有几个没排上,而不是悄悄丢掉。

4. 让规划逻辑保持“纯”

真正做判断的只有三个文件:KeywordMatcher、AlarmPlanner、Reconciler。它们都不 import EventKit,也不 import AlarmKit。与系统的边界只有两个协议:EventProviding 和 AlarmScheduling,测试时用假实现替换。第 2、3 节的内容全部用这些假实现做了单元测试,包括“第二次运行什么都不做”这一性质。如果让 EKEvent 或 AlarmManager 渗进规划逻辑,这些就都只能在真机上测了。

5. 实时活动的 Metadata 要放在共享目录

AlarmKit 用实时活动显示倒计时,类型是你自己定义的 AlarmAttributes<Metadata>。这个 Metadata 类型在应用和小组件扩展里必须完全一致。如果文件只加进了其中一个 target,实时活动就解码失败,你会看到一个空白的倒计时,而且没有任何报错。我们把 KeyAlarmMetadata.swift 放在 Shared/ 目录里,两个 target 的 sources 都包含它。

6. 远程“强制更新”开关必须失败时放行

我们在网站上放了一个很小的 version.json,以防某个版本出了让闹钟不响的 bug 时可以强制用户更新。这个检查在任何网络错误时都返回 .ok。如果失败时拦截,那么飞行模式、需要登录的公共 Wi-Fi、或者我们的 CDN 出点问题,都会把一个闹钟应用变成打不开的砖头。失败放行的路径有专门的测试,而且不是可选的。

7. 审核:准则 5.1.1(iv)

我们在系统弹窗出现之前,有一个说明“为什么需要日历和闹钟权限”的预先说明页。第一次提交因为这个页面上的按钮写着“允许”而被以 5.1.1(iv) 拒绝。自定义页面不能看起来像是它自己在授予权限,按钮必须是中性的。改成“继续”就是全部的修改。第一次就做对,成本很低。

KeyAlarm 用这些做了什么

只需登记一次关键词(比如“钢琴课”),标题里含有这个词的每个日历日程都会在一个或多个提前时间变成真正的闹钟(提前 30 分钟准备,提前 5 分钟出门)。1.16 版起还可以把所有闹钟暂停 1、3、6 或 24 小时,也能用 Siri 或快捷指令操作。没有服务器,不需要账号,App Store 隐私标签为“未收集数据”。需要 iOS 26 及以上,免费试用 30 天,之后一次性买断(不是订阅)。

欢迎通过联系表单交流 AlarmKit 的问题。

KeyAlarm 已在 App Store 上架。 需要 iOS 26 或更高版本。免费试用 30 天,之后一次性买断。无订阅、无账号、无服务器。 App Store · 产品页面 · 英文原文

不在日历里的待办事项,可以用姊妹 App MustDo:不做完就一直响的待办闹钟。