@ebarooni/电容-日历

@ebarooni/capacitor-calendar 连接您的 Capacitor app 到本地日历 。 在iOS和Android上,创建,编辑和列出事件,并管理日历和权限. iOS还支持提醒. 在网络上,插件会构建一个可下载的 .ics 文件; 它不写入设备日历.

目录

• 特征和平台
• 演示
• 为什么是这个插件?
• MCP 服务器
• 电容兼容性
• 安装
• 设置
• 错误代码
• 快速启动
• 用法实例
• 文档
• 更改日志
• 中断更改
• API 密码
• 捐款
• 许可证

特征和平台

在网络上, createEvent 财务报告和审定财务报表 createEventWithPrompt 返回可下载 .ics 文档。 它们不会写入设备日历 。 见 在网络上创建和下载一个事件。 。 。 .

演示

iOS系统	机器人

网络 : 在浏览器中运行示例应用程序 。 使用 创建事件 或者说 快速创建事件 页:1 .ics 输出。 不支持的动作被禁用 .

为什么是这个插件?

• 已建立. 从5号控制器开始就可用 背后有数年的真实世界.
• 积极维护. 原作者仍拥有代码库和船只修补和特征.
• 快速支撑. 问题和错误报告得到快速答案.
• 降低供应商风险. 依靠一个插件作者做每件事都是危险的. 独立,专注的维护者保持了你的堆积弹性.

MCP 服务器

@ebarooni/capacitor-calendar 官员 MCP 磁共振 服务器。 它为AI编码助手提供了对插件的准确,有根据的知识.

docker run --rm -d --name capacitor-calendar-mcp -p 8080:8080 ghcr.io/ebarooni/capacitor-calendar-mcp:1.2.0

见 mcp/README.md 用于客户端配置和全部细节.

电容兼容性

将 npm 标记匹配到您的 Capacitor 主修 。 这个 latest 财务报告和审定财务报表 latest-7 软件包旨在保持特性均等.

电容	npm 标签	版本
8.x	latest
7.x	latest-7

安装

电容8:

npm install @ebarooni/capacitor-calendar
# or: npm install @ebarooni/capacitor-calendar@latest
npx cap sync

电容7:

npm install @ebarooni/capacitor-calendar@latest-7
npx cap sync

设置

此插件与本地日历 API 工作, 因此您需要在运行时请求访问之前配置每个平台的权限 。 设置后,看 快速启动 以代码请求权限.

机器人

添加这些权限到 android/app/src/main/AndroidManifest.xml数字 :

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

在从日历读取或写入日历前请求匹配的运行时间权限 .

iOS系统

添加相应的使用描述密钥到 ios/App/App/Info.plist. 从iOS 17开始,苹果公司需要单独的密钥,用于只写和完整的日历访问.

<key>NSCalendarsUsageDescription</key>
<string>This app needs access to your calendar.</string>

<key>NSCalendarsWriteOnlyAccessUsageDescription</key>
<string>This app needs permission to create calendar events.</string>

<key>NSCalendarsFullAccessUsageDescription</key>
<string>This app needs permission to read and manage your calendar events.</string>

<key>NSRemindersUsageDescription</key>
<string>This app needs access to your reminders.</string>

<key>NSRemindersFullAccessUsageDescription</key>
<string>This app needs permission to read and manage your reminders.</string>

[大
只包含您的应用程序实际需要的密钥 。 如果只创建事件,则可以省略全部访问和提醒条目.

官方参考资料

• iOS: (英语) 移入最新日历访问级别
• 机器人: 日历提供者用户权限

错误代码

在Android和iOS上,一个被拒绝的电话可以曝光 error.code (稳定类别)和 error.message (确切原因). 将代码与导出代码进行比较 CapacitorCalendarErrorCode um. 并不是每个拒绝都有一个代码;后来的发布会添加更多的目录案例.

定义的代码 :

Android 拒绝非数字或空日历或事件 id 作为 InvalidArgumentiOS 查找系统日历存储中的字符串,并可能拒绝作为 NotFound 当没有匹配.

IoError: Android 和 iOS 地图存储失败,例如失败的创建/删除ID检索并删除失败. 其他不是允许或发射失败的日历存储错误也使用此代码. 在iOS上,EventKit商店或系统拒绝使用此代码,包括一些与授权相关的故障; Android 权限提供者拒绝使用 PermissionDenied (单位:千美元)EB-CLDR-0020) (中文(简体) ). 在 iOS 上,此代码也涵盖编辑即时 processFailed 结果.

