common-select-package 选择器组件库

一个功能强大的选择器组件库，包含单选和多选组件，方便最终联合表单校验，支持虚拟滚动、搜索、批量操作等功能。

组件列表

• ComSingleSelect: 单选下拉选择器
• ComMultiSelect: 多选下拉选择器
• BatchAddModal: 批量添加弹窗组件
• ComModal: 通用弹窗组件

安装

npm install common-select-package@latest 

引入

// 全局引入
import ComSelect from 'common-select-package'
app.use(ComSelect)

// 按需引入
import { ComSingleSelect, ComMultiSelect } from 'common-select-package'

ComMultiSelect 多选组件

一个功能强大的多选组件，支持虚拟滚动、搜索、批量操作等功能。

• 支持所有 Ant Design select 的基础功能
• 提供完整的 TypeScript 类型支持
• 支持全选、反选、一键清空等功能
• 提供完整的后端搜索功能
• 提供验证状态、表单红框校验显示
• 提供下拉插槽
• 提供自定义新增下拉值
• 支持键盘操作
• 支持批量添加

基础用法

<template>
  <ComMultiSelect
    v-model="selectedValues"
    :options="options"
    placeholder="请选择"
    @change="handleChange"
  />
</template>

<script setup>
import { ref } from 'vue'
import { ComMultiSelect } from 'common-select-package'

const selectedValues = ref([])
const options = ref([
  { label: '选项1', value: 'option1' },
  { label: '选项2', value: 'option2' },
  { label: '选项3', value: 'option3' }
])

const handleChange = (values) => {
  console.log('选中的值:', values)
}
</script>

API

Props

| 参数 | 说明 | 类型 | 默认值 | | --- | --- | --- | --- | | modelValue / v-model | 选中的值 | (string | number)[] | [] | | options | 选项数据 | MultiSelectOption[] | [] | | placeholder | 占位文本 | string | '请选择' | | disabled | 是否禁用 | boolean | false | | width | 宽度 | number | 0 (自适应) | | widthType | 宽度单位 | 'px' | 'vw' | 'px' | | minWidth | 最小宽度 | number | 140 | | maxWidth | 最大宽度 | number | 0 (无限制) | | height | 高度 | number | 32 | | maxTagCount | 最多显示多少个标签 | number | 1 | | modeType | 模式类型 | string | 'multiple' | | fieldName | 自定义字段名 | FieldNames | { label: 'label', value: 'value' } | | loading | 加载状态 | boolean | false | | pupLodaing | 下拉框加载状态 | boolean | false | | verification | 是否显示验证错误样式 | boolean | false | | autoCreate | 是否允许创建新选项 | boolean | true | | showSuffixIcon | 是否显示后缀图标 | boolean | false | | suffixIconClass | 后缀图标类名 | string | 'batchEdit' | | backendSearch | 是否使用后端搜索 | boolean | false | | showTag | 是否显示标签 | boolean | false | | showPropsTip | 提示文本 | string | '' |

Events

| 事件名 | 说明 | 回调参数 | | --- | --- | --- | | update:modelValue | 更新选中值 | (value: (string | number)[]) => void | | change | 选中值变化 | (value: (string | number)[]) => void | | search | 搜索事件 | (value: string) => void | | blur | 失焦事件 | () => void | | visibleChange | 下拉框显示状态变化 | (visible: boolean) => void | | batchAdd | 批量添加按钮点击 | () => void | | changeItem | 选项变化 | (item: string) => void |

Slots

| 插槽名 | 说明 | | --- | --- | | dropdownHeder | 下拉框头部内容 | | suffixIcon | 自定义后缀图标 | | timePicker | 时间选择器 | | [动态插槽] | 通过选项的 slotName 属性动态生成的插槽 |

方法

通过 ref 可以获取到组件实例并调用以下方法：

| 方法名 | 说明 | 参数 | | --- | --- | --- | | focus | 使组件获取焦点 | () => void | | blur | 使组件失去焦点 | () => void |

ComSingleSelect 单选组件

一个功能强大的单选组件，支持搜索、自定义字段映射等功能。

• 支持所有 Ant Design select 的基础功能
• 提供完整的 TypeScript 类型支持
• 提供验证状态、表单红框校验显示
• 支持自定义字段映射
• 支持提示信息

基础用法

<template>
  <ComSingleSelect
    v-model="selectedValue"
    :options="options"
    placeholder="请选择"
    @change="handleChange"
  />
</template>

<script setup>
import { ref } from 'vue'
import { ComSingleSelect } from 'common-select-package'

const selectedValue = ref('')
const options = ref([
  { label: '选项1', value: 'option1' },
  { label: '选项2', value: 'option2' },
  { label: '选项3', value: 'option3' }
])

