---
title: "Card 卡片"
description: "带头部、正文与底部插槽的表面容器"
category: Layout
status: beta
since: 0.3.4
tags: [card, surface, layout]
syncStatus: reviewed
verified: true
---

## 用法

### 基础
:::TuffDemoWrapper{demo="CardBasicDemo" code-lang="vue"}
---
code: |
  <template>
    <TxCard background="glass">
      A generic container for content.
    </TxCard>
  </template>
---
:::

### 头部与底部
:::TuffDemoWrapper{demo="CardBasicSlotsDemo" code-lang="vue"}
---
code: |
  <template>
    <TxCard background="glass" shadow="soft">
      <template #header>
        Card title
        <TxButton size="sm" variant="ghost">Action</TxButton>
      </template>
      Slots: header / default / footer
      <template #footer>
        <TxButton size="sm" variant="secondary">Cancel</TxButton>
        <TxButton size="sm" variant="primary">Confirm</TxButton>
      </template>
    </TxCard>
  </template>
---
:::

### 惯性
`inertial` 让卡片跟随指针位移，离开后回弹；`inertialMaxOffset` 限制位移，`inertialRebound` 调节弹性。
:::TuffDemoWrapper{demo="CardInertialDemo" code-lang="vue"}
---
code: |
  <template>
    <TxCard inertial :inertial-max-offset="26" :inertial-rebound="0.12">
      Inertial drag
    </TxCard>
  </template>
---
:::

### 标题
:::TuffDemoWrapper{demo="CardHeaderDemo" code-lang="vue"}
---
code: |
  <template>
    <TxCard>
      <template #header>Card title</template>
      Using header slot
    </TxCard>
  </template>
---
:::

### 操作按钮
:::TuffDemoWrapper{demo="CardHeaderFooterActionsDemo" code-lang="vue"}
---
code: |
  <template>
    <TxCard shadow="soft">
      <template #header>
        User info
        <TxButton size="sm" variant="ghost">More</TxButton>
      </template>
      Zhang San · Frontend Engineer
      <template #footer>
        <TxButton size="sm" variant="secondary">Cancel</TxButton>
        <TxButton size="sm" variant="primary">Confirm</TxButton>
      </template>
    </TxCard>
  </template>
---
:::

### 变体
`plain` 去掉边框与悬停反馈。
:::TuffDemoWrapper{demo="CardVariantsDemo" code-lang="vue"}
---
code: |
  <template>
    <TxCard variant="solid">solid</TxCard>
    <TxCard variant="dashed">dashed</TxCard>
    <TxCard variant="plain">plain</TxCard>
  </template>
---
:::

### 背景材质
`background` 选择表面材质，推荐 `refraction`。
:::TuffDemoWrapper{demo="CardCardBackgroundsScrollDemo" code-lang="vue"}
---
code: |
  <template>
    <TxCard background="refraction" refraction-profile="filmic" refraction-tone="vivid">
      refraction
    </TxCard>
    <TxCard background="glass">glass</TxCard>
    <TxCard background="blur">blur</TxCard>
    <TxCard background="mask">mask</TxCard>
  </template>
---
:::

### 空状态
:::TuffDemoWrapper{demo="CardCardWithEmptyDemo" code-lang="vue"}
---
code: |
  <template>
    <TxCard variant="plain" background="mask" :padding="16">
      <TxEmpty title="Nothing here" description="Create your first item to get started.">
        <template #action>
          <TxButton variant="primary" size="sm">Create</TxButton>
        </template>
      </TxEmpty>
    </TxCard>
    <TxEmpty title="Empty only" description="No Card wrapper, pure empty block." compact />
  </template>
---
:::

