---
title: "SearchInput 搜索输入框"
description: "内置搜索图标、按 Enter 搜索的输入框"
category: Form
status: beta
since: 0.3.4
tags: [search, input, form]
syncStatus: reviewed
verified: true
---

## 用法

### 基础
按 Enter 立即派发 `search`。
:::TuffDemoWrapper{demo="SearchInputSearchInputDemo" code-lang="vue"}
---
code: |
  <template>
    <TxSearchInput v-model="value" placeholder="搜索" @search="onSearch" />
  </template>
---
:::

### 远程搜索
`remote` 在输入停止 `searchDebounce` 毫秒后派发 `search`；结果面板由宿主渲染。
:::TuffDemoWrapper{demo="SearchInputSearchInputRemoteDemo" code-lang="vue"}
---
code: |
  <script setup lang="ts">
  import { ref } from 'vue'

  const value = ref('')
  const hits = ref<string[]>([])
  const open = ref(false)

  async function onSearch(query: string) {
    hits.value = await searchApi(query)
    open.value = true
  }
  </script>

  <template>
    <TxPopover v-model="open" reference-full-width>
      <template #reference>
        <TxSearchInput
          v-model="value"
          remote
          :search-debounce="250"
          @focus="open = true"
          @search="onSearch"
        />
      </template>

      <button v-for="hit in hits" :key="hit" @click="value = hit">
        {{ hit }}
      </button>
    </TxPopover>
  </template>
---
:::

### 筛选工具栏
关键词交给 `TxSearchInput`，范围交给 `TxSearchSelect`，无结果时显示 `TxSearchEmpty`。
::::TuffDemoWrapper{demo="ComponentsSearchFiltersDemo" code-lang="vue"}
---
code: |
  <template>
    <TxSearchInput
      v-model="query"
      remote
      :search-debounce="180"
      placeholder="搜索插件 / 文档 / 任务"
      @search="onSearch"
    />
    <TxSearchSelect v-model="scope" :options="scopeOptions" placeholder="筛选范围" />
    <TxSearchEmpty v-if="!filteredRecords.length" description="换一个关键词或筛选范围。" />
  </template>
---
::::

### 最佳实践

- 只需关键词与 Enter 时用 `TxSearchInput`；需要结果面板或回填选中值时用 `TxSearchSelect`。
- `remote` 下 Enter 与防抖可能派发同一查询，请求处理保持幂等。
- 不要只靠 placeholder 表达含义；密集工具栏中提供外部标签或上下文。
- 只有本地或已完整缓存的搜索才把 `searchDebounce` 设为 `0`。
- 需要自定义前缀或后缀时直接使用 `TuffInput`。

## API 参考

### 属性

| 属性名 | 类型 | 默认值 | 说明 |
|------|------|---------|------|
| `modelValue` | `string` | `''` | 输入值，配合 `v-model` 使用。 |
| `placeholder` | `string` | `'Search'` | 占位文本。 |
| `disabled` | `boolean` | `false` | 禁止输入、清空与远程搜索。 |
| `clearable` | `boolean` | `true` | 有值时显示清空按钮。 |
| `remote` | `boolean` | `false` | 输入时按防抖派发 `search`。 |
| `searchDebounce` | `number` | `200` | 远程搜索的防抖时长（ms）。 |

### 事件

| 事件名 | 参数 | 说明 |
|------|------|------|
| `update:modelValue` | `(v: string)` | 输入值变化时触发。 |
| `input` | `(v: string)` | 与 `update:modelValue` 同时触发。 |
| `focus` | `(e: FocusEvent)` | 输入框获得焦点时触发。 |
| `blur` | `(e: FocusEvent)` | 输入框失去焦点时触发。 |
| `clear` | - | 清空按钮重置值后触发。 |
| `search` | `(v: string)` | 按 Enter 时立即触发；`remote` 下输入防抖结束后也触发。 |

### 暴露方法

| 名称 | 类型 | 说明 |
|------|------|------|
| `focus()` | `() => void` | 聚焦输入框。 |
| `blur()` | `() => void` | 使输入框失焦。 |
| `clear()` | `() => void` | 清空值并触发 `clear`。 |
| `setValue(v)` | `(v: string) => void` | 设置输入值。 |
| `getValue()` | `() => string` | 返回当前输入值。 |

## 技术实现

- 包装 `TuffInput` 并内置前缀搜索图标；清空行为与暴露方法均转发自 `TuffInput`。
- 源码：`packages/tuffex/packages/components/src/search-input/`。

<TuffDocSourceLink />