分步表单

分步表单组件通过将复杂表单拆解为多个步骤，引导用户逐步完成填写。每个步骤都可以包含独立的表单内容，支持数据验证和步骤切换，有助于提高用户填写体验和数据准确性。

基础使用

切换步骤

通过注入的 api.el 方法可以操作分步表单，动态设置其激活状态。例如，切换到步骤2：

function onChange($inject) {
    $inject.api.el('ref_F2vulxvqc841dac').active = 2;
}

将 ref_F2vulxvqc841dac 替换为您的分步表单组件的ID，将 2 替换为目标步骤索引（从0开始）。通过设置 active 属性，您可以实现步骤的精确跳转。

获取子表单API

分步表单内部的表单实例可以通过 subApi 属性获取，方便您进行数据操作或验证：

function getSubApi($inject) {
    // 获取分步表单实例
    const stepFormInstance = $inject.api.el('ref_F2vulxvqc841dac');
    // 获取子表单API
    const subApi = stepFormInstance.subApi;

    // 获取当前表单数据
    const formData = subApi.formData();
    console.log('当前步骤表单数据:', formData);

    // 验证当前步骤
    subApi.validate().then(() => {
        console.log('验证通过');
    }).catch(() => {
        console.log('验证失败');
    });
}

通过 subApi，您可以访问当前活跃步骤的表单API，进行数据读取、字段验证、值设置等操作。

配置项

分步表单提供了丰富的配置选项，您可以通过在设计器中配置属性来自定义分步表单的行为和外观。

属性名	类型	默认值	必需	说明
stepsProps	Object	-	否	步骤条属性配置
modelValue	Object	-	否	双向绑定的表单数据
autoValidate	Boolean	-	否	是否在切换步骤时自动验证
submitBtn	Boolean	true	否	是否显示提交按钮
steps	Array	[]	是	步骤配置数组
options	Object	{ submitBtn: false, resetBtn: false }	否	表单配置选项

事件

分步表单组件提供了丰富的事件，方便您监听表单状态变化并执行相应的处理。

事件名	参数	说明
update:modelValue	value	表单数据更新事件，当任意步骤的表单数据变化时触发
change	value	表单数据变化事件，与update:modelValue类似
itemMounted	api	子表单挂载完成事件，当子表单初始化完成时触发
submit	formData, api	表单提交事件，当用户点击提交按钮时触发
next	{active, api}	下一步切换事件，当切换到下一步时触发
validateFail	api	表单验证失败事件，当自动验证失败时触发

事件使用示例

监听步骤切换：

function handleNext({ active, api }) {
    console.log('当前步骤:', active);
    console.log('表单数据:', api.formData());
    // 在特定步骤执行特定操作
    if (active === 1) {
        // 第二步时的特殊处理
        console.log('进入第二步');
    }
}

监听表单提交：

function handleSubmit(formData, api) {
    console.log('最终提交的数据:', formData);
    // 提交数据到后台
    // submitToBackend(formData);
}

监听表单数据变化：

function handleChange(value) {
    console.log('当前所有步骤的数据:', value);
    // 可以实时保存草稿
    // saveDraft(value);
}

方法

分步表单提供了多种方法，方便您进行程序化控制。

方法名	参数	说明	返回值
init	-	初始化步骤表单	-
onPrev	-	执行上一步操作	-
validate	-	验证当前步骤的表单数据	Promise
onNext	-	执行下一步操作	-
submit	-	提交整个表单	-
addSubApi	api	添加子表单API实例（内部使用）	-
formData	value	处理表单数据变化（内部使用）	-
setValue	value	设置表单值	-

方法使用示例

程序化验证当前步骤：

function validateCurrentStep($inject) {
    const stepForm = $inject.api.el('ref_F2vulxvqc841dac');
    const subApi = stepForm.subApi;
    subApi.validate().then(() => {
        console.log('当前步骤验证通过');
        // 继续下一步或其他操作
    }).catch(errors => {
        console.log('当前步骤验证失败:', errors);
        // 提示用户修复错误
    });
}

程序化切换步骤：

function goToStep($inject, stepIndex) {
    const stepForm = $inject.api.el('ref_F2vulxvqc841dac');
    stepForm.active = stepIndex;
}

程序化提交表单：

function submitForm($inject) {
    const stepForm = $inject.api.el('ref_F2vulxvqc841dac');
    const subApi = stepForm.subApi;
    // 验证所有步骤
    subApi.validate().then(() => {
        const formData = subApi.formData();
        console.log('提交数据:', formData);
        // 提交到后台
    }).catch(() => {
        console.log('验证失败，无法提交');
    });
}

Data

分步表单组件的内部数据属性如下：

数据名	初始值	说明
active	0	当前激活的步骤索引
cacheRule	[]	缓存的分步规则
cacheValue	{}	缓存的表单数据
subApi	{}	子表单API实例
Form	markRaw(formCreateInject.form.$form())	Form组件实例

数据说明：

• active：当前激活的步骤索引，从0开始。可以通过修改此值来实现步骤跳转
• cacheRule：缓存的分步规则数组，包含了所有步骤的表单规则配置
• cacheValue：缓存的表单数据对象，保存了所有步骤的数据，确保步骤切换时数据不丢失
• subApi：子表单API实例，提供了访问和操作当前步骤表单的方法
• Form：Form组件实例，用于渲染表单内容