组件/BaseSurface 基础表面层
自 2.5.0BETA

BaseSurface 基础表面层

统一管理背景渲染策略的基础组件,支持 pure/mask/blur/glass/refraction 五种模式,并通过运动降级机制解决 backdrop-filter + transform 失效问题。

该页面由 AI 迁移生成,请谨慎使用

内容已迁移完成,但仍建议结合源码和人工评审结果使用。

BaseSurface 基础表面层

统一管理背景渲染策略的基础组件 — 支持 pure(纯色)、mask(透明遮罩)、blur(filter)、glass(glass)、refraction(glass+filter)五种模式,并通过运动降级机制自动解决 Chromium 已知的 backdrop-filter + transform 失效 bug。

支持 fake 伪元素模式渲染(与现有 .fake-background 一致),暗色模式通过 CSS 变量体系自动切换。

与 TxCard 的关系

  • 需要业务层开箱即用(header/footer/loading/inertial/交互态)时,用 TxCard
  • 需要底层材质调参(filter/refraction/glass 参数矩阵)时,用 TxBaseSurface
  • 推荐做法:TxCard 负责容器语义与交互,TxBaseSurface 负责材质渲染。

背景模式

五种模式对比:pure 纯色、mask 带透明度遮罩、blur 背景模糊、glass 玻璃层、refraction 折射层。

模式对比

示例即将加载...
<template>
  <div style="display: flex; gap: 16px; flex-wrap: wrap;">
    <TxBaseSurface mode="pure" style="width: 140px; height: 80px; display: flex; align-items: center; justify-content: center;">
      纯色
    </TxBaseSurface>
    <TxBaseSurface mode="mask" :opacity="0.6" style="width: 140px; height: 80px; display: flex; align-items: center; justify-content: center;">
      遮罩
    </TxBaseSurface>
    <TxBaseSurface mode="blur" :blur="8" style="width: 140px; height: 80px; display: flex; align-items: center; justify-content: center;">
      模糊
    </TxBaseSurface>
    <TxBaseSurface mode="glass" :blur="12" :saturation="1.8" style="width: 140px; height: 80px; display: flex; align-items: center; justify-content: center;">
      毛玻璃
    </TxBaseSurface>
  </div>
</template>

底层参数实验(Advanced)

用于材质层调参的低层实验台,适合探索 filter / refraction 的参数组合;若是业务卡片场景,仍建议优先使用 TxCard

Advanced Lab

示例即将加载...
<script setup lang="ts">
import { ref } from 'vue'

const mode = ref<'blur' | 'glass' | 'refraction'>('refraction')
const profile = ref<'soft' | 'filmic' | 'cinematic'>('filmic')
const blur = ref(24)
const filterSaturation = ref(1.6)
const filterContrast = ref(1.05)
const filterBrightness = ref(1.02)

const refractionStrength = ref(68)
const refractionAngle = ref(-24)
const refractionHaloOpacity = ref(0.42)
</script>

<template>
  <TxBaseSurface
    :mode="mode"
    preset="card"
    :radius="18"
    :blur="blur"
    :filter-saturation="filterSaturation"
    :filter-contrast="filterContrast"
    :filter-brightness="filterBrightness"
    :refraction-profile="profile"
    :refraction-strength="refractionStrength"
    :refraction-angle="refractionAngle"
    :refraction-halo-opacity="refractionHaloOpacity"
    style="min-height: 180px; padding: 16px;"
  >
    BaseSurface Advanced
  </TxBaseSurface>
</template>

Fake 伪元素模式

通过 fake prop 启用伪元素渲染背景,slot 内容自然在背景上层,无需额外 z-index 管理。适合需要与现有 .fake-background 模式保持一致的场景。

Fake 模式

示例即将加载...
<template>
  <div style="display: flex; gap: 16px; flex-wrap: wrap;">
    <TxBaseSurface fake mode="mask" :opacity="0.5" :radius="12" style="width: 200px; height: 100px;">
      <strong>伪元素背景</strong>
      <span style="font-size: 12px; opacity: 0.7;">slot 内容自然在背景上层</span>
    </TxBaseSurface>
    <TxBaseSurface fake mode="pure" :radius="12" color="var(--tx-color-primary-light-9)" style="width: 200px; height: 100px;">
      自定义颜色
    </TxBaseSurface>
  </div>
</template>

运动降级

blurglass 模式的元素处于 CSS transform 运动中时,backdrop-filter 会失效(Chromium 已知 bug)。

通过 moving prop 手动控制降级,或 auto-detect 自动检测 transform 变化,自动降级到 fallbackMode(默认 mask),运动结束后平滑恢复。

点击按钮后,blur 和 glass 卡片会真正进行 transform 位移,同时自动降级到 mask 模式。卡片内部内容可滚动。

多模式运动降级

示例即将加载...
<script setup lang="ts">
import { ref } from 'vue'

const animating = ref(false)
</script>

