EventKit 集成

适用于 macOS/iOS 应用的高级 EventKit 模式。专为提醒系统、权限处理和双向同步而设计。

使用场景

在以下情况下使用此技能：

• - 集成 EventKit 提醒或事件
• 处理 EventKit 权限和授权
• 实现与外部数据的双向同步
• 使用零宽字符隐写术进行身份追踪
• 批量 EventKit 操作
• 构建僵尸任务自愈逻辑

核心原则

1. 基于 Actor 的服务

swift
import EventKit
import Foundation

actor EventKitService {
private let eventStore = EKEventStore()
private var timeFlowCalendar: EKCalendar?

func initialize() async throws {
let remindersGranted = try await eventStore.requestFullAccessToReminders()
let eventsGranted = try await eventStore.requestFullAccessToEvents()

guard remindersGranted && eventsGranted else {
throw EventKitError.permissionDenied
}

timeFlowCalendar = try await getOrCreateTimeFlowCalendar()
}
}

2. 日历管理

swift
private func getOrCreateTimeFlowCalendar() async throws -> EKCalendar {
let calendars = eventStore.calendars(for: .reminder)

if let existing = calendars.first(where: { $0.title == TimeFlow }) {
return existing
}

let calendar = EKCalendar(for: .reminder, eventStore: eventStore)
calendar.title = TimeFlow
calendar.source = eventStore.defaultCalendarForNewReminders()?.source

try eventStore.saveCalendar(calendar, commit: true)
return calendar
}

3. 批量获取模式

swift
func fetchAllReminders() async throws -> [ReminderSnapshot] {
guard let calendar = timeFlowCalendar else {
throw EventKitError.calendarNotFound
}

let incompletePredicate = eventStore.predicateForIncompleteReminders(
withDueDateStarting: nil, ending: nil, calendars: [calendar]
)

return try await withCheckedThrowingContinuation { continuation in
eventStore.fetchReminders(matching: incompletePredicate) { reminders in
if let reminders = reminders {
let snapshots = reminders.map { $0.toSnapshot() }
continuation.resume(returning: snapshots)
} else {
continuation.resume(returning: [])
}
}
}
}

权限处理

授权流程

swift
enum EventKitError: Error, LocalizedError {
case permissionDenied
case calendarNotFound

var errorDescription: String? {
switch self {
case .permissionDenied:
return 需要访问提醒事项的权限
case .calendarNotFound:
return 找不到 TimeFlow 日历
}
}
}

操作前检查

swift
func updateReminder(_ reminder: EKReminder) async throws {
// 操作前验证日历是否存在
guard timeFlowCalendar != nil else {
throw EventKitError.calendarNotFound
}

try eventStore.save(reminder, commit: true)
}

同步模式

零宽字符隐写术

在 EventKit 备注中不可见地嵌入身份签名：

swift
func buildNotes(from task: IdentityMap) -> String {
let baseNotes = task.notesSnapshot ??

// 嵌入零宽签名用于身份追踪
let signature = \u{200B}TIMEFLOW:\(task.localUUID)\u{200C}

return baseNotes.isEmpty ? signature : baseNotes + \n + signature
}

func extractSignature(from notes: String?) -> String? {
guard let notes = notes else { return nil }

let pattern = #\u{200B}TIMEFLOW:([^\u{200B}]+)\u{200C}#
guard let regex = try? NSRegularExpression(pattern: pattern),
let match = regex.firstMatch(in: notes, range: NSRange(notes.startRange, in: notes)) else {
return nil
}

guard let range = Range(match.range(at: 1), in: notes) else { return nil }
return String(notes[range])
}

关键：防止同步循环

从 EventKit 创建新的 IdentityMap 时，立即绑定：

swift
private func findOrCreateIdentityMap(for reminder: ReminderSnapshot) -> IdentityMap? {
if let existing = swiftDataService.findIdentityMap(by: reminder.id) {
return existing
}

let newMap = swiftDataService.createIdentityMap(
title: reminder.title,
projectName: nil,
contextTags: []
)

// 关键：立即绑定并标记为干净
// 这可以防止：新映射 -> 脏状态 -> 推送 -> 重复的无限循环
newMap.ekIdentifier = reminder.id
newMap.lastSyncDate = Date()
newMap.isDirty = false

return newMap
}

批量操作

分块批量删除

swift
func deleteReminders(identifiers: [String]) async throws -> Int {
var deletedCount = 0
let batchSize = 500

for id in identifiers {
if let reminder = eventStore.calendarItem(withIdentifier: id) as? EKReminder {
try eventStore.remove(reminder, commit: false)
deletedCount += 1
}

// 分批提交以提高性能
if deletedCount % batchSize == 0 {
try eventStore.commit()
}
}

// 最终提交
try eventStore.commit()
return deletedCount
}

僵尸任务自愈

宽限期模式

不要立即删除刚创建的任务：

swift
nonisolated func purgeZombieTasksBackground() {
let context = ModelContext(container)
context.autosaveEnabled = false

// 宽限期：1小时
// 新创建的任务 ekID 为 nil，但不是僵尸任务
let oneHourAgo = Date().addingTimeInterval(-3600)

let descriptor = FetchDescriptor(
predicate: #Predicate { $0.ekIdentifier == nil && $0.createdAt < oneHourAgo }
)

let zombies = (try? context.fetch(descriptor)) ?? []
guard !zombies.isEmpty else { return }

// 按标题分组以识别重复项
let grouped = Dictionary(grouping: zombies, by: { $0.titleSnapshot })

for (title, tasks) in grouped where tasks.count > 1 {
// 保留最旧的，删除重复项
let sorted = tasks.sorted { $0.createdAt < $1.createdAt }
for task in sorted.dropFirst() {
context.delete(task)
}
}

try? context.save()
}

测试模式

用于测试的 Mock EventKit

swift
@MainActor
final class EventKitServiceTests: XCTestCase {
var mockService: MockEventKitService!

override func setUp() async throws {
try await super.setUp()
mockService = MockEventKitService()
}

func testFetchAllReminders() async throws {
// 给定：模拟提醒
mockService.addReminder(id: EK-1, title: 任务 1)
mockService.addReminder(id: EK-2, title: 任务 2)

// 当：获取
let reminders = try await mockService.fetchAllReminders()

// 然后：验证
XCTAssertEqual(reminders.count, 2)
}
}

最佳实践

常见陷阱

运行 EventKit 测试

bash

测试 EventKit 集成