更新记录

1.0.0（2026-09-17）

• 新增 Android、iOS、HarmonyOS 本地通知、长文本、图片和平台可用的进度展示。
• 新增通知点击、两个前台动作、分组、同 ID 更新、单条和范围清理。
• 新增系统托管的单次、每日、每周提醒；Android 和 iOS 支持间隔重复，提供任务查询、修改与取消。
• 新增能力与授权查询、双宿主演示和分模块接入文档，明确各平台的限制与文字替代方式。
• 首次接入需重新制作并安装 Android 自定义基座，并重新打包 iOS / HarmonyOS；各端实际能力以设备授权和系统条件为准。

平台兼容性

uni-app(5.24)

uni-app x(5.24)

lizhao-notify-pro

介绍

为 uni-app / uni-app x 提供 Android、iOS、HarmonyOS 原生本地通知与系统定时提醒，用统一 API 处理消息展示、业务点击、进度和任务管理。

适用于应用在设备上产生的提醒。远程推送、消息服务器和应用保活需要由业务另行接入。

功能特色

通知样式、调度精度和点击能力存在平台差异，详见后面的支持平台表。

适合哪些场景

下载与导入

将完整插件导入项目的 uni_modules，只从插件根目录引入 API：

import { showNotification } from '@/uni_modules/lizhao-notify-pro'

完整演示见 uni-app 示例 与 uni-app x 示例。点击接入还需将 App.vue 片段 或 App.uvue 片段 合并到现有 App 入口，保留其中的顶层静态 import；不要直接覆盖项目原有 App 文件。

5 分钟跑通：发送第一条通知

在按钮点击时申请授权，获得授权后再发送消息。success 表示系统受理，实际是否弹横幅、响铃由系统设置决定。

uni-app

<template><button @click="send">发送订单提醒</button></template>
<script>
import { requestNotificationPermission, showNotification } from '@/uni_modules/lizhao-notify-pro'
export default {
  methods: {
    send() {
      requestNotificationPermission({
        success: (permission) => {
          if (!permission.canPost) {
            uni.showToast({ title: '请在系统设置中允许通知', icon: 'none' })
            return
          }
          showNotification({
            id: 'order-001', title: '订单提醒', body: '订单已准备完成',
            success: (res) => { console.log('通知已受理：' + res.id) },
            fail: (err) => { console.log('发送失败：' + err.errCode + ' ' + err.errMsg) },
            complete: (res) => { console.log('操作完成：' + res.success) }
          })
        },
        fail: (err) => { console.log('授权失败：' + err.errMsg) }
      })
    }
  }
}
</script>

uni-app x

<template><button @click="send">发送订单提醒</button></template>
<script lang="uts">
import { requestNotificationPermission, showNotification, NotificationPermissionResult,
  NotificationSubmitResult, NotificationFail, NotificationCompleteResult } from '@/uni_modules/lizhao-notify-pro'
export default {
  methods: {
    send() {
      requestNotificationPermission({
        success: (permission: NotificationPermissionResult) => {
          if (!permission.canPost) {
            uni.showToast({ title: '请在系统设置中允许通知', icon: 'none' })
            return
          }
          showNotification({
            id: 'order-001', title: '订单提醒', body: '订单已准备完成',
            success: (res: NotificationSubmitResult) => { console.log('通知已受理：' + res.id) },
            fail: (err: NotificationFail) => { console.log('发送失败：' + err.errCode + ' ' + err.errMsg) },
            complete: (res: NotificationCompleteResult) => { console.log('操作完成：' + res.success) }
          })
        },
        fail: (err: NotificationFail) => { console.log('授权失败：' + err.errMsg) }
      })
    }
  }
}
</script>

核心配置

相同 id 的 showNotification 会重新提交该通知；updateNotification 只修改已有记录中传入的字段。更新时省略的字段保持原值，false、0、空正文和空动作数组会正常生效；传入 null 不表示清空。

接入方式选择

从基础到进阶：按业务模块使用

下面代码放在已接入插件的页面脚本中。完整页面示例包含成功、失败、完成回调和操作按钮。

模块一：发出一条业务通知

import { showNotification } from '@/uni_modules/lizhao-notify-pro'
showNotification({
  id: 'order-002', title: '订单已完成', body: '点击查看订单详情',
  payloadJson: '{"orderId":"002"}',
  success: (res) => { console.log('受理编号：' + res.id) },
  fail: (err) => { console.log('通知失败：' + err.errMsg) }
})

