Drupal：用 GLightbox 替换 Colorbox

1 简介

十多年来，Lightbox 插件一直是 Drupal 网站的核心组成部分。它们允许编辑人员在不离开当前页面的情况下，通过覆盖层展示图片、视频和其他媒体内容——这是现代富媒体网站访客所习以为常的一种交互模式。

Colorbox 长期以来一直是 Drupal 生态系统中的首选解决方案。colorbox 贡献模块与 Drupal 的图片字段格式器紧密配合，拥有成熟的 API，并且在社区中具有极高的认知度。然而，随着 Web 的发展，Colorbox 已逐渐显露出其年代感：它依赖 jQuery，负载较重，并且在当代无障碍性方面明显落后。

GLightbox 应运而生——这是一个纯原生 JavaScript（零依赖）的 lightbox 库，拥有精致的 UI、强大的无障碍支持以及极轻量的体积。对应的 Drupal 模块可以无缝集成到此前由 Colorbox 处理的相同图片字段和媒体实体中。

本文将带你完整走过迁移流程：从审计当前的 Colorbox 配置，到安装 GLightbox，重新映射字段格式器，安全移除旧模块，以及为主题微调全新的使用体验。

2 Colorbox vs GLightbox：为什么要迁移？

2.1 Colorbox 的局限性

Colorbox 诞生于 Web 的早期阶段，其架构基于许多在现代 Drupal 开发中已不再成立的假设：

• 依赖 jQuery。 Colorbox 是一个 jQuery 插件，无法在没有 jQuery 的情况下运行。Drupal 核心正在逐步减少对 jQuery 的依赖，而许多注重性能的主题会延迟加载甚至完全不加载 jQuery。强制依赖 jQuery 与这一趋势背道而驰。
• 界面和动画老旧。 以 2024–2026 年的设计标准来看，Colorbox 的默认样式明显过时，往往需要大量 CSS 自定义才能勉强达到现代审美的基础水平。
• 无障碍性不足。 尽管 Colorbox 多年来收到了一些无障碍补丁，但它并非以 WCAG 2.1 AA 为核心设计目标。焦点陷阱、ARIA 角色以及屏幕阅读器提示通常需要大量额外工作才能完善。
• 维护节奏缓慢。 上游的 jQuery Colorbox 库更新频率较低。对于长期运行的 Drupal 项目而言，依赖一个维护缓慢的库会带来潜在风险。

2.2 GLightbox 的优势

GLightbox 针对上述痛点逐一给出了直接的解决方案：

• 零依赖。 纯 ES6+ JavaScript，不需要 jQuery。
• 现代化的用户体验。 平滑的 CSS 过渡、滑动手势、键盘导航，以及干净的默认主题，可自然融入当代设计体系。
• 一流的无障碍支持。 焦点会被限制在 lightbox 内部，键盘方向键导航默认启用，并自动应用正确的 ARIA role="dialog" 语义。
• 轻量。 压缩并 gzip 后的体积小于 15 KB——大约只有典型 Colorbox 配置的三分之一。
• 图库分组。 原生支持通过 data-gallery 属性进行分组，无需额外插件。
• 持续活跃的开发。 GitHub 上的 GLightbox 项目保持着 регуляр 的版本发布与缺陷修复。

3 Drupal 生态系统概览

多年来，Drupal 核心一直在持续减少对 jQuery 的依赖，逐步转向原生 JavaScript 和现代浏览器 API。这一点在 Drupal 10+ 中大量基于 jQuery 的行为被弃用，以及官方推动主题采用更精简 JavaScript 策略中体现得尤为明显。

在贡献模块（contrib）层面，Colorbox 和 GLightbox 均在 Drupal.org 上提供了各自的 Drupal 模块：

• colorbox —— 经典选择，与图片字段格式器、Views 以及媒体系统深度集成。尽管安装量仍然很高，但更新频率已明显降低。
• glightbox —— 较新的贡献模块，对 GLightbox JS 库进行了 Drupal 封装，提供图片和媒体字段格式器、Views 支持，以及用于常见 GLightbox 选项的配置表单。

4 迁移前的准备工作

4.1 审计当前的 Colorbox 使用情况

在修改任何配置之前，先全面了解 Colorbox 在网站中的使用位置和方式：

1. 图片字段。 访问 结构 → 内容类型 → [类型] → 管理显示，检查是否有图片字段使用 Colorbox 格式器，并记录所用的图片样式和说明配置。
2. 媒体实体。 在 结构 → 媒体类型 中检查各个媒体类型的显示模式，特别是涉及图片或视频的类型。
3. Views。 查找包含图片字段的 View，并确认使用的字段格式器。Colorbox 也可能通过 Views 的 “Colorbox” 格式插件启用。
4. 自定义代码。 在自定义模块和主题中搜索 colorbox、.colorbox、Drupal.behaviors.colorbox 以及库键 colorbox/colorbox。

