Vant

繁體中文

简体中文
English

繁體中文

简体中文
English

Appearance

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 圆角stringsquare
id🆔 搜索框 id，同时会设置 label 的 for 属性stringvan-search-n-input
background🎨 搜索框外部背景色，支持渐变色string#f2f2f2
maxlength📏 输入的最大字符数限制number | string-
placeholder💬 占位提示文字，引导用户输入string-
clearable🗑️ 是否启用清除图标，点击可清空输入框booleantrue
clear-icon🧹 清除图标名称或图片链接stringclear
clear-trigger👁️ 显示清除图标的时机，always 总是显示，focus 聚焦时显示stringfocus
autofocus🎯 是否自动聚焦（iOS 系统不支持）booleanfalse
show-action🎬 是否在搜索框右侧显示操作按钮booleanfalse
action-text📝 操作按钮文字内容string取消
disabled🚫 是否禁用输入框booleanfalse
readonly👀 是否将输入框设为只读状态booleanfalse
error❌ 是否将输入内容标红显示错误状态booleanfalse
error-message💥 底部错误提示文案，为空时不展示string-
formatter🔧 输入内容格式化函数(val: string) => string-
format-trigger⚡ 格式化函数触发时机，onChange 输入时，onBlur 失焦时stringonChange
input-align📐 输入框内容对齐方式，left 左对齐，center 居中，right 右对齐stringleft
left-icon🔍 输入框左侧图标名称或图片链接stringsearch
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-padding10px var(--van-padding-sm)🔲 搜索框整体内边距
--van-search-backgroundvar(--van-background-2)🎨 搜索框外部背景色
--van-search-content-backgroundvar(--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 事件，参见桌面端适配。

📚 相关文档 ​

📝 表单组件 ​

  • Field 输入框 - 基础输入框组件，支持多种输入类型
  • Form 表单 - 表单容器组件，提供数据收集和验证功能

🎛️ 交互组件 ​

🎨 反馈组件 ​

🔧 工具组件 ​

基於Vant構建的企業級移動端解決方案

Copyright © 2025 siex.cn ｜ sitemap