> Leaf UI 0.17.3 · Package: @ifhover/leaf-ui · Source: c3221834f84f2f48481a2054026b713456f8e5dc
> Browser documentation: https://ifhover.github.io/leaf-ui/components/card.html

> For AI agents: the complete documentation index is available at https://ifhover.github.io/leaf-ui/llms.txt, the full documentation bundle is available at https://ifhover.github.io/leaf-ui/llms-full.txt.

# Card 卡片

在独立容器中展示相关内容和操作。


## 基础用法

通过 `title` 提供卡片标题，内容写在 `children` 中。


### 项目资料

在这里整理项目的说明与相关资料。

basic.tsx

复制代码

```tsx lineNumbers file="../../src/examples/card/basic.tsx"
import { Card } from '@ifhover/leaf-ui';

export function CardBasic() {
  return <Card title="项目资料">在这里整理项目的说明与相关资料。</Card>;
}
```

展开代码


## 示例

### 选中状态

`selected` 只改变外观，不会让整张卡片成为可点击控件。需要选择卡片时，使用明确的按钮或选择控件。


### 个人方案

适合个人使用。

选择方案

### 团队方案

适合团队协作。

选择方案

selected.tsx

复制代码

```tsx lineNumbers file="../../src/examples/card/selected.tsx"
import { Button, Card, Flex } from '@ifhover/leaf-ui';
import { useState } from 'react';

export function CardSelected() {
  const [selected, setSelected] = useState('personal');
  return (
    <Flex direction="column" gap={16}>
      {[
        { key: 'personal', title: '个人方案' },
        { key: 'team', title: '团队方案' },
      ].map((option) => (
        <Card
          key={option.key}
          title={option.title}
          selected={selected === option.key}
          footer={
            <Button aria-pressed={selected === option.key} onClick={() => setSelected(option.key)}>
              选择方案
            </Button>
          }
        >
          {option.key === 'personal' ? '适合个人使用。' : '适合团队协作。'}
        </Card>
      ))}
    </Flex>
  );
}
```

展开代码

### 尺寸

内嵌标签页默认跟随卡片的 `size`，可通过 `tabs.size` 单独设置，高度与独立的同尺寸线形 Tabs 一致；卡片内的按钮、输入框等控件使用各自的 `size`。


小

### 项目资料

相同的卡片内容。

默认

### 项目资料

相同的卡片内容。

大

### 项目资料

相同的卡片内容。

sizes.tsx

复制代码

```tsx lineNumbers file="../../src/examples/card/sizes.tsx"
import { Card, Flex, Text } from '@ifhover/leaf-ui';

const sizes = [
  { size: 'sm', label: '小' },
  { size: 'md', label: '默认' },
  { size: 'lg', label: '大' },
] as const;

export function CardSizes() {
  return (
    <Flex direction="column" gap="lg">
      {sizes.map(({ size, label }) => (
        <Flex key={size} direction="column" gap="sm">
          <Text tone="muted">{label}</Text>
          <Card title="项目资料" size={size}>
            相同的卡片内容。
          </Card>
        </Flex>
      ))}
    </Flex>
  );
}
```

展开代码

### 分层卡片

设置 `variant="layered"`，将标题与内容卡分层展示。此时不展示 `description`。


### 项目进度

进行中

整理组件用法，补充交互示例。

60%

已完成 6 / 10 项任务预计周五完成

layered.tsx

复制代码

```tsx lineNumbers file="../../src/examples/card/layered.tsx"
import { Card, Flex, Progress, Space, Tag, Text } from '@ifhover/leaf-ui';

export function CardLayered() {
  return (
    <Card title="项目进度" extra={<Tag variant="soft">进行中</Tag>} variant="layered">
      <Space direction="vertical" align="stretch" size="md">
        <Text>整理组件用法，补充交互示例。</Text>
        <Progress percent={60} aria-label="项目完成进度" />
        <Flex justify="space-between" gap="sm" wrap>
          <Text tone="muted">已完成 6 / 10 项任务</Text>
          <Text tone="muted">预计周五完成</Text>
        </Flex>
      </Space>
    </Card>
  );
}
```

展开代码

### 独立标题

`CardTitle` 可以在卡片外使用，默认渲染 `<h3>`。通过 `level` 匹配页面的标题层级，不改变视觉尺寸。


