スタートガイド

インストール

AIアシストによるセットアップでプラグインをインストールできます。以下のコマンドを使用して、お使いの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'.
• タイムゾーン: バックエンドと整合性を保つため、明示的なオフセットまたは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を呼び出す場合に限り、リマインダーの使用目的の説明を含めてください。

Appleのリファレンス: 最新のCalendarアクセスレベルへの移行.

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タイムスタンプです。

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専用です。

サンプルアプリ

このリポジトリには、権限チェック、イベント作成、ネイティブのイベントプロンプト、カレンダー一覧、イベント範囲一覧を備えた Capacitor のサンプルアプリが含まれています。

iOSと	Androidでは

API リファレンス

API の完全なリファレンスは、パッケージのREADMEとTypeScriptの型定義で管理されています:

• README
• 型定義