快速入门

安装

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

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

然后使用以下 prompt：

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 访问权限级别: 根据功能选择“只读”、“只写”或“完全访问”权限，避免过度申请权限。
• 提醒事项仅限 iOS: 在使用 Reminders API 时需进行防护，以防 Capacitor.getPlatform() === 'ios'.
• 时区: 传入与后端保持一致的显式偏移量或 UTC 毫秒数。

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 及更高版本会区分仅写入和完整日历访问权限。仅当你的应用调用 Reminders API 时，才需要包含提醒事项使用说明。

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 时间戳。

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 使用。

示例 App

该仓库包含一个 Capacitor 示例 App，涵盖了权限检查、事件创建、原生事件提示、日历列表以及事件范围列表等功能。

iOS	Android

API 参考

完整的 API 参考文档维护在 package 的 README 和 TypeScript 定义中：

• README
• 类型定义