Bricks 表单生成器完整指南——从字段、动作到防垃圾提交

Bricks 的 Form 元素是建站最常用的元素之一：联系表单、询盘表单、报名表单、甚至登录注册页都能用它搭，全程可视化、不用写一行 HTML。本指南把 Form 元素的字段、动作、验证、防垃圾和数据库存档一次讲透，读完就能应付绝大多数表单需求。

如果你只需要一个能收询盘并发邮件的表单，先看询盘表单实战教程；本文是系统性的完整指南。

Form 元素能做什么

Form 元素可以构建自定义表单，并在提交后触发一系列动作（Actions）：发邮件通知、跳转页面、对接 SendGrid/Mailchimp、用户登录/注册等。如果内置动作不够用，还可以写自己的动作（自定义动作钩子）。

防垃圾方面，Form 元素内置集成 Google reCAPTCHA V3、hCaptcha 和 Cloudflare Turnstile，支持动态数据与表单验证钩子。

表单字段：16 种内置字段类型

Form 元素内置以下字段类型：

• Email
• Text
• Textarea
• Telephone
• Number
• URL
• Image（媒体库）
• Gallery（媒体库）
• Checkbox
• Select（下拉）
• Radio
• Password
• Remember me
• Datepicker
• File upload
• Hidden

每个字段都有自己的「字段 ID」（六位随机字符，位于字段设置底部）。这个 ID 在后面做动态字段、自定义验证、防重复提交时都会用到，先记住它的存在。

另外还有一个 HTML 字段可以往表单里插入自定义标记（它不能作为蜜罐字段，见下文）。

提交动作（Actions）：邮件、重定向、Webhook

表单提交成功后按选中顺序依次执行动作，唯一的例外是 Redirect（重定向）永远排到最后执行。每个动作会生成一个独立的控制组。

Email 邮件通知

默认把全部字段内容发给站点管理员邮箱。可配置项：

• Subject：邮件主题
• Send to email address：收件人，支持多个邮箱用逗号分隔
• From email address / From name：发件人地址与名称
• Reply to email address：回复地址
• Email content：自定义邮件内容，留空则发送包含全部字段的默认内容
• Error message：邮件发送失败时展示给用户的提示
• HTML email：开启则发送 HTML 邮件，否则纯文本

想确保邮件送达，强烈建议配好 SMTP——WordPress 免费 SMTP 插件不少，五分钟能搞定。收不到邮件时先查是不是别的插件或自定义代码覆盖了 From 名称与地址。

表单动态字段

可以把提交的字段值塞进邮件设置里：把字段 ID 用双花括号包起来，例如 {{form_field_id}}，用在 Subject、Email content、From name 等设置中。

三个内置占位符：

• {{form_field_id}}：某个提交字段的值（换成真实字段 ID）
• {{referrer_url}}：表单所在页面的 URL
• {{all_fields}}：在 Email content 里渲染所有提交字段

Redirect 重定向

提交成功后跳转到站内其他页面或自定义 URL，可设置延迟时间。1.10 起 Custom redirect URL 支持表单动态字段标签。

Webhook（2.0+）

把提交数据以 HTTP 请求发给一个或多个外部 URL，典型用途：把线索推给 Zoho/HubSpot/Salesforce 等 CRM、触发 Zapier/Make 场景、写入 Google Sheets 或外部数据库、通知自建 API 或 Slack bot。

每个端点可配置：

• Name：备注名称
• Endpoint URL：接收数据的 URL
• Data format：JSON 或 Form data（x-www-form-urlencoded）
• Data：可选 payload 模板，用动态字段标签拼装；留空发送全部字段

{ "name": "{{43f295}}", "email": "{{a5c626}}" }

• Headers：自定义请求头，JSON 格式，例如 { "Authorization": "Bearer token" }

还有 Max payload size（KB）（默认 1024，即 1MB）、Rate limiting（按小时限流，默认 60 次/小时）、Continue on error（webhook 失败时是否仍算提交成功）等设置。

以 Zapier 为例：在 Zapier 里新建 Zap → 选 Webhooks by Zapier 触发 → Catch Hook → 复制 webhook URL → 在 Bricks 表单里加 Webhook 动作 → 粘贴 Endpoint URL → Data format 选 JSON → 保存测试。

Unlock password protection

用于解锁 Bricks 密码保护的内容：把字段映射到 Password，未映射时默认取表单里第一个密码字段。

Create & Update posts（2.1+）

用「Create post」「Update post」动作可以做前台发布/编辑表单，详见官方 Create/Update Posts on the Frontend 文档。

进阶动作：保存提交、创建文章、用户登录注册

