wot-ui-plus3.1.0

主题

赞助商
成为赞助商

wd-select-picker 选择器 ​

14:29

组件概况 ​

组件概述 ​

选择器组件是一种常用的 UI 组件，用于在多个选项之间进行选择。wd-select-picker 组件提供了单选和多选两种模式，支持自定义样式、搜索功能、加载状态等，适用于各种需要在多个选项间选择的场景。

功能特性 ​

  • 支持单选和多选两种模式
  • 支持自定义左侧标签和标签宽度
  • 支持禁用和只读状态
  • 支持自定义占位符和弹出层标题
  • 支持自定义选中颜色和大小
  • 支持加载状态
  • 支持搜索功能（本地搜索）
  • 支持清空按钮
  • 支持表单验证
  • 支持自定义展示格式
  • 支持确认前校验
  • 支持底部安全距离设置
  • 支持从页面中脱离（解决 fixed 失效问题）

适用场景 ​

  • 表单中的选择字段
  • 筛选条件选择
  • 多选项配置
  • 分类选择
  • 标签选择

API 参考 ​

Props ​

属性名类型默认值必填描述
customStylestring''否自定义根节点样式
customClassstring''否自定义根节点样式类
labelstring-否选择器左侧文案
labelWidthstring'33%'否设置左侧标题宽度
disabledbooleanfalse否禁用
readonlybooleanfalse否只读
placeholderstring-否选择器占位符
titlestring-否弹出层标题
alignRightbooleanfalse否选择器的值靠右展示
errorbooleanfalse否是否为错误状态，错误状态时右侧内容为红色
requiredbooleanfalse否必填样式
useLabelSlotbooleanfalse否使用 label 插槽时设置该选项（已废弃，可直接使用标签插槽）
useDefaultSlotbooleanfalse否使用默认插槽时设置该选项（已废弃，可直接使用默认插槽）
sizestring-否设置选择器大小
centerbooleanfalse否是否垂直居中
checkedColorstring-否选中的颜色（单/复选框）
minnumber0否最小选中的数量（仅在复选框类型下生效，type类型为checkbox）
maxnumber0否最大选中的数量，0 为无限数量，默认为 0（仅在复选框类型下生效，type类型为checkbox）
selectSizestring-否设置 picker 内部的选项组尺寸大小 （单/复选框）
loadingbooleanfalse否加载中
loadingColorstring'#4D80F0'否加载的颜色，只能使用十六进制的色值写法，且不能使用缩写
closeOnClickModalbooleantrue否点击遮罩是否关闭
modelValuestring/number/boolean/array-是选中项，type类型为checkbox时，类型为 array；type为radio 时 ，类型为 number / boolean / string
columnsarray[]否选择器数据，一维数组
typestring'checkbox'否单复选选择器类型，可选值为 'checkbox' 或 'radio'
valueKeystring'value'否选项对象中，value 对应的 key
labelKeystring'label'否选项对象中，展示的文本对应的 key
confirmButtonTextstring-否确认按钮文案
displayFormatfunction-否自定义展示文案的格式化函数，返回一个字符串
beforeConfirmfunction-否确定前校验函数，接收 (value, resolve) 参数，通过 resolve 继续执行 picker，resolve 接收 1 个 boolean 参数
zIndexnumber15否弹窗层级
safeAreaInsetBottombooleantrue否弹出面板是否设置底部安全距离（iphone X 类型的机型）
filterablebooleanfalse否可搜索（目前只支持本地搜索）
filterPlaceholderstring-否搜索框占位符
ellipsisbooleanfalse否是否超出隐藏
scrollIntoViewbooleantrue否重新打开是否滚动到选中项
propstring-否表单域 model 字段名，在使用表单校验功能的情况下，该属性是必填的
rulesarray[]否表单验证规则，结合wd-form组件使用
customContentClassstring''否自定义内容样式类
customLabelClassstring''否自定义标签样式类
customValueClassstring''否自定义值样式类
showConfirmbooleantrue否是否显示确认按钮（radio类型生效），默认值为：true
clearablebooleanfalse否显示清空按钮
rootPortalbooleanfalse否是否从页面中脱离出来，用于解决各种 fixed 失效问题 (H5: teleport, APP: renderjs, 小程序: root-portal)
markerSidestring'before'否必填标记位置，可选值：before、after

