版本：v3

@capacitor/local-notifications

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

安装

npm install @capacitor/local-notifications
npx cap sync

配置

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

属性	类型	描述	始于
`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()
createChannel(...)
deleteChannel(...)
listChannels()
checkPermissions()
requestPermissions()
addListener('localNotificationReceived', ...)
addListener('localNotificationActionPerformed', ...)
removeAllListeners()
接口
类型别名
枚举

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

createChannel(...)

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

创建通知通道。

仅适用于 Android。

参数	类型
`channel`	`Channel`

始于： 1.0.0

deleteChannel(...)

deleteChannel(channel: NotificationChannel) => Promise<void>

删除通知通道。

仅适用于 Android。

参数	类型
`channel`	`Channel`

始于： 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

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

LocalNotificationDescriptor

描述本地通知的对象。

属性	类型	描述	始于
`id`	`number`	通知标识符。	1.0.0

ScheduleOptions

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

LocalNotificationSchema

属性	类型	描述	始于
`title`	`string`	通知的标题。	1.0.0
`body`	`string`	通知的正文，显示在标题下方。	1.0.0
`largeBody`	`string`	为大文本通知样式设置多行文本块。	1.0.0
`summaryText`	`string`	用于在收件箱和大文本通知样式中设置摘要文本详情。仅适用于 Android。	1.0.0
`id`	`number`	通知标识符。	1.0.0
`schedule`	`Schedule`	调度此通知在稍后时间触发。	1.0.0
`sound`	`string`	显示此通知时播放的音频文件名。包含文件扩展名。在 iOS 上，文件应位于应用包中。在 Android 上，文件应位于 res/raw 文件夹中。推荐格式为 `.wav`，因为 iOS 和 Android 都支持。仅适用于 iOS 和 Android < 26。对于 Android 26+，使用配置了所需声音的 channelId。如果未找到声音文件（例如空字符串或错误名称），将使用默认系统通知声音。如果未提供，在 Android 上将产生默认声音，在 iOS 上则没有声音。	1.0.0
`smallIcon`	`string`	设置自定义状态栏图标。如果设置，将覆盖 Capacitor 配置中的 `smallIcon` 选项。图标应放置在应用的 `res/drawable` 文件夹中。此选项的值应为可绘制资源 ID，即不带扩展名的文件名。仅适用于 Android。	1.0.0
`largeIcon`	`string`	设置通知的大图标。图标应放置在应用的 `res/drawable` 文件夹中。此选项的值应为可绘制资源 ID，即不带扩展名的文件名。仅适用于 Android。	1.0.0
`iconColor`	`string`	设置通知图标的颜色。仅适用于 Android。	1.0.0
`attachments`	`Attachment[]`	设置此通知的附件。	1.0.0
`actionTypeId`	`string`	将此通知与操作类型关联。	1.0.0
`extra`	`any`	设置存储在此通知中的额外数据。	1.0.0
`threadIdentifier`	`string`	用于分组多个通知。在 `UNMutableNotificationContent` 上设置 `threadIdentifier`。仅适用于 iOS。	1.0.0
`summaryArgument`	`string`	此通知添加到类别摘要格式字符串的字符串。在 `UNMutableNotificationContent` 上设置 `summaryArgument`。仅适用于 iOS 12+。	1.0.0
`group`	`string`	用于分组多个通知。在 `NotificationCompat.Builder` 上调用 `setGroup()` 并传入提供的值。仅适用于 Android。	1.0.0
`groupSummary`	`boolean`	如果为 true，此通知成为一组通知的摘要。在 `NotificationCompat.Builder` 上调用 `setGroupSummary()` 并传入提供的值。仅适用于 Android 在使用 `group` 时。	1.0.0
`channelId`	`string`	指定通知应传递的通道。如果给定名称的通道不存在，则通知不会触发。如果未提供，将使用默认通道。在 `NotificationCompat.Builder` 上调用 `setChannelId()` 并传入提供的值。仅适用于 Android 26+。	1.0.0
`ongoing`	`boolean`	如果为 true，通知无法被滑走。在 `NotificationCompat.Builder` 上调用 `setOngoing()` 并传入提供的值。仅适用于 Android。	1.0.0
`autoCancel`	`boolean`	如果为 true，当用户点击通知时取消通知。在 `NotificationCompat.Builder` 上调用 `setAutoCancel()` 并传入提供的值。仅适用于 Android。	1.0.0
`inboxList`	`string[]`	设置在收件箱样式通知中显示的字符串列表。最多允许 5 个字符串。仅适用于 Android。	1.0.0

Schedule

表示通知的调度。

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

属性	类型	描述	始于
`at`	`Date`	在特定日期和时间调度通知。	1.0.0
`repeats`	`boolean`	按 `at` 指定的日期和时间重复传递此通知。仅适用于 iOS 和 Android。	1.0.0
`allowWhileIdle`	`boolean`	允许此通知在 Doze 模式下触发。仅适用于 Android 23+。请注意，这些通知每个应用每 9 分钟只能触发一次。	1.0.0
`on`	`ScheduleOn`	在特定间隔调度通知。这类似于调度 cron 作业。仅适用于 iOS 和 Android。	1.0.0
`every`	`ScheduleEvery`	按特定间隔调度通知。	1.0.0
`count`	`number`	限制按 `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

