SpFormPlus 组件使用手册

概述

sp-form-plus 是一个基于 Element UI 的增强版表单组件，提供了更灵活的配置方式和更丰富的功能。支持多种表单类型（普通表单、搜索表单）和多种字段组件，支持自定义组件渲染，具有良好的扩展性。

基本用法

基础示例

API 文档

Props

Form Item 配置

每个表单项支持以下配置：

事件

事件名	说明	回调参数
submit	表单提交时触发（验证通过后）	(formData)
input	表单数据变化时触发（用于 v-model）	(formData)
reset	表单重置时触发	–

注意： field-change 事件在当前版本中已被注释，使用 v-model 或 componentProps.onChange 来处理字段变化。

方法

方法名	说明	参数	返回值
validate	验证表单	–	Promise
resetField	重置指定字段	(field)	–
clearValidate	清除验证	(props)	–

支持的字段类型

SpFormPlus 支持以下字段类型：

– 输入框

– 选择框

– 单选框

– 复选框

– 开关

– 日期选择器

– 日期时间选择器

– 图片选择器

– 按钮

– 分组标题

-自定义组件（函数形式）

表单验证

基本验证

{
fieldName: ’email’,
label: ‘邮箱’,
component: ‘input’,
rules: [
{ required: true, message: ‘请输入邮箱’, trigger: ‘blur’ },
{ type: ’email’, message: ‘请输入正确的邮箱格式’, trigger: ‘blur’ }
]
}

自定义验证

{
fieldName: ‘phone’,
label: ‘手机号’,
component: ‘input’,
rules: [
    {
      validator: (rule, value, callback) => {
        if (!value) {
          callback(new Error(‘请输入手机号’))
        } else if (!/^1[3-9]\d{9}$/.test(value)) {
          callback(new Error(‘请输入正确的手机号’))
        } else {
          callback()
        }
      },
      trigger: ‘blur’
    }
]
}

条件显示

{
fieldName: ‘reason’,
label: ‘原因’,
component: ‘input’,
isShow: (value) => {
// 只有当状态为禁用时才显示
return this.formData.status === 0
}
}

高级用法

动态表单项

使用计算属性根据表单数据动态生成表单项：

computed: {
formItems() {
    const items = [
      {
        fieldName: ‘type’,
        label: ‘类型’,
        component: ‘select’,
        value: ”,
        componentProps: {
          options: [
            { label: ‘个人’, value: ‘personal’ },
            { label: ‘企业’, value: ‘company’ }
          ],
          onChange: (value, formData) => {
            // 清空关联字段
            if (value !== ‘company’) {
              this.$set(formData, ‘companyName’, ”)
            }
          }
        }
      }
    ]

    // 根据类型动态添加字段
    if (this.formData.type === ‘company’) {
      items.push({
        fieldName: ‘companyName’,
        label: ‘公司名称’,
        component: ‘input’,
        value: ”,
        rules: [
          { required: true, message: ‘请输入公司名称’, trigger: ‘blur’ }
        ]
      })
    }

    return items
}
}

表单联动

使用 componentProps.onChange 实现字段间的联动：

{
fieldName: ‘province’,
label: ‘省份’,
component: ‘select’,
value: ”,
componentProps: {
    options: this.provinces,
    onChange: (value, formData) => {
      // 清空城市选择
      this.$set(formData, ‘city’, ”)
      this.$set(formData, ‘district’, ”)

      // 加载对应城市数据
      this.loadCities(value).then(cities => {
        // 更新城市字段的选项
        this.updateCityOptions(cities)
      })
    }
}
},
{
fieldName: ‘city’,
label: ‘城市’,
component: ‘select’,
value: ”,
componentProps: {
    options: this.cities,
    onChange: (value, formData) => {
      // 清空区县选择
      this.$set(formData, ‘district’, ”)
      // 加载区县数据
      this.loadDistricts(value)
    }
}
}

样式定制

自定义样式类

通过 formItemClass 为特定字段添加自定义样式：

{
fieldName: ‘special’,
label: ‘特殊字段’,
component: ‘input’,
value: ”,
formItemClass: ‘custom-form-item highlight-field’,
tip: ‘这是一个重要字段’
}

.custom-form-item {
&.highlight-field {
    .el-form-item__label {
      color: #f56c6c;
      font-weight: bold;

      &::before {
        content: ‘★ ‘;
        color: #ff4949;
      }
    }

    .el-input__inner {
      border-color: #f56c6c;
    }
}
}

