BaseSurface 基础表面层
可切换材质并在运动中降级的背景层
用法
模式
mode 选择材质：pure 纯色、mask 半透明遮罩、blur 背景模糊、glass 玻璃、refraction 折射。
示例加载中...
参数实验
filter* 调滤镜层，refraction* 调折射层，preset="card" 套用卡片调校。
示例加载中...
伪元素模式
fake 用伪元素绘制背景，与现有 .fake-background 层级一致，插槽内容自然位于其上。
示例加载中...
运动降级
transform 运动会让 backdrop-filter 失效；设置 moving 后降级为 fallbackMode，停止后平滑恢复。
示例加载中...
与原生对比
拿不到运动状态时开启 autoDetect，由组件监听 transform 过渡自行降级。
示例加载中...
最佳实践
- 业务容器优先用
TxCard，它负责容器语义与交互；只在直接调材质、降级或折射参数时用TxBaseSurface。 - 父层持有动画状态时传
moving；拿不到状态的 transform 过渡才用autoDetect。 blur/glass运动中保持fallbackMode="mask"以保证可读；能接受纯色时才用pure。- 折射优先调
refractionStrength、refractionProfile、refractionTone；RGB 通道偏移只用于视觉实验。 refractionRenderer="css"光学保真度较低，只在页面能接受时使用。
API 参考
属性
| 属性名 | 类型 | 默认值 | 说明 |
|---|---|---|---|
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 | 滤镜层模糊半径（px）。 |
filterSaturation | number | 1.5 | 滤镜层饱和度。 |
filterContrast | number | 1 | 滤镜层对比度。 |
filterBrightness | number | 1 | 滤镜层亮度。 |
saturation | number | 1.8 | glass / refraction 玻璃层的饱和度。 |
brightness | number | 70 | glass / refraction 玻璃层的亮度；<= 3 时视为倍率。 |
backgroundOpacity | number | 0 | 玻璃层的背景透明度。 |
borderWidth | number | 0.07 | 玻璃层的边缘宽度系数。 |
displace | number | 0.5 | 折射位移强度。 |
distortionScale | number | -180 | 折射扭曲缩放。 |
redOffset / greenOffset / blueOffset | number | 0 / 10 / 20 | RGB 通道偏移，控制色散。 |
xChannel / yChannel | 'R' | 'G' | 'B' | 'R' / 'G' | 折射位移的取样通道。 |
mixBlendMode | string | 'difference' | 折射混合模式。 |
refractionStrength | number | 62 | 折射强度（0–100）。 |
refractionProfile | 'soft' | 'filmic' | 'cinematic' | 'filmic' | 折射风格预设。 |
refractionTone | 'mist' | 'balanced' | 'vivid' | 'balanced' | 折射色调：vivid 更通透，mist 更柔和。 |
refractionAngle | number | -24 | 色散主方向（度）。 |
refractionLightX / refractionLightY | number | - | 光源锚点（0–1）。 |
refractionHaloOpacity | number | - | 光晕透明度（0–1）；不传时按内置 filmic 模型。 |
overlayOpacity | number | 0 | 非 mask 模式额外叠加的遮罩透明度。 |
preset | 'default' | 'card' | 'default' | 视觉预设；card 为卡片调校。 |
refractionRenderer | 'svg' | 'css' | 'svg' | 折射渲染器。 |
moving | boolean | false | 标记正在运动，触发降级。 |
fallbackMode | 'pure' | 'mask' | 'mask' | 运动中的降级模式。 |
settleDelay | number | 150 | 运动结束后开始恢复的延迟（ms），不短于 transitionDuration。 |
autoDetect | boolean | false | 自动检测 transform 运动并降级。 |
transitionDuration | number | 299 | 恢复过渡时长（ms）。 |
fake | boolean | false | 用伪元素渲染背景。 |
fakeIndex | number | 0 | 伪元素层的 z-index。 |
tag | string | 'div' | 根元素标签。 |
插槽
| 插槽名 | 参数 | 说明 |
|---|---|---|
default | - | 表面内容，渲染在 .tx-base-surface__content 中，位于所有材质层之上。 |
CSS 变量
| 变量名 | 来源 | 说明 |
|---|---|---|
--tx-surface-color | color prop 或主题兜底 | 纯色 / 遮罩底色，默认 var(--tx-fill-color-lighter, #fafafa)。 |
--tx-surface-radius | radius prop | 根节点与各层圆角；数字转为 px。 |
--tx-surface-transition | transitionDuration prop | 层淡入淡出、背景与 backdrop-filter 的过渡时长。 |
--tx-surface-filter-blur | blur prop | 滤镜层与折射滤镜层的模糊半径。 |
--tx-surface-filter-saturation | filterSaturation prop | 滤镜层饱和度倍率。 |
--tx-surface-filter-contrast | filterContrast prop | 滤镜层对比度倍率。 |
--tx-surface-filter-brightness | filterBrightness prop | 滤镜层亮度倍率。 |
--tx-surface-mask-opacity | opacity、fallbackMaskOpacity 或 overlayOpacity | 当前遮罩透明度，限制在 0..1。 |
--tx-surface-refraction-light-x / --tx-surface-refraction-light-y | refractionLightX / refractionLightY 或角度模型 | 折射光源锚点（百分比）。 |
--tx-surface-refraction-strength | refractionStrength 模型 | 静止、运动与恢复中混合后的光学强度。 |
--tx-surface-fake-index | fakeIndex prop | 伪元素层的 z-index。 |
--tx-surface-fake-bg | color prop 或主题兜底 | 伪元素的背景色。 |
--tx-surface-fake-opacity | mask 透明度模型 | 伪元素的透明度。 |
--tx-surface-mask-opacity-percent | mask 透明度模型 | 遮罩透明度的百分比形式（内部，勿覆写）。 |
--tx-surface-motion-cover-opacity | 运动状态模型 | 折射运动罩的透明度（内部）。 |
--tx-surface-refraction-edge-opacity | 光学模型 | 折射边缘高光的透明度（内部）。 |
--tx-surface-refraction-streak-angle | refractionAngle 模型 | 折射拉丝角度，等于角度 +92deg（内部）。 |
--tx-surface-refraction-{filter,mask}-{base,primary,secondary,veil}-weight / --tx-surface-refraction-streak-weight | profile/tone 权重模型 | 各光学层的混合权重（内部）。 |
--tx-surface-refraction-*-gain / -boost / -base、--tx-surface-refraction-halo-opacity、--tx-surface-refraction-mask-effective-opacity | profile/tone 派生量 | 光学插值的派生输出（内部）。 |
--tx-surface-refraction-mask-color | 主题钩子（消费） | 折射渐变层的基色，可在主题中覆写，默认 #fff 系。 |
概述
pure只渲染根背景；mask渲染遮罩层，透明度限制在0..1。blur、glass在moving或检测到 transform 运动时降级：fallbackMode="mask"优先用fallbackMaskOpacity，pure不渲染遮罩层。refraction运动中不切换模式：失去采样的 glass / blur 层各自淡出，由半透明运动罩接住，停止后交叉淡回。- 显式传入
refractionStrength、refractionAngle、refractionProfile任一项即启用派生折射模型，未传的项按62/-24/'filmic'兜底。 autoDetect监听根节点及祖先的style变化与transitionstart/transitionend/transitioncancel，卸载时移除。
技术实现
- glass 与 refraction 由
TxGlassSurface渲染，降级时序在base-surface-motion.ts。 - 源码：
packages/tuffex/packages/components/src/base-surface/。
查看源码
packages/tuffex/packages/components/src/base-surface/index.ts