---
title: "BaseSurface 基础表面层"
description: "可切换材质并在运动中降级的背景层"
category: Primitives
status: beta
since: 0.3.4
tags: [surface, background, blur, glass, backdrop-filter, fallback]
syncStatus: reviewed
verified: true
---

## 用法

### 模式
`mode` 选择材质：`pure` 纯色、`mask` 半透明遮罩、`blur` 背景模糊、`glass` 玻璃、`refraction` 折射。
:::TuffDemoWrapper{demo="BaseSurfaceModesDemo" code-lang="vue"}
---
code: |
  <template>
    <TxBaseSurface mode="pure">纯色</TxBaseSurface>
    <TxBaseSurface mode="mask" :opacity="0.6">遮罩</TxBaseSurface>
    <TxBaseSurface mode="blur" :blur="8">模糊</TxBaseSurface>
    <TxBaseSurface mode="glass" :blur="12" :saturation="1.8">毛玻璃</TxBaseSurface>
    <TxBaseSurface mode="refraction" :blur="11" :displace="0.8" :distortion-scale="-200">折射</TxBaseSurface>
  </template>
---
:::

### 参数实验
`filter*` 调滤镜层，`refraction*` 调折射层，`preset="card"` 套用卡片调校。
:::TuffDemoWrapper{demo="BaseSurfaceAdvancedDemo" code-lang="vue"}
---
code: |
  <template>
    <TxBaseSurface
      mode="refraction"
      preset="card"
      :radius="18"
      :blur="24"
      :filter-saturation="1.6"
      refraction-profile="filmic"
      :refraction-strength="68"
      :refraction-angle="-24"
      :refraction-halo-opacity="0.42"
    >
      BaseSurface Advanced
    </TxBaseSurface>
  </template>
---
:::

### 伪元素模式
`fake` 用伪元素绘制背景，与现有 `.fake-background` 层级一致，插槽内容自然位于其上。
:::TuffDemoWrapper{demo="BaseSurfaceFakeDemo" code-lang="vue"}
---
code: |
  <template>
    <TxBaseSurface fake mode="mask" :opacity="0.5" :radius="12">
      <strong>伪元素背景</strong>
    </TxBaseSurface>
    <TxBaseSurface fake mode="pure" :radius="12" color="var(--tx-color-primary-light-9)">
      自定义颜色
    </TxBaseSurface>
  </template>
---
:::

### 运动降级
`transform` 运动会让 `backdrop-filter` 失效；设置 `moving` 后降级为 `fallbackMode`，停止后平滑恢复。
:::TuffDemoWrapper{demo="BaseSurfaceFallbackDemo" code-lang="vue"}
---
code: |
  <template>
    <TxButton @click="animating = !animating">
      {{ animating ? '停止运动' : '开始运动' }}
    </TxButton>

    <div
      :style="{ transform: animating ? 'translateX(16px) scale(0.92)' : 'none' }"
      style="transition: transform 1.4s;"
    >
      <TxBaseSurface mode="glass" :blur="12">无降级</TxBaseSurface>
      <TxBaseSurface mode="glass" :blur="12" :moving="animating" fallback-mode="mask">
        有降级
      </TxBaseSurface>
    </div>
  </template>
---
:::

### 与原生对比
拿不到运动状态时开启 `autoDetect`，由组件监听 transform 过渡自行降级。
:::TuffDemoWrapper{demo="BaseSurfaceMotionCompareDemo" code-lang="vue"}
---
code: |
  <template>
    <div
      :style="{ transform: animating ? 'translateX(20px)' : '' }"
      style="backdrop-filter: blur(12px); transition: transform 1.2s;"
    >
      原生 glass（运动时失效）
    </div>

    <TxBaseSurface mode="glass" :blur="12" :moving="animating" auto-detect fallback-mode="mask">
      BaseSurface（运动时降级为 mask）
    </TxBaseSurface>
  </template>
---
:::

### 最佳实践

- 业务容器优先用 `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/`。

<TuffDocSourceLink />