使用 Cookies API

使用 Cookies API,您的扩展可以访问与网站用于存储和读取 Cookie 的功能类似的功能。API 的功能使扩展能够在每个网站的基础上存储信息。因此,正如我们在示例中将要看到的,您可以存储用户为某个网站选择的背景颜色的详细信息。然后,当用户重新访问该网站时,您的扩展可以使用 API 获取关于 Cookie 的详细信息并读取它们,以恢复用户的选择并将它应用于网站。

注意:可以使用 privacy.websites cookieConfig 属性控制 Cookie 的行为。此属性控制是否以及如何接受 Cookie,或者是否将所有 Cookie 视为会话 Cookie。

权限

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

主机权限字符串

读取

写入/删除

安全

不安全

安全

不安全

"http://*.example.com/"

主域名和子域名,以及任何路径

主域名和子域名,以及任何路径

主域名和子域名,以及任何路径

"https://www.example.com/"

www.example.com 或 .example.com 以及任何路径,但不包括子域名

www.example.com 或 .example.com 以及任何路径,但不包括子域名

www.example.com 或 .example.com 以及任何路径,但不包括子域名

www.example.com 或 .example.com 以及任何路径,但不包括子域名

"*://*.example.com/"

主域名和子域名,以及任何路径

主域名和子域名,以及任何路径

主域名和子域名,以及任何路径

主域名和子域名,以及任何路径

"<all_urls>"

任何域名以及任何路径

任何域名以及任何路径

任何域名以及任何路径

任何域名以及任何路径

Firefox 提供三种类型的 Cookie 存储

  • 默认存储,用于存储来自正常浏览的 Cookie。
  • 私密浏览模式存储,用于存储在私密浏览会话期间创建的 Cookie。这些存储及其包含的任何 Cookie 在相关私密浏览窗口关闭时将被删除。

    注意:仅当 extension.isAllowedIncognitoAccess() 返回 true 时可见。Safari 不支持访问私密 Cookie。

  • 容器选项卡存储,用于存储 Firefox 中每个上下文身份的 Cookie。上下文身份使用户能够在一个浏览器窗口中维护多个身份。这在您拥有公司和个人 Gmail 帐户时很有用。使用上下文身份,您可以打开一个针对个人身份的选项卡和一个针对业务身份的选项卡。然后,每个选项卡都可以使用不同的用户名登录到 Google 邮箱,并且这两个帐户可以并行使用。有关更多信息,请参阅 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 文件的关键功能是权限请求

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

在这里,扩展请求使用 Cookies API ("cookies") 的权限,以及所有网站 ("<all_urls>") 的权限。这使扩展能够为任何网站保存背景颜色图标选择。

脚本 - bgpicker.js

扩展的 UI 使用一个工具栏按钮 (browserAction),该按钮使用 bgpicker.html 实现,它调用 bgpicker.js。这些文件共同允许用户选择图标并输入他们想要应用为网站背景的颜色。它们还提供清除这些设置的选项。

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

要处理图标按钮,脚本首先收集 HTML 文件中用于按钮的所有类名

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

然后它遍历所有按钮,为它们分配图像,并为每个按钮创建一个 onclick 监听器

js
for (let i = 0; i < bgBtns.length; i++) {
  let imgName = bgBtns[i].getAttribute('class');
  let bgImg = 'url(\'images/' + imgName + '.png\')';
  bgBtns[i].style.backgroundImage = bgImg;

  bgBtns[i].onclick = (e) => {

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

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

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

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

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

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

reset.onclick 首先找到活动选项卡。然后,使用选项卡的 ID,它向页面的内容脚本 (updatebg.js) 发送消息,以使其从页面中删除图标和颜色。然后,该函数会清除 Cookie 值(这样旧的值就不会被传递并写入为同一页面上为新图标或颜色选择创建的 Cookie),然后删除 Cookie

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

此外,为了让您看到 Cookie 的运行情况,脚本会在控制台中报告所有 Cookie 的更改

js
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 是否存在。

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

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

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 的信息,请查看