动态表单迁移指南

本指南用于把旧动态表单页面迁移到增强后的 schema、handler、fetch 体系。

后端优先

显示、必填、远程数据这类规则优先写在 PHP schema 中：

$form->select('visible', '可见状态')
    ->options(Visible::class)
    ->whenEqual(3, function (Control $control): void {
        $control->required('password');
    })
    ->whenEqual(3, function (Control $control): void {
        $control->show('password');
    });

远程数据

使用 fetch() 描述远程选项：

$form->select('user_id', '用户')->fetch('users/options', to: 'options');

序列化结果：

{
  "effect": {
    "fetch": {
      "action": "users/options",
      "to": "options",
      "method": "GET"
    }
  }
}

前端 handler

复杂交互使用稳定 handler key。PHP 输出 key，前端本地注册实现。

$form->select('module', '所属模块')
    ->handler('change', 'permissions.moduleChanged')
    ->injectEvent();

registerCatchFormHandler('permissions.moduleChanged', ({ api, args }) => {
  const [module] = args as [string]
  api?.mergeRule('component', { props: { query: { module } } })
})

页面迁移

• 删除页面里的 @ts-nocheck。
• catch-form 统一传入 CatchFormConfig：api、rules、option、primary。
• 用后端 control 管理显示和必填状态。
• 用 handler key 承载必须保留的前端命令式逻辑。
• beforeSubmit 只保留 payload 归一化，例如 cascader 数组转 id。
• 表格里的历史字符串函数可先保留，由 useDynamic() 兼容转换。

兼容策略

旧 schema 消费方仍可读取 option、rules、formData。新字段按增量方式使用，前端读取失败时保持原有渲染路径。