如何在 Drupal 中使用 js_cookie 模块重写 jQuery Cookie 和 core/js-cookie 库

迁移路径概述

1) Drupal 8 → 9：jQuery Cookie → core/js-cookie

历史背景：Drupal 9 用 js-cookie 替换了 jQuery Cookie，并提供了代码和库映射示例。https://www.drupal.org/node/3104677

# 之前（Drupal 8 / 早期 Drupal 9）
my_library:
  js:
    js/my_library.js: {}
  dependencies:
    - core/jquery
    - core/jquery.cookie
    - core/drupal

// 之前（jQuery Cookie API）
(($, Drupal) => {
  Drupal.behaviors.myModule = {
    attach: () => {
      $.cookie('cutest', 'red panda');
      const myCookieValue = $.cookie('cutest');
      $.removeCookie('cutest');

      $.cookie.json = true;
      $.cookie('cutest', { animal: 'red panda' });
    },
  };
})(jQuery, Drupal);

之后（Drupal 9） 你依赖 core/js-cookie 并使用 Cookies.* API：https://www.drupal.org/node/3104677

# 之后（Drupal 9）
my_library:
  js:
    js/my_library.js: {}
  dependencies:
    - core/drupal
    - core/js-cookie

// 之后（Drupal 9，js-cookie API）
((Drupal, Cookies) => {
  Drupal.behaviors.myModule = {
    attach: () => {
      Cookies.set('cutest', 'red panda');
      const myCookieValue = Cookies.get('cutest');
      Cookies.remove('cutest');

      Cookies.set('cutest', JSON.stringify({ animal: 'red panda' }));
      const cutest = JSON.parse(Cookies.get('cutest') || 'null');
    },
  };
})(Drupal, window.Cookies);

2) Drupal 10.1+ 和 11：core/js-cookie → 贡献模块 js_cookie

由于 Drupal 核心在 10.1 中弃用了 core/js-cookie 并在 11 中将其删除，你必须将其替换为贡献模块 JS Cookie 的库：js_cookie/js-cookie。https://www.drupal.org/node/3322720

Composer

composer require drupal/js_cookie

这将安装模块，并为上游的 js-cookie 包提供 Drupal 资产库。https://www.drupal.org/project/js_cookie

声明模块 / 主题依赖（适用于 contrib / 自定义项目）

# my_module.info.yml（或你的主题 .info.yml）
name: My Module
type: module
core_version_requirement: ^10 || ^11
dependencies:
  - js_cookie:js_cookie

项目页面明确说明 contrib 模块应添加 js_cookie:js_cookie 作为依赖（如果你的模块包含 composer.json，还需在 composer 中 require drupal/js_cookie）。[4](https://www.drupal.org/project/js_cookie)

切换你的资产库依赖

# 替换此项（10.1 弃用，11 中删除）
# - core/js-cookie

# 使用此项（由 contrib 模块提供）
my_library:
  js:
    js/my_library.js: {}
  dependencies:
    - core/drupal
    - js_cookie/js-cookie

这一替换正是核心变更记录推荐的路径。[2](https://www.drupal.org/node/3322720)

JavaScript 代码

如果你已经使用 Cookies API，则 JS 代码无需修改——只需要更改库依赖即可。https://www.drupal.org/node/3322720

((Drupal, Cookies) => {
  Drupal.behaviors.myModule = {
    attach: () => {
      // 设置 cookie
      Cookies.set('cutest', 'red panda', { path: '/', sameSite: 'Lax' });

      // 获取 cookie
      const myCookieValue = Cookies.get('cutest');

      // 删除 cookie
      Cookies.remove('cutest', { path: '/' });

      // 安全存储 / 读取 JSON
      Cookies.set('cutest', JSON.stringify({ animal: 'red panda' }));
      const cutestRaw = Cookies.get('cutest');
      const cutest = cutestRaw ? JSON.parse(cutestRaw) : null;
    },
  };
})(Drupal, window.Cookies);

提示：js-cookie 遵循 RFC 6265，并且在编码方式上与旧的 jQuery Cookie 不同，尤其是处理 JSON 时。Drupal 9 的变更记录描述了这些行为差异。https://www.drupal.org/node/3104677

生态系统中的示例

• EU Cookie Compliance 模块跟踪了 core/js-cookie 的弃用情况，并提交了切换至 js_cookie/js-cookie 的补丁。https://www.drupal.org/project/eu_cookie_compliance/issues/3380490
• 多个 contrib 项目提交了 issue，以替换 jQuery Cookie 为 js-cookie，并随后处理 core/js-cookie 的弃用。https://www.drupal.org/project/quicktabs/issues/3298649
  https://www.drupal.org/project/fpa/issues/3505122

逐步升级方案

A) 从 jQuery Cookie 直接升级到 js_cookie/js-cookie（Drupal 10+）

1. 从你的 .libraries.yml 中移除对 core/jquery 和 core/jquery.cookie 的依赖。https://www.drupal.org/node/3104677
2. 在 .info.yml 中添加 js_cookie:js_cookie 作为依赖（适用于 contrib / 自定义模块和主题）。https://www.drupal.org/project/js_cookie
3. 将库依赖更换为 js_cookie/js-cookie。https://www.drupal.org/project/js_cookie
4. 将 JS 从 $.cookie 重写为 Cookies.*，如前文所示。https://www.drupal.org/node/3104677

B) 从 core/js-cookie 升级到 js_cookie/js-cookie（Drupal 10.1 → 11）

1. 安装模块：composer require drupal/js_cookie。https://www.drupal.org/project/js_cookie
2. （Contrib）在 .info.yml 中添加 js_cookie:js_cookie；站点级别只需启用模块即可。https://www.drupal.org/project/js_cookie
3. 在 .libraries.yml 中将 core/js-cookie 替换为 js_cookie/js-cookie。https://www.drupal.org/node/3322720
4. 继续使用现有的 Cookies.* JS 代码，无需做进一步修改。https://www.drupal.org/node/3322720

注意事项与最佳实践

• Drupal 11 准备： core/js-cookie 已在 Drupal 11 中删除——请确保所有依赖指向 js_cookie/js-cookie。https://www.drupal.org/node/3322720
• 隐私 / CDN： js_cookie 项目页面说明了如何避免从 CDN 加载 js-cookie（符合数据保护要求）。建议使用本地资源。https://www.drupal.org/project/js_cookie
• 编码与 JSON： 不要依赖隐式 JSON 行为，请使用 JSON.stringify 和 JSON.parse。https://www.drupal.org/node/3104677
• 真实补丁案例： 查看 issue 队列（例如 EU Cookie Compliance）以了解更新模式。https://www.drupal.org/project/eu_cookie_compliance/issues/3380490