更新记录

1.0.1（2026-07-15）

修复与优化

• 优化 Web 端通知弹层位置、进入/退出动画和多通知堆叠策略。
• 增强 Android 定时/重复通知：支持后台触发、自重排、精确定时、后续文案更新和声音/震动恢复。
• 优化 Android 通知提醒配置：声音、震动、静默和高优先级场景自动派生渠道，降低旧渠道配置不生效的问题。
• 同步 iOS、HarmonyOS、Web 对 Android 通知参数的接口承接，补齐 iconPath、showWhen、color、exact 等字段的降级处理。
• 新增 Android 消息横幅验证示例，并同步 uni-app / uni-app x 示例入口。
• 同步 Android 权限与示例配置，补充 POST_NOTIFICATIONS、SCHEDULE_EXACT_ALARM、WAKE_LOCK 等后台提醒相关声明。

1.0.0（2026-07-01）

新增

• 跨平台通知栏 UTS 插件：Android、iOS、HarmonyOS 三端统一公开 API。
• 通知权限申请、普通/大文本/大图/进度通知，以及更新、完成、取消。
• 点击回调（onNotificationClick）、打开指定页面、定时/重复通知、通知分组。
• 动作按钮、静默通知、自动消失、自定义声音与震动节奏等样式参数。
• Android 动作按钮兼容 UTSArray 桥接解析，带动作按钮的通知自动使用展开样式。
• Android 声音/震动按 soundPath、vibratePattern、silent 自动派生渠道，发送后主动提醒兜底。
• Android、iOS、HarmonyOS 原生实现与 UTS 类型定义。
• uni-app / uni-app x 双端示例页（含分组、样式、点击等 11 个场景）与使用文档（三端能力矩阵、自定义基座说明）。

平台兼容性

uni-app(5.06)

uni-app x(5.06)

xview-notification

跨平台通知栏提示 UTS 插件，Android、iOS、HarmonyOS 使用系统通知能力，Web 使用当前页面 DOM 弹层；四端保持同一套公开 API，支持普通通知、大文本通知、进度通知、点击回调、定时/重复通知、大图通知、通知分组、通知更新和取消。不同系统的通知能力不完全一致，部分能力会在 iOS、HarmonyOS 或 Web 上按平台规则降级。

权限

Android 已在 AndroidManifest 中声明：

• android.permission.POST_NOTIFICATIONS
• android.permission.VIBRATE
• android.permission.SCHEDULE_EXACT_ALARM
• android.permission.WAKE_LOCK

使用示例

import {
  requestNotificationPermission,
  sendSimpleNotification,
  sendNotification,
  sendProgressNotification,
  scheduleNotification,
  sendRepeatingNotification,
  isExactAlarmEnabled,
  onNotificationClick,
  updateScheduledNotification,
  updateProgress,
  completeProgress,
  cancelAllNotifications
} from '@/uni_modules/xview-notification'

onNotificationClick((event) => {
  console.log('notification click', event.id, event.type, event.target, event.actionId)
  // open-page 需在 App 层自行跳转，插件内不调用 uni.navigateTo
  if (event.type === 'open-page' && event.target) {
    uni.navigateTo({ url: event.target })
  }
})

requestNotificationPermission(
  () => {
    const id = sendSimpleNotification('标题', '通知内容')
    console.log('notification id', id)
  },
  () => {
    console.log('通知权限未开启')
  }
)

const bigId = sendNotification({
  channelId: 'xview_big_text',
  channelName: '大文本通知',
  title: '任务完成',
  content: '展开查看详情',
  bigText: '这里是更长的通知内容。',
  priority: 'high',
  vibrate: true
})

const progressId = sendProgressNotification('处理中', '当前进度 10%', 10, 100)
updateProgress(progressId, 60, 100)
completeProgress(progressId)

scheduleNotification({
  title: '定时提醒',
  content: '5 秒后触发',
  delay: 5000
})

const repeatId = sendRepeatingNotification({
  title: '重复提醒',
  content: '每分钟触发一次',
  repeatInterval: 60 * 1000
})
updateScheduledNotification(repeatId, {
  title: '重复提醒已更新',
  content: '后续触发使用新的标题和正文'
})

if (!isExactAlarmEnabled()) {
  console.log('请在系统设置中手动开启闹钟和提醒权限')
}

scheduleNotification({
  title: '后台准时提醒',
  content: 'Android 12+ 需先开启闹钟和提醒权限',
  delay: 10 * 1000,
  exact: true,
  soundPath: 'default',
  vibrate: true
})

cancelAllNotifications()

大图标与固定 ID

sendSimpleNotification('标题', '带大图标的通知', '/static/logo.png')

sendNotification({
  id: 9001,
  title: '固定 ID 通知',
  content: '再次发送会覆盖同 ID 通知',
  iconPath: '/static/logo.png'
})

cancelNotification(9001)

样式与行为参数

