73. 主题处理器theme_handler

主题处理器theme_handler与主题管理器theme.manager都是系统提供的服务，虽然一字之差但她们功能完全不同，主题管理器用于主题渲染和派发主题修改钩子，而主题处理器完成更为底层的工作，向上为主题管理器、初始化器等各主题相关组件提供基础功能支持，定义如下：

服务id：theme_handler

类：Drupal\Core\Extension\ThemeHandler

获取方法：\Drupal::service("theme_handler");

主要完成的工作是扫描查找文件系统中的主题扩展、理顺继承关系、添加主题info文件的默认项、初始化一些全局函数的静态变量值、判明主题是否应该显示在UI中等等；

主题处理器主要工作是向上层应用提供主题的扩展对象（该对象见下），上层组件有了扩展对象后就可以操作主题了。

 

主题相关名字：

以下是一些和主题相关的名字及其含义：

机器名：

又叫主题扩展名，全局唯一，是识别主题的唯一标识，来源于info文件的文件名，如“bartik.info.yml”那么机器名就是“bartik”，不能包含空格，正则为：/^[a-zA-Z_\x7f-\xff][a-zA-Z0-9_\x7f-\xff]*$/，有些特定名字虽然满足该正则，但不能被使用，如“template”；下文中除非特别说明，当提到主题名时均指机器名。

人类可读名：

在info文件中name项指定的名称，这可以和机器名不同也可不同，显示在UI中，能包括空格

目录名：

存放主题相关文件的目录名称，注意：主题的扫描查找实际上是在查找内容满足要求的以“.info.yml”后缀结束的文件（内容中必须有type属性），而不是依据目录结构信息，因此主题的目录名可以和机器名不同，但最佳实践应该相同，目录深度与结构不限，目录名不能使用：'src','lib','vendor','assets','css','files','images','js','misc','templates','includes','fixtures','Drupal',

这些目录在被扫描时会被跳过（可以利用这种特性隐藏多余的主题，不会对系统造成任何影响）

主扩展文件名：

默认为“机器名.扩展类型”，如“bartik.theme”、“search.module”，主扩展文件不是必须的，用于存放模块或主题需要的函数或定义常量，位于扩展根目录，是一个php文件，但并不以php做文件名后缀，如果存在则被默认加载。引擎主题是一个特殊情况，命名为“引擎名.engine”，如“twig.engine”。

 

扩展对象：

当扫描到一个合法的扩展时，系统会初始化一个扩展对象：

\Drupal\Core\Extension\Extension

该对象虽然在类定义中只有很少的属性，但却在初始化后从对象外部赋值了许多属性，见下，这些属性是公共的（public），该对象携带了扩展本身的所有信息，她是主题信息的承载者，初始化时：

$theme = new Extension($root, $type, $pathname, $filename);

四个参数分别是：

$root：drupal根路径，如“C:\root\drupal”没有后缀反斜杠

$type：扩展类型，来自info文件里面的type值

$pathname：info文件相对系统根目录的相对路径，如“core/themes/bartik/bartik.info.yml”

$filename：主扩展文件名，见前文描述，如“bartik.theme”，注意并非info文件的文件名

 

在主题扩展中常用的扩展对象属性如下（这里以$theme指代扩展对象）：

$theme->type：扩展类型，主题是“theme”

$theme->info：从info文件里面解析出来的内容，附加了默认值

$theme->engine：该主题使用的模板引擎，默认为“Twig”

$theme->base_theme：直接基主题的机器名

$theme->libraries：info文件中声明的库

$theme->status：表示主题是否被安装，整数值，1为安装，0为未安装

$theme->owner：所用引擎的主扩展名，通常值为：“core/themes/engines/twig/twig.engine”

$theme->prefix：所用引擎前缀，通常为“twig”

$theme->base_themes：是一个数组，键名是基主题机器名，键值为基主题的人类可读名，如果指定了基主题但其不存在，那么值为NULL，元素顺序代表继承顺序，第一个元素是根基主题，最后一个元素是直接基主题

$theme->base_theme：是一个字符串值，直接基主题机器名，如果没有基主题则该属性不存在

$theme->sub_themes：是一个数组，代表所有子主题，键名是子主题机器名，键值为子主题人类可读名，元素顺序没有意义

$theme->required_by：数组，元素为全部需要该主题的主题（子主题）

$theme->requires：数组，该主题需要的主题（基主题）

$theme->origin：内部为排序目的使用，用于跟踪扩展扫描的起始目录

$theme->subpath：内部为排序目的使用，加上$theme->origin就是相对于系统根目录的子目录

$theme->sort：显示主题时的排序值

$theme->root：系统根路径，如“C:\root\drupal”

$theme->pathname：info文件相对系统根目录的相对路径，如“core/themes/bartik/bartik.info.yml”

$theme->$filename：主扩展文件名，值如“bartik.theme”，注意并非info文件的文件名

 

该扩展对象中，除类定义的方法外，还可以调用info文件初始化的\SplFileInfo对象上的方法

下文提到扩展对象时均是指该对象。

 

主题关键配置项与状态值：

在了解主题处理器前我们应该先知道和主题相关的主要配置和信息储存。

\Drupal::service("config.factory")->get('system.theme')->get(“admin”);

储存后台管理主题的机器名

\Drupal::service("config.factory")->get('system.theme')->get(“default”);

储存前端默认主题的机器名

\Drupal::service("config.factory")->get('core.extension')->get('theme');

储存所有被安装的主题，数组值，键名为主题机器名，键值为0

\Drupal::state()->get("system.theme.data");

储存所有被安装的主题，数组值，键名为主题机器名，键值为对应的扩展对象

