配置架构/元数据

03/10/2025, by Ivan

Drupal 8 包含对由 Kwalify (http://www.kuwata-lab.com/kwalify/) 创建的 YAML 配置文件的架构/元数据语言的支持。Kwalify 本身是用 Ruby 编写的，我们对格式做了一些小的调整，因此并非所有 Kwalify 的细节都能直接应用，但已经非常接近。

速查表

为了快速理解和参考一些便捷的示例，请查看这份速查表，如果您还有疑问，请继续阅读：

ConfigSchemaCheatSheet1.5Thumb

/sites/default/files/config-schema-cheat-sheet1.5.pdf

入门示例

系统模块有两个与维护模式相关的配置参数（即网站是否对普通访客进入维护模式）：

<?php
$config = \Drupal::config('system.maintenance');
$message = $config->get('message');
$langcode = $config->get('langcode');
?>

（是否启用维护模式存储在状态系统中，而不是配置中。）

该配置对象的默认值存储在 core/modules/system/config/install/system.maintenance.yml 文件中，如下所示：

message: '@site is currently under maintenance. We should be back shortly. Thank you for your patience.'
langcode: en

每个模块都可以拥有所需数量的配置对象。这些都在一个或多个架构文件中定义，并与模块一起提供。对于系统模块，这些文件位于 core/modules/system/config/schema 中。system.schema.yml 文件中的相关部分如下：

system.maintenance:
  type: config_object
  label: 'Maintenance mode'
  mapping:
    message:
      type: text
      label: 'Message to display when in maintenance mode'

文件中的顶级键（"system.maintenance"）对应于 .yml 文件的基本文件名（"system.maintenance.yml"）以及配置对象的名称（config('system.maintenance')）。嵌套级别描述了文件中包含的内容。配置架构预定义了两种配置文件类型：全局配置文件使用 config_object，实体使用 config_entity。config_object 类型在 core.data_types.schema.yml 中定义：

# Root of a configuration object.

_core_config_info:
  type: mapping
  mapping:
    default_config_hash:
      type: string
      label: 'Default configuration hash'

config_object:
  type: mapping
  mapping:
    langcode:
      type: string
      label: 'Language code'
    _core:
      type: _core_config_info

mapping 类型是用于键值对的基本类型。通过 config_object 类型，维护模式的定义复用了 langcode 和 _core 键，并添加了一个新的键 message。回到 system.maintenance 的定义，label: 'Maintenance mode' 描述了架构的内容。实际的元素在 mapping 下列出，其中定义了 message 键，并继承了基类型的 langcode 和 _core。每个元素都有一个 type 和 label，分别描述数据类型和数据说明。标签通常与配置表单中的标签相同或相似，系统管理员可以编辑该值。

在核心支持的所有情况下，.yml 文件中的顶级元素都是一个映射，其中的元素在底部的 mapping 列表中定义。您必须使用 config_object 或 config_entity 这两个映射子类型之一。映射中的各个元素可以是任何类型，取决于您如何定义数据。_core 键及其下的所有键保留给 Drupal 核心使用。

架构文件的用途

1. 架构文件的主要用途是多语言支持。我们需要一种工具来识别配置中所有可翻译的字符串，以便当您提交自定义设置以及默认视图、额外的用户角色、菜单项等时，可以将它们作为您的模块/主题的一部分提供翻译，上传到 https://localize.drupal.org。为此，层级和类型定义就足够了。

2. 架构也用于基于数据提供实际的翻译表单。在这种情况下，类型和标签非常重要。核心配置翻译模块使用架构来生成翻译表单并保存翻译。两个最重要的可翻译类型是“label”用于单行文本输入和“text”用于多行文本输入。

3. 使用配置架构中内置的知识（即配置对象中存储的内容），配置对象的默认持久化实现需要配置架构，以便正确导出属性并指定数据类型。虽然最好提供配置架构，但如果您确实不想，可以在配置实体的实现中实现 toArray() 方法，这样就无需架构也能保存您的配置实体。

4. 配置架构还用于自动将值绑定到期望的类型。这确保了虽然 PHP 和 Web 表单通常偏向于将所有内容处理为字符串，但在保存配置时会使用正确的类型。这一点很重要，以便在部署配置时，差异只显示实际更改，而不会显示意外的类型更改。

5. 在 PHPUnit 所有派生自 TestBase 的测试默认强制执行严格的配置架构。如果缺少或无效的架构文件，将导致架构错误。虽然不推荐，但可以在测试中设置以下属性来跳过：

protected $strictConfigSchema = FALSE;

参见 https://drupal.org/project/config_inspector 模块，用于帮助调试架构。该模块帮助查找缺失的架构和不一致的元素，并通过多种方式展示您的数据和架构。

还有其他潜在的架构用途，例如基于架构生成 Web 服务接口。未来可能会出现更多我们尚未想到的使用场景。

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

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

配置架构/元数据

Menu

速查表

架构文件的用途