更新记录

1.1.2（2026-06-21）

日常更新

1.1.1（2026-06-18）

1

1.1.0（2026-06-18）

• 富媒体通知：支持图片、大图标、大图样式、长文本展开
• 新增角标、声音、震动、静默等配置项

平台兼容性

uni-app(4.12)

uni-app x(4.12)

其他

gs-notification

UTS 状态栏本地通知插件，为 uni-app 项目提供跨平台的系统通知能力。支持 Android、iOS 与 H5（Web Notifications API），可在 App 状态栏或浏览器系统通知区域显示本地消息。

目录

• 功能特性
• 平台支持
• 环境要求
• 安装与集成
• 权限配置
• 快速开始
• API 参考
• 错误码说明
• 平台差异说明
• 完整示例
• 常见问题
• 目录结构
• 更新日志
• 相关文档

功能特性

平台支持

H5 浏览器兼容性（参考 package.json）

环境要求

• HBuilderX：^3.6.11（见 package.json → engines）
• Vue 版本：Vue 3
• App 端：需使用 自定义调试基座 或 云打包 后运行，标准基座不包含 UTS 插件
• Android targetSdkVersion：33（插件已声明 POST_NOTIFICATIONS 权限）
• iOS deploymentTarget：10

安装与集成

方式一：复制 uni_modules（推荐）

将 uni_modules/gs-notification 整个目录复制到你的 uni-app 项目根目录下。

方式二：插件市场

若已发布到 DCloud 插件市场，可在 HBuilderX 中通过 uni_modules 导入。

导入方式（注意平台差异）

App 端（Android / iOS）：

import {
  requestNotificationPermission,
  showNotification,
  cancelNotification,
  cancelAllNotifications
} from '@/uni_modules/gs-notification'

H5 端：

H5 实现位于 utssdk/web/index.js，需从 index.js 入口导入，并额外提供 getNotificationSupport：

import {
  showNotification,
  cancelNotification,
  cancelAllNotifications,
  getNotificationSupport
} from '@/uni_modules/gs-notification/index.js'

建议在页面中使用条件编译（#ifdef APP-PLUS / #ifdef H5）分别导入，参考本仓库 Demo：pages/index/index.vue。

权限配置

Android

插件已在 utssdk/app-android/AndroidManifest.xml 中声明：

<uses-permission android:name="android.permission.POST_NOTIFICATIONS" />

建议在项目 manifest.json → App 模块配置 → Android 权限 中同步勾选 POST_NOTIFICATIONS（Android 13+ 发送通知必需）。

运行时权限：

• Android 13（API 33）及以上：需调用 requestNotificationPermission() 动态申请
• Android 12 及以下：安装后默认可发通知，调用权限接口会直接返回 granted: true

iOS

无需在 Info.plist 额外声明权限键，但需在运行时调用 requestNotificationPermission()，用户同意后才能显示通知。

H5

浏览器 不会 通过本插件弹出权限请求框。用户需在浏览器地址栏 → 网站设置 → 通知 中手动选择「允许」。

安全上下文要求：

本地 H5 开发可在 manifest.json → Web 配置 → 开发服务器 中开启 HTTPS，然后访问 https://localhost:5173。

快速开始

// App 端示例
import {
  requestNotificationPermission,
  showNotification
} from '@/uni_modules/gs-notification'

// 1. 先请求权限（App 端必做；H5 请先手动在浏览器中允许通知）
requestNotificationPermission({
  success: (res) => {
    if (res.granted) {
      // 2. 发送通知
      showNotification({
        id: 1001,
        title: '新消息',
        content: '您有一条新消息',
        subTitle: '来自 UTS 插件',
        success: () => console.log('发送成功')
      })
    }
  },
  fail: (err) => {
    console.error(err.errCode, err.errMsg)
  }
})

API 参考

requestNotificationPermission

请求或检测通知权限。

App 端：Android 13+ 弹出系统授权对话框；iOS 弹出通知授权对话框；低版本 Android 直接返回已授权。

H5 端：仅检测 Notification.permission === 'granted'，不会弹出浏览器授权框；未授权时走 fail 回调。

