uni-app x 玻璃效果组件 glass-effect-view 实战指南:iOS 液态玻璃与毛玻璃降级方案

原创2026-09-20 18:34:262,825 阅读
文章标签:示例工程前端移动开发

uni-app x 玻璃效果组件 glass-effect-view 实战指南:iOS 液态玻璃与毛玻璃降级方案

本文档对应仓库中的 docs/component/glass-effect-view.md,是 uni-app x 平台玻璃效果视图容器的权威说明。glass-effect-view 是 uni-app x 专为 iOS 平台提供的玻璃效果容器组件:在 iOS 26 及以上使用系统原生液态玻璃(Liquid Glass)效果,在 iOS 26 以下自动降级为系统毛玻璃效果。阅读本文后,你将掌握该组件的兼容性边界、三个核心属性的取值与生效条件、与 pages.json 中 tabbar 玻璃效果的选型差异,以及如何在 uvue 页面中组合使用 glass-style、interactive、tint-color 实现顶部返回箭头、悬浮按钮等玻璃质感 UI。

组件定位与适用场景

glass-effect-view 的组件类型为 UniGlassEffectViewElement,是一个玻璃效果视图容器。它并非通用的跨平台毛玻璃组件,而是围绕 iOS 系统玻璃材质能力封装的原生容器:

  • iOS 26 及以上:使用系统**液态玻璃(Liquid Glass)**效果;
  • iOS 26 以下:降级为系统毛玻璃效果。

基于这一特性,该组件最典型的应用场景是:在 iOS 26 以上制作顶部的左上返回箭头,或右上悬浮按钮。这类悬浮控件覆盖在滚动内容之上,使用玻璃材质可以既保持内容可读性,又保留背景的动态观感。

需要特别说明的是:液态玻璃 tabbar 一般不使用本组件,而是在 pages.json 中配置 tabbar 的 glassEffect 属性。如果坚持用 glass-effect-view 实现 tabbar,自定义性会强于 pages.json 的 tabbar,但无法实现 iOS UITabBar 左右滑动 item 的动效——这是系统 UITabBar 独有的交互能力,自定义玻璃容器无法复刻。

兼容性:仅 iOS 生效,且与蒸汽模式版本强绑定

组件兼容性由官方文档表格给出,注意其中的「iOS 系统版本」指 App 运行所在设备的系统版本,而「iOS(Vapor)」指 uni-app x 编译工具的版本要求:

Web 微信小程序 Android iOS 系统版本 iOS(VDOM) iOS(Vapor) HarmonyOS
不支持 不支持 不支持 15.0 不支持 5.25 不支持

从该表格可以得到两个关键结论:

  1. 平台范围:本组件仅在 iOS App 平台可用,Web、微信小程序、Android、HarmonyOS 均不支持。官方示例也明确提示"该 API 不支持 Web,请运行 hello uni-app x 到 App 平台体验"。
  2. 编译模式:只有 iOS(Vapor) 蒸汽模式(编译工具版本 5.25+)才支持该组件,iOS 的 VDOM 模式不支持。这与 uni-app x 蒸汽模式的推出节奏一致——在 docs/app-vapor.md 中说明"HBuilderX 5.11+,iOS 支持蒸汽模式",而 docs/release-note-alpha.md 同时记录了"iOS平台 蒸汽模式 新增 pages.json 中的 tabbar 支持液态玻璃效果"与"iOS平台 蒸汽模式 新增 组件 glass-effect-view 液态玻璃"两条里程碑,说明液态玻璃能力是蒸汽模式渲染管线下的原生能力。在 docs/select/native-render-and-self-render.md 中也强调:蒸汽模式提供的内置液态玻璃组件使用系统原生能力,因而不会带来完全自渲染方案的问题。

iOS 26 以下的降级行为

液态玻璃是 iOS 26 起提供的专有技术,因此组件在低版本系统上的表现需要开发者明确:

  • iOS 26 以下:组件降级为系统毛玻璃效果。此时 glass-style 的取值映射关系为:
    • "regular" 映射为系统标准毛玻璃材质;
    • "clear" 映射为更轻、更透明的毛玻璃材质;
    • interactive、tint-color 两个属性不生效。
  • iOS 26 及以上:使用系统液态玻璃,interactive 与 tint-color 才开始生效。

