---
title: Card 卡片
description: 灵活容器组件，用于分组相关内容与操作
links:
  source: card/card.tsx
  styles: card.css
  storybook: Components/Layout/Card
---

## 用法

```tsx
import { Card } from "@heroui/react";
```

<ComponentPreview
  name="card-default"
/>

## 组件结构

```tsx
import { Card } from "@heroui/react";

export default () => (
  <Card>
    <Card.Header>
      <Card.Title />
      <Card.Description />
    </Card.Header>
    <Card.Content />
    <Card.Footer />
  </Card>
);
```

## 示例

### 变体

Card 提供语义变体，描述 prominence 级别而非具体视觉样式，允许主题以不同方式解读：

<ComponentPreview
  name="card-variants"
/>

- **`transparent`** - 最低 prominence，透明背景（适合嵌套卡片）
- **`default`** - 大多数场景的标准卡片（surface-secondary）
- **`secondary`** - 中等 prominence 以吸引适度注意（surface-tertiary）
- **`tertiary`** - 更高 prominence 用于重要内容（surface-tertiary）

### 水平布局

<ComponentPreview
  name="card-horizontal"
/>

### 带头像

<ComponentPreview
  name="card-with-avatar"
/>

### 带图片

<ComponentPreview
  name="card-with-images"
/>

### 搭配表单

<ComponentPreview
  name="card-with-form"
/>

## 自定义样式

### Tailwind CSS

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

### 全局 CSS

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

```css
@layer components {
  .card--secondary {
    @apply bg-gradient-to-br from-blue-50 to-purple-50;
  }

  .card__title {
    @apply text-xl font-bold;
  }
}
```

## 样式参考

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

### CSS 类

Card 使用 [BEM](https://getbem.com/) 命名以实现可预测的样式（[查看源码样式](https://github.com/heroui-inc/heroui/blob/v3/packages/styles/components/card.css)）：

#### 基础类 [!toc]

- `.card` - 带 padding 与边框的基础容器
- `.card__header` - 头部区域容器
- `.card__title` - 基础字号与字重的标题
- `.card__description` - 弱化描述文本
- `.card__content` - 灵活内容容器
- `.card__footer` - 行布局的页脚

#### 变体类 [!toc]

- `.card--transparent` - 最低 prominence，透明背景（对应 `transparent` 变体）
- `.card--default` - 标准外观，surface-secondary（默认）
- `.card--secondary` - 中等 prominence，surface-tertiary（对应 `secondary` 变体）
- `.card--tertiary` - 更高 prominence，surface-tertiary（对应 `tertiary` 变体）

## API 参考

### Card

| Prop | 类型 | 默认值 | 描述 |
|------|------|--------|------|
| `variant` | `"transparent" \| "default" \| "secondary" \| "tertiary"` | `"default"` | 表示 prominence 级别的语义变体 |
| `className` | `string` | - | 附加 CSS 类 |
| `children` | `React.ReactNode` | - | 卡片内容 |

### Card.Header

| Prop | 类型 | 默认值 | 描述 |
|------|------|--------|------|
| `className` | `string` | - | 附加 CSS 类 |
| `children` | `React.ReactNode` | - | 头部内容 |

### Card.Title

| Prop | 类型 | 默认值 | 描述 |
|------|------|--------|------|
| `className` | `string` | - | 附加 CSS 类 |
| `children` | `React.ReactNode` | - | 标题内容（渲染为 `h3`） |

### Card.Description

| Prop | 类型 | 默认值 | 描述 |
|------|------|--------|------|
| `className` | `string` | - | 附加 CSS 类 |
| `children` | `React.ReactNode` | - | 描述内容（渲染为 `p`） |

### Card.Content

| Prop | 类型 | 默认值 | 描述 |
|------|------|--------|------|
| `className` | `string` | - | 附加 CSS 类 |
| `children` | `React.ReactNode` | - | 主要内容 |

### Card.Footer

| Prop | 类型 | 默认值 | 描述 |
|------|------|--------|------|
| `className` | `string` | - | 附加 CSS 类 |
| `children` | `React.ReactNode` | - | 页脚内容 |

## 无障碍

```tsx
import { Card } from '@heroui/react';
import { cardVariants } from '@heroui/styles';

// Semantic markup
<Card role="article" aria-labelledby="card-title">
  <Card.Header>
    <Card.Title id="card-title">Article Title</Card.Title>
  </Card.Header>
</Card>

// Interactive cards
<a className={cardVariants().base()} href="/details" aria-label="View product details">
  <Card.Title>Product Name</Card.Title>
</a>
```

## 相关组件

<RelatedComponents component="card" />