使用 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 示例。