更新记录

1.3.0（2026-10-11）

• 新增可选 theme 参数：light / dark 手动指定，auto、不传或其他值自动识别系统主题，手动指定优先
• Android / iOS 同步适配卡片、标题、正文、时间和头像底色；Android 关闭系统二次反色，iOS 使用深色毛玻璃
• 每条通知独立选择主题，队列在实际展示时识别系统主题，手动主题不会影响后续默认通知
• 测试页增加主题切换、默认自动识别和浅色 → 深色 → 自动主题队列示例

1.2.1（2026-09-19）

• 优化 Android / iOS 通知阴影，采用低透明度、柔和扩散和小偏移的悬浮效果，移除卡片描边

1.2.0（2026-09-17）

• 标准尺寸保持不变，Android max 保留系统大字体自适应，iOS max 保留横屏安全区避让
• 测试页的发送按钮随尺寸选择显示“发送标准通知”或“发送 Max 通知”，默认参数测试单独标明固定标准尺寸
• 新增 iOS 部署配置，将最低系统版本调整为 15.0，解决当前 Xcode 27 模拟器构建不支持 iOS 12.0 部署目标的问题
• 新增可选 size 参数，支持 standard / max；不传或传入其他值时保持标准尺寸，旧调用无需修改

平台兼容性

uni-app(3.8.5)

uni-app x(3.8.5)

其他

kongbai-AppNotice

kongbai-AppNotice 是一个面向 uni-app x App 端的轻量原生应用内横幅通知 UTS API 插件，不依赖系统通知栏即可在应用前台展示可交互的原生横幅。

它像 QQ / 微信一样，在应用前台顶部展示一条可交互、不中断当前页面操作的原生横幅通知。

插件特点

• 原生实现：Android / iOS 分别使用原生视图与动画实现
• 轻柔阴影：两端均提供低透明度悬浮阴影，iOS 保留毛玻璃效果，Android 独立绘制阴影以兼容旧系统
• 轻量 API：提供图片、标题、消息、尺寸、时间、附带数据、时长、提示音等参数
• 不耦合业务：插件只负责展示、关闭、点击回传，不内置跳转逻辑
• 两档尺寸：默认 standard 保留原有小巧横幅，max 放大头像、文字和内容区，正文最多两行
• 深浅主题：不传主题时自动识别系统，也可逐条手动指定浅色或深色，手动指定优先
• 交互完整：支持点击、长按暂停自动消失、上滑关闭、队列管理、覆盖式切换
• 提示音支持：支持按参数控制是否播放系统提示音
• 图片来源灵活：支持 /static/... 本地资源图片和 http/https 网络图片

适用场景

• 聊天消息前台提醒
• 页面内全局系统提示
• 轻量业务提醒条
• 不希望使用系统通知栏、又希望保留原生交互和动画的场景

平台兼容

安装方式

将插件放入项目的 uni_modules 目录后，按常规 uni_modules 方式使用即可。

import { showPluginInAppNotice, dismissPluginInAppNotice } from '@/uni_modules/kongbai-AppNotice'

快速开始

import { showPluginInAppNotice } from '@/uni_modules/kongbai-AppNotice'

showPluginInAppNotice({
  image: '/static/logo.png',
  title: '应用内通知演示',
  message: '这是一条纯原生 UTS 插件提供的通知消息',
  payload: JSON.stringify({ type: 'demo_notice' }),
  playSound: true
}, (payload: string) => {
  console.log('notice click payload:', payload)
}, () => {
  console.log('notice dismissed')
})

API 说明

showPluginInAppNotice(options, onClick?, onDismiss?)

显示一条应用内横幅通知。

参数

回调

也可以只传配置对象：

showPluginInAppNotice({
  title: '新的消息',
  message: '这是一条不监听回调的通知'
})

尺寸选择（v1.2.0 新增）

每次调用独立选择尺寸，支持两种尺寸混合入队，不会改变后续通知的默认值：

// 不传 size 或显式传 standard：保持原有标准尺寸。
showPluginInAppNotice({
  title: '标准通知',
  message: '沿用原有的小巧布局',
  size: 'standard'
})

// max：放大头像、字号和内容区，正文最多两行，超长内容尾部省略。
showPluginInAppNotice({
  image: '/static/logo.png',
  title: '新的客户消息',
  message: '客户希望了解更多房源信息，请及时查看消息并联系客户。',
  size: 'max',
  duration: 5000,
  payload: JSON.stringify({ type: 'customer_message', id: 1 })
}, (payload: string) => {
  console.log('notice click payload:', payload)
})

v1.2.0 的 max 采用接近 iOS 系统通知横幅的宽大布局。它仍是应用内原生视图，系统通知的实际尺寸会随系统版本和内容变化。

dp、sp、pt 均为平台逻辑单位，并非物理像素。两档均单行显示标题并预留时间区域；无图片时文字从左侧内边距开始。max 在 Android 上按实际文字尺寸计算行高、时间宽度及卡片高度，避免系统大字体挤压上下两行。iOS 沿用插件固定字号行为。

