axiom-eventkit（Axiom 事件包）

EventKit — Discipline

Core Philosophy

"Request the minimum access needed, and only when it's needed."

Mental model: EventKit has three access tiers. Most apps need only the first (no access + system UI). Requesting more than you need means more users deny your request, and more code to maintain.

When to Use This Skill

Use this skill when:

• Adding events or reminders to the user's calendar
• Choosing between EventKitUI, write-only, or full access
• Requesting calendar or reminder permissions
• Fetching, querying, or displaying existing events
• Migrating from pre-iOS 17 permission APIs
• Creating virtual conference extensions
• Implementing Siri Event Suggestions for reservations
• Debugging "access denied" or missing events

Do NOT use this skill for:

• Contacts framework questions (use contacts)
• General SwiftUI architecture (use swiftui-architecture)
• Background task scheduling (use background-processing)

Related Skills

• eventkit-ref — Complete EventKit/EventKitUI API reference
• contacts — Contacts framework discipline skill
• privacy-ux — General iOS privacy patterns and Permission UX
• extensions-widgets — WidgetKit if combining calendar with widgets
• background-processing — If scheduling background calendar sync

Access Tier Decision Tree

digraph access_decision {
    rankdir=TB;
    "What does your app need?" [shape=diamond];
    "Add single events to Calendar?" [shape=diamond];
    "Show custom create/edit UI?" [shape=diamond];
    "Read existing events/calendars?" [shape=diamond];

    "No access + EventKitUI" [shape=box, label="Tier 1: No Access\nPresent EKEventEditViewController\nNo permission prompt needed"];
    "No access + Siri Suggestions" [shape=box, label="Tier 1: No Access\nSiri Event Suggestions\nFor reservations only"];
    "Write-only access" [shape=box, label="Tier 2: Write-Only\nrequestWriteOnlyAccessToEvents()\nCan save but not read"];
    "Full access" [shape=box, label="Tier 3: Full Access\nrequestFullAccessToEvents()\nor requestFullAccessToReminders()"];

    "What does your app need?" -> "Add single events to Calendar?" [label="events"];
    "What does your app need?" -> "Full access" [label="reminders\n(always full)"];
    "Add single events to Calendar?" -> "No access + EventKitUI" [label="yes, one at a time"];
    "Add single events to Calendar?" -> "Show custom create/edit UI?" [label="no, batch or silent"];
    "Show custom create/edit UI?" -> "Write-only access" [label="yes, or batch save"];
    "Show custom create/edit UI?" -> "Read existing events/calendars?" [label="no"];
    "Read existing events/calendars?" -> "Full access" [label="yes"];
    "Read existing events/calendars?" -> "Write-only access" [label="no"];
    "Add single events to Calendar?" -> "No access + Siri Suggestions" [label="reservation-style\n(restaurant, flight, hotel)"];
}

Key rule: Reminders ALWAYS require full access. There is no write-only tier for reminders.

The Three Access Tiers

Tier 1: No Access (Preferred)

Present EKEventEditViewController — it runs out-of-process on iOS 17+ and requires zero permissions.

let store = EKEventStore()
let event = EKEvent(eventStore: store)
event.title = "Team Standup"
event.startDate = startDate
event.endDate = Calendar.current.date(byAdding: .hour, value: 1, to: startDate) ?? startDate
event.timeZone = TimeZone(identifier: "America/Los_Angeles")
event.location = "Conference Room A"

let editVC = EKEventEditViewController()
editVC.event = event
editVC.eventStore = store
editVC.editViewDelegate = self
present(editVC, animated: true)

Why this is best: No permission prompt. No denial risk. System handles Calendar selection and save. Works on iOS 4+.

For reservations (restaurant, flight, hotel, event tickets), use Siri Event Suggestions instead — events appear in Calendar inbox without any permission. See the eventkit-ref skill for the INReservation donation pattern.

Tier 2: Write-Only Access (iOS 17+)

Use only when you need: custom editing UI, batch saves, or silent event creation.

let store = EKEventStore()
guard try await store.requestWriteOnlyAccessToEvents() else {
    // User denied — handle gracefully
    return
}
let event = EKEvent(eventStore: store)
event.calendar = store.defaultCalendarForNewEvents  // REQUIRED for write-only
event.title = "Recurring Standup"
event.startDate = startDate
event.endDate = endDate
try store.save(event, span: .thisEvent)

Write-only constraints:

• Returns a single virtual calendar, not the user's real calendars
• Event queries return empty results
• System chooses destination calendar for created events
• Cannot read events back, even ones your app created

Info.plist required: NSCalendarsWriteOnlyAccessUsageDescription

Tier 3: Full Access

Use only when your app's core feature requires reading, modifying, or deleting existing events.

let store = EKEventStore()
guard try await store.requestFullAccessToEvents() else { return }

// Now you can fetch events
let interval = Calendar.current.dateInterval(of: .month, for: Date())!
let predicate = store.predicateForEvents(withStart: interval.start, end: interval.end, calendars: nil)
let events = store.events(matching: predicate)
    .sorted { $0.compareStartDate(with: $1) == .orderedAscending }