### 浮层面板
Popover、SearchSelect 等浮层的面板由 TxCard 渲染，用 `panel-*` 属性配置。
:::TuffDemoWrapper{demo="CardCardCompositionsDemo" code-lang="vue"}
---
code: |
  <template>
    <TxPopover
      panel-variant="solid"
      panel-background="glass"
      panel-shadow="soft"
      :panel-radius="18"
      :panel-padding="10"
    >
      <template #reference>
        <TxButton variant="primary">Popover panel</TxButton>
      </template>
      Popover panel uses TxCard
    </TxPopover>
    <TxSearchSelect
      v-model="value"
      :options="options"
      panel-background="glass"
      panel-shadow="soft"
      :panel-radius="18"
      :panel-padding="6"
    />
  </template>
---
:::

### 尺寸
`size` 只影响内边距。
:::TuffDemoWrapper{demo="CardSizeDemo" code-lang="vue"}
---
code: |
  <template>
    <TxCard size="small">size=small</TxCard>
    <TxCard size="medium">size=medium</TxCard>
    <TxCard size="large">size=large</TxCard>
  </template>
---
:::

### 内边距与圆角
:::TuffDemoWrapper{demo="CardLayoutPropsDemo" code-lang="vue"}
---
code: |
  <template>
    <TxCard :padding="10" :radius="10">padding=10</TxCard>
    <TxCard :padding="18" :radius="10">padding=18</TxCard>
    <TxCard variant="plain" :padding="14" :radius="22">radius=22</TxCard>
  </template>
---
:::

### 状态
:::TuffDemoWrapper{demo="CardStatesDemo" code-lang="vue"}
---
code: |
  <template>
    <TxCard clickable @click="open">clickable</TxCard>
    <TxCard loading :loading-spinner-size="20">loading</TxCard>
    <TxCard disabled>disabled</TxCard>
  </template>
---
:::

### 最佳实践

- 整卡导航或选择时才用 `clickable`；独立动作放进插槽里的真实按钮或链接。
- 外观优先用 `variant`、`shadow`、`size`、`radius`、`padding` 调整，CSS 变量只用于对齐插槽内容或遮罩底色。
- 需要折射或滤镜的底层参数（`displace`、`distortionScale`、`redOffset` 等）时改用 `TxBaseSurface`。

## API 参考

### 属性

| 属性 | 类型 | 默认值 | 说明 |
|------|------|--------|------|
| `variant` | `'solid' \| 'dashed' \| 'plain'` | `'solid'` | 边框形态；`plain` 无边框、无悬停反馈。 |
| `background` | `'pure' \| 'blur' \| 'glass' \| 'refraction' \| 'mask'` | `'pure'` | 表面材质。 |
| `shadow` | `'none' \| 'soft' \| 'medium'` | `'none'` | 阴影强度。 |
| `size` | `'small' \| 'medium' \| 'large'` | `'medium'` | 内边距预设：`10` / `12` / `16` px。 |
| `radius` | `number` | `18` | 圆角（px）。 |
| `padding` | `number` | - | 内边距（px），优先于 `size`。 |
| `glassBlur` | `boolean` | `true` | `glass` / `refraction` 下启用模糊。 |
| `glassBlurAmount` | `number` | `22` | `glass` / `refraction` 下的模糊半径（px）。 |
| `glassOverlay` | `boolean` | `true` | `glass` / `refraction` 下启用高光层。 |
| `glassOverlayOpacity` | `number` | `0.18` | 高光层透明度。 |
| `maskOpacity` | `number` | `0.75` | `mask` 下的表面透明度，收敛到 `0..1`。 |
| `fallbackMaskOpacity` | `number` | `0.26` | 运动中降级为遮罩时的透明度（0–1）。 |
| `surfaceMoving` | `boolean` | `false` | 外部运动标记，与惯性运动合并后转发给表面。 |
| `refractionStrength` | `number` | `62` | 折射强度（0–100），驱动色散与扭曲。 |
| `refractionProfile` | `'soft' \| 'filmic' \| 'cinematic'` | `'filmic'` | 折射风格预设。 |
| `refractionTone` | `'mist' \| 'balanced' \| 'vivid'` | `'vivid'` | 折射色调预设；`vivid` 避免发灰。 |
| `refractionAngle` | `number` | `-24` | 色散主方向（度）。 |
| `refractionLightFollowMouse` | `boolean` | `false` | 高光锚点跟随指针。 |
| `refractionLightFollowIntensity` | `number` | `0.45` | 跟随权重（0–1），影响色散角度与强度。 |
| `refractionLightSpring` | `boolean` | `true` | 光源跟随使用弹簧过渡。 |
| `refractionLightSpringStiffness` | `number` | `0.18` | 光源弹簧刚度，收敛到 `0.01–0.55`。 |
| `refractionLightSpringDamping` | `number` | `0.84` | 光源弹簧阻尼，收敛到 `0.55–0.99`。 |
| `clickable` | `boolean` | `false` | 启用悬停与按压反馈（缩至 `0.985`），并派发 `click`。 |
| `loading` | `boolean` | `false` | 用 `TxSpinner` 遮罩覆盖卡片。 |
| `loadingSpinnerSize` | `number` | - | Spinner 尺寸（px），省略时为 `12`。 |
| `disabled` | `boolean` | `false` | 禁用样式，阻止 `click` 与指针动效。 |
| `inertial` | `boolean` | `false` | 跟随指针位移，离开后弹簧回弹。 |
| `inertialMaxOffset` | `number` | `22` | 最大跟随位移（px）。 |
| `inertialRebound` | `number` | `0.12` | 回弹系数，收敛到 `0..1`；越大越有弹性。 |