液态玻璃与毛玻璃在显示效果、触摸效果上并不一样。文档明确建议:如需在其他平台(如 Android、Web、HarmonyOS)使用毛玻璃效果,应改用 CSS 的 backdrop-filter。backdrop-filter 是跨平台的背景滤镜方案,在 Android(Vapor) 5.25、iOS(Vapor) 5.25、HarmonyOS(Vapor) 5.25 等平台上均可用 blur() 实现毛玻璃高斯模糊,详见 docs/css/backdrop-filter.md 中的兼容性表格与示例。

属性详解

组件共暴露三个属性,完整参数如下:

名称 类型 默认值 兼容性 描述
glass-style string "regular" Web: x; 微信小程序: x; Android: x; iOS 系统版本: 15.0; iOS(VDOM): x; iOS(Vapor): 5.25; HarmonyOS: x 玻璃效果样式
interactive boolean false Web: x; 微信小程序: x; Android: x; iOS 系统版本: 26.0; iOS(VDOM): x; iOS(Vapor): 5.25; HarmonyOS: x 是否启用液态玻璃的交互行为,仅 iOS 26 及以上生效
tint-color string(string.ColorString) 无 Web: x; 微信小程序: x; Android: x; iOS 系统版本: 26.0; iOS(VDOM): x; iOS(Vapor): 5.25; HarmonyOS: x 施加在液态玻璃效果上的着色,仅 iOS 26 及以上生效

各属性要点:

  • glass-style(玻璃效果样式):唯一不依赖 iOS 26 的属性,iOS 15.0 及以上即生效。合法值如下:

    合法值 描述
    regular 常规玻璃效果
    clear 更通透的玻璃效果
  • interactive(启用交互行为):类型为 boolean,默认 false,仅 iOS 26 及以上生效。启用后液态玻璃会对用户的触摸产生形变、位移等系统级反馈,属于 Liquid Glass 的核心交互体验。

  • tint-color(玻璃效果着色):类型为 string,取值是 ColorString 字符串——也就是 uni-app x 中 docs/uts/data-type.md 定义的字符串类型,可传入 'transparent'、'#RRGGBB'、'rgba(r, g, b, a)' 等颜色写法。它用于在液态玻璃效果上叠加一层着色,仅 iOS 26 及以上生效。

关于 ColorString 的更多合法写法,可参考 docs/uts/data-type.md#ide-string。

子组件:支持所有组件

glass-effect-view 作为容器组件,子组件支持所有组件。即其内部可以放置 view、text、image、按钮乃至任意自定义组件,玻璃材质会作用于其背景,容器内的内容正常叠加渲染。这为构建悬浮按钮、气泡面板等复杂玻璃 UI 提供了自由度。

完整示例:玻璃面板 + 着色 + 交互开关

官方文档提供了与 hello uni-app x 项目同步的 uvue 示例。下面完整保留该示例:页面顶部是一个由五色块与 GLASS/iOS 文字构成的舞台,中间叠加一块 glass-effect-view 玻璃面板,下方通过三个控件分别切换 glass-style、interactive 与 tint-color。

<template>
  <page-head title="glass-effect-view"></page-head>
  <scroll-view style="flex: 1">
    <view class="uni-padding-wrap uni-common-mt">
      <text class="uni-title-text">玻璃效果预览</text>
      <view class="stage">
        <view class="color-row">
          <view class="color-block color-red"></view>
          <view class="color-block color-yellow"></view>
          <view class="color-block color-green"></view>
          <view class="color-block color-blue"></view>
          <view class="color-block color-purple"></view>
        </view>
        <text class="stage-text stage-text-top">GLASS</text>
        <text class="stage-text stage-text-bottom">iOS</text>
        <glass-effect-view
          v-if="data.glassStyle == 'regular'"
          class="glass-panel"
          glass-style="regular"
          :interactive="data.interactive"
          :tint-color="data.tintColor">
          <view class="glass-content">
            <text class="glass-title">regular</text>
            <text class="glass-detail">interactive: {{ data.interactive }}</text>
            <text class="glass-detail">tint: {{ data.tintColor }}</text>
          </view>
        </glass-effect-view>
        <glass-effect-view
          v-else
          class="glass-panel"
          glass-style="clear"
          :interactive="data.interactive"
          :tint-color="data.tintColor">
          <view class="glass-content">
            <text class="glass-title">clear</text>
            <text class="glass-detail">interactive: {{ data.interactive }}</text>
            <text class="glass-detail">tint: {{ data.tintColor }}</text>
          </view>
        </glass-effect-view>
      </view>
    </view>

    <view class="content">
      <enum-data
        title="glass-style 玻璃效果样式"
        :items="data.glassStyleItems"
        @change="changeGlassStyle"></enum-data>
      <boolean-data
        title="interactive 启用交互行为"
        :defaultValue="false"
        @change="changeInteractive"></boolean-data>
      <enum-data
        title="tint-color 玻璃效果着色"
        :items="data.tintColorItems"
        @change="changeTintColor"></enum-data>
      <view class="bottom-space"></view>
    </view>
  </scroll-view>
