Skip to content

表单 (OrchardCore.Forms)

表单模块提供了组件，如小部件和工作流活动，用于创建、验证和处理表单。

常规概念

构建表单时，主要涉及两个方面：

  1. 构建表单。
  2. 提交时处理表单。

这些部分是相互独立的，因此您可以仅使用表单构建器并自行处理其提交，或者提供表单 HTML 标记，但依赖于工作流来处理表单提交。
表单构建部分依赖于表单小部件。要创建表单，请将表单小部件添加到具有 FlowPart 附加的区域或内容项中。

创建表单

创建表单通常涉及以下步骤：

  1. 确保启用了表单功能。
  2. 创建具有 FlowPart 附加的新内容项。如果使用了 Blog 配方，则会有一个可以使用的 Page 内容类型。
  3. 添加表单小部件。
  4. 因为表单小部件附加了 FlowPart，所以您可以将其他小部件添加到表单小部件中。添加诸如输入、文本区域和按钮之类的小部件以构建您的表单。

处理表单提交

一旦您有了一个表单，就需要处理其提交。表单小部件有一个名为 Action 的字段，您可以在其中输入表单应提交到的 URL。这可以是指向自己的控制器的路径，但也可以是指向工作流类型的 URL。
使用工作流很方便，因为它不需要您创建自定义模块。

创建工作流并将其与表单关联通常涉及以下步骤：

  1. 确保启用了 HTTP 工作流活动 功能。
  2. 单击工作流菜单项并创建新的工作流类型。
  3. 将 HTTP 请求事件 事件添加到工作流中。确保 HTTP 方法 字段设置为 POST。
  4. 将生成的工作流 URL 复制到剪贴板中。
  5. 单击 保存 以保存更改并返回工作流编辑器。
  6. 确保 HTTP 请求事件活动已配置为起始活动（在工作流编辑器上，单击活动并单击开/关图标）。如果它是起始活动，则活动将呈绿色。
  7. 添加任何其他活动以验证和处理表单提交。稍后我们将看到一个真实的示例。
  8. 单击 保存 以保存工作流。
  9. 转到您添加了表单小部件的内容项。
  10. 将工作流 URL 粘贴到操作字段中。
  11. 保存您的内容项。

此时，您应该能够测试您的表单及其提交。

实现联系表单

在下面的演练中，我们将构建一个实际的联系表单，并使用工作流实现表单处理程序。
联系表单将包括以下字段：

  • 验证摘要小部件。
  • 名称输入小部件。
  • 电子邮件输入小部件。
  • 消息文本区域小部件。
  • Google NoCaptcha 小部件，以防止自动提交表单。
  • 提交按钮小部件。

工作流将执行以下操作：

  • 验证名称、电子邮件和消息字段不为空。如果它们为空，我们将添加模型状态验证错误。
  • 验证 NoCaptcha。
  • 向站点所有者发送电子邮件，说明已提交联系表单。电子邮件将包含提交的表单字段。

创建联系表单

对于此演练，我假设您在设置站点时执行了 Blog 配方，这将自动创建具有 FlowPart 附加的 Page 内容类型。 当您拥有全新的安装时，我们需要做的第一件事是启用以下功能：

  • 表单
  • HTTP 工作流活动
  • 电子邮件

接下来，创建一个新的页面内容项，并将其标题设置为 联系表单。单击 添加小部件 按钮以添加 表单 小部件。
将表单命名为 联系，现在暂时将操作字段留空。

将以下小部件添加到表单小部件中：

  • 验证摘要小部件
  • 输入小部件，名称 = "Name"，类型 = "Text"，占位符文本 = "输入您的姓名"
  • 输入小部件，名称 = "Email"，类型 = "Email"，占位符文本 = "输入您的电子邮件地址"
  • 文本区域小部件，名称 = "Message"，占位符文本 = "输入您的消息"
  • NoCaptcha 小部件（我们将立即配置设置）
  • 按钮小部件，文本 = "提交!"，类型 = "提交"

