更新记录

3.2.0（2026-06-02）

• 新增 effectAlpha 属性(默认 1.0):仅 iOS 生效,控制 UIVisualEffectView 整体不透明度。iOS system material 在浅色下会强制提亮(材质内建的白),又不暴露模糊半径,effectAlpha 略降可削弱固有白、让背景透出更多。Android / 鸿蒙忽略此值。
• iOS 材质 systemChromeMaterial → systemUltraThinMaterial:更通透,仍跟随系统亮暗。
• 鸿蒙 overlayColor 行为变更(重要):鸿蒙 BuilderNode.update 在运行时切主题时不可靠、不重绘,overlayColor 改了不生效(必须重启 App)。鸿蒙端 native-view 现在只负责模糊,叠色不再走 overlayColor;需要主题色蒙版时,请在组件外层另叠一个普通 <view> 用 :style 绑颜色(标准响应式,跟手变色)。iOS / Android 的 overlayColor 仍在 native-view 内正常工作。详见 readme 坑 6。
• 鸿蒙 backdropBlur 在小半径下糊不开背景,建议鸿蒙单独把 blurRadius 调大(如 50-60),靠模糊而非加厚蒙版保证可读性。

3.1.1（2026-06-01）

• 修复 iOS 云打包(新版 Xcode/Swift SDK)编译失败:
  • UIKit 系统类型在新 SDK 被重命名,改用嵌套全限定名:UIViewAutoresizing → UIView.AutoresizingMask、UIBlurEffectStyle → UIBlurEffect.Style
  • OptionSet 不能用 | 位或,改用 .union(...)
  • 绑定原生视图方法名修正为 bindIOSView(原 bindIosView 大小写错误)
  • 颜色分量 number / 255.0 显式包 CGFloat(...),避免被装箱成 NSNumber 无法转换
  • 拆分超长字符串拼接,规避 Swift "类型检查超时"
• iOS 最低系统从 12 调整为 13:systemChromeMaterial 为 iOS 13+ API,新增 utssdk/app-ios/config.json({"deploymentTarget": "13.0"})。DCloud 云打包 Xcode 环境本身已最低支持 iOS 13。

3.1.0（2026-06-01）

