uView Next
4.0.105

外观

Search 搜索

约 2072 字大约 7 分钟

2025-10-31

搜索组件，集成了常见搜索框所需功能，用户可以一键引入，开箱即用。

基本使用

  • 通过 placeholder 参数设置占位内容
  • 通过 v-model 双向绑定一个变量值，设置初始化时搜索框的值，如果初始内容为空，那么请绑定一个值为空字符的变量。
<template>
	<un-search placeholder="日照香炉生紫烟" v-model="keyword"></un-search>
</template>

<script setup lang="uts">
	import { ref } from 'vue'
	const keyword = ref('遥看瀑布挂前川')
</script>

设置初始值

可以通过 v-model 设置搜索框的初始值。

<template>
	<un-search v-model="value" :show-action="false"></un-search>
</template>

<script setup lang="uts">
import { ref } from 'vue'

const value = ref('天山雪莲')
</script>

设置输入框形状

通过 shape 设置输入框两端的形状，square-方形带圆角，round(默认)-半圆形

<un-search shape="round"></un-search>

是否开启清除控件

clearabled(默认为 true)设置为 true 的话，输入框有内容时，右边会显示一个清除的图标

<un-search :clearabled="true"></un-search>

是否开启右边控件

该控件为类似按钮形式，可以设置为"搜索"或者"取消"等内容，如果开启动画效果，用户确认搜索后，该控件会自动消失

  • showAction 配置是否开启右边按钮控件
  • actionText 配置控件内容
  • animation(默认为 false)设置为 true 的话，失去焦点，或者点击控件按钮时，控件自动消失，并且带有动画效果

说明

  1. 如果不想点击右侧控件时自动消失，请把 animation 设置为 false
  2. 右侧控件的默认文字为"搜索"(它本意为控件，碰巧内容为"搜索"二字，并非说它就是一个搜索按钮)，点击它的时候触发的是 custom 事件，而不是 search 事件
<un-search :showAction="true" actionText="搜索" :animation="true"></un-search>

右侧控件动态显示

可以根据输入内容动态显示或隐藏右侧控件。

<template>
	<un-search v-model="value" @change="handleChange" :show-action="showAction"></un-search>
</template>

<script setup lang="uts">
import { ref } from 'vue'

const value = ref('')
const showAction = ref(false)

const handleChange = (e: string) => {
	if (value.value.length > 0) {
		showAction.value = true
	} else {
		showAction.value = false
	}
}
</script>

自定义右侧控件

可以通过插槽自定义右侧控件。

<template>
	<un-search v-model="value" @change="handleChange" :show-action="showAction">
		<template #action>
			<un-button type="primary" size="small" text="搜索"></un-button>
		</template>
	</un-search>
</template>

<script setup lang="uts">
import { ref } from 'vue'

const value = ref('')
const showAction = ref(false)

const handleChange = (e: string) => {
	if (value.value.length > 0) {
		showAction.value = true
	} else {
		showAction.value = false
	}
}
</script>

点击左侧图标

可以通过 @clickIcon 事件监听左侧图标的点击事件。

<template>
	<un-search v-model="value" :show-action="false" @clickIcon="clickIcon"></un-search>
</template>

<script setup lang="uts">
import { ref } from 'vue'

const value = ref('')

const clickIcon = () => {
	console.log('点击了左侧图标')
}
</script>

自定义搜索图标

可以通过 search-icon 属性自定义搜索图标。

<un-search v-model="value" search-icon="scan" :show-action="false"></un-search>

自定义右侧插槽

<un-search
	placeholder="自定义右侧插槽"
	v-model="value15"
	:search-icon="false"
	:show-action="false"
>
	<template #right>
		<un-icon name="scan" size="20"></un-icon>
	</template>
</un-search>

自定义样式

  • 通过 inputAlign 设置输入框内容的对其方式，和 css 的 text-align 同理
  • 通过 borderColor 设置整个搜索组件的边框，只要配置了颜色，才会出现边框
  • 通过 height 设置组件高度
  • 通过 disabled 设置是否禁用输入框
  • 通过 bgColor 设置是搜索组件背景颜色
<un-search inputAlign="center" height="70"></un-search>

自定义边框和背景

可以通过 borderColor 和 bgColor 属性自定义搜索框的边框和背景颜色。

<template>
	<un-search 
		v-model="value" 
		:show-action="false" 
		borderColor="rgb(230, 230, 230)"
		bgColor="#fff"
	></un-search>
</template>

<script setup lang="uts">
import { ref } from 'vue'

const value = ref('')
</script>

自定义颜色

可以通过 search-icon-color、placeholder-color 和 color 属性自定义搜索框各部分的颜色。

