drupal-frontend

Drupal 前端开发

概述

启用专家级 Drupal 前端开发能力。为 Drupal 8、9、10 和 11+ 提供有关主题开发、Twig 模板、预处理、响应式设计和资源管理的全面指导。

何时使用此技能

在处理以下工作时调用此技能：

• 主题开发：创建或自定义 Drupal 主题
• Twig 模板：编写或修改 .twig 模板文件
• 预处理：为模板实现预处理函数
• 模板建议：添加自定义模板命名模式
• CSS/JS 库：管理主题资源及其依赖项
• 响应式设计：实现断点和移动优先设计
• 渲染系统：了解 Drupal 的渲染流程
• 主题钩子：实现与主题相关的钩子和修改

核心能力

1. 主题开发

构建结构规范且符合标准的完整 Drupal 主题：

快速入门工作流：

1. 使用 assets/theme-template/ 中的主题模板作为起点
2. 将 THEMENAME 替换为主题的机器名
3. 将 THEMELABEL 替换为易读的名称
4. 自定义模板、CSS、JS 和库
5. 启用主题，并通过外观界面进行配置

主题组件：

• .info.yml - 主题元数据和配置
• .libraries.yml - CSS/JS 库定义
• .theme - 预处理函数和主题逻辑
• .breakpoints.yml - 响应式断点
• templates/ - Twig 模板文件
• css/ - 样式表
• js/ - JavaScript 文件

参考文档：

• references/theming.md - 完整的主题指南及示例

2. Twig 模板系统

掌握 Twig 语法和 Drupal 专用扩展：

Twig 基础：