属性	类型
`year`	`number`
`month`	`number`
`day`	`number`
`weekday`	`Weekday`
`hour`	`number`
`minute`	`number`
`second`	`number`

Attachment

表示通知附件。

属性	类型	描述	始于
`id`	`string`	附件标识符。	1.0.0
`url`	`string`	附件的 URL。使用 `res` 方案引用 Web 资源，例如 `res:///assets/img/icon.png`。也接受 `file` URL。	1.0.0
`options`	`AttachmentOptions`	附件选项。	1.0.0

AttachmentOptions

属性	类型	描述	始于
`iosUNNotificationAttachmentOptionsTypeHintKey`	`string`	设置 `UNNotificationAttachment` 的可哈希选项中的 `UNNotificationAttachmentOptionsTypeHintKey` 键。仅适用于 iOS。	1.0.0
`iosUNNotificationAttachmentOptionsThumbnailHiddenKey`	`string`	设置 `UNNotificationAttachment` 的可哈希选项中的 `UNNotificationAttachmentOptionsThumbnailHiddenKey` 键。仅适用于 iOS。	1.0.0
`iosUNNotificationAttachmentOptionsThumbnailClippingRectKey`	`string`	设置 `UNNotificationAttachment` 的可哈希选项中的 `UNNotificationAttachmentOptionsThumbnailClippingRectKey` 键。仅适用于 iOS。	1.0.0
`iosUNNotificationAttachmentOptionsThumbnailTimeKey`	`string`	设置 `UNNotificationAttachment` 的可哈希选项中的 `UNNotificationAttachmentOptionsThumbnailTimeKey` 键。仅适用于 iOS。	1.0.0

PendingResult

属性	类型	描述	始于
`notifications`	`PendingLocalNotificationSchema[]`	待处理通知的列表。	1.0.0

PendingLocalNotificationSchema

属性	类型	描述	始于
`title`	`string`	通知的标题。	1.0.0
`body`	`string`	通知的正文，显示在标题下方。	1.0.0
`id`	`number`	通知标识符。	1.0.0
`schedule`	`Schedule`	调度此通知在稍后时间触发。	1.0.0
`extra`	`any`	设置存储在此通知中的额外数据。	1.0.0

RegisterActionTypesOptions

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

ActionType

操作的集合。

属性	类型	描述	始于
`id`	`string`	操作类型的 ID。在通知中通过 `actionTypeId` 键引用。	1.0.0
`actions`	`Action[]`	与此操作类型关联的操作列表。	1.0.0
`iosHiddenPreviewsBodyPlaceholder`	`string`	设置 `UNNotificationCategory` 的 `hiddenPreviewsBodyPlaceholder`。仅适用于 iOS。	1.0.0
`iosCustomDismissAction`	`boolean`	在 `UNNotificationCategory` 的选项中设置 `customDismissAction`。仅适用于 iOS。	1.0.0
`iosAllowInCarPlay`	`boolean`	在 `UNNotificationCategory` 的选项中设置 `allowInCarPlay`。仅适用于 iOS。	1.0.0
`iosHiddenPreviewsShowTitle`	`boolean`	在 `UNNotificationCategory` 的选项中设置 `hiddenPreviewsShowTitle`。仅适用于 iOS。	1.0.0
`iosHiddenPreviewsShowSubtitle`	`boolean`	在 `UNNotificationCategory` 的选项中设置 `hiddenPreviewsShowSubtitle`。仅适用于 iOS。	1.0.0

Action

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

属性	类型	描述	始于
`id`	`string`	操作标识符。在 `'actionPerformed'` 事件中作为 `actionId` 引用。	1.0.0
`title`	`string`	为此操作显示的标题文本。	1.0.0
`requiresAuthentication`	`boolean`	在 `UNNotificationAction` 的选项中设置 `authenticationRequired`。仅适用于 iOS。	1.0.0
`foreground`	`boolean`	在 `UNNotificationAction` 的选项中设置 `foreground`。仅适用于 iOS。	1.0.0
`destructive`	`boolean`	在 `UNNotificationAction` 的选项中设置 `destructive`。仅适用于 iOS。	1.0.0
`input`	`boolean`	使用 `UNTextInputNotificationAction` 而不是 `UNNotificationAction`。仅适用于 iOS。	1.0.0
`inputButtonTitle`	`string`	在 `UNTextInputNotificationAction` 上设置 `textInputButtonTitle`。仅适用于 iOS 且 `input` 为 `true` 时。	1.0.0
`inputPlaceholder`	`string`	在 `UNTextInputNotificationAction` 上设置 `textInputPlaceholder`。仅适用于 iOS 且 `input` 为 `true` 时。	1.0.0