Events ​

事件名触发条件参数说明
open打开选择器时触发-
change选择项变化时触发
confirm点击确认按钮时触发
cancel点击取消按钮或遮罩时触发-
clear点击清空按钮时触发-
update:modelValue选中值变化时触发选中的值
close选择器关闭时触发-

Slots ​

插槽名作用域变量描述
default-自定义选择器内容，替换默认的 cell 组件
label-自定义左侧标签内容

Methods ​

方法名参数返回值功能说明
open--打开选择器弹框
close--关闭选择器弹框

使用示例 ​

基础用法 ​

vue
<template>
  <wd-select-picker
    v-model="value"
    :columns="columns"
    label="选择器"
    placeholder="请选择"
    @change="onChange"
    @confirm="onConfirm"
  ></wd-select-picker>
</template>

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

const value = ref<string[]>([])

const columns = ref([
  { label: '选项1', value: '1' },
  { label: '选项2', value: '2' },
  { label: '选项3', value: '3' }
])

const onChange = ({ value }: { value: string[] }) => {
  console.log('选择变化:', value)
}

const onConfirm = ({ value, selectedItems }: { value: string[], selectedItems: any[] }) => {
  console.log('确认选择:', value, selectedItems)
}
</script>

单选模式 ​

vue
<template>
  <wd-select-picker
    v-model="value"
    :columns="columns"
    type="radio"
    label="单选选择器"
    placeholder="请选择"
  ></wd-select-picker>
</template>

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

const value = ref<string>('')

const columns = ref([
  { label: '选项1', value: '1' },
  { label: '选项2', value: '2' },
  { label: '选项3', value: '3' }
])
</script>

自定义样式 ​

vue
<template>
  <wd-select-picker
    v-model="value"
    :columns="columns"
    label="自定义样式"
    label-width="100px"
    align-right
    checked-color="#07c160"
    :custom-style="{ margin: '20px' }"
  ></wd-select-picker>
</template>

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

const value = ref<string[]>([])

const columns = ref([
  { label: '选项1', value: '1' },
  { label: '选项2', value: '2' },
  { label: '选项3', value: '3' }
])
</script>

带搜索功能 ​

vue
<template>
  <wd-select-picker
    v-model="value"
    :columns="columns"
    label="带搜索功能"
    filterable
    filter-placeholder="请输入搜索关键词"
  ></wd-select-picker>
</template>

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

const value = ref<string[]>([])

const columns = ref([
  { label: '选项1', value: '1' },
  { label: '选项2', value: '2' },
  { label: '选项3', value: '3' },
  { label: '选项4', value: '4' },
  { label: '选项5', value: '5' }
])
</script>

带清空按钮 ​

vue
<template>
  <wd-select-picker
    v-model="value"
    :columns="columns"
    label="带清空按钮"
    clearable
  ></wd-select-picker>
</template>

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

const value = ref<string[]>([])

const columns = ref([
  { label: '选项1', value: '1' },
  { label: '选项2', value: '2' },
  { label: '选项3', value: '3' }
])
</script>

自定义展示格式 ​

vue
<template>
  <wd-select-picker
    v-model="value"
    :columns="columns"
    label="自定义展示格式"
    :display-format="displayFormat"
  ></wd-select-picker>
</template>

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

const value = ref<string[]>([])

const columns = ref([
  { label: '选项1', value: '1' },
  { label: '选项2', value: '2' },
  { label: '选项3', value: '3' }
])

const displayFormat = (value: string[], columns: any[]) => {
  if (value.length === 0) {
    return '请选择'
  }
  return `已选择 ${value.length} 项：${value.join(', ')}`
}
</script>

确认前校验 ​

vue
<template>
  <wd-select-picker
    v-model="value"
    :columns="columns"
    label="确认前校验"
    :before-confirm="beforeConfirm"
  ></wd-select-picker>
</template>

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

const value = ref<string[]>([])

const columns = ref([
  { label: '选项1', value: '1' },
  { label: '选项2', value: '2' },
  { label: '选项3', value: '3' }
])