• {{ variable }} - 输出变量
• {% if/for/set %} - 控制结构和逻辑
• {# comment #} - 注释和文档
• {{ var|filter }} - 对变量应用过滤器
• {% extends %} - 模板继承
• {% block %} - 定义可重写的区块

Drupal 专用 Twig：

• {{ 'Text'|t }} - 翻译字符串
• {{ attach_library('theme/library') }} - 加载 CSS/JS
• {{ url('route.name') }} - 生成 URL
• {{ path('route.name') }} - 生成路径
• {{ file_url('public://image.jpg') }} - 文件 URL
• {{ content|without('field') }} - 排除字段

常见模板：

• page.html.twig - 页面布局结构
• node.html.twig - 节点显示
• block.html.twig - 区块渲染
• field.html.twig - 字段输出
• views-view.html.twig - Views 输出

3. 预处理函数

在渲染前修改模板变量：

预处理模式：

function THEMENAME_preprocess_HOOK(&$variables) {
  // Add or modify variables
  // Access entities, services, configuration
  // Prepare data for templates
}

常见预处理钩子：

• hook_preprocess_page() - 页面级变量
• hook_preprocess_node() - 节点专属数据
• hook_preprocess_block() - 区块修改
• hook_preprocess_field() - 字段修改
• hook_preprocess_html() - HTML 文档

最佳实践：

• 将逻辑放在预处理中，将标记放在模板中
• 尽可能使用依赖注入
• 使用缓存上下文/标签进行适当缓存
• 为复杂的预处理编写文档

4. 模板建议

为不同上下文提供特定模板：

建议模式：

page--front.html.twig                  # Homepage
page--node--{nid}.html.twig            # Specific node
page--node--{type}.html.twig           # Content type
node--{type}--{viewmode}.html.twig     # Type + view mode
block--{plugin-id}.html.twig           # Specific block
field--{entity}--{field}.html.twig     # Specific field

添加建议：

function THEMENAME_theme_suggestions_HOOK_alter(array &$suggestions, array $variables) {
  // Add custom suggestions
  $suggestions[] = 'custom__suggestion';
}

5. CSS 和 JavaScript 管理

高效组织和加载主题资源：

库定义：

# THEMENAME.libraries.yml
global-styling:
  version: 1.0
  css:
    base:
      css/base/reset.css: {}
    theme:
      css/theme/styles.css: {}
  js:
    js/custom.js: {}
  dependencies:
    - core/drupal

加载库：

• 全局：在 .info.yml 中定义
• 有条件地：在模板中使用 attach_library()
• 预处理：在预处理函数中附加

最佳实践：

• 将 CSS 分为多个层（基础、布局、组件、主题）
• 在生产环境中使用 CSS 聚合
• 尽量减少 JavaScript 依赖项
• 利用 Drupal 的资源库系统

6. 响应式设计

实现移动优先且易于访问的设计：

断点定义：

# THEMENAME.breakpoints.yml
THEMENAME.mobile:
  label: Mobile
  mediaQuery: 'screen and (min-width: 0px)'
  weight: 0

THEMENAME.tablet:
  label: Tablet
  mediaQuery: 'screen and (min-width: 768px)'
  weight: 1

THEMENAME.desktop:
  label: Desktop
  mediaQuery: 'screen and (min-width: 1024px)'
  weight: 2

移动优先方法：

1. 首先为最小屏幕进行设计
2. 针对更大的视口进行增强
3. 使用响应式图片
4. 在不同设备上进行测试
5. 遵循无障碍标准（WCAG）

开发工作流

创建新主题

1. 搭建主题框架：

   cp -r assets/theme-template/ /path/to/drupal/themes/custom/mytheme/
   cd /path/to/drupal/themes/custom/mytheme/
   
   # Rename files
   mv THEMENAME.info.yml mytheme.info.yml
   mv THEMENAME.libraries.yml mytheme.libraries.yml
   mv THEMENAME.theme mytheme.theme
   

2. 更新主题配置：

   • 编辑 mytheme.info.yml - 设置名称、区域和基础主题
   • 编辑 mytheme.libraries.yml - 定义 CSS/JS 库
   • 将 THEMENAME 替换为你的机器名
   • 将 THEMELABEL 替换为你的标签

3. 启用主题：

   ddev drush cr
   # Enable via UI at /admin/appearance or:
   ddev drush config:set system.theme default mytheme -y
   

4. 启用 Twig 调试：

   • 将 sites/default/default.services.yml 复制到 sites/default/services.yml
   • 设置 twig.config.debug: true
   • 设置 twig.config.auto_reload: true
   • 设置 twig.config.cache: false
   • 运行 ddev drush cr

5. 开发并迭代：

   • 修改 templates/ 中的模板
   • 更新 css/ 中的 CSS
   • 经常清除缓存：ddev drush cr
   • 检查浏览器控制台中的错误

标准开发工作流

1. 启用开发设置（Twig 调试，禁用 CSS/JS 聚合）
2. 根据 Twig 调试的建议创建/修改模板
3. 在 .theme 文件中实现预处理，以处理复杂数据
4. 通过库系统添加 CSS/JS
5. 在不同浏览器和设备上测试
6. 更改后清除缓存：ddev drush cr

查找模板名称

启用 Twig 调试后，检查 HTML 源代码：

x 表示当前使用的模板。其他模板是你可以创建的建议。

常见模式

在预处理中添加自定义变量

function mytheme_preprocess_page(&$variables) {
  // Add site slogan
  $variables['site_slogan'] = \Drupal::config('system.site')->get('slogan');

  // Add current user
  $variables['is_logged_in'] = \Drupal::currentUser()->isAuthenticated();

  // Add custom class
  $variables['attributes']['class'][] = 'custom-page-class';
}

模板继承

{# templates/page--article.html.twig #}
{% extends "page.html.twig" %}

{% block content %}
  <div class="article-wrapper">
    {{ parent() }}
  </div>
{% endblock %}

有条件地加载库

function mytheme_preprocess_node(&$variables) {
  if ($variables['node']->bundle() == 'article') {
    $variables['#attached']['library'][] = 'mytheme/article-styles';
  }
}

在 Twig 中访问字段值

{# Get field value #}
{{ node.field_custom.value }}

{# Check if field has value #}
{% if node.field_image|render %}
  {{ content.field_image }}
{% endif %}

{# Loop through multi-value field #}
{% for item in node.field_tags %}
  {{ item.entity.label }}
{% endfor %}

最佳实践

主题开发

1. 基础主题：选择合适的基础主题（Olivero、Claro 或不使用基础主题）
2. 结构：按逻辑组织 CSS（基础、布局、组件、主题）
3. 命名：使用 BEM 或类似的 CSS 方法论
4. 注释：记录复杂的 Twig 逻辑和预处理
5. 性能：优化图片、精简 CSS/JS，并尽可能延迟加载

Twig 模板

1. 逻辑：将复杂逻辑放在预处理中，而不是模板中
2. 过滤器：使用适当的过滤器（|t、|clean_class、|safe_join）
3. 空白字符：使用 {% spaceless %} 控制输出
4. 调试：仅在开发期间启用 Twig 调试
5. 建议：仅在需要时使用特定模板

预处理

1. 服务：在主题服务订阅者中使用依赖注入
2. 缓存：添加适当的缓存上下文和标签
3. 性能：避免在频繁调用的预处理中执行耗时操作
4. 组织：按逻辑归类相关的预处理

CSS 与 JavaScript

1. 库：将相关资源归入逻辑清晰的库
2. 依赖项：声明所有库依赖项
3. 加载：仅在必要时全局加载
4. 聚合：在生产环境中启用以提升性能

无障碍

1. 语义化 HTML：使用恰当的元素（header、nav、main 等）
2. ARIA：按需添加标签和角色
3. 键盘：确保键盘导航正常工作
4. 对比度：满足 WCAG 颜色对比度要求
5. 替代文本：为所有图片提供替代文本

响应式设计

1. 移动优先：为小屏幕设计，并针对大屏幕进行增强
2. 断点：定义符合逻辑的断点
3. 图片：使用响应式图片样式
4. 测试：在不同设备和屏幕尺寸上进行测试
5. 性能：针对移动网络进行优化

故障排除

模板更改未显示

• 清除缓存：ddev drush cr
• 确认文件位置和命名
• 在 Twig 调试中检查当前使用的模板
• 确保库定义正确

CSS/JS 未加载

• 检查 .libraries.yml 中的库定义
• 确认文件路径正确
• 确保库已附加（全局或按条件附加）
• 清除缓存并检查浏览器控制台

模板中无法使用变量

• 检查预处理函数的命名
• 确认变量设置正确
• 使用 Twig 调试：{{ dump() }}
• 修改预处理后清除缓存

Twig 调试无法使用

• 确认 sites/default/services.yml 存在
• 检查是否已设置 twig.config.debug: true
• 清除缓存：ddev drush cr
• 检查文件权限

资源

参考文档

• references/theming.md - 全面的主题开发指南
  • Twig 语法和过滤器
  • 模板建议
  • 预处理模式
  • 库管理
  • 响应式设计
  • 最佳实践

资源模板

• assets/theme-template/ - 完整的主题脚手架
  • 包含区域和配置的 .info.yml
  • 包含 CSS/JS 示例的 .libraries.yml
  • 包含预处理示例的 .theme
  • 页面模板
  • CSS 和 JS 起始文件

搜索参考资料

# Find specific Twig filter
grep -r "clean_class" references/

# Find preprocessing examples
grep -r "preprocess_node" references/

# Find library patterns
grep -r "libraries.yml" references/

版本兼容性

Drupal 8、9、10 和 11

• Twig 语法：所有版本均保持一致
• 基础主题：部分旧版主题已在 10+ 中移除
• 库：各版本的结构相同
• jQuery：Drupal 9+ 默认不加载 jQuery
• Claro：9+ 中的标准管理主题
• Olivero：10+ 中的标准前端主题

迁移说明

• 升级时，检查是否存在已弃用的基础主题
• 检查 jQuery 依赖项
• 使用当前的 Twig 版本进行测试
• 检查是否有已移除的核心模板

另请参阅

• drupal-backend - 模块开发、钩子、API
• drupal-tooling - DDEV 和 Drush 开发工具
• Drupal 主题开发指南 - 官方文档
• Twig 文档 - Twig 语法参考