配置 NoCaptcha

添加 NoCaptcha 小部件时，会显示一条消息，指出需要配置 NoCaptcha 设置才能在表单上显示它。让我们立即这样做。
单击显示在消息中的 NoCaptcha 设置 链接。或者，转到 配置 -> 设置 -> 表单。

表单设置显示两个字段：SiteKey 和 Site Secret。您可以从 https://developers.google.com/recaptcha/ 免费获取这些值。小部件使用 reCaptcha V2，因此请确保为该版本创建 Site Key 和 Site Secret。
在使用 Google 生成 Site Key 和 Site Secret 后，将这些值分别复制并粘贴到 SiteKey 和 Site Secret 字段中，然后单击 保存 按钮。

最终表单配置应如下所示：

联系表单 - 扩展

在前端，它将如下所示：

联系表单 - 前端

创建联系表单工作流

为了验证表单输入并发送电子邮件，我们将创建一个工作流。

从管理菜单中单击 工作流 菜单项。接下来，单击 创建工作流类型。
现在要求我们为工作流提供名称。输入 "联系表单工作流"，将其他选项保留不变，然后单击 保存。这样做后，您将被重定向到工作流编辑器，这是我们将实现联系表单提交逻辑的地方。

添加 Http 请求事件

单击 添加事件 按钮，查找名为 HTTP 请求 的活动。
对于标题，输入 "提交联系表单"，并将 HTTP 方法 选择更改为 POST。
将生成的 URL（不包括方案、主机名和端口号）复制到剪贴板中，因为我们需要使用它来更新创建的表单。
单击 保存 返回到工作流编辑器。

回到工作流编辑器，现在有一个活动。单击此活动并单击最左侧的图标，将此活动转换为起始活动。

添加分叉活动

有各种方面的表单需要验证：我们希望确保用户为 名称、电子邮件 和 消息 字段输入了值，并且我们希望确保 captcha 有效。
虽然我们可以依次执行每个字段验证（即一个接一个），但我们将并行执行它。这样做的好处是，我们可以在不必立即检查每个验证结果的情况下执行表单字段验证。相反，我们可以在验证所有表单字段后，一次性检查所有验证结果。

单击 添加活动 按钮，查找名为 分叉 的活动。
对于标题，输入 "验证表单字段"。
将 分叉 活动连接到 HTTP 请求 活动。
单击 添加结果 按钮，添加以下结果：

  • 验证名称
  • 验证电子邮件
  • 验证消息
  • 验证 NoCaptcha

单击 保存。

添加验证表单字段活动

现在，我们将添加四个验证活动，每个活动都验证一个表单字段。
单击 添加活动 按钮，查找名为 验证表单字段 的活动。
对于标题，输入 "验证名称"。
将 验证名称 活动连接到 分叉 活动的 验证名称 结果。
在 验证表单字段 活动的 表单字段名称 字段中输入 "Name"。
在 验证表单字段 活动的 验证类型 字段中选择 "不为空"。
单击 保存。

重复此过程，添加以下验证活动：

  • 验证电子邮件
  • 标题：验证电子邮件
  • 连接到：分叉活动的验证电子邮件结果
  • 表单字段名称：Email
  • 验证类型：不为空
  • 验证消息
  • 标题：验证消息
  • 连接到：分叉活动的验证消息结果
  • 表单字段名称：Message
  • 验证类型：不为空
  • 验证 NoCaptcha
  • 标题：验证 NoCaptcha
  • 连接到：分叉活动的验证 NoCaptcha 结果
  • Site Key：从 Google 获取的 Site Key
  • Site Secret：从 Google 获取的 Site Secret

添加 Join 活动

现在，我们需要将分叉的工作流执行合并回单个流。
单击 添加活动 按钮，查找名为 Join 的活动。
对于标题，输入 "合并验证结果"。
将 Join 活动连接到所有验证活动的 完成 结果。
将 Join 活动的 等待模式 字段设置为 等待所有。
单击 保存。

添加验证表单活动