NotSupported: Android 映射出一个缺失的日历活动处理器(ActivityNotFoundException,例如 openCalendar)到本码. iOS 地图发布和 URL 失败 (Failed to launch calendar app.,提醒, Unable to open URL.) (中文(简体) ).

在Android上,以权限错误拒绝失败的日历操作 PermissionDenied (单位:千美元)EB-CLDR-0020) (中文(简体) ). 权限检查和请求 API 仍然解决 "denied" android 和 iOS 上,他们不否认 0020。 。 。 .

对于Android和iOS包装系统存储,启动,和权限失败,消息从固定句子开始. 如果操作系统提供了不同的细节,则在括号中附上.

快速启动

以下样本为Android和iOS. 关于Web,见 在网络上创建和下载一个事件。 。 。 .

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

const { result } = await CapacitorCalendar.requestFullCalendarAccess();

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

// Create an event starting in 1 hour, lasting 1 hour
const startDate = Date.now() + 60 * 60 * 1000;
const endDate = startDate + 60 * 60 * 1000;

const { id } = await CapacitorCalendar.createEvent({
  title: 'Product review',
  location: 'Office',
  startDate,
  endDate,
  description: 'Created with @ebarooni/capacitor-calendar',
});

console.log('Event created with ID:', id);

[注]
日期以毫秒表示.

用法实例

在网络上创建和下载一个事件

网上, createEvent 财务报告和审定财务报表 createEventWithPrompt 构建一个 .ics 文档。 他们不会写信给日历店。 使用 autoDownloadIcsFile (默认 : false 打开 createEvent, (中文(简体) ), true 打开 createEventWithPrompt)或(或) downloadIcsFile。许可 API 未执行。 详情见MCP docs://web-behavior (单位:千美元)mcp/README.md) (中文(简体) ).

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

const startDate = Date.now() + 60 * 60 * 1000;
const endDate = startDate + 60 * 60 * 1000;

const { ics } = await CapacitorCalendar.createEvent({
  title: 'Team standup',
  startDate,
  endDate,
  icsFileName: 'team-standup.ics',
  autoDownloadIcsFile: true,
});

打开本地事件编辑器

使用系统日历 UI 允许用户创建或编辑事件( 在 Web: 确认对话框 + ICS 上):

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

[注]
在Android上,这种方法总是返回无效 id。如果需要事件标识,请拨 listEventsInRange(...) 后结. 在 Web 上,取消解决方式为 ics: null。 。 。 .

修改或删除事件

以下样本为Android和iOS. 使用一个 id 从 createEvent 或者说 listEventsInRange数字 :

await CapacitorCalendar.modifyEvent({
  id: eventId,
  title: 'Updated title',
});

await CapacitorCalendar.deleteEvent({
  id: eventId,
});

在一定范围内列出事件

listEventsInRange 返回与给定范围相重叠的事件,而不仅仅是在其内部开始或结束的事件。 包括跨间隔的多天活动.

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

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

console.log('Upcoming events:', events);

要列出一天的事件, 请使用当天的界限 :

const startOfDay = new Date();
startOfDay.setHours(0, 0, 0, 0);
const startOfNextDay = new Date(startOfDay);
startOfNextDay.setDate(startOfNextDay.getDate() + 1);

const { result: todaysEvents } = await CapacitorCalendar.listEventsInRange({
  from: startOfDay.getTime(),
  to: startOfNextDay.getTime(),
});

工作日历

// Get all calendars and default calendar
const { result: calendars } = await CapacitorCalendar.listCalendars();
const { result: defaultCalendar } = await CapacitorCalendar.getDefaultCalendar();

// Use default or fall back to first calendar
const targetCalendarId = defaultCalendar?.id ?? calendars[0]?.id;

[注]
在iOS上,您也可以使用 selectCalendarsWithPrompt() 让用户通过本地界面选择日历.

创建提醒( 只有iOS)

const { result } = await CapacitorCalendar.requestFullRemindersAccess();

if (result === 'granted') {
  await CapacitorCalendar.createReminder({
    title: 'Send launch notes',
    dueDate: Date.now() + 2 * 24 * 60 * 60 * 1000,
    notes: 'Created with @ebarooni/capacitor-calendar',
  });
}

文档

完整的文档来自TypeScript定义,可在线查阅:

• 完整文档 指南、实例和完整的API参考(建议)
• 来源定义 — 用于生成文档的 TypeScript 源

更改日志

见 变动情况 用于更新和发布历史.

中断更改

见 震动. md 用于打破变化和移民步骤.

API 密码