• iOS 端原生支持:UIVisualEffectView + UIBlurEffect.systemChromeMaterial,替换原 CSS backdrop-filter(uvue 编译不识别)
• iOS 端 overlayColor 解析与 Android Color.parseColor 对齐(#AARRGGBB)
• 三端(iOS / Android / 鸿蒙)统一走 <kelp-blur-view>,H5 继续用 CSS
• 文档重写,补齐 iOS 实现说明 + 跨端写法 + 踩坑指南

平台兼容性

uni-app x(5.07)

其他

kelp-blur-view

跨平台原生毛玻璃组件,uni-app x 三端原生 + H5 全覆盖。

iOS / Android / 鸿蒙都走原生模糊层,H5 用 CSS backdrop-filter。一个 <kelp-blur-view> 标签搞定所有 App 端,H5 端用条件编译降级到 CSS 即可。

一句话定位

快速上手

App 三端(iOS / Android / 鸿蒙)统一用组件:

<template>
    <view class="container">
        <image class="bg" src="/static/bg.png" />

        <view class="bottom-bar">
            <kelp-blur-view class="blur-bg" :blurRadius="20" overlayColor="#80FFFFFF" />
            <text class="title">毛玻璃效果</text>
        </view>
    </view>
</template>

<style>
.bottom-bar {
    position: fixed;
    bottom: 0;
    left: 0;
    right: 0;
    height: 80px;
}

.blur-bg {
    position: absolute;
    top: 0;
    left: 0;
    right: 0;
    bottom: 0;
    z-index: 1;
}

.title {
    position: relative;
    z-index: 2;
    color: #111;
}
</style>

属性

属性响应式更新的平台差异:

• iOS / Android:改 blurRadius / overlayColor / effectAlpha 即时生效。
• 鸿蒙:blurRadius 在首次绑定时生效;overlayColor 运行时改值不重绘(BuilderNode.update 在这套 wrapBuilder 机制下不可靠),需要随主题切换的蒙版色请放到外层普通 <view>,详见坑 6。

平台支持矩阵

H5 写法

H5 上不需要本组件,CSS 一句话就够,且性能比原生组件更好:

<template>
    <view class="glass-bar">
        <text class="title">毛玻璃顶栏</text>
    </view>
</template>

<style>
.glass-bar {
    position: fixed;
    top: 0; left: 0; right: 0;
    height: 88px;
    background-color: rgba(255, 255, 255, 0.55);
    backdrop-filter: blur(20px);
    -webkit-backdrop-filter: blur(20px);
}
</style>

调参建议:

• blur(N) 数值越大模糊越强,15-25 是常用区间。
• background-color 的 alpha 控制蒙版浓度,0.4-0.6 看起来比较舒服。
• -webkit-backdrop-filter 不能省,部分旧版 WebKit 只认带前缀的写法。

跨端统一写法(推荐)

App 三端走 <kelp-blur-view>,H5 走 CSS,用条件编译分流:

<template>
    <view class="bar">
        <!-- H5: CSS backdrop-filter -->
        <!-- #ifdef H5 -->
        <view class="glass-css"></view>
        <!-- #endif -->

        <!-- iOS / Android / 鸿蒙: 原生 blur-view -->
        <!-- #ifdef APP-IOS || APP-ANDROID || APP-HARMONY -->
        <kelp-blur-view class="glass-native" :blurRadius="20" overlayColor="#80FFFFFF" />
        <!-- #endif -->

        <!-- 你的内容 -->
    </view>
</template>

<style>
/* #ifdef H5 */
.glass-css {
    position: absolute;
    top: 0; left: 0; right: 0; bottom: 0;
    background-color: rgba(255, 255, 255, 0.55);
    backdrop-filter: blur(20px);
    -webkit-backdrop-filter: blur(20px);
    z-index: 1;
}
/* #endif */

/* #ifdef APP-IOS || APP-ANDROID || APP-HARMONY */
.glass-native {
    position: absolute;
    top: 0; left: 0; right: 0; bottom: 0;
    z-index: 1;
}
/* #endif */
</style>

最佳实践

场景 1:悬浮卡片

<view class="card">
    <kelp-blur-view class="card-bg" :blurRadius="15" overlayColor="#A0FFFFFF" />
    <view class="card-content">
        <text>卡片内容</text>
    </view>
</view>

<style>
.card {
    position: relative;
    width: 300px;
    height: 200px;
    border-radius: 16px;
    overflow: hidden;
}
.card-bg {
    position: absolute;
    top: 0; left: 0; right: 0; bottom: 0;
}
.card-content {
    position: relative;
    z-index: 2;
    padding: 20px;
}
</style>

场景 2:贴底 TabBar(进阶)

要同时处理"手势小白条安全区"和"模糊覆盖完整高度",有踩坑,详见下方踩坑指南。

踩坑指南

坑 1:小白条区域模糊失效(主要在 OPPO / vivo)

现象:<kelp-blur-view> 用 position: absolute; top/left/right/bottom: 0 撑满父容器,父容器有 padding 或包含其它非 absolute 子元素时,模糊只覆盖到非 absolute 子元素的总和高度,padding 区域和兄弟 view 透出底部页面背景。

根因:<kelp-blur-view> 在 Android / 鸿蒙 / iOS 都是原生 View,uni-app x 把 absolute 撑满翻译成原生布局时,实际测量参考的是非 absolute 子元素的内容总和(content-box),不包含 padding,也不会跟兄弟 view 增高。

解法:给 <kelp-blur-view> 显式 style="height: ...",绕开 absolute 撑满的测量逻辑。

<template>
    <view class="bar">
        <kelp-blur-view class="bg" :style="blurStyle" :blurRadius="20" overlayColor="#80FFFFFF" />
        <view class="content"><!-- 50px 高 --></view>
        <view class="placeholder" :style="placeholderStyle"><!-- 安全区,16px 高 --></view>
    </view>
</template>

<script setup lang="uts">
    const safeBottom = ref<number>(16)

    const blurStyle = computed<UTSJSONObject>(() : UTSJSONObject => {
        return { height: (50 + safeBottom.value) + 'px' } as UTSJSONObject
    })

    const placeholderStyle = computed<UTSJSONObject>(() : UTSJSONObject => {
        return { height: safeBottom.value + 'px' } as UTSJSONObject
    })
</script>

<style>
.bg {
    position: absolute;
    top: 0; left: 0; right: 0;
    /* 不要写 bottom: 0 或 height: 100%,改用 :style 显式高度 */
    z-index: 1;
}
</style>

坑 2:贴底毛玻璃栏与底部安全区适配

现象:全面屏开手势导航后,系统手势条(Android)或 home indicator(iOS)会盖住 TabBar 一部分,不处理就显得"按钮被切了一半"。

算法分平台:

• iOS:UIKit 的 safeAreaInsets.bottom 直接就是 home indicator 高度,iPhone X 系列 = 34pt,旧设备 = 0,直接用即可。
• Android:优先用 safeAreaInsets.bottom,部分 ROM(OPPO 等)不汇报时用几何 screenHeight - windowHeight 兜底,但要剔除 diff ≈ statusBarHeight 的假阳性(说明 windowHeight 临时排掉了 statusBar 而非 navBar)。
• 鸿蒙:ArkUI 对 fixed 容器有默认底部安全区避让,自动顶起一半,要用 Math.round(raw / 2),否则双倍留白。
• H5:不需要处理,浏览器自动管理 viewport。

function resolveBottomInset() : number {
    // #ifdef H5
    return 0
    // #endif

    // #ifndef H5
    const info = uni.getWindowInfo()
    const insetBottom = info.safeAreaInsets.bottom

    // #ifdef APP-IOS
    return insetBottom
    // #endif

    // #ifndef APP-IOS
    let raw = insetBottom
    if (raw == 0) {
        const diff = info.screenHeight - info.windowHeight
        const statusH = info.statusBarHeight
        if (diff > statusH + 8) raw = diff - statusH
        else if (diff >= 8 && Math.abs(diff - statusH) >= 8) raw = diff
    }

    // #ifdef APP-HARMONY
    return Math.round(raw / 2)
    // #endif

    // #ifdef APP-ANDROID
    return raw
    // #endif
    // #endif
    // #endif
}

坑 3:Android 本地编译报"找不到 eightbitlab"

现象:HBuilderX 本地直接运行时报 找不到 eightbitlab.com.blurview.BlurView。

根因:maven 依赖 com.eightbitlab:blurview:1.6.6 只存在云端 maven 仓库,本地 UTS 编译器看不到 jar。

解法:云端打自定义调试基座(HBuilderX → 项目右键 → 运行 → 运行到 Android → 制作自定义调试基座),5-10 分钟云端打包后用新基座运行即可。同样的限制对所有依赖 maven 的 UTS 插件都适用。

坑 4:iOS 模糊样式不跟随主题

现象:iOS 端切换暗色主题时,毛玻璃看起来颜色没变。

根因:本组件用的是 UIBlurEffect.systemUltraThinMaterial,会自动跟随系统亮暗主题。但如果你的应用主题是手动控制的(独立于系统),systemUltraThinMaterial 不会跟着切换。

解法:用 overlayColor 配合主题 token 提供颜色蒙版,亮色给 #80FFFFFF,暗色给 #CC1A1A1A,iOS 端会即时重绘:

<kelp-blur-view :blurRadius="20" :overlayColor="isDark ? '#CC1A1A1A' : '#80FFFFFF'" />

⚠️ 此法仅 iOS / Android 有效。鸿蒙端 overlayColor 运行时改值不重绘,鸿蒙的主题色蒙版要按坑 6 的办法在外层另叠普通 view。

坑 5:iOS 云打包报 systemUltraThinMaterial / UIView.AutoresizingMask 相关错误

现象:iOS 云打包(新版 Xcode / Swift SDK)报一连串编译错误,例如:

• 'systemUltraThinMaterial' is only available in iOS 13.0 or newer
• 'UIViewAutoresizing' has been renamed to 'UIView.AutoresizingMask'
• 'UIBlurEffectStyle' has been renamed to 'UIBlurEffect.Style'

根因:两类问题。一是 systemUltraThinMaterial(及 systemChromeMaterial 等 system* 材质)是 iOS 13+ API,部署目标低于 13 就报"only available"。二是新版 SDK 把多个 UIKit 系统类型重命名成了嵌套类型,裸用旧名会报 has been renamed。

解法:

1. 把部署目标提到 iOS 13:插件已自带 utssdk/app-ios/config.json({"deploymentTarget": "13.0"})。若你 fork 了源码自行编译,确认这个文件在。DCloud 云打包 Xcode 环境本身已最低支持 iOS 13,继续兼容 12 没有实际收益。
2. 系统枚举/OptionSet 一律写嵌套全限定名,并且 OptionSet 用 .union() 而非 |:

// ✗ 旧写法(新 SDK 编译失败)
ev.autoresizingMask = UIViewAutoresizing.flexibleWidth | UIViewAutoresizing.flexibleHeight
const effect = UIBlurEffect(style = UIBlurEffectStyle.systemUltraThinMaterial)

// ✓ 正确写法
ev.autoresizingMask = UIView.AutoresizingMask.flexibleWidth.union(UIView.AutoresizingMask.flexibleHeight)
const effect = UIBlurEffect(style = UIBlurEffect.Style.systemUltraThinMaterial)

3.1.1 起源码已按正确写法修正,直接用插件无需改动;此条供 fork 源码二次开发者参考。

坑 6:鸿蒙端切主题时蒙版颜色不变(必须重启 App 才生效)

现象:鸿蒙端运行时切换暗/亮主题,改 overlayColor 不生效——暗色蒙版没盖上、tabbar 发浅灰,只有杀掉 App 重进才正常。

根因:鸿蒙端 native-view 内的模糊+蒙版由 ArkUI BuilderNode 渲染。BuilderNode.update() 在这套 wrapBuilder 机制下不可靠、运行时不重绘;只有组件首次 bind 时(冷启动 / 重新挂载)才会用上新颜色。所以 overlayColor 改值无效,重启才正常。iOS / Android 直接 set 原生属性,无此问题。

解法:鸿蒙的蒙版色不要走 overlayColor,改在组件外层另叠一个普通 <view>,用 :style 绑主题色(普通 view 的 backgroundColor 是标准响应式,跟手变色)。鸿蒙端 native-view 只保留模糊,蒙版交给外层 view:

<template>
    <view class="bar">
        <!-- 鸿蒙 native-view 只做模糊,blurRadius 调大些糊得开,overlayColor 传透明 -->
        <kelp-blur-view class="glass" :blurRadius="60" overlayColor="#00000000" />
        <!-- 鸿蒙蒙版层:普通 view 跟手变色 -->
        <!-- #ifdef APP-HARMONY -->
        <view class="glass" :style="{ backgroundColor: isDark ? 'rgba(20,20,20,0.72)' : 'rgba(255,255,255,0.68)' }"></view>
        <!-- #endif -->
        <!-- 内容 -->
    </view>
</template>

<style>
.glass {
    position: absolute;
    top: 0; left: 0; right: 0; bottom: 0;
    z-index: 1;
}
</style>

注意两点:① 蒙版 view 写在 blur-view 之后(同 z-index 时后者盖在上面);② 可读性优先靠 blurRadius 调大(鸿蒙 backdropBlur 弱,50-60 才糊得开),蒙版不透明度取中等(0.65-0.8),不要顶到 0.9 以上,否则盖死模糊、看着像半透明纯色而非毛玻璃。

FAQ

Q: Android 上模糊看起来颗粒粗,iOS 细腻很多?

A: RenderScriptBlur 是采样降级 + 高斯模糊,半径越大颗粒越明显。把 blurRadius 调到 12-18 一般能平衡性能和效果;如果项目允许,可以把 overlayColor 透明度调高(如 #B0FFFFFF),靠蒙版掩盖颗粒感。

Q: iOS 为什么不直接用 CSS backdrop-filter?

A: 早期版本确实是这样做的,但 uvue 的 <style> 编译产物只支持很小一个 CSS 子集,backdrop-filter 在 iOS native 编译产物里不识别(uvue 走 UIKit 而非 WebView)。所以 3.0.0 起 iOS 改用 UIVisualEffectView 原生组件,效果与系统级 tabbar 一致。H5 端因为是真实浏览器环境,继续用 CSS 即可。

Q: 鸿蒙端最低系统要求?

A: HarmonyOS Next 5.0+。HarmonyOS 4.x 的旧版 ArkUI 不支持 .backdropBlur,组件不会报错但模糊不生效。

Q: 在 slot 内放内容会怎样?

A: slot 内容会渲染在 blur-view 的 native-view 内部,但不推荐——native-view 内的子元素布局/事件会受平台原生差异影响,排查问题困难。建议把 blur-view 作为 absolute 背景层,内容放外层兄弟节点,通过 z-index 叠加。

Q: 为什么 iOS 的 blurRadius 不生效?

A: iOS 的 UIVisualEffectView 不暴露具体 radius 数值,只提供预设 style(.systemUltraThinMaterial / .systemMaterial / .regular 等),组件内部用的是 systemUltraThinMaterial(较通透,跟随系统亮暗)。要换强度需要改源码切 style;或用 effectAlpha 属性微调整体不透明度(仅 iOS)。

更新日志

3.2.0

• 新增 effectAlpha 属性(仅 iOS):控制 UIVisualEffectView 整体不透明度,用于削弱浅色 material 固有的白、让背景透出更多。Android / 鸿蒙忽略
• iOS 材质 systemChromeMaterial → systemUltraThinMaterial(更通透,仍跟随系统亮暗)
• 鸿蒙 overlayColor 运行时不重绘(BuilderNode.update 不可靠):鸿蒙端 native-view 改为只做模糊,主题色蒙版需在外层另叠普通 view(见坑 6)

3.1.1

• 修复 iOS 云打包(新版 Xcode/Swift SDK)编译失败:系统类型改用嵌套全限定名(UIView.AutoresizingMask / UIBlurEffect.Style)、OptionSet 用 .union()、bindIOSView 大小写修正、颜色分量显式包 CGFloat、拆分超长字符串拼接
• iOS 最低系统 12 → 13(systemChromeMaterial 为 iOS 13+ API),新增 utssdk/app-ios/config.json 设 deploymentTarget: 13.0

3.0.0

• iOS 端原生支持(UIVisualEffectView + UIBlurEffect.systemChromeMaterial),不再依赖 CSS backdrop-filter(uvue 编译不识别)
• 三端(iOS / Android / 鸿蒙)统一走 <kelp-blur-view>,H5 继续用 CSS
• iOS 端 overlayColor 解析与 Android Color.parseColor 对齐(#AARRGGBB)

2.0.0

• 鸿蒙端原生支持(BuilderNode + backdropBlur)
• Android 端切换到 com.eightbitlab:blurview Maven 库,渲染稳定性提升
• 标准模式重写为 native-view + UTS,API 简化

1.x

• 仅 Android,基于自研 RenderScript 实现