更新记录

1.0.0（2026-10-12） 下载此版本

• 首次发布。
• Android：基于 NotificationCompat + NotificationChannel + AlarmManager 实现通知渠道、权限申请、发送/取消通知、常驻通知、进度条通知、定时通知及点击/清除回调。
• iOS：基于 UserNotifications 实现权限申请、发送/取消通知、定时通知及点击/清除回调。
• Web：基于浏览器 Notification API 实现发送/取消/更新/定时通知与点击回调。
• 微信小程序：降级为应用内 toast。
• 统一错误码：9020001 ~ 9020007。

平台兼容性

uni-app(5.0)

uni-app x(5.0)

其他

hy-notification 本地通知

跨平台本地通知 UTS 插件，基于各端原生能力实现通知渠道、权限申请、常驻/进度条通知、定时通知与点击回调，同一套 API 适配 Android / iOS 原生，Web 与微信小程序降级。

平台支持

iOS 进度条为更新式（进度文本追加到内容），无系统原生进度条。 iOS 需在 macOS 环境下编译验证。

安装

将 hy-notification 目录放入项目的 uni_modules 下即可，无需手动注册（uni_modules 自动引入）。

使用

引入

import {
  initNotification,
  requestNotificationPermission,
  getNotificationPermission,
  createNotificationChannel,
  deleteNotificationChannel,
  sendNotification,
  updateNotificationProgress,
  cancelNotification,
  scheduleNotification,
  cancelScheduleNotification,
  onNotificationClick,
  offNotificationClick
} from '@/uni_modules/hy-notification'

初始化

initNotification({
  channel: {
    id: 'default',
    name: '默认通知',
    description: '应用默认通知渠道',
    importance: 'default'
  },
  requestPermission: true,
  success: (res) => {
    console.log('权限状态', res.granted, res.status)
  }
})

发送通知

sendNotification({
  id: 1001,
  title: '标题',
  content: '通知内容',
  channelId: 'default',
  payload: { page: 'detail', id: '123' },
  success: (res) => {
    console.log('已发送', res.id)
  },
  fail: (err) => {
    console.error('发送失败', err.errCode, err.errMsg)
  }
})

进度条通知

const id = 2001
sendNotification({ id, title: '下载中', progress: { max: 100, current: 0 } })

updateNotificationProgress({
  id,
  progress: { max: 100, current: 50 },
  title: '下载中',
  content: '已完成一半'
})

常驻通知

sendNotification({
  id: 3001,
  title: '正在运行',
  content: '后台服务运行中',
  ongoing: true,
  autoCancel: false
})

定时通知

scheduleNotification({
  id: 4001,
  title: '会议提醒',
  content: '5 分钟后开始',
  triggerAt: Date.now() + 5 * 60 * 1000,
  repeat: 'none'
})

// 取消
cancelScheduleNotification({ id: 4001 })

监听点击 / 清除

onNotificationClick((event) => {
  console.log('动作', event.action, '通知 id', event.id, '透传数据', event.payload)
})

// 取消监听
offNotificationClick()

API

initNotification(options)

初始化：创建 Android 通知渠道并（可选）申请通知权限。options 为必填（可为空对象 {}）。

requestNotificationPermission(options?)

申请通知权限。

• Android：申请 POST_NOTIFICATIONS（Android 13+）。
• iOS：调用系统授权弹窗。
• Web：调用 Notification.requestPermission()。
• 微信小程序：返回 status: 'unsupported'。

成功回调 res：{ granted: boolean, status: 'granted' | 'denied' | 'notDetermined' | 'unsupported' }

getNotificationPermission(options?)

查询当前权限状态，回调结构同上。

createNotificationChannel(options)

创建 Android 通知渠道（iOS / Web / 小程序为空实现或直接成功）。

deleteNotificationChannel(options)

删除 Android 通知渠道。

sendNotification(options)

发送通知。

进度对象：{ max: number, current: number, indeterminate?: boolean }

成功回调 res：{ id: number }

updateNotificationProgress(options)

更新进度通知（同 id 覆盖）。

cancelNotification(options?)

取消通知。不传 id 时清除全部。

scheduleNotification(options)

定时通知。

cancelScheduleNotification(options)

取消定时通知。{ id: number }

onNotificationClick(callback)

注册通知点击 / 清除监听，回调参数 NotificationClickEvent：

offNotificationClick()

移除点击 / 清除监听。

错误码

注意事项

• Android 13+ 需申请 POST_NOTIFICATIONS 权限，initNotification / requestNotificationPermission 会自动处理。
• Android 8.0+ 若发送时目标渠道不存在，插件会自动兜底创建该渠道，避免通知被系统静默丢弃。
• Android 精确闹钟（SCHEDULE_EXACT_ALARM）在部分机型需用户手动开启，否则定时可能不精确；未授权时插件自动降级为非精确闹钟。
• Android 定时通知在设备重启后会自动恢复（依赖 RECEIVE_BOOT_COMPLETED）。
• iOS 无通知渠道概念，createNotificationChannel / deleteNotificationChannel 直接成功。
• iOS 无原生进度条，进度以文本形式追加到通知内容中。
• iOS 用户主动清除通知触发的 dismiss 事件需注册通知分类才会回调，当前仅在点击通知时触发 click。
• iOS repeat 为 minute / hourly 时从设置时刻起按固定间隔重复，不使用 triggerAt。
• iOS 插件会设置 UNUserNotificationCenter 的 delegate，若与其它通知方案（如 uniPush）同时使用可能存在回调冲突。
• Web 通知依赖浏览器授权与页面存活，页面关闭后无法接收点击回调。
• 微信小程序不支持系统通知栏，sendNotification 等接口降级为应用内 toast，权限状态恒为 unsupported。

更新日志

见 changelog.md