uni-app x 中 backdrop-filter 背景滤镜(毛玻璃)完整指南

原创2026-09-20 16:10:422,199 阅读
文章标签:示例工程前端移动开发

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 的模糊半径与盒子的半透明背景色。

示例中的关键实现要点

  1. 半透明背景是前提:glass-box 使用 background-color: rgba(255, 255, 255, 0.3),透明度 0.3,让后方内容能够透出并被 blur() 模糊;
  2. 悬浮层定位:.floating-display-layer 使用 position: absolute 配合 top/left/right 与 z-index: 10 盖在 scroll-view 滚动内容之上,从而持续对动态滚动的内容做实时背景模糊;
  3. 动态样式绑定:通过 :style="backdrop-filter: blur(${blurValue}px); ..." 模板字符串将响应式变量直接拼入内联样式,实现滑块拖动时毛玻璃半径实时变化;
  4. 背景内容丰富化:背景层包含纯色块、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 行为。

参见

登录后查看全文
uni-app