AlarmManager
类)为您提供了一种在应用生命周期之外基于时间的操作。例如,您可以使用闹钟来启动长时间运行的操作,例如每天启动一次服务以下载天气预报。
闹钟具有以下特征:
它们可让您按设定的时间和/或间隔触发 intent。
您可以将它们与广播接收器结合使用,以调度作业或 WorkRequest 以执行其他操作。
它们在应用外部运行,因此即使应用未运行,甚至设备本身处于休眠状态,您也可以使用它们来触发事件或操作。
它们可帮助您最大限度地降低应用的资源需求。您可以调度操作,而无需依赖计时器或持续运行的服务。
设置不精确闹钟
当应用设置不精确闹钟时,系统会在未来的某个时间点发出闹钟。不精确闹钟可提供有关闹钟触发时间的一些保证,同时遵循低电耗模式等省电限制。
开发者可以利用以下 API 保证来自定义不精确闹钟传送的时间。
在特定时间后发出闹钟
如果您的应用调用 set()
、setInexactRepeating()
或 setAndAllowWhileIdle()
,则闹钟绝不会在提供的触发时间之前触发。
在 Android 12(API 级别 31)及更高版本中,系统会在提供的触发时间后的 1 小时内调用闹钟,除非存在任何省电限制(例如省电模式或低电耗模式)。
在某个时间范围内发出警报
如果您的应用调用 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 级别 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 级别 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 级别 19)及更高版本中,所有重复闹钟都是不精确闹钟。
重复闹钟具有以下特征:
闹钟类型。要了解详情,请参阅选择闹钟类型。
触发时间。如果您指定的触发时间是过去的时间,则闹钟会立即触发。
闹钟的间隔。例如,每天一次、每小时一次或每 5 分钟一次。
闹钟触发的待定 Intent。当您设置使用同一待处理 intent 的第二个闹钟时,它会替换原始闹钟。
如需取消 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
:根据自设备启动以来的时间触发待定 intent,但不会唤醒设备。经过的时间包括设备处于休眠状态期间的任何时间。ELAPSED_REALTIME_WAKEUP
:唤醒设备,并在自设备启动以来经过指定的时间过去后触发待定 intent。RTC
:在指定的时间触发待定 intent,但不会唤醒设备。RTC_WAKEUP
:唤醒设备以在指定的时间触发待定 intent。
“经过的时间”闹钟示例
以下是使用 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
。
取消闹钟
您可能需要包含取消闹钟的功能,具体取决于您的应用。
如需取消闹钟,请在闹钟管理器上调用 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. } } }
使用可过滤
ACTION_BOOT_COMPLETED
操作的 intent 过滤器将该接收器添加到应用的清单文件中:<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 级别 23)的设备支持低电耗模式,这有助于延长设备电池续航时间。当设备处于低电耗模式时,闹钟不会触发。任何已设置的闹钟都会被推迟,直到设备退出低电耗模式为止。如果您需要在设备处于空闲状态时也完成工作,有以下几个选项可供选择:
设置精确闹钟。
使用专为执行后台工作而构建的 WorkManager API。您可以指示系统应加速您的工作,以便工作尽快完成。如需了解详情,请参阅使用 WorkManager 调度任务
最佳实践
您在设计重复闹钟时所做的每一个选择都会影响应用使用(或滥用)系统资源的方式。例如,假设有一个热门应用会与服务器同步。如果同步操作基于时钟时间,并且应用的每个实例都在晚上 11:00 进行同步,则服务器上的负载可能会导致高延迟甚至“拒绝服务”攻击。请遵循以下使用闹钟的最佳做法:
为重复闹钟触发的网络请求添加随机性(抖动):
在闹钟触发时执行本地的任何操作。“本地工作”是指无需连接服务器或不需要服务器数据的任何工作。
同时,将包含网络请求的闹钟安排在某个随机时间段触发。
尽可能降低闹钟的触发频率。
请勿在不必要的情况下唤醒设备(此行为由闹钟类型决定,如选择闹钟类型中所述)。
请勿将闹钟的触发时间设置得过于精确。
使用
setInexactRepeating()
代替setRepeating()
。当您使用setInexactRepeating()
时,Android 会同步多个应用的重复闹钟,并同时触发这些闹钟。这可以减少系统必须唤醒设备的总次数,从而减少耗电量。从 Android 4.4(API 级别 19)开始,所有重复闹钟都是不精确闹钟。请注意,虽然setInexactRepeating()
是对setRepeating()
的改进,但如果应用的每个实例都差不多都同时连接到服务器,仍可能会导致服务器超负荷运行。因此,如前所述,对于网络请求,请为您的闹钟添加一些随机性。尽量避免基于时钟时间设置闹钟。
基于精确触发时间的重复闹钟无法很好地扩展。如果可以,请使用
ELAPSED_REALTIME
。下一部分更详细地介绍了不同的闹钟类型。