Search 搜索 - Vant 4
🔍 Search 搜索
🎯 介绍
Search 组件是用于搜索场景的输入框组件,支持双向绑定、背景色自定义、事件监听等能力,常与列表、筛选功能搭配使用。
📦 引入
通过以下方式来全局注册组件,更多注册方式请参考组件注册。
js
import { createApp } from'vue'; import { Search } from'vant'; const app = createApp(); app.use(Search);🎯 代码演示
🔍 基础用法
最简单的搜索框!通过 v-model 双向绑定搜索内容,background 属性让你轻松定制外观。
html
<template>
<div class="demo-search">
<!-- 基础搜索框 -->
<van-search v-model="value" placeholder="请输入搜索关键词" />
<p>当前输入:{{ value }}</p>
<!-- 自定义背景色 -->
<van-search
v-model="value2"
placeholder="自定义背景色"
background="#4fc08d"
/>
</div>
</template>js
import { ref } from 'vue';
export default {
setup() {
const value = ref('');
const value2 = ref('');
return {
value,
value2
};
},
};🎯 事件监听
让搜索更智能!监听 search 和 cancel 事件,实现搜索确认和取消操作的完美交互。
html
<template>
<div class="demo-search">
<van-search
v-model="searchValue"
placeholder="输入关键词后按回车搜索"
show-action
@search="onSearch"
@cancel="onCancel"
@focus="onFocus"
@blur="onBlur"
/>
<div class="search-result" v-if="searchResult">
<p>搜索结果:{{ searchResult }}</p>
</div>
</div>
</template>js
import { ref } from 'vue';
import { showToast } from 'vant';
export default {
setup() {
const searchValue = ref('');
const searchResult = ref('');
const onSearch = (val) => {
searchResult.value = `正在搜索"${val}"...`;
showToast(`搜索:${val}`);
};
const onCancel = () => {
searchValue.value = '';
searchResult.value = '';
showToast('已取消搜索');
};
const onFocus = () => {
showToast('搜索框已聚焦');
};
const onBlur = () => {
showToast('搜索框失去焦点');
};
return {
searchValue,
searchResult,
onSearch,
onCancel,
onFocus,
onBlur
};
},
};💡 小贴士:在 van-search 外层增加 form 标签,且 action 不为空,即可在 iOS 输入法中显示搜索按钮。
📐 搜索框内容对齐
让文字更有序!通过 input-align 属性控制搜索内容的对齐方式,打造不同的视觉效果。
html
<template>
<div class="demo-search">
<!-- 左对齐(默认) -->
<van-search
v-model="leftValue"
placeholder="左对齐(默认)"
input-align="left"
/>
<!-- 居中对齐 -->
<van-search
v-model="centerValue"
placeholder="居中对齐"
input-align="center"
/>
<!-- 右对齐 -->
<van-search
v-model="rightValue"
placeholder="右对齐"
input-align="right"
/>
</div>
</template>js
import { ref } from 'vue';
export default {
setup() {
const leftValue = ref('');
const centerValue = ref('');
const rightValue = ref('');
return {
leftValue,
centerValue,
rightValue
};
},
};🚫 禁用搜索框
需要暂时禁用搜索?通过 disabled 属性轻松实现,保持界面一致性。
html
<template>
<div class="demo-search">
<!-- 正常状态 -->
<van-search
v-model="normalValue"
placeholder="正常状态的搜索框"
/>
<!-- 禁用状态 -->
<van-search
v-model="disabledValue"
placeholder="禁用状态的搜索框"
disabled
/>
<!-- 只读状态 -->
<van-search
v-model="readonlyValue"
placeholder="只读状态的搜索框"
readonly
/>
</div>
</template>js
import { ref } from 'vue';
export default {
setup() {
const normalValue = ref('');
const disabledValue = ref('已禁用');
const readonlyValue = ref('只读内容');
return {
normalValue,
disabledValue,
readonlyValue
};
},
};🎨 自定义背景色和形状
让搜索框更有个性!通过 background 和 shape 属性打造独特的视觉风格。
html
<template>
<div class="demo-search">
<!-- 方形搜索框(默认) -->
<van-search
v-model="squareValue"
placeholder="方形搜索框"
background="#f7f8fa"
shape="square"
/>
<!-- 圆角搜索框 -->
<van-search
v-model="roundValue"
placeholder="圆角搜索框"
background="#fff2e8"
shape="round"
/>
<!-- 渐变背景 -->
<van-search
v-model="gradientValue"
placeholder="渐变背景搜索框"
background="linear-gradient(135deg, #667eea 0%, #764ba2 100%)"
shape="round"
/>
</div>
</template>js
import { ref } from 'vue';
export default {
setup() {
const squareValue = ref('');
const roundValue = ref('');
const gradientValue = ref('');
return {
squareValue,
roundValue,
gradientValue
};
},
};🎛️ 自定义按钮
想要更个性化的操作按钮?使用 action 插槽自定义右侧按钮,实现更丰富的交互功能。
html
<template>
<div class="demo-search">
<!-- 自定义文字按钮 -->
<van-search
v-model="customValue"
placeholder="自定义按钮文字"
show-action
>
<template #action>
<div @click="onClickButton" class="search-action">
搜索
</div>
</template>
</van-search>
<!-- 自定义图标按钮 -->
<van-search
v-model="iconValue"
placeholder="自定义图标按钮"
show-action
>
<template #action>
<van-icon
name="search"
@click="onClickIcon"
class="search-icon"
/>
</template>
</van-search>
<!-- 多个自定义按钮 -->
<van-search
v-model="multiValue"
placeholder="多个自定义按钮"
show-action
>
<template #action>
<van-button
size="small"
type="primary"
@click="onSearch"
>
搜索
</van-button>
<van-button
size="small"
@click="onClear"
style="margin-left: 8px;"
>
清空
</van-button>
</template>
</van-search>
</div>
</template>js
import { ref } from 'vue';
import { showToast } from 'vant';
export default {
setup() {
const customValue = ref('');
const iconValue = ref('');
const multiValue = ref('');
const onClickButton = () => {
showToast(`搜索:${customValue.value}`);
};
const onClickIcon = () => {
showToast(`图标搜索:${iconValue.value}`);
};
const onSearch = () => {
showToast(`执行搜索:${multiValue.value}`);
};
const onClear = () => {
multiValue.value = '';
showToast('已清空搜索内容');
};
return {
customValue,
iconValue,
multiValue,
onClickButton,
onClickIcon,
onSearch,
onClear
};
},
};css
.search-action {
padding: 0 16px;
color: #1989fa;
font-size: 14px;
line-height: 34px;
cursor: pointer;
}
.search-icon {
padding: 0 16px;
color: #1989fa;
font-size: 16px;
line-height: 34px;
cursor: pointer;
}📖 API
🎛️ Props
| 参数 | 说明 | 类型 | 默认值 |
|---|---|---|---|
| v-model | 🔗 当前输入的值,支持双向绑定 | number | string | - |
| label | 🏷️ 搜索框左侧文本标签 | string | - |
| name | 📝 名称,作为提交表单时的标识符 | string | - |
| shape | 🔘 搜索框形状,square 方形,round 圆角 | string | square |
| id | 🆔 搜索框 id,同时会设置 label 的 for 属性 | string | van-search-n-input |
| background | 🎨 搜索框外部背景色,支持渐变色 | string | #f2f2f2 |
| maxlength | 📏 输入的最大字符数限制 | number | string | - |
| placeholder | 💬 占位提示文字,引导用户输入 | string | - |
| clearable | 🗑️ 是否启用清除图标,点击可清空输入框 | boolean | true |
| clear-icon | 🧹 清除图标名称或图片链接 | string | clear |
| clear-trigger | 👁️ 显示清除图标的时机,always 总是显示,focus 聚焦时显示 | string | focus |
| autofocus | 🎯 是否自动聚焦(iOS 系统不支持) | boolean | false |
| show-action | 🎬 是否在搜索框右侧显示操作按钮 | boolean | false |
| action-text | 📝 操作按钮文字内容 | string | 取消 |
| disabled | 🚫 是否禁用输入框 | boolean | false |
| readonly | 👀 是否将输入框设为只读状态 | boolean | false |
| error | ❌ 是否将输入内容标红显示错误状态 | boolean | false |
| error-message | 💥 底部错误提示文案,为空时不展示 | string | - |
| formatter | 🔧 输入内容格式化函数 | (val: string) => string | - |
| format-trigger | ⚡ 格式化函数触发时机,onChange 输入时,onBlur 失焦时 | string | onChange |
| input-align | 📐 输入框内容对齐方式,left 左对齐,center 居中,right 右对齐 | string | left |
| left-icon | 🔍 输入框左侧图标名称或图片链接 | string | search |
| right-icon | ➡️ 输入框右侧图标名称或图片链接 | string | - |
| autocomplete | 🤖 input 标签原生的自动完成属性 | string | - |
🎯 Events
| 事件名 | 说明 | 回调参数 |
|---|---|---|
| search | 🔍 确定搜索时触发(按回车或点击搜索按钮) | value: string (当前输入的值) |
| update:model-value | 📝 输入框内容变化时触发 | value: string (当前输入的值) |
| focus | 🎯 输入框获得焦点时触发 | event: Event |
| blur | 😴 输入框失去焦点时触发 | event: Event |
| click-input | 👆 点击输入区域时触发 | event: MouseEvent |
| click-left-icon | ⬅️ 点击左侧图标时触发 | event: MouseEvent |
| click-right-icon | ➡️ 点击右侧图标时触发 | event: MouseEvent |
| clear | 🗑️ 点击清除按钮后触发 | event: MouseEvent |
| cancel | ❌ 点击取消按钮时触发 | - |
🔧 Methods
通过 ref 可以获取到 Search 实例并调用实例方法,详见组件实例方法。
| 方法名 | 说明 | 参数 | 返回值 |
|---|---|---|---|
| focus | 🎯 获取输入框焦点 | - | - |
| blur | 😴 取消输入框焦点 | - | - |
📝 类型定义
组件导出以下类型定义,方便 TypeScript 开发:
ts
import type { SearchProps, SearchShape, SearchInstance } from 'vant';SearchInstance 是组件实例的类型,用法如下:
ts
import { ref } from 'vue';
import type { SearchInstance } from 'vant';
const searchRef = ref<SearchInstance>();
searchRef.value?.focus();🎨 Slots
| 名称 | 说明 |
|---|---|
| left | ⬅️ 自定义左侧内容(搜索框外) |
| action | 🎬 自定义右侧内容(搜索框外),设置 show-action 属性后展示 |
| label | 🏷️ 自定义左侧文本(搜索框内) |
| left-icon | 🔍 自定义左侧图标(搜索框内) |
| right-icon | ➡️ 自定义右侧图标(搜索框内) |
🎨 主题定制
🎛️ 样式变量
组件提供了下列 CSS 变量,可用于自定义样式,使用方法请参考 ConfigProvider 组件。
| 名称 | 默认值 | 描述 |
|---|---|---|
| --van-search-padding | 10px var(--van-padding-sm) | 🔲 搜索框整体内边距 |
| --van-search-background | var(--van-background-2) | 🎨 搜索框外部背景色 |
| --van-search-content-background | var(--van-gray-1) | 🎨 搜索框内容区域背景色 |
| --van-search-input-height | 34px | 📏 输入框高度 |
| --van-search-label-padding | 0 5px | 🔲 标签内边距 |
| --van-search-label-color | var(--van-text-color) | 🎨 标签文字颜色 |
| --van-search-label-font-size | var(--van-font-size-md) | 📝 标签字体大小 |
| --van-search-left-icon-color | var(--van-gray-6) | 🎨 左侧图标颜色 |
| --van-search-action-padding | 0 var(--van-padding-xs) | 🔲 操作按钮内边距 |
| --van-search-action-text-color | var(--van-text-color) | 🎨 操作按钮文字颜色 |
| --van-search-action-font-size | var(--van-font-size-md) | 📝 操作按钮字体大小 |
常见问题
在桌面端点击清除按钮无效?
清除按钮监听是的移动端 Touch 事件,参见桌面端适配。
📚 相关文档
📝 表单组件
🎛️ 交互组件
🎨 反馈组件
- Toast 轻提示 - 轻提示组件,用于搜索结果反馈
- Loading 加载 - 加载组件,用于搜索过程中的加载状态
- Empty 空状态 - 空状态组件,用于无搜索结果时的展示
🔧 工具组件
- ConfigProvider 全局配置 - 全局配置组件,用于主题定制
- Popup 弹出层 - 弹出层组件,可用于搜索建议或筛选面板