By-Components-V3

Appearance

ByCommonSelector 通用选择器组件 ​

一个功能强大的通用选择器组件，支持多种选择模式（下拉选择、复选框、边框选择）和丰富的功能特性。

基础用法 ​

下拉选择模式 ​

::: demo

vue
<template>
  <div>
    <by-common-selector v-model="selectedValue" :options="options" placeholder="请选择城市" @input="handleChange" />
    <p>选中值: {{ selectedValue }}</p>
  </div>
</template>

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

const selectedValue = ref('')
const options = ref([
  { id: 1, name: '何其灿', initial: 'H', status: 1 },
  { id: 2, name: '张三', initial: 'Z', status: 1 },
  { id: 3, name: '李四', initial: 'L', status: 1 },
  { id: 4, name: '王五', initial: 'W', status: 0 },
  { id: 5, name: '赵六', initial: 'Z', status: 1 },
  { id: 6, name: '孙七', initial: 'S', status: 1 },
  { id: 7, name: '周八', initial: 'Z', status: 1 },
  { id: 8, name: '吴九', initial: 'W', status: 1 },
  { id: 9, name: '郑十', initial: 'Z', status: 1 },
])

const handleChange = (value) => {
  console.log('选中值变化:', value)
}
</script>
::: ### 复选框模式 ::: demo ```vue
<template>
  <div>
    <by-common-selector
      v-model="selectedValues"
      type="checkbox"
      :options="options"
      :multiple="true"
      placeholder="请选择城市"
      @input="handleChange"
    />
    <p>选中值: {{ selectedValues }}</p>
  </div>
</template>

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

const selectedValues = ref([])
const options = ref([
  { id: 1, name: '何其灿2', initial: 'H', status: 1 },
  { id: 2, name: '张三', initial: 'Z', status: 1 },
  { id: 3, name: '李四', initial: 'L', status: 1 },
  { id: 4, name: '王五', initial: 'W', status: 0 },
  { id: 5, name: '赵六', initial: 'Z', status: 1 },
  { id: 6, name: '孙七', initial: 'S', status: 1 },
  { id: 7, name: '周八', initial: 'Z', status: 1 },
  { id: 8, name: '吴九', initial: 'W', status: 1 },
  { id: 9, name: '郑十', initial: 'Z', status: 1 },
])

const handleChange = (value) => {
  console.log('选中值变化:', value)
}
</script>
::: ### 边框选择模式 ::: demo ```vue
<template>
  <div>
    <by-common-selector
      v-model="selectedValue"
      type="border"
      :options="options"
      placeholder="请选择城市"
      @input="handleChange"
    />
    <p>选中值: {{ selectedValue }}</p>
  </div>
</template>

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

const selectedValue = ref('')
const options = ref([
  { id: 1, name: '何其灿3', initial: 'H', status: 1 },
  { id: 2, name: '张三', initial: 'Z', status: 1 },
  { id: 3, name: '李四', initial: 'L', status: 1 },
  { id: 4, name: '王五', initial: 'W', status: 0 },
  { id: 5, name: '赵六', initial: 'Z', status: 1 },
  { id: 6, name: '孙七', initial: 'S', status: 1 },
  { id: 7, name: '周八', initial: 'Z', status: 1 },
  { id: 8, name: '吴九', initial: 'W', status: 1 },
  { id: 9, name: '郑十', initial: 'Z', status: 1 },
])

const handleChange = (value) => {
  console.log('选中值变化:', value)
}
</script>
::: ### 带搜索栏的选择器 ::: demo ```vue
<template>
  <div>
    <by-common-selector
      v-model="selectedValue"
      :options="options"
      :show-search-bar="true"
      placeholder="请选择城市"
      @input="handleChange"
    />
    <p>选中值: {{ selectedValue }}</p>
  </div>
</template>

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

const selectedValue = ref('')
const options = ref([
  { id: 1, name: '何其灿4', initial: 'H', status: 1 },
  { id: 2, name: '张三', initial: 'Z', status: 1 },
  { id: 3, name: '李四', initial: 'L', status: 1 },
  { id: 4, name: '王五', initial: 'W', status: 0 },
  { id: 5, name: '赵六', initial: 'Z', status: 1 },
  { id: 6, name: '孙七', initial: 'S', status: 1 },
  { id: 7, name: '周八', initial: 'Z', status: 1 },
  { id: 8, name: '吴九', initial: 'W', status: 1 },
  { id: 9, name: '郑十', initial: 'Z', status: 1 },
])

const handleChange = (value) => {
  console.log('选中值变化:', value)
}
</script>
::: ### 异步加载数据 ::: demo ```vue
<template>
  <div>
    <by-common-selector
      v-model="selectedValue"
      :load-options="loadOptions"
      :need-show-loading="true"
      placeholder="请选择用户"
      @input="handleChange"
    />
    <p>选中值: {{ selectedValue }}</p>
  </div>
