创建字段格式化器

04/10/2025, by Ivan

字段格式化器模块用于将字段数据格式化为最终用户可见的内容。字段格式化器被定义为插件，因此在编写新的字段格式化器之前，建议先熟悉插件 API。

字段格式化器类

文件：/modules/random/src/Plugin/Field/FieldFormatter/RandomDefaultFormatter.php

<?php

namespace Drupal\random\Plugin\Field\FieldFormatter;

use Drupal\Core\Field\FormatterBase;
use Drupal\Core\Field\FieldItemListInterface;

/**
 * Plugin implementation of the 'Random_default' formatter.
 *
 * @FieldFormatter(
 *   id = "Random_default",
 *   label = @Translation("Random text"),
 *   field_types = {
 *     "Random"
 *   }
 * )
 */
class RandomDefaultFormatter extends FormatterBase {

  /**
   * {@inheritdoc}
   */
  public function settingsSummary() {
    $summary = [];
    $summary[] = $this->t('Displays the random string.');
    return $summary;
  }

  /**
   * {@inheritdoc}
   */
  public function viewElements(FieldItemListInterface $items, $langcode) {
    $element = [];

    foreach ($items as $delta => $item) {
      // 将每个元素渲染为标记。
      $element[$delta] = ['#markup' => $item->value];
    }

    return $element;
  }

}

格式化器设置

如果你的格式化器需要自定义显示设置，需要执行以下三个步骤：

重写 PluginSettingsBase::defaultSettings() 以设置默认值
为自定义设置创建配置 schema
创建表单，允许用户修改这些设置

步骤 1：重写 PluginSettingsBase::defaultSettings() 设置默认值

/**
 * {@inheritdoc}
 */
public static function defaultSettings() {
  return [
    // 声明一个名为 'text_length' 的设置，默认值为 'short'
    'text_length' => 'short',
  ] + parent::defaultSettings();
}

步骤 2：为自定义设置创建配置 schema

配置 schema 文件路径：

[MODULE ROOT]/config/schema/[MODULE_NAME].schema.yml

在该文件中定义 defaultSettings() 中创建的设置的数据类型：

field.formatter.settings.[FORMATTER ID]:
  type: mapping
  label: 'FORMATTER NAME text length'
  mapping:
    text_length:
      type: string
      label: 'Text Length'

步骤 3：创建表单让用户修改设置

通过重写 FormatterBase::settingsForm() 创建表单。

别忘了在 php 文件开头引入 FormStateInterface 命名空间：

use Drupal\Core\Form\FormStateInterface;

/**
 * {@inheritdoc}
 */
public function settingsForm(array $form, FormStateInterface $form_state) {
  $form['text_length'] = [
    '#title' => $this->t('Text length'),
    '#type' => 'select',
    '#options' => [
      'short' => $this->t('Short'),
      'long' => $this->t('Long'),
    ],
    '#default_value' => $this->getSetting('text_length'),
  ];

  return $form;
}

在设置表单中使用 #ajax

在设置表单中使用 #ajax 并不简单，因为 settingsForm() 创建的表单片段不是在表单根部，而是深度嵌套的。以下示例中表单有两个设置：display_type（可以是 “label” 或 “entity”），以及 entity_display_mode（可以是 “full” 或 “teaser”）。只有当 display_type 设为 “entity” 时才显示 entity_display_mode。

public function settingsForm(array $form, FormStateInterface $form_state) {
  $form['display_type'] = [
    '#title' => $this->t('Display Type'),
    '#type' => 'select',
    '#options' => [
      'label' => $this->t('Label'),
      'entity' => $this->t('Entity'),
    ],
    '#default_value' => $this->getSetting('display_type'),
    '#ajax' => [
      'wrapper' => 'private_message_thread_member_formatter_settings_wrapper',
      'callback' => [$this, 'ajaxCallback'],
    ],
  ];

  $form['entity_display_mode'] = [
    '#prefix' => '<div id="private_message_thread_member_formatter_settings_wrapper">',
    '#suffix' => '</div>',
  ];

  $field_name = $this->fieldDefinition->getItemDefinition()->getFieldDefinition()->getName();
  $setting_key = 'display_type';

  if($value = $form_state->getValue(['fields', $field_name, 'settings_edit_form', 'settings', $setting_key])) {
    $display_type = $value;
  }
  else {
    $display_type = $this->getSetting('display_type');
  }

  if($display_type == 'entity') {
    $form['entity_display_mode']['#type'] = 'select';
    $form['entity_display_mode']['#title'] = $this->t('View mode');
    $form['entity_display_mode']['#options'] = [
      'full' => $this->t('Full'),
      'teaser' => $this->t('Teaser'),
    ];
    $form['entity_display_mode']['#default_value'] = $this->getSetting('entity_display_mode');
  }
  else {
    $form['entity_display_mode']['#markup'] = '';
  }

  return $form;
}

然后创建 ajax 回调并返回相应表单元素：

public function ajaxCallback(array $form, FormStateInterface $form_state) {
  $field_name = $this->fieldDefinition->getItemDefinition()->getFieldDefinition()->getName();
  $element_to_return = 'entity_display_mode';

  return $form['fields'][$field_name]['plugin']['settings_edit_form']['settings'][$element_to_return];
}

在字段格式化器中使用依赖注入

在字段格式化器中使用依赖注入需要三个步骤：

实现 ContainerFactoryPluginInterface
实现 ContainerFactoryPluginInterface::create()
重写 FormatterBase::__construct()

1) 实现 ContainerFactoryPluginInterface 接口

use Drupal\Core\Plugin\ContainerFactoryPluginInterface;

class MyFormatter extends FormatterBase implements ContainerFactoryPluginInterface {

2) 实现 ContainerFactoryPluginInterface::create()

以下示例向格式化器中注入 entity.manager 服务：

use Symfony\Component\DependencyInjection\ContainerInterface;

public static function create(ContainerInterface $container, array $configuration, $plugin_id, $plugin_definition) {
  return new static(
    $plugin_id,
    $plugin_definition,
    $configuration['field_definition'],
    $configuration['settings'],
    $configuration['label'],
    $configuration['view_mode'],
    $configuration['third_party_settings'],
    $container->get('entity.manager')
  );
}

3) 重写 FormatterBase::__construct()

重写 __construct()，调用 parent::__construct()，然后保存服务到类属性。

use Drupal\Core\Field\FieldDefinitionInterface;

/**
 * 实体管理服务
 *
 * @var \Drupal\Core\Entity\EntityManagerInterface
 */
protected $entityManager;

/**
 * 构造函数
 */
public function __construct($plugin_id, $plugin_definition, FieldDefinitionInterface $field_definition, array $settings, $label, $view_mode, array $third_party_settings, EntityManagerInterface $entityManager) {
  parent::__construct($plugin_id, $plugin_definition, $field_definition, $settings, $label, $view_mode, $third_party_settings);

  $this->entityManager = $entityManager;
}

现在你就可以在格式化器类的任意位置使用 $this->entityManager。

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

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