# 在代码库中快速搜索（从 Drupal 根目录运行）
grep -r "colorbox" web/modules/custom web/themes/custom \
  --include="*.php" --include="*.js" --include="*.twig" \
  --include="*.yml" -l

将找到的每一处位置记录下来，后续替换阶段会逐一处理。

4.2 备份与环境注意事项

• 导出当前配置：drush config:export
• 在开始前将配置提交到版本控制系统
• 迁移过程中关闭 CSS/JS 聚合（管理 → 性能）
• 备份数据库：drush sql:dump > pre-migration.sql
• 确保部署流水线可以将配置推送到预发布/生产环境

5 在 Drupal 中安装并启用 GLightbox

5.1 安装 GLightbox JavaScript 库

Drupal 的 GLightbox 模块依赖上游的 GLightbox JS 库。 目前支持以下两种提供方式。

方案 A — Composer + Asset Packagist（推荐）

# 为项目添加 Asset Packagist 仓库（每个项目只需一次）
composer config repositories.asset-packagist \
  composer https://asset-packagist.org

# 安装所需依赖
composer require oomphinc/composer-installers-extender
composer require npm-asset/glightbox

在 composer.json 的 extra.installer-paths 中添加或确认 npm-asset 的安装路径：

"extra": {
  "installer-types": ["npm-asset", "bower-asset"],
  "installer-paths": {
    "web/libraries/{$name}": [
      "type:drupal-library",
      "type:npm-asset",
      "type:bower-asset"
    ]
  }
}

运行 composer install 后，库将位于 web/libraries/glightbox/。

方案 B — 手动放置

从 GLightbox GitHub releases 页面下载最新版本，并确保以下路径存在：

web/libraries/glightbox/dist/js/glightbox.min.js
web/libraries/glightbox/dist/css/glightbox.min.css

5.2 安装并启用 GLightbox Drupal 模块

# 下载模块
composer require drupal/glightbox

# 启用模块
drush en glightbox -y

# 清理缓存
drush cr

前往 管理 → 配置 → 媒体 → GLightbox， 确认库已被检测到，并查看全局配置选项。

6 替换 Colorbox 功能

6.1 图片字段

这是 Colorbox 最常见的使用场景：在内容类型中显示缩略图， 点击后在 lightbox 中打开原图。

1. 前往 结构 → 内容类型 → [你的类型] → 管理显示。
2. 找到图片字段，在 格式 下拉框中， 将 Colorbox 切换为 GLightbox。
3. 点击设置齿轮（⚙），配置格式器。 设置 图片样式（页面中的缩略图） 和 链接图片样式（lightbox 中加载的图片）。 如需说明文字可启用标题。
4. 保存显示配置并清理缓存： drush cr。

你也可以通过配置导出并使用 YAML 应用这些更改。 下面是内容类型显示配置中的示例：

# core.entity_view_display.node.article.default.yml（节选）
dependencies:
  module:
    - glightbox
    - image
content:
  field_image:
    type: glightbox
    label: hidden
    settings:
      image_style: medium
      image_link: ''
      glightbox_image_style: large
      glightbox_gallery: ''
      glightbox_caption: title
      glightbox_caption_custom: ''
    third_party_settings: {  }

6.2 媒体与图库

对于使用 Drupal 媒体系统的网站，迁移步骤类似，但需要应用在媒体类型的显示模式上。

• 访问 结构 → 媒体类型 → [类型] → 管理显示。
• 将图片源字段的格式器从 Colorbox 切换为 GLightbox。
• 如需图库分组，请在 GLightbox 格式器设置中配置 图库 ID。 具有相同图库 ID 的所有项目将在 lightbox 中作为一个组进行浏览。 这直接映射到 GLightbox 原生的 data-gallery 属性。

说明文字（caption）的映射非常直接： GLightbox 读取 data-description 属性。 Drupal 模块允许你将其映射到图片的 title、 alt 属性，或某个自定义字段值。

6.3 Views 集成

如果 Views 中使用了 Colorbox 来显示图片，请按以下步骤更新每个 View：

1. 在 结构 → Views → [View 名称] → 编辑 中打开 해당 View。
2. 在 字段 下点击图片字段， 在 格式器 下拉框中将 Colorbox 切换为 GLightbox。
3. 如果 Colorbox 是在 格式 层级启用的 （例如使用 “Colorbox” 格式插件）， 请切换为标准格式（如 未格式化列表 或 网格）， 然后在字段级别应用 GLightbox 格式器。
4. 保存并清理缓存。