• checkPermission(...)
• checkAllPermissions()
• requestPermission(...)
• requestAllPermissions()
• requestWriteOnlyCalendarAccess()
• requestReadOnlyCalendarAccess()
• requestFullCalendarAccess()
• requestFullRemindersAccess()
• createEventWithPrompt(...)
• modifyEventWithPrompt(...)
• createEvent(...)
• modifyEvent(...)
• deleteEventsById(...)
• deleteEvent(...)
• deleteEventWithPrompt(...)
• listEventsInRange(...)
• commit()
• selectCalendarsWithPrompt(...)
• fetchAllCalendarSources()
• listCalendars()
• getDefaultCalendar(...)
• openCalendar(...)
• createCalendar(...)
• deleteCalendar(...)
• modifyCalendar(...)
• createRemindersList(...)
• deleteRemindersList(...)
• fetchAllRemindersSources()
• openReminders()
• getDefaultRemindersList()
• getRemindersLists()
• createReminder(...)
• deleteRemindersById(...)
• deleteReminder(...)
• modifyReminder(...)
• getReminderById(...)
• getRemindersFromLists(...)
• deleteReminderWithPrompt(...)
• updateRemindersList(...)
• 接口
• 类型异名
• 数字

检查许可(...)

checkPermission(options: CheckPermissionOptions) => Promise<{ result: PermissionState; }>

为给定范围获取当前权限状态. 关于Android, readReminders 财务报告和审定财务报表 writeReminders 决 议 "prompt"。 。 。 .

回返情况: Promise<{ result: PermissionState; }>

自: 0.1.0 (中文(简体) )

平台: Android, iOS (英语)

检查所有许可( A)

checkAllPermissions() => Promise<{ result: CheckAllPermissionsResult; }>

获取所有权限的当前状态 . 关于Android,提醒键总是决心 "prompt"。 。 。 .

回返情况: Promise<{ result: CheckAllPermissionsResult; }>

自: 0.1.0 (中文(简体) )

平台: Android, iOS (英语)

请求许可(...)

requestPermission(options: RequestPermissionOptions) => Promise<{ result: PermissionState; }>

请求准许某一范围. 关于Android, readReminders 财务报告和审定财务报表 writeReminders 拒绝 Invalid scope.

回返情况: Promise<{ result: PermissionState; }>

自: 0.1.0 (中文(简体) )

平台: Android, iOS (英语)

请求全部许可( )

requestAllPermissions() => Promise<{ result: RequestAllPermissionsResult; }>

请求允许所有日历和提醒权限 . 在 Android 上, 只请求日历权限; 提醒密钥保留 "prompt"。 。 。 .

回返情况: Promise<{ result: CheckAllPermissionsResult; }>

自: 0.1.0 (中文(简体) )

平台: Android, iOS (英语)

请求仅写 Calendar 访问 ()

requestWriteOnlyCalendarAccess() => Promise<{ result: PermissionState; }>

请求写入日历 .

回返情况: Promise<{ result: PermissionState; }>

自: 5.4.0 (单位:千美元)

平台: Android, iOS (英语)

请求只读 CalendarAccess ()

requestReadOnlyCalendarAccess() => Promise<{ result: PermissionState; }>

请查看日历 .

回返情况: Promise<{ result: PermissionState; }>

自: 5.4.0 (单位:千美元)

平台: 机器人

请求FullCalendar Access ()

requestFullCalendarAccess() => Promise<{ result: PermissionState; }>

请求读取和写入日历.

回返情况: Promise<{ result: PermissionState; }>

自: 5.4.0 (单位:千美元)

平台: Android, iOS (英语)

请求FulllReminders Access( )

requestFullRemindersAccess() => Promise<{ result: PermissionState; }>

请求可读取和写入提醒. 决定: "granted" 或者说 "denied" (从来没有) "prompt") (中文(简体) ). 赠款涵盖两者 readReminders 财务报告和审定财务报表 writeReminders。 。 。 .

回返情况: Promise<{ result: PermissionState; }>

自: 5.4.0 (单位:千美元)

平台: iOS系统

创建 Event With Prompt (...)

createEventWithPrompt(options?: CreateEventWithPromptOptions | undefined) => Promise<CreateEventWithPromptResult>

打开日历 UI 创建事件. 在Android和iOS上,打开系统编辑器. 关于Android, id 总是 null。 。 。 . 在 Web 上显示一个确认对话框,然后构建一个 .ics File 当用户确认. 见MCP docs://web-behavior 详情.

回返情况: Promise<CreateEventWithPromptResult>

自: 0.1.0 (中文(简体) )

平台: Android, iOS, Web (英语)

修改 Event With Prompt (...)

modifyEventWithPrompt(options: ModifyEventWithPromptOptions) => Promise<{ result: EventEditAction | null; }>

