@capacitor/local-notifications
Local Notifications API 提供了一种在本地调度设备通知的方法(即无需服务器发送推送通知)。
安装
npm install @capacitor/local-notifications
npx cap sync
Android
Android 13 需要进行权限检查才能发送通知。您需要相应地调用 checkPermissions()
和 requestPermissions()
。
在 Android 12 及更早版本上,它不会显示提示,只会返回已授权状态。
从 Android 12 开始,除非在 AndroidManifest.xml
中添加以下权限,否则计划通知将不精确:
<uses-permission android:name="android.permission.SCHEDULE_EXACT_ALARM" />
请注意,即使存在该权限,用户仍可以从应用设置中禁用精确通知。使用 checkExactNotificationSetting()
检查该设置的值。如果用户禁用此设置,应用将重新启动,并且任何使用精确闹钟调度的通知都将被删除。如果您的应用依赖精确闹钟,请务必在应用启动时检查此设置(例如,在 App.appStateChange
中),以便提供备选方案或替代行为。
在 Android 14 中,有一个名为 USE_EXACT_ALARM
的新权限。使用此权限可以在无需向用户请求权限的情况下使用精确闹钟。这仅应在精确闹钟的使用对应用功能至关重要时使用。有关使用此权限的影响的更多信息,请参阅此处。
从 Android 15 开始,用户可以在私人空间中安装应用。用户可以随时锁定其私人空间,这意味着推送通知在用户解锁之前不会显示。
无法检测应用是否安装在私人空间中。因此,如果您的应用 显示任何关键通知,请告知用户避免将应用安装在私人空间中。
有关与私人空间相关的应用行为更改的更多信息,请参阅 Android 文档。
配置
在 Android 上,可以使用以下选项配置 Local Notifications:
属性 | 类型 | 描述 | 始于 |
---|---|---|---|
smallIcon | string | 设置通知的默认状态栏图标。图标应放置在应用的 res/drawable 文件夹中。此选项的值应为可绘制资源 ID,即不带扩展名的文件名。仅适用于 Android。 | 1.0.0 |
iconColor | string | 设置通知状态栏图标的默认颜色。仅适用于 Android。 | 1.0.0 |
sound | string | 设置通知的默认通知声音。在 Android 26+ 上,它设置默认通道声音且无法更改,除非卸载应用。如果找不到音频文件,Android 21-25 将播放默认系统声音,Android 26+ 则无声音。仅适用于 Android。 | 1.0.0 |
示例
在 capacitor.config.json
中:
{
"plugins": {
"LocalNotifications": {
"smallIcon": "ic_stat_icon_config_sample",
"iconColor": "#488AFF",
"sound": "beep.wav"
}
}
}
在 capacitor.config.ts
中:
/// <reference types="@capacitor/local-notifications" />
import { CapacitorConfig } from '@capacitor/cli';
const config: CapacitorConfig = {
plugins: {
LocalNotifications: {
smallIcon: 'ic_stat_icon_config_sample',
iconColor: '#488AFF',
sound: 'beep.wav',
},
},
};
export default config;
Doze 模式
如果设备已进入 Doze 模式,您的应用可能会受到功能限制。如果您需要在 Doze 模式下也能触发通知,请使用 allowWhileIdle: true
来调度通知。请谨慎使用 allowWhileIdle
,因为这些通知每个应用每 9 分钟只能触发一次。
API
schedule(...)
getPending()
registerActionTypes(...)
cancel(...)
areEnabled()
getDeliveredNotifications()
removeDeliveredNotifications(...)
removeAllDeliveredNotifications()
createChannel(...)
deleteChannel(...)
listChannels()
checkPermissions()
requestPermissions()
changeExactNotificationSetting()
checkExactNotificationSetting()
addListener('localNotificationReceived', ...)
addListener('localNotificationActionPerformed', ...)
removeAllListeners()
- 接口
- 类型别名
- 枚举
schedule(...)
schedule(options: ScheduleOptions) => Promise<ScheduleResult>
调度一个或多个本地通知。
参数 | 类型 |
---|---|
options |
|
返回值:
Promise<ScheduleResult>
始于: 1.0.0
getPending()
getPending() => Promise<PendingResult>
获取待处理通知列表。
返回值:
Promise<PendingResult>
始于: 1.0.0
registerActionTypes(...)
registerActionTypes(options: RegisterActionTypesOptions) => Promise<void>
注册在通知显示时要执行的操作。
仅适用于 iOS 和 Android。
参数 | 类型 |
---|---|
options |
|
始于: 1.0.0
cancel(...)
cancel(options: CancelOptions) => Promise<void>
取消待处理的通知。
参数 | 类型 |
---|---|
options |
|
始于: 1.0.0
areEnabled()
areEnabled() => Promise<EnabledResult>
检查通知是否已启用。
返回值:
Promise<EnabledResult>
始于: 1.0.0
getDeliveredNotifications()
getDeliveredNotifications() => Promise<DeliveredNotifications>
获取通知屏幕上可见的通知列表。
返回值:
Promise<DeliveredNotifications>
始于: 4.0.0
removeDeliveredNotifications(...)
removeDeliveredNotifications(delivered: DeliveredNotifications) => Promise<void>
从通知屏幕中移除指定的通知。
参数 | 类型 |
---|---|
delivered |
|
始于: 4.0.0
removeAllDeliveredNotifications()
removeAllDeliveredNotifications() => Promise<void>
从通知屏幕中移除所有通知。
始于: 4.0.0
createChannel(...)
createChannel(channel: Channel) => Promise<void>
创建通知通道。
仅适用于 Android。
参数 | 类型 |
---|---|
channel |
|
始于: 1.0.0
deleteChannel(...)
deleteChannel(args: { id: string; }) => Promise<void>
删除通知通道。
仅适用于 Android。
参数 | 类型 |
---|---|
args | { id: string; } |
始于: 1.0.0
listChannels()
listChannels() => Promise<ListChannelsResult>
获取通知通道列表。
仅适用于 Android。
返回值:
Promise<ListChannelsResult>
始于: 1.0.0
checkPermissions()
checkPermissions() => Promise<PermissionStatus>
检查显示本地通知的权限。
返回值:
Promise<PermissionStatus>
始于: 1.0.0
requestPermissions()
requestPermissions() => Promise<PermissionStatus>
请求显示本地通知的权限。
返回值:
Promise<PermissionStatus>
始于: 1.0.0
changeExactNotificationSetting()
changeExactNotificationSetting() => Promise<SettingsPermissionStatus>
引导用户进入应用设置屏幕以配置精确闹钟。
如果用户将设置从授予更改为拒绝,应用将重新启动,并且任何使用精确闹钟调度的通知都将被删除。
在 Android < 12 上,用户不会被引导至应用设置屏幕,而是此函数将返回 granted
。
仅适用于 Android。
返回值:
Promise<SettingsPermissionStatus>
始于: 6.0.0
checkExactNotificationSetting()
checkExactNotificationSetting() => Promise<SettingsPermissionStatus>
检查使用精确闹钟的应用设置。
仅适用于 Android。
返回值:
Promise<SettingsPermissionStatus>
始于: 6.0.0
addListener('localNotificationReceived', ...)
addListener(eventName: 'localNotificationReceived', listenerFunc: (notification: LocalNotificationSchema) => void) => Promise<PluginListenerHandle>
监听通知显示事件。
参数 | 类型 |
---|---|
eventName | 'localNotificationReceived' |
listenerFunc |
|
返回值:
Promise<PluginListenerHandle>
始于: 1.0.0
addListener('localNotificationActionPerformed', ...)
addListener(eventName: 'localNotificationActionPerformed', listenerFunc: (notificationAction: ActionPerformed) => void) => Promise<PluginListenerHandle>
监听在通知上执行操作的事件。
参数 | 类型 |
---|---|
eventName | 'localNotificationActionPerformed' |
listenerFunc |
|
返回值:
Promise<PluginListenerHandle>
始于: 1.0.0
removeAllListeners()
removeAllListeners() => Promise<void>
移除此插件的所有监听器。
始于: 1.0.0