配置对象的依赖关系

03/10/2025, by Ivan

配置对象可以声明依赖关系。依赖项可以是模块、主题或实体。

配置对象的依赖必须在配置对象安装之前就已安装。如果缺少依赖且未在站点中安装，则该配置对象无法被安装。模块必须在其 info YAML 文件中声明其配置对象所需的模块和主题依赖。

通常，模块开发人员无需手动为配置对象声明依赖。通过扩展核心配置实体基类以及从标准插件 API 提供者中创建插件，依赖会被自动计算并声明。

概览

配置对象的依赖通过 config_dependencies 键在配置对象定义中声明。该数组的键可以包括以下几类：

content
config
module
theme

配置对象通过实现 \Drupal\Core\Config\Entity\ConfigEntityInterface::calculateDependencies() 来定义其依赖。此方法应当从配置对象实现的 \Drupal\Core\Entity\EntityInterface::preSave() 中调用。实现时应使用辅助方法 \Drupal\Core\Config\Entity\ConfigEntityBase::addDependency() 来添加依赖。核心中的所有实现都会调用父类方法 \Drupal\Core\Config\Entity\ConfigEntityBase::calculateDependencies()，该方法会重置依赖，并为实现了 \Drupal\Core\Entity\EntityWithPluginCollectionInterface 的配置对象提供插件提供者依赖的实现。详情请参阅配置依赖管理器 API 文档，以了解这些类和方法。

配置依赖如何计算

基于配置对象属性计算依赖

@todo - 参见 \Drupal\block\Entity\Block::calculateDependencies

基于其他配置对象计算依赖

@todo - 参见 \Drupal\entity\EntityDisplayBase::calculateDependencies （这是一个相当复杂的示例）

在插件及其派生中计算依赖

@todo - 参见 Drupal\Core\Config\Entity\ConfigEntityBase::calculateDependencies —— 注意 config 对象实现了 EntityWithPluginBagInterface，此后会自动添加提供该插件的模块作为依赖。

插件派生的定义来源于基础插件。例如，\Drupal\system\Plugin\Derivative\SystemMenuBlock 就是从 \Drupal\system\Plugin\Block\SystemMenuBlock 派生的插件。系统菜单块需要在块模块配置对象与通过块提供的菜单配置对象之间建立依赖关系。

\Drupal\system\Plugin\Block\SystemMenuBlock 实现了 getDerivativeDefinitions() 方法。因此，派生出的菜单块（如 Bartik 页脚菜单块）会依赖于对应的 \Drupal\system\Entity\Menu 实体。

public function getDerivativeDefinitions($base_plugin_definition) {
  foreach ($this->menuStorage->loadMultiple() as $menu => $entity) {
    $this->derivatives[$menu] = $base_plugin_definition;
    $this->derivatives[$menu]['admin_label'] = $entity->label();
    $this->derivatives[$menu]['config_dependencies']['config'] = array($entity->getConfigDependencyName());
  }
  return $this->derivatives;
}

在上述代码中，每个系统菜单块派生体都会被分配一个依赖，依赖于提供该菜单的配置对象。要获取用于标识配置依赖的实体名称，需要调用实体的 getConfigDependencyName() 方法。对象名称是一个组合字符串，不应在依赖声明处硬编码。

config_dependencies 属性也可以在插件定义中声明。但由于配置对象的依赖大多是动态的，因此它们通常是计算得出的。在插件定义中声明静态依赖的情况很少见，且应尽量避免。

强制依赖

@todo - 参见 https://www.drupal.org/node/2404447。

更多关于导出和导入配置文件的信息，请参阅 Drupal 8 中的配置管理。

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

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