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, and this page is available as Markdown at https://ifhover.github.io/leaf-ui/components/card.md.

Card 卡片

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

基础用法

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

项目资料

在这里整理项目的说明与相关资料。
basic.tsx
import { Card } from '@ifhover/leaf-ui';

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

示例

选中状态

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

个人方案

适合个人使用。

团队方案

适合团队协作。
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
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
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
import { CardTitle } from '@ifhover/leaf-ui';

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

标题与底部操作

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

项目资料

有尚未保存的修改。
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
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-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
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

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

属性类型默认值说明
titleReactNode—卡片标题。
descriptionReactNode—标题下方的补充说明,仅默认外观支持;layered 不展示。
extraReactNode—标题旁的操作;没有标题时显示在标签栏右侧。
tabsCardTabsProps—内嵌标签页;无标题时替代标题栏,有标题时位于其下方。
coverReactNode—顶部封面。
footerReactNode—底部内容或操作;layered 展示在内容卡下方的外层区域。
loadingbooleanfalse将正文和标签页内容替换为骨架屏;不会禁用标题、标签页或操作。
borderedbooleantrue显示外轮廓;设为 false 移除边框。
shadowbooleantrue显示卡片的静止阴影;分层卡片将其应用于内层内容面。
selectedbooleanfalse标记选中外观,不提供选择交互;使用按钮或选择控件管理选中状态。
variant'default' | 'layered''default'卡片外观;layered 将内容卡与外层标题、底部操作分层展示。
size'sm' | 'md' | 'lg''md'卡片尺寸;内嵌标签页默认跟随此尺寸,其他子组件独立配置。

CardTabs API

内嵌标签页的可用属性见 Tabs API(新标签页打开)。Card 固定使用 type="line" 与 placement="top",并为标签页内容接入加载骨架;tabs.extra 仍属于标签栏,items 为空时恢复普通卡片。

type CardTabsProps = Omit<TabsProps, 'type' | 'placement' | 'children'>;

CardTitle API

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

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