---
title: "GlassSurface 玻璃拟态"
description: "折射背后内容的玻璃容器"
category: Effects
status: beta
since: 0.3.4
tags: [glass, blur, refraction]
syncStatus: reviewed
verified: true
---

## 用法

### 基础
:::TuffDemoWrapper{demo="GlassSurfaceGlassSurfaceDemo" code-lang="vue"}
---
code: |
  <template>
    <div class="backdrop">
      <TxGlassSurface :width="360" :height="160" :border-radius="20" :background-opacity="0.08">
        GlassSurface
      </TxGlassSurface>
    </div>
  </template>
---
:::

### 参数调节
:::TuffDemoWrapper{demo="GlassSurfaceGlassSurface2Demo" code-lang="vue"}
---
code: |
  <template>
    <TxGlassSurface
      :width="360"
      :height="160"
      :blur="blur"
      :displace="displace"
      :distortion-scale="distortionScale"
    >
      GlassSurface
    </TxGlassSurface>
    <TxSlider v-model="blur" :min="0" :max="24" />
    <TxSlider v-model="displace" :min="0" :max="6" :step="0.1" />
    <TxSlider v-model="distortionScale" :min="-600" :max="0" :step="10" />
  </template>
---
:::

### 最佳实践

- 只在插画、图片或渐变背景需要折射感时使用；普通卡片用 `TxBaseSurface` 或 `TxCard`。
- 覆盖滚动内容或图片时，显式设置 `width`、`height` 与 `borderRadius`。
- 对照真实背景调 `blur`、`backgroundOpacity`、`saturation`，避免背后的文字不可读。
- 大幅 `distortionScale` 或较宽的通道偏移只用于 hero 或预览表面，不用于密集表单。
- 重要控件放进默认插槽。

## API 参考

### 属性

::TuffPropsTable
---
rows:
  - name: width
    type: "string | number"
    default: "'200px'"
    description: 表面宽度；数字按 px，字符串原样使用。
  - name: height
    type: "string | number"
    default: "'200px'"
    description: 表面高度；数字按 px，字符串原样使用。
  - name: borderRadius
    type: number
    default: 20
    description: 外层圆角（px），也用于位移图。
  - name: borderWidth
    type: number
    default: 0.07
    description: 位移图遮罩的边缘尺寸倍率。
  - name: brightness
    type: number
    default: 70
    description: 位移图内层遮罩的亮度百分比。
  - name: opacity
    type: number
    default: 0.93
    description: 位移图内层遮罩的透明度。
  - name: blur
    type: number
    default: 11
    description: 位移图遮罩的模糊半径，也是 backdrop-filter 降级路径的模糊。
  - name: displace
    type: number
    default: 0.5
    description: RGB 位移图混合后的最终模糊（feGaussianBlur.stdDeviation）。
  - name: backgroundOpacity
    type: number
    default: 0
    description: SVG 滤镜路径上的背景透明度。
  - name: saturation
    type: number
    default: 1
    description: SVG 滤镜路径上的饱和度。
  - name: distortionScale
    type: number
    default: -180
    description: 红、绿、蓝三张位移图的基础位移量。
  - name: redOffset
    type: number
    default: 0
    description: 叠加到 distortionScale 上的红色偏移。
  - name: greenOffset
    type: number
    default: 10
    description: 叠加到 distortionScale 上的绿色偏移。
  - name: blueOffset
    type: number
    default: 20
    description: 叠加到 distortionScale 上的蓝色偏移。
  - name: xChannel
    type: "'R' | 'G' | 'B'"
    default: "'R'"
    description: 三张位移图的 X 轴取色通道。
  - name: yChannel
    type: "'R' | 'G' | 'B'"
    default: "'G'"
    description: 三张位移图的 Y 轴取色通道。
  - name: mixBlendMode
    type: "'normal' | 'multiply' | 'screen' | 'overlay' | 'darken' | 'lighten' | 'color-dodge' | 'color-burn' | 'hard-light' | 'soft-light' | 'difference' | 'exclusion' | 'hue' | 'saturation' | 'color' | 'luminosity' | 'plus-darker' | 'plus-lighter'"
    default: "'difference'"
    description: 生成位移图时蓝色渐变的混合模式。
---
::

### 插槽

| 插槽名 | 参数 | 说明 |
|--------|------|------|
| `default` | - | 面板内容，在 `.tx-glass-surface__content` 中居中，位于滤镜层之上。 |

## 概述

- 按能力依次选择渲染路径：支持 `backdrop-filter: url()` 时用 SVG 位移折射；否则用 `blur()` 毛玻璃；仍不支持时退为半透明背景加边框。
- Safari、Firefox、SSR 与没有 `CSS.supports` 的环境不走折射路径；降级路径保留尺寸、圆角与可读性，但没有 RGB 折射。
- 位移图按实测尺寸生成，容器尺寸或光学参数变化时重算。
- 生成的 SVG 只做装饰，不可交互，位于内容层之下。

## 技术实现

- 三个 `feDisplacementMap` 分别位移红、绿、蓝通道后合成，形成色散折射。
- 源码：`packages/tuffex/packages/components/src/glass-surface/`。

<TuffDocSourceLink />