</template>

<script setup lang="uts">
  import { ItemType } from '@/components/enum-data/enum-data-types'

  type DataType = {
    glassStyle : string;
    interactive : boolean;
    tintColor : string;
    glassStyleItems : ItemType[];
    tintColorItems : ItemType[];
  }

  const data = reactive({
    glassStyle: 'regular',
    interactive: false,
    tintColor: 'transparent',
    glassStyleItems: [
      { value: 0, name: 'regular', checked: true },
      { value: 1, name: 'clear' },
    ],
    tintColorItems: [
      { value: 0, name: '透明', checked: true },
      { value: 1, name: '红色' },
      { value: 2, name: '蓝色' },
      { value: 3, name: '绿色' },
    ],
  } as DataType)

  function changeGlassStyle(value : number) {
    data.glassStyle = value == 1 ? 'clear' : 'regular'
  }

  function changeInteractive(value : boolean) {
    data.interactive = value
  }

  function changeTintColor(value : number) {
    switch (value) {
      case 1:
        data.tintColor = 'rgba(255, 59, 48, 0.25)'
        break
      case 2:
        data.tintColor = 'rgba(0, 122, 255, 0.25)'
        break
      case 3:
        data.tintColor = 'rgba(52, 199, 89, 0.25)'
        break
      default:
        data.tintColor = 'transparent'
        break
    }
  }

  defineExpose({
    data,
  })
</script>

<style>
  .stage {
    position: relative;
    height: 300px;
    margin-top: 12px;
    overflow: hidden;
    border-radius: 8px;
    background-color: #ffffff;
  }

  .color-row {
    position: absolute;
    left: 0;
    right: 0;
    top: 0;
    bottom: 0;
    flex-direction: row;
  }

  .color-block {
    flex: 1;
  }

  .color-red {
    background-color: #ff453a;
  }

  .color-yellow {
    background-color: #ffd60a;
  }

  .color-green {
    background-color: #30d158;
  }

  .color-blue {
    background-color: #0a84ff;
  }

  .color-purple {
    background-color: #bf5af2;
  }

  .stage-text {
    position: absolute;
    font-size: 48px;
    font-weight: 700;
    color: #ffffff;
  }

  .stage-text-top {
    left: 18px;
    top: 18px;
  }

  .stage-text-bottom {
    right: 18px;
    bottom: 18px;
  }

  .glass-panel {
    position: absolute;
    left: 42px;
    right: 42px;
    top: 74px;
    height: 152px;
    border-radius: 28px;
    overflow: hidden;
  }

  .glass-content {
    flex: 1;
    justify-content: center;
    align-items: center;
  }

  .glass-title {
    font-size: 24px;
    font-weight: 700;
    color: #111111;
  }

  .glass-detail {
    margin-top: 8px;
    font-size: 13px;
    color: #222222;
  }

  .content {
    margin-top: 10px;
  }

  .bottom-space {
    height: 30px;
  }
</style>

