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

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

# Card 卡片

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

## 基础用法


### 项目概览

整理项目资料，让团队围绕同一份计划协作。

basic.tsx

复制代码

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

export function CardBasic() {
  return <Card title="项目概览">整理项目资料，让团队围绕同一份计划协作。</Card>;
}
```

展开代码

## 尺寸

`size` 提供小、默认和大三种尺寸，同时调整卡片内边距、标题字号与标题栏高度。内嵌 Tabs 默认跟随卡片尺寸，也可通过 `tabs.size` 单独设置；卡片内的按钮、输入框等控件使用各自的 `size`。

下面的三张卡片展示相同内容，方便对比标题、标签栏与正文留白；每张卡片的标签均可独立切换。


### 小尺寸

概览

最近动态

整理项目资料，让设计与开发围绕同一份计划协作。

### 默认尺寸

概览

最近动态

整理项目资料，让设计与开发围绕同一份计划协作。

### 大尺寸

概览

最近动态

整理项目资料，让设计与开发围绕同一份计划协作。

sizes.tsx

复制代码

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

export function CardSizes() {
  const items = [
    { key: 'overview', label: '概览', children: '整理项目资料，让设计与开发围绕同一份计划协作。' },
    {
      key: 'activity',
      label: '最近动态',
      children: '今天更新了组件规范，并邀请两位成员加入项目。',
    },
  ];
  return (
    <Space direction="vertical" align="stretch" size="lg">
      <Card title="小尺寸" size="sm" tabs={{ items }} />
      <Card title="默认尺寸" tabs={{ items }} />
      <Card title="大尺寸" size="lg" tabs={{ items }} />
    </Space>
  );
}
```

展开代码

## 内容分区

默认以留白组织内容；设置 `divided` 可划分标题、正文与底部操作区。


### 项目概览

默认通过留白组织内容

进行中

标题、说明和正文自然分组。

### 内容分区

设置 divided 后，标题、正文和底部操作使用分隔线划分。

取消确认

sections.tsx

复制代码

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

export function CardSections() {
  
  return (
    <Space direction="vertical" align="stretch" size="lg">
      <Card
        title={'项目概览'}
        description={'默认通过留白组织内容'}
        extra={<Tag>{'进行中'}</Tag>}
      >
        {'标题、说明和正文自然分组。'}
      </Card>
      <Card
        divided
        title={'内容分区'}
        footer={
          <Flex justify="end" gap="sm" wrap>
            <Button variant="outline">{'取消'}</Button>
            <Button>{'确认'}</Button>
          </Flex>
        }
      >
        {'设置 divided 后，标题、正文和底部操作使用分隔线划分。'}
      </Card>
    </Space>
  );
}
```

展开代码

## 标签页卡片

通过 `tabs.items` 设置标签与对应内容。没有标题时，标签占满标题栏高度，文字上下留白一致；卡片的 `extra` 显示在标签栏右侧。


概览

最近动态

查看项目

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

负责人林若团队成员8 人

tabs.tsx

复制代码

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

export function CardTabs() {
  return (
    <Card
      extra={<Button variant="link">查看项目</Button>}
      tabs={{
        'aria-label': '项目概览',
        items: [
          {
            key: 'overview',
            label: '概览',
            children: (
              <Space direction="vertical" align="stretch" size="md">
                <span>让设计与开发围绕同一份计划协作。</span>
                <Descriptions
                  columns={2}
                  items={[
                    { key: 'owner', label: '负责人', children: '林若' },
                    { key: 'members', label: '团队成员', children: '8 人' },
                  ]}
                />
              </Space>
            ),
          },
          {
            key: 'activity',
            label: '最近动态',
            children: '今天更新了组件规范，并邀请两位成员加入项目。',
          },
        ],
      }}
    />
  );
}
```

展开代码

## 标题与标签页

有 `title` 或 `description` 时，标签栏位于标题区域下方，两者之间没有分割线，分割线只展示在标签栏下方。`tabs.activeKey` / `tabs.onChange` 控制当前标签，默认保留已访问页面的输入内容；`divided` 继续控制底部操作区的分隔线和背景。


### 项目设置

管理项目资料与团队成员。

草稿

基本信息

团队成员

账单

项目名称

联系邮箱

保存修改

tabs-with-title.tsx

复制代码

```tsx lineNumbers file="../../src/examples/card/tabs-with-title.tsx"
import { Button, Card, Descriptions, Flex, Form, FormField, Input, Tag } 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
      divided
      title="项目设置"
      description="管理项目资料与团队成员。"
      extra={<Tag>{saved ? '已保存' : '草稿'}</Tag>}
      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>
                <FormField label="联系邮箱">
                  <Input name="email" type="email" defaultValue="team@example.com" required />
                </FormField>
              </Form>
            ),
          },
          {
            key: 'members',
            label: '团队成员',
            children: (
              <Descriptions
                columns={1}
                items={[
                  { key: 'owner', label: '项目负责人', children: '林若' },
                  { key: 'designer', label: '设计师', children: '陈安' },
                ]}
              />
            ),
          },
          { key: 'billing', label: '账单', disabled: true, children: null },
        ],
      }}
      footer={
        <Flex align="center" gap="sm" justify="end">
          <Button type="submit" form={formId} disabled={activeKey !== 'settings'}>
            保存修改
          </Button>
        </Flex>
      }
    />
  );
}
```