模块二：点击通知后打开业务

import { consumeInitialNotification, onNotificationClick, offNotificationClick,
  NotificationClickEvent } from '@/uni_modules/lizhao-notify-pro'

// 在页面或应用的业务路由已就绪后执行，并在所属页面销毁时执行 dispose。
const handleClick = (event: NotificationClickEvent) => {
  console.log('业务通知：' + event.notificationId + '，动作：' + event.actionId)
  console.log('业务数据：' + event.payloadJson)
  // 校验业务数据和登录状态后，再调用项目自己的导航逻辑。
}
consumeInitialNotification({
  success: (res) => { if (res.event != null) handleClick(res.event!) },
  fail: (err) => { console.log('读取启动通知失败：' + err.errMsg) }
})
const listenerId = onNotificationClick(handleClick)
const dispose = () => { offNotificationClick(listenerId) }

uni-app 普通 JS 脚本移除 NotificationClickEvent 类型导入、参数类型和非空断言即可。consumeInitialNotification 最多返回一个待消费启动事件，没有事件时为 null；实时监听和启动消费共用去重，不要把同一事件再次手动派发。onNotificationClick 返回空字符串表示当前未能建立监听，可在应用前台重试。

动作回调只在应用获得执行机会后触发，不提供应用退出状态下执行任意 JS 的能力。业务导航、登录等待和可靠业务处理由应用管理；可用 eventId 做业务去重。HarmonyOS 即时通知的每次投递入口只消费一次，更新通知会建立新的点击入口；系统代理提醒只负责返回应用，不产生可依赖的业务点击事件，请用应用首页提供相关业务入口。

模块三：显示长消息或图片

import { showNotification } from '@/uni_modules/lizhao-notify-pro'
showNotification({
  id: 'journey', title: '行程安排', body: '展开查看详情', style: 'big-text',
  bigText: '明天 09:00 出发。请提前准备好证件，抵达后到服务台签到。',
  fail: (err) => { console.log('长文本通知失败：' + err.errMsg) }
})
uni.chooseImage({ count: 1, success: (selection) => {
  if (selection.tempFilePaths.length == 0) return
  showNotification({
    id: 'picture', title: '图片提醒', body: '展开查看图片',
    style: 'big-picture', imagePath: selection.tempFilePaths[0], fallback: 'text',
    success: (res) => { console.log('实际样式：' + res.effectiveStyle + '，' + res.warnings.join('；')) },
    fail: (err) => { console.log('图片通知失败：' + err.errMsg) }
  })
} })

只接收应用可读取的本地图片，插件不下载网络图片。定时图片应使用持久可读路径；临时文件和临时授权可能在提醒触发前失效。iOS 使用系统附件，Android/HarmonyOS 的展开方式由系统通知界面决定。

模块四：跟随任务更新进度

以下适合 Android。先创建通知，再更新相同 ID，省略的标题和业务数据保持不变。

import { showNotification, updateNotification } from '@/uni_modules/lizhao-notify-pro'
showNotification({
  id: 'download-001', title: '文件下载', body: '下载中', style: 'progress',
  progress: { current: 0, total: 100 }, ongoing: true, autoCancel: false,
  silent: true, android: { onlyAlertOnce: true },
  success: () => {
    updateNotification({
      id: 'download-001', progress: { current: 50, total: 100 },
      fail: (err) => { console.log('更新进度失败：' + err.errMsg) }
    })
  },
  fail: (err) => { console.log('创建进度通知失败：' + err.errMsg) }
})
// 真实业务完成后再调用：
// updateNotification({ id: 'download-001', body: '下载完成',
//   progress: { current: 100, total: 100 }, ongoing: false, autoCancel: true })

iOS 没有此类原生进度条；可设置 fallback: 'text'，省略 ongoing 和 autoCancel: false，将进度作为文字显示。更新已显示通知必须传 replaceDelivered: true，返回 reposted，不适合高频进度刷新。HarmonyOS 先查询进度能力，模板不可用时可明确选择文字替代。

模块五：安排一次预约提醒