requestNotificationPermission(options: {
  success?: (res: { errMsg: string; granted: boolean }) => void
  fail?: (err: UniError) => void
  complete?: (res: any) => void
}): void

success 返回值：

showNotification

发送一条本地通知。相同 id 会更新已有通知（H5 会先关闭旧实例再创建新通知）。

showNotification(options: {
  id?: number
  title: string
  content: string
  subTitle?: string
  payload?: any
  icon?: string          // 小图标 URL 或本地路径
  largeIcon?: string     // 大图标/头像（Android）
  image?: string         // 大图 URL 或本地路径
  bigText?: string       // 展开长文本（style=bigText）
  style?: 'default' | 'bigText' | 'bigPicture'
  badge?: number         // 角标，0 清除角标
  sound?: boolean        // 是否播放声音，默认 true
  vibrate?: boolean      // 是否震动（Android），默认 false
  silent?: boolean       // 静默通知
  success?: (res: { errMsg: string; id: number }) => void
  fail?: (err: UniError) => void
  complete?: (res: any) => void
}): void

富媒体示例：

showNotification({
  id: 1001,
  title: '订单已发货',
  content: '您的包裹正在派送中',
  style: 'bigPicture',
  icon: 'https://example.com/avatar.png',
  image: 'https://example.com/product.jpg',
  badge: 1,
  vibrate: true,
  payload: { orderId: '12345' }
})

图片路径说明：

• 支持 http:// / https:// 网络图片（自动异步下载）
• 支持 file:// 或应用内绝对路径
• 相对路径可通过 plus.io.convertLocalFileSystemURL 转换后传入

success 返回值：

cancelNotification

取消指定 ID 的通知。

cancelNotification(options: {
  id: number           // 要取消的通知 ID（必填）
  success?: (res: { errMsg: string }) => void
  fail?: (err: UniError) => void
  complete?: (res: any) => void
}): void

cancelAllNotifications

清除当前应用发出的全部通知。

cancelAllNotifications(options: {
  success?: (res: { errMsg: string }) => void
  fail?: (err: UniError) => void
  complete?: (res: any) => void
}): void

onNotificationClick / offNotificationClick

监听用户点击通知栏消息。建议在 App.vue 的 onLaunch 或页面 onShow 中注册，在 onUnload 中取消。

import { onNotificationClick, offNotificationClick } from '@/uni_modules/gs-notification'

const handleClick = (res) => {
  console.log('通知 ID', res.id)
  console.log('自定义数据', res.payload)
  // 可根据 res.payload 跳转页面
}

onNotificationClick(handleClick)

// 取消单个监听
offNotificationClick(handleClick)

// 取消全部监听
offNotificationClick()

回调参数 NotificationClickResult：

冷启动说明：App 被通知点击唤起时，若 JS 尚未注册监听，事件会暂存，在首次调用 onNotificationClick 后立即补发。

getNotificationSupport（仅 H5）

检测当前浏览器环境是否满足发送系统通知的条件，便于在页面上展示诊断信息。

import { getNotificationSupport } from '@/uni_modules/gs-notification/index.js'

const info = getNotificationSupport()
console.log(info)

返回值：

错误码说明

所有错误对象的 errSubject 均为 gs-notification。

App 端（Android / iOS）

H5 端

fail 回调示例：

fail: (err) => {
  // err.errSubject === 'gs-notification'
  // err.errCode === 1002
  // err.errMsg === '...'
}

平台差异说明

完整示例

以下示例演示 App 与 H5 的条件编译写法，与本仓库 Demo 一致：

<script>
// #ifdef H5
import {
  showNotification,
  cancelNotification,
  cancelAllNotifications,
  getNotificationSupport
} from '@/uni_modules/gs-notification/index.js'
// #endif

// #ifdef APP-PLUS
import {
  requestNotificationPermission,
  showNotification,
  cancelNotification,
  cancelAllNotifications
} from '@/uni_modules/gs-notification'
// #endif

