Prise en main

Installer

Vous pouvez utiliser notre configuration assistée par IA pour installer le plugin. Ajoutez les skills Capgo à votre outil d'IA avec la commande suivante :

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

Utilisez ensuite le prompt suivant :

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

Si vous préférez une installation manuelle, installez le plugin en exécutant les commandes suivantes et suivez les instructions spécifiques à chaque plateforme ci-dessous :

bun add @capgo/capacitor-calendar
bunx cap sync

Démarrage rapide

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',
});

Exemple : flux de l'éditeur système

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

Erreurs courantes

• Niveaux d'accès iOS: choisissez des helpers en lecture seule, écriture seule ou accès complet selon votre fonctionnalité, ne demandez pas plus que nécessaire.
• Les rappels sont limités à iOS: protégez les API Reminders lorsque Capacitor.getPlatform() === 'ios'.
• Fuseaux horaires: passez des décalages explicites ou des millisecondes UTC cohérents avec votre backend.

Configuration iOS

Add the usage descriptions your app needs to 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 et versions ultérieures distinguent l'accès en écriture seule de l'accès complet au calendrier. N'incluez les descriptions d'utilisation des rappels que si votre app appelle les API Reminders.

Référence Apple : Migration vers les derniers niveaux d'accès au calendrier.

Configuration Android

Ajoutez les permissions de calendrier nécessaires à votre application android/app/src/main/AndroidManifest.xml:

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

Référence Android : Permissions utilisateur du Calendar Provider.

Demander l'accès au calendrier

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

const permission = await CapacitorCalendar.requestFullCalendarAccess();

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

For apps that only add events, use requestWriteOnlyCalendarAccess(). For Android-only read flows, use requestReadOnlyCalendarAccess().

Créer un événement

Les dates sont des timestamps Unix en millisecondes.

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);

Ouvrir l'éditeur d'événement natif

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

Sur Android, les appels de création et de modification via prompt retournent null. Listez les événements ensuite si vous devez trouver l'ID de l'événement créé.

Lister les événements à venir

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

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

Choisir un calendrier

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

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

selectCalendarsWithPrompt() est disponible sur iOS lorsque vous souhaitez afficher le sélecteur de calendrier du système.

Créer un rappel iOS

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',
  });
}

Les API de rappel sont réservées à iOS.

Example App

Le dépôt inclut une application exemple Capacitor avec gestion des permissions, création d'événements, prompts d'événements natifs, liste des calendriers et liste des plages d'événements.

iOS	Android

Référence API

La référence API complète est disponible dans le README du package et les définitions TypeScript :

• README
• Définitions de types