用途:面向 WordPress 开发者,说明如何扩展 Elementor Pro 表单模块,实现自定义表单动作、自定义字段类型、字段校验与提交处理。所有表单 API 均要求 Elementor Pro 处于启用状态。
主要能力:
- 表单动作:继承 \ElementorPro\Modules\Forms\Classes\Action_Base,通过 elementor_pro/forms/actions/register 钩子注册。必需方法 get_name()、get_label()、run( $record, $ajax_handler );可选 register_settings_section( $widget ) 添加控件、on_export( $element ) 导出时移除敏感设置。控件需放在带 submit_actions 条件的 section 中。run() 中可用 $record->get( 'form_settings' ) 取编辑器设置、$record->get( 'fields' ) 取提交字段,并通过 $ajax_handler->add_error()、add_success_message() 反馈。
- 自定义字段:继承 \ElementorPro\Modules\Forms\Fields\Field_Base,通过 elementor_pro/forms/fields/register 注册。必需 get_type()、get_name()、render( $item, $item_index, $form );可选 validation()、update_controls()、get_script_depends()、get_style_depends()。渲染时用 $form->add_render_attribute() 与 get_render_attribute_string()。字段控件通过 update_controls() 注入 form_fields 中继器,需带 condition、tab、inner_tab、tabs_wrapper。编辑器实时预览需用 elementor.hooks.addFilter 的 content_template 过滤器,且方法不要命名为 content_template()。
- 校验:全局钩子 elementor_pro/forms/validation 在表单处理前触发,可做单字段与跨字段校验;任何 add_error() 调用都会中止提交并返回错误。
- 处理钩子:elementor_pro/forms/validation(处理前校验)、elementor_pro/forms/process(处理中)、elementor_pro/forms/new(新记录)。
使用方式:在插件或主题中引入类文件,用 add_action 注册;字段依赖脚本样式需先 wp_register_script/wp_register_style,再在类中声明;Elementor 3.28 以下还需设置 $depended_scripts、$depended_styles 属性。可用 elementor_pro/forms/field_types 过滤器移除内置字段。
适用场景:需要把表单提交接入第三方服务(如 Sendy、Webhook)、添加专用输入类型(如本地电话、信用卡号)或实现自定义校验规则时。
限制:仅支持 Elementor Pro;资料未提供具体版本兼容范围、性能数据或收费信息。