### 项目资料

统一整理说明与参考资料。

standalone-title.tsx

复制代码

```tsx lineNumbers file="../../src/examples/card/standalone-title.tsx"
import { CardTitle } from '@ifhover/leaf-ui';

export function CardStandaloneTitle() {
  return <CardTitle description="统一整理说明与参考资料。">项目资料</CardTitle>;
}
```

展开代码

### 标题与底部操作

使用 `extra` 放置标题旁的操作，使用 `footer` 放置正文下方的操作。


### 项目资料

重置

有尚未保存的修改。

保存

actions.tsx

复制代码

```tsx lineNumbers file="../../src/examples/card/actions.tsx"
import { Button, Card, Flex, Text } from '@ifhover/leaf-ui';
import { useState } from 'react';

export function CardActions() {
  const [saved, setSaved] = useState(false);

  return (
    <Card
      title="项目资料"
      extra={
        <Button variant="link" disabled={!saved} onClick={() => setSaved(false)}>
          重置
        </Button>
      }
      footer={
        <Flex justify="end">
          <Button disabled={saved} onClick={() => setSaved(true)}>
            保存
          </Button>
        </Flex>
      }
    >
      <Text role="status">{saved ? '修改已保存。' : '有尚未保存的修改。'}</Text>
    </Card>
  );
}
```

展开代码

### 标签页卡片

通过 `tabs.items` 定义标签页。没有卡片标题时，请通过 `tabs['aria-label']` 提供名称。各项的 `children` 是对应页面内容；若仅将标签栏用于切换状态并把内容写在 Card 的 `children` 中，可省略各项的 `children`。Card 的 `children` 会作为正文展示在下方。


概览

最近动态

让设计与开发围绕同一份计划协作。

tabs.tsx

复制代码

```tsx lineNumbers file="../../src/examples/card/tabs.tsx"
import { Card, Text } from '@ifhover/leaf-ui';

export function CardTabs() {
  return (
    <Card
      tabs={{
        'aria-label': '项目概览',
        items: [
          {
            key: 'overview',
            label: '概览',
            children: <Text>让设计与开发围绕同一份计划协作。</Text>,
          },
          {
            key: 'activity',
            label: '最近动态',
            children: <Text>今天更新了组件规范。</Text>,
          },
        ],
      }}
    />
  );
}
```

展开代码

### 标题与标签页

