uni-app x 玻璃效果组件 glass-effect-view 实战指南:iOS 液态玻璃与毛玻璃降级方案
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 | 不支持 |
从该表格可以得到两个关键结论:
- 平台范围:本组件仅在 iOS App 平台可用,Web、微信小程序、Android、HarmonyOS 均不支持。官方示例也明确提示"该 API 不支持 Web,请运行 hello uni-app x 到 App 平台体验"。
- 编译模式:只有 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在不需要时卸载玻璃组件,而不是长期保留。
仓库中的相关实现与资料线索
以下仓库文件可以帮助你继续深入:
- 组件官方文档:docs/component/glass-effect-view.md;
- tabbar 玻璃效果配置:docs/collocation/pagesjson.md(
glassEffect属性、悬浮 tabbar 布局变化说明); - 跨平台毛玻璃替代方案:docs/css/backdrop-filter.md(
blur()滤镜、各平台兼容性); - 蒸汽模式背景:docs/app-vapor.md(蒸汽模式定义、各平台支持版本)与 docs/select/native-render-and-self-render.md(原生渲染与自渲染对比、液态玻璃组件采用系统原生能力的原因);
- 版本里程碑:docs/release-note-alpha.md(iOS 蒸汽模式新增 glass-effect-view 与 tabbar 液态玻璃的记录);
- 演示组件源码:仓库 src/components/enum-data、src/components/boolean-data 中
enum-data、boolean-data的实现可供示例复用参考。
小结
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 合成开销带来的卡顿。