使用 Cookies API

Permissions

要使用 Cookies API，您需要为要访问或使用的协议、域或网站请求 "cookies" 权限和 主机权限，或者使用 "<all_urls>" 来访问任何协议和域。定义主机权限字符串的方式会影响扩展程序读取、写入和删除 cookie 的能力。

Cookie 存储

Firefox 提供三种类型的 cookie 存储

• 默认存储，用于存储普通浏览产生的 cookie。

• 隐私浏览模式存储，用于存储在隐私浏览会话期间创建的 cookie。这些存储及其包含的任何 cookie 在相关隐私浏览窗口关闭时会被删除。

  注意：仅当 extension.isAllowedIncognitoAccess() 返回 true 时可见。Safari 不支持访问隐私 cookie。

• 容器标签存储，用于存储 Firefox 中每个上下文身份的 cookie。上下文身份使用户能够在单个浏览器窗口中维护多个身份。例如，如果您有一个公司和个人 Gmail 帐户，这将非常有用。使用上下文身份，您可以针对个人身份打开一个标签页，针对商务身份打开第二个标签页。然后，每个标签页都可以使用不同的用户名登录 Gmail，并且可以并排使用这两个帐户。有关更多信息，请参阅 Mozilla Wiki 中的 Security/Contextual Identity Project/Containers。

您可以使用 cookies.getAllCookieStores 来查找可用的 cookie 存储，它会返回一个包含每个 cookie 存储 ID 和使用每个 cookie 存储的标签 ID 列表的对象。

示例详解

示例扩展 cookie-bg-picker 允许用户选择应用于网站页面背景的颜色和图标。这些选择使用 cookies.set 按网站进行保存。当打开网站页面时，cookies.get 会读取任何先前的选择，扩展程序会将其应用于网页。重置选项会删除网站的背景图标和颜色以及 cookie，使用 cookies.remove。它还使用 cookies.onChanged 来监听 cookie 的更改，并将更改的详细信息发送到控制台。

此视频展示了该扩展程序的工作原理

此示例还使用了 Tabs 和 Runtime API，但我们将只简要讨论这些功能。

manifest.json

与 Cookies API 使用相关的 manifest.json 文件中的关键功能是权限请求

  "permissions": [
      "tabs",
      "cookies",
      "<all_urls>"
],

在此，扩展程序请求使用 Cookies API ("cookies") 和所有网站 ("<all_urls>") 的权限。这使得扩展程序能够为任何网站保存背景图标选择。

脚本 - bgpicker.js

扩展程序的 UI 使用一个由 bgpicker.html 实现的工具栏按钮 (browserAction)，它调用 bgpicker.js。它们一起允许用户选择要应用于网站背景的图标和输入的颜色。它们还提供了清除这些设置的选项。

bgpicker.js 在单独的函数中处理图标的选择或背景颜色的输入。

为了处理图标按钮，脚本首先收集 HTML 文件中用于按钮的所有类名。然后，它循环遍历所有按钮，为每个按钮分配它们的图像并创建一个 onclick 监听器。

const bgBtns = document.querySelectorAll(".bg-container button");

for (const btn of bgBtns) {
  const imgName = btn.getAttribute("class");
  btn.style.backgroundImage = `url('images/${imgName}.png')`;

  btn.onclick = (e) => {
    // ...
  };
}

当按钮被点击时，其对应的监听器函数会获取按钮的类名，然后获取图标路径，并使用消息将其传递给页面的内容脚本 (updatebg.js)。然后，内容脚本会将图标应用于网页背景。与此同时，bgpicker.js 将应用于背景的图标详细信息存储在 cookie 中。

cookieVal.image = fullURL;
browser.cookies.set({
  url: tabs[0].url,
  name: "bgpicker",
  value: JSON.stringify(cookieVal),
});

颜色设置以类似的方式处理，由颜色输入字段上的监听器触发。当输入颜色时，会发现活动标签页，并将颜色选择详细信息通过消息发送到页面的内容脚本，以应用于网页背景。然后，将颜色选择添加到 cookie 中。

cookieVal.color = currColor;
browser.cookies.set({
  url: tabs[0].url,
  name: "bgpicker",
  value: JSON.stringify(cookieVal),
});

当用户点击已分配给变量 reset 的重置按钮时

let reset = document.querySelector(".color-reset button");

reset.onclick 首先查找活动标签页。然后，使用标签页的 ID，它会将消息传递给页面的内容脚本 (updatebg.js) 来让它删除页面上的图标和颜色。然后，该函数会清除 cookie 值（这样旧值就不会被带到稍后为同一页面上的新图标或颜色选择创建的 cookie 中），然后再删除 cookie。

cookieVal = { image: "", color: "" };
browser.cookies.remove({
  url: tabs[0].url,
  name: "bgpicker",
});

此外，为了让您看到 cookie 的变化，脚本会在控制台中报告所有 cookie 的变化。

browser.cookies.onChanged.addListener((changeInfo) => {
  console.log(`Cookie changed:\n
    * Cookie: ${JSON.stringify(changeInfo.cookie)}\n
    * Cause: ${changeInfo.cause}\n
    * Removed: ${changeInfo.removed}`);
});

脚本 - background.js

背景脚本 (background.js) 提供了用户在上一个会话中已为网站选择背景图标和颜色的可能性。脚本会监听活动标签页的变化，无论是用户在标签页之间切换还是更改标签页中显示的页面的 URL。当这些事件之一发生时，会调用 cookieUpdate()。cookieUpdate() 又使用 getActiveTab() 获取活动标签页 ID。然后，该函数可以使用标签页的 URL 检查扩展程序的 cookie 是否存在。

let gettingCookies = browser.cookies.get({
  url: tabs[0].url,
  name: "bgpicker",
});

如果网站存在 "bgpicker" cookie，则会检索先前选择的图标和颜色的详细信息，并通过消息传递给内容脚本 updatebg.js。

gettingCookies.then((cookie) => {
  if (cookie) {
    let cookieVal = JSON.parse(cookie.value);
    browser.tabs.sendMessage(tabs[0].id, { image: cookieVal.image });
    browser.tabs.sendMessage(tabs[0].id, { color: cookieVal.color });
  }
});

其他功能

除了到目前为止提到的 API 之外，Cookies API 还提供 cookies.getAll。此函数接受详细信息对象来指定所选 cookie 的过滤器，并返回一个 cookies.Cookie 对象数组，这些对象匹配过滤条件。

了解更多

如果您想了解更多关于 Cookies API 的信息，请查看

• Cookies API 参考.
• List-cookies 示例。