指南
如何在 Capacitor 中使用 Alarm
使用 @capgo/capacitor-alarm
Capacitor Alarm 插件，用于管理原生系统的闹钟。
安装
bun add @capgo/capacitor-alarm
bunx cap sync
bunx cap sync 将插件的原生 code 复制到你的原生项目中。每次升级插件后都要重新运行。
导入
import { CapgoAlarm } from '@capgo/capacitor-alarm';
API 概览
| 方法 | 描述 |
|---|---|
createAlarm |
使用系统时钟应用创建原生系统闹钟。Android 上使用 Alarm Clock intent；iOS 上如果可用（iOS 16+）则使用 AlarmKit。 |
openAlarms |
如果可用，打开平台的原生闹钟列表 UI。 |
getOSInfo |
获取 OS 及能力信息。 |
requestPermissions |
请求平台上闹钟使用的相关权限。Android 上可能会跳转到设置以配置精确闹钟。 |
checkPermissions |
检查原生闹钟访问权限的当前状态，不会触发 UI。iOS 上返回 AlarmKit 就绪状态；Android 上返回能力详情。 |
getAlarms |
获取本应用已调度的闹钟列表。iOS 26+ 上返回 AlarmKit 中的闹钟。Android 不支持，因为系统不提供用于查询闹钟的 API。 |
cancelAlarm |
按 ID 取消已调度的闹钟。iOS 26+ 上会从 AlarmKit 中移除该闹钟。Android/web 上返回不支持。 |
示例
createAlarm()
使用系统时钟应用创建原生系统闹钟。Android 上使用 Alarm Clock intent；iOS 上如果可用（iOS 16+）则使用 AlarmKit。
import { CapgoAlarm } from '@capgo/capacitor-alarm';
const result = await CapgoAlarm.createAlarm({
hour: 7,
minute: 30,
label: 'Wake up',
skipUi: false,
vibrate: true
});
console.log('Alarm created:', result.success);
openAlarms()
如果可用，打开平台的原生闹钟列表 UI。
import { CapgoAlarm } from '@capgo/capacitor-alarm';
const result = await CapgoAlarm.openAlarms();
if (result.success) {
console.log('Alarms UI opened');
}
getOSInfo()
获取 OS 及能力信息。
import { CapgoAlarm } from '@capgo/capacitor-alarm';
const info = await CapgoAlarm.getOSInfo();
console.log('Platform:', info.platform);
console.log('Supports native alarms:', info.supportsNativeAlarms);
if (info.platform === 'android') {
console.log('Can schedule exact alarms:', info.canScheduleExactAlarms);
}
requestPermissions()
请求平台上闹钟使用的相关权限。Android 上可能会跳转到设置以配置精确闹钟。
import { CapgoAlarm } from '@capgo/capacitor-alarm';
const result = await CapgoAlarm.requestPermissions({ exactAlarm: true });
if (result.granted) {
console.log('Permissions granted');
} else {
console.log('Permissions denied');
}
checkPermissions()
检查原生闹钟访问权限的当前状态，不会触发 UI。iOS 上返回 AlarmKit 就绪状态；Android 上返回能力详情。
import { CapgoAlarm } from '@capgo/capacitor-alarm';
const status = await CapgoAlarm.checkPermissions();
console.log('AlarmKit allowed?', status.details?.alarmKit);
getAlarms()
获取本应用已调度的闹钟列表。iOS 26+ 上返回 AlarmKit 中的闹钟。Android 不支持，因为系统不提供用于查询闹钟的 API。
import { CapgoAlarm } from '@capgo/capacitor-alarm';
const { alarms } = await CapgoAlarm.getAlarms();
console.log('Scheduled alarms:', alarms);
alarms.forEach(alarm => {
console.log(`Alarm ${alarm.id}: ${alarm.hour}:${alarm.minute} - ${alarm.label}`);
});
上表列出了 7 个核心方法。有关 Listener、版本辅助函数以及每个方法的完整契约，请参阅 GitHub 仓库.
完整参考文档
继续阅读：使用 @capgo/capacitor-alarm
如果你正在使用 使用 @capgo/capacitor-alarm 要规划原生插件工作，请将其与 @capgo/capacitor-alarm 了解 @capgo/capacitor-alarm 中的实现细节， 快速入门 有关“入门指南”中的实现细节， Capgo 插件目录 查看 Capgo 插件目录中的产品工作流， Capgo 提供的 Capacitor 插件 有关 Capgo 开发的 Capacitor 插件的实现细节，以及 添加或更新插件 有关添加或更新插件的实现细节。