Per iniziare

Installa

Puoi usare il nostro setup assistito dall'IA per installare il plugin. Aggiungi le skill Capgo al tuo strumento di IA usando il seguente comando:

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

Poi usa il seguente prompt:

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

Se preferisci la configurazione manuale, installa il plugin eseguendo questi comandi e segui le istruzioni specifiche per piattaforma qui sotto:

bun add @capgo/capacitor-calendar
bunx cap sync

Avvio rapido

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

Esempio: flusso dell'editor di sistema

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

Errori comuni

• Livelli di accesso iOS: scegli gli helper di sola lettura, sola scrittura o accesso completo in base alla tua feature, senza richiedere permessi eccessivi.
• I Promemoria sono solo per iOS: proteggi le API dei Reminders quando Capacitor.getPlatform() === 'ios'.
• Fusi orari: passa offset espliciti o millisecondi UTC coerenti con il tuo backend.

Setup iOS

Aggiungi le descrizioni d'uso necessarie alla tua app a 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 e versioni successive distinguono tra accesso in sola scrittura e accesso completo al calendario. Includi le descrizioni per i promemoria solo se la tua app utilizza le Reminders API.

Riferimento Apple: Migrazione ai più recenti livelli di accesso al Calendario.

Configurazione Android

Aggiungi i permessi per il calendario necessari alla tua app a android/app/src/main/AndroidManifest.xml:

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

Riferimento Android: Permessi utente di Calendar Provider.

Richiedere l'accesso al Calendario

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

const permission = await CapacitorCalendar.requestFullCalendarAccess();

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

Per le app che aggiungono solo eventi, usa requestWriteOnlyCalendarAccess(). Per flussi di sola lettura su Android, usa requestReadOnlyCalendarAccess().

Crea un evento

Le date sono Unix timestamp in millisecondi.

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

Apri il Native Event Editor

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

Su Android, le chiamate di creazione e modifica tramite prompt restituiscono null. Elenca gli eventi in seguito se devi trovare l'ID dell'evento creato.

Elenca eventi imminenti

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

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

Scegli un calendario

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

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

selectCalendarsWithPrompt() è disponibile su iOS quando vuoi mostrare il selettore del calendario di sistema.

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

Le API dei promemoria sono solo per iOS.

App di esempio

Il repository include un'app di esempio Capacitor con controlli dei permessi, creazione di eventi, prompt nativi, elenco calendario ed elenco intervalli eventi.

iOS	Android

Riferimento API

La documentazione completa di API è disponibile nel README del pacchetto e nelle definizioni TypeScript:

• README
• Definizioni dei tipi