使用 .info.yml 文件定义主题

03/10/2025, by Ivan

要创建 Drupal 8 主题，首先需要创建一个 THEMENAME.info.yml 文件，它为 Drupal 提供关于你主题的元数据。这与模块和安装配置文件的定义方式类似，因此在 file.info.yml 文件中将键 type 设置为 theme 很重要，以便加以区分。

此页面包含一个 THEMENAME.info.yml 文件示例，以及该文件可能包含的信息概述。

创建 .info.yml 文件

在你的主题目录根目录下创建一个 .info.yml 文件。目录的名称必须与 .info.yml 文件相同。因此，如果你的主题名为 “Fluffiness”，那么目录应命名为 “fluffiness/”，文件名为 “fluffiness/fluffiness.info.yml”。如果文件包含最少的必需属性（name、type 和 core），你的主题将显示在网站的“管理 > 外观”部分中（http://example.com/admin/appearance）。请务必选择一个未被其他模块或主题使用的主题名称。主题名在 Drupal 配置中必须唯一，否则主题组件将无法正常加载。

将主题名称中的空格替换为下划线 (_)，用于目录名和 .info.yml 文件名。

如果你不熟悉 YAML 文件格式，请阅读 YAML 文件格式简要介绍。

不允许使用制表符（Tab）。只能使用空格。
属性和列表必须缩进两个（2）空格。

示例

name: Fluffiness
type: theme
description: 'A cuddly theme that offers extra fluffiness.'
core: 8.x
libraries:
  - fluffiness/global-styling
base theme: classy
regions:
  header: Header
  content: Content
  sidebar_first: 'Sidebar first'
  footer: Footer

在你的网站中，你可以通过查看核心自带的主题找到更多 .info.yml 文件的示例。例如，打开 core/themes/stark 目录并找到 stark.info.yml 文件。

键/值对

以下键/值对提供关于主题的元数据并定义一些核心功能。（参见 \Drupal\Core\Extension\InfoParserInterface::parse()）。

name （必填）
type （必填）
description （可选）
package （可选）
core （必填）
php （可选）
version （可选）
libraries （可选）
libraries-override （可选）
libraries-extend （可选）
base theme （推荐）
hidden （可选）
engine （可选）
logo （可选）
screenshot （可选）
regions （可选）
regions_hidden （可选）
features （可选）
stylesheets-remove （不推荐）
ckeditor_stylesheets （可选）

name - 名称（必填）

人类可读的名称。它会显示在“外观”页面中，供你启用主题时使用。

name: Fluffiness

type - 类型（必填）

扩展类型，例如 “module”（模块）、“theme”（主题）或 “profile”（配置文件）。对于主题，它必须始终是 “theme”。此值区分大小写。

type: theme

description - 描述（可选）

显示在“外观”页面的描述。

description: An extra cuddly Drupal theme available in grey and blue.

package - 包（可选）

定义“包”，允许将主题分组。

package: Core

core - 核心（必填）

定义主题兼容的 Drupal 核心版本。

core: 8.x

php（可选）

所需的最低 PHP 版本。默认使用 DRUPAL_MINIMUM_PHP 常量的值。

php: 5.5.9

version - 版本（可选）

定义版本。对于托管在 drupal.org 上的主题，版本号会由打包脚本自动填充。不应手动填写。

version: 8.x-1.0

libraries - 库（可选）

在主题启用时，添加到所有页面的库（CSS 和 JavaScript 资源）。了解更多关于主题和资源库的信息。

libraries:
  - fluffiness/global-styling

libraries-override - 库覆盖（可选）

用于覆盖的库和资源集合。阅读更多关于覆盖和扩展库的内容。

libraries-override:
  contextual/drupal.contextual-links:
    css:
      component:
        /core/themes/stable/css/contextual/contextual.module.css: false

libraries-extend - 库扩展（可选）

当连接某个库时，附加额外资源的集合。了解更多关于覆盖和扩展库的信息。

libraries-extend:
  core/drupal.user: 
    - classy/user1
    - classy/user2

base theme - 基础主题（推荐）

主题可以通过指定另一个主题为基础主题来继承其资源。推荐使用 “classy” 或 “stable”。（如果未指定，默认是 “stable”）。这有助于你的主题继承未来核心主题的改进。

base theme: classy

hidden（可选）

指示是否在“外观”页面中隐藏该主题，防止通过 UI 启用/禁用。

hidden: true

engine（可选）

模板引擎。默认是 “twig”。

engine: twig

logo - 标志（可选）

参见更改记录：https://www.drupal.org/node/2939152

相对于主题 .info.yml 文件的路径。默认情况下，Drupal 会在主题目录下查找名为 “logo.svg” 的文件，并将其用作主题的 Logo。

logo: images/logo.png

screenshot - 截图（可选）

相对于主题 .info.yml 文件的路径。截图应为 588x438 像素（尽管会显示更小）。默认情况下，Drupal 会在主题目录下查找名为 “screenshot.png” 的文件，并在“外观”页面显示。

screenshot: fluffiness.png

regions - 区域（可选）

主题区域列表。（注意：区域键前面没有破折号。）了解更多关于在主题中添加区域的信息。

regions:
  header: Header
  content: Content
  sidebar_first: 'First sidebar'

regions_hidden（可选）

需要移除的继承区域列表。

regions_hidden:
  - sidebar_last

features - 特性（可选）

在主题“设置”页面中显示的功能列表。

features:
  - comment_user_verification
  - comment_user_picture
  - favicon
  - logo
  - node_user_picture

stylesheets-remove - 移除样式表（不推荐）

移除在主题启用时加载的其他模块或主题的样式表。每个值必须是相对文档的完整路径，或者使用 @module_or_theme_name 令牌形式（需加引号）。注意：此键已弃用，并将在 Drupal 9 移除。大多数情况下应使用 libraries-override。

stylesheets-remove:
  - core/assets/vendor/normalize-css/normalize.css
  - '@classy/css/components/tabs.css'

ckeditor_stylesheets（可选）

在 CKEditor 编辑器中加载的样式表列表。

ckeditor_stylesheets:
  - https://fonts.googleapis.com/css?family=Open+Sans
  - css/base/elements.css

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

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

使用 .info.yml 文件定义主题

Menu

创建 .info.yml 文件

示例

键/值对

更多信息