跳到主要内容
版本:v7

@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:

属性类型描述始于
smallIconstring设置通知的默认状态栏图标。图标应放置在应用的 res/drawable 文件夹中。此选项的值应为可绘制资源 ID,即不带扩展名的文件名。仅适用于 Android。1.0.0
iconColorstring设置通知状态栏图标的默认颜色。仅适用于 Android。1.0.0
soundstring设置通知的默认通知声音。在 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(...)

schedule(options: ScheduleOptions) => Promise<ScheduleResult>

调度一个或多个本地通知。

参数类型
options
ScheduleOptions

返回值:

Promise<ScheduleResult>

始于: 1.0.0


getPending()

getPending() => Promise<PendingResult>

获取待处理通知列表。

返回值:

Promise<PendingResult>

始于: 1.0.0


registerActionTypes(...)

registerActionTypes(options: RegisterActionTypesOptions) => Promise<void>

注册在通知显示时要执行的操作。

仅适用于 iOS 和 Android。

参数类型
options
RegisterActionTypesOptions

始于: 1.0.0


cancel(...)

cancel(options: CancelOptions) => Promise<void>

取消待处理的通知。

参数类型
options
CancelOptions

始于: 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
DeliveredNotifications

始于: 4.0.0


removeAllDeliveredNotifications()

removeAllDeliveredNotifications() => Promise<void>

从通知屏幕中移除所有通知。

始于: 4.0.0


createChannel(...)

createChannel(channel: Channel) => Promise<void>

创建通知通道。

仅适用于 Android。

参数类型
channel
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
(notification: LocalNotificationSchema) => void

返回值:

Promise<PluginListenerHandle>

始于: 1.0.0


addListener('localNotificationActionPerformed', ...)

addListener(eventName: 'localNotificationActionPerformed', listenerFunc: (notificationAction: ActionPerformed) => void) => Promise<PluginListenerHandle>

监听在通知上执行操作的事件。

参数类型
eventName'localNotificationActionPerformed'
listenerFunc
(notificationAction: ActionPerformed) => void

返回值:

Promise<PluginListenerHandle>

始于: 1.0.0


removeAllListeners()

removeAllListeners() => Promise<void>

移除此插件的所有监听器。

始于: 1.0.0


Interfaces

ScheduleResult

属性类型描述始于
notificationsLocalNotificationDescriptor[]已调度的通知列表。1.0.0

LocalNotificationDescriptor

描述本地通知的对象。

属性类型描述始于
idnumber通知标识符。1.0.0

ScheduleOptions

属性类型描述始于
notificationsLocalNotificationSchema[]要调度的通知列表。1.0.0

LocalNotificationSchema

属性类型描述始于
titlestring通知的标题。1.0.0
bodystring通知的正文,显示在标题下方。1.0.0
largeBodystring设置在大文本通知样式中显示的多行文本块。1.0.0
summaryTextstring用于在收件箱和大文本通知样式中设置摘要文本详细信息。仅适用于 Android。1.0.0
idnumber通知标识符。在 Android 上为 32 位整数,因此值应在 -2147483648 到 2147483647 之间(包含)。1.0.0
schedule
Schedule
调度此通知在稍后时间触发。1.0.0
soundstring显示此通知时播放的音频文件名。包含文件扩展名。在 iOS 上,文件应位于应用包中。在 Android 上,文件应位于 res/raw 文件夹中。推荐格式为 .wav,因为它受 iOS 和 Android 支持。仅适用于 iOS 和 Android < 26。对于 Android 26+,使用配置了所需声音的通道的 channelId。如果找不到声音文件(例如空字符串或错误名称),将使用默认系统通知声音。如果未提供,Android 上将产生默认声音,iOS 上则无声音。1.0.0
smallIconstring设置自定义状态栏图标。如果设置,将覆盖 Capacitor 配置中的 smallIcon 选项。图标应放置在应用的 res/drawable 文件夹中。此选项的值应为可绘制资源 ID,即不带扩展名的文件名。仅适用于 Android。1.0.0
largeIconstring设置通知的大图标。图标应放置在应用的 res/drawable 文件夹中。此选项的值应为可绘制资源 ID,即不带扩展名的文件名。仅适用于 Android。1.0.0
iconColorstring设置通知图标的颜色。仅适用于 Android。1.0.0
attachmentsAttachment[]设置此通知的附件。1.0.0
actionTypeIdstring将此通知与操作类型关联。1.0.0
extraany设置存储在此通知中的额外数据。1.0.0
threadIdentifierstring用于分组多个通知。在 UNMutableNotificationContent 上设置 threadIdentifier。仅适用于 iOS。1.0.0
summaryArgumentstring此通知添加到类别摘要格式字符串的字符串。在 UNMutableNotificationContent 上设置 summaryArgument。仅适用于 iOS。1.0.0
groupstring用于分组多个通知。使用提供的值调用 NotificationCompat.Builder 上的 setGroup()。仅适用于 Android。1.0.0
groupSummaryboolean如果为 true,此通知成为一组通知的摘要。使用提供的值调用 NotificationCompat.Builder 上的 setGroupSummary()。仅在使用 group 时适用于 Android。1.0.0
channelIdstring指定通知应传递的通道。如果不存在具有给定名称的通道,则通知不会触发。如果未提供,将使用默认通道。使用提供的值调用 NotificationCompat.Builder 上的 setChannelId()。仅适用于 Android 26+。1.0.0
ongoingboolean如果为 true,通知无法滑动清除。使用提供的值调用 NotificationCompat.Builder 上的 setOngoing()。仅适用于 Android。1.0.0
autoCancelboolean如果为 true,用户点击通知时取消通知。使用提供的值调用 NotificationCompat.Builder 上的 setAutoCancel()。仅适用于 Android。1.0.0
inboxListstring[]设置在收件箱样式通知中显示的字符串列表。最多允许 5 个字符串。仅适用于 Android。1.0.0
silentboolean如果为 true,应用在前台时通知不会出现。仅适用于 iOS。5.0.0