通过 `tabs.activeKey`
 和 `tabs.onChange`
 控制当前标签。默认保留已访问页面的输入状态；设置 `destroyInactive`
 可在切走时卸载页面。其他标签交互见 [Tabs API
](tabs.html#tabs-api)（新标签页打开）。

### 项目设置

基本信息

说明

项目名称

尚未保存保存修改

tabs-with-title.tsx

复制代码

```tsx lineNumbers file="../../src/examples/card/tabs-with-title.tsx"
import { Button, Card, Flex, Form, FormField, Input, Text } from '@ifhover/leaf-ui';
import { useId, useState } from 'react';

export function CardTabsWithTitle() {
  const [activeKey, setActiveKey] = useState('settings');
  const [saved, setSaved] = useState(false);
  const formId = useId();
  return (
    <Card
      title="项目设置"
      tabs={{
        activeKey,
        onChange: setActiveKey,
        items: [
          {
            key: 'settings',
            label: '基本信息',
            children: (
              <Form
                id={formId}
                layout="vertical"
                onChange={() => setSaved(false)}
                onSubmit={(event) => {
                  event.preventDefault();
                  setSaved(true);
                }}
              >
                <FormField label="项目名称">
                  <Input name="name" defaultValue="Leaf 设计系统" required />
                </FormField>
              </Form>
            ),
          },
          {
            key: 'notes',
            label: '说明',
            children: <Text>修改项目名称后，在基本信息中保存。</Text>,
          },
        ],
      }}
      footer={
        <Flex align="center" gap="sm" justify="space-between" wrap>
          <Text role="status" tone="muted">
            {saved ? '已保存' : '尚未保存'}
          </Text>
          <Button type="submit" form={formId} disabled={activeKey !== 'settings'}>
            保存修改
          </Button>
        </Flex>
      }
    />
  );
}
```

展开代码

### 加载状态

`loading` 使用骨架屏替换正文和标签页内容，不会自动禁用标题、标签或操作；需要禁用的操作由应用处理。


加载中

### 项目资料

loading.tsx

复制代码

```tsx lineNumbers file="../../src/examples/card/loading.tsx"
import { Card, Flex, Switch } from '@ifhover/leaf-ui';
import { useState } from 'react';

export function CardLoading() {
  const [loading, setLoading] = useState(true);

  return (
    <Flex direction="column" gap="md">
      <Switch checked={loading} onChange={(event) => setLoading(event.currentTarget.checked)}>
        加载中
      </Switch>
      <Card title="项目资料" loading={loading}>
        在这里整理项目的说明与相关资料。
      </Card>
    </Flex>
  );
}
```

展开代码


## API

### Card API

卡片的标题、内容区域、内嵌标签页与加载状态配置。

| 属性            | 类型                               | 默认值         | 说明                               |
| ------------- | -------------------------------- | ----------- | -------------------------------- |
| `title`       | `ReactNode`                      | —           | 卡片标题。                            |
| `description` | `ReactNode`                      | —           | 标题下方的补充说明，仅默认外观支持；layered 不展示。   |
| `extra`       | `ReactNode`                      | —           | 标题旁的操作；没有标题时显示在标签栏右侧。            |
| `tabs`        | [`CardTabsProps`](#cardtabs-api) | —           | 内嵌标签页；无标题时替代标题栏，有标题时位于其下方。       |
| `cover`       | `ReactNode`                      | —           | 顶部封面。                            |
| `footer`      | `ReactNode`                      | —           | 底部内容或操作；layered 展示在内容卡下方的外层区域。   |
| `loading`     | `boolean`                        | `false`     | 将正文和标签页内容替换为骨架屏；不会禁用标题、标签页或操作。   |
| `bordered`    | `boolean`                        | `true`      | 显示外轮廓；设为 `false` 移除边框。           |
| `shadow`      | `boolean`                        | `true`      | 显示卡片的静止阴影；分层卡片将其应用于内层内容面。        |
| `selected`    | `boolean`                        | `false`     | 标记选中外观，不提供选择交互；使用按钮或选择控件管理选中状态。  |
| `variant`     | `'default' \| 'layered'`         | `'default'` | 卡片外观；layered 将内容卡与外层标题、底部操作分层展示。 |
| `size`        | `'sm' \| 'md' \| 'lg'`           | `'md'`      | 卡片尺寸；内嵌标签页默认跟随此尺寸，其他子组件独立配置。     |

### CardTabs API

内嵌标签页的可用属性见 [Tabs API
](tabs.html#tabs-api)（新标签页打开）。Card 固定使用 `type="line"`
 与 `placement="top"`
，并为标签页内容接入加载骨架；`tabs.extra`
 仍属于标签栏，`items`
 为空时恢复普通卡片。
```ts
type CardTabsProps = Omit<TabsProps, 'type' | 'placement' | 'children'>;
```

### CardTitle API

支持原生标题属性，ref 指向实际标题元素。`ConfigProvider` 的 `components.CardTitle` 默认参数只影响直接使用的标题；Card 内部标题继续跟随 Card 的尺寸。

| 属性               | 类型                                                 | 默认值    | 说明                                                |
| ---------------- | -------------------------------------------------- | ------ | ------------------------------------------------- |
| `size`           | `'sm' \| 'md' \| 'lg'`                             | `'md'` | 标题的视觉尺寸，与 Card 对应尺寸的标题一致。                         |
| `description`    | `ReactNode`                                        | —      | 标题下方的补充说明。                                        |
| `extra`          | `ReactNode`                                        | —      | 标题右侧的附加操作。                                        |
| `level`          | `1 \| 2 \| 3 \| 4 \| 5 \| 6`                       | `3`    | 可选语义层级；默认与 Card 标题相同为 h3，不改变视觉尺寸。                 |
| `containerProps` | `Omit<HTMLAttributes<HTMLDivElement>, 'children'>` | —      | 标题区域外层容器的原生属性；heading 自身的属性、事件与 ref 仍直接应用于实际标题元素。 |
| `children`       | `ReactNode`                                        | —      | 标题内容。                                             |
| `ref`            | `Ref<HTMLHeadingElement>`                          | —      | 标题元素引用。                                           |
