Search 搜索

介绍

用于搜索场景的输入框组件。

引入

通过以下方式来全局注册组件,更多注册方式请参考组件注册

  1. import { createApp } from 'vue';
  2. import { Search } from 'vant';
  3. const app = createApp();
  4. app.use(Search);

代码演示

基础用法

v-model 用于控制搜索框中的文字,background 可以自定义搜索框外部背景色。

  1. <van-search v-model="value" placeholder="请输入搜索关键词" />
  1. import { ref } from 'vue';
  2. export default {
  3. setup() {
  4. const value = ref('');
  5. return { value };
  6. },
  7. };

事件监听

Search 组件提供了 searchcancel 事件,search 事件在点击键盘上的搜索/回车按钮后触发,cancel 事件在点击搜索框右侧取消按钮时触发。

  1. <form action="/">
  2. <van-search
  3. v-model="value"
  4. show-action
  5. placeholder="请输入搜索关键词"
  6. @search="onSearch"
  7. @cancel="onCancel"
  8. />
  9. </form>
  1. import { ref } from 'vue';
  2. import { Toast } from 'vant';
  3. export default {
  4. setup() {
  5. const value = ref('');
  6. const onSearch = (val) => Toast(val);
  7. const onCancel = () => Toast('取消');
  8. return {
  9. value,
  10. onSearch,
  11. onCancel,
  12. };
  13. },
  14. };

Tips: 在 van-search 外层增加 form 标签,且 action 不为空,即可在 iOS 输入法中显示搜索按钮。

搜索框内容对齐

通过 input-align 属性设置搜索框内容的对齐方式,可选值为 centerright

  1. <van-search
  2. v-model="value"
  3. placeholder="请输入搜索关键词"
  4. input-align="center"
  5. />

禁用搜索框

通过 disabled 属性禁用搜索框。

  1. <van-search v-model="value" disabled placeholder="请输入搜索关键词" />

自定义背景色

通过 background 属性可以设置搜索框外部的背景色,通过 shape 属性设置搜索框的形状,可选值为 round

  1. <van-search
  2. v-model="value"
  3. shape="round"
  4. background="#4fc08d"
  5. placeholder="请输入搜索关键词"
  6. />

自定义按钮

使用 action 插槽可以自定义右侧按钮的内容。使用插槽后,cancel 事件将不再触发。

  1. <van-search
  2. v-model="value"
  3. show-action
  4. label="地址"
  5. placeholder="请输入搜索关键词"
  6. @search="onSearch"
  7. >
  8. <template #action>
  9. <div @click="onClickButton">搜索</div>
  10. </template>
  11. </van-search>
  1. import { ref } from 'vue';
  2. import { Toast } from 'vant';
  3. export default {
  4. setup() {
  5. const value = ref('');
  6. const onSearch = (val) => Toast(val);
  7. const onClickButton = () => Toast(value.value);
  8. return {
  9. value,
  10. onSearch,
  11. onClickButton,
  12. };
  13. },
  14. };

API

Props

参数说明类型默认值
v-model当前输入的值number | string-
label搜索框左侧文本string-
name v3.2.3名称,作为提交表单时的标识符string-
shape搜索框形状,可选值为 roundstringsquare
id v3.2.2搜索框 id,同时会设置 label 的 for 属性stringvan-search-n-input
background搜索框外部背景色string#f2f2f2
maxlength输入的最大字符数number | string-
placeholder占位提示文字string-
clearable是否启用清除图标,点击清除图标后会清空输入框booleantrue
clear-icon v3.0.12清除图标名称或图片链接,等同于 Icon 组件的 name 属性stringclear
clear-trigger显示清除图标的时机,always 表示输入框不为空时展示,
focus 表示输入框聚焦且不为空时展示
stringfocus
autofocus是否自动聚焦,iOS 系统不支持该属性booleanfalse
show-action是否在搜索框右侧显示取消按钮booleanfalse
action-text取消按钮文字boolean取消
disabled是否禁用输入框booleanfalse
readonly是否将输入框设为只读状态,只读状态下无法输入内容booleanfalse
error是否将输入内容标红booleanfalse
error-message底部错误提示文案,为空时不展示string-
formatter v3.0.12输入内容格式化函数(val: string) => string-
format-trigger v3.0.12格式化函数触发的时机,可选值为 onBlurstringonChange
input-align输入框内容对齐方式,可选值为 center rightstringleft
left-icon输入框左侧图标名称或图片链接,等同于 Icon 组件的 name 属性stringsearch
right-icon输入框右侧图标名称或图片链接,等同于 Icon 组件的 name 属性string-
autocomplete v3.2.3input 标签原生的自动完成属性string-

Events

事件名说明回调参数
search确定搜索时触发value: string (当前输入的值)
update:model-value输入框内容变化时触发value: string (当前输入的值)
focus输入框获得焦点时触发event: Event
blur输入框失去焦点时触发event: Event
click-input点击输入区域时触发event: MouseEvent
click-left-icon v3.4.0点击左侧图标时触发event: MouseEvent
click-right-icon 3.4.0点击右侧图标时触发event: MouseEvent
clear点击清除按钮后触发event: MouseEvent
cancel点击取消按钮时触发-

方法

通过 ref 可以获取到 Search 实例并调用实例方法,详见组件实例方法

方法名说明参数返回值
focus获取输入框焦点--
blur取消输入框焦点--

类型定义

组件导出以下类型定义:

  1. import type { SearchProps, SearchShape, SearchInstance } from 'vant';

SearchInstance 是组件实例的类型,用法如下:

  1. import { ref } from 'vue';
  2. import type { SearchInstance } from 'vant';
  3. const searchRef = ref<SearchInstance>();
  4. searchRef.value?.focus();

Slots

名称说明
left自定义左侧内容(搜索框外)
action自定义右侧内容(搜索框外),设置 show-action 属性后展示
label自定义左侧文本(搜索框内)
left-icon自定义左侧图标(搜索框内)
right-icon自定义右侧图标(搜索框内)

主题定制

样式变量

组件提供了下列 CSS 变量,可用于自定义样式,使用方法请参考 ConfigProvider 组件

名称默认值描述
—van-search-padding10px var(—van-padding-sm)-
—van-search-background-colorvar(—van-background-color-light)-
—van-search-content-background-colorvar(—van-gray-1)-
—van-search-input-height34px-
—van-search-label-padding0 5px-
—van-search-label-colorvar(—van-text-color)-
—van-search-label-font-sizevar(—van-font-size-md)-
—van-search-left-icon-colorvar(—van-gray-6)-
—van-search-action-padding0 var(—van-padding-xs)-
—van-search-action-text-colorvar(—van-text-color)-
—van-search-action-font-sizevar(—van-font-size-md)-

常见问题

在桌面端点击清除按钮无效?

清除按钮监听是的移动端 Touch 事件,参见桌面端适配

Search 搜索 - 图1