更新记录

1.0.2（2026-10-19） 下载此版本

增加确定和取消按钮配置支持文字和颜色的配置

1.0.1（2026-10-18） 下载此版本

更新api文档

1.0.0（2026-10-18） 下载此版本

init

平台兼容性

uni-app(5.26)

uni-app x(5.26)

其他

lj-alert-popup 系统级顶部悬浮通知（Android）

系统消息提示的系统级顶部悬浮窗。圆角卡片从屏幕顶部滑入，左侧图标、右侧标题 + 正文（标题单行省略、正文两行省略），可覆盖在其他 App 之上显示，点击可拉回应用并跳转。

仅支持 Android App（iOS / Web / 小程序不支持）。最低 Android 5.0（API 21）。

安装

1. 将 uni_modules/lj-alert-popup 整个目录放进项目 uni_modules；

2. 确认项目 manifest.json → App 权限配置里有：

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

3. 制作自定义调试基座后运行（涉及原生权限声明，标准基座不生效）。

用法示例

所有示例统一引入：

import {
  show, hide, hasPermission, requestPermission, isShowing, setDefaultOptions
} from '@/uni_modules/lj-alert-popup'

1. 最简弹窗

show({
  title: '3 号泵房 · 压力超标',
  content: '当前压力 1.82MPa，超过阈值 1.60MPa'
})

默认 3 秒后自动消失。

2. 带网络图标

show({
  title: '3 号泵房 · 压力超标',
  content: '当前压力 1.82MPa，超过阈值 1.60MPa',
  icon: 'https://example.com/icon.png'
})

3. 带 base64 图标

show({
  title: '告警',
  content: '设备离线',
  icon: 'data:image/png;base64,iVBORw0KGgoAAAANSUhEUg...'
})

4. 用包内图片做图标

/static/xxx.png 原生层读不到，需要先转 base64：

uni.getFileSystemManager().readFile({
  filePath: '_www/static/alert-icon.png',
  encoding: 'base64',
  success: (res) => {
    show({
      title: '告警',
      content: '设备离线',
      icon: 'data:image/png;base64,' + res.data
    })
  }
})

5. 常驻显示，手动关闭

show({ title: '巡检中', content: '正在上传数据…', duration: 0 })

// 业务处理完后关闭
hide()

6. 调整距顶部的距离

// 距状态栏下沿 120dp
show({ title: '告警', content: '内容', topOffset: 120 })

// 紧贴状态栏
show({ title: '告警', content: '内容', topOffset: 0 })

// 忽略状态栏，从屏幕最顶部算起
show({ title: '告警', content: '内容', topOffset: 0, ignoreStatusBar: true })

7. 点击跳转内部页面

show({
  title: '3 号泵房 · 压力超标',
  content: '点击查看详情',
  onClick: () => {
    uni.navigateTo({ url: '/pages/detail/detail?id=1' })
  }
})

点击时会先收起弹窗、把应用从后台拉到前台，再执行回调。

8. 点击打开外部链接

show({
  title: '了解保活方案',
  content: '点击打开插件市场',
  onClick: () => {
    plus.runtime.openURL('https://ext.dcloud.net.cn/plugin?id=30231')
  }
})

9. 只有「确定」按钮

show({
  title: '告警已恢复',
  content: '系统运行正常',
  confirmText: '知道了',
  onConfirm: () => {}
})

10. 只有「取消」按钮

show({
  title: '正在上传数据',
  content: '是否停止上传？',
  cancelText: '停止上传',
  onCancel: () => {
    uni.showToast({ title: '已停止', icon: 'none' })
  }
})

11. 「取消」+「确定」两个按钮

show({
  title: '确认处理该告警？',
  content: '3 号泵房压力超标，确认后将标记为已处理。',
  icon: 'https://example.com/icon.png',
  duration: 0,                      // 带按钮时通常设为常驻
  cancelText: '忽略',
  confirmText: '立即处理',
  onCancel: () => {
    uni.showToast({ title: '已忽略', icon: 'none' })
  },
  onConfirm: () => {
    uni.navigateTo({ url: '/pages/detail/detail?id=99' })
  }
})

12. 自定义按钮文字颜色

show({
  title: '确认处理该告警？',
  content: '3 号泵房压力超标',
  cancelText: '忽略',
  cancelTextColor: '#FF999999',     // 灰色
  confirmText: '立即处理',
  confirmTextColor: '#FFFF3B30',    // 红色
  onCancel: () => {},
  onConfirm: () => {}
})

颜色支持 #RGB、#RRGGBB、#AARRGGBB，写错不会崩溃，自动回退默认色。

13. 权限检查与引导

// 判断是否已授权
if (!hasPermission()) {
  // 跳转系统设置页「显示在其他应用上层」
  requestPermission()
}

