chrome.cookies

說明

請使用 chrome.cookies API 查詢及修改 Cookie,並在 Cookie 變更時接收通知。

權限

cookies

若要使用 Cookie API,請在您的"cookies" 以及您想要的 Cookie 主機的主機權限 。例如:

{
  "name": "My extension",
  ...
  "host_permissions": [
    "*://*.google.com/"
  ],
  "permissions": [
    "cookies"
  ],
  ...
}

分區

分區 Cookie 可允許網站標示特定的 Cookie 應以 也包含頂層影格的原點舉例來說,假設網站 A 是透過網站 B 的 iframe 嵌入 和網站 C,而 A 分區 Cookie 的嵌入版本在 B 和 C 可以有不同的值。

根據預設,所有 API 方法都會在未分區的 Cookie 上執行。 partitionKey 屬性可用來覆寫這項行為。

如要進一步瞭解擴充功能分區的一般影響,請參閱「儲存空間和 Cookie」。

範例

您可以在 examples/api/cookies 目錄。其他範例及說明 原始碼,請參閱範例

類型

代表 HTTP Cookie 相關資訊。

屬性

  • 字串

    Cookie 的網域 (例如「www.google.com」、「example.com」)。

  • 編號 選填

    Cookie 的到期日,以自 UNIX 紀元時間起算的秒數。未提供工作階段 Cookie。

  • 布林值

    如果 Cookie 是僅限主機專用的 Cookie,則為「是」(亦即,請求的主機必須與 Cookie 的網域完全相符)。

  • 布林值

    如果 Cookie 標示為 HttpOnly (例如用戶端指令碼無法存取 Cookie),則為「是」。

  • 字串

    Cookie 的名稱。

  • Chrome 119 以上版本

    使用分區屬性讀取或修改 Cookie 的分區索引鍵。

  • 字串

    Cookie 的路徑。

  • Chrome 51 以上版本

    Cookie 的同網站狀態 (也就是 Cookie 是否與跨網站要求一併送出)。

  • 布林值

    如果 Cookie 標示為安全 (即範圍僅限於安全管道,通常是 HTTPS),則為「true」。

  • 布林值

    如果 Cookie 是工作階段 Cookie,而不是有到期日的持續 Cookie,則為 True。

  • 字串

    含有此 Cookie 的 Cookie 儲存庫 ID (由 getAllCookieStores() 提供)。

  • 字串

    Cookie 的值。

CookieDetails

Chrome 88 以上版本

用來識別 Cookie 的詳細資料。

屬性

  • 名稱

    字串

    存取的 Cookie 名稱。

  • partitionKey
    Chrome 119 以上版本

    使用分區屬性讀取或修改 Cookie 的分區索引鍵。

  • storeId

    string optional

    用來尋找 Cookie 的 Cookie 儲存庫 ID。根據預設,系統會使用目前執行內容的 Cookie 儲存庫。

  • 網址

    字串

    與要存取 Cookie 相關聯的網址。此引數可以是完整網址,在此情況下,網址路徑 (例如查詢字串) 後方的資料會遭到直接忽略。如未在資訊清單檔案中指定這個網址的主機權限,API 呼叫就會失敗。

CookiePartitionKey

Chrome 119 以上版本

代表分區 Cookie 的分區金鑰。

屬性

  • hasCrossSiteAncestor

    布林值 選填

    待處理

    表示 Cookie 是否在跨網站環境中設定。這樣就能防止嵌入跨網站結構定義的頂層網站,存取頂層網站在相同網站環境中設定的 Cookie。

  • topLevelSite

    string optional

    可使用分區 Cookie 的頂層網站。

CookieStore

代表瀏覽器的 Cookie 儲存庫。舉例來說,無痕模式視窗會從非無痕式視窗另外使用 Cookie 儲存庫。

屬性

  • id

    字串

    Cookie 存放區的專屬 ID。

  • tabIds

    數字 []

    共用此 Cookie 儲存庫的所有瀏覽器分頁的 ID。

OnChangedCause

Chrome 44 以上版本

