更新记录

1.0.0（2026-01-16）

• feat: 初版支持 iOS/Android 背景模糊（backdrop blur）
• fix(android): 兼容性与稳定性调整（含 PreDraw 快照模式、布局/背景处理优化）

平台兼容性

uni-app x(4.87)

hans-blur-view

uni-app x 跨端毛玻璃组件（仅 iOS / Android），用于实现类似 CSS backdrop-filter: blur(...) 的背景模糊效果。

组件

• hans-blur-view：毛玻璃容器（iOS/Android）
• hans-blur-target：Android 专用的采样容器（用于 androidMode="target"）

使用

<template>
    <hans-blur-view
        class="card"
        :blurRadius="16"
        overlayColor="rgba(255,255,255,0.25)"
        :cornerRadius="16"
    >
        <view class="content">
            <text>Glass Card</text>
        </view>
    </hans-blur-view>
</template>

Slots

• hans-blur-view 默认插槽：前景内容（显示在模糊层之上）
• hans-blur-target 默认插槽：背景内容（作为采样源，仅 Android 使用）

Android PreDraw 模式示例（推荐）

<template>
    <view class="page">
        <view id="blur-bg" class="bg-root">
            <scroll-view class="scroll" scroll-y="true">
                <!-- 背景内容 -->
            </scroll-view>
        </view>

        <hans-blur-view
            class="blur-card"
            androidMode="predraw"
            androidTargetId="blur-bg"
            :blurRadius="16"
            overlayColor="rgba(255,255,255,0.25)"
            :cornerRadius="16"
        >
            <view class="content">
                <text>Glass Card</text>
            </view>
        </hans-blur-view>
    </view>
</template>

注意：androidTargetId 指向的容器应只包含“背景”，不要包含模糊卡片本身或其内容，否则会把前景内容也采样进去，出现发光/重影。

Android BlurTarget 模式示例

<template>
    <hans-blur-target targetId="blur-bg" class="bg-root">
        <scroll-view class="scroll" scroll-y="true">
            <!-- 背景内容 -->
        </scroll-view>
    </hans-blur-target>

    <hans-blur-view
        class="blur-card"
        androidMode="target"
        androidTargetId="blur-bg"
        :blurRadius="16"
        overlayColor="rgba(255,255,255,0.25)"
        :cornerRadius="16"
    >
        <view class="content">
            <text>Glass Card</text>
        </view>
    </hans-blur-view>
</template>

Props

hans-blur-view

• enabled：是否启用（默认 true）
• blurRadius：模糊强度（0-25，默认 12；Android 上 0 会关闭 blur，仅保留 overlay）
• blurStyle：视觉风格预设（light | dark | extraLight，默认 light；不区分大小写）
• overlayColor：叠加色（默认不传；iOS 仅支持 rgba()/rgb()/#RGB/#RRGGBB/#RRGGBBAA/transparent；传了则优先生效；未传时 Android 会按 blurStyle 自动选择一套默认 overlay；如需“无叠加”，请显式传 transparent 或 rgba(255,255,255,0)）
• cornerRadius：圆角（默认 0）
• iosIntensity：iOS 强度（0-1，默认不传；优先生效覆盖 blurRadius 映射）
• androidMode：Android 模式（predraw | target，默认 predraw）
• androidTargetId：Android 指定采样容器的 id（可选；容器需是 view 类节点，且只包含“背景”，不要包含模糊卡片本身或其内容；为空时默认采样 android.R.id.content）
• androidTargetPreferPredraw：Android 目标容器优先使用 PreDraw（仅 androidMode="target" 时生效，默认 true；设为 false 可优先走 BlurTarget 硬件路径）

hans-blur-target（Android only）

• targetId：采样容器的 id（建议与 hans-blur-view 的 androidTargetId 保持一致）

Events

• ready：原生视图初始化完成

Methods

• refresh()：手动刷新配置（例如在外部尺寸/内容变化后触发）

平台说明

• iOS：UIVisualEffectView + UIBlurEffect，blurRadius 会映射为强度（近似），需要精确控制请用 iosIntensity
• Android：基于 BlurView（已内置 AAR，version-3.2.0）
  • 为避免在部分 uni-app x 页面结构下触发布局/层级问题，Android 端强制使用 PreDraw 快照模式（不创建 BlurTarget、不搬运同级 View）
  • androidMode="predraw"：使用 PreDraw 快照模式；可通过 androidTargetId 指定采样容器（该容器应只包含“背景”，不要包含模糊卡片本身或内容，否则会出现发光/重影）
  • androidMode="target"：使用 BlurTarget 模式，建议搭配 hans-blur-target 作为采样容器（Android 专用）
    • androidTargetPreferPredraw="true"：优先在目标容器内容上走 PreDraw（更稳妥，兼容性更好）
    • androidTargetPreferPredraw="false"：优先使用 BlurTarget 硬件路径（性能更好，但需确保目标容器布局稳定）
  • 实现方式为：对 android.R.id.content 做 bitmap snapshot，再通过 RenderScript 做 blur（兼容路径；性能取决于页面复杂度/模糊半径/刷新频率）
  • SurfaceView/VideoView/Map 等底层为 Surface 的内容无法被 blur（库限制）
  • 运行在标准基座时三方依赖可能不会生效：需要使用自定义基座才能看到真实 blur（否则会自动降级为 overlay）
  • 建议：在 Android 上尽量使用较小的 blurRadius（如 8-16）并配合合适的 overlayColor 获得更接近 iOS 的观感

Demo

• playground 页面：uniappx-lumina-playground/pages/blur-demo/blur-demo.uvue