uni-app x 中 backdrop-filter 背景滤镜(毛玻璃)完整指南
uni-app x 中 backdrop-filter 背景滤镜(毛玻璃)完整指南
本篇指南聚焦 uni-app x 对 CSS backdrop-filter 属性的支持:它能为元素后方透出的背景内容添加高斯模糊等图形效果,是实现毛玻璃(Glassmorphism)、悬浮导航栏、玻璃质感卡片等界面效果的核心手段。读完本文,你将掌握 backdrop-filter 的语法、属性值、各端兼容性约束,并能基于仓库中的完整示例代码,在 uni-app x 项目中直接落地可运行的毛玻璃 UI。
backdrop-filter 是什么:作用于“背后”的滤镜
CSS 的 backdrop-filter 属性用于给元素后方(背景透出)的所有内容添加图形效果,例如毛玻璃、背景高斯模糊等。它与普通 filter 的区别在于作用对象:
filter:作用于元素自身的绘制结果;backdrop-filter:作用于元素背后被遮挡住的背景内容,再与其自身内容叠加显示。
要看到
backdrop-filter的效果,必须使元素或其背景至少部分透明。否则元素自身不透明背景会完全遮住后方内容,滤镜无从作用。
这也是毛玻璃实现的典型前提:一个半透明的浮层(如悬浮面板、导航条)盖在滚动内容之上,通过 backdrop-filter 把透出的内容做高斯模糊,形成类似玻璃的质感。
uni-app x 兼容性
backdrop-filter 属于 CSS 属性,其可用性与编译到各端的渲染引擎直接相关。官方兼容性如下:
| Web | Android(VDOM) | Android(Vapor) | iOS(VDOM) | iOS(Vapor) | HarmonyOS(VDOM) | HarmonyOS(Vapor) |
|---|---|---|---|---|---|---|
| 4.0 | x | 5.25 | x | 5.25 | x | 5.25 |
要点解读:
- 该属性仅在 Web 端(4.0 起) 以及 Vapor 渲染模式下可用,VDOM 模式下不支持;
- Android、iOS、HarmonyOS 三个平台的 Vapor 模式均自 5.25 版本起支持;
- 从源码结构看,CSS 属性文档目录 中每项属性都按渲染管线分别标注兼容版本,
backdrop-filter的 “x” 标记即代表 VDOM 模式暂未实现,开发时应通过 条件编译 或降级方案处理 VDOM 平台。
语法
backdrop-filter: none | <filter-function-list>;
none:清除/禁用背景滤镜效果,为默认值;<filter-function-list>:一个或多个滤镜函数组成的列表,函数之间以空格分隔,可叠加使用。
backdrop-filter 的属性值
| 名称 | 兼容性 | 描述 |
|---|---|---|
none |
Web: 4.0; Android(VDOM): x; Android(Vapor): 5.25; iOS(VDOM): x; iOS(Vapor): 5.25; HarmonyOS(VDOM): x; HarmonyOS(Vapor): 5.25 | 清除/禁用背景滤镜效果 |
blur() |
Web: 4.0; Android(VDOM): x; Android(Vapor): 5.25; iOS(VDOM): x; iOS(Vapor): 5.25; HarmonyOS(VDOM): x; HarmonyOS(Vapor): 5.25 | 对背景内容添加高斯模糊(Gaussian Blur)滤镜效果 |
其中 blur() 是毛玻璃效果的核心函数,参数为模糊半径,例如 backdrop-filter: blur(4px) 表示对背景做半径为 4px 的高斯模糊。文档当前列出 none 与 blur() 两种取值,<filter-function-list> 中的其他滤镜函数(如亮度、对比度、饱和度等)在 uni-app x 各端的具体支持情况,可查阅 CSS 方法文档 及各端发布说明确认。
完整示例:毛玻璃控制面板与动态调节
以下示例来自 hello uni-app x 的 backdrop-filter 演示页(hello uni-app x alpha 分支对应源码,与最新 HBuilderX Alpha 版同步;master 分支示例与最新正式版同步),完整演示了静态毛玻璃、动态调节模糊半径、背景颜色与边框宽度,以及元素后方滚动内容透出的效果。
<template>
<view class="page-root uni-theme-root">
<fps />
<!-- 控制面板:模糊半径 / 背景颜色 / 边框宽度 -->
<view class="control-panel">
<view class="control-section">
<text class="control-label">模糊半径</text>
<slider class="control-wrapper"
:min="0"
:max="15"
:step="1"
:value="blurValue"
:show-value="true"
@changing="updateBlurValue"
@change="updateBlurValue"
/>
</view>
<view class="control-section">
<text class="control-label">背景颜色</text>
<view class="control-wrapper">
<radio-group class="radio-group" @change="updateBackgroundColor">
<radio class="control-radio" value="rgba(255, 255, 255, 0.3)" :checked="backgroundColor == 'rgba(255, 255, 255, 0.3)'">白色</radio>
<radio class="control-radio" value="rgba(255, 0, 0, 0.3)" :checked="backgroundColor == 'rgba(255, 0, 0, 0.3)'">红色</radio>
<radio class="control-radio" value="rgba(0, 255, 0, 0.3)" :checked="backgroundColor == 'rgba(0, 255, 0, 0.3)'">绿色</radio>
<radio class="control-radio" value="rgba(0, 0, 255, 0.3)" :checked="backgroundColor == 'rgba(0, 0, 255, 0.3)'">蓝色</radio>
</radio-group>
</view>
</view>
<view class="control-section">
<text class="control-label">边框宽度</text>
<slider class="control-wrapper"
:min="0"
:max="20"
:step="1"
:value="borderWidthValue"
:show-value="true"
@changing="updateBorderWidth"
@change="updateBorderWidth"
/>
</view>
</view>
<!-- 悬浮展示层:毛玻璃 box 叠加在可滚动内容之上 -->
<view class="scroll-panel">
<view class="floating-display-layer">
<view class="demo-section">
<view class="demo-slot">
<view class="glass-box" style="backdrop-filter: blur(4px);"></view>
<text class="demo-label">静态 4px</text>
</view>
<view class="demo-slot">
<view class="glass-box" style="backdrop-filter: blur(8px);"></view>
<text class="demo-label">静态 8px</text>
</view>
<view class="demo-slot">
<view class="glass-box" style="backdrop-filter: blur(12px);"></view>
<text class="demo-label">静态 12px</text>
</view>
</view>
<view class="demo-section">
<view class="demo-slot">
<view class="glass-box" :style="`backdrop-filter: blur(${blurValue}px);`"></view>
<text class="demo-label">动态 {{ blurValue }}px</text>
</view>
<view class="demo-slot">
<view class="glass-box" :style="`backdrop-filter: blur(${blurValue}px); background-color: ${backgroundColor}; border-width: ${borderWidthValue}px;`"></view>
<view class="demo-label demo-label-stack">
<text class="demo-label-text">动态 {{ blurValue }}px</text>
<text class="demo-label-text">{{ colorLabel }} / {{ borderWidthValue }}px</text>
</view>
</view>
<view class="demo-slot"></view>
</view>
</view>
<!-- 可滚动背景内容:毛玻璃背后透出的“素材” -->
<scroll-view class="content-scroll-view" direction="vertical" :show-scrollbar="true">
<view class="background-content">
<view v-for="section in backgroundSections" :key="section" class="uni-common-mb">
<view class="logo-row">
<image v-for="logoIndex in logoIndexes" :key="logoIndex" class="logo-item" src="/static/test-image/logo.png" mode="widthFix"></image>
</view>
<view class="uni-row uni-common-mt">
<view v-for="(color, colorIndex) in solidColors1" :key="colorIndex" class="color-box" :style="`background-color: ${color};`"></view>
</view>
<view class="uni-row">
<view v-for="(color, colorIndex) in solidColors2" :key="colorIndex" class="color-box" :style="`background-color: ${color};`"></view>
</view>
<view class="uni-row uni-common-mt">
<view v-for="(gradientStyle, gradientIndex) in gradientStyles1" :key="gradientIndex" class="color-box" :style="gradientStyle"></view>
</view>
<view class="uni-row">
<view v-for="(gradientStyle, gradientIndex) in gradientStyles2" :key="gradientIndex" class="color-box" :style="gradientStyle"></view>
</view>
<view class="uni-common-mt uni-common-mb">
<text class="sample-line uni-common-mb" v-for="(line, lineIndex) in sampleLines" :key="lineIndex">{{ line }}</text>
</view>
</view>
</view>
</scroll-view>
</view>
</view>
</template>
<script setup lang="uts">
const backgroundSections = [1, 2, 3, 4, 5, 6]
const logoIndexes = [1, 2, 3]
const solidColors1 = ['#ff0000', '#00ff00', '#ff0000', '#00ff00', '#ff0000', '#00ff00']
const solidColors2 = ['#0000ff', '#000000', '#0000ff', '#000000', '#0000ff', '#000000']
const gradientStyles1 = [
'background-image: linear-gradient(45deg, #ff0000, #ffffff);',
'background-image: linear-gradient(90deg, #00ff00, #ffffff);',
'background-image: linear-gradient(45deg, #ff0000, #ffffff);',
'background-image: linear-gradient(90deg, #00ff00, #ffffff);',
'background-image: linear-gradient(45deg, #ff0000, #ffffff);',
'background-image: linear-gradient(90deg, #00ff00, #ffffff);'
]
const gradientStyles2 = [
'background-image: linear-gradient(0deg, #0000ff, #ffffff);',
'background-image: linear-gradient(135deg, #000000, #ffffff);',
'background-image: linear-gradient(0deg, #0000ff, #ffffff);',
'background-image: linear-gradient(135deg, #000000, #ffffff);',
'background-image: linear-gradient(0deg, #0000ff, #ffffff);',
'background-image: linear-gradient(135deg, #000000, #ffffff);'
]
const sampleLines = Array.from({ length: 20 }, () : string => 'uni-app x 蒸汽模式 uni-app x 蒸汽模式')
const blurValue = ref(8)
const borderWidthValue = ref(2)
const backgroundColor = ref('rgba(255, 255, 255, 0.3)')
const colorLabel = ref('白色')
const updateBlurValue = (event : UniSliderChangeEvent) => {
blurValue.value = event.detail.value
}
const updateBorderWidth = (event : UniSliderChangeEvent) => {
borderWidthValue.value = event.detail.value
}
const updateBackgroundColor = (event : UniRadioGroupChangeEvent) => {
backgroundColor.value = event.detail.value
if (event.detail.value == 'rgba(255, 0, 0, 0.3)') {
colorLabel.value = '红色'
} else if (event.detail.value == 'rgba(0, 255, 0, 0.3)') {
colorLabel.value = '绿色'
} else if (event.detail.value == 'rgba(0, 0, 255, 0.3)') {
colorLabel.value = '蓝色'
} else {
colorLabel.value = '白色'
}
}
</script>
<style>
.page-root {
flex: 1;
}
.control-panel {
padding: 20px;
}
.scroll-panel {
flex: 1;
position: relative;
}
.content-scroll-view {
flex: 1;
}
.background-content {
padding: 10px 20px 80px 20px;
}
/* 悬浮展示层:position: absolute 盖在滚动内容上方,z-index 高于背景 */
.floating-display-layer {
position: absolute;
top: 20px;
left: 20px;
right: 20px;
pointer-events: none;
z-index: 10;
}
.logo-row {
flex-direction: row;
justify-content: space-between;
margin-bottom: 12px;
}
.logo-item {
width: 33%;
}
.color-box {
flex: 1;
height: 64px;
}
.demo-section {
flex-direction: row;
justify-content: space-between;
margin-bottom: 16px;
}
.demo-slot {
flex: 1;
align-items: center;
}
.demo-label {
margin: 4px;
background-color: rgba(255, 255, 255, 0.9);
padding: 4px 6px;
box-shadow: 3px 3px 3px gray;
color: #1a1a1a;
}
.demo-label-text {
color: #1a1a1a;
}
/* 毛玻璃盒子:半透明背景 + backdrop-filter 模糊 */
.glass-box {
width: 100px;
height: 100px;
background-color: rgba(255, 255, 255, 0.3);
border-width: 1px;
border-style: solid;
border-color: rgba(255, 255, 255, 0.4);
border-radius: 16px;
}
.demo-label-stack {
align-items: center;
}
.control-section {
flex-direction: row;
align-items: center;
background-color: var(--list-background-color, rgba(255, 255, 255, 0.9));
margin-bottom: 6px;
padding: 5px 10px;
}
.control-label {
margin-right: 10px;
color: var(--text-color, #1a1a1a);
}
.control-radio {
color: var(--text-color, #1a1a1a);
}
.sample-line {
color: var(--text-color, #333333);
}
.control-wrapper {
flex: 1;
}
.radio-group {
flex-direction: row;
justify-content: space-around;
}
</style>
该示例在仓库结构上对应 src/pages/CSS 目录 下的样式演示页体系,页面通过 script setup lang="uts"(uts 脚本)管理响应式状态,配合 slider、radio-group 等内置组件实时改写 backdrop-filter 的模糊半径与盒子的半透明背景色。
示例中的关键实现要点
- 半透明背景是前提:
glass-box使用background-color: rgba(255, 255, 255, 0.3),透明度 0.3,让后方内容能够透出并被blur()模糊; - 悬浮层定位:
.floating-display-layer使用position: absolute配合top/left/right与z-index: 10盖在scroll-view滚动内容之上,从而持续对动态滚动的内容做实时背景模糊; - 动态样式绑定:通过
:style="backdrop-filter: blur(${blurValue}px); ..."模板字符串将响应式变量直接拼入内联样式,实现滑块拖动时毛玻璃半径实时变化; - 背景内容丰富化:背景层包含纯色块、
linear-gradient渐变块、logo 图片与文本行,便于直观验证模糊对各类背景素材的处理效果。
在 uni-app x 中 backdrop-filter 的典型应用场景
从仓库文档可以交叉验证 backdrop-filter 在 uni-app x 中的主流用法:
- 悬浮毛玻璃 tabbar:pages.json 配置文档 指出,
glassEffect的液态玻璃是 iOS 26 专有技术;如需在其他平台使用悬浮毛玻璃 tabbar,可在非 iOS 平台通过条件编译使用 CSS 的backdrop-filter实现。启用玻璃效果 tabbar 后,tabbar 以悬浮方式覆盖在页面内容上方,页面不再以 tabbar 顶部作为底部边界,而是延伸到屏幕底部。 - 毛玻璃卡片/面板:uni-ui x 的 uni-tab-bar 组件文档 中给出了“半透明毛玻璃”示例,其原理正是“半透明背景 + backdrop-filter”,让底部内容自然透出并形成毛玻璃效果。
- 悬浮操作按钮、顶部导航:任何需要“内容滚动穿过但保持可读”的悬浮层,都可通过
backdrop-filter提升可读性与质感。
毛玻璃 ≠ iOS 液态玻璃
官方文档特别提示:毛玻璃并非 iOS 液态玻璃(Liquid Glass)。
- iOS 26 及以上的液态玻璃是系统专有效果,由 glass-effect-view 组件 提供:iOS 26 及以上使用系统液态玻璃效果,iOS 26 以下降级为系统毛玻璃效果(
regular映射系统标准毛玻璃,clear映射更轻、更透明的毛玻璃,此时interactive、tint-color属性不生效); - 液态玻璃与毛玻璃在显示效果、触摸效果上并不一样;
- 如需在 Android、HarmonyOS、Web 等其他平台实现毛玻璃,应使用本文档的 CSS
backdrop-filter。
从组件兼容性表看,glass-effect-view 目前仅支持 iOS 系统版本 15.0 及以上(iOS Vapor 5.25),而 backdrop-filter 是跨 Web 与 Android/iOS/HarmonyOS Vapor 的通用方案,两者按平台与效果需求互补使用。
性能与使用建议
- 背景模糊需要实时采样并合成背景内容,模糊半径越大、覆盖区域越大,GPU 合成开销越高。建议控制毛玻璃浮层的数量、面积与模糊半径,避免在长列表高频复用的行内大量使用(glass-effect-view 文档 对玻璃类效果有同样的性能提醒);
- 由于 VDOM 模式(Android/iOS/HarmonyOS 的 VDOM)暂不支持
backdrop-filter,在需要同时覆盖 VDOM 与 Vapor 场景时,应通过条件编译提供降级样式(如纯半透明背景); - 验证效果请以支持平台的真实设备/模拟器为准,Web 端可结合 CSS 与 Web 的差异说明 对比标准 CSS 行为。
参见
- MDN Reference(标准 CSS 定义与浏览器行为)
- 相关 Bug 反馈入口(uni-app x 属性级问题跟踪)
- glass-effect-view 组件文档(iOS 液态玻璃/系统毛玻璃)
- pages.json tabbar 配置(glassEffect 悬浮玻璃 tabbar)
- uni-tab-bar 毛玻璃示例(半透明背景 + backdrop-filter 实战)