---
title: Surface 表面
description: 提供表面级样式与子组件上下文的容器组件。
links:
  source: surface/surface.tsx
  styles: surface.css
  storybook: surface
---

## 用法

```tsx
import { Surface } from '@heroui/react';
```

<ComponentPreview name="surface-basic" />

## 示例

### 变体

Surface 提供描述 prominence 层级的语义变体：

- **`default`** - 标准表面外观（bg-surface）
- **`secondary`** - 中等 prominence（bg-surface-secondary）
- **`tertiary`** - 较高 prominence（bg-surface-tertiary）

<ComponentPreview name="surface-variants" />

### 搭配表单

在 Surface 内使用表单组件时，请使用 `variant="secondary"` 以应用适合表面背景的低强调变体。

<ComponentPreview name="surface-with-form-components" />

## 自定义样式

### Tailwind CSS

<ComponentPreview name="surface-custom-styles" />

### 全局 CSS

若要自定义组件类，可使用 `@layer components` 指令。[了解更多](https://tailwindcss.com/docs/adding-custom-styles#adding-component-classes)。

```css
@layer components {
  .surface {
    @apply rounded-2xl border border-border;
  }

  .surface--secondary {
    @apply bg-gradient-to-br from-blue-50 to-purple-50;
  }
}
```

## 样式参考

HeroUI 遵循 [BEM](https://getbem.com/) 方法论，确保组件变体与状态可复用且易于自定义。

### CSS 类

Surface 组件使用以下 CSS 类（[查看源码样式](https://github.com/heroui-inc/heroui/blob/v3/packages/styles/components/surface.css)）：

#### 基础类 [!toc]
- `.surface` - Surface 根容器

#### 变体类 [!toc]
- `.surface--default` - 默认 Surface 变体（bg-surface）
- `.surface--secondary` - Secondary Surface 变体（bg-surface-secondary）
- `.surface--tertiary` - Tertiary Surface 变体（bg-surface-tertiary）

## API 参考

### Surface
| Prop | 类型 | 默认值 | 描述 |
|------|------|--------|------|
| `variant` | ` "transparent" \| "default" \| "secondary" \| "tertiary"` | `"default"` | Surface 的视觉变体。 |
| `className` | `string` | - | 额外的 CSS 类。 |
| `children` | `ReactNode` | - | Surface 内容。 |

## Context API

### SurfaceContext

子组件可通过 Surface 上下文读取当前变体：

```tsx
import { useContext } from 'react';
import { SurfaceContext } from '@heroui/react';

function MyComponent() {
  const { variant } = useContext(SurfaceContext);
  // variant 为 "transparent" | "default" | "secondary" | "tertiary" | undefined
}
```

## 相关组件

<RelatedComponents component="surface" />