Component Value Change Callback

The update callback and link field allow you to dynamically modify other components' properties or values when a form component's value changes. This feature is very useful when 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, please read the Computing Component Rules documentation in detail.

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 update callback function to dynamically update component properties: when the input box 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 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 link property: when input1 value changes, automatically trigger input2's update callback function, dynamically update input2's title to current timestamp, achieving cross-field linkage update mechanism.

Update Display State

Control component display state through update callback: when the input box 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

We can dynamically adjust the maximum character length of the comment input box based on the rating component's value. For example, when the rating exceeds 3 stars, the comment input box'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, we can make one field's change trigger other fields' update callbacks. For example, in a shopping cart form, we may need to 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, you may need to 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, you can 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 can provide strong support. Combined with the link configuration item, you can more conveniently implement linkage between components, making forms more intelligent and dynamic. Through the above examples and explanations, I believe you can better understand and apply the update callback functionality.