快捷表单 · ElementPlus

核心 API 请查阅 快捷表单-基础篇，本文档仅说明 ElementPlus 框架下的特化配置。

导入路径

import { $initHook, $Input, $Select, $DatePicker } from '@jiess/plus/vue3';

ElementPlus 表单组件映射

Jiess 组件	ElementPlus 组件	说明
$Input	el-input	文本输入
$InputNumber	el-input-number	数字输入
$Select	el-select	下拉选择
$DatePicker	el-date-picker	日期选择
$TimePicker	el-time-picker	时间选择
$Switch	el-switch	开关
$CheckboxGroup	el-checkbox-group	复选框组
$RadioGroup	el-radio-group	单选框组
$TreeSelect	el-tree-select	树形选择
$Cascader	el-cascader	级联选择
$ColorPicker	el-color-picker	颜色选择

ElementPlus 特有属性

表单布局

{
    $Form: {
        labelWidth: '120px',     // 标签宽度
        labelPosition: 'right',  // 'left' / 'right' / 'top'
        size: 'default',         // 'large' / 'default' / 'small'
        children: { /* */ },
    },
}

表单项透传属性

$Input({
    $label: '姓名',
    $name: 'name',
    // 以下透传给 el-input
    placeholder: '请输入姓名',
    clearable: true,
    maxlength: 50,
    showWordLimit: true,
    prefixIcon: Search,
});

$Select({
    $label: '状态',
    $name: 'status',
    filterable: true,        // 可搜索
    remote: true,            // 远程搜索
    remoteMethod: (query) => fetchOptions(query),
    multiple: true,          // 多选
});

注意事项

事项	说明
el-form 校验	Jiess 将 $rules 转换为 ElementPlus 的 el-form-item rules
el-input 事件	@change/@blur/@focus 自动绑定校验触发
内部使用 $formItemParam	透传额外 el-form-item 属性

实战示例

示例1：完整注册表单 + 校验规则实战

import { $initHook, $Input, $InputNumber, $Select, $DatePicker, $Switch, $RadioGroup } from '@jiess/plus/vue3';

export default {
    name: {
        $Input: {
            $label: '用户名',
            $rules: [
                { required: true, message: '请输入用户名' },
                { minLen: 2, message: '用户名至少2个字符' },
                { maxLen: 20, message: '用户名最多20个字符' },
            ],
            placeholder: '请输入用户名',
            clearable: true,
        },
    },
    age: {
        $InputNumber: {
            $label: '年龄',
            $rules: [
                { required: true, message: '请输入年龄' },
                { integer: true, message: '请输入整数' },
                { min: 0, message: '年龄不能小于0' },
                { max: 150, message: '年龄不能大于150' },
            ],
            min: 0,
            max: 150,
        },
    },
    email: {
        $Input: {
            $label: '邮箱',
            $rules: [
                { required: true, message: '请输入邮箱' },
                { email: true, message: '请输入正确的邮箱格式' },
            ],
            placeholder: '请输入邮箱',
        },
    },
    phone: {
        $Input: {
            $label: '手机号',
            $rules: [
                { phone: true, message: '请输入正确的手机号' },
            ],
            placeholder: '请输入手机号',
        },
    },
    idCard: {
        $Input: {
            $label: '身份证号',
            $rules: [
                { card: true, message: '请输入正确的身份证号' },
            ],
            placeholder: '请输入身份证号',
        },
    },
    gender: {
        $RadioGroup: {
            $label: '性别',
            $rules: [{ required: true, message: '请选择性别' }],
            options: [
                { label: '男', value: 'male' },
                { label: '女', value: 'female' },
            ],
        },
    },
    birthday: {
        $DatePicker: {
            $label: '生日',
            type: 'date',
            placeholder: '请选择生日',
        },
    },
    status: {
        $Select: {
            $label: '状态',
            options: [
                { label: '启用', value: 1 },
                { label: '禁用', value: 0 },
            ],
        },
    },
    agreement: {
        $Switch: {
            $label: '同意协议',
            $rules: [
                { required: true, message: '请同意用户协议' },
            ],
        },
    },
};

示例2：动态表单项（增删行）

// 在 Jiess 配置中使用 $Form 包装，配合 data 中的 formData 实现动态行
{
    $Form: {
        labelWidth: '100px',
        children: {
            // 使用 map 遍历 formData 生成动态表单项
            ...Object.fromEntries(
                formData.items.map((item, idx) => [
                    `item_${idx}`,
                    {
                        $Input: {
                            $label: `项目 ${idx + 1}`,
                            $name: `items[${idx}].value`,
                            placeholder: '请输入内容',
                            clearable: true,
                        },
                    },
                ])
            ),
            $Button: {
                children: '添加项目',
                type: 'primary',
                onClick: () => {
                    // 添加新项需要更新响应式数据
                    // formData.items.push({ value: '' })
                },
            },
        },
    },
}

示例3：表单联动（省市区三级联动）

export default {
    province: {
        $Select: {
            $label: '省份',
            $rules: [{ required: true, message: '请选择省份' }],
            options: provinceOptions,
            filterable: true,
            // 选择省份后，触发联动
            onChange: (val) => {
                cityOptions.value = getCityByProvince(val);
                districtOptions.value = [];
                // 清空已选的城市和区县
                formRef.value.setFieldValue('city', null);
                formRef.value.setFieldValue('district', null);
            },
        },
    },
    city: {
        $Select: {
            $label: '城市',
            $rules: [{ required: true, message: '请选择城市' }],
            options: cityOptions,
            filterable: true,
            onChange: (val) => {
                districtOptions.value = getDistrictByCity(val);
                formRef.value.setFieldValue('district', null);
            },
        },
    },
    district: {
        $Select: {
            $label: '区县',
            options: districtOptions,
            filterable: true,
        },
    },
};

下一步

• 快捷表单-基础篇 — 表单核心 API + 14 条校验规则