组件介绍

StepForm 是一个基于 Vue3 的分步表单组件，支持自定义表单配置、验证规则和样式，适用于分步注册、分步信息收集等场景。

效果展示

上图展示了组件的基本外观，包含：

• 标题和副标题区域
• 表单输入区域
• 步骤切换按钮
• 错误提示功能
• Logo展示区域（可选）

安装依赖

组件依赖于 Element Plus，请确保项目中已安装。

npm

npm install element-plus

yarn

yarn add element-plus

pnpm

pnpm add element-plus

基础用法

在模板中使用 StepForm 组件，通过 props 传入必要的配置：

• width: 设置表单宽度（如："500px"）
• height: 设置表单高度（如："200px"）
• primary-color: 设置主题色（如："#42b883"）
• title: 设置表单标题
• sub-title: 设置表单副标题
• show-logo: 是否显示 logo
• logo-src: 设置 logo 图片路径
• submit-text: 设置提交按钮文字
• form-config: 设置表单配置项

Props 说明

属性名	类型	默认值	说明
width	String	''	表单宽度
height	String	''	表单高度
primaryColor	String	''	主题色
title	String	''	表单标题
subTitle	String	''	表单副标题
showLogo	Boolean	false	是否显示 logo
logoSrc	String	''	logo 图片路径
submitText	String	''	提交按钮文字
formConfig	Array	[]	表单配置项

formConfig 配置说明

formConfig 是一个数组，每个元素包含以下属性：

• label: 字段标签
• modelKey: 字段名（必须唯一）
• rules: 验证规则数组

验证规则支持以下类型：

1. 必填验证：{ required: true, trigger: 'change', message: '错误提示' }
2. 长度验证：{ min: 2, trigger: 'change', message: '错误提示' }
3. 自定义验证器：使用 validator 函数

事件说明

事件名	参数	说明
submit	formData	表单提交时触发，返回表单数据
step-change	{ currentStep, data }	步骤切换时触发，返回当前步骤和数据
validate	{ field, valid }	表单验证时触发，返回字段名和验证结果

事件处理

组件提供了三个主要事件：

1. submit: 表单提交时触发，返回完整的表单数据
2. step-change: 步骤切换时触发，返回当前步骤信息
3. validate: 表单验证时触发，返回验证结果

样式定制

组件支持通过 primaryColor 属性设置主题色，会自动生成对应的悬浮、点击等状态颜色。

注意事项

1. formConfig 中的 modelKey 必须唯一
2. 每个表单项都支持独立的验证规则
3. 表单验证通过才能进行下一步或提交
4. 组件会自动处理密码字段的显示/隐藏
5. 所有的 props 都需要在父组件中显式传入，没有默认值

使用建议

1.建议将表单配置抽离为单独的配置文件 2. 验证规则建议根据业务需求适当调整 3. 可以通过主题色配置来匹配项目风格 4. 事件处理函数建议做好错误处理

使用示例

基础示例

loading

配置文件示例

formConfig.js

// formConfig.js
export const registerConfig = [
  {
    label: '用户名',
    modelKey: 'username',
    rules: [
      { required: true, message: '请输入用户名' },
      { min: 3, message: '用户名至少3个字符' }
    ]
  },
  {
    label: '邮箱',
    modelKey: 'email',
    rules: [{
      validator: (rule, value, callback) => {
        if (!value) {
          callback('请输入邮箱')
        } else if (!value.match(/^[a-zA-Z0-9_-]+@[a-zA-Z0-9_-]+(\.[a-zA-Z0-9_-]+)+$/)) {
          callback('请输入正确的邮箱格式')
        } else {
          callback()
        }
      },
      trigger: 'change'
    }]
  }
]

// 使用配置
import { registerConfig } from './formConfig'

const formConfig = registerConfig

主题定制示例

vue

<template>
  <StepForm
    width="600px"
    height="250px"
    primary-color="#ff6b6b"
    title="会员注册"
    sub-title="欢迎加入我们"
    :show-logo="false"
    submit-text="完成注册"
    :form-config="formConfig"
  />
</template>