更新记录

1.0.0（2026-08-02）

● ## sh_NotificationManagement v1.0.0 发布日志

平台：Android（最低 API 21）

权限管理

• 检查/跳转通知监听权限

• 检查/跳转悬浮窗权限

  通知监听

• 开启/停止监听 Android 通知栏新消息
• 实时回调：包名、标题、内容

• 查询监听状态

  清除通知

• 按包名清除指定应用所有通知
• 按关键词清除匹配通知（忽略大小写）

• 清除通知栏全部通知

  悬浮窗胶囊（灵动岛风格）

• 显示/隐藏悬浮窗胶囊，淡入淡出动画
• 点击胶囊展开面板，点击外部或 5 秒自动收起
• 自由拖动胶囊，不会超出屏幕
• 拖到屏幕边缘 3 秒自动缩成圆点
• 短按圆点恢复胶囊，长按圆点展开面板
• 胶囊宽度随内容自适应，始终保持居中
• 面板内置"开启/停止监听"开关按钮
• 面板内置"打开应用"按钮

• 更新胶囊状态文本和通知数量

  回调

• 面板开关按钮回调（全局共享，跨页面可用）

  自定义

• 自定义面板标题/副标题，支持恢复默认

平台兼容性

uni-app x(5.15)

Sh-NoticeMgmt 插件使用

Android通知管理插件，支持通知栏消息监听、清除通知、悬浮窗胶囊。

平台支持：仅 Android（最低 API 21）

一、功能概述

二、使用方法

import { NotificationManager } from '@/uni_modules/Sh-NoticeMgmt'
const sh_Not = new NotificationManager()

所有 API 通过 sh_Not 实例调用，多个实例共享同一底层 Service。

三、使用示例

完整示例 uniappx

