Erste Schritte

Installieren

Du kannst unser KI-gestütztes Setup nutzen, um das Plugin zu installieren. Füge die Capgo Skills mit dem folgenden Befehl deinem KI-Tool hinzu:

npx skills add https://github.com/Cap-go/capgo-skills --skill capacitor-plugins

Nutze dann diesen Prompt:

Use the `capacitor-plugins` skill from `Cap-go/capgo-skills` to install the `@capgo/capacitor-calendar` plugin in my project.

Wenn du ein manuelles Setup bevorzugst, installiere das Plugin mit den folgenden Befehlen und befolge die plattformspezifischen Anweisungen unten:

bun add @capgo/capacitor-calendar
bunx cap sync

Quickstart

import { CapacitorCalendar } from '@capgo/capacitor-calendar';

await CapacitorCalendar.requestFullCalendarAccess();
await CapacitorCalendar.createEvent({
  title: 'Site visit',
  startDate: Date.now(),
  endDate: Date.now() + 60 * 60 * 1000,
  location: 'Warehouse 4',
});

Beispiel: System-Editor-Flow

await CapacitorCalendar.createEventWithPrompt({
  title: 'Team sync',
  startDate: Date.now() + 86400000,
  endDate: Date.now() + 90000000,
});

Häufige Stolperfallen

• iOS-Zugriffsrechte: Wähle Read-only, Write-only oder Full Access passend zu deinem Feature – fordere nicht mehr an als nötig.
• Reminders sind nur für iOS verfügbar: Schütze die Reminders APIs, wenn Capacitor.getPlatform() === 'ios'.
• Zeitzonen: Übergib explizite Offsets oder UTC-Millisekunden, die mit deinem Backend konsistent sind.

iOS-Setup

Füge die benötigten Usage Descriptions deiner App hinzu ios/App/App/Info.plist:

<key>NSCalendarsUsageDescription</key>
<string>This app needs calendar access.</string>
<key>NSCalendarsWriteOnlyAccessUsageDescription</key>
<string>This app needs permission to add calendar events.</string>
<key>NSCalendarsFullAccessUsageDescription</key>
<string>This app needs permission to read and manage calendar events.</string>
<key>NSRemindersUsageDescription</key>
<string>This app needs reminders access.</string>
<key>NSRemindersFullAccessUsageDescription</key>
<string>This app needs permission to read and manage reminders.</string>

iOS 17 und neuer unterscheidet zwischen Schreibzugriff und vollem Kalenderzugriff. Füge Beschreibungen für die Nutzung von Erinnerungen nur hinzu, wenn deine App die Reminders APIs aufruft.

Apple Referenz: Migration auf die neuesten Kalender-Zugriffsrechte.

Android-Setup

Füge die benötigten Kalender-Berechtigungen hinzu unter: android/app/src/main/AndroidManifest.xml:

<uses-permission android:name="android.permission.READ_CALENDAR" />
<uses-permission android:name="android.permission.WRITE_CALENDAR" />

Android Referenz: Calendar Provider Benutzerberechtigungen.

Kalenderzugriff anfordern

import { CapacitorCalendar } from '@capgo/capacitor-calendar';

const permission = await CapacitorCalendar.requestFullCalendarAccess();

if (permission.result !== 'granted') {
  throw new Error('Calendar permission was not granted');
}

Für Apps, die nur Events hinzufügen, nutze requestWriteOnlyCalendarAccess(). Für reine Android-Read-Flows nutze requestReadOnlyCalendarAccess().

Event erstellen

Datumsangaben sind Unix-Timestamps in Millisekunden.

import { CapacitorCalendar } from '@capgo/capacitor-calendar';

const startDate = Date.now() + 60 * 60 * 1000;
const endDate = startDate + 60 * 60 * 1000;

const { id } = await CapacitorCalendar.createEvent({
  title: 'Product review',
  location: 'Capgo',
  startDate,
  endDate,
  description: 'Created with @capgo/capacitor-calendar',
});

console.log('Created event', id);

Den nativen Event-Editor öffnen

await CapacitorCalendar.createEventWithPrompt({
  title: 'Planning session',
  location: 'Office',
  startDate: Date.now() + 24 * 60 * 60 * 1000,
  endDate: Date.now() + 25 * 60 * 60 * 1000,
});

Auf Android geben prompt-basierte Create- und Modify-Aufrufe null zurück. Liste die Events danach auf, falls du die erstellte Event-ID finden musst.

Kommende Events auflisten

const now = Date.now();
const oneWeekFromNow = now + 7 * 24 * 60 * 60 * 1000;

const { result: events } = await CapacitorCalendar.listEventsInRange({
  from: now,
  to: oneWeekFromNow,
});

Kalender auswählen

const { result: calendars } = await CapacitorCalendar.listCalendars();
const { result: defaultCalendar } = await CapacitorCalendar.getDefaultCalendar();

const calendarId = defaultCalendar?.id ?? calendars[0]?.id;

selectCalendarsWithPrompt() ist auf iOS verfügbar, wenn du den System-Kalender-Picker anzeigen möchtest.

iOS-Reminder erstellen

const permission = await CapacitorCalendar.requestFullRemindersAccess();

if (permission.result === 'granted') {
  await CapacitorCalendar.createReminder({
    title: 'Send launch notes',
    dueDate: Date.now() + 2 * 24 * 60 * 60 * 1000,
    notes: 'Created with @capgo/capacitor-calendar',
  });
}

Reminder APIs sind nur für iOS verfügbar.

Beispiel-App

Das Repository enthält eine Capacitor Beispiel-App mit Berechtigungsprüfungen, Event-Erstellung, nativen Event-Prompts, Kalenderauflistung und Event-Zeitraumauflistung.

iOS	Android

API Referenz

Die vollständige API Referenz findest du in der README des Packages und in den TypeScript-Definitionen:

• README
• Type-Definitionen