---
title: "Empty 空状态"
description: "用于面板与筛选结果的紧凑空状态卡片"
category: Status
status: beta
since: 0.3.4
tags: [empty, state, placeholder]
syncStatus: reviewed
verified: true
---

## 用法

### 基础
`compact` 切换为小尺寸，`iconClass` 替换图标。
:::TuffDemoWrapper{demo="EmptyEmptyDemo" code-lang="vue"}
---
code: |
  <template>
    <TxEmpty title="没有匹配结果" description="调整筛选条件或清空关键字后再试。" icon-class="i-carbon-search" compact />
  </template>
---
:::

### 操作
:::TuffDemoWrapper{demo="EmptyEmptyActionDemo" code-lang="vue"}
---
code: |
  <template>
    <TxEmpty title="还没有项目" description="创建第一个项目后，可以在这里统一管理。">
      <template #action>
        <TxButton type="primary">新建项目</TxButton>
      </template>
    </TxEmpty>
  </template>
---
:::

### 最佳实践

- 列表、搜索结果或面板中需要卡片表面的占位用 `TxEmpty`。
- 空的原因有产品含义时，改用 `TxNoData`、`TxNoSelection`、`TxOfflineState` 或 `TxPermissionState`。
- 侧栏、表格内部等密集区域设置 `compact`。
- 点击逻辑写在 `action` 插槽内的控件上；`TxEmpty` 不派发事件。

## API 参考

渲染 [TxEmptyState](./empty-state.zh.mdc)，固定 `variant="empty"`、`surface="card"`、`layout="vertical"`。

### 属性

| 属性名 | 类型 | 默认值 | 说明 |
|------|------|---------|------|
| `title` | `string` | `'Nothing here'` | 主文案。 |
| `description` | `string` | `''` | 标题下的说明。 |
| `iconClass` | `string` | `'i-carbon-incomplete'` | 图标 class，作为 `icon` 传给 `TxEmptyState`。 |
| `compact` | `boolean` | `false` | 为 `true` 时 `size="small"`，否则为 `medium`。 |

### 插槽

| 插槽名 | Props | 说明 |
|------|------|------|
| `icon` | - | 替换 `iconClass` 图标。 |
| `title` | - | 替换标题。 |
| `description` | - | 替换说明。 |
| `action` | - | 操作区，替换 `TxEmptyState` 的 `actions` 插槽。 |

## 技术实现

- 源码：`packages/tuffex/packages/components/src/empty/`。

<TuffDocSourceLink />