시작하기

설치

AI-Assisted Setup으로 플러그인을 설치할 수 있습니다. 다음 명령어로 AI 도구에 Capgo 스킬을 추가하세요:

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

그런 다음 아래 프롬프트를 사용하세요:

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

수동 설정을 선호한다면, 다음 명령어를 실행하여 플러그인을 설치하고 아래의 플랫폼별 지침을 따르세요:

bun add @capgo/capacitor-calendar
bunx cap sync

빠른 시작

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

예시: 시스템 에디터 흐름

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

자주 하는 실수

• iOS 접근 권한 수준: 기능에 맞춰 읽기 전용, 쓰기 전용 또는 전체 접근 권한 헬퍼를 선택하세요. 과도한 권한 요청은 피해야 합니다.
• Reminders는 iOS 전용입니다: Reminders API 사용 시 다음 사항을 주의하세요. Capacitor.getPlatform() === 'ios'.
• 시간대(Time zones): 백엔드와 일치하도록 명시적인 오프셋이나 UTC 밀리초를 전달하세요.

iOS 설정

앱에 필요한 사용 설명(usage descriptions)을 다음 항목에 추가하세요. 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 이상에서는 쓰기 전용 캘린더 접근과 전체 캘린더 접근을 구분합니다. 앱에서 Reminders API를 호출하는 경우에만 Reminders 사용 설명을 포함하세요.

Apple 공식 문서: 최신 캘린더 접근 권한 수준으로 마이그레이션하기.

Android 설정

앱에 필요한 캘린더 권한을 다음 항목에 추가하세요: android/app/src/main/AndroidManifest.xml:

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

Android 공식 문서: Calendar Provider 사용자 권한.

캘린더 권한 요청

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

const permission = await CapacitorCalendar.requestFullCalendarAccess();

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

이벤트 추가 기능만 있는 앱은 다음을 사용하세요: requestWriteOnlyCalendarAccess()를 사용하세요. Android 전용 읽기 흐름의 경우 requestReadOnlyCalendarAccess().

이벤트 생성

날짜는 밀리초 단위의 Unix timestamp입니다.

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

네이티브 이벤트 에디터 열기

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

Android에서 prompt 기반의 생성 및 수정 호출은 다음을 반환합니다: null생성된 이벤트 ID를 확인해야 하는 경우, 이후에 이벤트를 리스트업하세요.

다가오는 이벤트 목록

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

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

캘린더 선택

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

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

selectCalendarsWithPrompt() 시스템 캘린더 피커를 표시하려면 iOS에서 사용할 수 있습니다.

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

Reminder API는 iOS 전용입니다.

예제 앱

이 저장소에는 권한 확인, 이벤트 생성, 네이티브 이벤트 prompt, 캘린더 목록, 이벤트 범위 목록이 포함된 Capacitor 예제 앱이 있습니다.

iOS	Android

API 레퍼런스

전체 API 레퍼런스는 패키지 README와 TypeScript 정의에서 관리됩니다:

• README
• 타입 정의