从零封装一个高复用性的el-select-v2远程搜索组件-洪萨配资

1. 为什么需要封装el-select-v2远程搜索组件

在中后台管理系统开发中，表单筛选条件需要从服务端动态获取选项的场景非常常见。比如用户管理模块需要根据部门筛选员工，订单管理需要根据商品分类筛选订单等。如果每个地方都直接使用el-select-v2组件，会导致大量重复代码，维护起来非常困难。

我接手过一个项目，里面有20多个地方都用到了远程搜索功能。最初每个地方都是独立实现的，后来需求变更要统一修改搜索逻辑时，简直是一场噩梦。这就是为什么我们需要封装一个高复用性的远程搜索组件。

封装后的组件应该具备这些特点：

统一管理远程请求逻辑
支持灵活配置搜索参数
自动处理加载状态
内置防抖优化
支持自定义数据转换
易于重置和刷新

2. 基础封装方案

我们先来看一个最基本的封装实现。创建一个ElSelectV2文件夹，里面放index.vue文件：

<template> <el-select-v2 v-model="selectedValue" filterable remote :remote-method="handleRemoteSearch" :options="options" :loading="loading" :placeholder="placeholder" /> </template> <script setup> import { ref, watch } from 'vue' const props = defineProps({ modelValue: [String, Number, Array], apiFunc: { type: Function, required: true }, placeholder: { type: String, default: '请输入关键词搜索' }, labelKey: { type: String, default: 'label' }, valueKey: { type: String, default: 'value' } }) const emit = defineEmits(['update:modelValue']) const loading = ref(false) const options = ref([]) const selectedValue = ref(props.modelValue) const handleRemoteSearch = async (query) => { if (!query) { options.value = [] return } loading.value = true try { const res = await props.apiFunc(query) options.value = res.data.map(item => ({ label: item[props.labelKey], value: item[props.valueKey] })) } finally { loading.value = false } } watch(selectedValue, (val) => { emit('update:modelValue', val) }) watch(() => props.modelValue, (val) => { selectedValue = val }) </script>

这个基础版本已经实现了：

通过apiFunc prop传入搜索API
自动管理加载状态
支持自定义label和value的字段名
双向绑定支持

3. 增强功能实现

基础版本虽然能用，但实际项目中还需要更多增强功能。下面我们来逐步完善。

3.1 添加防抖功能

频繁触发远程搜索会导致性能问题，我们需要添加防抖：