Form 还内置四个认证动作：User login（用户登录）、User registration（用户注册）、Lost password（找回密码）、Reset password（重置密码），配合自定义认证页面，可以完全替换 WordPress 默认的登录注册界面（见后文）。

动作执行顺序有讲究：如果某个动作失败，后续动作全部停止。例如「保存提交」失败，「邮件」就不会发。把动作按工作流需要的顺序排好。

自定义动作与自定义表单动作（开发向）

Custom 动作（bricks/form/custom_action）

在表单的 Actions 里勾选 Custom，然后挂 bricks/form/custom_action 钩子，回调接收 $form 对象，可用三个方法取数据：

• $form->get_settings()：表单设置（字段、动作、按钮样式等），关联数组
• $form->get_fields()：本次提交的字段值，含 postId、formId、referrer 等元信息
• $form->get_uploaded_files()：提交的文件，按字段 ID 分组，含 file（物理路径）、url、type

基本骨架：

<?php
function my_form_custom_action( $form ) {
  // $fields = $form->get_fields();
  // $formId = $fields['formId'];
  // $postId = $fields['postId'];
  // $settings = $form->get_settings();
  // $files = $form->get_uploaded_files();

  // Perform some logic here...

  // Set result in case it fails
  $form->set_result([
    'action' => 'my_custom_action',
    'type'   => 'success', // or 'error' or 'info'
    'message' => esc_html__('Oh my custom action failed', 'bricks'),
  ]);
}
add_action( 'bricks/form/custom_action', 'my_form_custom_action', 10, 1 );

官方文档还给了两个例子：用 Custom 动作触发第二封邮件（Bricks 原生每个表单只能发一封通知邮件）、按 URL 参数做自定义跳转（把 {url_parameter:key} 放进隐藏字段，再在回调里读出来用 set_result 返回 type => 'redirect' + redirectTo）。

自定义表单动作（1.12.2+）

可以用三个过滤器给表单加「全新的动作类型」（比如发给 Slack 的通知动作）：

• bricks/elements/form/controls：把新动作加入 Actions 下拉选项，并定义它的设置控件
• bricks/elements/form/control_groups：新增一个控制组收纳这些设置
• bricks/form/action/{form_action}：处理提交时的动作逻辑

三段式骨架（官方 Slack 例子）：

// 1 - Add the action to form actions setting
add_filter(
    'bricks/elements/form/controls',
    function( $controls ) {
        $controls['actions']['options']['slack-notification'] = esc_html__( 'Send to Slack', 'bricks' );
        $controls['slackFields'] = [
            'group'       => 'slack',
            'label'       => esc_html__( 'Fields to include', 'bricks' ),
            'type'        => 'select',
            'multiple'    => true,
            'options'     => [], // Auto-populated with form fields with 'map_fields' => true
            'map_fields'  => true,
            'description' => esc_html__( 'Select which form fields to include in the Slack notification', 'bricks' ),
        ];
        return $controls;
    }
);

// 2 - Add a new control group
add_filter(
    'bricks/elements/form/control_groups',
    function( $control_groups ) {
        $control_groups['slack'] = [
            'title' => esc_html__( 'Slack notification', 'bricks' ),
            'required' => [ 'actions', '=', 'slack-notification' ],
        ];
        return $control_groups;
    }
);

// 3 - Handle the action logic on form submission
add_action(
    'bricks/form/action/slack-notification',
    function ( $form ) {
        $settings = $form->get_settings();
        $fields   = $form->get_fields();
        // Custom Slack notification implementation
    }
);

表单验证：内置校验与 bricks/form/validate 钩子

即时输入校验（Immediate input validation）

给字段填上 Error message，字段失焦时就会按以下规则即时判断并显示错误：Required（必填）、Min/Max number（数字范围）、Email（邮箱格式）、URL（URL 结构）。1.12 起新增 Disable Form Validation 控件，可分别关掉「输入时」和「失焦时」的即时校验，但提交时仍会校验。

Pattern 属性校验（2.0.2+）

pattern 属性（配合 title 属性）可以在浏览器端做原生校验，适用于 text、tel、email、url、password 字段。例如要求 ###-###-### 格式的电话号码：

pattern: ^\d{3}-\d{3}-\d{3}$

注意不要开启「Don’t use browser validation」开关。

自定义校验钩子

Bricks 1.7.1 提供 bricks/form/validate 过滤器，第一个参数 $errors 是错误信息数组，第二个参数 $form 是提交的表单实例。往 $errors 里塞消息就会阻止提交。

官方例子：校验邮箱必须是站内已注册用户（注意用 $form->get_settings() / $form->get_fields() 拿表单 ID 和字段值，按目标表单过滤）：

