chrome.cookies

說明

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

權限

cookies

資訊清單

若要使用 Cookie API，您必須宣告「Cookie」授予相關權限 以及您想要的 Cookie 主機的主機權限 。例如：

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

分區

分區 Cookie 可允許網站標示特定的 Cookie 應以 也包含頂層頁框的原點也就是說，如果網站 A 是透過網站 B 的 iframe 嵌入 和網站 C，分區 Cookie 的每個值可能都不同。

chrome.cookies 不支援分區，這代表所有方法 讀取及寫入所有分區的 Cookie。cookies.set() 方法會將 Cookie 儲存在 預設分區

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

範例

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

類型

代表 HTTP Cookie 相關資訊。

屬性

  • 網域

    字串

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

  • expirationDate

    編號 選填

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

  • hostOnly

    布林值

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

  • httpOnly

    布林值

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

  • 名稱

    字串

    Cookie 的名稱。

  • partitionKey

    CookiePartitionKey 選用

    Chrome 119 以上版本

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

  • 路徑

    字串

    Cookie 的路徑。

  • sameSite

    SameSiteStatus

    Chrome 51 以上版本

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

  • 安全

    布林值

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

  • 工作階段

    布林值

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

  • storeId

    字串

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

  • 值

    字串

    Cookie 的值。

CookieDetails

Chrome 88 以上版本

用來識別 Cookie 的詳細資料。

屬性

  • 名稱

    字串

    存取的 Cookie 名稱。

  • partitionKey

    CookiePartitionKey 選用

    Chrome 119 以上版本

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

  • storeId

    string optional

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

  • 網址

    字串

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

CookiePartitionKey

Chrome 119 以上版本

代表分區 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 因「設定」而遭到自動移除打電話給你說了。「原因」變更為「覆寫」據此規劃回應方式。

列舉

"evicted"

"已過期"

「煽情露骨內容」

"expired_overwrite"

"覆寫"

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。

列舉

"no_restriction"

「寬鬆」

「嚴格」

"未指定"

方法

get()

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

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

參數

  • 詳細資料

    CookieDetails

  • 回呼

    函式 選用

    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

      CookiePartitionKey 選用

      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 資訊的現有未過期 Cookie。

傳回

  • Promise<Cookie[]>

    Chrome 88 以上版本

    Promise 僅適用於 Manifest V3 及以上版本，其他平台需要使用回呼。

getAllCookieStores()

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

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

參數

  • 回呼

    函式 選用

    callback 參數如下所示： 

    (cookieStores: CookieStore[]) => void

    • cookieStores

      CookieStore[]

      所有現有 Cookie 儲存庫。

傳回

  • Promise<CookieStore[]>

    Chrome 88 以上版本

    Promise 僅適用於 Manifest V3 及以上版本，其他平台需要使用回呼。

remove()

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

依名稱刪除 Cookie。

參數

  • 詳細資料

    CookieDetails

  • 回呼

    函式 選用

    callback 參數如下所示： 

    (details?: object) => void

    • 詳細資料

      物件 optional

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

      • 名稱

        字串

        已移除的 Cookie 名稱，

      • partitionKey

        CookiePartitionKey 選用

        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

      CookiePartitionKey 選用

      Chrome 119 以上版本

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

    • 路徑

      string optional

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

    • sameSite

      SameSiteStatus 選用

      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 相關資訊。

      • 已移除

        布林值

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