import { debounce } from 'lodash-es' const handleRemoteSearch = debounce(async (query) => { // 原有逻辑 }, 500)

3.2 支持初始数据加载

很多时候我们需要组件初始化时就加载一些数据：

const initOptions = ref([]) const loadInitData = async () => { try { const res = await props.apiFunc('') initOptions.value = res.data.map(item => ({ label: item[props.labelKey], value: item[props.valueKey] })) } catch (e) { console.error(e) } } // 在onMounted中调用 onMounted(() => { if (props.initLoad) { loadInitData() } })

3.3 添加缓存功能

对于不常变的数据，可以添加本地缓存：

const cache = new Map() const handleRemoteSearch = debounce(async (query) => { if (cache.has(query)) { options.value = cache.get(query) return } // 原有请求逻辑 cache.set(query, options.value) }, 500)

4. 完整封装方案

结合所有增强功能，我们的完整组件代码如下：

<template> <el-select-v2 v-model="selectedValue" filterable remote :remote-method="handleRemoteSearch" :options="showOptions" :loading="loading" :placeholder="placeholder" :disabled="disabled" clearable @clear="handleClear" > <template #prefix> <el-icon v-if="showSearchIcon"><Search /></el-icon> </template> </el-select-v2> </template> <script setup> import { ref, watch, computed, onMounted } from 'vue' import { debounce } from 'lodash-es' import { Search } from '@element-plus/icons-vue' const props = defineProps({ modelValue: [String, Number, Array], apiFunc: { type: Function, required: true }, placeholder: { type: String, default: '请输入关键词搜索' }, labelKey: { type: String, default: 'label' }, valueKey: { type: String, default: 'value' }, initLoad: { type: Boolean, default: false }, disabled: { type: Boolean, default: false }, showSearchIcon: { type: Boolean, default: true }, cacheEnabled: { type: Boolean, default: true } }) const emit = defineEmits(['update:modelValue', 'change']) const loading = ref(false) const initOptions = ref([]) const searchOptions = ref([]) const selectedValue = ref(props.modelValue) const cache = new Map() const showOptions = computed(() => { return searchOptions.value.length ? searchOptions.value : initOptions.value }) const loadInitData = async () => { try { const res = await props.apiFunc('') initOptions.value = res.data.map(item => ({ label: item[props.labelKey], value: item[props.valueKey] })) } catch (e) { console.error('初始化加载失败:', e) } } const handleRemoteSearch = debounce(async (query) => { if (!query && !props.initLoad) { searchOptions.value = [] return } if (props.cacheEnabled && cache.has(query)) { searchOptions.value = cache.get(query) return } loading.value = true try { const res = await props.apiFunc(query) const newOptions = res.data.map(item => ({ label: item[props.labelKey], value: item[props.valueKey] })) searchOptions.value = newOptions if (props.cacheEnabled) { cache.set(query, newOptions) } } catch (e) { console.error('搜索失败:', e) searchOptions.value = [] } finally { loading.value = false } }, 500) const handleClear = () => { searchOptions.value = [] emit('change', null) } watch(selectedValue, (val) => { emit('update:modelValue', val) emit('change', val) }) watch(() => props.modelValue, (val) => { selectedValue.value = val }) onMounted(() => { if (props.initLoad) { loadInitData() } }) </script>

5. 组件使用示例

在父组件中使用封装好的远程搜索组件：

<template> <el-form :model="queryParams" ref="queryRef"> <el-form-item label="部门筛选"> <RemoteSelect v-model="queryParams.department" :api-func="fetchDepartments" label-key="name" value-key="id" init-load placeholder="请输入部门名称" @change="handleDepartmentChange" /> </el-form-item> </el-form> </template> <script setup> import { ref } from 'vue' import RemoteSelect from '@/components/RemoteSelect/index.vue' import { getDepartments } from '@/api/department' const queryParams = ref({ department: null }) const fetchDepartments = async (keyword) => { return await getDepartments({ keyword }) } const handleDepartmentChange = (value) => { console.log('部门选择变化:', value) } </script>

6. 高级功能扩展

6.1 自定义选项渲染

有时候我们需要自定义选项的显示方式：

<template> <el-select-v2 ... > <template #default="{ item }"> <div class="custom-option"> <span>{{ item.label }}</span> <el-tag v-if="item.extra" size="small">{{ item.extra }}</el-tag> </div> </template> </el-select-v2> </template>

6.2 多选支持

添加对多选模式的支持：

const props = defineProps({ // ...其他props multiple: { type: Boolean, default: false } }) // 在el-select-v2上添加 :multiple="multiple"

6.3 远程搜索与本地过滤结合

有时候我们需要先加载全部数据，然后在本地过滤：

const handleRemoteSearch = debounce(async (query) => { if (props.localFilter) { options.value = initOptions.value.filter(item => item.label.includes(query) ) return } // 原有远程搜索逻辑 }, 500)

7. 常见问题解决

7.1 组件重置问题

使用key强制刷新组件是最简单的重置方法：

<template> <RemoteSelect :key="refreshKey" ... /> </template> <script setup> const refreshKey = ref(0) const resetForm = () => { refreshKey.value++ } </script>

7.2 性能优化

对于大数据量的情况，可以添加虚拟滚动优化：

<el-select-v2 ... :height="300" :item-height="40" />

7.3 错误处理

添加统一的错误处理逻辑：

const handleRemoteSearch = debounce(async (query) => { try { // 请求逻辑 } catch (error) { ElMessage.error('搜索失败: ' + error.message) options.value = [] } finally { loading.value = false } }, 500)