7 安全移除 Colorbox

在所有格式器和自定义代码完成迁移后， 你就可以安全地移除 Colorbox。 请按以下顺序操作，以避免依赖错误：

1. 禁用 Colorbox 模块。 在卸载前禁用模块可以让 Drupal 执行 hook_uninstall() 清理逻辑。

   drush pm:uninstall colorbox -y

2. 从 composer.json 中移除。

   composer remove drupal/colorbox

3. 移除 Colorbox JS 库（如果是手动放置的）， 路径为 web/libraries/colorbox/。
4. 清理自定义代码。 搜索并移除所有残留的 Colorbox 引用， 包括 CSS 类（.colorbox、.colorbox-load）、 JS 行为（Drupal.behaviors.colorbox） 或库附加（colorbox/colorbox）。

5. 清理所有缓存并导出配置。

   drush cr
   drush config:export

8 自定义与增强

8.1 GLightbox 配置选项

全局 GLightbox 设置页面（管理 → 配置 → 媒体 → GLightbox） 提供了最常用的配置选项。 这些选项与 GLightbox 的 JavaScript API 一一对应：

8.2 主题与样式

GLightbox 自带一个默认样式表（glightbox.min.css）， 提供了简洁的深色遮罩设计。 不需要修改库文件即可在主题中进行覆盖：

/* mytheme/css/glightbox-overrides.css */

/* 修改遮罩背景 */
.glightbox-clean .goverlay {
  background: rgba(0, 0, 0, 0.92);
}

/* 样式化说明文字区域 */
.glightbox-clean .gdesc-inner {
  font-family: inherit;
  font-size: 0.9rem;
  color: #f0f0f0;
  padding: 12px 16px;
}

/* 放大导航箭头 */
.glightbox-clean .gnext,
.glightbox-clean .gprev {
  width: 48px;
  height: 48px;
}

/* 亮色模式变体 */
@media (prefers-color-scheme: light) {
  .glightbox-clean .goverlay {
    background: rgba(255, 255, 255, 0.95);
  }
  .glightbox-clean .gdesc-inner {
    color: #1a1a1a;
  }
}

在主题的 .libraries.yml 文件中附加该覆盖样式：

# mytheme.libraries.yml
glightbox-overrides:
  version: VERSION
  css:
    theme:
      css/glightbox-overrides.css: {}
  dependencies:
    - glightbox/glightbox

然后在 mytheme.info.yml 中全局引入：

# mytheme.info.yml（节选）
libraries:
  - mytheme/glightbox-overrides

8.3 高级用法

通过 #attached 进行程序化附加

你可以在自定义模块或预处理函数中， 将 GLightbox 附加到任意渲染数组：

// 在 preprocess 函数或自定义区块的 build() 中
$build['#attached']['library'][] = 'glightbox/glightbox';

// 通过 JS 设置传入配置覆盖
$build['#attached']['drupalSettings']['glightbox'] = [
  'animation'  => 'fade',
  'loop'       => TRUE,
  'touchNavigation' => TRUE,
];

在 Twig 模板中使用自定义触发器

如需在 Twig 模板中手动创建 GLightbox 触发元素， 只需添加正确的属性。 GLightbox 会自动处理所有带有 class="glightbox" （或你配置的 selector）的元素：