Cookie 異動的根本原因。如果 Cookie 是透過明確呼叫「chrome.cookies.remove」插入或移除,「原因」為「煽情露骨內容」。如果 Cookie 因到期而自動移除,請「原因」的狀態為「已過期」。如果 Cookie 因到期日已失效覆寫而遭到移除,系統會標示為「原因」會設為「expired_overwrite」。如果 Cookie 因垃圾收集而遭到自動移除,請「原因」標示為「撤銷」的狀態。Cookie 因「設定」而遭到自動移除打電話給你說了。「原因」變更為「覆寫」據此規劃回應方式。

列舉

SameSiteStatus

Chrome 51 以上版本

Cookie 的「SameSite」狀態 (https://tools.ietf.org/html/draft-west-first-party-cookies)。「no_restriction」對應至含有「SameSite=None」和「lax」的 Cookie「SameSite=Lax」和「strict」設為「SameSite=Strict」。「未指定」對應到不含 SameSite 屬性的 Cookie。

列舉

方法

get()

Promise
chrome.cookies.get(
  details: CookieDetails,
  callback?: function,
)

擷取單一 Cookie 的相關資訊。如果指定網址存在多個相同名稱的 Cookie,系統會傳迴路徑最長的 Cookie。如果是路徑長度相同的 Cookie,系統會傳回建立時間最早的 Cookie。

參數

  • 詳細資料
  • 回呼

    函式 選用

    callback 參數如下所示:

    (cookie?: Cookie) => void

    • Cookie 選用

      包含 Cookie 的相關詳細資料。找不到這類 Cookie 時,此參數會是空值。

傳回

  • Promise<Cookie |未定義>

    Chrome 88 以上版本

    Promise 適用於 Manifest V3 及以上版本,但系統會為 回溯相容性您無法在同一函式呼叫中同時使用兩者。 保證會以傳遞至回呼的相同類型來解析。

getAll()

Promise
chrome.cookies.getAll(
  details: object,
  callback?: function,
)

從單一 Cookie 儲存庫擷取所有與指定資訊相符的 Cookie。系統會將傳回的 Cookie 排序,路徑最長的 Cookie 會優先顯示。如果多個 Cookie 的路徑長度相同,系統會優先採用建立時間最早的 Cookie。這個方法只會針對擴充功能具有主機權限的網域擷取 Cookie。

參數

  • 詳細資料

    物件

    用於篩選已擷取 Cookie 的資訊。

    • 網域

      string optional

      將擷取的 Cookie 限制在網域相符或隸屬於其子網域的 Cookie。

    • 名稱

      string optional

      按照名稱篩選 Cookie。

    • partitionKey
      Chrome 119 以上版本

      使用分區屬性讀取或修改 Cookie 的分區索引鍵。

    • 路徑

      string optional

      將擷取的 Cookie 限制在路徑與這個字串完全相符的 Cookie 內。

    • 安全

      布林值 選填

      按照 Cookie 安全屬性篩選 Cookie。

    • 工作階段

      布林值 選填

      篩選出工作階段與永久 Cookie。

    • storeId

      string optional

      用來擷取 Cookie 的 Cookie 儲存區。如果省略,系統會使用目前執行內容的 Cookie 儲存庫。

    • 網址

      string optional

      將擷取的 Cookie 限制為符合指定網址的 Cookie。

  • 回呼

    函式 選用

    callback 參數如下所示:

    (cookies: Cookie[]) => void

    • Cookie

      所有符合指定 Cookie 資訊的現有未過期 Cookie。

傳回

  • Promise<Cookie[]>

    Chrome 88 以上版本

    Promise 適用於 Manifest V3 及以上版本,但系統會為 回溯相容性您無法在同一函式呼叫中同時使用兩者。 保證會以傳遞至回呼的相同類型來解析。

getAllCookieStores()

Promise
chrome.cookies.getAllCookieStores(
  callback?: function,
)

列出所有現有的 Cookie 儲存庫。

參數

  • 回呼

    函式 選用

    callback 參數如下所示:

    (cookieStores: CookieStore[]) => void

    • cookieStores

      所有現有 Cookie 儲存庫。

傳回

  • Promise<CookieStore[]>

    Chrome 88 以上版本

    Promise 適用於 Manifest V3 及以上版本,但系統會為 回溯相容性您無法在同一函式呼叫中同時使用兩者。 保證會以傳遞至回呼的相同類型來解析。

remove()

Promise
chrome.cookies.remove(
  details: CookieDetails,
  callback?: function,
)

依名稱刪除 Cookie。

參數

  • 詳細資料
  • 回呼

    函式 選用

    callback 參數如下所示:

    (details?: object) => void

    • 詳細資料

      物件 optional

      包含已移除的 Cookie 詳細資料。如果因為任何原因移除失敗,這個欄位會設為「null」,系統會在 runtime.lastError 中設定。

      • 名稱

        字串

        已移除的 Cookie 名稱,

      • partitionKey
        Chrome 119 以上版本

        使用分區屬性讀取或修改 Cookie 的分區索引鍵。

      • storeId

        字串

        Cookie 移除來源的 ID。

      • 網址

        字串

        與已移除的 Cookie 相關聯的網址。

傳回

  • Promise<object |未定義>

    Chrome 88 以上版本

    Promise 適用於 Manifest V3 及以上版本,但系統會為 回溯相容性您無法在同一函式呼叫中同時使用兩者。 保證會以傳遞至回呼的相同類型來解析。

set()

Promise
chrome.cookies.set(
  details: object,
  callback?: function,
)

設定具有指定 Cookie 資料的 Cookie;可能會覆寫現有的 Cookie (如果有的話)。

參數

  • 詳細資料

    物件

    所設定 Cookie 的詳細資料。

    • 網域

      string optional

      Cookie 的網域。若省略,該 Cookie 會成為主機專用的 Cookie。

    • expirationDate

      編號 選填

      Cookie 的到期日,以自 UNIX 紀元時間起算的秒數。如果省略,該 Cookie 就會變成工作階段 Cookie。

    • httpOnly

      布林值 選填

      是否應將 Cookie 標示為 HttpOnly。預設值為 false。

    • 名稱

      string optional

      Cookie 的名稱。省略時則預設為空白。

    • partitionKey
      Chrome 119 以上版本

      使用分區屬性讀取或修改 Cookie 的分區索引鍵。

    • 路徑

      string optional

      Cookie 的路徑。預設值為網址參數的路徑部分。

    • sameSite
      Chrome 51 以上版本

      Cookie 的相同網站狀態。預設值為「未指定」,也就是說如未指定 SameSite 屬性,系統會設定 Cookie。

    • 安全

      布林值 選填

      Cookie 是否應標示為安全。預設值為 false。

    • storeId

      string optional

      用於設定 Cookie 的 Cookie 儲存庫 ID。根據預設,Cookie 會設定在目前執行環境的 Cookie 儲存庫中。

    • 網址

      字串

      與 Cookie 設定建立關聯的要求 URI。這個值會影響所建立 Cookie 的預設網域和路徑值。如未在資訊清單檔案中指定這個網址的主機權限,API 呼叫就會失敗。

    • string optional

      Cookie 的值。省略時則預設為空白。

  • 回呼

    函式 選用

    callback 參數如下所示:

    (cookie?: Cookie) => void

    • Cookie 選用

      內含所設定 Cookie 的詳細資料。如果因任何原因設定失敗,則會是「null」並runtime.lastError設定。

傳回

  • Promise<Cookie |未定義>

    Chrome 88 以上版本

    Promise 適用於 Manifest V3 及以上版本,但系統會為 回溯相容性您無法在同一函式呼叫中同時使用兩者。 保證會以傳遞至回呼的相同類型來解析。

活動

onChanged

chrome.cookies.onChanged.addListener(
  callback: function,
)

設定或移除 Cookie 時觸發。在特殊案例中,請注意更新 Cookie 屬性的過程分為兩個步驟:系統會先徹底移除要更新的 Cookie,並產生一則含有「原因」的通知的「覆寫」,直接在 Google Cloud 控制台實際操作。之後,系統會使用更新的值寫入新的 Cookie,產生第二則通知,並註明「原因」「煽情露骨內容」。

參數

  • 回呼

    函式

    callback 參數如下所示:

    (changeInfo: object) => void

    • changeInfo

      物件

      • Cookie 異動的根本原因。

      • 設定或移除的 Cookie 相關資訊。

      • 已移除

        布林值

        如果 Cookie 已遭移除,則為「true」。