展开代码

## Card API

| 属性            | 类型                               | 默认值     | 说明                                   |
| ------------- | -------------------------------- | ------- | ------------------------------------ |
| `title`       | `ReactNode`                      | —       | 卡片标题。                                |
| `description` | `ReactNode`                      | —       | 补充说明。                                |
| `extra`       | `ReactNode`                      | —       | 标题旁的操作；没有标题时显示在标签栏右侧。                |
| `tabs`        | [`CardTabsProps`](#cardtabs-api) | —       | 内嵌标签页；无标题时替代标题栏，有标题时位于其下方。           |
| `cover`       | `ReactNode`                      | —       | 顶部封面。                                |
| `footer`      | `ReactNode`                      | —       | 底部内容或操作。                             |
| `loading`     | `boolean`                        | `false` | 使用骨架屏替换正文                            |
| `bordered`    | `boolean`                        | `true`  | 显示外轮廓                                |
| `divided`     | `boolean`                        | `false` | 用浅分隔线划分标题、内容和底部操作区。                  |
| `size`        | `'sm' \| 'md' \| 'lg'`           | `'md'`  | 卡片尺寸，影响内边距、标题字号、标题栏高度及内嵌 Tabs 的默认尺寸。 |

## 类型

定义组件属性或组装列表时可导入相关类型。

```ts
import type { CardProps, CardTabsProps, TabItem } from '@ifhover/leaf-ui';
```

## 使用说明

extra 和 footer 可以放置按钮或链接。需要点击操作时请使用明确的按钮或链接。

`tabs` 复用 Tabs 的配置和交互，固定使用顶部线形标签。`tabs.items[].children` 是对应页面内容；Card 的 `children` 可放置在所有页面下方的公共说明。`loading` 替换正文为骨架屏，标题、标签栏和操作保持可用。标签默认跟随卡片的 `size`，可用 `tabs.size` 单独调整；标签数组为空时恢复普通卡片。

可在 `tabs` 中设置禁用、图标、手动键盘激活、保留或销毁页面、溢出菜单以及增删、排序回调。`tabs.extra` 始终属于标签栏；有标题时 Card 的 `extra` 仍位于标题右侧。

## 外观与丰富内容

`description` 显示标题下的补充说明。普通卡片默认不显示内部边框，标签页卡片始终在标签栏下方展示分割线；设置 `divided` 可增加底部的分隔线与淡灰背景，操作区与 Modal、Drawer 使用一致的纵向留白。通过 `ConfigProvider` 的 `components.Card` 可定制背景、分区背景和边框。

## CardTabs API

| 属性                 | 类型                                                                                                       | 默认值           | 说明                      |
| ------------------ | -------------------------------------------------------------------------------------------------------- | ------------- | ----------------------- |
| `items`            | `readonly `[`TabItem`](https://ifhover.github.io/leaf-ui/v/0.6.0/components/tabs.md#tabitem)`[]`         | 必填            | 必需。标签与页面列表；为空时恢复普通卡片。   |
| `activeKey`        | `string`                                                                                                 | 首个可用项         | 受控的激活项。                 |
| `defaultActiveKey` | `string`                                                                                                 | 首个可用项         | 初始激活项。                  |
| `onChange`         | `(key: string) => void`                                                                                  | —             | 激活项变化时调用。               |
| `size`             | `'sm' \| 'md' \| 'lg'`                                                                                   | Card 的 `size` | 标签尺寸，可单独覆盖。             |
| `activationMode`   | `'automatic' \| 'manual'`                                                                                | `'automatic'` | 方向键直接激活，或回车 / 空格激活。     |
| `destroyInactive`  | `boolean`                                                                                                | `false`       | 切走时卸载内容；默认保留已访问页面。      |
| `extra`            | `ReactNode`                                                                                              | —             | 标签栏右侧的附加内容。             |
| `onClose`          | `(key: string, event: MouseEvent<HTMLButtonElement>) => void`                                            | —             | 请求关闭，由应用移除对应项；可阻止默认切换。  |
| `onAdd`            | `() => void`                                                                                             | —             | 添加页签，传入后显示添加按钮。         |
| `addLabel`         | `string`                                                                                                 | 当前语言的提示       | 添加按钮的可访问名称。             |
| `overflow`         | `boolean`                                                                                                | `true`        | 溢出页签收进更多菜单。             |
| `sortable`         | `boolean`                                                                                                | `false`       | 启用排序，配合 `onReorder` 使用。 |
| `onReorder`        | `(items: `[`TabItem`](https://ifhover.github.io/leaf-ui/v/0.6.0/components/tabs.md#tabitem)`[]) => void` | —             | 返回排序后的原始页签，由应用更新列表。     |