\Drupal::state()->get("system.theme.files");

储存系统所有主题的info文件路径，包括没有启用的主题，数组值，键名为机器名，键值为相对系统根目录的路径，如：core/themes/bartik/bartik.info.yml

\Drupal::state()->get("system.theme_engine.files");

同上，只是储存模板引擎主题的机器名和路径，默认为[twig=>‘core/themes/engines/twig/twig.info.yml’]

\Drupal::cache('bootstrap')->get('system_list')

缓存主题数据，值为两个元素的数组，键名theme的值为\Drupal::state()->get("system.theme.data")的内容，键名filepaths的值为多个['type' => 'theme','name' => ‘主题机器名’,'filepath' => “info文件路径”,]元素构成的数组，如：['type' => 'theme','name' => ‘bartik’,'filepath' => “core/themes/bartik/bartik.info.yml”,]

 

主题处理器方法简述：

\Drupal::service("theme_handler")->getDefault();

得到前端主题机器名

setDefault($name);

设置前端主题，参数为机器名，必须是已经安装过的主题，她不会失效如何缓存，所以该方法只应该系统使用内部使用

listInfo()

列出所有已经安装的主题，返回数组值，键名为主题机器名，键值为对应的扩展对象，以扩展目录名作为排序依据（见\Drupal\Core\Extension\ExtensionDiscovery::sort），在很多使用情况下这个顺序是无意义的

addTheme(Extension $theme)

添加一个扩展对象到已安装主题列表

refreshInfo()

重新扫描文件系统，重新构建已经安装主题列表

rebuildThemeData()

扫描文件系统，返回所有存在的主题，包括未安装的主题，理顺主题的继承关系以及设置相关属性变量，返回一个数组，键名为主题机器名，键值为对应的扩展对象。

getBaseThemes(array $themes, $theme)

在一个主题集中查找一个主题的所有基主题，返回一个数组，键名是基主题机器名，键值为基主题的人类可读名，如果指定了基主题但其不存在，那么值为NULL，元素顺序代表继承顺序，第一个元素是根基主题，最后一个元素是直接基主题。

getName($theme)

根据一个主题的机器名返回人类可读名

getThemeDirectories()

得到所有已经安装主题的绝对路径，返回数组，键名为机器名，键值为路径名（不带文件名），如：C:\root\drupal/core/themes/bartik

themeExists($theme)

判断主题是否存在于已安装主题中

getTheme($name)

通过主题机器名取得扩展对象

hasUi($name)

判断主题是否应该在ui中出现，如果info信息中'hidden'为真，那么不出现，如果省略该项设置，默认出现，如果是默认的管理主题或前端主题，那么强制出现

 

此外安装卸载方法虽然在8.x版本中存在，但你不应该使用，将在9.0版本中移除，使用安装服务代替

 

主题info文件的附加默认值：

主题info文件被系统读取时会附加默认值，采用数组“+”操作，由此可见在没有指定选项时她会是什么样子，默认值被定义在主题处理器中，如下：

$defaults = [
      'engine' => 'twig',
      'base theme' => 'stable',
      'regions' => [
        'sidebar_first' => 'Left sidebar',
        'sidebar_second' => 'Right sidebar',
        'content' => 'Content',
        'header' => 'Header',
        'primary_menu' => 'Primary menu',
        'secondary_menu' => 'Secondary menu',
        'footer' => 'Footer',
        'highlighted' => 'Highlighted',
        'help' => 'Help',
        'page_top' => 'Page top',
        'page_bottom' => 'Page bottom',
        'breadcrumb' => 'Breadcrumb',
      ],
      'description' => '',
      'features' =>  [
                   'favicon',
                   'logo',
                   'node_user_picture',
                   'comment_user_picture',
                   'comment_user_verification',
  ],
      'screenshot' => 'screenshot.png',
      'php' => DRUPAL_MINIMUM_PHP,
      'libraries' => [],
];

由于采用数组后附加操作，所以当不想要某默认值时，需要自定义该值，比如不想要基主题那么需要明确定义为FALSE，否则默认为'stable'主题。

默认值被附加后，会派发system_info修改钩：

$moduleHandler->alter('system_info', $theme->info, $theme, $type);

这里 $theme是前文提到的\Drupal\Core\Extension\Extension对象，info是对象外附加的公共属性，内容是应用了默认值的info文件内容数组，$type值为'theme'，模块可以通过hook_system_info_alter()去修改她，接收三个参数，第一个和第三个参数实际上是包含在Extension对象中的，由于php对象默认是按引用传递所以模块可以修改该对象（修改$info数组参数将无作用，她不是引用传递），由于派发钩子的原因，意味着先安装的模块可以修改后面正在安装主题的info文件

 

主题的继承：

可以一层一层的继承下去，层数不限，但只有一个直接基主题（父主题），也就是“单基多层继承”，这和php类继承类似。

drupal是可以使用多个主题引擎的，如果在主题继承链中，子主题和基主题指定了不同的主题引擎，那么将以根基主题的设置为准。

当声明了基主题后，就自动声明了基主题依赖，在info文件中不必手动指定

 

补充：

  1. 在info文件里面注意空格的问题，如“'base theme'”项写成了“'base  theme'”将失去作用，那影响了数组键名，在建立info文件时最好复制修改，避免这些小问题。
  2. 在主题处理器中使用了一些编程技巧加快系统性能，如：为主题初始化drupal_get_filename全局函数，通过drupal_static函数设置中心静态属性等，有兴趣可以自行深究

 

 

 

 

 

 

 

本书共161小节。


评论 (0)