PickerPro 自定义选择器

介绍

主要用于提供多个选项集合供用户选择，支持单列选择、多列选择和级联选择以及搜索功能，基于 vant 的组件进行二次封装。使用了以下组件：

Popup 用于弹窗显示
Picker 用于选择器组件
Search 用于搜索输入框
Loading 用于显示加载状态
Icon 用于展示图标

引入

全局注册:

import { createApp } from "vue"
import { PickerPro } from "@dyb-dev/vant-pro"

const app = createApp()
app.use(PickerPro)

代码演示

提示

PickerPro 滑动选择只在移动端正常使用

源代码 ⬇️

<script setup lang="ts">
import { App, Button, Space } from "ant-design-vue"
import { reactive, ref } from "vue"

import { PickerPro, showPickerPro } from "@dyb-dev/vant-pro"

import CellPhoneBox from "@/components/CellPhoneBox.vue"
import JsonViewer from "@/components/JsonViewer.vue"

import type { TPickerProBaseSelectedResult } from "@dyb-dev/vant-pro"

interface IData {
    /** 搜索关键字 */
    searchKeyword: string
    /** 当前选择器值 */
    pickerValue: (string | number)[]
    /** 当前选中结果 */
    selectResult: TPickerProBaseSelectedResult | null
}

/** REACTIVE: 数据 */
const data: IData = reactive({
    searchKeyword: "",
    pickerValue: [],
    selectResult: null
})

/** REF: 手机盒子实例 */
const cellPhoneBox = ref<InstanceType<typeof CellPhoneBox>>()

/** STATIC: 数据 */
const columns = [
    {
        cityName: "浙江",
        cities: [
            {
                cityName: "杭州",
                cities: [{ cityName: "西湖区" }, { cityName: "余杭区" }]
            },
            {
                cityName: "温州",
                cities: [{ cityName: "鹿城区" }, { cityName: "瓯海区" }]
            }
        ]
    },
    {
        cityName: "福建",
        cities: [
            {
                cityName: "福州",
                cities: [{ cityName: "鼓楼区" }, { cityName: "台江区" }]
            },
            {
                cityName: "厦门",
                cities: [{ cityName: "思明区" }, { cityName: "海沧区" }]
            }
        ]
    }
]

/** STATIC: 字段名映射 */
const columnsFieldNames = {
    text: "cityName",
    value: "cityName",
    children: "cities"
}

/** EVENT: 函数式调用 */
const onClickButton1 = async() => {

    const _result = await showPickerPro({
        showSearch: true,
        pickerValue: data.pickerValue,
        teleport: cellPhoneBox.value?.boxElement,
        lockScroll: false,
        columnsFieldNames,
        async fetchDataFn(param) {

            data.searchKeyword = param.keyword

            await delay(500)
            // 模拟错误操作
            if (param.keyword === "test") {

                return

            }

            return columns

        },
        async beforeClose(action) {

            if (action.actionType === "confirm" && action.selectedValues.length > 0) {

                // 模拟其他操作
                await delay(500)

            }
            return true

        }
    })
    if (_result[0].actionType === "confirm" && _result[0].selectedValues.length > 0) {

        data.selectResult = _result[0]
        data.pickerValue = data.selectResult.selectedValues

    }

}

/** REF: 是否显示 */
const show = ref(false)

/** EVENT: 组件式调用 */
const onClickButton2 = async() => {

    show.value = true

}

/**
 * EVENT: 组件式调用时点击确认按钮
 *
 * @param selectResult 选中结果
 */
const onConfirm = (selectResult: TPickerProBaseSelectedResult) => {

    data.selectResult = selectResult

}

/**
 * FUN: 延迟
 *
 * @param ms 毫秒
 * @returns Promise<void>
 */
const delay = (ms: number): Promise<void> => {

    return new Promise<void>(resolve => setTimeout(resolve, ms))

}
</script>

<template>
    <App>
        <Space style="width: 100%" direction="vertical" size="middle">
            <Space style="width: 100%" direction="horizontal">
                <Button type="primary" @click="onClickButton1">函数式调用</Button>
                <Button type="primary" @click="onClickButton2">组件式调用</Button>
            </Space>

            <CellPhoneBox class="cell-phone-box" ref="cellPhoneBox">
                <PickerPro
                    v-model:show="show"
                    v-model:picker-value="data.pickerValue"
                    :columns="columns"
                    :columns-field-names="columnsFieldNames"
                    :lock-scroll="false"
                    @confirm="onConfirm"
                />
            </CellPhoneBox>

            <JsonViewer :value="data" :expand-depth="2" />
        </Space>
    </App>
</template>

API

vant-pro 中导出了 PickerPro 相关的辅助函数:

