版本：v2

本地通知

本地通知 API 提供了一种安排"本地"通知的方式——这些通知在设备上调度并发送，与从服务器发送的"推送"通知不同。

本地通知非常适合在用户上次访问后提醒他们应用中的变化、提供提醒功能，以及在应用不处于前台时传递离线信息。

示例

import { Plugins } from '@capacitor/core';
const { LocalNotifications } = Plugins;

const notifs = await LocalNotifications.schedule({
  notifications: [
    {
      title: '标题',
      body: '正文',
      id: 1,
      schedule: { at: new Date(Date.now() + 1000 * 5) },
      sound: null,
      attachments: null,
      actionTypeId: '',
      extra: null,
    },
  ],
});
console.log('已安排的通知', notifs);

本地通知配置（仅限 Android）

本地通知插件允许在 capacitor.config.json 中为 Android 平台添加以下配置值：

smallIcon：允许设置本地通知的默认图标。
iconColor：允许设置本地通知图标的默认颜色。
sound：允许设置默认的通知声音。在 Android 26+ 上，它设置默认通道声音，除非卸载应用，否则无法更改。

 "plugins": {
    "LocalNotifications": {
      "smallIcon": "ic_stat_icon_config_sample",
      "iconColor": "#488AFF",
      "sound": "beep.wav"
    }
  }

API

schedule(...)

schedule(options: { notifications: LocalNotification[]; }) => Promise<LocalNotificationScheduleResult>

安排通知。

参数	类型
`options`	`{ notifications: LocalNotification[]; }`

返回值：

Promise<LocalNotificationScheduleResult>

getPending()

getPending() => Promise<LocalNotificationPendingList>

获取待处理通知列表。

返回值：

Promise<LocalNotificationPendingList>

registerActionTypes(...)

registerActionTypes(options: { types: LocalNotificationActionType[]; }) => Promise<void>

注册操作类型。

参数	类型
`options`	`{ types: LocalNotificationActionType[]; }`

cancel(...)

cancel(pending: LocalNotificationPendingList) => Promise<void>

取消待处理通知。

参数	类型
`pending`	`LocalNotificationPendingList`

areEnabled()

areEnabled() => Promise<LocalNotificationEnabledResult>

检查是否启用了通知。

返回值：

Promise<LocalNotificationEnabledResult>

createChannel(...)

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

创建通知通道（仅限 Android）。

参数	类型
`channel`	`NotificationChannel`

deleteChannel(...)

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

删除通知通道（仅限 Android）。

参数	类型
`channel`	`NotificationChannel`

listChannels()

listChannels() => Promise<NotificationChannelList>

列出通知通道（仅限 Android）。

返回值：

Promise<NotificationChannelList>

requestPermission()

requestPermission() => Promise<NotificationPermissionResponse>

请求通知权限。

返回值：

Promise<NotificationPermissionResponse>

addListener(...)

addListener(eventName: 'localNotificationReceived', listenerFunc: (notification: LocalNotification) => void) => PluginListenerHandle

监听本地通知接收事件。

参数	类型
`eventName`	`"localNotificationReceived"`
`listenerFunc`	`(notification: LocalNotification) => void`

返回值：

PluginListenerHandle

addListener(...)

addListener(eventName: 'localNotificationActionPerformed', listenerFunc: (notificationAction: LocalNotificationActionPerformed) => void) => PluginListenerHandle

监听本地通知操作执行事件。

参数	类型
`eventName`	`"localNotificationActionPerformed"`
`listenerFunc`	`(notificationAction: LocalNotificationActionPerformed) => void`

返回值：

PluginListenerHandle

removeAllListeners()

removeAllListeners() => void

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

接口

LocalNotificationScheduleResult

LocalNotification

属性	类型	描述
`title`	`string`	通知标题
`body`	`string`	通知正文
`id`	`number`	通知 ID
`schedule`	`LocalNotificationSchedule`	调度设置
`sound`	`string`	带扩展名的音频文件名。在 iOS 上，文件应在应用包中。在 Android 上，文件应在 res/raw 文件夹中。在 Android 26+（Android O 及更新版本）上无效，推荐格式为 .wav，因为两个平台都支持。
`smallIcon`	`string`	仅限 Android：设置自定义状态栏图标。如果设置，将覆盖 capacitor.config.json 中的默认图标
`iconColor`	`string`	仅限 Android：设置通知图标的颜色
`attachments`	`LocalNotificationAttachment[]`	附件
`actionTypeId`	`string`	操作类型 ID
`extra`	`any`	额外数据
`threadIdentifier`	`string`	仅限 iOS：设置通知分组的线程标识符
`summaryArgument`	`string`	仅限 iOS 12+：设置通知分组的摘要参数
`group`	`string`	仅限 Android：设置通知分组的组标识符，类似于 iOS 上的 threadIdentifier。
`groupSummary`	`boolean`	仅限 Android：将此通知指定为组的摘要（应与 `group` 属性一起使用）。
`channelId`	`string`	仅限 Android：设置生成本地通知的通知通道。如果具有给定名称的通道不存在，则通知不会触发。如果未提供，将使用默认通道。
`ongoing`	`boolean`	仅限 Android：设置通知为持续通知。如果设置为 true，通知无法被滑走。
`autoCancel`	`boolean`	仅限 Android：设置在用户点击时自动移除通知

LocalNotificationSchedule