export default {
  data() {
    return {
      notificationId: 1001
    }
  },
  methods: {
    async sendNotify() {
      // #ifdef APP-PLUS
      requestNotificationPermission({
        success: (res) => {
          if (res.granted) this.doShow()
        },
        fail: (err) => {
          uni.showToast({ title: err.errMsg, icon: 'none' })
        }
      })
      // #endif

      // #ifdef H5
      const support = getNotificationSupport()
      if (!support.canUse) {
        uni.showToast({ title: support.reason, icon: 'none', duration: 3000 })
        return
      }
      if (support.permission !== 'granted') {
        uni.showToast({
          title: '请在浏览器网站设置中允许通知',
          icon: 'none',
          duration: 3000
        })
        return
      }
      this.doShow()
      // #endif
    },

    doShow() {
      showNotification({
        id: this.notificationId,
        title: '新消息提醒',
        content: '您有一条来自 UTS 插件的状态栏通知',
        subTitle: 'gs-notification',
        success: () => {
          uni.showToast({ title: '通知已发送', icon: 'success' })
        },
        fail: (err) => {
          uni.showToast({ title: err.errMsg, icon: 'none' })
        }
      })
    },

    cancelOne() {
      cancelNotification({
        id: this.notificationId,
        success: () => uni.showToast({ title: '已取消', icon: 'none' })
      })
    },

    cancelAll() {
      cancelAllNotifications({
        success: () => uni.showToast({ title: '已全部清除', icon: 'none' })
      })
    }
  }
}
</script>

Demo 页面路径： pages/index/index.vue

常见问题

Q1：App 端运行时报「通知模块未加载」

UTS 插件未打入当前运行包。请 制作自定义调试基座 或 云打包 后，在真机上运行。

Q2：Android 云打包 Kotlin 编译失败

请确保使用 1.0.3+ 版本。旧版本存在 UTS → Kotlin 类型不匹配问题（grantResults 类型、PERMISSION_REQUEST_CODE 类型），已在 1.0.3 修复。

Q3：Android 13+ 发送通知失败（errCode 1002）

先调用 requestNotificationPermission()，并在 manifest.json 中确认已声明 POST_NOTIFICATIONS 权限。

Q4：H5 点击发送没有反应

按顺序排查：

1. 调用 getNotificationSupport() 查看 reason
2. 确认使用 HTTPS 或 http://localhost
3. 在浏览器 网站设置 → 通知 中选择「允许」
4. 确认从 index.js 导入（而非 App 端路径）

Q5：H5 在 Windows 上重复发送同 ID 通知无效

已在 1.0.2 修复：每次发送会使用带时间戳的唯一 tag，并先关闭同 ID 的旧通知实例。

Q6：iOS 收不到通知

• 确认已调用 requestNotificationPermission 且用户点击「允许」
• 确认 App 未被系统「专注模式」等限制
• 前台通知需 iOS 10+，本插件使用 UNUserNotificationCenter 即时触发（0.1s）

Q7：能否用于远程推送（FCM / APNs）？

本插件仅支持 本地通知（应用内主动触发），不包含远程推送能力。远程推送需配合 uniPush 或其他推送服务。

Q8：相同 id 有什么用？

id 是业务侧标识。再次调用 showNotification({ id: 1001, ... }) 会 更新 该条通知内容，而不是新增一条。取消时也用同一 id。

目录结构

uni_modules/gs-notification/
├── index.js                    # H5 入口， re-export web 实现
├── package.json                # 插件元信息
├── readme.md                   # 本文档
├── changelog.md                # 版本更新记录
└── utssdk/
    ├── interface.uts           # 跨平台 TypeScript 类型定义
    ├── unierror.uts            # App 端统一错误实现
    ├── app-android/
    │   ├── index.uts           # Android 实现
    │   ├── config.json         # minSdkVersion / targetSdkVersion
    │   └── AndroidManifest.xml # POST_NOTIFICATIONS 权限声明
    ├── app-ios/
    │   ├── index.uts           # iOS 实现
    │   └── config.json         # deploymentTarget
    └── web/
        └── index.js            # H5 实现（Web Notifications API）

更新日志

详见 changelog.md。

相关文档

• UTS 语法
• UTS 原生插件
• UTS Android 平台说明
• Web Notifications API（MDN）

许可证

本插件为开源 UTS 插件，可在 uni-app 项目中自由集成使用。