示例的实操要点:

  • 舞台搭建:.stage 容器使用五块全高色块(红/黄/绿/蓝/紫)作为玻璃的背景采样源,叠加 GLASS、iOS 白色大字,玻璃面板绝对定位悬浮于色块之上,便于肉眼观察玻璃对背景的模糊与着色效果。
  • 双面板切换:通过 v-if="data.glassStyle == 'regular'" 在 regular 与 clear 两种样式间切换渲染,直观对比两种材质的通透度差异。
  • 动态属性绑定:interactive、tint-color 均通过 :interactive、:tint-color 动态绑定,配合 boolean-data 与 enum-data 控件实时修改。tint-color 的四个可选值中,三种颜色均使用 rgba(..., 0.25) 的低透明度写法,说明着色应当是半透明的,否则会遮挡背景,玻璃感会消失。
  • 数据驱动:脚本部分使用组合式 API(<script setup lang="uts">)与 reactive 管理状态,changeGlassStyle、changeInteractive、changeTintColor 三个回调分别对应三个控件的事件。

需要提醒:该示例依赖 @/components/enum-data/enum-data-types 的 ItemType 类型与 enum-data、boolean-data 两个演示组件,可直接参考仓库 src/components/enum-data 与 src/components/boolean-data 目录中的实现。

选型对比:组件实现 vs pages.json glassEffect tabbar

对于液态玻璃 tabbar,文档明确建议使用 pages.json 中 tabbar 的 glassEffect 属性,而非 glass-effect-view 组件。两者的取舍如下:

维度 pages.json 的 glassEffect tabbar glass-effect-view 组件自定义 tabbar
动效 保留 iOS UITabBar 左右滑动 item 的动效 无法实现 UITabBar 的滑动动效
自定义性 较低,受系统 tabbar 约束 更高,可自由布局
推荐度 官方推荐 仅适合特殊自定义需求

pages.json 中 glassEffect 的配置项为 boolean 类型,默认 false,兼容性为 iOS 系统版本 15.0 / iOS(Vapor) 5.25,启用后仅支持图片图标,不支持 iconfont(详见 docs/collocation/pagesjson.md 的 tabbar 配置说明)。启用后的布局行为也值得注意:

  • 启用后,iOS 所有支持版本均使用系统 UITabBar;iOS 26 及以上,backgroundColor、borderStyle、color 和 height 属性将无效,玻璃材质的具体表现由系统版本决定;
  • tabbar 以悬浮方式覆盖在页面内容上方,页面不再以 tabbar 顶部作为底部边界,而是延伸到屏幕底部;iOS 26 以下降级为毛玻璃 tabbar 时,页面布局行为保持一致(页面排版高度包含 TabBar 覆盖区域、UniPage.height 返回延伸后的高度、安全区按悬浮 TabBar 计算等);
  • 如果想在非 iOS 平台使用悬浮毛玻璃 tabbar,官方建议用条件编译,在非 iOS 平台下使用 CSS 的 backdrop-filter 实现,页面统一通顶、tabbar 悬浮在安全区上方(相关思路可参见 docs/select/native-render-and-self-render.md 对蒸汽模式原生渲染能力的说明)。

性能注意事项(Tips)

玻璃材质需要实时采样和合成背景内容,这是玻璃效果的本质代价,官方文档给出了明确的性能警告:

大量创建、重叠或在长列表中频繁复用玻璃组件,可能增加 GPU 合成开销造成卡顿。

因此在使用 glass-effect-view 时应当遵循以下实践:

  • 控制玻璃面板的数量,避免一屏内大量堆叠;
  • 避免多层玻璃互相重叠(重叠意味着多次背景采样合成);
  • 在长列表(如 list-view、scroll-view)中不要对每个 item 都复用玻璃组件,优先将玻璃效果用于固定悬浮的头部/底部控件;
  • 必要时用 v-if 在不需要时卸载玻璃组件,而不是长期保留。

仓库中的相关实现与资料线索

以下仓库文件可以帮助你继续深入:

小结

glass-effect-view 是 uni-app x 蒸汽模式在 iOS 平台上的系统级玻璃能力封装:iOS 26 及以上提供液态玻璃(含 interactive 交互与 tint-color 着色),iOS 26 以下自动降级为系统毛玻璃(regular/clear 两种材质)。它最适合制作顶部返回箭头、悬浮按钮等局部玻璃控件;tabbar 场景应优先使用 pages.json 的 glassEffect 配置,而跨平台毛玻璃需求则应转向 CSS 的 backdrop-filter。在使用时务必结合其"仅 iOS(Vapor) 5.25+"的兼容边界,并控制玻璃组件的数量与复用频率,以避免 GPU 合成开销带来的卡顿。

登录后查看全文
uni-app