更新记录

1.0.1（2026-07-24）

iOS, Android应用切换后台模糊保护

平台兼容性

uni-app(5.07)

uni-app x(5.07)

其他

dd-window-blur 使用文档

本文档根据当前插件源码整理，适用于 uni_modules/dd-window-blur。

1. 插件结论

• 插件类型：UTS 原生插件
• 支持平台：uni-app / uni-app x 的 App-Android、App-iOS
• 不支持平台：H5、各类小程序、Harmony
• HBuilderX 要求：>= 5.07
• Android 最低版本：minSdkVersion 21
• iOS 最低版本：deploymentTarget 12

2. 插件作用

插件用于在应用进入后台、失去焦点或切换任务时，对主窗口内容做保护，避免任务切换界面直接暴露敏感页面内容。

当前实现分为两类：

• iOS：在主窗口上叠加 UIVisualEffectView 模糊层和半透明色层
• Android：优先对页面快照做模糊和着色后覆盖显示；也支持回退为 FLAG_SECURE 模式

非 App 平台会走空实现：

• enableBackgroundBlur() 返回 false
• updateBackgroundBlurOptions() 返回 false
• getBackgroundBlurStatus() 返回 { supported: false, enabled: false }

3. 导出 API

插件导出以下 4 个方法：

• enableBackgroundBlur(options?)
• updateBackgroundBlurOptions(options)
• disableBackgroundBlur()
• getBackgroundBlurStatus()

3.1 DDWindowBlurOptions

type DDWindowBlurOptions = {
  blurStrength?: number
  overlayColor?: string
  overlayOpacity?: number
  androidFallbackToSecure?: boolean
  androidSecureOnly?: boolean
}

字段说明：

• blurStrength：模糊强度，范围 0 ~ 100
• overlayColor：遮罩颜色，建议统一传 #RRGGBB 或 #AARRGGBB
• overlayOpacity：遮罩透明度，范围 0 ~ 1
• androidFallbackToSecure：Android 端是否在无法安全生成模糊快照时回退到 FLAG_SECURE
• androidSecureOnly：Android 端是否始终只使用 FLAG_SECURE，不显示模糊遮罩。建议直接设置true，安卓模糊快照显示不稳定

默认值：

• blurStrength: 55
• overlayColor: '#FFFFFF'
• overlayOpacity: 0.12
• androidFallbackToSecure: false
• androidSecureOnly: false

范围处理：

• blurStrength 超出范围时会被限制到 0 ~ 100
• overlayOpacity 超出范围时会被限制到 0 ~ 1

颜色透明度说明：

• 如果 overlayColor 自身带 alpha，最终透明度会再乘以 overlayOpacity
• 为了效果更可控，建议颜色传不透明值，透明度只通过 overlayOpacity 调整

3.2 enableBackgroundBlur(options?)

启用后台保护。

import { enableBackgroundBlur } from '@/uni_modules/dd-window-blur'

const ok = enableBackgroundBlur({
  blurStrength: 60,
  overlayColor: '#FFFFFF',
  overlayOpacity: 0.18
})

返回值：

• true：启用成功
• false：当前平台不支持，或 Android 当前拿不到可用的 Application 上下文

说明：

• 重复调用是安全的
• 已启用状态下再次调用，会直接刷新内部配置
• Android 在启用后会注册 ActivityLifecycleCallbacks
• iOS 在启用后会注册前后台通知监听

3.3 updateBackgroundBlurOptions(options)

更新已启用保护的参数。

import { updateBackgroundBlurOptions } from '@/uni_modules/dd-window-blur'

updateBackgroundBlurOptions({
  blurStrength: 75,
  overlayColor: '#0F172A',
  overlayOpacity: 0.28,
  androidFallbackToSecure: true
})

返回值：

• true：更新成功
• false：当前尚未启用，或当前平台不支持

说明：

• 该方法不会自动启用插件
• 必须先调用 enableBackgroundBlur()

3.4 disableBackgroundBlur()

关闭后台保护，移除监听并清理遮罩。

import { disableBackgroundBlur } from '@/uni_modules/dd-window-blur'

disableBackgroundBlur()

3.5 getBackgroundBlurStatus()

获取插件状态。

import { getBackgroundBlurStatus } from '@/uni_modules/dd-window-blur'