现在，我们需要添加一个活动，该活动将检查 ModelState 是否有效。
单击 添加活动 按钮，查找名为 验证表单 的活动。
对于标题，输入 "验证表单"。
将 验证表单 活动连接到 Join 活动的 完成 结果。
单击 保存。

添加重定向活动

如果 ModelState 无效，则我们将重定向回表单。
单击 添加活动 按钮，查找名为 重定向 的活动。
对于标题，输入 "显示表单错误"。
将 重定向 活动连接到 验证表单 活动的 无效 结果。
在 重定向 活动的 URL 字段中输入 "/contact-form"。
单击 保存。

添加电子邮件活动

如果 ModelState 有效，则我们将向站点所有者发送电子邮件。
单击 添加活动 按钮，查找名为 发送电子邮件 的活动。
对于标题，输入 "向站点所有者发送电子邮件"。
在 发送电子邮件 活动的 收件人 字段中输入 "admin@orchardcore.io"。
在 发送电子邮件 活动的 主题 字段中输入 "由 {{Request.Form.Name}} 提交的联系表单！"。
在 发送电子邮件 活动的 正文 字段中输入以下内容：

<p>已提交以下信息：<p/>
<p>名称：{{Request.Form.Name}}</p>
<p>电子邮件：{{Request.Form.Email}}</p>
<p>消息：{{Request.Form.Message}}</p>

单击 保存。

添加第二个重定向活动

在发送电子邮件后，我们将重定向到 "感谢" 页面。
单击 添加活动 按钮，查找名为 重定向 的活动。
对于标题，输入 "显示感谢页面"。
将 重定向 活动连接到 发送电子邮件 活动的 完成 结果。
在 重定向 活动的 URL 字段中输入 "/thank-you"。
单击 保存。

添加感谢页面

创建一个新的页面内容项，标题为 "感谢！"，并确保其永久链接为 "thank-you"。
将任何小部件添加到此页面，例如使用以下文本添加 段落 小部件： "感谢您的联系！我们会尽快回复。"

更新联系表单小部件

现在，我们需要更新联系表单小部件，以便它使用我们刚刚创建的工作流。
转到您创建的联系表单小部件所在的页面内容项。
展开联系表单小部件，并将工作流 URL 粘贴到 操作 字段中。
保存您的更改。

尝试它！

现在，您可以尝试提交表单。
导航到 https://localhost:44300/contact-form 并填写表单。如果一切正常，您应该会看到一封电子邮件进入并被重定向到感谢页面。
如果您留下任何字段为空或未通过 captcha，请将重定向到联系表单页面并查看验证错误。

修复丢失字段值问题

表单有一个问题，我故意将其留到最后。要查看问题，请在表单中输入一些值，除了一个（例如，将电子邮件留空，或者不选中 captcha 复选框）。当您提交表单时，请注意您输入的值已消失。
通常，当您将表单提交给 MVC 控制器时，模型绑定器将表单字段绑定到某个视图模型。在模型绑定阶段，MVC 将添加模型状态条目。但是，我们没有在任何地方调用模型绑定。我们仅在识别缺少值时添加模型验证错误。
为了解决此问题，我们必须将 绑定表单模型状态 活动添加到工作流中，并在第一个活动（Http 请求）和第二个活动（Fork 活动）之间连接它。这将导致将所有表单字段复制到 ModelState 中，该字段在再次显示表单时使用。

最终工作流应如下所示：

联系表单工作流

未来的改进

实现处理表单提交的工作流很容易，但是一旦开始将验证逻辑添加到混合中，工作流就会很快变得很大。在 Forms 模块的下一个版本中，将有一种更容易的方法来验证与 Form 小部件结合使用的表单提交。表单小部件将包含所有验证设置，并且将有一个单独的工作流活动，该活动根据这些设置验证提交的值。
低级别验证活动将继续作为工具箱的一部分，以支持针对不使用 Form 小部件的表单（例如，以原始 HTML 实现）的工作流验证。

Last update: March 22, 2023