表单脚本 API

概念说明

本文档是表单概念的具体配置说明，也是表单字段属性中「字段脚本」的 API 参考。建议先阅读表单概念，了解整体架构。

本文档详细说明表单脚本中支持的所有 API，包括其功能、参数和使用示例。

脚本结构

表单脚本支持以下事件函数：

// 示例脚本
function onChange(api, value) {
    // 字段值变化时触发
    // api 包含所有可用的 API 方法
}

function onLoad(api, formData) {
    // 表单加载时触发
    // api 包含所有可用的 API 方法
}

function onFocus(api, value) {
    // 字段获得焦点时触发
    // api 包含所有可用的 API 方法
}

function onBlur(api, value) {
    // 字段失去焦点时触发
    // api 包含所有可用的 API 方法
}

支持的 API

1. getValue(fieldCode)

功能：获取指定字段的值

参数：

fieldCode：字段编码

返回值：字段的值

示例：

function onChange(api, value) {
    const otherValue = api.getValue('otherField');
    console.log('Other field value:', otherValue);
}

2. setValue(fieldCode, value)

功能：设置指定字段的值

参数：

fieldCode：字段编码
value：要设置的值

示例：

function onChange(api, value) {
    if (value === 'yes') {
        api.setValue('otherField', 'enabled');
    } else {
        api.setValue('otherField', 'disabled');
    }
}

3. setValues(values)

功能：同时设置多个字段的值

参数：

values：包含字段编码和对应值的对象

示例：

function onLoad(api, formData) {
    api.setValues({
        'field1': 'default1',
        'field2': 'default2',
        'field3': 'default3'
    });
}

4. setVisible(fieldCode, visible)

功能：设置字段的可见性（可以用下文的 show 和 hide 函数更方便快捷）

参数：

fieldCode：字段编码
visible：是否可见（true/false）

示例：

function onChange(api, value) {
    if (value === 'show') {
        api.setVisible('targetField', true);
    } else {
        api.setVisible('targetField', false);
    }
}

5. setReadOnly(fieldCode, readOnly)

功能：设置字段是否只读

参数：

fieldCode：字段编码
readOnly：是否只读（true/false）

示例：

function onChange(api, value) {
    if (value === 'locked') {
        api.setReadOnly('targetField', true);
    } else {
        api.setReadOnly('targetField', false);
    }
}

6. setRequired(fieldCode, required)

功能：设置字段是否必填

参数：

fieldCode：字段编码
required：是否必填（true/false）

示例：

function onChange(api, value) {
    if (value === 'yes') {
        api.setRequired('detailsField', true);
    } else {
        api.setRequired('detailsField', false);
    }
}

7. setPlaceholder(fieldCode, placeholder)

功能：设置字段的占位符

参数：

fieldCode：字段编码
placeholder：占位符文本

示例：

function onLoad(api, formData) {
    api.setPlaceholder('nameField', '请输入姓名');
    api.setPlaceholder('emailField', '请输入邮箱地址');
}

8. addValidation(fieldCode, rule)

功能：添加验证规则

参数：

fieldCode：字段编码
rule：验证规则对象

示例：

function onLoad(api, formData) {
    api.addValidation('emailField', {
        type: 'email',
        message: '请输入有效的邮箱地址'
    });
}

9. clearValidations(fieldCode)

功能：清除字段的所有验证规则

参数：

fieldCode：字段编码

示例：

function onChange(api, value) {
    if (value === 'noValidation') {
        api.clearValidations('targetField');
    }
}

10. setPattern(fieldCode, pattern, message)

功能：设置字段的正则验证模式

参数：

fieldCode：字段编码
pattern：正则表达式或字符串
message：验证失败时的提示信息（可选）

示例：

function onLoad(api, formData) {
    api.setPattern('phoneField', /^1[3-9]\d{9}$/, '请输入有效的手机号码');
}

11. setValidator(fieldCode, validator)

功能：设置字段的自定义验证器

参数：

fieldCode：字段编码
validator：验证函数，返回错误信息或 null

示例：

function onLoad(api, formData) {
    api.setValidator('passwordField', (value) => {
        if (value.length < 6) {
            return '密码长度不能少于6位';
        }
        return null;
    });
}

12. validateField(fieldCode)

功能：验证指定字段（动态添加验证函数后，会自动触发验证，动态添加场景不需要调用该 API）

参数：

fieldCode：字段编码

示例：

async function onChange(api, value) {
    try {
        await api.validateField('emailField');
        console.log('验证通过');
    } catch (error) {
        console.log('验证失败:', error);
    }
}

13. getFormData()

功能：获取所有表单数据

返回值：包含所有字段值的对象

示例：

function onLoad(api, formData) {
    const allData = api.getFormData();
    console.log('所有表单数据:', allData);
}

