Search 搜索框

17:06

说明

集输入框、搜索图标、清除控件与可选右侧操作按钮于一体，通过 v-model 双向绑定关键字。回车（confirm-type="search"）触发 search，点击右侧按钮触发 custom，输入变化触发 input / change，聚焦且有内容时显示清除控件。

兼容性

平台	支持情况
App	✅ 支持
H5	✅ 支持
微信小程序	✅ 支持（animation 展开无过渡动画，右侧按钮瞬时显隐）

示例

基础用法

支持 v-model 双向绑定，可通过 @change、@search、@custom、@clear 监听事件。

查看源码

<template>
    <ux-search v-model="value" @search="onSearch" />
</template>

<script setup lang="uts">
const value = ref<string>('');

const onSearch = (val: string) => {
    uni.showToast({ title: '搜索: ' + val, icon: 'none' });
};
</script>

搜索框形状 shape

shape="square" 为小圆角（4px，默认），shape="round" 为胶囊。

查看源码

<template>
    <!-- 两档形状全演示：square 小圆角（4px，不传即此档） / round 胶囊 -->
    <ux-search v-model="squareValue" shape="square" />
    <ux-search v-model="roundValue" shape="round" />
</template>

<script setup lang="uts">
const squareValue = ref<string>('');
const roundValue = ref<string>('');
</script>

清除控件 clearabled

clearabled 控制是否显示清除图标，聚焦且输入内容时显示。

查看源码

<template>
    <ux-search v-model="value" :clearabled="true" />
</template>

<script setup lang="uts">
const value = ref<string>('可清除内容');
</script>

右侧控件 show-action

show-action 控制是否显示右侧搜索按钮，点击触发 @custom 事件。

查看源码

<template>
    <ux-search v-model="value" :show-action="true" @custom="onCustom" />
</template>

<script setup lang="uts">
const value = ref<string>('');

const onCustom = (val: string) => {
    uni.showToast({ title: '点击了右侧按钮: ' + val, icon: 'none' });
};
</script>

动画展开 animation

animation 为 true 时，右侧按钮在聚焦时展开，失焦时收起。

查看源码

<template>
    <ux-search v-model="value" :animation="true" />
</template>

<script setup lang="uts">
const value = ref<string>('');
</script>

对齐方式 input-align

input-align 控制输入框内容的水平对齐方式。

查看源码

<template>
    <ux-search v-model="value" input-align="center" />
</template>

<script setup lang="uts">
const value = ref<string>('');
</script>

API

Props

属性	说明	类型	默认值	版本
customStyle	自定义根节点样式	string | UTSJSONObject	-	-
customClass	自定义根节点样式类	string	''	-
shape	搜索框形状（词表见 types/global.uts 的 SearchShape）：square-小圆角 4px（默认），round-胶囊	SearchShape	'square'	-
bgColor	搜索框背景颜色	string	''	-
borderColor	边框颜色，配置了颜色，才会有边框	string	''	-
placeholder	占位文字内容	string	''	-
clearabled	是否启用清除控件	boolean	true	-
focus	是否自动获得焦点	boolean	false	-
showAction	是否显示右侧控件	boolean	true	-
actionText	右侧控件文字	string	''	-
actionStyle	右侧控件的样式，对象形式	UTSJSONObject	-	-
inputAlign	输入框内容水平对齐方式	InputAlign	'left'	-
inputStyle	自定义输入框样式，对象形式	UTSJSONObject	-	-
disabled	是否启用输入框	boolean	false	-
animation	是否开启动画，见上方说明	boolean	false	-
searchIconColor	搜索图标的颜色，默认同输入框字体颜色	string	''	-
color	输入框字体颜色	string	''	-
placeholderColor	placeholder 的颜色	string	''	-
searchIcon	搜索图标，可以为 uView 图标名称或图片路径	string	'search'	-
margin	组件与其他上下左右元素之间的距离，带单位的字符串形式，如"15px"	string	'0'	-
height	输入框高度，单位 px	string | number	32	-
maxlength	输入框最大能输入的长度，-1 为不限制长度	string | number	-1	-
modelValue	输入框的初始化内容	string	''	-
adjustPosition	弹出键盘时是否自动调节高度	boolean	true	-

Events

事件名	说明	回调参数	版本
input	输入框内容发生变化时触发	value: string	-
change	输入框内容发生变化时触发	value: string	-
search	用户确定搜索时触发	value: string	-
custom	用户点击右侧控件时触发	value: string	-
clear	用户点击清除按钮时触发	-	-
focus	输入框获得焦点时触发	value: string	-
blur	输入框失去焦点时触发	value: string	-
click	点击搜索框时触发（仅disabled=true时）	-	-

Slots

ux-search 无插槽。

注意事项

• animation 需与 show-action 同开才生效（在聚焦时展开、失焦时收起）；微信小程序端无过渡动画，按钮瞬时显隐。
• disabled 为 true 时输入框不可输入，此时点击整个组件才触发 click 事件（非禁用时不触发）。
• 点击清除图标会同时触发输入框 @blur，组件延后 100ms 才置失焦态，保证图标可被正常点中；clear 事件延后 50ms 发出。
• placeholder、action-text 未传时回落到组件内置文案（locale）。
• App 端 input-align 会一并写入内联 placeholder-style，使占位文字与输入内容对齐一致。