import { scheduleNotification } from '@/uni_modules/lizhao-notify-pro'
scheduleNotification({
  id: 'appointment', title: '预约提醒', body: '预约将在十分钟后开始',
  trigger: { type: 'once', at: Date.now() + 10 * 60 * 1000 },
  success: (res) => { console.log('已安排：' + res.id + '，实际精度：' + res.precision) },
  fail: (err) => { console.log('安排失败：' + err.errCode + ' ' + err.errMsg) }
})

at 为未来的毫秒时间戳。默认不请求精确闹钟。仅 Android 可设置 exact: true；授权不足时默认失败，允许延迟时再设置 allowInexactFallback: true 并检查 precision、warnings。HarmonyOS 系统提醒需应用具备对应的代理提醒权限和权益，不支持动作和业务点击透传；请省略 actions / payloadJson。

模块六：每天或每周提醒

import { scheduleNotification, updateScheduledNotification, getScheduledNotifications,
  cancelScheduledNotification } from '@/uni_modules/lizhao-notify-pro'
scheduleNotification({
  id: 'weekly-plan', title: '每周安排', body: '查看今天的事项',
  trigger: { type: 'weekly', hour: 9, minute: 0, weekdays: [1, 3, 5] },
  fail: (err) => { console.log('每周提醒失败：' + err.errMsg) }
})
// 改为每天 08:30，保留原内容：
// updateScheduledNotification({ id: 'weekly-plan', trigger: { type: 'daily', hour: 8, minute: 30 } })
// getScheduledNotifications({ success: (res) => { console.log('任务列表：' + JSON.stringify(res.items)) } })
// cancelScheduledNotification({ id: 'weekly-plan' })

每日和每周按设备当地时间计算；星期 1 表示周一，7 表示周日。Android / iOS 还支持 { type: 'interval', intervalSeconds: 60 }，间隔至少 60 秒，iOS 最大 31536000 秒。firstAt 只适用于 Android。跨时区、夏令时、节电、专注模式及系统配额都可能影响实际送达。

模块七：分类、动作和清理

import { showNotification, cancelNotification, cancelAllNotifications } from '@/uni_modules/lizhao-notify-pro'
showNotification({
  id: 'order-actions', title: '订单待处理', body: '选择要打开的页面',
  group: { id: 'orders' }, payloadJson: '{"orderId":"003"}',
  actions: [
    { id: 'details', title: '查看详情', payloadJson: '{"page":"detail","orderId":"003"}' },
    { id: 'list', title: '订单列表', payloadJson: '{"page":"list"}' }
  ],
  fail: (err) => { console.log('交互通知失败：' + err.errMsg) }
})
// cancelNotification({ id: 'order-actions' })
// cancelAllNotifications({ scope: 'delivered' }) // 只清理已显示通知
// cancelAllNotifications({ scope: 'scheduled' }) // 只取消定时任务
// cancelAllNotifications({ scope: 'all' }) // 两类都清理

最多两个前台动作，点击后回调包含独立 actionId 和该动作的 payloadJson；省略动作数据时为 '{}'。分组只影响系统归类，不保证折叠外观。批量清理只处理本插件登记的通知与任务。

Android 可先创建业务渠道，再通过 android.channelId 使用：

import { createNotificationChannel, showNotification } from '@/uni_modules/lizhao-notify-pro'
createNotificationChannel({
  channelId: 'orders', channelName: '订单提醒', importance: 'high',
  success: () => {
    showNotification({ title: '订单更新', body: '有一条新进展', android: { channelId: 'orders' } })
  },
  fail: (err) => { console.log('创建渠道失败：' + err.errMsg) }
})

Android 8 及以上的渠道重要性、声音等首次建立后受系统和使用者管理，重复创建无法强制重置设置。其他平台调用渠道 API 返回不支持。

模块八：按设备能力选择体验

import { getNotificationCapabilities, getNotificationPermission,
  openNotificationSettings } from '@/uni_modules/lizhao-notify-pro'
getNotificationCapabilities({
  success: (res) => {
    console.log('进度能力：' + res.capabilities.progress.state)
    console.log('进度能力说明：' + res.capabilities.progress.reason)
    console.log('定时点击透传：' + res.capabilities.scheduledClickPayload.state)
  },
  fail: (err) => { console.log('能力查询失败：' + err.errMsg) }
})
getNotificationPermission({
  success: (res) => { console.log('可展示：' + res.canPost + '，可调度：' + res.canSchedule) }
})
// 用户选择去设置时再调用：
// openNotificationSettings({ section: 'notification' })
// Android 精确定时：openNotificationSettings({ section: 'exact-alarm' })

