版本：v3

@capacitor/local-notifications

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

安装

npm install @capacitor/local-notifications
npx cap sync

配置

在 Android 上，可以通过以下选项配置本地通知：

属性	Type	描述	始于
`smallIcon`	`string`	设置通知的默认状态栏图标。图标应放置在应用的 `res/drawable` 文件夹中。此选项的值应为 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)

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

安排一个或多个本地通知。

参数	Type
`options`	`ScheduleOptions`

返回：

Promise<ScheduleResult>

始于： 1.0.0

getPending()

getPending() => Promise<PendingResult>

获取待处理通知列表。

返回：

Promise<PendingResult>

始于： 1.0.0

registerActionTypes(...)

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

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

仅适用于 iOS 和 Android。

参数	Type
`options`	`RegisterActionTypesOptions`

始于： 1.0.0

cancel(...)

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

取消待处理的通知。

参数	Type
`options`	`CancelOptions`

始于： 1.0.0

areEnabled()

areEnabled() => Promise<EnabledResult>

检查通知是否已启用。

返回：

Promise<EnabledResult>

始于： 1.0.0

createChannel(...)

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

创建通知频道。

仅适用于 Android。

参数	Type
`channel`	`Channel`

始于： 1.0.0

deleteChannel(...)

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

删除通知频道。

仅适用于 Android。

参数	Type
`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

监听通知显示的事件。

参数	Type
`eventName`	`'localNotificationReceived'`
`listenerFunc`	`(notification: LocalNotificationSchema) => void`

返回：

Promise<PluginListenerHandle> & PluginListenerHandle

始于： 1.0.0

addListener('localNotificationActionPerformed', ...)

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

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

参数	Type
`eventName`	`'localNotificationActionPerformed'`
`listenerFunc`	`(notificationAction: ActionPerformed) => void`

返回：

Promise<PluginListenerHandle> & PluginListenerHandle

始于： 1.0.0

removeAllListeners()

removeAllListeners() => Promise<void>

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

始于： 1.0.0

接口

ScheduleResult

属性	Type	描述	始于
`notifications`	`LocalNotificationDescriptor[]`	已安排的通知列表。	1.0.0

LocalNotificationDescriptor

描述本地通知的对象。

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

ScheduleOptions

属性	Type	描述	始于
`notifications`	`LocalNotificationSchema[]`	要安排的通知列表。	1.0.0

LocalNotificationSchema

属性	Type	描述	始于
`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 上，文件应在应用 bundle 中。在 Android 上，文件应在 res/raw 文件夹中。推荐使用 `.wav` 格式，因为 iOS 和 Android 都支持。仅适用于 iOS 和 Android < 26。对于 Android 26+，请使用配置了所需声音的 channelId。如果未找到声音文件（即空字符串或错误名称），将使用默认系统通知声音。如果未提供，Android 将产生默认声音，iOS 将没有声音。	1.0.0
`smallIcon`	`string`	设置自定义状态栏图标。如果设置，它将覆盖 Capacitor 配置中的 `smallIcon` 选项。图标应放置在应用的 `res/drawable` 文件夹中。此选项的值应为 drawable 资源 ID，即不带扩展名的文件名。仅适用于 Android。	1.0.0
`largeIcon`	`string`	为通知设置大图标。图标应放置在应用的 `res/drawable` 文件夹中。此选项的值应为 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 之一来安排通知。

属性	Type	描述	始于
`at`	`Date`	在特定的日期和时间安排通知。	1.0.0
`repeats`	`boolean`	在 `at` 指定的日期和时间重复投递此通知。仅适用于 iOS 和 Android。	1.0.0
`allowWhileIdle`	`boolean`	允许此通知在低电耗模式下触发。仅适用于 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

支持日期和时间的 basic storage and retrieval。

方法	签名	描述
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

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

Attachment

表示通知附件。

属性	Type	描述	始于
`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

属性	Type	描述	始于
`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

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

PendingLocalNotificationSchema

属性	Type	描述	始于
`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

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

ActionType

操作的集合。

属性	Type	描述	始于
`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

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

属性	Type	描述	始于
`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

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

EnabledResult

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

Channel

属性	Type	描述	始于
`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

属性	Type	描述	始于
`channels`	`Channel[]`	通知频道列表。	1.0.0

PermissionStatus

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

PluginListenerHandle

属性	Type
`remove`	`() => Promise<void>`

ActionPerformed

属性	Type	描述	始于
`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

成员	Value
`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