Component Value Change Callback

The update callback and link field let you dynamically modify other components' properties or values when a form component's value changes. This feature is useful for creating complex, dynamic forms, for example: dynamically adjusting form display state, required rules, disabled state, etc. based on user input.

It is recommended to use the more powerful computed rules feature. For specific usage, read the Computing Component Rules documentation.

Data Structure

type UpdateArg = {
    //Trigger method: may be triggered by initialization, value change, or field linkage
    origin: 'change' | 'init' | 'link'
    //Associated trigger field name, effective when origin is 'link'
    linkField: string | undefined;
}
type Update = (val:any, rule:FormRule, api:Api, arg: UpdateArg)=>boolean|undefined;

origin Options

• init: Triggered during initialization, usually triggered when the component first loads.
• link: Triggered when other fields' linkage affects the current field.
• change: Triggered when the field's value changes.

Note

The component's update callback will automatically execute once immediately after initialization is complete.

Examples

Update Current Component

Use the update callback function to dynamically update component properties: when the input value changes, automatically synchronize the component's title to the current input value, achieving real-time linkage effects of form component properties.

Update Other Components

Achieve bidirectional linkage through the update callback and API methods: when input1 or input2 values change, mutually update each other's title property, achieving real-time dynamic interaction between two form fields.

Trigger When Associated Field Changes

Establish field association through the link property: when input1 value changes, automatically trigger input2's update callback function, dynamically update input2's title to the current timestamp, achieving cross-field linkage update mechanism.

Update Display State

Control component display state through the update callback: when the input value is empty, automatically hide the component, achieving dynamic control of component visibility based on input content.

Control Component Display State

Suppose we want to dynamically show or hide another component based on the input box content. When input1 value is empty, hide input2.

const rules = [{
  type: 'input',
  field: 'input1',
  title: 'Input Box 1',
  value: '',
  update(val, rule, api) {
    const targetRule = api.getRule('input2');
    targetRule.hidden = !val;
  }
},
{
  type: 'input',
  field: 'input2',
  title: 'Input Box 2',
  hidden: true
}]

Modify Specified Component Property

Dynamically adjust the maximum character length of the comment input based on the rating component's value. For example, when the rating exceeds 3 stars, the comment input's maximum character length increases from 200 to 500.

const rules = [{
    type: 'rate',
    field: 'rating',
    title: 'Rating',
    value: 0,
    update(val, rule, api) {
        const commentRule = api.getRule('comment');
        commentRule.props.maxlength = val > 3 ? 500 : 200;
    }
},
{
    type: 'input',
    field: 'comment',
    title: 'Comment',
    props: {
        maxlength: 200
    }
}]

Combined Calculation of Field Values

Through the link configuration item, make one field's change trigger other fields' update callbacks. For example, in a shopping cart form, dynamically calculate the total price based on product quantity and unit price.

const rules = [{
    type: 'inputNumber',
    field: 'quantity',
    title: 'Quantity',
    value: 1,
    link: ['price'],
    update(val, rule, api) {
        const price = api.getValue('price');
        const total = val * price;
        api.setValue('total', total);
    }
},
{
    type: 'inputNumber',
    field: 'price',
    title: 'Unit Price',
    value: 100,
},
{
    type: 'input',
    field: 'total',
    title: 'Total Price',
    props: {
        disabled: true
    }
}]

Update Checkbox Options

In some scenarios, dynamically update checkbox or radio button option lists based on user selection.

const rules = [{
    type: 'select',
    field: 'category',
    title: 'Category',
    value: '',
    options: [
        { value: 'fruits', label: 'Fruits' },
        { value: 'vegetables', label: 'Vegetables' }
    ],
    link: ['product'],
    update(val, rule, api) {
        const productRule = api.getRule('product');
        if (val === 'fruits') {
            productRule.options = [
                { value: 'apple', label: 'Apple' },
                { value: 'banana', label: 'Banana' }
            ];
        } else if (val === 'vegetables') {
            productRule.options = [
                { value: 'carrot', label: 'Carrot' },
                { value: 'spinach', label: 'Spinach' }
            ];
        }
    }
},
{
    type: 'select',
    field: 'product',
    title: 'Product',
    options: []
}]

Through the update callback, implement complex interaction logic between components in forms. Whether it's simple dynamic display and hiding, or complex value linkage and calculation, the update callback provides strong support. Combined with the link configuration item, more conveniently implement linkage between components, making forms more intelligent and dynamic. Through the above examples and explanations, you can better understand and apply the update callback functionality.