跳到主要内容
版本:v4

@capacitor/local-notifications

本地通知 API 提供了一种在设备本地调度通知的方式(即无需服务器发送推送通知)。

安装

npm install @capacitor/local-notifications
npx cap sync

Android

从 Android 12 开始,除非将此权限添加到你的 AndroidManifest.xml 中,否则计划通知将不会是精确触发的:

<uses-permission android:name="android.permission.SCHEDULE_EXACT_ALARM" />

请注意,即使拥有此权限,用户仍然可以从应用设置中禁用精确通知。

配置

在 Android 上,本地通知可以通过以下选项进行配置:

属性类型描述始于版本
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;

休眠模式

如果设备已进入 休眠模式,你的应用可能会受到功能限制。如果你需要在休眠期间也触发通知,请通过设置 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


addListener('localNotificationReceived', ...)

addListener(eventName: 'localNotificationReceived', listenerFunc: (notification: LocalNotificationSchema) => void) => Promise<PluginListenerHandle> & PluginListenerHandle

监听通知显示事件。

参数类型
eventName'localNotificationReceived'
listenerFunc
(notification: LocalNotificationSchema) => void

返回值:

Promise<PluginListenerHandle> & PluginListenerHandle

自版本: 1.0.0


addListener('localNotificationActionPerformed', ...)

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

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

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

返回值:

Promise<PluginListenerHandle> & PluginListenerHandle

自版本: 1.0.0


removeAllListeners()

removeAllListeners() => Promise<void>

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

自版本: 1.0.0


接口

ScheduleResult

属性类型描述自版本
notificationsLocalNotificationDescriptor[]已安排的通知列表。1.0.0

LocalNotificationDescriptor

描述本地通知的对象。

属性类型描述自版本
idnumber通知标识符。1.0.0

ScheduleOptions

属性类型描述自版本
notificationsLocalNotificationSchema[]要安排的通知列表。1.0.0
------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
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
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() 并传入提供的值。仅适用于 Android(当使用 group 时)。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

表示通知的调度计划。

使用 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

用于实现日期和时间的基本存储与检索功能。| 方法 | 签名 | 描述 | | ---------------------- | ------------------------------------------------------------------------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------- | | 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
Attachment 选项。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

一个动作类型的集合。

属性类型描述始于版本
idstring动作类型的 ID。在通知中通过 actionTypeId 键引用。1.0.0
actionsAction[]与此动作类型关联的动作列表。1.0.0
iosHiddenPreviewsBodyPlaceholderstring设置 UNNotificationCategoryhiddenPreviewsBodyPlaceholder。仅适用于 iOS。1.0.0
iosCustomDismissActionboolean设置 UNNotificationCategory 选项中的 customDismissAction。仅适用于 iOS。1.0.0
iosAllowInCarPlayboolean设置 UNNotificationCategory 选项中的 allowInCarPlay。仅适用于 iOS。1.0.0
iosHiddenPreviewsShowTitleboolean设置 UNNotificationCategory 选项中的 hiddenPreviewsShowTitle。仅适用于 iOS。1.0.0
iosHiddenPreviewsShowSubtitleboolean设置 UNNotificationCategory 选项中的 hiddenPreviewsShowSubtitle。仅适用于 iOS。1.0.0

Action

显示通知时可以执行的一个动作。

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

CancelOptions

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

EnabledResult

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

DeliveredNotifications

属性类型描述始于版本
notificationsDeliveredNotificationSchema[]通知屏幕上可见的通知列表。1.0.0
属性类型描述始于版本
idnumber通知标识符。4.0.0
tagstring通知标签。仅在 Android 上可用。4.0.0
titlestring通知的标题。4.0.0
bodystring通知的正文,显示在标题下方。4.0.0
groupstring通知的配置组。仅在 Android 上可用。4.0.0
groupSummaryboolean此通知是否为通知组的摘要。仅在 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
属性类型描述始于
channelsChannel[]通知渠道列表。1.0.0

PermissionStatus

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

PluginListenerHandle

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

ActionPerformed

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

类型别名

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'

枚举

Weekday

成员
Sunday1
Monday2
Tuesday3
Wednesday4
Thursday5
Friday6
Saturday7