打开系统日历界面来修改一个事件. 安卓总是回来 null。 。 。 .

回返情况: Promise<{ result: EventEditAction | null; }>

自: 6.6.0 (简体中文)

平台: Android, iOS (英语)

创建 Event (...)

createEvent(options: CreateEventOptions) => Promise<CreateEventResult>

在日历中创建事件. 在Android和iOS上,插入到系统日历并返回其日历 id。 。 。 . 在网络上,构建一个 .ics File 作为 ics (无日历存储). 见MCP docs://web-behavior。 。 。 .

回返情况: Promise<CreateEventResult>

自: 0.4.0 (中文(简体) )

平台: Android, iOS, Web (英语)

修改 Event (...)

modifyEvent(options: ModifyEventOptions) => Promise<void>

修改一个事件.

自: 6.6.0 (简体中文)

平台: Android, iOS (英语)

删除 EventsById(...)

deleteEventsById(options: DeleteEventsByIdOptions) => Promise<{ result: DeleteEventsByIdResult; }>

删除多个事件.

回返情况: Promise<{ result: DeleteEventsByIdResult; }>

自: 0.11.0 (中文(简体) )

平台: Android, iOS (英语)

删除 Event (...)

deleteEvent(options: DeleteEventOptions) => Promise<void>

删除事件.

自: 7.1.0 (中文(简体) )

平台: Android, iOS (英语)

删除 Event With Prompt (...)

deleteEventWithPrompt(options: DeleteEventWithPromptOptions) => Promise<{ deleted: boolean; }>

打开对话框删除事件.

回返情况: Promise<{ deleted: boolean; }>

自: 7.1.0 (中文(简体) )

平台: Android, iOS (英语)

列表 Events In Range (...)

listEventsInRange(options: ListEventsInRangeOptions) => Promise<ListEventsInRangeResult>

检索重叠日期范围的事件.

时间间隔相交时包含一个事件 [from, to],包括: 跨范围而不开始或结束的多天事件.

回返情况: Promise<ListEventsInRangeResult>

自: 0.10.0 (中文(简体) )

平台: Android, iOS (英语)

实施( )

commit() => Promise<void>

保存待定日历更改 .

自: 7.1.0 (中文(简体) )

平台: iOS系统

选择 Calendars With Prompt (...)

selectCalendarsWithPrompt(options?: SelectCalendarsWithPromptOptions | undefined) => Promise<SelectCalendarsWithPromptResult>

打开一个系统接口来选择一个或多个日历.

预计可进入日历。 打电话 requestFullCalendarAccess() 先说. 没有授权, 选择者可以看起来是空的 .

确认后, result 包含所选用户的日历. 取消时, result 是一空数组.

如果选择者已经出现,则拒绝新呼叫;飞行中 呼叫持续到用户确认或取消.

回返情况: Promise<SelectCalendarsWithPromptResult>

自: 0.2.0 (中文(简体) )

平台: iOS系统

获取 AllCalendar 源代码 ()

fetchAllCalendarSources() => Promise<FetchAllCalendarSourcesResult>

获取日历源列表 .

需要日历访问 。 未经批准, result 通常为 空数组。 这种方法并不仅仅因为缺少许可而拒绝.

回返情况: Promise<FetchAllCalendarSourcesResult>

自: 6.6.0 (简体中文)

平台: iOS系统

列表计数器( )

listCalendars() => Promise<ListCalendarsResult>

获取所有可用的日历列表 .

需要日历读取权限 。 在Android上,通常缺失权限 拒绝。 在 iOS 上, 缺少的授权通常返回空的 result。 。 。 .

回返情况: Promise<ListCalendarsResult>

自: 7.1.0 (中文(简体) )

平台: Android, iOS (英语)

得到DefaultCalendar (...)

getDefaultCalendar(options?: GetDefaultCalendarOptions | undefined) => Promise<{ result: Calendar | null; }>

获取默认日历 .

需要日历读取权限 。 在Android上,通常缺失权限 拒绝。 在iOS上,缺少授权一般产量 result: null。 。 。 .

系统默认是 Android 和 defaultCalendarForNewEvents (原始内容存档于2018-03-31). On iOS. 当两者均不存在时 useFallbackCalendar ,返回第一个可用的日历. 否则方法返回 null 当没有系统默认时.

回返情况: Promise<{ result: Calendar | null; }>

自: 0.3.0 (中文(简体) )

平台: Android, iOS (英语)

打开日历(...)

openCalendar(options?: OpenCalendarOptions | undefined) => Promise<void>

打开日历应用程序.

自: 7.1.0 (中文(简体) )

平台: Android, iOS (英语)

创建 Calendar (...)

