---
title: "SearchEmpty 搜索空态"
description: "搜索或筛选无结果时的空状态"
category: Status
status: beta
since: 0.3.4
tags: [search, empty, state]
syncStatus: reviewed
verified: true
---

## 用法

### 基础
:::TuffDemoWrapper{demo="SearchEmptySearchEmptyDemo" code-lang="vue"}
---
code: |
  <template>
    <TxSearchEmpty
      title="没有匹配结果"
      description="换一个关键词、清空筛选条件，或扩大搜索范围。"
      surface="card"
      :primary-action="{ label: '重置筛选', type: 'primary', icon: 'i-carbon-reset' }"
    />
  </template>
---
:::

### 后台筛选工具栏
:::TuffDemoWrapper{demo="ComponentsSearchFiltersDemo" code-lang="vue"}
---
code: |
  <template>
    <TxSearchEmpty
      title="没有匹配结果"
      description="换一个关键词或筛选范围，再重新搜索。"
      surface="card"
      :primary-action="{ label: '重置筛选', type: 'primary', icon: 'i-carbon-reset' }"
      @primary="resetFilters"
    />
  </template>
---
:::

### 最佳实践

- 查询或筛选没有匹配时使用；未筛选的数据为空用 `TxNoData`。
- 在附近回显失败的关键词或当前筛选条件，让用户知道搜了什么。
- 筛选可以恢复时，提供重置或扩大范围的操作。
- 留在原结果容器内，不改用全局 toast 或脱离列表的横幅。
- 替换整块结果面板时用 `surface="card"`；行内筛选反馈保持 `plain`。

## API 参考

继承 [TxEmptyState](./empty-state.zh.mdc) 除 `variant` 外的全部属性、事件与插槽；`variant` 固定为 `search-empty`。

### 属性

| 属性名 | 类型 | 默认值 | 说明 |
|------|------|---------|------|
| `title` | `string` | `No results` | 覆盖预设标题。 |
| `description` | `string` | `Try a different keyword or filter.` | 覆盖恢复建议。 |
| `icon` | `TxIconSource \| string \| null` | - | 替换搜索插画；`null` 隐藏图标区。 |
| `iconSize` | `number` | - | 图标尺寸。 |
| `layout` | `'vertical' \| 'horizontal'` | `'vertical'` | 图标与内容的排列方向。 |
| `align` | `'start' \| 'center' \| 'end'` | `'center'` | 图标、文案与操作的对齐。 |
| `size` | `'small' \| 'medium' \| 'large'` | `'medium'` | 间距、字号与插画尺寸。 |
| `surface` | `'plain' \| 'card'` | `'plain'` | `card` 为结果面板添加边框容器。 |
| `primaryAction` | `EmptyStateAction` | - | 生成主恢复操作，点击触发 `primary`。 |
| `secondaryAction` | `EmptyStateAction` | - | 生成次恢复操作，点击触发 `secondary`。 |
| `actionSize` | `TxButtonProps['size']` | `'sm'` | 生成按钮的默认尺寸。 |
| `loading` | `boolean` | `false` | 无自定义图标时显示 spinner。 |

### 事件

| 事件名 | 说明 |
|------|------|
| `primary` | 点击生成的主操作按钮时触发。 |
| `secondary` | 点击生成的次操作按钮时触发。 |

### 插槽

| 名称 | 说明 |
|------|------|
| `icon` | 替换搜索插画。 |
| `title` | 替换标题。 |
| `description` | 替换说明。 |
| `actions` | 替换生成的主/次操作按钮。 |

## 技术实现

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

<TuffDocSourceLink />