Effect 与处理器

DynamicForm 使用 form-chain-effect-engine 执行依赖链，但 effect 返回值如何作用到表单由 DynamicForm 的 handler 系统负责。

初始化约束

依赖默认或自定义 effect result handler 的表单，应在渲染前调用 useInitHandlers。

const { isInitialized, error } = useInitHandlers({
  handlers: customHandlers,
  options: { override: false },
  debug: false
});

if (!isInitialized) return null;
if (error) return <div>{error.message}</div>;

return <DynamicForm form={form} formConfig={formConfig} />;

DynamicFormProvider 可以在检测到 handler 可能未初始化时发出 warning。该行为由 enableInitializationCheck 和 checkDelay 控制。

useInitHandlers({ debug: true }) 会输出处理器初始化诊断和未匹配 effect result key。默认 debug: false，正常渲染、reducer 更新、字段提交和 effect 执行不会向控制台输出过程日志。无效配置、缺失组件和初始化契约问题仍会使用 warn 或 error 报告。

联动配置

字段和分组都可以声明 dependents 和 effect。

{
  id: 'employeeCount',
  component: 'NumberInput',
  dependents: ['companySize'],
  effect: (value, values) => {
    return {
      value,
      componentProps: { min: 0 },
      visible: value !== undefined
    };
  }
}

配置处理阶段会生成 effectMap，并传给 form-chain-effect-engine。

默认返回 key

默认 handler 定义在 src/config/defaultConfig.ts。

返回 key	作用
value	调用 form.setFieldsValue 更新当前字段值。
visible	更新当前字段 meta.behavior.visible。
disabled	更新当前字段 meta.behavior.disabled。
readonly	更新当前字段 meta.behavior.readonly。
groupsVisible	按 group id 更新分组可见性。
formItemProps	更新当前字段 meta.formItemProps。
componentProps	更新当前字段 meta.componentProps。
formProps	合并到全局动态 Form props。
buttonProps	合并到全局动态 Button props。
cardProps	合并到全局动态 Card props。
rowProps	合并到全局动态 Row props。
colProps	合并到全局动态 Col props。
submitAreaProps	合并到动态提交区域 props。

未匹配到 handler 的 key 不会被应用，只会进入 warning 日志。

Meta 边界

行为 meta 属于 Runtime：

{
  behavior: {
    visible: true,
    disabled: false,
    readonly: false
  }
}

渲染专用 meta 属于渲染层：

{
  formItemProps: { help: 'Shown below the field' },
  componentProps: { placeholder: 'Enter value' }
}

旧的 flat key 仍然兼容：

{ visible: false, disabled: true, readonly: true }

新代码应优先写入 meta.behavior。

自定义处理器

自定义 handler 实现 CustomEffectResultHandler。

import type { CustomEffectResultHandler } from '@whynotsnow/dynamic-form';

export const customHandlers: CustomEffectResultHandler[] = [
  {
    name: 'highlight',
    description: 'Apply highlight style to the current field',
    canHandle: (key) => key === 'highlight',
    validate: (value) => typeof value === 'boolean',
    handle: (context, enabled) => {
      context.updateFieldMeta({
        componentProps: {
          style: enabled ? { background: '#fffbe6' } : undefined
        }
      });
    }
  }
];

handler context 提供语义化 API：

• fieldName
• form
• getField
• setFieldValue
• updateFieldMeta
• updateFieldMetaById
• setGroupVisible
• updateDynamicUIConfig

优先使用这些 API，不要在 handler 中直接维护 value、error、touched 或 validating 副本。

值更新原则

reducer 不存储 values、errors、warnings、touched、validating。value handler 直接更新 Ant Design Form。提交时先做 runtime 过滤后的校验，再用 form.getFieldsValue(true) 读取数据。

初始值结果

函数式 initialValue 可以返回 effect result 对象。初始化阶段也会使用同一套 handler 路由，因此初始值也能配置字段 meta 或 UI props。