createCalendar(options: CreateCalendarOptions) => Promise<CreateCalendarResult>

创建日历.

title 需要时间. color 是可选的,默认为 #007AFF。 。 。 . 关于Android, accountName 财务报告和审定财务报表 ownerAccount 运行时需要.

回返情况: Promise<CreateCalendarResult>

自: 5.2.0 (中文(简体) )

平台: Android, iOS (英语)

删除日历(...)

deleteCalendar(options: DeleteCalendarOptions) => Promise<void>

以 id 删除日历.

自: 5.2.0 (中文(简体) )

平台: Android, iOS (英语)

修改日历(...)

modifyCalendar(options: ModifyCalendarOptions) => Promise<void>

修改带有选项的日历 .

自: 7.2.0 联合国

平台: Android, iOS (英语)

创建 RemindersList (...)

createRemindersList(options: CreateRemindersListOptions) => Promise<CreateRemindersListResult>

创建新的提醒列表.

回返情况: Promise<CreateRemindersListResult>

自: 8.1.0 联合国

平台: iOS系统

删除 Reminders 列表(...)

deleteRemindersList(options: DeleteRemindersListOptions) => Promise<void>

删除提醒列表.

自: 8.2.0 (中文(简体) )

平台: iOS系统

获取 AllReminders 来源( )

fetchAllRemindersSources() => Promise<FetchAllCalendarSourcesResult>

获取日历源列表 .

回返情况: Promise<FetchAllCalendarSourcesResult>

自: 6.6.0 (简体中文)

平台: iOS系统

打开复刻器( )

openReminders() => Promise<void>

打开提醒应用程序.

自: 7.1.0 (中文(简体) )

平台: iOS系统

获取默认Reminders列表 ()

getDefaultRemindersList() => Promise<GetDefaultRemindersListResult>

获取默认提醒列表.

回返情况: Promise<GetDefaultRemindersListResult>

自: 7.1.0 (中文(简体) )

平台: iOS系统

获取Reminders 列表 ()

getRemindersLists() => Promise<GetRemindersListsResult>

获取所有可用的提醒列表.

回返情况: Promise<GetRemindersListsResult>

自: 7.1.0 (中文(简体) )

平台: iOS系统

创建 Reminder (...)

createReminder(options: CreateReminderOptions) => Promise<CreateReminderResult>

创建提醒.

回返情况: Promise<CreateReminderResult>

自: 0.5.0 (单位:千美元)

平台: iOS系统

删除RemindersById(...)

deleteRemindersById(options: DeleteRemindersByIdOptions) => Promise<{ result: DeleteRemindersByIdResult; }>

删除多个提醒.

回返情况: Promise<{ result: DeleteRemindersByIdResult; }>

自: 5.3.0 (中文(简体) )

平台: iOS系统

删除Reminder(...)

deleteReminder(options: DeleteReminderOptions) => Promise<void>

删除提醒.

自: 7.1.0 (中文(简体) )

平台: iOS系统

修改Reminder(...)

modifyReminder(options: ModifyReminderOptions) => Promise<void>

修改一个教诲.

自: 6.7.0 (简体中文)

平台: iOS系统

获取ReminderById(...)

getReminderById(options: GetReminderByIdOptions) => Promise<GetReminderByIdResult>

由ID获取一个提醒.

回返情况: Promise<GetReminderByIdResult>

自: 7.1.0 (中文(简体) )

平台: iOS系统

获取 Reminders fromLists (...)

getRemindersFromLists(options: GetRemindersFromListsOptions) => Promise<GetRemindersFromListsResult>

从多个列表获取提醒 .

回返情况: Promise<GetRemindersFromListsResult>

自: 5.3.0 (中文(简体) )

平台: iOS系统

删除 Reminder With Prompt (...)

deleteReminderWithPrompt(options: DeleteReminderWithPromptOptions) => Promise<DeleteReminderWithPromptResult>

打开对话框删除提醒.

回返情况: Promise<DeleteReminderWithPromptResult>

自: 7.2.0 联合国

平台: iOS系统

更新Reminders列表(...)

updateRemindersList(options: UpdateRemindersListOptions) => Promise<UpdateRemindersListResult>

更新提醒列表.

回返情况: Promise<UpdateRemindersListResult>

自: 8.2.0 (中文(简体) )

平台: iOS系统

接口

检查选项

QQlink Calendar Access# checkPermission} 的选项 .

请求允许选项

QQlink Calendar Access# requestPermission} 的选项 .

创建成功事件

创建带有Prompt 选项的事件

重犯规则

修改“ 快速” 选项

创建活动结果

创建事件选项

事件嘉宾

修改事件选项