---
url: /components/search-box.md
---
# SearchBox 搜索框

`EvSearchBox` 是本库的招牌组件：一体式三段结构 —— 分类下拉 ∣ 放大镜输入 ∣ 后缀动作位。
16px 大圆角配弥散软阴影，focus 时浮现主色光环，适合作为首屏的视觉锚点。

## 基础用法

\<EvSearchBox
large
placeholder="搜索文章、模板或帮助…"
:categories="\['全部', '文章', '模板', '帮助']"
style="max-width:640px;"

>

\<template #suffix>




```vue
<EvSearchBox large placeholder="搜索文章、模板或帮助…" :categories="['全部', '文章', '帮助']">
  <!-- 后缀位两种常见用法 -->
  <template #suffix>
    <EvKeycap :keys="['⌘', 'K']" />                     <!-- 快捷键提示 -->
    <EvIconButton icon="star-line" size="small" aria-label="收藏搜索结果" />  <!-- 轻动作 -->
  </template>
</EvSearchBox>
```

## 远程搜索（下拉结果）

`remote` 传入异步函数后进入远程模式：输入经防抖（默认 300ms）调用接口，
结果以 select 下拉形态呈现；`↑↓` 选择、`Enter` 确认、`Esc` 关闭，选中回填搜索词并派发 `select`。

\<EvSearchBox
large
placeholder="搜索组件，试试「按钮」或「表单」…"
:remote="remoteSearch"
:debounce="200"
style="max-width:640px;"
@select="onPick"
/>

```vue
<EvSearchBox
  v-model="keyword"
  :remote="async (kw) => {
    const res = await fetch('/api/search?q=' + kw)
    return (await res.json()).map(r => ({ title: r.name, description: r.desc }))
  }"
  @select="onPick"
/>
```

## 受控使用

```vue
<EvSearchBox v-model="kw" v-model:category="cat" :categories="cats" @search="onSearch" />
```

::: tip 与 EvIconGrid 的关系
[EvIconGrid](./icon-grid) 内部就使用本组件作为搜索头；单独引入 SearchBox 适合自定义搜索场景。
:::

## API

### Props

| 属性 | 说明 | 类型 | 默认值 |
| --- | --- | --- | --- |
| v-model | 搜索词 | string | `''` |
| categories | 分类项（字符串或 `{ label, value }`），空数组隐藏分类位 | array | `[]` |
| v-model:category | 当前分类 | string | `''` |
| size | 尺寸（large 为 hero 级） | `'default' \| 'large'` | `'default'` |
| placeholder | 占位文案 | string | `'Search'` |
| aria-label | 无障碍标签（缺省取 placeholder） | string | placeholder |

### 事件

| 事件 | 说明 | 参数 |
| --- | --- | --- |
| update:modelValue | 输入时派发 | string |
| update:category | 切换分类时派发 | string |
| search | 输入或切换分类时派发 | string |

### 插槽

| 插槽 | 说明 |
| --- | --- |
| suffix | 后缀动作位：快捷键提示（[EvKeycap](./keycap)）、收藏 / 历史记录（[EvIconButton](./icon-button)）等轻动作 |