能力为 supported / unsupported / unknown，能力支持不等于已经取得授权；unknown 时先按不依赖该能力的方式展示，并处理实际调用的失败结果。

API 用途速查

参数说明

样式与交互

平台专用设置

平台专用块只在对应平台执行，不能通过其他平台字段扩展当前端的能力。

定时规则与管理

修改已有任务至少传一个内容或调度字段。scheduleNotification 同 ID 重新提交与 updateScheduledNotification 的区别是：前者完整定义任务，后者保留省略的原有字段且要求记录存在。

授权、设置与渠道

回调说明

异步 API 接收 success / fail / complete。一次调用最终只进入一个成功或失败分支，随后调用 complete；complete 为统一结果 { operation, success, notificationId, errCode?, errMsg }。页面回调抛出异常不会再次触发成功或失败分支。

onNotificationClick(callback) 是持续监听，返回 listenerId；offNotificationClick(listenerId) 仅移除该监听并返回是否移除，页面销毁时必须执行。多个订阅者各自接收事件，不要在每次页面 onShow 重复注册。

支持平台

适用宿主为 uni-app 和 uni-app x；Web、小程序不提供系统通知实现，调用相关操作返回 9082004。通知展示需系统授权；Android 精确定时和 HarmonyOS 代理提醒还需满足各自的系统前提。

返回值说明

deliveryEffect 区分 posted（提交展示）、reposted（重新投递）、updated（更新）、cancelled（取消）和 unchanged（没有变化）。定时 state 为 submitting / scheduled / expired / cancelled / invalid / unknown；precision 为 exact / inexact / system-calendar / unknown。

查询里的 nextTriggerAt 为预计下次毫秒时间戳，无法确认时可为 0。Android 无法可靠查询系统闹钟是否仍存在，因此 systemConfirmed: false 不代表任务必然丢失；应用内登记也不代表系统保证送达。iOS 每周多个星期会占用多个系统待触发请求，配额与应用其他通知共享。

limits 包含动作数、payload 字节、图片字节、点击缓存数、最小重复间隔和任务上限。以当前设备查询结果及实际调用为准，超过配额通过失败回调返回。

错误码说明

失败对象统一包含 errSubject / errCode / errMsg / operation / platform / nativeCode / recoverable / notificationId / details。recoverable 只提示处理条件后可以重试，不代表应当立即循环重试。

注意事项

1. 使用包含本插件原生代码的安装包；首次接入或原生代码更新后，应重新制作并安装 Android 自定义基座，并重新打包 iOS / HarmonyOS。
2. 应用必须拥有发送通知所需的系统授权。勿扰、专注、静音、渠道设置和厂商省电策略都可能影响声音、横幅和时间，插件不保证绕过系统设置。
3. 系统定时任务无需页面定时器，但强制停止、卸载、数据清除或系统限制可能使任务失效。Android 恢复时只安排未来任务，已经错过的单次提醒不补发，重复任务跳到下一次。重新进入应用后可查询并按业务规则重新安排。
4. cancelNotification 处理已显示通知，cancelScheduledNotification 停止未来提醒；如果两者都需要清理，分别取消或使用 scope: 'all'。HarmonyOS 的已显示代理提醒由系统管理，清理已显示范围只处理插件的即时通知；停止未来提醒使用调度取消 API。
5. 只传本地可读图片，较大图片建议先压缩。Android 使用小图标资源时应提供适合状态栏的单色图形。不要把业务敏感信息直接放进锁屏通知、payload 或页面日志。
6. 插件只在设备本地保存通知管理和点击所需数据，不向作者服务器发送内容。应用开发者仍需在自身隐私政策中说明实际业务的数据使用方式。

第三方依赖说明见 THIRD_PARTY_NOTICES.md。

联系方式

信-微：l-z-1-8-7-1512-5421（-去掉，不这样写会被和谐）

作者系列 UTS 插件

以下为已在 DCloud 插件市场上架的作者系列 UTS 插件，可按业务场景组合使用。未列出的插件表示当前未确认公开市场页，后续上架后再补充。