// 搜索表单特殊样式
.sp-form-plus–search-form {
.custom-form-item {
    background-color: rgba(245, 108, 108, 0.1);
    padding: 8px;
    border-radius: 4px;
}
}

// 分组标题样式
.form-field-group {
position: relative;
padding: 8px;
color: #333;
font-size: 15px;
border-bottom: 1px solid #f1f2f5;
margin-bottom: 18px;

&::before {
    position: absolute;
    top: 11px;
    bottom: 11px;
    left: 0;
    width: 2px;
    background-color: var(–primary);
    content: ”;
}
}

// 内联表单网格布局
.sp-form-plus–inline {
.sp-form-plus__wapper {
    display: grid;
    grid-template-columns: repeat(auto-fit, minmax(320px, 1fr));
    gap: 8px;
}
}

useForm Composable

除了直接使用 SpFormPlus 组件外，还提供了 useForm Composable API，用于更灵活的表单管理。

基本用法

import { useForm } from ‘@/composables/useForm’

export default {
setup() {
    const { Form, FormApi } = useForm({
      formProps: {
        labelWidth: ‘120px’
      },
      formItems: [
        {
          prop: ‘name’,
          label: ‘姓名’,
          type: ‘input’,
          placeholder: ‘请输入姓名’,
          rules: [
            { required: true, message: ‘请输入姓名’, trigger: ‘blur’ }
          ]
        },
        {
          prop: ’email’,
          label: ‘邮箱’,
          type: ‘input’,
          placeholder: ‘请输入邮箱’
        }
      ],
      rules: {
        email: [
          { type: ’email’, message: ‘请输入正确的邮箱格式’, trigger: ‘blur’ }
        ]
      },
      initialValues: {
        name: ”,
        email: ”
      }
    })

    return {
      Form,
      FormApi
    }
}
}

支持的字段类型

useForm 支持以下字段类型：

– 输入框

– 选择框

– 单选框

– 复选框

– 日期选择器

– 时间选择器

– 开关

– 滑块

– 自定义组件

API 方法

FormApi 提供以下方法：

– 验证表单

– 重置表单

– 清除验证

– 设置字段值

– 获取字段值

– 设置字段验证状态

最佳实践

：用于数据筛选，带有查询/重置按钮，具有特殊的背景样式

：用于数据录入，带有保存按钮

v-model 进行双向绑定

value 属性作为默认值

componentProps.onChange 处理字段变化

ref 调用 validate() 方法进行手动验证

labelWidth

inline 属性创建自适应的网格布局

formItemClass 自定义单个字段样式

isShow 函数控制字段显示/隐藏

onChange 回调实现字段联动

h 函数创建 VNode

formData 参数访问整个表单数据

isShow 而非动态创建

group 组件进行分组

componentProps.onChange 中执行重度计算

常见问题

Q: 如何获取表单数据？

A: 有以下几种方式：

v-model 双向绑定：

@submit 事件：@submit=”handleSubmit”

this.$refs.formRef.validate()

Q: 如何重置表单？

@reset 事件

this.$refs.formRef.resetField() 方法

监听整体数据变化

监听单个字段变化

是 Vue 组件，适合在模板中直接使用

是 Composable API，提供更灵活的编程式表单管理

支持更多的字段类型和自定义渲染

Q: 如何在 useForm 中使用自定义组件？

A: 设置字段类型为 custom 并提供 render 函数：

{
prop: ‘customField’,
label: ‘自定义字段’,
type: ‘custom’,
render: (h, formData) => {
return h(‘div’, ‘自定义内容’)
}
}

Q: datepicker 和 datetimepicker 有什么区别？

只选择日期，返回格式如 ‘2023-12-01’

可选择日期时间范围，支持 datetimerange 类型

属性	类型	默认值	说明
colon	Boolean	false	是否在 label 后添加冒号
formType	String	‘searchForm’	表单类型，可选值：‘searchForm’、’normalForm’
formItems	Array	[]	表单项配置数组
formApi	Object	{}	表单 API 配置（预留字段，暂未使用）
inline	Boolean	false	是否内联显示（使用网格布局）
labelWidth	String	‘160px’	标签宽度
layout	String	‘horizontal’	布局方式（预留字段，暂未使用）
showDefaultActions	Boolean	true	是否显示默认操作按钮
value / v-model	Object	{}	表单数据（支持 v-model 双向绑定）

商派资讯新闻