Drupal

当前位置： 首页 Drupal主题开发（二）主题配置及CSS和JS加载

Drupal主题开发（二）主题配置及CSS和JS加载

由 webadmin 发布于 阅读 25 次

一、主题目录结构

themes/custom/mytheme/
├── assets/css/
│   ├── base.css
│   ├── layout.css
│   ├── components.css
│   └── style.css
├── assets/js/
│   └── script.js
├── templates/
│   └── page.html.twig
├── mytheme.info.yml
├── mytheme.libraries.yml
├── mytheme.theme
├── mytheme.png       # 主题预览图（建议 280x210 px）

二、主题配置

1、THEMENAME.info.yml配置

        在 Drupal 11（以及 Drupal 8/9/10）的主题系统中，THEMENAME.info.yml 文件是主题的核心配置文件，Drupal 通过它识别、加载和管理主题。

         它主要作用是：

  • 定义主题的基本信息（名称、描述、版本、包分类等）。
  • 声明主题的依赖关系（基础主题、所需模块等）。
  • 定义主题使用的样式和脚本库。
  • 指定主题的布局区域（regions）。
  • 设置默认的断点（breakpoints）、截图等。
1.1、常见参数及作用

（1）、基础信息

name: MyTheme #主题的名称，后台显示用。
type: theme #固定为 theme
description: 'A custom theme for Drupal 11.' #后台主题列表中显示的描述
core_version_requirement: ^11 #支持的 Drupal 核心版本范围，例如 ^11 表示支持 11.x。
package: Custom #主题分组（Core 为核心主题，Custom 通常用于自定义主题，方便分类）。
version: 1.0 #版本号（可选，主要用于信息展示）。

（2）、主题继承

 指定一个基础主题（如 stable9、classy），你的主题会继承它的模板和 CSS。如果你完全自定义，可以不设置。

base theme: classy

（3）、样式与脚本

        libraries：加载在所有页面的默认样式/脚本库（在 THEMENAME.libraries.yml 中定义）。例如 global-styling 可以包含全局 CSS 和 JS。

libraries:
  - mytheme/global-styling

       libraries-extend：扩展已有库（如核心库），加入自己的 CSS/JS。

libraries-extend:
  core/drupal.dialog:
    - mytheme/dialog

（4）、区域（Regions）

       定义主题中可放置区块（block）的区域。键是机器名，值是后台可见名称。

regions:
  header: Header
  primary_menu: 'Primary menu'
  secondary_menu: 'Secondary menu'
  content: Content
  sidebar_first: 'Sidebar first'
  footer: Footer

（5）、屏幕断点（Breakpoints）

breakpoints:
  mytheme.mobile:
    label: mobile
    mediaQuery: 'all and (min-width: 0px) and (max-width: 480px)'
    weight: 0
    multipliers:
      - 1x
      - 2x

定义响应式断点（用于图片样式、布局）。

（6）、依赖

      声明主题依赖的模块或主题。

dependencies:
  - drupal:views
  - drupal:block

（7）、屏幕截图（主题缩略图）

指定后台主题预览图（必须放在主题根目录）。

screenshot: screenshot.png

（8）、其他参数

        hidden：是否在后台主题列表中隐藏（多用于子主题或特殊用途）。

hidden: true

       engine：模板引擎（默认是 twig，一般不用写）。

engine: twig

      regions_hidden：不显示某些区域。

regions_hidden:
  - sidebar_first
1.2、一个完整示例（Drupal 11 推荐格式）
name: MyTheme
type: theme
description: 'A custom Drupal 11 theme.'
core_version_requirement: ^11
package: Custom
version: 1.0
base theme: classy
libraries:
  - mytheme/global-styling
libraries-extend:
  core/drupal.dialog:
    - mytheme/dialog
regions:
  header: Header
  primary_menu: 'Primary menu'
  secondary_menu: 'Secondary menu'
  content: Content
  sidebar_first: 'Sidebar first'
  footer: Footer
breakpoints:
  mytheme.mobile:
    label: mobile
    mediaQuery: 'all and (min-width: 0px) and (max-width: 480px)'
    weight: 0
    multipliers:
      - 1x
      - 2x
  mytheme.tablet:
    label: tablet
    mediaQuery: 'all and (min-width: 481px) and (max-width: 768px)'
    weight: 1
    multipliers:
      - 1x
      - 2x
