ZpElementPlus 组件文档

Appearance

SearchForm 介绍 ​

该组件是基于 Element-plus 框架的 Form 表单二次封装，主要用作查询条件使用。

基本使用 ​

查询条件包含：输入框，下拉框，级联，年份，月份，月份区间，日期区间，日期时间区间。

TIP

如果是区间形式，prop 以数组的形式传入 key。
如果需要在按钮后面追击其他按钮，可通过插槽形式插入，插槽名 extra。

输入框
下拉框
请选择
级联
年份
月份
月份区间
日期区间
日期时间区间
<template>
    <ZpSearchForm
        ref="zpSearchFormRef"
        :formConfig="{ labelWidth: 120 }"
        :formList="formList"
        @onSubmit="onSubmit"
        @onReset="onReset"
    >
        <template #extraBtn>
            <el-button type="danger" @click="exportList">导出</el-button>
        </template>
    </ZpSearchForm>
</template>

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

const zpSearchFormRef = ref<any>(null);
const formList = reactive([
    { type: 'input', label: '输入框', prop: 'aa' },
    {
        type: 'select',
        label: '下拉框',
        prop: 'bb',
        options: [
            { label: '上海', value: 'shanghai' },
            { label: '杭州', value: 'hangzhou' },
            { label: '北京', value: 'beijing' },
        ],
    },
    {
        type: 'cascader',
        label: '级联',
        prop: 'cc',
        options: [
            {
                label: '安徽',
                value: 'anhui',
                children: [
                    {
                        label: '合肥',
                        value: 'hefei',
                    },
                ],
            },
            {
                label: '福建',
                value: 'fujian',
                children: [
                    {
                        label: '厦门',
                        value: 'xiamen',
                    },
                ],
            },
        ],
    },
    { type: 'year', label: '年份', prop: 'year' },
    { type: 'month', label: '月份', prop: 'month', valueFormat: 'YYYY-MM' },
    { type: 'monthrange', label: '月份区间', prop: ['startMonth', 'endMonth'] },
    { type: 'daterange', label: '日期区间', prop: ['startDate', 'endDate'] },
    { type: 'datetimerange', label: '日期时间区间', prop: ['startDateTime', 'endDateTime'] },
]);

// 查询
const onSubmit = () => {
    const params = zpSearchFormRef.value.getFormData();
    console.log('查询：', params);
};
// 重置
const onReset = () => {
    const params = zpSearchFormRef.value.getFormData();
    console.log('重置：', params);
};
// 导出
const exportList = () => {
    const params = zpSearchFormRef.value.getFormData();
    console.log('导出：', params);
};
</script>

默认值 ​

默认值可通过 value 来设置。

输入框
下拉框
请选择
级联
年份
月份
月份区间
日期区间
日期时间区间
<template>
    <ZpSearchForm
        ref="zpSearchFormRef"
        :formConfig="{ labelWidth: 120 }"
        :formList="formList"
        @onSubmit="onSubmit"
        @onReset="onReset"
    />
</template>

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

const zpSearchFormRef = ref<any>(null);
const formList = reactive([
    { type: 'input', label: '输入框', prop: 'aa', value: '张三' },
    {
        type: 'select',
        label: '下拉框',
        prop: 'bb',
        value: 'hangzhou',
        options: [
            { label: '上海', value: 'shanghai' },
            { label: '杭州', value: 'hangzhou' },
            { label: '北京', value: 'beijing' },
        ],
    },
    {
        type: 'cascader',
        label: '级联',
        prop: 'cc',
        value: ['anhui', 'hefei'],
        options: [
            {
                label: '安徽',
                value: 'anhui',
                children: [
                    {
                        label: '合肥',
                        value: 'hefei',
                    },
                ],
            },
            {
                label: '福建',
                value: 'fujian',
                children: [
                    {
                        label: '厦门',
                        value: 'xiamen',
                    },
                ],
            },
        ],
    },
    { type: 'year', label: '年份', prop: 'year', value: '2000' },
    { type: 'month', label: '月份', prop: 'month', valueFormat: 'YYYY-MM', value: '2000-01' },
    {
        type: 'monthrange',
        label: '月份区间',
        prop: ['startMonth', 'endMonth'],
        value: ['2000-01', '2002-02'],
    },
    {
        type: 'daterange',
        label: '日期区间',
        prop: ['startDate', 'endDate'],
        value: ['2000-01-02', '2002-02-03'],
    },
    {
        type: 'datetimerange',
        label: '日期时间区间',
        prop: ['startDateTime', 'endDateTime'],
        value: ['2000-01-02 11:22', '2002-02-02 22:33'],
    },
]);

// 查询
const onSubmit = () => {
    const params = zpSearchFormRef.value.getFormData();
    console.log('查询：', params);
};
// 重置
const onReset = () => {
    const params = zpSearchFormRef.value.getFormData();
    console.log('重置：', params);
};
</script>

转换值 / 拼接时间后缀 ​