// #ifdef APP-ANDROID
    import { NotificationManager } from '@/uni_modules/Sh-NoticeMgmt'
    var sh_Notif = new NotificationManager()

    const notifPerm = ref(false)
    const overlayPerm = ref(false)
    const listening = ref(false)
    const notifLogs = ref({} as UTSJSONObject)
    const clearPkg = ref('')
    const clearKeyword = ref('')
    const floatingShowing = ref(false)
    const toggleLogs = ref([] as Array<UTSJSONObject>)
    const panelTitle = ref('')
    const panelSubtitle = ref('')

    const click = (id : number) => {
        if (id == 0) {
            notifPerm.value = sh_Notif.isNotificationPermissionEnabled() as boolean
            uni.showToast({ title: notifPerm.value ? '已开启' : '未开启', icon: 'none', position: 'bottom' })
        } else if (id == 1) {
            sh_Notif.openNotificationPermissionSettings()
        } else if (id == 2) {
            overlayPerm.value = sh_Notif.isOverlayPermissionEnabled() as boolean
            uni.showToast({ title: overlayPerm.value ? '已开启' : '未开启', icon: 'none', position: 'bottom' })
        } else if (id == 3) {
            sh_Notif.requestOverlayPermission()
        } else if (id == 4) {
            if (!sh_Notif.isNotificationPermissionEnabled()) {
                uni.showToast({ title: '请先开启通知权限', icon: 'none', position: 'bottom' })
                return
            }
            listening.value = true
            sh_Notif.startListening((pkg : string, title : string, msg : string) => {
                notifLogs.value = { pkg, title, msg }
            })
            uni.showToast({ title: '监听已开启', position: 'bottom' })
        } else if (id == 5) {
            listening.value = false
            sh_Notif.stopListening()
            uni.showToast({ title: '监听已停止', position: 'bottom' })
        } else if (id == 6) {
            const pkg = clearPkg.value as string
            if (pkg == '') {
                uni.showToast({ title: '请输入包名', icon: 'none', position: 'bottom' })
                return
            }
            sh_Notif.cancelPackageNotifications(pkg)
            uni.showToast({ title: `已清除: ${pkg}`, position: 'bottom' })
        } else if (id == 7) {
            const kw = clearKeyword.value as string
            if (kw == '') {
                uni.showToast({ title: '请输入关键词', icon: 'none', position: 'bottom' })
                return
            }
            const pkg = clearPkg.value as string
            sh_Notif.cancelByKeyword(kw, pkg != '' ? pkg : null)
            uni.showToast({ title: `已清除关键词: ${kw}`, position: 'bottom' })
        } else if (id == 8) {
            sh_Notif.cancelAllNotifications()
            uni.showToast({ title: '已清除所有通知', position: 'bottom' })
        } else if (id == 9) {
            if (!sh_Notif.isOverlayPermissionEnabled()) {
                uni.showToast({ title: '请先开启悬浮窗权限', icon: 'none', position: 'bottom' })
                return
            }
            floatingShowing.value = true
            sh_Notif.showFloatingWindow(listening.value as boolean, 0)
            sh_Notif.setFloatingToggleCallback((enabled : boolean) => {
                const now = new Date()
                const time = `${now.getHours().toString().padStart(2, '0')}:${now.getMinutes().toString().padStart(2, '0')}:${now.getSeconds().toString().padStart(2, '0')}`
                const newLogs = (toggleLogs.value as Array<UTSJSONObject>).slice()
                newLogs.unshift({ enabled: enabled, time: time } as UTSJSONObject)
                toggleLogs.value = newLogs.slice(0, 20)
                if (enabled) {
                    if (!sh_Notif.isNotificationPermissionEnabled()) {
                        uni.showToast({ title: '请先开启通知权限', icon: 'none', position: 'bottom' })
                        return
                    }
                    listening.value = true
                    sh_Notif.startListening((pkg : string, title : string, msg : string) => {
                        notifLogs.value = { pkg, title, msg }
                    })
                    uni.showToast({ title: '监听已开启', position: 'bottom' })
                    sh_Notif.updateFloatingWindow(listening.value as boolean, 0)
                } else if (!enabled && listening.value) {
                    listening.value = false
                    sh_Notif.stopListening()
                    uni.showToast({ title: '监听已停止', position: 'bottom' })
                    sh_Notif.updateFloatingWindow(listening.value as boolean, 0)
                }
            })
            setTimeout(() => {
                floatingShowing.value = sh_Notif.isFloatingWindowShowing() as boolean
                uni.showToast({ title: floatingShowing.value ? '已显示' : '未显示', icon: 'none', position: 'bottom' })
            }, 500)
        } else if (id == 10) {
            sh_Notif.hideFloatingWindow()
            setTimeout(() => {
                floatingShowing.value = sh_Notif.isFloatingWindowShowing() as boolean
                uni.showToast({ title: floatingShowing.value ? '已显示' : '已隐藏', icon: 'none', position: 'bottom' })
            }, 500)
        } else if (id == 11) {
            sh_Notif.updateFloatingWindow(listening.value as boolean, 66)
            uni.showToast({ title: '胶囊已更新', position: 'bottom' })
        } else if (id == 12) {
            floatingShowing.value = sh_Notif.isFloatingWindowShowing() as boolean
            uni.showToast({ title: floatingShowing.value ? '已显示' : '未显示', icon: 'none', position: 'bottom' })
        } else if (id == 13) {
            const title = panelTitle.value as string
            const subtitle = panelSubtitle.value as string
            sh_Notif.setPanelTexts(title != '' ? title : null, subtitle != '' ? subtitle : null)
            sh_Notif.updateFloatingWindow(listening.value as boolean, 99)
            uni.showToast({ title: '文本已应用', position: 'bottom' })
        } else if (id == 14) {
            panelTitle.value = ''
            panelSubtitle.value = ''
            sh_Notif.setPanelTexts(null, null)
            sh_Notif.updateFloatingWindow(listening.value as boolean, 99)
            uni.showToast({ title: '已恢复默认', position: 'bottom' })
        }
    }

    onShow(() => {
        click(0);
        click(2);
    })

    onMounted(() => {
        click(0);
        click(2);
    })

    onUnmounted(() => {
        if (listening.value) { sh_Notif.stopListening() }
        if (floatingShowing.value) { sh_Notif.hideFloatingWindow() }
    })
    // #endif