方法名	说明	参数	返回值
`showPickerPro`	显示选择器增强版弹窗	`options?: TShowPickerProOptions`	`Promise<TPickerProBaseResult>`

TShowPickerProOptions

调用 showPickerPro 等方法时，支持传入以下选项：

参数	说明	类型	默认值
pickerValue	当前选中项对应的值	`(number \| string)[]`	`[]`
columns	对象数组，配置每一列显示的数据	`TPickerProData`	`[]`
columnsFieldNames	自定义 columns 结构中的字段	`PickerFieldNames`	`{ text: 'text', values: 'values', children: 'children' }`
showSearch	是否显示搜索组件，使用搜索功能还需要传入 `fetchDataFn` 函数	`boolean`	`false`
title	顶部栏标题	`string`	`"请选择"`
confirmButtonText	确认按钮文字，设置为空字符串可以隐藏按钮	`string`	`"确认"`
cancelButtonText	取消按钮文字，设置为空字符串可以隐藏按钮	`string`	`"取消"`
allowHtml	是否允许选项内容中渲染 HTML	`boolean`	`false`
fetchDataFailTipText	请求数据失败提示文案	`string`	`"加载失败，点击重试"`
visibleOptionNum	可见的选项个数	`number`	`6`
optionHeight	选项高度，支持 px, vw, vh, rem 单位，默认 px	`number \| string`	`44`
swipeDuration	快速滑动时惯性滚动的时长，单位 ms	`number \| string`	`1000`
lockScroll	是否锁定背景滚动	`boolean`	`true`
teleport	指定挂载的节点，等同于 Teleport 组件的 to 属性	`string \| Element`	-
fetchDataFn	获取 Picker 数据的函数	`(param: TPickerProFetchDataFnParam) => TPickerProFetchDataFnReturn`	-
beforeClose	关闭前的回调函数，返回 false 可阻止关闭，支持返回 Promise	`(selectedResult: TPickerProBaseSelectedResult) => boolean \| Promise<boolean>`	-

Props

参数	说明	类型	默认值
v-model:show	是否显示	`boolean`	-
v-model:pickerValue	当前选中项对应的值	`(number \| string)[]`	`[]`
columns	对象数组，配置每一列显示的数据	`TPickerProData`	`[]`
columnsFieldNames	自定义 columns 结构中的字段	`PickerFieldNames`	`{ text: 'text', values: 'values', children: 'children' }`
showSearch	是否显示搜索组件，使用搜索功能还需要传入 `fetchDataFn` 函数	`boolean`	`false`
title	顶部栏标题	`string`	`"请选择"`
confirmButtonText	确认按钮文字，设置为空字符串可以隐藏按钮	`string`	`"确认"`
cancelButtonText	取消按钮文字，设置为空字符串可以隐藏按钮	`string`	`"取消"`
allowHtml	是否允许选项内容中渲染 HTML	`boolean`	`false`
fetchDataFailTipText	请求数据失败提示文案	`string`	`"加载失败，点击重试"`
visibleOptionNum	可见的选项个数	`number`	`6`
optionHeight	选项高度，支持 px, vw, vh, rem 单位，默认 px	`number \| string`	`44`
swipeDuration	快速滑动时惯性滚动的时长，单位 ms	`number \| string`	`1000`
lockScroll	是否锁定背景滚动	`boolean`	`true`
teleport	指定挂载的节点，等同于 Teleport 组件的 to 属性	`string \| Element`	-
fetchDataFn	获取 Picker 数据的函数，如果 `columns` 不存在时会在弹窗打开时调用该函数获取数据	`(param: TPickerProFetchDataFnParam) => TPickerProFetchDataFnReturn`	-
beforeClose	关闭前的回调函数，返回 false 可阻止关闭，支持返回 Promise	`(selectedResult: TPickerProBaseSelectedResult) => boolean \| Promise<boolean>`	-

Events

事件名	说明	回调参数
update:show	是否显示	-
update:pickerValue	更新选中的值	-
confirm	确认按钮点击	`params: TPickerProBaseSelectedResult`
cancel	取消按钮点击	`params: TPickerProBaseSelectedResult`

类型定义

组件导出以下类型定义：

import type {
    TPickerProBaseActionType,
    TPickerProBaseSelectedResult,
    TPickerProBaseUnmountParam,
    TShowPickerProBaseResult,
    TPickerProFetchDataFnParam,
    TPickerProData,
    TPickerProFetchDataFnReturn,
    IPickerProProps,
    TShowPickerProOptions
} from "@dyb-dev/vant-pro"

主题定制

请参考 vant 中 ConfigProvider 的使用

PickerPro 自定义选择器 ​

介绍 ​

引入 ​

代码演示 ​

API ​

TShowPickerProOptions ​

Props ​

Events ​

类型定义 ​

主题定制 ​