AB
AB
AiBoss

すべてのカテゴリ

チュートリアル

Solo

チュートリアル

用 Solo 创建 Drupal 子主题并自定义站点外观

Solo 是 Drupal 的一款 contributed 主题，自带颜色、布局、菜单与区域设置，并附带一个可直接复制的子主题起始包。本文讲清如何用 Composer 安装 Solo、用 Drush 一条命令或手工十步生成自己的子主题、替换 logo 与 favicon、显示站点标语、改写页脚版权信息，以及按区域挑选菜单模板。

Solo 是 Drupal 的一款 contributed 主题，它把颜色、布局、菜单和区域设置都存进站点配置，因此主题更新不会覆盖你调好的外观。对大多数站点来说，直接用 Solo 就够了，不需要子主题；只有当你需要覆盖 Twig 模板时，才需要派生一个子主题。Solo 自带一个子主题起始包，可以复制改名，也可以用 Drush 命令一次生成。本文按实际操作顺序讲清安装、建子主题、改 logo 与 favicon、显示标语、定制页脚版权、挑选菜单模板这几件事。如果你只是想先了解这个主题的整体能力，可以先看 Solo 的工具页，再回到本文动手。

需要说明的是，主题的版本支持范围、Drush 命令的可用性、设置页面的字段名称都可能随版本变化，涉及具体版本号与功能细节时，请以官网当前信息为准。

准备工作

开始之前，先确认环境满足以下条件：

  • Drupal 版本：Solo 支持 Drupal 10.1 及更高版本，也支持 Drupal 11 与 Drupal 12。低于 10.1 的站点无法使用。
  • Composer：主题通过 Composer 安装，需要在项目根目录执行命令。
  • Drush：清缓存、安装主题、生成子主题都用到 Drush。用 drush solo:subtheme 这条快捷命令需要 Drush 12 或更高版本，并且启用 Solo Utilities 1.0.10 或更高版本。
  • 站点管理员权限：安装主题、修改主题设置、配置区块都需要相应权限。
  • 文件系统写入权限：Composer 会把主题放进 web/themes/contrib/solo，自定义代码与上传文件会写入 sites/*/files/solo/，这些目录需要可写。

另外要建立一个基本认识：不要直接修改 Solo 主题自身的文件。下一次更新会把它们整体替换掉。所有自定义都应通过主题设置界面、Custom Code 区域，或者你自己的子主题来完成。

操作步骤

第一步：用 Composer 安装 Solo

在项目根目录执行：

composer require drupal/solo

Composer 会把主题放到 web/themes/contrib/solo。安装完成后进入后台外观页面：

your-site-domain/admin/appearance

找到 Solo，点击「Install and set as default」，把它安装并设为默认主题。

第二步：决定是否需要子主题

这一步不是必做项，但需要先判断清楚：

  • 如果你只需要改颜色、布局、菜单、区域，以及追加一些 CSS 和 JavaScript，不需要子主题。这些设置都存在站点配置里，更新 Solo 不会丢失。
  • 如果你需要覆盖 Twig 模板，才需要子主题。子主题让你在保留原主题完整性的前提下做定制，原主题仍可正常接收更新。

追加自定义 CSS 与 JavaScript 的位置在主题设置的 Global Site Settings > Custom Code 下，有三个入口：CSS Injector、CSS Dynamic、JavaScript Dynamic。这些内容会随设置一起保存，或者写入 sites/*/files/solo/ 下的文件，不会写进 Solo 自己的目录。

第三步：用 Drush 一条命令生成子主题

如果环境满足 Drush 12 以上、Solo Utilities 1.0.10 以上，这是最快的做法。假设子主题机器名是 my_theme：

drush solo:subtheme my_theme

这条命令会把 Solo 自带的起始子主题复制到 themes/custom/my_theme，并把其中所有文件名、命名空间、类名、函数名、库名和标签一并改名。接着安装并设为默认：

drush theme:install my_theme
drush config:set system.theme default my_theme -y

机器名有格式约束：只能用小写字母、数字和下划线，必须以字母开头，最长 50 个字符，且不能与已有的主题、模块或安装配置重名。

第四步：手工创建子主题（不使用快捷命令时）

下面以创建一个名为 fun 的子主题为例，逐步说明。起始包是 Solo 目录下的 solo_subtheme。

Step 1：复制并重命名主题文件夹

找到 ../web/themes/contrib/solo/ 下的 solo_subtheme 文件夹，整体复制到 ../web/themes/custom/，并把文件夹改名为 fun。

Step 2：重命名三个配置文件