### 事件

| 事件名 | 参数 | 说明 |
|--------|------|------|
| `click` | `(event: MouseEvent)` | 可点击且未禁用时，点击或按 Enter / Space 触发。 |

### 插槽

| 插槽名 | Props | 说明 |
|--------|-------|------|
| `default` | - | 正文。 |
| `header` | - | 正文上方的头部。 |
| `footer` | - | 正文下方的底部。 |
| `cover` | - | 头部与正文之前的封面。 |

## 概述

- 可点击时根节点带 `role="button"` 与 `tabindex="0"`，Enter / Space 与点击一样触发 `click`；否则是无语义的 `div`。
- 可点击卡片禁用时设置 `aria-disabled` 并移出 Tab 序列。
- 只响应卡片自身的 Enter / Space，插槽内控件的按键不会触发卡片。
- `loading` 的遮罩带 `aria-hidden`，读屏或表单忙碌提示由调用方负责。
- `background` 作为表面模式转发给 `TxBaseSurface`：`mask` 使用 `maskOpacity`，`glass` 与 `refraction` 使用模糊与高光参数；折射参数只在 `refraction` 下生效。

## 技术实现

- 表面是 `aria-hidden` 的 `TxBaseSurface`；惯性由 `requestAnimationFrame` 弹簧写入 `--tx-card-dx` / `--tx-card-dy`，静止后停止。
- 源码：`packages/tuffex/packages/components/src/card/`。

<TuffDocSourceLink />

## 自定义

:::TuffCodeBlock{lang="css"}
---
code: |
  .custom-card {
    /* mask 与折射降级表面采样的底色 */
    --tx-card-fake-background: color-mix(in srgb, var(--tx-bg-color-overlay, #fff) 92%, transparent);
  }
---
:::

| 变量 | 写入方 | 用途 |
|------|--------|------|
| `--tx-card-radius` | `radius` | 根节点、表面、封面与加载层的圆角。 |
| `--tx-card-padding` | `padding` 或 `size` | 内边距与封面的负外边距。 |
| `--tx-card-dx` / `--tx-card-dy` | 惯性动效 | 根节点位移；不要手动设置。 |
| `--tx-card-fake-background` | 调用方 / 主题 | `mask` 与折射降级表面的底色。 |
| `--tx-surface-refraction-mask-color` | 根节点内联样式 | 把 `--tx-card-fake-background` 转给 `TxBaseSurface`；改前者即可。 |

跟随应用主题时覆盖全局 token，如 `--tx-bg-color-overlay`、`--tx-border-color-light`、`--tx-color-primary`。