CancelOptions

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

EnabledResult

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

Channel

属性	类型	描述	始于
`id`	`string`	通道标识符。	1.0.0
`name`	`string`	此通道的用户友好名称（呈现给用户）。	1.0.0
`description`	`string`	此通道的描述（呈现给用户）。	1.0.0
`sound`	`string`	应为此通道中发布的通知播放的声音。重要性至少为 `3` 的通知通道应具有声音。声音文件名应相对于 Android 应用 `res/raw` 目录指定。如果未提供声音，或未找到声音文件，则不使用声音。	1.0.0
`importance`	`Importance`	发布到此通道的通知的中断级别。	1.0.0
`visibility`	`Visibility`	发布到此通道的通知的可见性。此设置控制发布到此通道的通知是否出现在锁屏上，以及如果出现，是否以经过编辑的形式显示。	1.0.0
`lights`	`boolean`	发布到此通道的通知是否应显示通知灯（在支持的设备上）。	1.0.0
`lightColor`	`string`	发布到此通道的通知的灯光颜色。仅在此通道启用灯光且设备支持时才支持。支持的颜色格式为 `#RRGGBB` 和 `#RRGGBBAA`。	1.0.0
`vibration`	`boolean`	发布到此通道的通知是否应振动。	1.0.0

ListChannelsResult

属性	类型	描述	始于
`channels`	`Channel[]`	通知通道的列表。	1.0.0

PermissionStatus

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

PluginListenerHandle

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

ActionPerformed

属性	类型	描述	始于
`actionId`	`string`	已执行操作的标识符。	1.0.0
`inputValue`	`string`	用户在通知上输入的值。仅在 iOS 上适用于 `input` 设置为 `true` 的通知。	1.0.0
`notification`	`LocalNotificationSchema`	原始通知模式。	1.0.0

类型别名

ScheduleEvery

NotificationChannel

Channel

Importance

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

1 | 2 | 3 | 4 | 5

Visibility

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

-1 | 0 | 1

PermissionState

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

枚举

Weekday

成员	值
`Sunday`	`1`
`Monday`	`2`
`Tuesday`	`3`
`Wednesday`	`4`
`Thursday`	`5`
`Friday`	`6`
`Saturday`	`7`

安装​

配置​

示例​

Doze 模式​

API​

schedule(...)​

getPending()​

registerActionTypes(...)​

cancel(...)​

areEnabled()​

createChannel(...)​

deleteChannel(...)​

listChannels()​

checkPermissions()​

requestPermissions()​

addListener('localNotificationReceived', ...)​

addListener('localNotificationActionPerformed', ...)​

removeAllListeners()​

接口​

ScheduleResult​

LocalNotificationDescriptor​

ScheduleOptions​

LocalNotificationSchema​

Schedule​

Date​

ScheduleOn​

Attachment​

AttachmentOptions​

PendingResult​

PendingLocalNotificationSchema​

RegisterActionTypesOptions​

ActionType​

Action​

CancelOptions​

EnabledResult​

Channel​

ListChannelsResult​

PermissionStatus​

PluginListenerHandle​

ActionPerformed​

类型别名​

ScheduleEvery​

NotificationChannel​

Importance​

Visibility​

PermissionState​

枚举​

Weekday​

Contents

安装

配置

示例

Doze 模式

API

schedule(...)

getPending()

registerActionTypes(...)

cancel(...)

areEnabled()

createChannel(...)

deleteChannel(...)

listChannels()

checkPermissions()

requestPermissions()

addListener('localNotificationReceived', ...)

addListener('localNotificationActionPerformed', ...)

removeAllListeners()

接口

ScheduleResult

LocalNotificationDescriptor

ScheduleOptions

LocalNotificationSchema

Schedule

Date

ScheduleOn

Attachment

AttachmentOptions

PendingResult

PendingLocalNotificationSchema

RegisterActionTypesOptions

ActionType

Action

CancelOptions

EnabledResult

Channel

ListChannelsResult

PermissionStatus

PluginListenerHandle

ActionPerformed

类型别名

ScheduleEvery

NotificationChannel

Importance

Visibility

PermissionState

枚举

Weekday