更新记录

1.0.0（2025-12-23）

1.0.0（2025-12-23）

• 初次发布。
• 支持 Android。
• App后台切换前台。
• 适配 Android 10+ 运行时权限。
• 采用 UTS 架构，无原生依赖，体积轻巧。

平台兼容性

uni-app(4.57)

uni-app x(4.57)

beautifulman-foreground

实现 App 从后台运行状态主动切换到前台显示的 UTS 插件。适用于音视频通话来电、紧急提醒等需要主动弹出界面的场景。

平台支持

• Android: 支持 (Android 5.0+ / API 21+)
• iOS: 系统限制，仅支持通过推送通知引导用户点击进入。

核心原理

在 Android 10+ 系统中，后台启动 Activity 受到严格限制。本插件通过 悬浮窗权限 (Overlay Permission) 结合 Activity 任务栈调度 实现唤起。在国内厂商（小米、华为等）设备上，通常还需要用户手动开启 “后台弹出界面” 权限。

权限配置 (Android)

在 manifest.json 的 app-plus -> distribute -> android -> permissions 中添加：

[
  "<uses-permission android:name=\"android.permission.SYSTEM_ALERT_WINDOW\"/>",
  "<uses-permission android:name=\"android.permission.REORDER_TASKS\"/>"
]

API 说明

1. ToForegroundOptions 对象说明

所有带回调的 API 均接收此对象作为参数：

2. checkOverlayPermission()

检查当前是否拥有“悬浮窗”权限。

• 返回值: Boolean

3. requestOverlayPermission(options)

跳转到系统设置页申请“悬浮窗”权限。

• 参数: ToForegroundOptions (可选)

4. bringToForeground(options)

核心方法：将应用从后台唤起到前台。

• 参数: ToForegroundOptions (可选)

5. openAppSettings()

跳转到本应用的系统详情页。

• 用途: 用于引导用户手动开启国产手机特有的“后台弹出界面”权限。

完整示例

import { 
  checkOverlayPermission, 
  requestOverlayPermission, 
  bringToForeground,
  openAppSettings
} from "@/uni_modules/beautifulman-foreground";

/**
 * 唤起逻辑封装
 */
export function wakeUpApp() {
  // 1. 先检查基础的悬浮窗权限 (Android 10+ 必需)
  if (!checkOverlayPermission()) {
    uni.showModal({
      title: '权限申请',
      content: '后台来电提醒需要开启“悬浮窗”权限，请在设置中开启。',
      confirmText: '去开启',
      success: (res) => {
        if (res.confirm) {
          requestOverlayPermission();
        }
      }
    });
    return;
  }

  // 2. 执行唤起指令
  bringToForeground({
    success: () => {
      console.log('唤起成功');
    },
    fail: (err) => {
      console.error('唤起失败', err);
      // 如果报错且是国产手机，通常是因为“后台弹出界面”权限没开
      uni.showModal({
        title: '唤起失败',
        content: '请确保已在手机设置中开启“后台弹出界面”权限',
        confirmText: '去设置',
        success: (res) => {
          if (res.confirm) {
            openAppSettings();
          }
        }
      });
    }
  });
}

常见问题

1. 为什么代码执行成功了但 App 没跳出来？ 国产手机（小米、华为、vivo、OPPO）对后台启动有二次拦截。请务必检查：设置 -> 应用管理 -> 本应用 -> 权限管理 -> 后台弹出界面 -> 允许。