Skip to content

Form API ​

FormCreate provides a comprehensive API for full control over forms—generation, dynamic updates, validation, and data processing. These APIs simplify complex form requirements.

Note

For detailed usage, see the API Documentation

Get API ​

FormCreate provides multiple ways to access the API object for different scenarios.

Get in Events ​

ts
const api = $inject.api;

Get in Custom Validation Functions ​

ts
const api = this.api;

Get in Hook Events ​

ts
const api = data.api;

Custom Component Injection ​

Custom components automatically receive key parameters for working with forms.

The formCreateInject object contains: - formCreateInject.api Form API object for form operations - formCreateInject.options Global configuration for form components - formCreateInject.rule Generation rule object defining all component configurations - formCreateInject.field Field name bound to form data

Example: Using formCreateInject in custom components:

js
const customComponent = defineComponent({
  name: 'custom-component',
  props: {
    formCreateInject: Object, // Automatically injected form parameters
  },
  mounted() {
    console.log(this.formCreateInject.api);  // Access API within the component
  }
});

API Properties ​

The API provides key properties for controlling and operating forms.

Property NameTypeDescription
configObjectGlobal configuration object for the form, containing all form configuration information
indexnumber|undefinedGet the index of the current form in the sub-form (group) (if the form is a nested sub-form)
siblingsApi[]|undefinedGet all form APIs in the sub-form (group) where the current form is located (if the form is a nested sub-form)
ruleRule[]Generation rule list for the current form, defining the form's structure and components
formObjectData object for the current form, containing values for all fields
parentApi |undefinedParent form's Api object (if the form is a nested sub-form)
topApiTop-level form's Api object (for nested form scenarios)
childrenApi[]Array of sub-form Api objects, allowing operations on nested sub-forms

API Methods ​

The API provides methods for dynamically controlling and operating forms.

Method NameTypeDescription
print Pro Version(config: Object)=>voidPrint the current form, see Detailed Documentation.
exportPdf Pro Version(config: Object)=>voidExport the current form as PDF, see Detailed Documentation.
message Pro Version(config: {message:string})=>voidShow popup message
formEl()=> undefined|ComponentInternalInstanceGet the Vue component instance of the entire form for directly operating component internal methods or properties
wrapEl(id: string)=> undefined|ComponentInternalInstanceGet the Vue component instance of the specified form item for operating specific form items
formData(field?: string[])=> ObjectGet the data object of the current form, returning values for all fields
getValue(field: string)=> anyGet the value of the specified field
coverValue(formData: Object)=> voidOverwrite the current values of the form with new data
setValue(formData: Object)=> void|(field: string, value: any)=> voidSet form values, can set for the entire form or for specific fields
fields()=> string[]Get names of all fields in the form
hidden(hidden: Boolean, field?: string|string[])=> voidHide or show specified form components (no DOM nodes)
display(display: Boolean, field?: string|string[])=> voidControl display of form components (with DOM nodes)
disabled(disabled: Boolean, field?: string|string[])=> voidDisable or enable specified form components
onSubmit(fn: (formData: Object, api: Api) => void)=> voidListen to form submit events, execute callback when form is submitted
updateOptions(options: Options)=> voidUpdate global configuration of the form
submit(success?: (formData: Object, api: Api) => void, fail?: (api: Api) => void)=> Promise<any>Manually submit the form, trigger submission flow and execute success or failure callbacks
getRule(id: string)=> Rule|undefinedGet the generation rule of the specified field via name or field
getRenderRule(id: string)=> Rule|undefinedGet the final rendering rule of the component via name or field, including content after dynamic changes
validate(callback?: (state: any) => void)=> Promise<any>Validate the form, return a Promise with validation results
validateField(field: string, callback?: (state: any) => void)=> Promise<any>Validate the specified field, return a Promise with validation results
clearValidateState(fields?: string|string[], clearSub?: Boolean)=> voidClear validation state of specified fields or the entire form
resetFields(field?: string| string[])=> voidReset the form, resetting values of all fields to initial state
nextTick(fn: (api: Api) => void)=> voidExecute callback after form rendering, ensuring all components are loaded
fetch(option: FetchOption)=> Promise<any>Send remote request, supporting custom request logic and processing
setData(id: string, value?: any)=> voidSet external data, supporting use of external data sources in forms
getData(id: string, defaultValue?: any)=> anyGet external data, return previously set data object
refreshData(id: string)=> voidRefresh components related to external data, ensuring UI updates synchronously after data changes

API.bus ​

The API includes a built-in event system for managing and triggering custom events. Use it for component communication, state management, and dynamic behavior.

Method NameTypeDescription
$emit(event: string, ...args: any[])=> voidManually trigger event
$on$on(event: string|string[], callback: Function)=> voidListen to event
$once$once(event: string|string[], callback: Function)=> voidListen to one-time event
$off$off(event: string|string[], callback: Function)=> voidRemove event listener

Examples ​

Send Request ​

Send remote requests manually using the fetch method:

js
api.fetch({
    action: '/api/getdata',
    query: {
        name: api.getValue('name')
    }
}).then(res=>{
    //todo
});

Disable Component ​

Disable specified components using the disabled method:

js
// Disable components via component field
api.disabled(true, ['field1', 'field2', 'field3']);
// Disable components via component name
api.disabled(true, ['name1', 'name2', 'name3']);

Hide Component ​

Hide specified components using the hidden method:

js
// Hide components via component field
api.hidden(true, ['field1', 'field2', 'field3']);
// Hide components via component name
api.hidden(true, ['name1', 'name2', 'name3']);

Call Component Method ​

Call component instance methods using the el method:

js
// Get selected rows of elTable component
api.el('elTable').getSelectionRows();

Modify Form Values ​

Modify form values using the setValue method:

js
api.setValue({
    field1: 'value1',
    field2: 'value2',
    field3: 'value3',
});

Modify Component Properties ​

Get component rules using the getRule method and modify them. View component configuration hierarchy and names in the designer's JSON panel

js
// Get component rule via component field
const rule1 = api.getRule('field');
// Get component rule via component name
const rule2 = api.getRule('name');

axios.get('/api/getForm').then(data => {
    // Modify data in component configuration items
    rule1.props.data = data;
})
// Modify whether component is required
rule2.$required = true;
// Modify component text
rule2.children[0] = 'New Text';

Manually Validate Specified Field ​

Manually trigger validation for specified fields using api.validateField:

js
api.validateField('field').then(() => {
    // Validation passed
});

Manually Trigger Form Validation ​

Manually trigger overall form validation using api.validate:

js
api.validate().then(() => {
    // Validation passed
});

Manually Trigger Form Submission ​

Manually trigger form submission by calling api.submit() without requiring the user to click the submit button:

js
api.submit();

Set/Get External Data ​

js
api.setData('Token', 'xxx');
const token = api.getData('Token');