Info.plist required: NSCalendarsFullAccessUsageDescription

For reminders:

guard try await store.requestFullAccessToReminders() else { return }

Info.plist required: NSRemindersFullAccessUsageDescription

Anti-Patterns

Reminder Patterns

Reminders ALWAYS require requestFullAccessToReminders().

Creating a Reminder

let reminder = EKReminder(eventStore: store)
reminder.title = "Review PR"
reminder.calendar = store.defaultCalendarForNewReminders()  // Required

// Due dates use DateComponents, NOT Date
if let dueDate = dueDate {
    reminder.dueDateComponents = Calendar.current.dateComponents(
        [.year, .month, .day, .hour, .minute], from: dueDate
    )
}

reminder.priority = EKReminderPriority.medium.rawValue
try store.save(reminder, commit: true)

Fetching Reminders (Async)

Unlike events, reminder fetches are asynchronous:

let predicate = store.predicateForReminders(in: nil)  // nil = all calendars
let reminders = try await withCheckedThrowingContinuation { continuation in
    store.fetchReminders(matching: predicate) { reminders in
        if let reminders {
            continuation.resume(returning: reminders)
        } else {
            continuation.resume(throwing: TodayError.failedReadingReminders)
        }
    }
}

Creating Reminder Lists

Reminder lists are EKCalendar objects filtered by entity type:

let newList = EKCalendar(for: .reminder, eventStore: store)
newList.title = "Sprint Tasks"

// Source selection matters — prefer .local or .calDAV
guard let source = store.sources.first(where: {
    $0.sourceType == .local || $0.sourceType == .calDAV
}) ?? store.defaultCalendarForNewReminders()?.source else {
    throw EventKitError.noValidSource
}

newList.source = source
try store.saveCalendar(newList, commit: true)

Store Lifecycle

Singleton Pattern

Create one EKEventStore and reuse it. Objects from one store instance cannot be used with another.

Change Notifications

NotificationCenter.default.addObserver(
    self, selector: #selector(storeChanged),
    name: .EKEventStoreChanged, object: store
)

@objc func storeChanged(_ notification: Notification) {
    // Refetch your current date range
    // Individual objects: call refresh() — if false, refetch
}

Batch Operations

// Pass commit: false for batch, then commit once
try store.save(event1, span: .thisEvent, commit: false)
try store.save(event2, span: .thisEvent, commit: false)
try store.commit()  // Atomic save
// On failure: store.reset() to rollback

Migration from Pre-iOS 17

Runtime compatibility:

if #available(iOS 17.0, *) {
    granted = try await store.requestFullAccessToEvents()
} else {
    granted = try await store.requestAccess(to: .event)
}

Keep old Info.plist keys alongside new ones to support iOS 16 and below.

Gotcha: Apps built with older Xcode SDKs map both .writeOnly and .fullAccess to .authorized. This means an app linked against an old SDK may fail to fetch events even after users granted full access — because the app sees .authorized but the system gave .writeOnly.

EventKitUI Decision Guide

Gotcha: EKEventEditViewController inherits from UINavigationController, not UIViewController. Do NOT embed it inside another navigation controller.

Gotcha: EKEventViewController inherits from UIViewController and CAN be pushed onto a navigation stack.

Gotcha: Under write-only access, EKCalendarChooser ignores displayStyle and always shows writable calendars only.

Pressure Scenarios

Scenario 1: "Just request full access, we might need it later"

Pressure: Product manager asks for full access "just in case."

Why resist: Full access prompts are denied 30%+ of the time. Write-only or EventKitUI gets you event creation with near-zero denials. You can always upgrade later if a reading feature is added.

Response: "Full access shows a scary prompt about reading ALL calendar data. For adding events, EventKitUI needs no prompt at all. Let's start there and upgrade if we ship a feature that reads events."

Scenario 2: "The deprecated API still works, we'll migrate later"

Pressure: Deadline pressure to skip migration from requestAccess(to:).

Why resist: On iOS 17, calling requestAccess(to:.event) throws an error — no prompt, no access, broken feature. Users on iOS 17+ get a silent failure.

Response: "The deprecated API throws on iOS 17. It's not 'deprecated but works' — it's broken. The fix is a 3-line #available check."

Scenario 3: "Just create a new EKEventStore for each screen"

Pressure: Different view controllers each create their own store for isolation.

Why resist: Objects from one store cannot be used with another. Events fetched from store A cannot be saved by store B. Change notifications only fire on the store that's registered.

Response: "EventKit requires a single shared store. Objects are bound to the store that created them. Create one and inject it."

Error Handling

Key EKErrorDomain codes to handle:

Resources

WWDC: 2023-10052, 2020-10197

Docs: /eventkit, /eventkitui, /technotes/tn3152, /technotes/tn3153

Skills: eventkit-ref, contacts, privacy-ux, extensions-widgets