<template>
  <TxBaseSurface
    mode="glass"
    :blur="12"
    :moving="animating"
    fallback-mode="mask"
    :radius="14"
  >
    <div style="max-height: 140px; overflow-y: auto;">
      可滚动内容...
    </div>
  </TxBaseSurface>
  <TxButton @click="animating = !animating">
    {{ animating ? '停止' : '开始运动' }}
  </TxButton>
</template>

原生 vs BaseSurface 对比

左侧使用原生 backdrop-filter,运动时模糊效果直接失效变透明;右侧使用 BaseSurface,运动时平滑降级为 mask 遮罩,停止后恢复毛玻璃。

运动对比

示例即将加载...
<script setup lang="ts">
import { ref } from 'vue'

const animating = ref(false)
</script>

<template>
  <!-- 左:原生,运动时 backdrop-filter 失效 -->
  <div :style="{ transform: animating ? 'translateX(20px)' : '' }"
       style="backdrop-filter: blur(12px); transition: transform 1.2s;">
    原生 glass(运动时失效)
  </div>

  <!-- 右:BaseSurface 自动降级 -->
  <TxBaseSurface mode="glass" :blur="12" :moving="animating"
                 fallback-mode="mask" :radius="14">
    BaseSurface(运动时降级为 mask)
  </TxBaseSurface>
</template>

API

TxBaseSurface Props

属性名类型默认值说明
mode'pure' | 'mask' | 'blur' | 'glass' | 'refraction''pure'背景模式(对应纯色 / 遮罩 / 滤镜 / 玻璃 / 折射)。
radiusstring | number-自定义圆角,不传则继承父元素。
colorstring-纯色或遮罩底色。
opacitynumber0.75mask 模式透明度(0-1)。
fallbackMaskOpacitynumber-降级到 mask 时覆盖透明度(0-1)。
blurnumber10filter 层模糊强度(px)。
filterSaturationnumber1.5filter 层饱和度(底层细调)。
filterContrastnumber1filter 层对比度(底层细调)。
filterBrightnessnumber1filter 层亮度(底层细调)。
saturationnumber1.8glass/refraction 的玻璃层饱和度。
brightnessnumber70glass/refraction 的玻璃层亮度。
backgroundOpacitynumber0glass 层背景透明度。
borderWidthnumber0.07glass 层边缘宽度系数。
displacenumber0.5refraction 位移强度。
distortionScalenumber-180refraction 扭曲缩放。
redOffset / greenOffset / blueOffsetnumber0 / 10 / 20RGB 通道偏移(底层色散控制)。
xChannel / yChannel'R' | 'G' | 'B''R' / 'G'refraction 位移取样通道。
mixBlendModestring'difference'refraction 混合模式。
refractionStrengthnumber-0-100,统一控制折射强度。
refractionProfile'soft' | 'filmic' | 'cinematic'-折射风格预设。
refractionTone'mist' | 'balanced' | 'vivid''balanced'折射色调预设(vivid 更通透,mist 更柔和)。
refractionAnglenumber-色散主方向角度(度)。
refractionLightX / refractionLightYnumber-光源锚点(0-1)。
refractionHaloOpacitynumber-halo 透明度(0-1),不传时用内置 filmic 模型。
overlayOpacitynumber0非 mask 模式下附加 mask 层透明度。
preset'default' | 'card''default'视觉预设(card 为卡片风格调校)。
refractionRenderer'svg' | 'css''svg'refraction 渲染器类型。
movingbooleanfalse手动标记是否处于运动中。
fallbackMode'pure' | 'mask''mask'运动降级模式。
settleDelaynumber150结束运动后恢复延迟(ms)。
autoDetectbooleanfalse自动检测 transform 触发降级。
transitionDurationnumber260过渡时长(ms)。
fakebooleanfalse是否使用 fake 伪元素渲染。
fakeIndexnumber0fake 层 z-index。
tagstring'div'根元素标签名。

Slots

插槽名说明
default表面层内容

CSS 变量

变量名说明亮色默认值暗色默认值
--tx-surface-color纯色/遮罩背景色var(--tx-fill-color-lighter) (#fafafa)#1d1d1d
--tx-surface-blur-bgblur/glass 半透明底色rgba(255,255,255,0.6)rgba(0,0,0,0.4)

交互契约

  • tag 控制根元素标签,默认插槽内容始终渲染在材质层之上。
  • pure 模式只渲染根背景;mask 模式渲染 mask 层并将透明度 clamp 到 0..1
  • blurglassmoving=true 或自动检测到 transform 运动时降级。fallbackMode='mask' 会优先使用 fallbackMaskOpacityfallbackMode='pure' 不渲染 mask 层。
  • glassrefraction 会把归一化后的几何和光学参数透传给 TxGlassSurface
  • refraction 会渲染 glass/filter/mask/edge 层,并暴露 renderer/profile/tone class 与 light/strength CSS 变量。
  • autoDetect 会监听根节点及祖先节点的 style/transition 变化,并在卸载时清理监听器与 observer。