<template>
	<view class="demo">
		<!-- 自定义搜索图标颜色 -->
		<un-search 
			v-model="value1" 
			:show-action="false" 
			search-icon-color="#FF0000"
		></un-search>
		
		<!-- 自定义占位符颜色 -->
		<un-search 
			v-model="value2" 
			:show-action="false" 
			placeholder-color="#FF0000"
		></un-search>
		
		<!-- 自定义文字颜色 -->
		<un-search 
			v-model="value3" 
			:show-action="false" 
			color="#FF0000"
		></un-search>
	</view>
</template>

<script setup lang="uts">
import { ref } from 'vue'

const value1 = ref('')
const value2 = ref('')
const value3 = ref('')
</script>

监听事件

change 事件

当输入框内容发生变化时触发 change 事件，可以实时获取用户输入的内容：

<template>
	<view>
		<un-search 
			placeholder="请输入搜索内容" 
			v-model="searchValue" 
			@change="onSearchChange"
		/>
		<text class="search-text">当前输入：{{ searchValue }}</text>
	</view>
</template>

<script setup lang="uts">
import { ref } from 'vue'

const searchValue = ref<string>('')

const onSearchChange = (value: string) => {
	console.log('输入内容发生变化:', value)
	// 可以在这里处理实时搜索逻辑
}
</script>

<style>
.search-text {
	margin-top: 20rpx;
	font-size: 28rpx;
	color: #666;
}
</style>

search 事件

当用户确定搜索时触发 search 事件，比如按回车键或点击手机键盘的搜索键：

<template>
	<view>
		<un-search 
			placeholder="请输入关键词搜索" 
			v-model="keyword" 
			@search="onSearch"
		/>
		<view class="search-result" v-if="searchResult">
			<text>搜索结果：{{ searchResult }}</text>
		</view>
	</view>
</template>

<script setup lang="uts">
import { ref } from 'vue'

const keyword = ref<string>('')
const searchResult = ref<string>('')

const onSearch = (value: string) => {
	console.log('开始搜索:', value)
	// 模拟搜索逻辑
	searchResult.value = `搜索"${value}"的结果...`
}
</script>

<style>
.search-result {
	margin-top: 20rpx;
	padding: 20rpx;
	background-color: #f5f5f5;
	border-radius: 10rpx;
}
</style>

API

Props

参数说明类型默认值
v-model双向绑定输入框搜索值String-
shape搜索框形状
Enum
round
bgColor搜索框背景颜色String#f2f2f2
placeholder占位文字内容String请输入关键字
clearabled是否启用清除控件Booleantrue
focus是否自动获得焦点Booleanfalse
showAction是否显示右侧控件(右侧的"搜索"按钮)Booleantrue
actionStyle右侧控件的样式，对象形式Object-
actionText右侧控件文字String搜索
inputAlign输入框内容水平对齐方式
Enum
left
inputStyle自定义输入框样式，对象形式Object-
disabled是否启用输入框Booleanfalse
borderColor边框颜色，配置了颜色，才会有边框Stringtransparent
searchIconColor搜索图标的颜色，默认同输入框字体颜色String#909399
searchIconSize搜索图标的大小Number22
color输入框字体颜色String#606266
placeholderColorplaceholder 的颜色String#909399
searchIcon输入框左边的图标，可以为 uView 图标名称或图片路径String|Booleansearch
margin组件与其他上下左右元素之间的距离，带单位的字符串形式，如"30rpx"、"30rpx 20rpx"等写法String0
animation是否开启动画，见上方说明Booleanfalse
value输入框初始值String-
maxlength输入框最大能输入的长度，-1 为不限制长度String | Number-1
height输入框高度，单位 rpxString | Number64
label搜索左侧文本信息String | Number-

Events

事件名说明类型
change输入框内容发生变化时触发
Function
search用户确定搜索时触发，用户按回车键，或者手机键盘右下角的"搜索"键时触发
Function
custom用户点击右侧控件时触发
Function
blur输入框失去焦点时触发
Function
focus输入框获得焦点时触发
Function
clear配置了 clearabled 后，清空内容时会发出此事件
Function
clickdisabled 为 true 时，点击输入框，发出此事件，用于跳转搜索页
Function
clickIcon左侧 icon 点击时候时触发
Function

Slot

名称说明
lable自定义搜索框左边显示内容
right自定义右侧内容
action 4.0.101自定义右侧控件

Scss 变量

变量名默认值说明
$un-search-content-padding0 10px搜索框内容内边距
$un-search-close-width20px清除按钮宽度
$un-search-close-right10px清除按钮右侧距离
$un-search-close-bg-color#C6C7CB清除按钮背景色
$un-search-close-scale0.82清除按钮缩放比例
$un-search-input-margin0 5px输入框外边距
$un-search-input-height34px输入框高度
$un-search-action-active-width40px右侧激活态宽度
$un-search-action-active-margin-left5px右侧激活态左侧间距
$un-search-label-color$text-color标签文字颜色
$un-search-label-font-size$text-base标签文字大小

提示

组件内部默认使用 scss 变量，如需修改，请查看 scss 变量使用 文档

Copyright © 2026 uView Next