Schedule

表示通知的调度。

使用 atonevery 之一来调度通知。

属性类型描述始于
at
Date
在特定日期和时间调度通知。1.0.0
repeatsbooleanat 指定的日期和时间重复传递此通知。仅适用于 iOS 和 Android。1.0.0
allowWhileIdleboolean允许此通知在 Doze 模式下触发。仅适用于 Android 23+。请注意,这些通知只能每个应用每 9 分钟触发一次1.0.0
on
ScheduleOn
在特定间隔调度通知。这类似于调度 cron 作业。仅适用于 iOS 和 Android。1.0.0
every
ScheduleEvery
在特定间隔调度通知。1.0.0
countnumber限制通过 every 指定的间隔传递通知的次数。1.0.0

Date

启用日期和时间的基本存储和检索。

方法签名描述
toString() => string返回日期的字符串表示形式。字符串的格式取决于区域设置。
toDateString() => string返回日期作为字符串值。
toTimeString() => string返回时间作为字符串值。
toLocaleString() => string返回适合主机环境当前区域设置的字符串值。
toLocaleDateString() => string返回适合主机环境当前区域设置的日期字符串值。
toLocaleTimeString() => string返回适合主机环境当前区域设置的时间字符串值。
valueOf() => number返回存储的时间值,自 1970 年 1 月 1 日 UTC 午夜以来的毫秒数。
getTime() => number获取时间值(毫秒)。
getFullYear() => number获取年份(本地时间)。
getUTCFullYear() => number使用协调世界时 (UTC) 获取年份。
getMonth() => number获取月份(本地时间)。
getUTCMonth() => number使用协调世界时 (UTC) 获取 Date 对象的月份。
getDate() => number获取月份中的日期(本地时间)。
getUTCDate() => number使用协调世界时 (UTC) 获取月份中的日期。
getDay() => number获取星期几(本地时间)。
getUTCDay() => number使用协调世界时 (UTC) 获取星期几。
getHours() => number获取日期中的小时(本地时间)。
getUTCHours() => number使用协调世界时 (UTC) 获取 Date 对象的小时值。
getMinutes() => number获取 Date 对象的分钟(本地时间)。
getUTCMinutes() => number使用协调世界时 (UTC) 获取 Date 对象的分钟。
getSeconds() => number获取 Date 对象的秒(本地时间)。
getUTCSeconds() => number使用协调世界时 (UTC) 获取 Date 对象的秒。
getMilliseconds() => number获取 Date 的毫秒(本地时间)。
getUTCMilliseconds() => number使用协调世界时 (UTC) 获取 Date 对象的毫秒。
getTimezoneOffset() => number获取本地计算机时间与协调世界时 (UTC) 之间的分钟差。
setTime(time: number) => number设置 Date 对象中的日期和时间值。
setMilliseconds(ms: number) => number使用本地时间设置 Date 对象中的毫秒值。
setUTCMilliseconds(ms: number) => number使用协调世界时 (UTC) 设置 Date 对象中的毫秒值。
setSeconds(sec: number, ms?: number | undefined) => number使用本地时间设置 Date 对象中的秒值。
setUTCSeconds(sec: number, ms?: number | undefined) => number使用协调世界时 (UTC) 设置 Date 对象中的秒值。
setMinutes(min: number, sec?: number | undefined, ms?: number | undefined) => number使用本地时间设置 Date 对象中的分钟值。
setUTCMinutes(min: number, sec?: number | undefined, ms?: number | undefined) => number使用协调世界时 (UTC) 设置 Date 对象中的分钟值。
setHours(hours: number, min?: number | undefined, sec?: number | undefined, ms?: number | undefined) => number使用本地时间设置 Date 对象中的小时值。
setUTCHours(hours: number, min?: number | undefined, sec?: number | undefined, ms?: number | undefined) => number使用协调世界时 (UTC) 设置 Date 对象中的小时值。
setDate(date: number) => number使用本地时间设置 Date 对象中的数字日期值。
setUTCDate(date: number) => number使用协调世界时 (UTC) 设置 Date 对象中的数字日期值。
setMonth(month: number, date?: number | undefined) => number使用本地时间设置 Date 对象中的月份值。
setUTCMonth(month: number, date?: number | undefined) => number使用协调世界时 (UTC) 设置 Date 对象中的月份值。
setFullYear(year: number, month?: number | undefined, date?: number | undefined) => number使用本地时间设置 Date 对象的年份。
setUTCFullYear(year: number, month?: number | undefined, date?: number | undefined) => number使用协调世界时 (UTC) 设置 Date 对象中的年份值。
toUTCString() => string返回使用协调世界时 (UTC) 转换的日期字符串。
toISOString() => string以 ISO 格式返回日期作为字符串值。
toJSON(key?: any) => string由 JSON.stringify 方法使用,以启用对象数据的 JavaScript 对象表示法 (JSON) 序列化转换。

