BaseSurface 基础表面层
统一管理背景渲染策略的基础组件,支持 pure/mask/blur/glass/refraction 五种模式,并通过运动降级机制解决 backdrop-filter + transform 失效问题。
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 折射层。
模式对比
底层参数实验(Advanced)
用于材质层调参的低层实验台,适合探索 filter / refraction 的参数组合;若是业务卡片场景,仍建议优先使用 TxCard。
Advanced Lab
Fake 伪元素模式
通过 fake prop 启用伪元素渲染背景,slot 内容自然在背景上层,无需额外 z-index 管理。适合需要与现有 .fake-background 模式保持一致的场景。
Fake 模式
运动降级
当 blur 或 glass 模式的元素处于 CSS transform 运动中时,backdrop-filter 会失效(Chromium 已知 bug)。
通过 moving prop 手动控制降级,或 auto-detect 自动检测 transform 变化,自动降级到 fallbackMode(默认 mask),运动结束后平滑恢复。
点击按钮后,blur 和 glass 卡片会真正进行 transform 位移,同时自动降级到 mask 模式。卡片内部内容可滚动。
多模式运动降级
原生 vs BaseSurface 对比
左侧使用原生 backdrop-filter,运动时模糊效果直接失效变透明;右侧使用 BaseSurface,运动时平滑降级为 mask 遮罩,停止后恢复毛玻璃。
运动对比
API
TxBaseSurface Props
| 属性名 | 类型 | 默认值 | 说明 |
|---|---|---|---|
mode | 'pure' | 'mask' | 'blur' | 'glass' | 'refraction' | 'pure' | 背景模式(对应纯色 / 遮罩 / 滤镜 / 玻璃 / 折射)。 |
radius | string | number | - | 自定义圆角,不传则继承父元素。 |
color | string | - | 纯色或遮罩底色。 |
opacity | number | 0.75 | mask 模式透明度(0-1)。 |
fallbackMaskOpacity | number | - | 降级到 mask 时覆盖透明度(0-1)。 |
blur | number | 10 | filter 层模糊强度(px)。 |
filterSaturation | number | 1.5 | filter 层饱和度(底层细调)。 |
filterContrast | number | 1 | filter 层对比度(底层细调)。 |
filterBrightness | number | 1 | filter 层亮度(底层细调)。 |
saturation | number | 1.8 | glass/refraction 的玻璃层饱和度。 |
brightness | number | 70 | glass/refraction 的玻璃层亮度。 |
backgroundOpacity | number | 0 | glass 层背景透明度。 |
borderWidth | number | 0.07 | glass 层边缘宽度系数。 |
displace | number | 0.5 | refraction 位移强度。 |
distortionScale | number | -180 | refraction 扭曲缩放。 |
redOffset / greenOffset / blueOffset | number | 0 / 10 / 20 | RGB 通道偏移(底层色散控制)。 |
xChannel / yChannel | 'R' | 'G' | 'B' | 'R' / 'G' | refraction 位移取样通道。 |
mixBlendMode | string | 'difference' | refraction 混合模式。 |
refractionStrength | number | - | 0-100,统一控制折射强度。 |
refractionProfile | 'soft' | 'filmic' | 'cinematic' | - | 折射风格预设。 |
refractionTone | 'mist' | 'balanced' | 'vivid' | 'balanced' | 折射色调预设(vivid 更通透,mist 更柔和)。 |
refractionAngle | number | - | 色散主方向角度(度)。 |
refractionLightX / refractionLightY | number | - | 光源锚点(0-1)。 |
refractionHaloOpacity | number | - | halo 透明度(0-1),不传时用内置 filmic 模型。 |
overlayOpacity | number | 0 | 非 mask 模式下附加 mask 层透明度。 |
preset | 'default' | 'card' | 'default' | 视觉预设(card 为卡片风格调校)。 |
refractionRenderer | 'svg' | 'css' | 'svg' | refraction 渲染器类型。 |
moving | boolean | false | 手动标记是否处于运动中。 |
fallbackMode | 'pure' | 'mask' | 'mask' | 运动降级模式。 |
settleDelay | number | 150 | 结束运动后恢复延迟(ms)。 |
autoDetect | boolean | false | 自动检测 transform 触发降级。 |
transitionDuration | number | 260 | 过渡时长(ms)。 |
fake | boolean | false | 是否使用 fake 伪元素渲染。 |
fakeIndex | number | 0 | fake 层 z-index。 |
tag | string | 'div' | 根元素标签名。 |
Slots
| 插槽名 | 说明 |
|---|---|
default | 表面层内容 |
CSS 变量
| 变量名 | 说明 | 亮色默认值 | 暗色默认值 |
|---|---|---|---|
--tx-surface-color | 纯色/遮罩背景色 | var(--tx-fill-color-lighter) (#fafafa) | #1d1d1d |
--tx-surface-blur-bg | blur/glass 半透明底色 | rgba(255,255,255,0.6) | rgba(0,0,0,0.4) |
交互契约
tag控制根元素标签,默认插槽内容始终渲染在材质层之上。pure模式只渲染根背景;mask模式渲染 mask 层并将透明度 clamp 到0..1。blur与glass在moving=true或自动检测到 transform 运动时降级。fallbackMode='mask'会优先使用fallbackMaskOpacity;fallbackMode='pure'不渲染 mask 层。glass与refraction会把归一化后的几何和光学参数透传给TxGlassSurface。refraction会渲染 glass/filter/mask/edge 层,并暴露 renderer/profile/tone class 与 light/strength CSS 变量。autoDetect会监听根节点及祖先节点的 style/transition 变化,并在卸载时清理监听器与 observer。