const beforeConfirm = (value: string[], resolve: (isPass: boolean) => void) => {
  if (value.length === 0) {
    uni.showToast({
      title: '请至少选择一项',
      icon: 'none'
    })
    resolve(false)
  } else {
    resolve(true)
  }
}
</script>

加载状态 ​

vue
<template>
  <wd-select-picker
    v-model="value"
    :columns="columns"
    label="加载状态"
    :loading="loading"
    loading-color="#07c160"
  ></wd-select-picker>
</template>

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

const value = ref<string[]>([])
const loading = ref(true)

const columns = ref([
  { label: '选项1', value: '1' },
  { label: '选项2', value: '2' },
  { label: '选项3', value: '3' }
])

// 模拟加载完成
setTimeout(() => {
  loading.value = false
}, 2000)
</script>

表单验证 ​

vue
<template>
  <wd-form @submit="onSubmit" ref="formRef">
    <wd-select-picker
      v-model="value"
      :columns="columns"
      label="表单验证"
      placeholder="请选择"
      prop="select"
      :rules="[{ required: true, message: '请选择选项', trigger: 'change' }]"
    ></wd-select-picker>
    <wd-button type="primary" block @click="onSubmit">提交</wd-button>
  </wd-form>
</template>

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

const formRef = ref<any>(null)
const value = ref<string[]>([])

const columns = ref([
  { label: '选项1', value: '1' },
  { label: '选项2', value: '2' },
  { label: '选项3', value: '3' }
])

const onSubmit = () => {
  formRef.value.validate().then(() => {
    console.log('验证通过')
  }).catch((error: any) => {
    console.log('验证失败:', error)
  })
}
</script>

样式定制 ​

自定义根节点样式 ​

使用 customStyle 属性可以自定义组件根节点的样式：

vue
<wd-select-picker
  :columns="columns"
  v-model="value"
  :custom-style="{ margin: '20px', borderRadius: '8px' }"
></wd-select-picker>

自定义根节点类名 ​

使用 customClass 属性可以自定义组件根节点的类名：

vue
<wd-select-picker
  :columns="columns"
  v-model="value"
  custom-class="my-select-picker"
></wd-select-picker>

<style scoped>
:deep(.my-select-picker) {
  margin: 20px;
  border-radius: 8px;
}
</style>

自定义标签和值样式 ​

使用 customLabelClass 和 customValueClass 属性可以自定义标签和值的样式：

vue
<wd-select-picker
  :columns="columns"
  v-model="value"
  label="自定义样式"
  custom-label-class="my-label"
  custom-value-class="my-value"
></wd-select-picker>

<style scoped>
:deep(.my-label) {
  color: #07c160;
  font-weight: bold;
}

:deep(.my-value) {
  color: #606266;
  font-size: 14px;
}
</style>

注意事项 ​

  1. 选项数据格式：columns 属性支持对象数组格式，每个对象必须包含 label 和 value 属性（可通过 labelKey 和 valueKey 自定义）。

  2. 模式差异：

    • checkbox 模式下，modelValue 为数组类型，支持多选
    • radio 模式下，modelValue 为字符串、数字或布尔值类型，支持单选

  3. 搜索功能：目前仅支持本地搜索，搜索时会高亮匹配的文本。

  4. 加载状态：设置 loading 为 true 时，选择器会显示加载动画，此时点击确认按钮会直接关闭选择器。

  5. 确认前校验：beforeConfirm 函数接收两个参数：当前选中值和一个回调函数，通过调用回调函数并传入 true 或 false 来决定是否继续执行确认操作。

  6. 表单验证：结合 wd-form 组件使用时，需要设置 prop 和 rules 属性。

  7. 清空按钮：设置 clearable 为 true 时，会显示清空按钮，点击后会触发 clear 事件并清空选中值。

  8. 底部安全距离：在 iPhone X 等机型上，建议设置 safeAreaInsetBottom 为 true，以避免弹出层内容被底部安全区域遮挡。

  9. 从页面中脱离：当遇到 fixed 定位失效问题时，可以设置 rootPortal 为 true，将弹出层从页面中脱离出来。

  10. 废弃属性：useLabelSlot 和 useDefaultSlot 属性已废弃，可直接使用插槽，无需配置这两个属性。

📖 Released under the MIT License

Copyright © 2025 Wot UI Plus