---
title: Card 卡片
description: 卡片容器，提供灵活分区以结构化展示内容。
links:
  source_native: card/card.tsx
  styles_native: card/card.styles.ts
---

<NativeVideoPlayerView
  target="auto"
  srcLight="https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/docs/native/components/videos/card-docs-light.mp4"
  srcDark="https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/docs/native/components/videos/card-docs-dark.mp4"
/>

## 导入

```tsx
import { Card } from 'heroui-native';
```

## 结构

```tsx
<Card>
  <Card.Header>...</Card.Header>
  <Card.Body>
    <Card.Title>...</Card.Title>
    <Card.Description>...</Card.Description>
  </Card.Body>
  <Card.Footer>...</Card.Footer>
</Card>
```

- **Card**：主容器，继承 `Surface`；提供可配置的表面变体与整体布局。
- **Card.Header**：顶部区域，可放图标、徽章等。
- **Card.Body**：主内容区，`flex-1` 填充 `Header` 与 `Footer` 之间的空间。
- **Card.Title**：标题，前景色与中等字重。
- **Card.Description**：描述，弱化色与较小字号。
- **Card.Footer**：底部区域，可放按钮等操作。

## 用法

### 基础用法

使用内置分区组织内容。

```tsx
<Card>
  <Card.Body>...</Card.Body>
</Card>
```

### 标题与描述

组合标题与描述以结构化展示文字。

```tsx
<Card>
  <Card.Body>
    <Card.Title>...</Card.Title>
    <Card.Description>...</Card.Description>
  </Card.Body>
</Card>
```

### 页头与页脚

增加顶部与底部区域放置图标、徽章或操作。

```tsx
<Card>
  <Card.Header>...</Card.Header>
  <Card.Body>...</Card.Body>
  <Card.Footer>...</Card.Footer>
</Card>
```

### 变体

通过变体控制卡片背景外观。

```tsx
<Card variant="default">...</Card>
<Card variant="secondary">...</Card>
<Card variant="tertiary">...</Card>
<Card variant="transparent">...</Card>
```

### 横向布局

使用 `flex-row` 等样式创建横向卡片。

```tsx
<Card className="flex-row gap-4">
  <Image source={...} className="size-24 rounded-lg" />
</Card>
```

### 背景图

使用绝对定位图片作为背景。

```tsx
<Card>
  <Image source={...} className="absolute inset-0" />
  <View className="gap-4">...</View>
</Card>
```

## 示例

```tsx
import { Button, Card } from 'heroui-native';
import { Ionicons } from '@expo/vector-icons';
import { View } from 'react-native';

export default function CardExample() {
  return (
    <Card>
      <View className="gap-4">
        <Card.Body className="mb-4">
          <View className="gap-1 mb-2">
            <Card.Title className="text-pink-500">¥450</Card.Title>
            <Card.Title>客厅沙发 • 2025 系列</Card.Title>
          </View>
          <Card.Description>
            这款沙发适合现代热带风、巴洛克灵感等空间。
          </Card.Description>
        </Card.Body>
        <Card.Footer className="gap-3">
          <Button variant="primary">立即购买</Button>
          <Button variant="ghost">
            <Button.Label>加入购物车</Button.Label>
            <Ionicons name="bag-outline" size={16} />
          </Button>
        </Card.Footer>
      </View>
    </Card>
  );
}
```

更多示例见 [GitHub 仓库](https://github.com/heroui-inc/heroui-native/blob/main/example/src/app/(home)/components/card.tsx)。

## API 参考

### Card

| prop           | type                                                      | default     | description                                                                               |
| -------------- | --------------------------------------------------------- | ----------- | ----------------------------------------------------------------------------------------- |
| `children`     | `React.ReactNode`                                         | -           | 卡片内内容                                                                               |
| `variant`      | `'default' \| 'secondary' \| 'tertiary' \| 'transparent'` | `'default'` | 卡片表面视觉变体                                                                         |
| `className`    | `string`                                                  | -           | 额外的 class                                                                             |
| `animation`    | `"disable-all" \| undefined`                              | `undefined` | 动画配置；`"disable-all"` 可禁用自身及子级的全部动画                                     |
| `...ViewProps` | `ViewProps`                                               | -           | 支持 React Native `View` 的全部属性                                                      |

### Card.Header

| prop           | type              | default | description                                        |
| -------------- | ----------------- | ------- | -------------------------------------------------- |
| `children`     | `React.ReactNode` | -       | 页头内子节点                                       |
| `className`    | `string`          | -       | 额外的 class                                       |
| `...ViewProps` | `ViewProps`       | -       | 支持 React Native `View` 的全部属性                |

### Card.Body

| prop           | type              | default | description                                        |
| -------------- | ----------------- | ------- | -------------------------------------------------- |
| `children`     | `React.ReactNode` | -       | 主内容区子节点                                     |
| `className`    | `string`          | -       | 额外的 class                                       |
| `...ViewProps` | `ViewProps`       | -       | 支持 React Native `View` 的全部属性                |

### Card.Footer

| prop           | type              | default | description                                        |
| -------------- | ----------------- | ------- | -------------------------------------------------- |
| `children`     | `React.ReactNode` | -       | 页脚内子节点                                       |
| `className`    | `string`          | -       | 额外的 class                                       |
| `...ViewProps` | `ViewProps`       | -       | 支持 React Native `View` 的全部属性                |

### Card.Title

| prop           | type              | default | description                                        |
| -------------- | ----------------- | ------- | -------------------------------------------------- |
| `children`     | `React.ReactNode` | -       | 标题文字                                           |
| `className`    | `string`          | -       | 额外的 class                                       |
| `...TextProps` | `TextProps`       | -       | 支持 React Native `Text` 的全部属性                |

### Card.Description

| prop           | type              | default | description                                              |
| -------------- | ----------------- | ------- | -------------------------------------------------------- |
| `children`     | `React.ReactNode` | -       | 描述文字                                                 |
| `className`    | `string`          | -       | 额外的 class                                             |
| `...TextProps` | `TextProps`       | -       | 支持 React Native `Text` 的全部属性                      |