add_filter( 'bricks/form/validate', function( $errors, $form ) {

  $form_settings = $form->get_settings();
  $form_fields   = $form->get_fields();
  $form_id       = $form_fields['formId'];

  // Skip validation: Form ID is not 'kfbqso'
  if ( $form_id !== 'kfbqso' ) {
    return $errors;
  }

  // Get submitted field value of form field ID '7e30aa'
  $email_address = $form->get_field_value( '7e30aa' );

  // Error: Email from registered user (show error message, and don't send email)
  if ( ! email_exists( $email_address ) ) {
    $errors[] = esc_html__( 'This email address is not in our system, sorry.', 'bricks' );
  }

  // Make sure to always return the $errors array
  return $errors;

}, 10, 2 );

垃圾防护：reCAPTCHA v3、hCaptcha、Turnstile 与 Honeypot

Form 元素集成三种人机验证 + 一个蜜罐字段，全部在 Form 元素的 Spam Protection 控制组里开关。

reCAPTCHA V3 阈值调优

默认阈值 0.5。如果垃圾还是多，用 bricks/form/recaptcha_score_threshold 过滤器调高：

add_filter( 'bricks/form/recaptcha_score_threshold', function( $score ) {
  // Bricks default is 0.5
  $score = 0.8;
  return $score;
}, 10, 1 );

阈值 0.8 意味着只接受更「像真人」的提交。关于 reCAPTCHA v3 的完整接入步骤，看给 Bricks Form 加 Google reCAPTCHA v3。

自动化测试

在 staging 或测试站做自动化测试时，hCaptcha 官方提供测试密钥——测试密钥没有防机器人能力，绝不能用在生产表单上。

保存表单提交：开启、查看与导出

Bricks 1.9.2 起可以把表单提交存进 WordPress 数据库，用于联系表单、报价申请、活动报名、线索收集等需要后台存档的场景。

开启

Bricks > Settings > General > Form submissions，打开 Save form submissions in database 并保存。Bricks 会创建自定义数据表 bricks_form_submissions（带 WP 表前缀），设置页出现两个危险按钮：

• Reset database table：清空所有已存提交
• Delete database table：删表并关闭全局设置

两个操作都不可逆，动手前先备份。

在表单上启用

编辑 Form 元素，在 Actions 控制组里选 Save submission。动作顺序重要：如果保存失败，后面的动作不会执行。Bricks 始终把 Redirect 移到动作列表最后。

保存什么

• 提交时的帖子 ID（如有）
• Form 元素 ID（全局元素则用全局 ID）
• 提交日期
• 提交字段数据（JSON 存储）
• 浏览器与操作系统（从 user agent 解析）
• Referrer URL
• 登录用户 ID（如已登录）
• IP 地址（仅当该表单开启 Save IP address）

HTML 字段和蜜罐字段不保存。写入前 Bricks 会按字段类型清洗数据（email 按邮箱清洗、URL 按 URL 清洗、数字按数字清洗等）。

存档设置

• Form name：给表单起个辨识度高的名字，后台 Form Submissions 页面用它显示；不设则显示 [No name]
• Save IP address：需要存 IP 才开，开了记得更新隐私说明
• Max. entries：最大存档条数，适合活动报名、限量候补；达到上限后返回错误且后续动作不执行，错误文案可自定义
• Prevent duplicates：防重复提交——复制目标字段的六位 ID，在 Prevent duplicates 里新增一条并填进 Compare with (Field ID)；开启 Save IP address 后可用 ip 关键字限制同一 IP 只存一条。所有配置的查重条件都匹配才算重复，字段值忽略大小写并去首尾空格

查看与导出

后台 Bricks > Form Submissions 查看。概览页按 Form ID 分组显示表单名和条数；点表单名看该表单全部条目，右上角 Screen options 可开关元数据列（Date、Browser、IP address、OS、Referrer、User）。搜索框搜的是存档数据 JSON（即字段值），不搜元数据列。

Download (CSV) 导出当前表单全部提交；Bricks 会为疑似电子表格公式的单元格加前缀，降低 CSV 公式注入风险。

谁能看提交

Bricks 1.11 引入 bricks_form_submission_access 能力，可在 Bricks > Settings > General > Form submissions 按角色勾选（Administrator 默认开启且不可关），也可在 Users > 编辑用户里单独给某个用户授权。有查看权但没有完整 Bricks 管理权的用户，会看到一个精简的 Bricks - Form Submissions 菜单。只有能 manage options 的用户才能重置/删除整表或批量删除。

开发者钩子

• bricks/form/save-submission/form_data：入库前清洗/增删字段
• bricks/form/submission-table/file_url：调整提交表里文件字段的 URL（文件可存在媒体库、uploads 目录或自定义目录）

