Primeros pasos

Instalar

Puedes usar nuestro setup asistido por IA para instalar el plugin. Añade las skills de Capgo a tu herramienta de IA con el siguiente comando:

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

Luego usa el siguiente prompt:

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

Si prefieres la configuración manual, instala el plugin ejecutando estos comandos y sigue las instrucciones de cada plataforma:

bun add @capgo/capacitor-calendar
bunx cap sync

Inicio rápido

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

Ejemplo: flujo del editor del sistema

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

Errores comunes

• Niveles de acceso en iOS: elige los helpers de solo lectura, solo escritura o acceso total según tu funcionalidad; no pidas permisos de más.
• Reminders es solo para iOS: protege las APIs de Reminders cuando Capacitor.getPlatform() === 'ios'.
• Zonas horarias: pasa offsets explícitos o milisegundos UTC que sean consistentes con tu backend.

iOS Setup

Añade las descripciones de uso que tu app necesite en 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 y versiones posteriores distinguen entre acceso de solo escritura y acceso completo al calendario. Solo incluye descripciones de uso de recordatorios si tu app llama a las Reminders APIs.

Referencia de Apple: Migración a los últimos niveles de acceso al Calendario.

Configuración de Android

Añade los permisos de calendario que tu app necesite a android/app/src/main/AndroidManifest.xml:

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

Referencia de Android: Permisos de usuario de Calendar Provider.

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

Para apps que solo añaden eventos, usa requestWriteOnlyCalendarAccess(). Para flujos de solo lectura en Android, usa requestReadOnlyCalendarAccess().

Crear un evento

Las fechas son Unix timestamps en milisegundos.

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

Abrir el editor de eventos nativo

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

En Android, las llamadas de creación y modificación mediante prompt devuelven null. Lista los eventos después si necesitas hallar el ID del evento creado.

Listar próximos eventos

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

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

Elige un calendario

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

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

selectCalendarsWithPrompt() está disponible en iOS cuando quieras mostrar el selector de calendario del sistema.

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

Las APIs de Reminder son solo para iOS.

App de ejemplo

El repositorio incluye una app de ejemplo Capacitor con validación de permisos, creación de eventos, prompts nativos, listado de calendarios y de rangos de eventos.

iOS	Android

Referencia de API

La referencia completa de API se mantiene en el README del paquete y en las definiciones de TypeScript:

• README
• Definiciones de tipos