{# 打开单张图片 #}
<a href="{{ file_url(node.field_hero_image.entity.uri.value) }}"
   class="glightbox"
   data-title="{{ node.label }}"
   data-description="{{ node.field_caption.value }}">
  {{ content.field_hero_image }}
</a>

{# 图库分组 —— 具有相同 data-gallery 的项目会一起打开 #}
{% for item in node.field_gallery %}
  <a href="{{ file_url(item.entity.uri.value) }}"
     class="glightbox"
     data-gallery="gallery-{{ node.id }}"
     data-description="{{ item.alt }}">
    <img src="{{ file_url(item.entity.uri.value) | image_style('thumbnail') }}"
         alt="{{ item.alt }}" />
  </a>
{% endfor %}

使用 Drupal Behavior 进行自定义初始化

如果需要使用模块管理界面中未暴露的选项来初始化 GLightbox， 可以编写自定义 Drupal behavior：

// mytheme/js/glightbox-init.js
(function (Drupal, drupalSettings) {
  'use strict';

  Drupal.behaviors.mythemeGlightbox = {
    attach(context, settings) {
      // 确保每个 context 只初始化一次
      const elements = context.querySelectorAll('.glightbox-custom:not(.glightbox-processed)');
      if (!elements.length) return;

      elements.forEach(el => el.classList.add('glightbox-processed'));

      const lightbox = GLightbox({
        selector: '.glightbox-custom',
        touchNavigation: true,
        loop: true,
        animation: 'fade',
        autoplayVideos: settings.glightbox?.autoplayVideos ?? true,
      });
    },
  };

}(Drupal, drupalSettings));

9 测试与质量保证

迁移完成后，在部署到生产环境之前，请按以下 QA 清单逐项检查：

功能测试

• 在所有受影响的内容类型中，点击图片都会在 lightbox 中打开
• 图库导航（上一张/下一张箭头、键盘方向键）正常工作
• 说明文字正常显示，并且与预期的字段值一致
• 视频项目（YouTube、Vimeo、本地视频）可自动播放并正常关闭
• 关闭 lightbox（✕ 按钮、Esc 键、点击外部）后，焦点会正确返回

跨浏览器测试

• Chrome / Edge（Chromium）、Firefox、Safari（macOS 与 iOS）
• 确认 CSS 过渡效果在所有测试浏览器中均能正确渲染

移动端与触控测试

• 左右滑动可在图库项目间切换
• 图片支持双指缩放（如已启用）
• 在小屏幕上遮罩层能够正确覆盖整个视口

无障碍性检查

• Tab 键可以在 lightbox 控件之间循环（关闭、上一张、下一张）
• 关闭后焦点返回到触发元素
• 屏幕阅读器能够正确宣布对话框及其内容（使用 NVDA 或 VoiceOver 测试）
• 运行 axe DevTools 或 Lighthouse 无障碍审计 —— 目标为零关键错误

性能

• 重新启用 CSS/JS 聚合，并确认 GLightbox 仍能正常初始化
• 运行 Lighthouse 性能审计，并与 Colorbox 基线进行对比
• 确认所有测试页面的 JavaScript 控制台中不存在错误

10 常见问题与故障排查

图片未在 Lightbox 中打开

症状： 点击图片后跳转到链接地址，而不是打开 GLightbox。

• 确认 GLightbox 库已加载：打开浏览器开发者工具 → Network， 过滤 glightbox。 如未加载，请检查文件是否存在于 web/libraries/glightbox/dist/。
• 检查 CSS/JS 聚合是否正常； 可临时关闭以排查是否为聚合问题。
• 查看渲染后的 HTML，确认触发元素是否包含 class="glightbox" （或你配置的自定义选择器）。

说明文字缺失或图库异常

症状： 说明为空，或图库导航跳过部分项目。

• 检查渲染后的链接元素，确认 data-description 已填充， 且分组项目的 data-gallery 值一致。
• 检查字段格式器中的 说明来源 是否指向非空字段。
• 对于图库分组，确认图库 ID 一致； 如果使用 token 但未安装 Token 模块，可能会解析为空字符串。

与其他 JS 库发生冲突

症状： GLightbox 部分初始化或在控制台中报错。

• 检查是否重复加载 GLightbox（模块 + 主题手动附加）。
• 确认没有其他库覆盖 window.GLightbox。
• 如果主题使用 JS bundler， 请确保 GLightbox 没有被额外打包， 同时仍通过 Drupal 的资源系统附加。

缓存与聚合问题

症状： 在开发环境正常，但在生产环境中失效。

• 在生产环境部署配置后运行 drush cr。
• 确认 web/libraries/glightbox/ 已正确提交或部署。 该目录有时会因 .gitignore 规则而被忽略。 可在 CI/CD 中使用 composer install --no-dev 确保库被正确放置。
• 如果 CSS 聚合在压缩 GLightbox 样式时导致选择器优先级问题， 请将你的覆盖样式放在资源加载顺序的后面。

# 在生产环境清理所有缓存（如可用 Drush）
drush @prod cr

# 确认库文件存在
ls web/libraries/glightbox/dist/js/glightbox.min.js

11 总结

从 Colorbox 迁移到 GLightbox 是任何 Drupal 项目中一次有价值的前端现代化升级。 优势十分明显：

• 从 lightbox 链路中移除对 jQuery 运行时的依赖
• 为访客提供更快、更轻量的体验
• 无需自定义补丁即可获得开箱即用的无障碍合规性
• 与 Drupal 核心逐步转向原生 JavaScript 的方向保持一致
• 通过持续维护的库降低长期维护成本

只要方法得当， 整个迁移过程风险很低： 先审计， 再逐一迁移字段格式器， 清理遗留代码， 并在部署前进行充分测试。 glightbox Drupal 模块 使大多数工作都可以通过后台配置完成， 而无需自定义代码。

对于计划进行更大规模前端现代化的网站—— 例如走向解耦或无头架构、 采用现代主题（Olivero、Gin 或自定义设计系统）， 或减少 JavaScript 体积—— 用 GLightbox 替换 Colorbox 是一个理想且独立的切入点， 能以极低风险带来可见成效。