</template>

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

const selectedValue = ref('')

const loadOptions = async () => {
  // 模拟异步请求
  await new Promise((resolve) => setTimeout(resolve, 1000))
  return [
    { id: 1, name: '何其灿', initial: 'H', status: 1 },
    { id: 2, name: '张三', initial: 'Z', status: 1 },
    { id: 3, name: '李四', initial: 'L', status: 1 },
    { id: 4, name: '王五', initial: 'W', status: 0 },
    { id: 5, name: '赵六', initial: 'Z', status: 1 },
    { id: 6, name: '孙七', initial: 'S', status: 1 },
    { id: 7, name: '周八', initial: 'Z', status: 1 },
    { id: 8, name: '吴九', initial: 'W', status: 1 },
    { id: 9, name: '郑十', initial: 'Z', status: 1 },
  ]
}

const handleChange = (value) => {
  console.log('选中值变化:', value)
}
</script>
::: ### 带后置输入框的选择器 ::: demo ```vue
<template>
  <div>
    <by-common-selector
      v-model="selectedValue"
      :options="options"
      :show-suffix-input="true"
      suffix-input-placeholder="请输入数量"
      suffix-input-unit="个"
      :suffix-input-value="suffixValue"
      @input="handleChange"
      @update:suffix-input-value="handleSuffixChange"
    />
    <p>选中值: {{ selectedValue }}</p>
    <p>数量: {{ suffixValue }}</p>
  </div>
</template>

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

const selectedValue = ref('')
const suffixValue = ref('')
const options = ref([
  { id: 1, name: '何其灿', initial: 'H', status: 1 },
  { id: 1, name: '苹果', initial: 'P', status: 1 },
  { id: 2, name: '香蕉', initial: 'X', status: 1 },
  { id: 3, name: '橙子', initial: 'C', status: 1 },
  { id: 4, name: '葡萄', initial: 'P', status: 1 },
])

const handleChange = (value) => {
  console.log('选中值变化:', value)
}

const handleSuffixChange = (value) => {
  suffixValue.value = value
  console.log('数量变化:', value)
}
</script>

:::

API ​

Props ​

参数说明类型默认值
value选择器的值string | number | (string | number)[]-
type选择器类型'select' | 'checkbox' | 'border''select'
options选项数据Option[][]
loadOptions异步加载数据的函数() => Promise<Option[]>-
hiddenAllOptions是否隐藏全部选项booleanfalse
multiple是否多选booleanfalse
placeholder选择器占位符string'请选择'
size选择器大小string'small'
showSearchBar是否显示搜索栏booleanfalse
pagination是否启用分页booleanfalse
pageSize每页显示数量number50
needShowLoading异步加载时是否显示loadingbooleanfalse
showSuffixInput是否显示后置输入框booleanfalse
suffixInputPlaceholder后置输入框占位符string'请输入'
suffixInputValue后置输入框的值string''
suffixInputUnit后置输入框的单位string''
suffixInputOptions后置输入框的选项Record<string, any>{}

Events ​

事件名说明回调参数
input选择值变化时触发(value: SelectorValue) => void
update:suffixInputValue后置输入框值变化时触发(value: string) => void
suffix-input-change后置输入框值变化时触发(value: string) => void

Option 数据结构 ​

typescript
interface Option {
  id: number | string // 选项的唯一标识
  name: string // 选项显示名称
  initial?: string // 首字母（用于搜索栏）
  status?: number // 状态标识
}

特性说明 ​

搜索栏功能 ​

当启用搜索栏时（showSearchBar: true），组件会：

  1. 显示 A~Z 字母列表，方便快速定位
  2. 提供搜索框，支持按名称搜索
  3. 自动根据 name 字段生成 initial 值：
    • 中文：提取拼音首字母并转为大写
    • 非中文：直接取首字母并转为大写

分页功能 ​

当数据量较大时，可以启用分页功能：

  • pagination: true - 启用分页
  • pageSize - 设置每页显示数量
  • 支持展开/收起功能，自动检测是否需要展开按钮

异步加载 ​

支持异步加载数据，适用于大数据量场景：

javascript
const loadOptions = async () => {
  const response = await fetch('/api/options')
  return response.json()
}

后置输入框 ​

支持在选择器右侧添加输入框，常用于数量、金额等场景：

  • showSuffixInput: true - 显示后置输入框
  • suffixInputPlaceholder - 设置占位符
  • suffixInputUnit - 设置单位
  • suffixInputValue - 双向绑定输入值

注意事项 ​

  1. 当使用 loadOptions 时，options 属性将被忽略
  2. 多选模式下，value 应该是一个数组
  3. 搜索栏功能若无 initial 字段，则会自动生成
  4. 后置输入框的值需要手动绑定和更新

Released under the MIT License.

Copyright © 2024 贝颜科技