# SearchBox <small>搜索框</small>

## 示例

### 风格

可选的 [`ui`](#props-ui) 属性值：`strong`。

[[ demo src="/demo/search-box/style.vue" ]]

### 尺寸

可选的 [`ui`](#props-ui) 属性值：`xs` / `s` / `m` / `l`。

[[ demo src="/demo/search-box/size.vue" ]]

### 只读与禁用

[[ demo src="/demo/search-box/disabled.vue" ]]

### 推荐列表

[[ demo src="/demo/search-box/suggestion.vue" ]]

## API

### 属性

| 名称 | 类型 | 默认值 | 描述 |
| -- | -- | -- | -- |
| ``ui`` | `string=` | - | [^ui] |
| ``value`` | `string` | - | [^value] |
| ``disabled`` | `boolean=` | `false` | 是否为禁用状态。 |
| ``readonly`` | `boolean=` | `false` | 是否为只读状态。 |
| ``placeholder`` | `string` | - | 搜索框占位符。 |
| ``autofocus`` | `boolean` | `false` | 是否自动聚焦。 |
| ``clearable`` | `boolean` | `false` | 是否显示清除按钮。 |
| ``select-on-focus`` | `boolean` | `false` | 聚焦时是否自动选择文本。 |
| ``composition`` | `boolean` | `false` | 是否感知输入法状态。 |
| ``suggestions`` | `Array<string>|Array<Object>` | - | [^suggestions] |
| ``replace-on-select`` | `boolean` | `true` | 选择推荐项时是否自动使用其内容填充文本框。 |
| ``maxlength`` | `number=` | - | 最大可输入的字符长度。 |
| ``get-length`` | `function(string): number=` | - | 自定义的字符长度计算函数。 |
| ``strict`` | `boolean=` | `false` | 是否超出最大字符长度后不允许继续输入。 |
| ``trim`` | `boolean | string=` | `false` | [^trim] |
| ``suggest-trigger`` | `Array<string>|string` | `input` | [^suggest-trigger] |
| ``expanded`` | `boolean=` | `false` | [^expanded] |
| ``match`` | `(item, keyword, { ancestors }) => boolean | Array<[number, number]>` | - | 支持自定义高亮逻辑， 默认大小写不敏感，参考 [`Autocomplete`](./Autocomplete#自定义搜索逻辑)。 |
| ``filter`` | `(item, keyword, { ancestors, offsets }) => boolean` | - | 支持自定义搜索命中逻辑，参考 [`Autocomplete`](./Autocomplete#自定义搜索逻辑)。 |

^^^ui
按钮预设样式。

+++枚举值
| 值 | 描述 |
| -- | -- |
| `strong` | 加强样式，搜索图标变成搜索按钮，背景为主题色。 |
| `xs` | 特小尺寸样式。 |
| `s` | 小尺寸样式。 |
| `m` | 中等尺寸样式。 |
| `l` | 大尺寸样式。 |
+++
^^^

^^^value
:::badges
`v-model`
:::

输入框的值。
^^^

^^^suggestions
推荐列表。列表项为 `Object` 时格式为 `{label, value}`。

+++字段详情
| 名称 | 类型 | 描述 |
| -- | -- | -- |
| `label` | `string` | 推荐项文本。 |
| `value` | `string` | 推荐项值。 |
+++
^^^

^^^suggest-trigger
展示推荐列表的触发时机。可以是枚举值，也可以枚举值的组合。

+++枚举值
| 值 | 描述 |
| -- | -- |
| `focus` | 输入框聚焦时。 |
| `input` | 输入框触发 [`input`](#events-input) 事件时。 |
| `submit` | 点击搜索按钮时。 |
+++
^^^

^^^expanded
:::badges
`.sync`
:::

建议面板是否展开（如果 `suggestions` 中没有待选项，则即使为 `true` 时面板也会关闭）。
^^^

^^^trim
是否移除前后空格。当为 `true` 时，会移除前后空格，当为 `false` 时，不移除前后空格。设置为字符串时，按指定方式进行移除。

+++枚举值
| 值 | 描述 |
| -- | -- |
| `both` | 移除两端空格。等同于 `true` 时的行为。 |
| `start` | 移除开始空格。 |
| `end` | 移除末尾空格。 |
+++
^^^

### 插槽

| 名称 | 描述 |
| -- | -- |
| ``suggestions`` | [^slot-suggestions] |
| ``suggestions-before`` | 插入推荐列表前的内容。 |
| ``suggestions-after`` | 插入推荐列表后的内容。 |
| ``suggestion`` | [^slot-suggestion] |
| ``clear`` | 点击清除按钮时触发。 |
| ``group-label`` | 可以参考 [`Select`](./select) 组件的 [`group-label`](./select#props-group-label) 属性。 |
| ``option-label`` | 可以参考 [`Select`](./select) 组件的 [`option-label`](./select#props-option-label) 属性。 |

^^^slot-suggestions
推荐列表内容。

+++作用域参数
| 名称 | 类型 | 描述 |
| -- | -- | -- |
| `suggestions` | `Array<{value: string, label: string}>` | 从 [`suggestions`](#props-suggestions) 属性归一化类型后的推荐列表。 |
| `select` | `function(suggestion: {value: string, label: string}): void` | 选择指定的推荐项。 |

^^^slot-suggestion
推荐列表的单项插槽，用来定制选项内容。

+++作用域参数
| 名称 | 类型 | 描述 |
| -- | -- | -- |
| `label` | `string` | 选项文本。 |
| `value` | `string` | 选项值。 |

`suggestions` 中的每一项，除了 `label` 和 `value` 外的字段也会自动通过 `v-bind` 进行绑定。

当 `suggestions` 为 `Array<string>` 类型时，`label` 和 `value` 均为单项 `string` 值。
+++
^^^

### 事件

| 名称 | 描述 |
| -- | -- |
| ``input`` | [^event-input] |
| ``suggest`` | [^event-suggest] |
| ``select`` | [^event-select] |
| ``search`` | [^event-search] |
| ``toggle`` | 提示面板展开状态切换时触发，回调参数为 `(expanded: boolean)`。`expanded` 表示操作将触发提示面板展开还是收起。 |

^^^event-input
输入框中文本发生变化时触发该事件，回调参数为 `(value: string)`。

+++参数详情
| 名称 | 类型 | 描述 |
| -- | -- | -- |
| `value` | `string` | 输入框的值。 |
+++
^^^

^^^event-suggest
需要展示推荐列表时触发，回调参数为 `(value: string)`。

+++参数详情
| 名称 | 类型 | 描述 |
| -- | -- | -- |
| `value` | `string` | 输入框的值。 |
+++
^^^

^^^event-select
选择推荐列表某个选项时触发，回调参数为 `(item: Object)`。

+++参数详情
| 名称 | 类型 | 描述 |
| -- | -- | -- |
| `item` | `{label: string, value: string=, ...}` | 单个选项。 |
+++
^^^

^^^event-search
输入内容被提交时触发，回调参数为 `(value: string, event: Event)`。

+++参数详情
| 名称 | 类型 | 描述 |
| -- | -- | -- |
| `value` | `string` | 输入框的值。 |
| `event` | [`Event`](https://developer.mozilla.org/en-US/docs/Web/Events/click) | 原生点击事件。 |
+++
^^^

### 图标

| 名称 | 描述 |
| -- | -- |
| ``search`` | 搜索。 |