AlarmManager
类)让您可以在应用生命周期之外执行基于时间的操作。例如,您可以使用闹钟启动一个长时间运行的操作,例如每天启动一项服务来下载天气预报。
闹钟具有以下特点:
它们允许您在设定的时间或间隔触发 Intent。
您可以将它们与广播接收器结合使用,以调度作业或 WorkRequests 来执行其他操作。
它们在您的应用之外运行,因此您可以使用它们来触发事件或操作,即使您的应用未运行,甚至设备本身处于休眠状态。
它们帮助您最大限度地减少应用对资源的需求。您可以安排操作,而无需依赖计时器或持续运行的服务。
设置非精确闹钟
当应用设置非精确闹钟时,系统会在将来的某个时间点传递闹钟。非精确闹钟在尊重省电限制(如 低电耗模式)的同时,提供了关于闹钟传递时间的某些保证。
开发者可以利用以下 API 保证来定制非精确闹钟的传递时间。
在特定时间之后传递闹钟
如果您的应用调用 set()
、setInexactRepeating()
或 setAndAllowWhileIdle()
,则闹钟绝不会在提供的触发时间之前触发。
在 Android 12 (API level 31) 及更高版本上,系统会在提供的触发时间一小时内调用闹钟,除非有任何省电限制生效,例如 省电模式 或 低电耗模式。
在时间窗口内传递闹钟
如果您的应用调用 setWindow()
,则闹钟绝不会在提供的触发时间之前触发。除非有任何省电限制生效,否则闹钟会在指定的时间窗口内传递,从给定的触发时间开始。
如果您的应用以 Android 12 或更高版本为目标平台,系统可以将时间窗口内的非精确闹钟的调用延迟至少 10 分钟。因此,小于 600000
的 windowLengthMillis
参数值会被裁剪为 600000
。
以大致规律的间隔传递重复闹钟
如果您的应用调用 setInexactRepeating()
,系统会调用多个闹钟:
- 第一个闹钟在指定的时间窗口内触发,从给定的触发时间开始。
- 随后的闹钟通常在指定时间窗口结束后触发。两次连续闹钟调用之间的时间可能有所不同。
设置精确闹钟
系统会在将来的精确时刻调用精确闹钟。
大多数应用可以使用非精确闹钟来调度任务和事件,以完成几个常见用例。如果您的应用的核心功能依赖于精确计时的闹钟(例如闹钟应用或日历应用),那么可以使用精确闹钟。
可能不需要精确闹钟的用例
以下列表显示了可能不需要精确闹钟的常见工作流程:
- 在应用生命周期内调度时间操作
Handler
类包含几种处理计时操作的好方法,例如在您的应用处于活动状态时每 n 秒执行一些工作:postAtTime()
和postDelayed()
。请注意,这些 API 依赖于系统启动时间而不是实时。- 调度后台工作,例如更新应用和上传日志
WorkManager
提供了一种调度时间敏感型周期性工作的方法。您可以提供重复间隔和flexInterval
(至少 15 分钟)来定义工作的精细运行时。- 用户指定在特定时间后应发生的操作(即使系统处于空闲状态)
- 使用非精确闹钟。具体来说,调用
setAndAllowWhileIdle()
。 - 用户指定在特定时间后应发生的操作
- 使用非精确闹钟。具体来说,调用
set()
。 - 用户指定在指定时间窗口内可以发生的操作
- 使用非精确闹钟。具体来说,调用
setWindow()
。请注意,如果您的应用以 Android 12 或更高版本为目标平台,允许的最短窗口长度为 10 分钟。
设置精确闹钟的方法
您的应用可以使用以下方法之一设置精确闹钟。这些方法的顺序是,列表中越靠后的方法服务于时间越关键的任务,但对系统资源的要求也越高。
setExact()
在将来几乎精确的时间触发闹钟,只要没有其他省电措施生效。
使用此方法设置精确闹钟,除非您的应用的工作对用户来说是时间关键的。
setExactAndAllowWhileIdle()
在将来几乎精确的时间触发闹钟,即使省电措施生效。
setAlarmClock()
在将来的精确时间触发闹钟。由于这些闹钟对用户高度可见,系统绝不会调整其传递时间。系统将这些闹钟识别为最关键的闹钟,必要时会退出低功耗模式以传递闹钟。
系统资源消耗
当系统触发您的应用设置的精确闹钟时,设备会消耗大量资源,例如电池续航,特别是在省电模式下。此外,系统无法轻易批量处理这些请求,以更有效地利用资源。
强烈建议您尽可能创建非精确闹钟。要执行更长时间的工作,请从闹钟的 BroadcastReceiver
中使用 WorkManager
或 JobScheduler
进行调度。要在设备处于低电耗模式时执行工作,请使用 setAndAllowWhileIdle()
创建非精确闹钟,并从闹钟启动作业。
声明相应的精确闹钟权限
如果您的应用以 Android 12 或更高版本为目标平台,您必须获得“闹钟和提醒”特殊应用访问权限。为此,请在您应用的清单文件中声明 SCHEDULE_EXACT_ALARM
权限,如以下代码片段所示:
<manifest ...> <uses-permission android:name="android.permission.SCHEDULE_EXACT_ALARM"/> <application ...> ... </application> </manifest>
如果您的应用以 Android 13 (API level 33) 或更高版本为目标平台,您可以选择声明 SCHEDULE_EXACT_ALARM
或 USE_EXACT_ALARM
权限。
<manifest ...> <uses-permission android:name="android.permission.USE_EXACT_ALARM"/> <application ...> ... </application> </manifest>
虽然 SCHEDULE_EXACT_ALARM
和 USE_EXACT_ALARM
权限表示相同的功能,但它们的授予方式不同,并支持不同的用例。仅当您的应用中的面向用户的功能需要精确计时的操作时,您的应用才应使用精确闹钟,并声明 SCHEDULE_EXACT_ALARM
或 USE_EXACT_ALARM
权限。
USE_EXACT_ALARM
- 自动授予
- 用户无法撤销
- 受 即将推出的 Google Play 政策 的约束
- 用例有限
SCHEDULE_EXACT_ALARM
- 由用户授予
- 更广泛的用例
- 应用应确认权限未被撤销
对于以 Android 13 (API level 33) 及更高版本为目标平台的新安装应用,SCHEDULE_EXACT_ALARM
权限不会预先授予。如果用户通过备份和恢复操作将应用数据传输到运行 Android 14 的设备,则在新设备上将拒绝 SCHEDULE_EXACT_ALARM
权限。但是,如果现有应用已经拥有此权限,则在设备升级到 Android 14 时会预先授予此权限。
注意:如果使用 OnAlarmListener
对象设置精确闹钟,例如使用 setExact
API,则不需要 SCHEDULE_EXACT_ALARM
权限。
使用 SCHEDULE_EXACT_ALARM
权限
与 USE_EXACT_ALARM
不同,SCHEDULE_EXACT_ALARM
权限必须由用户授予。用户和系统都可以撤销 SCHEDULE_EXACT_ALARM
权限。
要检查您的应用是否已获得权限,请在尝试设置精确闹钟之前调用 canScheduleExactAlarms()
。当您的应用的 SCHEDULE_EXACT_ALARM
权限被撤销时,您的应用将停止,并且所有未来的精确闹钟都将被取消。这也意味着 canScheduleExactAlarms()
返回的值在您应用的整个生命周期内都保持有效。
当您的应用获得 SCHEDULE_EXACT_ALARMS
权限时,系统会向其发送 ACTION_SCHEDULE_EXACT_ALARM_PERMISSION_STATE_CHANGED
广播。您的应用应实现一个广播接收器,执行以下操作:
- 确认您的应用仍然具有特殊应用访问权限。为此,请调用
canScheduleExactAlarms()
。此检查可保护您的应用,以防用户授予应用权限后,又几乎立即撤销权限的情况。 - 根据其当前状态,重新调度您的应用所需的任何精确闹钟。此逻辑应类似于您的应用收到
ACTION_BOOT_COMPLETED
广播时所做的操作。
请求用户授予 SCHEDULE_EXACT_ALARM
权限
如有必要,您可以将用户引导至系统设置中的闹钟和提醒屏幕,如图 1 所示。为此,请完成以下步骤:
- 在您应用的界面中,向用户解释您的应用为何需要调度精确闹钟。
- 调用包含
ACTION_REQUEST_SCHEDULE_EXACT_ALARM
intent 操作的 intent。
设置重复闹钟
重复闹钟允许系统按照重复的日程通知您的应用。
设计不佳的闹钟会导致电池耗尽并给服务器带来显著负载。因此,在 Android 4.4 (API level 19) 及更高版本上,所有重复闹钟都是非精确闹钟。
重复闹钟具有以下特点:
闹钟类型。有关更多讨论,请参阅选择闹钟类型。
触发时间。如果您指定的触发时间已过,闹钟会立即触发。
闹钟的间隔。例如,每天一次、每小时一次或每 5 分钟一次。
闹钟触发时触发的 PendingIntent。当您设置使用相同 PendingIntent 的第二个闹钟时,它会替换原始闹钟。
要取消 PendingIntent()
,请将 FLAG_NO_CREATE
传递给 PendingIntent.getService()
以获取 Intent 实例(如果存在),然后将该 Intent 传递给 AlarmManager.cancel()
Kotlin
val alarmManager = context.getSystemService(Context.ALARM_SERVICE) as? AlarmManager val pendingIntent = PendingIntent.getService(context, requestId, intent, PendingIntent.FLAG_NO_CREATE) if (pendingIntent != null && alarmManager != null) { alarmManager.cancel(pendingIntent) }
Java
AlarmManager alarmManager = (AlarmManager) context.getSystemService(Context.ALARM_SERVICE); PendingIntent pendingIntent = PendingIntent.getService(context, requestId, intent, PendingIntent.FLAG_NO_CREATE); if (pendingIntent != null && alarmManager != null) { alarmManager.cancel(pendingIntent); }
选择闹钟类型
使用重复闹钟时,首要考虑因素之一是其类型。
闹钟有两种通用时钟类型:“已逝去实时”和“实时时钟”(RTC)。已逝去实时使用“系统启动以来的时间”作为参考,而实时时钟使用 UTC(挂钟)时间。这意味着已逝去实时适合根据时间流逝设置闹钟(例如,每 30 秒触发一次的闹钟),因为它不受时区或区域设置的影响。实时时钟类型更适合依赖当前区域设置的闹钟。
两种类型都有一个“唤醒”版本,表示如果屏幕关闭,则唤醒设备的 CPU。这可确保闹钟在预定时间触发。如果您的应用具有时间依赖性,这会很有用。例如,如果它有执行特定操作的有限窗口。如果您不使用闹钟类型的唤醒版本,那么所有重复闹钟将在您的设备下一次唤醒时触发。
如果您只需要闹钟以特定间隔触发(例如,每半小时),请使用其中一种已逝去实时类型。通常,这是更好的选择。
如果您需要闹钟在一天中的特定时间触发,则选择基于时钟的实时时钟类型之一。但请注意,这种方法可能有一些缺点。应用可能无法很好地转换为其他区域设置,并且如果用户更改设备的时间设置,可能会导致应用中出现意外行为。使用实时时钟闹钟类型也无法很好地扩展,如上所述。我们建议您尽可能使用“已逝去实时”闹钟。
以下是类型列表:
ELAPSED_REALTIME
:根据设备启动以来的时间量触发 PendingIntent,但不唤醒设备。已逝去时间包括设备休眠的任何时间。ELAPSED_REALTIME_WAKEUP
:唤醒设备并在设备启动后经过指定时间长度后触发 PendingIntent。RTC
:在指定时间触发 PendingIntent,但不唤醒设备。RTC_WAKEUP
:唤醒设备以在指定时间触发 PendingIntent。
已逝去实时闹钟示例
以下是使用 ELAPSED_REALTIME_WAKEUP
的一些示例:
唤醒设备以在 30 分钟内触发闹钟,之后每隔 30 分钟触发一次
Kotlin
// Hopefully your alarm will have a lower frequency than this! alarmMgr?.setInexactRepeating( AlarmManager.ELAPSED_REALTIME_WAKEUP, SystemClock.elapsedRealtime() + AlarmManager.INTERVAL_HALF_HOUR, AlarmManager.INTERVAL_HALF_HOUR, alarmIntent )
Java
// Hopefully your alarm will have a lower frequency than this! alarmMgr.setInexactRepeating(AlarmManager.ELAPSED_REALTIME_WAKEUP, SystemClock.elapsedRealtime() + AlarmManager.INTERVAL_HALF_HOUR, AlarmManager.INTERVAL_HALF_HOUR, alarmIntent);
唤醒设备以在一分钟内触发一次性(非重复)闹钟
Kotlin
private var alarmMgr: AlarmManager? = null private lateinit var alarmIntent: PendingIntent ... alarmMgr = context.getSystemService(Context.ALARM_SERVICE) as AlarmManager alarmIntent = Intent(context, AlarmReceiver::class.java).let { intent -> PendingIntent.getBroadcast(context, 0, intent, 0) } alarmMgr?.set( AlarmManager.ELAPSED_REALTIME_WAKEUP, SystemClock.elapsedRealtime() + 60 * 1000, alarmIntent )
Java
private AlarmManager alarmMgr; private PendingIntent alarmIntent; ... alarmMgr = (AlarmManager)context.getSystemService(Context.ALARM_SERVICE); Intent intent = new Intent(context, AlarmReceiver.class); alarmIntent = PendingIntent.getBroadcast(context, 0, intent, 0); alarmMgr.set(AlarmManager.ELAPSED_REALTIME_WAKEUP, SystemClock.elapsedRealtime() + 60 * 1000, alarmIntent);
实时时钟闹钟示例
以下是使用 RTC_WAKEUP
的一些示例。
唤醒设备以在下午 2:00 左右触发闹钟,并每天在同一时间重复一次
Kotlin
// Set the alarm to start at approximately 2:00 p.m. val calendar: Calendar = Calendar.getInstance().apply { timeInMillis = System.currentTimeMillis() set(Calendar.HOUR_OF_DAY, 14) } // With setInexactRepeating(), you have to use one of the AlarmManager interval // constants--in this case, AlarmManager.INTERVAL_DAY. alarmMgr?.setInexactRepeating( AlarmManager.RTC_WAKEUP, calendar.timeInMillis, AlarmManager.INTERVAL_DAY, alarmIntent )
Java
// Set the alarm to start at approximately 2:00 p.m. Calendar calendar = Calendar.getInstance(); calendar.setTimeInMillis(System.currentTimeMillis()); calendar.set(Calendar.HOUR_OF_DAY, 14); // With setInexactRepeating(), you have to use one of the AlarmManager interval // constants--in this case, AlarmManager.INTERVAL_DAY. alarmMgr.setInexactRepeating(AlarmManager.RTC_WAKEUP, calendar.getTimeInMillis(), AlarmManager.INTERVAL_DAY, alarmIntent);
唤醒设备以在上午 8:30 精确触发闹钟,此后每 20 分钟触发一次
Kotlin
private var alarmMgr: AlarmManager? = null private lateinit var alarmIntent: PendingIntent ... alarmMgr = context.getSystemService(Context.ALARM_SERVICE) as AlarmManager alarmIntent = Intent(context, AlarmReceiver::class.java).let { intent -> PendingIntent.getBroadcast(context, 0, intent, 0) } // Set the alarm to start at 8:30 a.m. val calendar: Calendar = Calendar.getInstance().apply { timeInMillis = System.currentTimeMillis() set(Calendar.HOUR_OF_DAY, 8) set(Calendar.MINUTE, 30) } // setRepeating() lets you specify a precise custom interval--in this case, // 20 minutes. alarmMgr?.setRepeating( AlarmManager.RTC_WAKEUP, calendar.timeInMillis, 1000 * 60 * 20, alarmIntent )
Java
private AlarmManager alarmMgr; private PendingIntent alarmIntent; ... alarmMgr = (AlarmManager)context.getSystemService(Context.ALARM_SERVICE); Intent intent = new Intent(context, AlarmReceiver.class); alarmIntent = PendingIntent.getBroadcast(context, 0, intent, 0); // Set the alarm to start at 8:30 a.m. Calendar calendar = Calendar.getInstance(); calendar.setTimeInMillis(System.currentTimeMillis()); calendar.set(Calendar.HOUR_OF_DAY, 8); calendar.set(Calendar.MINUTE, 30); // setRepeating() lets you specify a precise custom interval--in this case, // 20 minutes. alarmMgr.setRepeating(AlarmManager.RTC_WAKEUP, calendar.getTimeInMillis(), 1000 * 60 * 20, alarmIntent);
确定闹钟需要多精确
如前所述,选择闹钟类型通常是创建闹钟的第一步。另一个区别是闹钟需要多精确。对于大多数应用,setInexactRepeating()
是正确的选择。当您使用此方法时,Android 会同步多个非精确重复闹钟并同时触发它们。这减少了电池消耗。
尽可能避免使用精确闹钟。但是,对于少数具有严格时间要求的应用,您可以通过调用 setRepeating()
来设置精确闹钟。
使用 setInexactRepeating()
时,您无法像使用 setRepeating()
那样指定自定义间隔。您必须使用其中一个间隔常量,例如 INTERVAL_FIFTEEN_MINUTES
、INTERVAL_DAY
等。有关完整列表,请参阅 AlarmManager
。
取消闹钟
根据您的应用,您可能希望包含取消闹钟的功能。要取消闹钟,请在 Alarm Manager 上调用 cancel()
,并传入您不再希望触发的 PendingIntent
。例如:
Kotlin
// If the alarm has been set, cancel it. alarmMgr?.cancel(alarmIntent)
Java
// If the alarm has been set, cancel it. if (alarmMgr!= null) { alarmMgr.cancel(alarmIntent); }
设备重启时启动闹钟
默认情况下,当设备关机时,所有闹钟都会被取消。为了防止这种情况发生,您可以设计您的应用在用户重启设备时自动重新启动重复闹钟。这可确保 AlarmManager
将继续执行其任务,而无需用户手动重新启动闹钟。
以下是步骤:
在您应用的清单中设置
RECEIVE_BOOT_COMPLETED
权限。这允许您的应用接收系统启动完成后广播的ACTION_BOOT_COMPLETED
(这仅在应用已被用户至少启动一次后才有效)<uses-permission android:name="android.permission.RECEIVE_BOOT_COMPLETED"/>
实现
BroadcastReceiver
以接收广播Kotlin
class SampleBootReceiver : BroadcastReceiver() { override fun onReceive(context: Context, intent: Intent) { if (intent.action == "android.intent.action.BOOT_COMPLETED") { // Set the alarm here. } } }
Java
public class SampleBootReceiver extends BroadcastReceiver { @Override public void onReceive(Context context, Intent intent) { if (intent.getAction().equals("android.intent.action.BOOT_COMPLETED")) { // Set the alarm here. } } }
使用一个 intent 过滤器将接收器添加到您应用的清单文件中,该过滤器针对
ACTION_BOOT_COMPLETED
操作进行过滤<receiver android:name=".SampleBootReceiver" android:enabled="false"> <intent-filter> <action android:name="android.intent.action.BOOT_COMPLETED"></action> </intent-filter> </receiver>
请注意,在清单中,启动接收器设置为
android:enabled="false"
。这意味着除非应用程序明确启用它,否则不会调用接收器。这可以防止不必要地调用启动接收器。您可以按如下方式启用接收器(例如,如果用户设置了闹钟):Kotlin
val receiver = ComponentName(context, SampleBootReceiver::class.java) context.packageManager.setComponentEnabledSetting( receiver, PackageManager.COMPONENT_ENABLED_STATE_ENABLED, PackageManager.DONT_KILL_APP )
Java
ComponentName receiver = new ComponentName(context, SampleBootReceiver.class); PackageManager pm = context.getPackageManager(); pm.setComponentEnabledSetting(receiver, PackageManager.COMPONENT_ENABLED_STATE_ENABLED, PackageManager.DONT_KILL_APP);
一旦您以这种方式启用接收器,它将保持启用状态,即使用户重启设备也是如此。换句话说,以编程方式启用接收器会覆盖清单设置,即使在重启后也是如此。接收器将保持启用状态,直到您的应用将其禁用。您可以按如下方式禁用接收器(例如,如果用户取消了闹钟):
Kotlin
val receiver = ComponentName(context, SampleBootReceiver::class.java) context.packageManager.setComponentEnabledSetting( receiver, PackageManager.COMPONENT_ENABLED_STATE_DISABLED, PackageManager.DONT_KILL_APP )
Java
ComponentName receiver = new ComponentName(context, SampleBootReceiver.class); PackageManager pm = context.getPackageManager(); pm.setComponentEnabledSetting(receiver, PackageManager.COMPONENT_ENABLED_STATE_DISABLED, PackageManager.DONT_KILL_APP);
在设备处于低电耗模式时调用闹钟
运行 Android 6.0 (API level 23) 的设备支持低电耗模式,这有助于延长设备电池续航。当设备处于低电耗模式时,闹钟不会触发。任何预定的闹钟都将延迟到设备退出低电耗模式。如果您需要在设备空闲时完成工作,有几种可用选项:
设置精确闹钟。
使用 WorkManager API,它旨在执行后台工作。您可以指示系统加快您的工作,以便工作尽快完成。有关更多信息,请参阅使用 WorkManager 调度任务
最佳实践
您在设计重复闹钟时做出的每个选择都可能对您的应用如何使用(或滥用)系统资源产生影响。例如,假设有一个流行的应用与服务器同步。如果同步操作基于时钟时间,并且每个应用实例都在晚上 11:00 同步,则服务器上的负载可能导致高延迟甚至“拒绝服务”。在使用闹钟时遵循以下最佳实践:
对因重复闹钟触发的任何网络请求添加随机性(抖动)
当闹钟触发时,执行任何本地工作。“本地工作”是指任何不访问服务器或不需要服务器数据的工作。
同时,安排包含网络请求的闹钟在随机时间段触发。
将闹钟频率保持在最低限度。
不要不必要地唤醒设备(此行为由闹钟类型决定,如选择闹钟类型中所述)。
不要让闹钟的触发时间比实际需要更精确。
使用
setInexactRepeating()
而不是setRepeating()
。当您使用setInexactRepeating()
时,Android 会同步来自多个应用的重复闹钟并同时触发它们。这减少了系统唤醒设备的总次数,从而减少了电池消耗。截至 Android 4.4 (API Level 19),所有重复闹钟都是非精确闹钟。请注意,虽然setInexactRepeating()
是对setRepeating()
的改进,但如果每个应用实例都在同一时间访问服务器,它仍然可能使服务器超负荷。因此,对于网络请求,请在您的闹钟中添加一些随机性,如前所述。尽可能避免将闹钟基于时钟时间。
基于精确触发时间的重复闹钟无法很好地扩展。如果可以,请使用
ELAPSED_REALTIME
。不同闹钟类型在下一节中有更详细的描述。