EP02. "elementor-form-action 表单提交动作开发"

首页 › AI 工具 › Claude · Skills · Elementor Skills · EP02

约 14 分钟· #EP02#Claude#Elementor Skills

客户填完 Elementor Pro 的表单要发去 CRM、丢一个 webhook、还是写进自己的数据表？表单本身没有这些能力，得自己写一个提交后的"动作"（Action）接上去——elementor-form-action 就是帮你把这个动作骨架搭对
这是 mekko-digital/elementor-skills 开源 skill 包的其中一个，Pro-only（免费版 Elementor 没有 Form widget）
核心是继承 Action_Base 抽象类，实现 4 个必要方法（命名、设置面板、提交后执行、导出时脱敏）
前置知识：先看过 Overview 系列「Claude Code 是什么与新手上手」「进阶功能：Skills、Plugins 与 Routines」两篇；也建议知道 Elementor Pro Form widget 后台的基本操作（Actions After Submit 面板）

重点内容

这个 Skill 是做什么的

elementor-form-action 专门解决一个问题：Elementor Pro 表单提交成功之后，要触发什么副作用。同一个开源包里的 elementor-widget-create 管的是"造一个新控件"，这个 skill 管的是"表单提交完之后该做什么事"，两者不重叠。

适合用在：

要新增一个"After Submit"动作，比如发送到自定义 CRM、打一个 webhook、写进自定义数据表
需要在表单提交成功后触发某个副作用（发通知、更新库存、排队处理等）
要做完整的 OAuth 型 CRM 集成（带"Connect"面板、字段映射）

不适合用在：

要新增一个全新的表单字段类型（不是提交动作）——那是走并列的 fields_registrar 注册，不是这个 skill 覆盖的范围
单纯排查一个已存在的动作为什么没有触发或表单渲染坏了——那是 elementor-debug-render 的工作
要做的不是 Form widget，而是普通 widget——那是 elementor-widget-create 的工作

📌 这个 skill 依赖 Elementor Pro 的 Forms 模块必须启用，免费版 Elementor 没有这个功能。

参考代码位置

抽象类：elementor-pro/modules/forms/classes/action-base.php（Action_Base，第 10–44 行）
官方参考实现：elementor-pro/modules/forms/actions/webhook.php（想抄写法可以直接对照这个文件）
注册器：elementor-pro/modules/forms/module.php（$this->actions_registrar->register( $instance, $id )）

4 个必须实现的方法

方法	作用
`get_name()`	动作的 slug，会出现在表单的 `submit_actions` 多选列表里
`get_label()`	显示给用户看的动作名称（勾选框旁边的文字）
`register_settings_section( $widget )`	加控件面板；一定要用 `'condition' => [ 'submit_actions' => $this->get_name() ]` 包住，这样设置只在动作被启用时才显示；整段包在 `start_controls_section()` / `end_controls_section()` 之间
`run( $record, $ajax_handler )`	提交成功后才会执行。`$record` 是 `Form_Record`（见 `classes/form-record.php`）：`$record->get('fields')`、`$record->get('form_settings')`、`$record->get('meta')`；要影响返回给前端的 JSON，用 `$ajax_handler->add_error( $field, $msg )` / `->add_response_data( $key, $value )`
`on_export( $element )`	模板被导出时，把 API key / 密钥这类敏感数据从 element 数据里剥掉；返回清理后的 element 数组，没需要处理就返回原样（no-op）

实操示例：注册一个自定义动作

// ✅ GOOD：挂在 elementor_pro/forms/actions/register 这个 hook 上
add_action( 'elementor_pro/forms/actions/register', function( $actions_registrar ) {
    require_once __DIR__ . '/actions/my-action.php';
    $actions_registrar->register( new \My_Plugin\Forms\My_Action() );
} );

// ❌ BAD：不要调用已废弃的方法（3.5.0 起弃用，见 forms/module.php:156）
Plugin::instance()->modules_manager->get_modules( 'forms' )->add_form_action( ... );

敏感字段怎么处理

API key、密钥这类字段，注册控件时要额外加两个参数：

$widget->add_control( 'api_key', [
    'label'       => __( 'API Key', 'td' ),
    'type'        => \Elementor\Controls_Manager::TEXT,
    'ai'          => [ 'active' => false ],   // 不让 AI 功能读到这个字段
    'render_type' => 'none',                  // 不参与前端实时渲染
    'condition'   => [ 'submit_actions' => 'my_action' ],
] );

对应地，在 on_export() 里把这个字段的值清掉，避免密钥被打包进导出的模板文件里。

两种动作，怎么选

需求	该继承的类	说明
单纯的动作（发 webhook、写自定义表、触发一个函数）	`Action_Base`	本文默认讲的这条路，覆盖大多数场景
完整 CRM 集成（要有"Connect"面板、OAuth 授权、远程字段映射）	`Integration_Base`（`forms/classes/integration-base.php`）	多一层 `handle_panel_request()` 回调，走 `pro_forms_panel_action_data` 这个 ajax action（`module.php:179-181`）；Mailchimp/ActiveCampaign/GetResponse 的 handler（`forms/classes/*-handler.php`）都是现成的参考实现

怎么安装

这个 skill 是 mekko-digital/elementor-skills 这个开源仓库打包的 8 个技能之一，用 Claude Code 的插件市场机制安装，装一次全部到位：

Claude Code（推荐：走插件市场）：

claude plugin marketplace add mekko-digital/elementor-skills
claude plugin install elementor-skills@elementor-skills-marketplace

Claude Code（手动方式）： 把 skills/elementor-form-action 这个文件夹复制到 ~/.claude/skills/（所有项目都能用）或专案底下的 ./.claude/skills/（只想在这个项目用）。

Claude Desktop / claude.ai： 走 Settings → Capabilities → Skills，上传 skills/elementor-form-action 这个文件夹（打包成 zip，内含 SKILL.md）——插件市场机制是 Claude Code 专属的，Desktop 端目前只能手动上传单个 skill。

常见错误

❌ 忘记给控件加 'condition' => [ 'submit_actions' => $this->get_name() ]——设置面板会一直显示，不管这个动作有没有被勾选启用
❌ 敏感控件（API key/密钥）没设 'ai' => [ 'active' => false ] 和 'render_type' => 'none'，也没在 on_export() 里清掉——密钥可能被 AI 功能读到，或者被打包进导出的模板文件
❌ 在 run() 里做长耗时的操作（调用外部 CRM、webhook）却不设超时——提交已经算成功了，这里出错只有调用 $ajax_handler->add_error_message() 才会影响用户看到的结果，卡住只会拖慢响应
❌ 用字段的 label 当 key 去取值——表单字段是按 custom_id（或自动生成的 id）取值的，label 只是用来显示
📌 蜜罐（honeypot）/ reCAPTCHA / Akismet 这些反垃圾检查都在你的动作之前跑完——run() 被调用时，这条提交已经被判定为合法
💡 动作写完用同一个 skill 包里的 elementor-deploy-verify 部署到 staging 站确认真的注册成功（断言 actions_registrar->get('<name>') 存在），再交给别人用

Sources

官方文档：

elementor-skills（GitHub 仓库）— https://github.com/Mekko-Digital/elementor-skills
elementor-form-action SKILL.md — https://github.com/Mekko-Digital/elementor-skills/blob/main/skills/elementor-form-action/SKILL.md