Drupal8 主题介绍

主题是定义视图层的文件的集合。您还可以在一个主题上创建一个或多个“子主题”或变体。需要配置 主题名.info.yml 文件。

主题工作流程

Drupal8主题工作流程

主题位置

必须将主题放置在Drupal项目目录下的“themes”文件夹中,Drupal核心主题(例如Bartik和Seven)位于Drupal项目目录下的core / themes文件夹中。

  • 官方推荐
    将贡献的主题(第三方主题)放在名为 “ contrib” 的子文件夹中,而将自己的主题放在名为 “ custom” 的文件夹中。

    每个单独的主题都包含在以主题本身命名的目录中。例如 ** fluffiness/**。名称必须全部小写,以字母开头,并使用下划线(_)代替空格。

  • Drupal安装的(部分)结构如下所示:

|-core
|  |-modules
|  |-themes
|  |  |-bartik
|  |  |-seven
..
|-modules
|-themes
|  |-contrib
|  |  |-zen
|  |  |-basic
|  |  |-bluemarine
|  |-custom
|  |  |-fluffiness

主题文件夹结构

典型主题文件夹结构中找到的文件和文件夹的示例:

fluffiness
  |-fluffiness.breakpoints.yml
  |-fluffiness.info.yml
  |-fluffiness.libraries.yml
  |-fluffiness.theme
  |-config
  |  |-install
  |  |  |-fluffiness.settings.yml
  |  |-schema
  |  |  |-fluffiness.schema.yml
  |-css
  |  |-style.css
  |-js
  |  |-fluffiness.js
  |-images
  |  |-buttons.png
  |-logo.svg
  |-screenshot.png
  |-templates
  |  |-maintenance-page.html.twig
  |  |-node.html.twig

常见主题文件的描述(*代表主题名)

*.info.yml
主题必须包含 *.info.yml文件才能定义主题。 *.info.yml文件尤其定义了元数据,库和块区域。这是主题中唯一需要的文件。

*.libraries.yml
该 *.libraries.yml文件是用来定义JavaScript和CSS库,可以通过主题加载。

*.breakpoints.yml
断点定义了响应式设计需要更改的位置,以响应不同的设备。断点在 *.breakpoints.yml文件中定义。

*.theme
*.theme文件是一个PHP文件,其中包含输出的所有条件逻辑和数据(预处理)。它还可以扩展基本主题设置。创建高级主题设置。

CSS/
最好将.css文件存储在“ css”子文件夹中。Drupal 8核心主题遵循SMACSS样式指南来组织CSS文件。要使主题加载CSS文件,必须在 *.libraries.yml文件中定义它们,并且可以在 *.info.yml文件中覆盖或删除它们。

js /
特定于主题的JavaScript文件存储在“ js”文件夹中。要使主题加载JavaScript文件,必须在 *.libraries.yml文件中定义它们。

images/
优良作法是将图像存储在“images”子文件夹中。

screenshot.png
如果在主题文件夹中找到screenshot.png文件,那么它将在“外观”页面上使用。或者,您可以在 *.info.yml文件中定义屏幕截图。

logo.svg
如果在主题文件夹中找到了主题徽标的SVG矢量文件,则可以在网站标题中使用它。徽标也可以在上载。Appearance > Settings

templates/
模板提供HTML标记和一些表示逻辑。与Drupal 7相反,在Drupal 8中,模板文件(*.html.twig文件)必须存储在“ templates”子文件夹中。如果遵循特定的命名约定,则Drupal将用您提供的模板替换默认的核心模板,从而允许您覆盖默认的标记。您还可以在子文件夹中组织模板,例如,”templates/block” 中的所有块模板以及”templates/views”中的所有视图模板。

核心主题Bartik文件夹结构

bartik
  |-bartik.breakpoints.yml
  |-bartik.info.yml
  |-bartik.libraries.yml
  |-bartik.theme
  |-color
  |  |-color.inc
  |  |-preview.css
  |  |-preview.html
  |  |-preview.js
  |-config
  |  |-schema
  |  |  |-bartik.schema.yml
  |-css
  |  |-colors.css
  |  |-layout.css
  |  |-maintenance-page.css
  |  |-print.css
  |-images
  |  |-add.png
  |  |-required.svg
  |  |-tabs-border.png
  |-logo.svg
  |-screenshot.png
  |-templates
  |  |-block--search-form-block.html.twig
  |  |-block--system-branding-block.html.twig
  |  |-block--system-menu-block.html.twig
  |  |-block.html.twig
  |  |-comment.html.twig
  |  |-field--taxonomy-term-reference.html.twig
  |  |-maintenance-page.html.twig
  |  |-node.html.twig
  |  |-page.html.twig
  |  |-status-messages.html.twig

Drupal8 主题开发

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

要创建Drupal 8主题,您需要首先创建一个 主题名.info.yml文件,该文件向Drupal提供有关您主题设计的元数据。注意,将文件中的类型(“ type”)设置为“ theme”。

创建一个 主题名.info.yml 文件

主题文件夹的根目录中创建 主题名.info.yml 文件。该文件夹应与 .info.yml 文件具有相同的名称。

注意: YAML文件结构写作规范

案例

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

键值对

  • name (名称(必填))
    易读的名称。这将显示在激活主题的“外观”页面上。
    name: Fluffiness
  • type (类型(必填))
    指示扩展名的类型,即“module”,“theme”或“profile”。对于主题,应始终将其设置为“theme”。此值区分大小写。
    type: theme
  • description (说明(可选))
    描述,显示在“外观”页面上。
    description: 一个有灰色和蓝色两种额外可爱的Drupal主题.
  • package (包装(可选))
    指定一个“包”,使您可以将主题分组在一起。
    package: Core
  • core (核心(必填))
    指定主题兼容的Drupal核心的版本。
    core: 8.x
  • php (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 (基本主题(推荐))
    通过将主题指定为基本主题,主题可以从另一个主题继承资源。–它能让你的主题在继承核心主题时,主题修改更容易。
    base theme: classy
  • hidden (隐藏(可选))
    指是否从“外观”页面隐藏主题,以便无法通过UI启用/禁用主题。
    hidden: true
  • engine (引擎(可选))
    主题引擎. 默认为”twig”.
    engine: twig
  • logo (品牌图标(可选))
    在8.6.x中引入
    品牌图标相对于主题文件的路径。默认情况下,Drupal将在主题文件夹的根目录中查找名为“ logo.svg”的文件,并将其用作主题的品牌图标
    logo: images/logo.png
  • screenshot (主题展示缩略图(可选))
    主题展示缩略图相对于主题文件的路径。主题展示缩略图应以宽588像素和高438像素的格式显示。默认情况下,Drupal将在主题文件夹的根目录中查找名为“ screenshot.png”的文件,并将其用作“外观”页面上的主题图像。
    screenshot: fluffiness.png
  • regions (区域(可选))
    主题区域列表。(请注意,区域键前面没有破折号。)content需要一个区域。阅读有关将区域添加到主题的更多信息
    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 (样式表删除(不建议使用))
    其他模块或主题的样式表列表,可从处于活动状态的所有页面中删除。每个值都必须是相对于docroot的完整路径,以在存在多个同名文件时解决歧义。如果文件是属于模块或主题的库的一部分,@module_or_theme_name则可以使用表单中的令牌代替完整路径。请注意,在使用令牌时,必须用引号将其引号,因为“ @”是YAML中的保留指示符。
  • 注意:*该密钥已被弃用,并将在Drupal 9中删除。在大多数情况下,应使用
    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

主题添加区域

  • 将区域元数据添加到 主题名.info.yml 文件。
  • 在新添加的主题中添加并编辑 page.html.twig 文件。

注意: 如果您在主题中声明了任何区域,甚至仅声明了一个,所有默认区域都将不再应用,你需要声明将要使用的所有区域。

将区域添加到 主题名.info.yml 文件

首先在 主题名.info.yml文件中声明所有新区域。regions像这样将区域声明为键的子级(域键应为字母数字,并可以包含下划线(_)):

regions:
  header: 'Header'
  content: 'Content'
  footer: 'Footer'

将区域添加到模板

为了使区域显示放置在其中的任何内容,您需要确保新区域也已添加到 主题名.info.yml文件中。区域将表示为Twig变量,其名称与 主题名.info.yml文件中使用的键相对应.

例子

header: 'Header'

…会变成:

{{ page.header }}

它们的行为与任何其他Twig变量一样,并且可以包装在对您的用例有意义的任何标记中。

  • 默认区域

有关默认区域的列表,请查阅page.html.twig文档

  1. page.header
  2. page.primary_menu
  3. page.secondary_menu
  4. page.highlighted
  5. page.help (动态帮助文本,主要用于管理页面)
  6. page.content (当前页面的主要内容)
  7. page.sidebar_first
  8. page.sidebar_second
  9. page.footer
  10. page.breadcrumb

如果您的主题未声明任何区域,Drupal将采用这组默认值。

Drupal主题添加样式表(CSS)和JavaScript(JS)

Drupal使用高级原则:仅当您告诉Drupal应该加载资产时,才加载资产(CSS或JS)。Drupal不会在每个页面上加载所有资产,因为它会降低前端性能。

  • 加载CSS或JS资源过程:
  1. 使用正确的命名约定和文件结构将CSS或JS保存到文件中。
  2. 定义一个“库”,主题注册这些CSS / JS文件。
  3. 通过预处理功能中的render元素将库“附加” 到所有页面,特定的Twig模板或目标特定的页面。
  • 定义库

定义一个与主题名同名的 主题名.libraries.yml 文件,文件中的每一个条目都描述一个资源文件,如下所示:

# fluffiness.libraries.yml
cuddly-slider:
  version: 1.x
  css:
    theme:
      css/cuddly-slider.css: {}
  js:
    js/cuddly-slider.js: {}
  • 声明依赖

要声明依赖关系,所需的库以resource / library的形式声明。对于核心库,资源是core,对于其他库,资源是模块名称或主题名称。所以,如果 new_library依赖于jQuery的核心, my_library中声明my_theme,并my_library宣布my_module,你会声明依赖关系:

# fluffiness.libraries.yml
new_library:
  js:
    js/new_libary.js: {}
  dependencies:
    - core/jquery
    - my_module/my_library
    - my_theme/my_library
  • 声明全局库文件

大多数主题使用一些全局样式资源库,需要在激活该主题的每个页面上加载的样式表(CSS文件)。一些全局js 资源库也是一样,需要在激活该主题的每个页面上加载js资源库。

# fluffiness.libraries.yml (multiple libraries can be added to a libraries.yml file, these would appear below the cuddly-slider libraries added earlier)
global-styling:
  version: 1.x
  css:
    theme:
      css/layout.css: {}
      css/style.css: {}
      css/colors.css: {}
global-scripts:
  version: 1.x
  js: 
    js/navmenu.js: {}

将global-style / global-scripts库添加到 主题名.libraries.yml 文件libraries中:

#fluffiness.info.yml
name: Fluffiness
type: theme
description: 'A cuddly theme that offers extra fluffiness.'
core: 8.x
# by adding global-styling and global-scripts here, the css/js files in the library become 
# available to every page presented by the theme
libraries:
  - fluffiness/global-styling
  - fluffiness/global-scripts
base theme: classy
regions:
  header: Header
  content: Content
  sidebar_first: 'Sidebar first'
  footer: Footer

定义库:选项和详细信息

以下属性是可选的,并且按CSS资产应用。

CSS相关属性

属性名 描述 参数
attributes 可选属性。已知用例引导CDN。 { attributes: { crossorigin: anonymous } }
browsers 基于浏览器有条件地加载资源。
注意,这个方法使用了条件注释,这在IE10及以上版本中是不支持的.
{ browsers: { IE: ‘lte IE 9’, ‘!IE’: false } }
group 按组汇总资源。
默认值:资产所在的SMACSS组。
很少使用
media 媒体类型. { media: print }
minified 资源是否已经压缩.
Default: false
{ type: external, minified: true }
preprocess 是否应该聚合资源.
Default: true
{ preprocess: false }
type 资源的来源.
Default: file
{ type: external, minified: true }
weight 调整相对于其他资源的顺序(在同一个SMACSS组中).
Default: 0. Use a numeric between -50 to +50.
{ weight: 1 }

JS 相关属性

属性名 描述 参数
attributes 额外的脚本属性。 { type: external, attributes: { async: true } }
browsers 基于浏览器有条件地加载资源。注意,这个方法使用了条件注释,这在IE10及以上版本中是不支持的. { browsers: { IE: ‘lte IE 9’, ‘!IE’: false } }
preprocess 是否应该聚合资源。
Default: true
{ preprocess: false }
type 资源的来源
Default: file
{ type: external, minified: true }
weight 不鼓励使用依赖项。
调整相对于其他资产的顺序。必须是负的
{ weight: -1 }

CDN /外部托管库

angular.angularjs:
  remote: https://github.com/angular
  version: 1.4.4
  license:
    name: MIT
    url: https://github.com/angular/angular.js/blob/master/LICENSE
    gpl-compatible: true
  js:
    https://ajax.googleapis.com/ajax/libs/angularjs/1.4.4/angular.min.js: { type: external, minified: true }

如果希望使用与请求页面相同的协议来请求外部文件,请指定相对于协议的URL:

js:
   //ajax.googleapis.com/ajax/libs/angularjs/1.4.4/angular.min.js: { type: external, minified: true }

或者,如果您想添加CSS,下面是集成Font Awesome的示例:

font-awesome:
  remote: https://fortawesome.github.io/Font-Awesome/
  version: 4.5.0
  license:
    name: MIT
    url: https://fortawesome.github.io/Font-Awesome/license/
    gpl-compatible: true
  css:
    theme:
      https://maxcdn.bootstrapcdn.com/font-awesome/4.5.0/css/font-awesome.min.css: { type: external, minified: true }

具有自定义属性的Bootstrap CDN CSS的示例。

bootstrap-cdn:
  remote: getbootstrap.com
  version: 4.0
  license:
    name: MIT
    url: https://github.com/twbs/bootstrap/blob/master/LICENSE
  css:
    theme:
      'https://maxcdn.bootstrapcdn.com/bootstrap/4.0.0/css/bootstrap.min.css':
        type: external
        minified: true
        attributes:
          crossorigin: anonymous
          integrity: "sha384-Gn5384xqQ1aoWXA+058RXPxPg6fy4IWvTNh0E263XmFcJlSAwiGgFAW/dAiS6JXm"

本博客所有文章除特别声明外,均采用 CC BY-SA 3.0协议 。转载请注明出处!

Drupal8 基本介绍 下一篇