跳到主要内容
版本：v5

@capacitor/local-notifications

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

安装​

npm install @capacitor/local-notifications@latest-5
npx cap sync

Android 系统​

Android 13 需要权限检查才能发送通知。您必须相应地调用 checkPermissions() 和 requestPermissions()。

在 Android 12 及更早版本上，不会显示权限提示，直接返回已授予状态。

从 Android 12 开始，除非在您的 AndroidManifest.xml 中添加此权限，否则计划通知将不精确：

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

请注意，即使存在该权限，用户仍然可以从应用设置中禁用精确通知。

配置​

在 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;

低电耗模式​

如果设备已进入低电耗模式，您的应用功能可能会受到限制。如果您需要在低电耗模式下仍能触发通知，请通过设置 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

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

定时设置​

代表通知的调度计划。

使用 at、on 或 every 来安排通知。

属性类型描述始于
at
Date
在特定日期和时间安排通知。1.0.0
repeatsboolean在 at 指定的日期和时间重复发送此通知。仅适用于 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 | 返回自协调世界时（UTC）1970年1月1日午夜以来的存储时间值（以毫秒为单位）。 | | 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 协议的 URL。1.0.0
options
AttachmentOptions
Attachment 的选项。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
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设置 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 属性。仅当 input 为 true 时适用于 iOS。1.0.0
inputPlaceholderstring设置 UNTextInputNotificationAction 的 textInputPlaceholder 属性。仅当 input 为 true 时适用于 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此通知是否为通知组的摘要。仅适用于 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

ListChannelsResult​

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

Contents

编辑此页