主题选择（v1.3.0 新增）

默认自动识别系统主题，无需修改原调用：

// 不传 theme（或传 'auto'）：实际显示时识别系统深浅模式。
showPluginInAppNotice({ title: '自动主题', message: '跟随系统外观' })

// 手动指定优先，独立于系统和宿主应用主题。
showPluginInAppNotice({ title: '浅色通知', message: '固定浅色', theme: 'light' })
showPluginInAppNotice({ title: '深色通知', message: '固定深色', theme: 'dark', size: 'max' })

theme 只作用于当前这条通知，不修改应用或系统主题，也不记忆上一次手动选择。light / dark 以外的值（包括空字符串）按 auto 处理。两档尺寸、有图/无图及混合队列均支持主题设置；排队中的自动通知在实际展示时重新读取系统主题。

主题在每条通知创建原生视图时确定；已经展示的通知保留本次主题，系统切换后的下一条自动通知会使用新主题。Android 通过系统夜间配置识别，旧系统未提供深色配置时默认浅色，但仍可手动指定 dark；iOS 读取当前窗口所属场景的系统外观。无需调用 uni.setAppTheme 或改变宿主应用的主题配置。

升级到 v1.3.0 后需要重新编译 App；自定义调试基座需要重新制作。测试页提供“跟随系统 / 浅色 / 深色”选择，以及“浅色 → 深色 → 自动”队列：请在系统深浅模式下分别发送，核对手动指定优先、默认恢复自动、文字可读性、头像、阴影和交互。

升级到 v1.2.1

v1.2.1 调整了两档通知的阴影和左右留白，卡片内容高度、字号及 API 保持不变。iOS 使用独立圆角阴影路径，Android 使用独立软件阴影视图；Android 的阴影区域不计入表格中的卡片内容高度，也不触发通知点击。两端采用接近 iOS 系统通知的轻柔悬浮风格，并非调用系统通知界面。

从 v1.2.0 升级同样需要重新编译 App；使用自定义调试基座时，需重新制作包含新版原生插件的基座。两端 UTS 转换检查已通过，真机视觉效果仍需验收。

从 v1.1.x 升级时还需注意：

v1.2.0 的 iOS 最低部署版本调整为 15.0，以适配当前 Xcode 27 工具链；升级后不再支持 iOS 12–14。

1. 更新 uni_modules/kongbai-AppNotice 至 v1.2.1，重新编译 App；使用自定义调试基座时，同步重新制作包含新版原生插件的基座。
2. 原调用无需修改，未传 size 仍使用标准模式，阴影和左右留白按新版显示。
3. 需要放大展示的通知单独增加 size: 'max'，其他参数和回调签名保持不变。

测试项目的 pages/index/index.uvue 已提供尺寸切换、不传参数、有图/无图、长标题/长正文、时长、提示音和“标准 → max → 标准”混合队列示例。验收时请分别在 Android / iOS 检查窄屏、横屏、点击、长按、上滑及主动关闭，并在 Android 大字体设置下复查 max 文字边界。混合队列的后续两条由页面延时发送，主动关闭当前通知不会取消页面尚未执行的发送计时器。

dismissPluginInAppNotice()

主动关闭当前横幅通知，并清空等待中的通知队列。

交互说明

• 点击通知：触发 onClick
• 长按通知：暂停自动消失计时
• 松手恢复：恢复自动消失或继续处理队列
• 上滑关闭：直接移除当前通知
• 连续推送多条：新通知覆盖切换到展示位，旧通知平滑退场

设计说明

当前版本以“轻量、小巧、圆滑、灵动”为主要设计方向：

• iOS 使用原生毛玻璃与原生动画
• Android 使用圆角卡片与原生过渡动画
• 双端都处理了顶部安全区
• 两档均采用轻柔阴影和更充足的左右留白；max 扩大纵向内容区并同步调整头像、字号、间距和圆角，宽度保持窗口内自适应
• 混合尺寸切换时旧卡片保持原尺寸退场，新卡片按自身高度入场

注意事项

• 本插件当前主打 uni-app x App 端，不建议直接用于 H5 / 小程序
• Android 端编译时可能出现 getUniActivity() 的废弃警告，目前不影响插件正常工作
• playSound: true 依赖系统音量、静音模式与音频路由，最终以真机表现为准
• iOS 端网络图片建议优先使用 https 地址，避免系统网络安全策略拦截
• 插件不负责业务跳转，如需点击后打开聊天页、详情页，请在 onClick 中自行处理
• payload 由业务层自行约定格式，插件不解析内容

目录结构

kongbai-AppNotice/
├─ package.json
├─ readme.md
├─ changelog.md
└─ utssdk/
   ├─ interface.uts
   ├─ app-android/
   │  ├─ config.json
   │  └─ index.uts
   ├─ app-ios/
   │  ├─ config.json
   │  └─ index.uts
   └─ app-harmony/
      ├─ config.json
      └─ index.uts

更新日志

详细更新内容见 changelog.md。

参考文档

• UTS 插件介绍
• uni_modules 规范
• UTS 语法