ScheduleOn

属性类型
yearnumber
monthnumber
daynumber
weekday
Weekday
hournumber
minutenumber
secondnumber

Attachment

表示通知附件。

属性类型描述始于
idstring附件标识符。1.0.0
urlstring附件的 URL。使用 res 方案引用网络资源,例如 res:///assets/img/icon.png。也接受 file URL。1.0.0
options
AttachmentOptions
附件选项。1.0.0

AttachmentOptions

属性类型描述始于
iosUNNotificationAttachmentOptionsTypeHintKeystringUNNotificationAttachment 的可哈希选项中设置 UNNotificationAttachmentOptionsTypeHintKey 键。仅适用于 iOS。1.0.0
iosUNNotificationAttachmentOptionsThumbnailHiddenKeystringUNNotificationAttachment 的可哈希选项中设置 UNNotificationAttachmentOptionsThumbnailHiddenKey 键。仅适用于 iOS。1.0.0
iosUNNotificationAttachmentOptionsThumbnailClippingRectKeystringUNNotificationAttachment 的可哈希选项中设置 UNNotificationAttachmentOptionsThumbnailClippingRectKey 键。仅适用于 iOS。1.0.0
iosUNNotificationAttachmentOptionsThumbnailTimeKeystringUNNotificationAttachment 的可哈希选项中设置 UNNotificationAttachmentOptionsThumbnailTimeKey 键。仅适用于 iOS。1.0.0

PendingResult

属性类型描述始于
notificationsPendingLocalNotificationSchema[]待处理通知列表。1.0.0

PendingLocalNotificationSchema

属性类型描述始于
titlestring通知的标题。1.0.0
bodystring通知的正文,显示在标题下方。1.0.0
idnumber通知标识符。1.0.0
schedule
Schedule
调度此通知在稍后时间触发。1.0.0
extraany设置存储在此通知中的额外数据。1.0.0

RegisterActionTypesOptions

属性类型描述始于
typesActionType[]要注册的操作类型列表。1.0.0

ActionType

操作的集合。

属性类型描述始于
idstring操作类型的 ID。在通知中通过 actionTypeId 键引用。1.0.0
actionsAction[]与此操作类型关联的操作列表。1.0.0
iosHiddenPreviewsBodyPlaceholderstring设置 UNNotificationCategoryhiddenPreviewsBodyPlaceholder。仅适用于 iOS。1.0.0
iosCustomDismissActionbooleanUNNotificationCategory 的选项中设置 customDismissAction。仅适用于 iOS。1.0.0
iosAllowInCarPlaybooleanUNNotificationCategory 的选项中设置 allowInCarPlay。仅适用于 iOS。1.0.0
iosHiddenPreviewsShowTitlebooleanUNNotificationCategory 的选项中设置 hiddenPreviewsShowTitle。仅适用于 iOS。1.0.0
iosHiddenPreviewsShowSubtitlebooleanUNNotificationCategory 的选项中设置 hiddenPreviewsShowSubtitle。仅适用于 iOS。1.0.0

Action

显示通知时可以执行的操作。