const handleChange = (value) => {
  console.log('选中值:', value)
}
</script>

自定义字段映射

<template>
  <ComSingleSelect
    v-model="selectedValue"
    :options="customOptions"
    :fieldName="{ label: 'name', value: 'id' }"
    placeholder="请选择"
  />
</template>

<script setup>
import { ref } from 'vue'
import { ComSingleSelect } from 'common-select-package'

const selectedValue = ref('')
const customOptions = ref([
  { name: '用户1', id: 'user1' },
  { name: '用户2', id: 'user2' },
  { name: '用户3', id: 'user3' }
])
</script>

属性

| 属性名 | 说明 | 类型 | 默认值 | | --- | --- | --- | --- | | modelValue | 选中的值 | string | number | boolean | - | | options | 选项数据 | SingleSelectOption[] | [] | | placeholder | 占位文本 | string | '请选择' | | disabled | 是否禁用 | boolean | false | | width | 宽度 | number | 0 (自适应) | | minWidth | 最小宽度 | string | '140px' | | height | 高度 | number | 32 | | fieldName | 自定义字段名 | FieldNames | { label: 'label', value: 'value' } | | allowClear | 是否可清空 | boolean | false | | showSearch | 是否可搜索 | boolean | false | | optionFilterProp | 搜索时过滤对应的 option 属性 | string | 'label' | | verification | 是否显示验证错误样式 | boolean | false | | getPopupContainer | 菜单渲染父节点 | boolean | false | | dropdownMatchSelectWidth | 下拉菜单和选择器同宽 | boolean | false | | autoResetValue | 当选项变化时是否自动重置值 | boolean | false | | showPropsTip | 提示文本 | string | '' |

事件

| 事件名 | 说明 | 回调参数 | | --- | --- | --- | | update:modelValue | 更新选中值 | (value: string | number | boolean) => void | | change | 选中值变化 | (value: string | number | boolean) => void | | update:selectItem | 更新选中的完整项 | (item: SingleSelectOption | undefined) => void |

方法

通过 ref 可以获取到组件实例并调用以下方法：

| 方法名 | 说明 | 参数 | | --- | --- | --- | | focus | 使组件获取焦点 | () => void | | blur | 使组件失去焦点 | () => void |

高级用法

可搜索

<template>
  <ComSingleSelect
    v-model="selectedValue"
    :options="options"
    :showSearch="true"
    placeholder="请输入搜索"
  />
</template>

启用 showSearch 属性后，用户可以在下拉框中输入关键字进行搜索。默认情况下，搜索会匹配选项的 label 属性。

可清空

<template>
  <ComSingleSelect
    v-model="selectedValue"
    :options="options"
    :allowClear="true"
    placeholder="请选择"
  />
</template>

启用 allowClear 属性后，当有值时会显示清除按钮。

表单验证

<template>
  <ComSingleSelect
    v-model="selectedValue"
    :options="options"
    :verification="showVerification"
    placeholder="请选择（必填）"
  />
  <a-button @click="validate">验证</a-button>
</template>

<script setup>
import { ref } from 'vue'

const selectedValue = ref('')
const showVerification = ref(false)

const validate = () => {
  showVerification.value = !selectedValue.value
}
</script>

当 verification 属性为 true 且没有选中值时，组件会显示红色边框提示。

提示信息

<template>
  <ComSingleSelect
    v-model="selectedValue"
    :options="options"
    showPropsTip="这是一个提示信息"
    placeholder="请选择"
  />
</template>

设置 showPropsTip 属性后，组件会显示一个信息图标，鼠标悬停时会显示提示信息。

自定义宽度

<template>
  <ComSingleSelect
    v-model="selectedValue"
    :options="options"
    :width="200"
    placeholder="请选择"
  />
</template>

通过 width 属性可以设置组件的宽度，单位为像素。

与 ComMultiSelect 的区别

ComSingleSelect 和 ComMultiSelect 是两个不同的组件，分别用于单选和多选场景：

1. ComSingleSelect:

   • 只能选择一个选项
   • v-model 绑定的值是单个值（字符串、数字或布尔值）
   • 适用于从多个选项中选择一个的场景

2. ComMultiSelect:

   • 可以选择多个选项
   • v-model 绑定的值是数组
   • 提供批量添加功能
   • 适用于需要选择多个选项的场景

最佳实践

1. 选择合适的组件

• 如果用户只需要选择一个选项，使用 ComSingleSelect
• 如果用户需要选择多个选项，使用 ComMultiSelect

2. 处理异步数据

<template>
  <ComSingleSelect
    v-model="selectedValue"
    :options="options"
    :disabled="loading"
    placeholder="请选择"
  />