清除通知示例

// 清除微信所有通知
sh_Not.cancelPackageNotifications('com.tencent.mm')

// 清除所有含"到账"的通知
sh_Not.cancelByKeyword('到账')

// 只清除微信中含"收款"的通知
sh_Not.cancelByKeyword('收款', 'com.tencent.mm')

// 清除所有通知
sh_Not.cancelAllNotifications()

跨页面回调示例

// ===== app.uvue 中显示悬浮窗 =====
const nmA = new NotificationManager()
nmA.showFloatingWindow(true, 0)

// ===== index.uvue 中设置回调，全局生效 =====
const nmB = new NotificationManager()
nmB.setFloatingToggleCallback((enabled: boolean) => {
    if (enabled) {
        nmB.startListening((pkg, title, msg) => {
            console.log(`[${pkg}] ${title}: ${msg}`)
        })
    } else {
        nmB.stopListening()
    }
})

四、API 参考

权限检查与申请

// 检查通知监听权限
if (!sh_Not.isNotificationPermissionEnabled()) {
    sh_Not.openNotificationPermissionSettings()
}

// 检查悬浮窗权限
if (!sh_Not.isOverlayPermissionEnabled()) {
    sh_Not.requestOverlayPermission()
}

通知监听

// 开启监听
sh_Not.startListening((pkg: string, title: string, msg: string) => {
    console.log(`包名: ${pkg}`)
    console.log(`标题: ${title}`)
    console.log(`内容: ${msg}`)
})

// 停止监听
sh_Not.stopListening()

// 查询状态
const status = sh_Not.getListeningStatus()

清除通知

// 清除指定包名
sh_Not.cancelPackageNotifications('com.tencent.mm')
sh_Not.cancelPackageNotifications('com.eg.android.AlipayGphone')

// 清除关键词匹配（忽略大小写）
sh_Not.cancelByKeyword('到账')
sh_Not.cancelByKeyword('收款', 'com.tencent.mm')

// 清除所有
sh_Not.cancelAllNotifications()

悬浮窗胶囊

// 显示胶囊
sh_Not.showFloatingWindow(true, 0)

// 更新胶囊（收到通知后）
sh_Not.updateFloatingWindow(true, 5)

// 查询状态
const showing = sh_Not.isFloatingWindowShowing()

// 隐藏胶囊
sh_Not.hideFloatingWindow()

回调设置

sh_Not.setFloatingToggleCallback((enabled: boolean) => {
    if (enabled) {
        sh_Not.startListening((pkg, title, msg) => {
            console.log(`新通知: ${title}`)
        })
    } else {
        sh_Not.stopListening()
    }
})

自定义面板文本

// 自定义
sh_Not.setPanelTexts('我的监听面板', '已监听 3 条消息')

// 只改标题
sh_Not.setPanelTexts('支付通知监听中', null)

// 恢复默认
sh_Not.setPanelTexts(null, null)

五、悬浮窗交互说明

权限声明

[
    "<uses-permission android:name=\"android.permission.SYSTEM_ALERT_WINDOW\" />",
    "<uses-permission android:name=\"android.permission.BIND_NOTIFICATION_LISTENER_SERVICE\" tools:ignore=\"ProtectedPermissions\" />",
    "<uses-permission android:name=\"android.permission.POST_NOTIFICATIONS\"/>"
]

注意事项

1. 通知监听权限需要用户在系统设置中手动授权，无法通过代码自动开启
2. 悬浮窗权限同样需要用户手动授权
3. 悬浮窗使用 TYPE_APPLICATION_OVERLAY，显示在状态栏下方
4. 监听仅获取新到达的通知，不会推送历史通知
5. 部分厂商 ROM 可能会限制后台监听服务的存活，建议配合保活插件使用
6. setFloatingToggleCallback 是全局回调，同一时间只有一个生效，后设置的覆盖之前的
7. updateFloatingWindow 不会影响已设置的回调，无需重新绑定