logo

额外区块类型 (EBT) - 全新的布局构建器体验❗

额外区块类型 (EBT) - 样式化、可定制的区块类型:幻灯片、标签页、卡片、手风琴等更多类型。内置背景、DOM Box、JavaScript 插件的设置。立即体验布局构建的未来。

演示 EBT 模块 下载 EBT 模块

❗额外段落类型 (EPT) - 全新的 Paragraphs 体验

额外段落类型 (EPT) - 类似的基于 Paragraph 的模块集合。

演示 EPT 模块 滚动

滚动

9.10.1. Drupal 字段 API。字段小部件:数据输入字段,为字段创建表单。

17/10/2025, by Ivan

Menu

在本教程中,我们将了解链接模块的字段小部件(Field Widget)是如何工作的。这是一篇概述性文章,因此如果你想开始编写你自己的字段小部件,请跳到后续的文章。

在上一课中,我们为节点和区块添加了链接字段。现在,让我们来看一下链接字段的表单是如何构建的。

我们已经接触过在 Drupal 中的 PHP 类自动加载,同时也有一个用于字段的小部件基类 WidgetBase:

core/lib/Drupal/Core/Field/WidgetBase.php

通过在模块中创建一个新的子类并将其放入 src/Plugin/Field/FieldWidget 目录下,该类会自动连接并可以用于字段。我们来看一下链接字段的小部件类:

core/modules/link/src/Plugin/Field/FieldWidget/LinkWidget.php

类注释包含了该小部件可用于的字段类型:

/**
 * Plugin implementation of the 'link' widget.
 *
 * @FieldWidget(
 *   id = "link_default",
 *   label = @Translation("Link"),
 *   field_types = {
 *     "link"
 *   }
 * )
 */

通过这种方式,你可以为现有字段向自定义模块添加新的字段小部件。

现在让我们继续讨论 formElement() 方法,这是小部件的主要方法之一,它通过 Form API 添加表单元素。链接小部件中有三个元素:

$element['title']
$element['uri']
$element['attributes']
这些字段将用于在节点或区块表单中输入数据。同时,还会为字段添加验证,例如 URI 字段必须包含正确的 URL 或本地站点地址。

另一个重要的方法是 settingsForm(),它负责定制你可以在管理表单页面上看到的表单:

link

字段小部件中的其他方法是可选的。我们不会详细讲解每个方法,因为它们并不一定用于编写自定义模块。如果你编写的是贡献模块,我认为你不会觉得阅读父类方法的描述有困难:

core/lib/Drupal/Core/Field/WidgetBase.php

所有字段的小部件配置都可以在每个实体的“管理表单显示”选项卡下单独配置:

manage form display