Drupal 11：使用 HTMX 创建级联选择表单
这是探讨 Drupal 中 HTMX 的系列文章的第四部分。在过去的两篇文章里，我探讨了在控制器中以不同方式使用 HTMX。这次，我要深入 HTMX 和表单的领域。
几年前，我曾在网站上写过一篇关于 Drupal 中级联 Ajax 选择表单的文章。当我尝试解决与选择表单和 Ajax 相关的问题时，常常会参考这篇文章。在那篇文章中，我使用年、月和日选择字段，并将它们关联起来，让它们在选择过程中相互影响。
我从事 Drupal 网站开发多年，但在 Drupal 表单中尝试实现 Ajax 时，仍需深呼吸。为了让一切正常运作，我最终会给表单字段添加包装元素或自定义属性，这似乎总是一次痛苦的经历。
当我学习 HTMX 和 Drupal 后，坐下来重新实现这个级联选择表单，大约半小时就完成了功能。大部分时间都花在了将表单元素添加到构建表单的方法中，这与在 Drupal 表单中添加 Ajax 的旧方法形成了鲜明对比。
在本文中，我们将创建一个包含多个选择元素的表单，然后使用 HTMX（以及一点表单状态 API）将它们关联起来，使选择一个元素时能更新其他元素。
本文包含的所有代码都能在 GitHub 上的 Drupal HTMX 示例项目中找到，这里我们会详细介绍代码的功能以及它生成内容所执行的操作。
和其他关于 HTMX 的文章一样，我将从基础开始，定义路由。
一、路由
这里我们需要的路由只需将路径 /htmx-examples/cascading-select 指向我们的表单类。
drupal_htmx_examples_cascading_select_form:
path: "/htmx-examples/creating-a-tabbed-interface-with-htmx"
defaults:
_form: '\Drupal\drupal_htmx_examples\Form\CascadingSelectForm'
_title: "HTMX 级联选择示例表单"
requirements:
_permission: "access content"
这个路由没什么特别的，就是一个普通的表单路由。
接下来，让我们为这个路由创建表单。
二、表单
表单类只是一个标准的 Drupal 表单，但在控制器中使用 HTMX 和在表单中使用 HTMX 是有区别的。当我们定义一个将使用 HTMX 的控制器时，有时需要将 request_stack 服务注入到表单中，以便检测任何传入的 HTMX 请求。对于表单来说，这不是必需的，因为 request_stack 服务是核心 FormBase 类的一部分，我们在 Drupal 中创建所有表单时都会扩展这个类。
这是表单类的大纲，它将包含我们的级联选择表单。
<?php
namespace Drupal\drupal_htmx_examples\Form;
use Drupal\Core\Form\FormBase;
use Drupal\Core\Form\FormStateInterface;
use Drupal\Core\Htmx\Htmx;
use Symfony\Component\DependencyInjection\ContainerInterface;
/**
* 使用 HTMX 展示级联选择的表单。
*/
class CascadingSelectForm extends FormBase {
/**
* {@inheritDoc}
*/
public function getFormId() {
return 'htmx_cascade_select_form';
}
/**
* {@inheritDoc}
*/
public function buildForm(array $form, FormStateInterface $form_state) {}
/**
* {@inheritDoc}
*/
public function submitForm(array &$form, FormStateInterface $form_state): void {
$year = $form_state->getValue('year');
$month = $form_state->getValue('month');
$day = $form_state->getValue('day');
$args = [
'%year' => $year,
'%month' => $month,
'%day' => $day,
];
$this->messenger()->addMessage($this->t('已提交表单，值为 年: %year, 月: %month, 日: %day', $args));
}
}
我还在这里添加了提交处理程序，它会把输入参数作为消息打印出来。
为了构建我们的表单，需要定义年、月和日选择字段，让它们在用户交互过程中可以相互更新。
第一个元素是年份选择，它定义了一个从 2019 年到 2050 年的任意日期范围，并将其作为数组提供给选择字段。我们还从表单状态中获取当前年份的值，以防用户已经提交了表单，我们希望保持该状态。这里我们可以对日期范围进行更细致的处理，但这只是一个测试表单。
$years = range(2019, 2050);
$years = array_combine($years, $years);
$year = $form_state->getValue('year');
$form['year'] = [
'#title' => $this->t('年'),
'#type' => 'select',
'#empty_option' => $this->t('- 选择 -'),
'#options' => $years,
'#default_value' => $year,
];
为了定义月份选择，我们只需创建一个小的月份数组（毕竟只有 12 个值），并将其提供给月份选择元素。我们还从表单状态中添加当前月份的值，然后在这里设置表单的 '#states' API，以便只有当年份选择有值时才显示月份选择。
$months = [
1 => $this->t('一月'),
2 => $this->t('二月'),
3 => $this->t('三月'),
4 => $this->t('四月'),
5 => $this->t('五月'),
6 => $this->t('六月'),
7 => $this->t('七月'),
8 => $this->t('八月'),
9 => $this->t('九月'),
10 => $this->t('十月'),
11 => $this->t('十一月'),
12 => $this->t('十二月'),
];
$month = $form_state->getValue('month');
$form['month'] = [
'#title' => $this->t('月'),
'#type' => 'select',
'#options' => $months,
'#empty_option' => $this->t('- 选择 -'),
'#default_value' => $month,
'#states' => [
'!visible' => [
':input[name="year"]' => ['value' => ''],
],
],
];
创建日期列表稍微复杂一些。有些月份的天数不同[需要引用]，所以我们不能简单地添加一个从 1 到 31 的范围就完事了。相反，我们需要监听年份和月份的值，然后使用 PHP 内置函数 cal_days_in_month() 来加载天数。这意味着如果月份是闰年的二月，我们仍然会在选择列表中显示正确的天数。我们还添加了 #states API 属性，以便只有当月份元素有值时才显示日期字段。
$days = [];
if ($month) {
$number = cal_days_in_month(CAL_GREGORIAN, $month, $year);
$days = range(1, $number);
$days = array_combine($days, $days);
}
$day = $form_state->getValue('day');
$form['day'] = [
'#title' => $this->t('日'),
'#type' => 'select',
'#options' => $days,
'#empty_option' => $this->t('- 选择 -'),
'#default_value' => $day,
'#states' => [
'!visible' => [
':input[name="month"]' => ['value' => ''],
],
],
];
最后，我们现在只需要添加一个提交按钮并返回表单。
$form['submit'] = [
'#type' => 'submit',
'#value' => '提交',
];
return $form;
这个表单会根据状态 API 显示和隐藏元素，但它不会用正确的天数填充日期字段。所以，让我们将重要的 HTMX 添加到表单中。
三、添加 HTMX
这个表单的 HTMX 需要在选择元素定义之后、表单末尾的返回语句之前添加。
我们需要为表单中的两个字段添加 HTMX 以执行以下操作：
- 当用户选择 月份 时，我们需要返回表单以计算该月的天数，并填充 日期 选择字段。
- 当用户选择 年份 时，我们需要返回并重新填充 月份 和 日期 选择字段。这将处理选择闰年且用户恰好选择了 2 月 29 日的情况。
我们使用 Htmx Drupal 类来创建我们需要的属性，并将它们应用到月份选择元素上。
(new Htmx())
->post()
->select('*:has(>select[name="day"])')
->target('*:has(>select[name="day"])')
->swap('outerHTML')
->applyTo($form['month']);
这会将以下 HTMX 属性添加到表单元素中。
data-hx-post- 这将向表单发送一个 POST 请求。由于我们没有为该方法添加值，它将自动使用当前路由。data-hx-select- 在 Drupal 中处理 HTMX 表单时，选择属性是必不可少的。如果你读过我之前的文章，你会记得当我们发出 HTMX 请求时，我们会从服务器得到整个表单。因此，我们需要告诉 HTMX 从响应中只挑选出我们需要的元素。在这种情况下，我们使用选择器字符串*:has(>select[name="day"]，它告诉 HTMX 我们要找到名称为 "day" 的选择元素的 父元素，即我们的日期选择元素。data-hx-target- 这告诉 HTMX 将我们从响应中提取的元素放置在哪里。我们使用与 data-hx-select 属性相同的选择器字符串，因为我们要替换页面上的日期选择元素。data-hs-swap- 最后，我们将交换策略设置为 outerHTML，这告诉 HTMX 用响应中选择的值完全替换目标元素。
创建另一个 Htmx Drupal 对象，将我们需要的属性添加到年份选择元素上。
(new Htmx())
->post()
->select('*:has(>select[name="month"])')
->target('*:has(>select[name="month"])')
// 我们还使用越界选择来针对 edit-day ID（即选择元素），以替换日期选择。
// 这可以处理选择 2 月 29 日且选择了非闰年的边缘情况。
->selectOob('#edit-day')
->swap('outerHTML')
->applyTo($form['year']);
年份表单元素的主要新增部分是添加了 selectOob() 方法。这会向年份字段添加一个 data-hx-select-oob 属性，当年份触发响应时，该属性会针对日期字段。
如果你读到这里，想知道为什么不能重用月份字段的 data-hx-select 和 data-hx-target 属性中的选择器字符串，那是因为当使用越界选择时，该选择器似乎会导致 HTMX 出现问题。HTMX 似乎希望属性中存在一个 ID，所以如果我们传递一个以 "*" 开头的字符串，它会尝试将其作为一个 ID 名称，如 "#*"，这对于选择器来说是无效的语法。
四、HTMX 工作流程
这些 HTMX 元素以以下方式工作。
请注意，我已经简化并删除了相当多的标记，以便于阅读和理解。
我们在这里要做的是选择日期 "2024 年 2 月 29 日"，这是一个闰年，然后选择 2023 年，这不是一个闰年。这会导致日期选择被取消选择，因为记录 29 不再存在。
表单被创建，其中包含以下元素。
<div class="js-form-item form-item form-type-select js-form-type-select form-item-year js-form-item-year">
<select data-hx-post="" data-hx-select="*:has(>select[name="month"])" data-hx-target="*:has(>select[name="month"])" data-hx-select-oob="edit-day" data-hx-swap="outerHTML ignoreTitle:true" data-drupal-selector="edit-year" id="edit-year" name="year" class="form-select form-element form-element--type-select">
<option value="" selected="selected">- 选择 -</option>
<option value="2019">2019</option>
...
<option value="2024">2024</option>
...
<option value="2050">2050</option>
</select>
</div>
<div class="js-form-item form-item form-type-select js-form-type-select form-item-month js-form-item-month" style="display: none;">
<select data-hx-post="" data-hx-select="*:has(>select[name="day"])" data-hx-target="*:has(>select[name="day"])" data-hx-swap="outerHTML ignoreTitle:true" data-drupal-selector="edit-month" id="edit-month" name="month" class="form-select form-element form-element--type-select" data-drupal-stats="{"!visible":{":input[name=\u0022year\u0022]":{"value":""}}}" data-once="states">
<option value="" selected="selected">- 选择 -</option>
<option value="1">一月</option>
<option value="2">二月</option>
<option value="3">三月</option>
<option value="4">四月</option>
<option value="5">五月</option>
<option value="6">六月</option>
<option value="7">七月</option>
<option value="8">八月</option>
<option value="9">九月</option>
<option value="10">十月</option>
<option value="11">十一月</option>
<option value="12">十二月</option>
</select>
</div>
<div class="js-form-item form-item form-type-select js-form-type-select form-item-day js-form-item-day" style="display: none;">
<select data