const status = getBackgroundBlurStatus()
console.log(status)

返回结构：

{
  supported: true,
  enabled: true
}

字段说明：

• supported：当前平台是否支持该插件
• enabled：当前是否已启用保护

4. Android 专属行为

4.1 默认模式

默认情况下，Android 不会直接对当前页面实时加模糊，而是：

1. 在前台时预先抓取当前页面快照
2. 在进入后台前显示这张快照
3. 对快照做模糊和颜色遮罩处理

4.2 androidFallbackToSecure

enableBackgroundBlur({
  androidFallbackToSecure: true
})

含义：

• 当 Android 端无法生成可用快照时，回退为 FLAG_SECURE 模式

当前源码中会触发回退的典型场景：

• Android 10 以下
• 根视图尺寸不可用
• 遮罩容器尚未建立完成
• 当前没有可用快照位图

适用场景：

• 页面内容非常敏感，宁可直接禁截屏，也不要出现无模糊的背景预览

4.3 androidSecureOnly

enableBackgroundBlur({
  androidSecureOnly: true
})

含义：

• Android 始终只使用 FLAG_SECURE
• 不生成快照，不显示模糊遮罩

适用场景：

• 金融、支付、身份信息等高敏感页面
• 你更关心“绝不泄露”，而不是“后台预览视觉更自然”

优先级：

• androidSecureOnly: true 时，优先级高于 androidFallbackToSecure

4.4 FLAG_SECURE 的清理规则

插件只会清除“它自己加上的” FLAG_SECURE。

这意味着：

• 如果你的业务本来就自己设置了 FLAG_SECURE
• 插件在 disableBackgroundBlur() 时不会误把业务自己的安全标记清掉

5. iOS 行为

iOS 端实现比较直接：

• 监听 UIApplication.willResignActiveNotification 时显示模糊层
• 监听 UIApplication.didBecomeActiveNotification 时移除模糊层
• 使用 UIBlurEffect 根据 blurStrength 选择不同模糊样式
• overlayColor 和 overlayOpacity 用于控制附加色层

iOS 端没有 androidFallbackToSecure 和 androidSecureOnly 这两个特有行为，它们传入后不会参与 iOS 逻辑。

6. 推荐接入方式

6.1 App 启动时统一启用

// #ifdef APP-PLUS
import { onLaunch } from '@dcloudio/uni-app'
import { enableBackgroundBlur } from '@/uni_modules/dd-window-blur'
// #endif

// #ifdef APP-PLUS
onLaunch(() => {
  enableBackgroundBlur({
    blurStrength: 55,
    overlayColor: '#FFFFFF',
    overlayOpacity: 0.12
  })
})
// #endif

这是最稳妥的接入方式，后续前后台切换由插件自行处理。

6.2 对 Android 开启安全回退

// #ifdef APP-PLUS
onLaunch(() => {
  const { osName } = uni.getDeviceInfo()
  enableBackgroundBlur({
    blurStrength: 60,
    overlayColor: '#FFFFFF',
    overlayOpacity: 0.16,
    androidFallbackToSecure: osName === 'android'
  })
})
// #endif

6.3 对高敏感 Android 页面只用 FLAG_SECURE

enableBackgroundBlur({
  androidSecureOnly: true
})

6.4 动态调整效果

import {
  enableBackgroundBlur,
  updateBackgroundBlurOptions,
  getBackgroundBlurStatus
} from '@/uni_modules/dd-window-blur'

function applyBlurPreset(options) {
  const status = getBackgroundBlurStatus()
  if (status.enabled) {
    updateBackgroundBlurOptions(options)
    return
  }
  enableBackgroundBlur(options)
}

7. 注意事项

• Android 模糊快照不稳定，建议使用 FLAG_SECURE 直接设置androidSecureOnly值为true
• 建议始终放在 APP-PLUS 条件编译块里使用
• updateBackgroundBlurOptions() 只有在已启用时才会成功
• 如果你要跨平台统一配置，Android 专属参数可以直接传，iOS 会忽略它们
• Android 的模糊本质上是“页面快照模糊”，不是对真实页面做持续实时模糊
• 如果你传入带 alpha 的颜色，再叠加 overlayOpacity，最终效果会比预期更透明
• 插件处理的是主窗口内容；如果你额外创建了独立原生窗口，需要单独评估保护策略