requestPermission() 不会告诉你用户是否授权，回到页面后需要重新检查：

export default {
  data() {
    return { waiting: false }
  },
  onShow() {
    if (this.waiting && hasPermission()) {
      this.waiting = false
      uni.showToast({ title: '权限已开启', icon: 'none' })
    }
  },
  methods: {
    grant() {
      this.waiting = true
      requestPermission()
    }
  }
}

14. 全局默认配置

统一设置图标、时长、位置、点击行为，之后每次只传标题和正文：

// App.vue onLaunch 里
setDefaultOptions({
  icon: 'https://example.com/alert-icon.png',
  duration: 5000,
  topOffset: 12,
  onClick: () => {
    uni.reLaunch({ url: '/pages/index/index' })
  }
})

// 页面里
show({ title: '告警', content: '压力超标' })

// 单次覆盖默认值
show({ title: '告警', content: '压力超标', duration: 0, topOffset: 0 })

15. 判断当前是否有弹窗

if (!isShowing()) {
  show({ title: '告警', content: '内容' })
}

注意 show() 内部切主线程异步执行，紧接着调用可能仍返回 false。

16. 配合保活插件（后台稳定收到告警）

本插件只负责显示，不负责让进程活着。需要锁屏 / 桌面稳定弹出时，搭配 lj-keeplive：

import { start } from '@/uni_modules/lj-keeplive'

// 启动时开启前台服务
start({ /* 按保活插件文档配置 */ })

// 收到告警后弹出
show({ title: '告警', content: '压力超标', duration: 0 })

API

方法总览

插件只导出以上 6 个方法。

类型定义

export type AlertPopupOptions = {
  title : string,
  content : string,
  icon ?: string,
  duration ?: number,
  topOffset ?: number,
  ignoreStatusBar ?: boolean,
  onClick ?: () => void,
  cancelText ?: string,
  cancelTextColor ?: string,
  onCancel ?: () => void,
  confirmText ?: string,
  confirmTextColor ?: string,
  onConfirm ?: () => void
}

export type AlertPopupDefaults = {
  icon ?: string,
  duration ?: number,
  topOffset ?: number,
  ignoreStatusBar ?: boolean,
  onClick ?: () => void
}

show(options)

显示一条顶部悬浮通知。重复调用会先移除旧弹窗，只保留最后一个。

返回值 void。不支持 success / fail 回调。

未授予悬浮窗权限时不会显示，控制台输出：lj-alert-popup: 未获得悬浮窗权限，请先调用 requestPermission()。

hide()

收起当前弹窗，无参数、无返回值。没有弹窗时调用不会报错。

hide()

hasPermission()

返回 boolean，是否已获得「显示在其他应用上层」权限。Android 6.0 以下恒为 true。

const granted = hasPermission()

requestPermission()

跳转系统设置页，无参数、无返回值。不返回用户是否授权，需要回到页面后用 hasPermission() 复查。

requestPermission()

isShowing()

返回 boolean，当前是否有弹窗在显示。自动消失、hide()、点击后均为 false。

const showing = isShowing()

setDefaultOptions(options)

设置全局默认值，show() 未显式传入的字段使用默认值。

返回值 void。只传想改的字段，未传的保持上次的值；title / content 不能设默认值。配置存在内存中，重启应用后恢复初始值。

setDefaultOptions({ duration: 5000, topOffset: 12 })

回调说明

onClick、onCancel、onConfirm 共用同一套执行流程：

1. 收起弹窗；
2. 把应用从后台拉回前台；
3. 延迟 300ms 执行回调（等页面栈就绪）。

• 每个弹窗的回调最多执行一次；
• 点击按钮不会触发整卡的 onClick；
• 点击卡片其他区域（含按钮行空白处）会触发 onClick。

注意事项

1. 按钮显示只看文字：只传 onCancel / onConfirm 不传文字，按钮不会出现。
2. 图标：不传时左侧保留 40dp 占位；网络图片异步下载，失败只显示文字。
3. 跨 App 显示：只要进程存活就能覆盖其他应用；进程被杀弹窗消失。
4. 后台触发：App 被系统冻结时 JS 不执行，弹窗也不会出现，需要配合保活插件。
5. 窗口层级：TYPE_APPLICATION_OVERLAY 低于系统状态栏，ignoreStatusBar: true 时卡片会被状态栏遮挡属正常现象。
6. 只显示一个：多次调用 show() 后面覆盖前面。

更新日志

1.0.0

• Android 系统级顶部悬浮通知，支持跨应用显示
• 图标支持网络 / base64 / 本地路径
• 支持自动消失、常驻、点击回调
• 支持 topOffset、ignoreStatusBar 定位配置
• 支持取消 / 确定按钮，文字、颜色、回调可配置
• 提供 isShowing()、setDefaultOptions()