进入新建的 fun 文件夹，把以下三个文件改成与新主题名一致：

  • solo_subtheme.info.yml 改为 fun.info.yml
  • solo_subtheme.libraries.yml 改为 fun.libraries.yml
  • solo_subtheme.theme 改为 fun.theme

Step 3：更新主题信息文件

打开 fun.info.yml，把 name 改为 fun，写一段简短描述说明这个主题的用途。然后找到库引用那一行：

- solo_subtheme/solo-subtheme-global

改为：

- fun/fun-global

Step 4：更新库配置

打开 fun.libraries.yml，把 solo-subtheme-global: 改为 fun-global:。

Step 5：按需重命名样式文件

如果你希望样式与脚本文件也带上自己的主题名，可以在对应目录里重命名，并同步修改 fun.libraries.yml 中对应的两行：

  • CSS 文件位于 ../web/themes/custom/fun/css，把 solo-subtheme-style.css 改名。
  • JS 文件位于 ../web/themes/custom/fun/js，把 solo-subtheme-script.js 改名。

Step 6：更新设置文件

进入 ../web/themes/custom/fun/config/install/，把 solo_subtheme.settings.yml 重命名为 fun.settings.yml。

Step 7：更新 Schema 文件

进入 ../web/themes/custom/fun/config/schema/，把 solo_subtheme.schema.yml 重命名为 fun.schema.yml，然后打开它，把这一段：

solo_subtheme.settings:
  type: mapping
  label: 'Solo sub-theme settings'
  mapping:

改为：

fun.settings:
  type: mapping
  label: 'Fun sub-theme settings'
  mapping:

Step 8：更新主题文件

打开 fun.theme，做两处替换。第一处是命名空间引用：

use Drupal\solo_subtheme\Hook\SoloSubthemeHooks;

改为：

use Drupal\fun\Hook\SoloSubthemeHooks;

第二处是函数名，把 solo_subtheme_theme_suggestions_block_alter 改为 fun_theme_suggestions_block_alter。

Step 9：更新 Hook 类（Solo 1.0.35 及以后）

从 Solo 1.0.35 起，子主题里还包含一个 PHP 类文件 src/Hook/SoloSubthemeHooks.php。这一步如果跳过，会触发致命错误「Cannot redeclare class Drupal\solo_subtheme\Hook\SoloSubthemeHooks」，因为 Drupal 会按你的主题名去找这个类。

打开 ../web/themes/custom/fun/src/Hook/SoloSubthemeHooks.php，把命名空间：

namespace Drupal\solo_subtheme\Hook;

改为：

namespace Drupal\fun\Hook;

再找到这一行：

$suggestion = str_replace('solo_', 'solo_subtheme_', $suggestion);

改为：

$suggestion = str_replace('solo_', 'fun_', $suggestion);

同样的规则适用于另一种情况：当你从更新版本的 Solo 里把新文件复制进已有的子主题时，也要按同样方式把文件里的 solo_subtheme 改名。

Step 10：检查是否有遗漏

在 fun 文件夹内执行下面这条命令，它应当没有任何输出：

grep -rn "solo_subtheme" --exclude=README.md .

如果有输出，说明还有残留的旧名称，逐条改掉。确认无误后清缓存并安装主题：

drush cr

然后到 your-site-domain/admin/appearance 安装你的新主题。

第五步：更换 Logo

进入 your-drupal-site-name/admin/appearance/settings/solo，取消勾选「Use the logo supplied by the theme」，然后上传自己的 logo 图片，并在「Path to custom logo」字段填入 logo 的位置，保存。

注意 Solo 不限制 logo 尺寸，所以上传前应先把图片处理成你希望最终呈现的大小。如果你用的是子主题，需要先在 Solo 主题里停用 logo，才能在子主题里上传自己的 logo。

第六步：更换 Favicon

Favicon 是浏览器标签页上的小图标。同样进入 your-drupal-site-name/admin/appearance/settings/solo，取消勾选「Use the favicon supplied by the theme」，上传自定义图标，在「Path to custom icon」字段填入路径并保存。

第七步：显示站点标语

如果希望在站点名称下方显示一句标语，进入：

your-drupal-site-name/admin/structure/block

在 header 区域会看到两个区块：User account menu 和 Site branding。点击 Site branding 旁边的 configure，勾选 Site Slogan 即可。

第八步：定制页脚版权与署名

进入 your-drupal-site-name/admin/appearance/settings/solo，展开 Copyright & Credit 区域。这里的 %year% 占位符会每年自动更新，因此版权年份不会过期。

Footer Link、Footer Label、Footer Link Text 三个字段配合使用，可以拼出一条完整的署名行。例如：

  • Footer Label 填「Developed & Designed by」
  • Footer Link Text 填公司名称
  • Footer Link 填链接地址