</template>

<script setup>
import { ref, onMounted } from 'vue'

const selectedValue = ref('')
const options = ref([])
const loading = ref(true)

onMounted(async () => {
  try {
    // 模拟异步请求
    const response = await fetch('/api/options')
    const data = await response.json()
    options.value = data
  } catch (error) {
    console.error('Failed to fetch options:', error)
  } finally {
    loading.value = false
  }
})
</script>

3. 表单集成

<template>
  <a-form :model="formState" @finish="onFinish">
    <a-form-item
      name="category"
      label="分类"
      :rules="[{ required: true, message: '请选择分类' }]"
    >
      <ComSingleSelect
        v-model:modelValue="formState.category"
        :options="categoryOptions"
        :verification="formErrors.category"
        placeholder="请选择分类"
      />
    </a-form-item>
    
    <a-form-item
      name="tags"
      label="标签"
      :rules="[{ required: true, message: '请选择至少一个标签' }]"
    >
      <ComMultiSelect
        v-model:modelValue="formState.tags"
        :options="tagOptions"
        :verification="formErrors.tags"
        placeholder="请选择标签"
      />
    </a-form-item>
    
    <a-form-item>
      <a-button type="primary" html-type="submit">提交</a-button>
    </a-form-item>
  </a-form>
</template>

<script setup>
import { ref, reactive } from 'vue'
import { Form, Button, message } from 'ant-design-vue'
import { ComSingleSelect, ComMultiSelect } from 'common-select-package'

const formState = reactive({
  category: '',
  tags: []
})

const formErrors = reactive({
  category: false,
  tags: false
})

const categoryOptions = ref([
  { label: '分类1', value: 'category1' },
  { label: '分类2', value: 'category2' },
  { label: '分类3', value: 'category3' }
])

const tagOptions = ref([
  { label: '标签1', value: 'tag1' },
  { label: '标签2', value: 'tag2' },
  { label: '标签3', value: 'tag3' },
  { label: '标签4', value: 'tag4' }
])

const onFinish = (values) => {
  console.log('Form values:', values)
  message.success('表单提交成功')
}
</script>

常见问题

Q: 如何在选项中显示禁用状态？

A: 可以在选项中添加 disabled 属性：

const options = ref([
  { label: '选项1', value: 'option1' },
  { label: '选项2', value: 'option2', disabled: true },
  { label: '选项3', value: 'option3' }
])

Q: 如何获取选中项的完整数据？

A: 可以监听 update:selectItem 事件：

<template>
  <ComSingleSelect
    v-model="selectedValue"
    :options="options"
    @update:selectItem="handleSelectItem"
    placeholder="请选择"
  />
</template>

<script setup>
import { ref } from 'vue'

const selectedValue = ref('')
const selectedItem = ref(null)

const handleSelectItem = (item) => {
  selectedItem.value = item
  console.log('完整选中项:', item)
}
</script>

Q: 如何实现级联选择？

A: 可以通过监听 change 事件来实现级联选择：

<template>
  <div>
    <ComSingleSelect
      v-model="province"
      :options="provinceOptions"
      @change="handleProvinceChange"
      placeholder="请选择省份"
    />
    
    <ComSingleSelect
      v-model="city"
      :options="cityOptions"
      :disabled="!province"
      placeholder="请选择城市"
      style="margin-left: 10px"
    />
  </div>
</template>

<script setup>
import { ref, watch } from 'vue'

const province = ref('')
const city = ref('')

const provinceOptions = ref([
  { label: '北京', value: 'beijing' },
  { label: '上海', value: 'shanghai' },
  { label: '广东', value: 'guangdong' }
])

const cityMap = {
  beijing: [
    { label: '朝阳区', value: 'chaoyang' },
    { label: '海淀区', value: 'haidian' }
  ],
  shanghai: [
    { label: '浦东新区', value: 'pudong' },
    { label: '黄浦区', value: 'huangpu' }
  ],
  guangdong: [
    { label: '广州', value: 'guangzhou' },
    { label: '深圳', value: 'shenzhen' }
  ]
}

const cityOptions = ref([])

const handleProvinceChange = (value) => {
  city.value = ''
  cityOptions.value = cityMap[value] || []
}

// 当省份变化时，重置城市选择
watch(province, (newValue) => {
  if (newValue) {
    cityOptions.value = cityMap[newValue] || []
  } else {
    cityOptions.value = []
  }
  city.value = ''
})
</script>

贡献指南

我们欢迎所有形式的贡献，包括但不限于：

• 提交问题和功能请求
• 提交代码修复或新功能
• 改进文档

请确保在提交代码前运行测试并遵循项目的代码风格。

许可证

MIT