做 uni-app 或 uni-app x App 时，很多提醒其实不适合交给系统通知栏：用户正在使用应用、当前页面不该被打断，但又希望新消息、订单状态或业务事件能被及时看到。
这类场景更适合应用内横幅通知。最近整理了一个 UTS API 插件 kongbai-AppNotice，目标是让通知像 QQ、微信的前台横幅一样从应用顶部出现，保留原生动画和交互，同时不把业务跳转逻辑封进插件。
一、插件能做什么
kongbai-AppNotice 面向 uni-app / uni-app x App 端，Android 和 iOS 分别使用原生视图与动画实现。通知采用紧凑的顶部横幅布局，支持标题、正文、图片、时间、附带数据、自动关闭时长和提示音。
它不是系统通知栏，也不会申请额外运行时权限。插件只负责展示、关闭与回调，点击后跳到哪里、打开哪一条会话，都交给业务层自己决定。
二、适用场景
1. 聊天消息的前台提醒
2. 订单、审核、任务等轻量业务提醒
3. 页面内的全局系统提示
4. 不想使用系统通知栏，但需要原生交互和动效的 App 场景
三、平台范围
当前版本支持 uni-app / uni-app x 的 Android（最低 Android 5.0）与 iOS（最低 iOS 12）App 端。Harmony 当前仅保留占位导出；H5 与各类小程序暂未适配，接入前需要确认项目端类型。
四、安装与导入
将插件按 uni_modules 规范导入项目后，即可直接使用：
import { showPluginInAppNotice, dismissPluginInAppNotice } from '@/uni_modules/kongbai-AppNotice'
五、最小调用示例
showPluginInAppNotice({
image: '/static/logo.png',
title: '新的消息',
message: '你收到一条新的应用内通知',
payload: JSON.stringify({ type: 'chat', conversationId: '1001' }),
playSound: true
}, (payload: string) => {
// 在这里按业务需要处理跳转
console.log('notice click payload:', payload)
}, () => {
console.log('notice dismissed')
})
image 支持 /static/... 本地资源和 http/https 网络图片；payload 会在点击时原样回传，建议由业务层传入 JSON 字符串。只想展示通知、不监听事件时，也可以只传配置对象。
六、交互细节
通知支持点击回调、长按暂停自动消失、松手恢复、上滑关闭，以及连续消息的覆盖切换。新通知到达后会进入展示位，旧通知平滑退场，适合消息连续到达的业务。
需要立即关闭当前通知并清空等待中的内容时，可以调用：
dismissPluginInAppNotice()
七、使用时的几个注意点
1. 插件不内置页面跳转，请在 onClick 中解析 payload 后处理。
2. playSound: true 最终仍受系统音量、静音模式和音频路由影响。
3. iOS 使用网络图片时建议优先 HTTPS，避免系统网络安全策略拦截。
4. Android 编译时可能看到 getUniActivity() 的废弃警告，目前不影响正常使用。
插件市场地址：
https://ext.dcloud.net.cn/plugin?name=kongbai-AppNotice
欢迎试用并反馈实际项目中的使用体验。