dependencies:
  - drupal:views
  - drupal:block
screenshot: screenshot.png

2、THEMENAME.libraries.yml配置

      THEMENAME.libraries.yml文件用于定义 CSS、JS、依赖库，可以在主题或模块中按需加载。

       Drupal 加载顺序：

（1）、依赖库（dependencies）先加载
（2）、CSS/JS 文件按定义顺序加载
（3）、如果在 Twig 模板中 attach_library()，仅在该模板加载

2.1、THEMENAME.libraries.yml的语法结构
library_name:
  css:
    type:
      path/to/file.css: { 属性 }
  js:
    path/to/file.js: { 属性 }
  dependencies:
    - library_or_core/library_name
2.2、配置项详解

（1）、library_name

必填：每个库必须有唯一名称，用来在 info.yml 或 Twig attach。
作用：标识库。
示例：

global-styling:
...

（2）、css

可选：定义 CSS 文件及加载顺序。
语法：

css:
  type:
    path/to/file.css: { 属性 }

参数说明：

参数说明可选值默认
typeCSS 类型，影响加载顺序base、layout、component、themetheme
path/to/file.cssCSS 文件路径，相对于主题目录--
属性对文件的额外配置media: 'all'、weight: 10、group-

type 含义：

  • base：基础样式（HTML、reset、normalize 等），最先加载

  • layout：布局相关样式（grid、container）

  • component：组件样式（按钮、表单、卡片）

  • theme：主题覆盖样式（颜色、字体），通常最后加载

示例：

css:
  base:
    css/base.css: {}
  layout:
    css/layout.css: {}
  component:
    css/components.css: {}
  theme:
    css/style.css: {}

（3）、js

可选：定义 JS 文件。
语法：

js:
  path/to/file.js: { 属性 }

属性说明：

参数说明可选值
minified指示文件已压缩true / false
weight加载顺序（数字越小越先加载）整数
defer是否使用 defer 属性true / false
async是否使用 async 属性true / false

示例：

js:
  js/script.js: {}
  js/extra.js: { minified: true, weight: 5 }

（4）、dependencies

  • 可选：指定库依赖关系。

  • 作用：

    • 保证某些库或核心 JS 先加载

    • 防止 $ 或 Drupal 未定义报错

  • 常见值：

    • core/drupal → 提供 Drupal 对象

    • core/jquery → 提供 $

    • core/jquery.once → 提供 Drupal 的 once() 方法

    • core/drupalSettings → 提供 drupalSettings 对象

示例：

dependencies:
  - core/drupal
  - core/jquery
  - core/jquery.once
  - core/drupalSettings

（5）、完整标准示例

global-styling:
  css:
    base:
      css/base.css: {}
    layout:
      css/layout.css: {}
    component:
      css/components.css: {}
    theme:
      css/style.css: {}
  js:
    js/script.js: {}
  dependencies:
    - core/drupal
    - core/jquery
    - core/jquery.once
    - core/drupalSettings

可扩展示例（按页面或模块区分）：

homepage:
  css:
    theme:
      css/homepage.css: {}
  js:
    js/homepage.js: {}
  dependencies:
    - mytheme/global-styling

slider:
  css:
    theme:
      css/slider.css: {}
  js:
    js/slider.js: {}
  dependencies:
    - core/drupal
    - core/jquery

（6）、 Drupal 行为加载注意事项

在 js/script.js 中写行为时，要确保依赖库正确：

(function ($, Drupal) {
  Drupal.behaviors.mythemeBehavior = {
    attach: function (context, settings) {
      console.log('MyTheme JS loaded!');
    }
  };
})(jQuery, Drupal);

⚠️ 如果报 Drupal is not defined，说明 core/drupal 没被依赖或加载顺序不对。

（7）、最佳实践

  • 全局样式使用 global-styling 库，在 info.yml 全局加载

  • 组件/页面特定库单独写库名，通过 Twig attach

  • 确保依赖正确，尤其是 core/drupal、jquery

  • CSS 按层级分类：base → layout → component → theme

  • JS 使用 Drupal behaviors，避免冲突和重复绑定。

搜索

文章分类

热门文章