跳到主要内容
版本：v6

@capacitor/local-notifications

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

安装​

npm install @capacitor/local-notifications@latest-6
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 文档。

从 Android 15 开始，用户可以在 私密空间 中安装应用。用户可以随时锁定其私密空间，这意味着在用户解锁之前，推送通知不会显示。

无法检测应用是否安装在私密空间中。因此，如果您的应用显示任何关键通知，请告知用户避免将应用安装在私密空间中。

有关与应用私密空间相关的行为更改的更多信息，请参阅 Android 文档。

配置​

在 Android 上，本地通知可以使用以下选项进行配置：

属性类型描述自版本
smallIconstring设置通知的默认状态栏图标。图标应放置在应用的 res/drawable 文件夹中。此选项的值应为 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)​

如果设备已进入 休眠模式，您的应用功能可能会受到限制。如果您需要即使在休眠模式下也能触发通知，请使用 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

接口​

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
silentboolean如果为 true，当应用在前台运行时，通知将不会显示。仅适用于 iOS。5.0.0

表示通知的调度计划。

可使用 at、on 或 every 来调度通知。

属性类型描述始于版本
at
Date
在特定日期和时间调度通知。1.0.0
repeatsboolean按 at 指定的日期和时间重复投递此通知。仅适用于 iOS 和 Android。1.0.0
allowWhileIdleboolean允许此通知在设备处于休眠模式时触发。仅适用于 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 方案来引用 Web 资产，例如 res:///assets/img/icon.png。也接受 file URLs。1.0.0
options
AttachmentOptions
附件 选项。1.0.0

AttachmentOptions​

属性类型描述始于
iosUNNotificationAttachmentOptionsTypeHintKeystring在 UNNotificationAttachment 的可哈希选项字典中设置 UNNotificationAttachmentOptionsTypeHintKey 键。仅适用于 iOS。1.0.0
iosUNNotificationAttachmentOptionsThumbnailHiddenKeystring在 UNNotificationAttachment 的可哈希选项字典中设置 UNNotificationAttachmentOptionsThumbnailHiddenKey 键。仅适用于 iOS。1.0.0
iosUNNotificationAttachmentOptionsThumbnailClippingRectKeystring在 UNNotificationAttachment 的可哈希选项字典中设置 UNNotificationAttachmentOptionsThumbnailClippingRectKey 键。仅适用于 iOS。1.0.0
iosUNNotificationAttachmentOptionsThumbnailTimeKeystring在 UNNotificationAttachment 的可哈希选项字典中设置 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设置 UNNotificationCategory 的 hiddenPreviewsBodyPlaceholder。仅适用于 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
inputButtonTitlestring在 UNTextInputNotificationAction 上设置 textInputButtonTitle。仅适用于 iOS 且当 input 为 true 时。1.0.0
inputPlaceholderstring在 UNTextInputNotificationAction 上设置 textInputPlaceholder。仅适用于 iOS 且当 input 为 true 时。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 和 #RRGGBBAA。1.0.0
vibrationboolean发布到此频道的通知是否应振动。1.0.0
属性类型描述始于
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

类型别名​

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

Contents

编辑此页