开始使用

安装

您可以使用我们的AI辅助安装来安装插件。使用以下命令将Capgo技能添加到您的AI工具中：

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.

如果您更喜欢手动设置，请按照以下命令安装插件，并遵循以下平台特定的说明:

npm install @capgo/capacitor-calendar
npx cap sync

iOS 设置

添加您的应用程序需要的使用说明 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 及更高版本区分写入和全日历访问权限。仅在您的应用程序调用提醒 API 时才包括提醒使用说明。

苹果参考: 迁移到最新的日历访问级别.

安卓设置

添加您的应用程序需要的日历权限 android/app/src/main/AndroidManifest.xml:

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

安卓参考: 日历提供者用户权限.

请求日历访问

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

const permission = await CapacitorCalendar.requestFullCalendarAccess();

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

仅添加事件的应用程序使用 requestWriteOnlyCalendarAccess()仅用于安卓读取流程的应用程序使用 requestReadOnlyCalendarAccess().

创建事件

时间戳以毫秒为单位

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 上，基于提示的创建和修改调用返回 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',
  });
}

提醒 API 只适用于 iOS。

示例应用

The repository includes a Capacitor example app with permission checks, event creation, native event prompts, calendar listing, and event range listing.

iOS	Android

API参考

API参考文档的完整内容保存在包README和TypeScript定义中:

• README
• 类型定义