14. getFormState()

功能：获取表单状态

返回值：表单状态（'create' | 'edit' | 'detail' | 'batchEdit'）

示例：

function onLoad(api, formData) {
    const state = api.getFormState();
    if (state === 'create') {
        console.log('当前是创建模式');
    } else if (state === 'edit') {
        console.log('当前是编辑模式');
    } else {
        console.log('当前是详情模式');
    }
}

15. show(fieldCode)

功能：显示指定字段（快捷方法，等同于 setVisible(fieldCode, true)）

参数：

fieldCode：字段编码

示例：

function onChange(api, value) {
    if (value === 'show') {
        api.show('targetField');
    }
}

16. hide(fieldCode)

功能：隐藏指定字段（快捷方法，等同于 setVisible(fieldCode, false)）

参数：

fieldCode：字段编码

示例：

function onChange(api, value) {
    if (value === 'hide') {
        api.hide('targetField');
    }
}

完整示例

示例 1：根据选择值控制字段显示

function onChange(api, value) {
    if (value === 'option1') {
        api.show('field1');
        api.hide('field2');
    } else if (value === 'option2') {
        api.hide('field1');
        api.show('field2');
    } else {
        api.hide('field1');
        api.hide('field2');
    }
}

function onLoad(api, formData) {
    // 初始化时根据默认值设置字段可见性
    if (formData.option === 'option1') {
        api.show('field1');
        api.hide('field2');
    } else if (formData.option === 'option2') {
        api.hide('field1');
        api.show('field2');
    }
}

示例 2：动态设置字段值和验证

function onChange(api, value) {
    // 根据输入值设置其他字段
    if (value) {
        api.setValue('description', `This is a description for ${value}`);
        api.setRequired('description', true);
    } else {
        api.setValue('description', '');
        api.setRequired('description', false);
    }
}

function onLoad(api, formData) {
    // 设置初始验证规则
    api.setPattern('email', /^[^\s@]+@[^\s@]+\.[^\s@]+$/, '请输入有效的邮箱地址');
    api.setValidator('password', (value) => {
        if (!value) return '密码不能为空';
        if (value.length < 6) return '密码长度不能少于6位';
        return null;
    });
}

示例 3：复杂的表单逻辑

function onChange(api, value) {
    // 复杂的条件逻辑
    const formData = api.getFormData();
    const formState = api.getFormState();
    
    if (formState === 'create') {
        // 创建模式下的逻辑
        if (value === 'special') {
            api.setValues({
                'field1': 'default1',
                'field2': 'default2'
            });
            api.show('specialField');
        } else {
            api.hide('specialField');
        }
    } else if (formState === 'edit') {
        // 编辑模式下的逻辑
        if (value !== formData.originalValue) {
            api.setReadOnly('originalValueField', true);
        }
    }
}

function onLoad(api, formData) {
    // 加载时的初始化逻辑
    if (formData.status === 'active') {
        api.setReadOnly('status', true);
    }
    
    // 显示欢迎信息
    console.log('Form loaded with data:', formData);
}

注意事项

脚本执行环境：脚本在沙箱环境中执行，只能访问上述 API，不能直接访问全局变量或 DOM。
性能考虑：避免在 onChange 事件中执行复杂的计算或网络请求，以免影响表单响应速度。
错误处理：脚本执行错误会在控制台显示，不会影响表单的正常运行。
缓存机制：脚本会被缓存，修改脚本后需要刷新页面才能生效。
API 可用性：所有 API 在所有事件函数中都可用，但某些 API 在特定事件中可能没有实际效果。

故障排除

如果脚本没有生效，请检查以下几点：

确保脚本语法正确，没有语法错误。
确保字段编码正确，与表单中的字段编码一致。
确保 EnableFieldScript 选项已启用。
检查浏览器控制台是否有脚本执行错误。
尝试刷新页面，确保脚本缓存已更新。

脚本结构​

支持的 API​

1. getValue(fieldCode)​

2. setValue(fieldCode, value)​

3. setValues(values)​

4. setVisible(fieldCode, visible)​

5. setReadOnly(fieldCode, readOnly)​

6. setRequired(fieldCode, required)​

7. setPlaceholder(fieldCode, placeholder)​

8. addValidation(fieldCode, rule)​

9. clearValidations(fieldCode)​

10. setPattern(fieldCode, pattern, message)​

11. setValidator(fieldCode, validator)​

12. validateField(fieldCode)​

13. getFormData()​

14. getFormState()​

15. show(fieldCode)​

16. hide(fieldCode)​

完整示例​

示例 1：根据选择值控制字段显示​

示例 2：动态设置字段值和验证​

示例 3：复杂的表单逻辑​

注意事项​

故障排除​