2023 年 8 月 29 日

在 Drupal 中，通常会与 Solr 集成以实现强大的搜索功能。有时，您可能需要将多个字段的信息组合起来，为 Solr 搜索创建一个新的自定义字段。本指南将向您展示如何在 Drupal 10 中创建与 Solr 兼容的 Search API 处理器插件。本指南也兼容 Drupal 8 和 9。

先决条件

一个正常运行的 Drupal 8、9 或 10 安装
已与 Drupal 集成的 Solr 搜索引擎
一个名为 Club 的自定义内容类型，其中包含一个名为 field_cl_district_name 的自定义字段。（注意：title 字段是任何 Drupal 内容类型的默认属性。出于本文的目的，已向内容类型添加了一个用于地区名称的自定义字段。您应该创建或使用与您的项目相关的实际内容类型。）
已安装并启用了 Drupal 的 Search API 模块
已安装并启用了 Search API Solr 模块
一个名为 my_custom_module 的自定义模块（您可以随意命名）

Solr 兼容性

本指南旨在与 Solr 兼容，Solr 是 Drupal 使用最广泛的搜索后端之一。您将创建的自定义 Search API 处理器插件可以配置为与 Solr 无缝协作，从而增强您网站的搜索功能。

创建 Search API 处理器插件

步骤 1：准备您的自定义模块

如果您尚未创建自定义模块，则需要先进行设置。在 modules/custom 下创建一个名为 my_custom_module 的文件夹。在其中，您需要一个 my_custom_module.info.yml 文件，其中包含以下内容：

name: 'My Custom Module'
type: module
description: 'A custom module to extend Drupal functionalities.'
core_version_requirement: ^8 || ^9 || ^10
package: Custom

步骤 2：创建插件类

在 modules / custom / my_custom_module / src / Plugin / search_api / processor 中创建一个名为 FullClubName.php 的 PHP 文件。

FullClubName.php 文件应如下所示：

<?php

namespace Drupal\my_custom_module\Plugin\search_api\processor;

use Drupal\search_api\Datasource\DatasourceInterface;
use Drupal\search_api\Processor\ProcessorPluginBase;
use Drupal\search_api\Item\ItemInterface;
use Drupal\search_api\Processor\ProcessorProperty;

/**
 * @SearchApiProcessor(
 *   id = "full_club_name",
 *   label = @Translation("Full Club Name"),
 *   description = @Translation("Combine Title and District fields for clubs."),
 *   stages = {
 *     "add_properties" = 0,
 *   },
 *   locked = true,
 *   hidden = true,
 * )
 */
class FullClubName extends ProcessorPluginBase {

  public function getPropertyDefinitions(DatasourceInterface $datasource = NULL) {
    $properties = [];

    if (!$datasource) {
      $definition = [
        'label' => $this->t('Full Club Name'),
        'description' => $this->t('Combines the Title and District fields for clubs.'),
        'type' => 'string',
        'processor_id' => $this->getPluginId(),
      ];
      $properties['full_club_name'] = new ProcessorProperty($definition);
    }

    return $properties;
  }

  public function addFieldValues(ItemInterface $item) {
    $entity = $item->getOriginalObject()->getValue();
    if ($entity->bundle() === 'club') {
      $title = $entity->get('title')->getString();
      $district = $entity->get('field_cl_district_name')->getString();

      $combined_value = $title . ' (' . $district . ')';
      $fields = $this->getFieldsHelper תח()
        ->filterForPropertyPath($item->getFields(), NULL, 'full_club_name');
      foreach ($fields as $field) {
        $field->addValue($combined_value);
      }
    }
  }
}

注解说明

@SearchApiProcessor：此注解将类声明为 Search API 处理器插件。
id = "full_club_name"：插件的内部机器名称，必须是唯一的。
label = @Translation("Full Club Name")：插件的可读标签，可以翻译。
description = @Translation("Combine Title and District fields for clubs.")：提供有关此处理器插件功能的更多信息。
stages = { "add_properties" = 0 }：指定此插件在“add_properties”阶段运行，权重为 0。
locked = true：处理器已锁定到索引，不能通过管理界面删除。
hidden = true：处理器在管理界面中隐藏。

此注解至关重要，因为它定义了 Drupal 应如何处理后续类。它指定了从插件的 ID 和标签到更细微的行为（如它参与的阶段以及它在界面中是否被锁定或隐藏）的所有内容。

方法说明

在定义插件注解后，插件的核心在于您实现的方法。以下是 Search API 处理器插件通常需要的基本方法及其功能：

getPropertyDefinitions(DatasourceInterface $datasource = NULL)

此方法负责定义插件将添加或操作的新属性。它在插件注解中指定的“add_properties”阶段被调用。如果您的插件需要为搜索索引创建新字段，则在此处定义它们。

preprocessIndexItems(PreprocessIndexItemsEvent $event)

此方法用于填充您在 getPropertyDefinitions() 中定义的字段的值。如果您正在操作现有字段或添加新字段，请在此处指定逻辑。它接收一个事件对象，该对象包含即将被索引的所有项，允许您在将它们发送到搜索索引之前更改它们的属性。

步骤 3：启用插件并清除缓存

编写自定义 Search API 处理器插件代码后，您需要确保 Drupal 和 Search API 能够识别它。

如果模块尚未启用

如果您的自定义模块尚未启用，请导航到 Drupal 管理界面中的“扩展”页面（/admin/modules），找到您的自定义模块并启用它。

如果模块已启用

如果包含插件的自定义模块已启用，Drupal 将不会自动检测新插件。您需要清除缓存才能使更改生效。您可以通过管理界面导航到“配置”>“开发”>“性能”（/admin / config / development / performance）并单击“清除所有缓存”来清除缓存。

或者，您可以使用 Drush 通过以下命令清除缓存：

drush cr

步骤 4：配置 Search API 索引

启用模块并清除缓存后，请通过导航到 /admin/config/search/search-api/index/your-index/fields 来访问您的 Search API 索引字段设置。

单击“添加字段”按钮，该按钮通常位于页面顶部。此操作将显示可用字段的列表。
在此列表中，您应该找到新添加的自定义字段，标记为 Full Club Name。
选择此字段，然后单击字段名称旁边的“添加”按钮将其包含在您的索引中。
单击“完成”。
最后，重新索引您的内容，以确保新自定义字段已填充并可搜索。

在视图和搜索中使用自定义字段

启用自定义模块并清除缓存后，您的自定义 Search API 处理器插件应该已激活。这对您意味着：

索引视图字段可用性

您的新自定义字段 Full Club Name 将在 Drupal 中创建或编辑索引视图时在字段列表中可用。这使您能够将此聚合数据作为搜索结果或视图列表的一部分。

全文搜索过滤器

如果您已将自定义字段定义为 Search API 设置中的“全文”类型，您还可以将此字段用作索引视图中的过滤器条件。这允许用户专门对此组合字段执行全文搜索查询，从而可能提高搜索结果的准确性和相关性。

结论

本指南已引导您完成在 Drupal 8、9 和 10 中创建自定义 Search API 处理器插件的过程。该插件名为 FullClubName，将 Club 内容类型的 title 和 field_cl_district_name 字段合并为一个可搜索字段。这增强了您的搜索功能，并且是 Drupal 的灵活性和可扩展性的绝佳示例。

祝您调试愉快！