如果你更想用一个字段搞定，勾选「Use a single formatted text field for copyright and credit」。四个字段会被一个格式化文本字段取代，你可以在里面写整行页脚内容，支持链接和基础 HTML，适合放许可证号之类的法律文本。%year% 在这个字段里同样有效。

如果希望页脚更干净、不显示版权文字，进入同一页面展开 Copyright & Credit 区域，把文本字段清空即可。

第九步：按区域选择菜单模板

Drupal 菜单自带默认设计，适合标准的多级横向导航。但站点不同区域往往需要不同的菜单样式，Solo 按菜单位置和行为提供了多个模板：

  • 左侧栏菜单：../solo/templates/navigation/menu--sidebar-first.html.twig
  • 右侧栏菜单：../solo/templates/navigation/menu--sidebar-second.html.twig
  • Primary Menu 区域：../solo/templates/navigation/menu--primary-menu.html.twig
  • Primary Sidebar Menu 区域：../solo/templates/navigation/menu--primary-sidebar-menu.html.twig
  • 用户账户菜单：../solo/templates/navigation/menu--account.html.twig

对于简单的单级菜单（例如页脚常见的菜单），使用侧栏模板 ../solo/templates/navigation/menu--sidebar-first.html.twig 即可。

对于需要下拉子菜单、并且要适配不同屏幕宽度的复杂菜单，Solo 提供了几种专门模板：

  • 横向菜单，悬停下拉：../solo/templates/navigation/menu--responsive-menu-template-hover.html.twig
  • 横向菜单，点击下拉：../solo/templates/navigation/menu--responsive-menu-template-click.html.twig

选用时按菜单所在区域和交互方式对照上表挑一个，再在子主题里覆盖对应模板文件。

一个完整示例

下面把前面的步骤串成一个可跑通的最小流程：为一个已有 Drupal 站点安装 Solo，并派生一个名为 fun 的子主题，最后改掉 logo 与页脚署名。

1. 安装主题

composer require drupal/solo

到 your-site-domain/admin/appearance 点击 Solo 的「Install and set as default」。

2. 生成子主题

如果 Drush 版本满足要求：

drush solo:subtheme fun
drush theme:install fun
drush config:set system.theme default fun -y
drush cr

如果不满足，就按第四步的 Step 1 到 Step 10 手工完成，最后执行：

grep -rn "solo_subtheme" --exclude=README.md .
drush cr

第一条命令应当没有输出，然后到外观页面安装 fun。

3. 换 logo

进入 your-drupal-site-name/admin/appearance/settings/solo，取消勾选「Use the logo supplied by the theme」，上传已按目标尺寸处理好的图片，在「Path to custom logo」填入路径，保存。

4. 写页脚署名

在同一页面展开 Copyright & Credit，勾选「Use a single formatted text field for copyright and credit」，在格式化文本字段里写入类似下面的内容：

© %year% Example Studio. All rights reserved.

保存后，页脚年份会随年份自动更新。

5. 验证

刷新前台页面，确认新主题生效、logo 已替换、页脚显示正确年份。再进入 your-drupal-site-name/admin/structure/block，检查各区域区块是否按预期显示。

注意事项

  • 不要改 Solo 自身文件：下一次更新会整体替换，改动全部丢失。自定义走主题设置、Custom Code 或子主题。
  • 子主题的 Hook 类必须改名：Solo 1.0.35 及以后，如果漏掉 src/Hook/SoloSubthemeHooks.php 里的命名空间与字符串替换，会直接触发致命错误，站点无法正常加载。
  • 从新版本复制文件进旧子主题时同样要改名：把 solo_subtheme 按你的主题名替换掉，否则会出现重复类或找不到类的错误。
  • 用 grep 做最后检查：grep -rn "solo_subtheme" --exclude=README.md . 必须无输出，这是判断改名是否彻底的最直接办法。
  • 机器名有格式限制：小写字母、数字、下划线，字母开头，最长 50 字符，且不能与已有主题、模块、安装配置重名。
  • logo 尺寸不受限制：Solo 不会帮你缩放，上传前自行处理好尺寸。
  • 子主题的 logo 需要先在 Solo 里停用：否则子主题里的 logo 设置不会生效。
  • 区域没有内容就不会出现在设置页：每个区域有各自的设置，空区域不会显示在 your-site-domain/admin/appearance/settings/solo 的设置页上。
  • 版本与命令可用性会变：Drupal 版本支持范围、Solo Utilities 的版本要求、Drush 命令的行为，请以官网当前信息为准。
戻る