自定义登录/注册/找回密码页面

Bricks 1.9.2 起可以为 WordPress 认证流程指定自定义页面，替换默认的登录/注册/找回密码/重置密码界面。注意：自定义页面只改变用户被送去哪里，认证逻辑仍走 WordPress 原生函数。

设置

Bricks > Settings > General > Custom authentication pages，为以下流程各选一个页面（WooCommerce 接管认证时 Bricks 会自动让位）：

要点：

• 登录页收到 redirect_to 参数时，Bricks 会把它存为隐藏字段，登录成功后跳过去（表单没设显式 Redirect 动作时）
• 出于隐私与安全，登录失败提示建议用通用文案，别暴露失败原因
• 注册页至少映射邮箱；用户名和密码可自动生成。Role 设置不允许 Administrator/Super Admin，被篡改时回退到站点默认角色
• 找回密码页对不存在的账号也返回成功响应（防枚举），账号存在则 WordPress 发重置邮件
• 重置密码页会把重置链接里的 key 和 login 参数渲染成隐藏字段，提交时由 WordPress 校验

访问控制（1.11+）

别人访问默认认证地址（如 wp-login.php）时怎么处理？Bricks > Settings > General > Custom authentication pages > WordPress authentication page access 有四个选项：

跳转时会保留查询参数（重置密码 key、登录 redirect 等）。

绕过自定义登录（1.9.4+）

访问任意认证页时，URL 加 brx_use_wp_login 参数可临时用默认登录页：

https://example.com/wp-login.php?brx_use_wp_login=1

该参数会种一个 5 分钟的绕过 cookie。可在设置里开 Disable custom authentication page bypass 关闭此功能——但关之前务必确认自定义登录页可用且你知道它的 URL，否则可能把自己锁在登录门外。

开发者过滤器

• bricks/auth/custom_redirect_url：按当前认证 URL 路径覆盖跳转地址
• bricks/auth/custom_login_redirect：换掉所选的自定义登录页
• bricks/auth/custom_registration_redirect：换掉所选的自定义注册页
• bricks/auth/custom_lost_password_redirect：换掉找回密码页
• bricks/auth/custom_reset_password_redirect：换掉重置密码页

多语言站、会员站或自定义路由场景用得上。

多列表单与日期选择器定制

多列布局

把字段 Width 设为百分比即可：两列表单就是把前两个字段宽度都设为 49%（留 2% 间距），底部 Spacing 设 2%，Alignment 选 space-between。

日期选择器

Bricks 1.5+ 用 Flatpickr 库，可用 bricks/element/form/datepicker_options 过滤器改初始化选项。例：把周一设为一周第一天。

add_filter( 'bricks/element/form/datepicker_options', function( $options, $element ) {
  $options['locale'] = [
    'firstDayOfWeek' => 1 // Set Monday as the first week day
  ];
  return $options;
}, 10, 2 );

日期选择器本地化

把语言包脚本放进 Bricks Settings > Custom Code > Body (footer) scripts，XX 换成语言代码（de 德语、pt 葡萄牙语等）：

<script src="https://npmcdn.com/flatpickr/dist/l10n/XX.js"></script>
<script>
  window.flatpickr.localize(window.flatpickr.l10ns.XX)
</script>

只想给某个表单换语言，用同一个过滤器按元素 ID 设置 $options['locale']：

add_filter( 'bricks/element/form/datepicker_options', function( $options, $element ) {
  if ( $element->id === 'abcdef' ) {
    // localize the form "abcdef" element
    $options['locale'] = 'XX';
  }
  return $options;
}, 10, 2 );

选项值 vs 标签

1.10.2 起，checkbox、radio、select 字段的选项可以用冒号分隔「值:标签」，例如 1:是——存储用冒号前的值，展示用冒号后的文案。

小结

Bricks Form 元素覆盖了建站表单的全部场景：16 种内置字段（外加 HTML 字段）+ 邮件/重定向/Webhook/保存提交/用户认证动作 + 三种人机验证和蜜罐 + 可编程的验证与自定义动作钩子。上手路径建议：先搭一个带 Email 动作的询盘表单（参考询盘表单实战），再开 Save submission 做后台存档，最后按需加 reCAPTCHA（接入教程）和自定义认证页面。邮件收不到先查 SMTP（Post SMTP + Gmail OAuth2 配置），垃圾提交多就把验证阈值调高。

站长

Ray Chan

WordPress Developer & Bricks Specialist

WordPress developer with 10+ years of client builds. Switched to Bricks in 2023 — now builds fast WordPress sites and migrates legacy Elementor/Divi projects.

获取报价 →浏览全部教程