sendNotification({
  title: '样式示例',
  content: '副标题 + 强调色 + 仅提醒一次',
  subText: '业务分类',
  bigTitle: '展开后的大标题',
  color: 0xff0ea5e9,
  showWhen: true,
  onlyAlertOnce: true,
  priority: 'high',
  ongoing: true,
  autoCancel: false
})

sendNotification({
  title: '静默通知',
  content: '不响铃、不震动',
  silent: true
})

sendNotification({
  title: '自动消失',
  content: '5 秒后自动取消',
  timeoutAfter: 5000
})

sendNotification({
  title: '默认提示音',
  content: '使用系统默认通知提示音',
  soundPath: 'default'
})

sendNotification({
  title: '自定义震动',
  content: 'Android 支持自定义震动节奏',
  vibrate: true,
  vibratePattern: [0, 180, 80, 260, 80, 360]
})

Android 消息横幅通知

scheduleNotification({
  channelId: 'xview_heads_up_message',
  channelName: '消息横幅通知',
  title: '开发资料群',
  content: '[1条] 码小趣：后台横幅通知测试',
  priority: 'high',
  soundPath: 'default',
  vibrate: true,
  type: 'open-page',
  target: '/pages/demo/open-page',
  autoCancel: true,
  delay: 5000,
  exact: true
})

验证桌面或其他 App 上方横幅时，不要点击后再切后台。应先安排 5 秒后发送，然后立即按 Home 或切到其他 App，让系统在后台触发通知发布。

Android 顶部横幅由系统通知渠道、通知权限、声音/震动、勿扰模式和厂商 ROM 策略共同决定。本插件在 Android 8.0+ 会将 priority: 'high' 或 priority: 'max' 的非静默通知创建为高重要性渠道，并为 xview_heads_up_message 场景设置消息通知类别；但用户关闭 App 通知、关闭该渠道横幅、进入勿扰模式或厂商系统限制后台提醒时，系统仍可能只进入通知栏或不展示横幅。

如果某个 channelId 已经在设备上被创建为普通重要性，Android 不允许应用静默改高。调试时请更换新的 channelId、清除应用数据、卸载重装，或进入系统通知设置手动打开该渠道的横幅/悬浮通知。

点击行为 type

// 仅拉起应用（默认）
sendNotification({ title: '打开应用', content: '点击后回到前台', type: 'open-app' })

// 拉起应用并跳转页面，target 为页面路径
sendNotification({
  title: '打开页面',
  content: '点击后跳转到业务页',
  type: 'open-page',
  target: '/pages/index/index'
})

// 点击后通过 onNotificationClick 回调 target 字符串
sendNotification({
  title: '点击回调',
  content: '在 callback 中处理业务逻辑',
  type: 'open-callback',
  target: 'order:10086'
})

// 动作按钮会通过 onNotificationClick 回传 actionId
sendNotification({
  title: '订单待处理',
  content: '在通知上直接处理',
  type: 'open-callback',
  target: 'order:10086',
  actions: [
    { id: 'view', title: '查看', type: 'open-page', target: '/pages/demo/open-page' },
    { id: 'confirm', title: '确认', type: 'open-callback', target: 'order:10086:confirm' }
  ]
})

不确定进度

const id = sendProgressNotification('同步中', '正在处理...', 0, 100, true)
updateProgress(id, 50, 100)
completeProgress(id)

定时 triggerAt 与 repeatType

// 指定绝对触发时间（毫秒时间戳）
scheduleNotification({
  title: '预约提醒',
  content: '在指定时间点触发',
  triggerAt: Date.now() + 10 * 1000
})

// 使用 repeatType 快捷周期（minute/hour/day/week）
sendRepeatingNotification({
  title: '每小时提醒',
  content: 'repeatType 示例',
  delay: 3000,
  repeatType: 'hour'
})

cancelScheduledNotification(scheduledId)

updateNotification

updateNotification(progressId, {
  title: '下载完成',
  content: '文件已保存',
  bigText: '点击查看详情',
  progressCurrent: 100,
  progressMax: 100
})

updateScheduledNotification

const repeatId = sendRepeatingNotification({
  title: '库存提醒',
  content: '库存状态待刷新',
  delay: 3000,
  repeatInterval: 60 * 1000
})

updateScheduledNotification(repeatId, {
  title: '库存提醒已更新',
  content: 'A 商品库存低于安全线'
})

示例工程

多端能力对齐

HarmonyOS 当前实现以 API 对齐和基础文本通知为主，动作按钮、分组样式、大图、点击 payload、定时/重复通知均按系统能力降级；需要强交互通知时优先以 Android/iOS 真机能力为准。

API

options

updateScheduledNotification options

updateScheduledNotification 只更新后续触发文案，不修改 channelId、声音、震动、点击行为、分组、动作按钮或精确定时策略。传入无效 ID、任务已取消、或 title/content 都未传时返回 false。