属性	类型
`at`	`Date`
`repeats`	`boolean`
`every`	`"year" \| "month" \| "two-weeks" \| "week" \| "day" \| "hour" \| "minute" \| "second"`
`count`	`number`
`on`	`{ year?: number; month?: number; day?: number; hour?: number; minute?: number; }`

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) => number	使用本地时间设置 Date 对象中的秒值。
setUTCSeconds	(sec: number, ms?: number) => number	使用协调世界时 (UTC) 设置 Date 对象中的秒值。
setMinutes	(min: number, sec?: number, ms?: number) => number	使用本地时间设置 Date 对象中的分钟值。
setUTCMinutes	(min: number, sec?: number, ms?: number) => number	使用协调世界时 (UTC) 设置 Date 对象中的分钟值。
setHours	(hours: number, min?: number, sec?: number, ms?: number) => number	使用本地时间设置 Date 对象中的小时值。
setUTCHours	(hours: number, min?: number, sec?: number, ms?: number) => number	使用协调世界时 (UTC) 设置 Date 对象中的小时值。
setDate	(date: number) => number	使用本地时间设置 Date 对象中的月份日期数值。
setUTCDate	(date: number) => number	使用协调世界时 (UTC) 设置 Date 对象中的月份日期。
setMonth	(month: number, date?: number) => number	使用本地时间设置 Date 对象中的月份值。
setUTCMonth	(month: number, date?: number) => number	使用协调世界时 (UTC) 设置 Date 对象中的月份值。
setFullYear	(year: number, month?: number, date?: number) => number	使用本地时间设置 Date 对象的年份。
setUTCFullYear	(year: number, month?: number, date?: number) => number	使用协调世界时 (UTC) 设置 Date 对象中的年份值。
toUTCString	() => string	返回使用协调世界时 (UTC) 转换的日期字符串。
toISOString	() => string	以 ISO 格式返回日期字符串值。
toJSON	(key?: any) => string	由 JSON.stringify 方法使用，以启用对象数据的 JavaScript 对象表示法 (JSON) 序列化转换。

LocalNotificationAttachment

属性	类型
`id`	`string`
`url`	`string`
`options`	`LocalNotificationAttachmentOptions`

LocalNotificationAttachmentOptions

属性	类型
`iosUNNotificationAttachmentOptionsTypeHintKey`	`string`
`iosUNNotificationAttachmentOptionsThumbnailHiddenKey`	`string`
`iosUNNotificationAttachmentOptionsThumbnailClippingRectKey`	`string`
`iosUNNotificationAttachmentOptionsThumbnailTimeKey`	`string`

LocalNotificationPendingList

属性	类型
`notifications`	`LocalNotificationRequest[]`

LocalNotificationRequest

属性	类型
`id`	`string`

LocalNotificationActionType

属性	类型
`id`	`string`
`actions`	`LocalNotificationAction[]`
`iosHiddenPreviewsBodyPlaceholder`	`string`
`iosCustomDismissAction`	`boolean`
`iosAllowInCarPlay`	`boolean`
`iosHiddenPreviewsShowTitle`	`boolean`
`iosHiddenPreviewsShowSubtitle`	`boolean`

LocalNotificationAction

属性	类型
`id`	`string`
`title`	`string`
`requiresAuthentication`	`boolean`
`foreground`	`boolean`
`destructive`	`boolean`
`input`	`boolean`
`inputButtonTitle`	`string`
`inputPlaceholder`	`string`

LocalNotificationEnabledResult

属性	类型	描述
`value`	`boolean`	设备是否启用了本地通知功能

NotificationChannel

属性	类型
`id`	`string`
`name`	`string`
`description`	`string`
`sound`	`string`
`importance`	`1 \| 2 \| 5 \| 4 \| 3`
`visibility`	`0 \| 1 \| -1`
`lights`	`boolean`
`lightColor`	`string`
`vibration`	`boolean`

NotificationChannelList

属性	类型
`channels`	`NotificationChannel[]`

NotificationPermissionResponse

属性	类型
`granted`	`boolean`

PluginListenerHandle

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

LocalNotificationActionPerformed

属性	类型
`actionId`	`string`
`inputValue`	`string`
`notification`	`LocalNotification`

示例​

本地通知配置（仅限 Android）​

API​

schedule(...)​

getPending()​

registerActionTypes(...)​

cancel(...)​

areEnabled()​

createChannel(...)​

deleteChannel(...)​

listChannels()​

requestPermission()​

addListener(...)​

addListener(...)​

removeAllListeners()​

接口​

LocalNotificationScheduleResult​

LocalNotification​

LocalNotificationSchedule​

Date​

LocalNotificationAttachment​

LocalNotificationAttachmentOptions​

LocalNotificationPendingList​

LocalNotificationRequest​

LocalNotificationActionType​

LocalNotificationAction​

LocalNotificationEnabledResult​

NotificationChannel​

NotificationChannelList​

NotificationPermissionResponse​

PluginListenerHandle​

LocalNotificationActionPerformed​

Contents

示例

本地通知配置（仅限 Android）

API

schedule(...)

getPending()

registerActionTypes(...)

cancel(...)

areEnabled()

createChannel(...)

deleteChannel(...)

listChannels()

requestPermission()

addListener(...)

addListener(...)

removeAllListeners()

接口

LocalNotificationScheduleResult

LocalNotification

LocalNotificationSchedule

Date

LocalNotificationAttachment

LocalNotificationAttachmentOptions

LocalNotificationPendingList

LocalNotificationRequest

LocalNotificationActionType

LocalNotificationAction

LocalNotificationEnabledResult

NotificationChannel

NotificationChannelList

NotificationPermissionResponse

PluginListenerHandle

LocalNotificationActionPerformed