type：select 时，点击查询的时候，是否转换值为 boolean 类型的值。
type为daterange、datetimerange 时，是否拼接时间后缀，如 2024-01-02 00:00:00。

是否开启
请选择
日期区间
日期时间区间
<template>
    <ZpSearchForm
        ref="zpSearchFormRef"
        :formConfig="{ labelWidth: 120 }"
        :formList="formList"
        @onSubmit="onSubmit"
        @onReset="onReset"
    />
</template>

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

const zpSearchFormRef = ref<any>(null);
const formList = reactive([
    {
        type: 'select',
        label: '是否开启',
        prop: 'bb',
        options: [
            { label: '开启', value: 1 },
            { label: '关闭', value: 0 },
        ],
        isConvertToBoolean: true,
    },
    {
        type: 'daterange',
        label: '日期区间',
        prop: ['startDate', 'endDate'],
        isJoinTimeSuffix: true,
    },
    {
        type: 'datetimerange',
        label: '日期时间区间',
        prop: ['startDateTime', 'endDateTime'],
        isJoinTimeSuffix: true,
    },
]);

// 查询
const onSubmit = () => {
    const params = zpSearchFormRef.value.getFormData();
    console.log('查询：', params);
};
// 重置
const onReset = () => {
    const params = zpSearchFormRef.value.getFormData();
    console.log('重置：', params);
};
</script>

自定义表单项 ​

在现有的表单项下，可以添加自定义表单项，可通过设置 type: custom，customComponent: markRaw(<组件>) 来实现。

输入框
自定义-城市
占位符
<template>
    <ZpSearchForm
        ref="zpSearchFormRef"
        :formConfig="{ labelWidth: 120 }"
        :formList="formList"
        @onSubmit="onSubmit"
        @onReset="onReset"
    />
</template>

<script setup lang="ts">
import { ref, reactive, markRaw } from 'vue';
import CustomCity from './components/customCity.vue';

const zpSearchFormRef = ref<any>(null);
const formList = reactive([
    { type: 'input', label: '输入框', prop: 'aa' },
    {
        type: 'custom',
        label: '自定义-城市',
        prop: 'zz',
        customComponent: markRaw(CustomCity),
        placeholder: '占位符',
    },
]);

// 查询
const onSubmit = () => {
    const params = zpSearchFormRef.value.getFormData();
    console.log('查询：', params);
};
// 重置
const onReset = () => {
    const params = zpSearchFormRef.value.getFormData();
    console.log('重置：', params);
};
</script>
点击查看代码
vue
<!--
 * @Author: zhangping
 * @Date: 2024-06-06 17:41:05
 * @Description: 自定义下拉组件-选择城市
-->

<template>
    <el-select v-model="city" placeholder="请选择" clearable @change="changeCity" v-bind="restItem">
        <el-option v-for="item in options" :key="item.value" :label="item.label" :value="item.value" />
    </el-select>
</template>

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

const props = defineProps({
    value: {
        type: String,
        default: () => null,
    },
    restItem: {
        type: Object,
        default: () => {},
    },
});
const emit = defineEmits(['onChange']);

const options = [
    { label: '上海', value: 'shanghai' },
    { label: '杭州', value: 'hangzhou' },
    { label: '北京', value: 'beijing' },
];

const city = ref();

// change-城市
const changeCity = (val) => {
    emit('onChange', val);
};

watch(
    () => props.value,
    (newVal) => {
        city.value = newVal;
    },
    {
        immediate: true,
        deep: true,
    },
);
</script>

<style lang="less" scoped></style>

API ​

Attributes ​

属性名说明类型默认值
formConfig设置表单 Form 的属性，继承至 element-plus 的 Form APIobject-
formList设置表单项的列表，详见 formListarray[]
colSpan一行展示表单项的个数string3

element-plus 的Form API

formList ​

属性名说明类型默认值
type设置表单项类型，详见 type 枚举enum-
value默认值string / number / string[] / numbr[]-
options下拉框的下拉选项数据array-
customComponent自定义的组件, type: custom有效component-
isConvertToBoolean是否将值转换为boolean类型, type: select有效boolean-
isJoinTimeSuffix是否拼接时间后缀，type为daterange、datetimerange 有效，如 2024-01-02 00:00:00boolean-
onChange输入框改变时触发Function-
其他属性继承至 element-plus 的 FormItem API--

element-plus 的FormItem API

type 枚举 ​

属性名说明
input输入框
select下拉框
cascader级联
year年，如 2024
month月，如 2024-01
monthrange月区间，如 2024-01、2024-02
daterange日期区间，如 2024-01-02、2024-05-06
datetimerange日期时间区间，如 2024-01-02 11:22、2024-05-06 22:33
custom自定义

Events ​

方法名说明类型
onSubmit点击查询按钮时触发Function
onReset点击充值按钮时触发Function

Slot ​

插槽名说明
extraBtn在查询/重置按钮后面追加自定义的按钮