属性类型描述始于
idstring操作标识符。在 'actionPerformed' 事件中作为 actionId 引用。1.0.0
titlestring为此操作显示的标题文本。1.0.0
requiresAuthenticationbooleanUNNotificationAction 的选项中设置 authenticationRequired。仅适用于 iOS。1.0.0
foregroundbooleanUNNotificationAction 的选项中设置 foreground。仅适用于 iOS。1.0.0
destructivebooleanUNNotificationAction 的选项中设置 destructive。仅适用于 iOS。1.0.0
inputboolean使用 UNTextInputNotificationAction 而不是 UNNotificationAction。仅适用于 iOS。1.0.0
inputButtonTitlestringUNTextInputNotificationAction 上设置 textInputButtonTitle。仅当 inputtrue 时适用于 iOS。1.0.0
inputPlaceholderstringUNTextInputNotificationAction 上设置 textInputPlaceholder。仅当 inputtrue 时适用于 iOS。1.0.0

CancelOptions

属性类型描述始于
notificationsLocalNotificationDescriptor[]要取消的通知列表。1.0.0

EnabledResult

属性类型描述始于
valueboolean设备是否启用了本地通知。1.0.0

DeliveredNotifications

属性类型描述始于
notificationsDeliveredNotificationSchema[]通知屏幕上可见的通知列表。1.0.0

DeliveredNotificationSchema

属性类型描述始于
idnumber通知标识符。4.0.0
tagstring通知标签。仅适用于 Android。4.0.0
titlestring通知的标题。4.0.0
bodystring通知的正文,显示在标题下方。4.0.0
groupstring通知的配置组。仅适用于 Android。4.0.0
groupSummaryboolean如果此通知是一组通知的摘要,则为 true。仅适用于 Android。4.0.0
dataany包含在通知负载中的任何附加数据。仅适用于 Android。4.0.0
extraany存储在此通知中的额外数据。仅适用于 iOS。4.0.0
attachmentsAttachment[]此通知的附件。仅适用于 iOS。1.0.0
actionTypeIdstring与此通知关联的操作类型。仅适用于 iOS。4.0.0
schedule
Schedule
用于触发此通知的调度。仅适用于 iOS。4.0.0
soundstring显示通知时使用的声音。仅适用于 iOS。4.0.0

Channel

属性类型描述默认始于
idstring通道标识符。1.0.0
namestring此通道的用户友好名称(向用户显示)。1.0.0
descriptionstring此通道的描述(向用户显示)。1.0.0
soundstring应为此通道发布的通知播放的声音。重要性至少为 3 的通知通道应具有声音。声音文件的文件名应相对于 Android 应用 res/raw 目录指定。如果未提供声音,或找不到声音文件,则不使用声音。1.0.0
importance
Importance
此通道发布的通知的中断级别。
3
1.0.0
visibility
Visibility
此通道发布的通知的可见性。此设置用于确定发布到此通道的通知是否出现在锁屏上,以及如果出现,是否以编辑形式显示。1.0.0
lightsboolean发布到此通道的通知是否应显示通知灯(在支持的设备上)。1.0.0
lightColorstring发布到此通道的通知的灯光颜色。仅当在此通道上启用了灯光且设备支持时才受支持。支持的颜色格式为 #RRGGBB#RRGGBBAA1.0.0
vibrationboolean发布到此通道的通知是否应振动。1.0.0

ListChannelsResult

属性类型描述始于
channelsChannel[]通知通道列表。1.0.0

PermissionStatus

属性类型描述始于
display
PermissionState
显示通知的权限状态。1.0.0

SettingsPermissionStatus

属性类型描述始于
exact_alarm
PermissionState
使用精确闹钟的权限状态。6.0.0

PluginListenerHandle

属性类型
remove() => Promise<void>

ActionPerformed

属性类型描述始于
actionIdstring执行的操作的标识符。1.0.0
inputValuestring用户在通知上输入的值。仅在 iOS 上适用于将 input 设置为 true 的通知。1.0.0
notification
LocalNotificationSchema
原始通知架构。1.0.0

Type Aliases

ScheduleEvery

'year' | 'month' | 'two-weeks' | 'week' | 'day' | 'hour' | 'minute' | 'second'

Importance

重要性级别。有关更多详细信息,请参阅 Android 开发者文档

1 | 2 | 3 | 4 | 5

Visibility

通知可见性。有关更多详细信息,请参阅 Android 开发者文档

-1 | 0 | 1

PermissionState

'prompt' | 'prompt-with-rationale' | 'granted' | 'denied'

Enums

Weekday

成员
Sunday1
Monday2
Tuesday3
Wednesday4
Thursday5
Friday6
Saturday7