browser.cookies

Mô tả

Sử dụng API chrome.cookies để truy vấn và sửa đổi cookie, đồng thời nhận thông báo khi cookie thay đổi.

Quyền

cookies

Để sử dụng API cookie, hãy khai báo quyền "cookies" trong tệp kê khai cùng với quyền của máy chủ lưu trữ cho mọi máy chủ lưu trữ có cookie mà bạn muốn truy cập. Ví dụ:

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

Phân vùng

Cookie được phân vùng cho phép một trang web đánh dấu rằng một số cookie nhất định phải được khoá theo nguồn gốc của khung cấp cao nhất. Điều này có nghĩa là, ví dụ: nếu trang web A được nhúng bằng iframe trong trang web B và trang web C, thì các phiên bản được nhúng của cookie được phân vùng từ A có thể có các giá trị khác nhau trên B và C.

Theo mặc định, tất cả phương thức API đều hoạt động trên cookie chưa phân vùng. Bạn có thể dùng thuộc tính partitionKey để ghi đè hành vi này.

Để biết thông tin chi tiết về tác động chung của việc phân vùng đối với tiện ích, hãy xem bài viết Bộ nhớ và cookie.

Ví dụ

Bạn có thể tìm thấy một ví dụ đơn giản về cách sử dụng API cookie trong thư mục examples/api/cookies. Để xem các ví dụ khác và được trợ giúp xem mã nguồn, hãy xem phần Mẫu.

Loại

Đại diện cho thông tin về cookie HTTP.

Thuộc tính

  • tên miền

    chuỗi

    Miền của cookie (ví dụ: "www.google.com", "example.com").

  • expirationDate

    number không bắt buộc

    Ngày hết hạn của cookie, tính bằng số giây kể từ thời gian Unix. Không được cung cấp cho cookie của phiên.

  • hostOnly

    boolean

    Đúng nếu cookie là cookie chỉ dành cho máy chủ lưu trữ (tức là máy chủ lưu trữ của yêu cầu phải khớp chính xác với miền của cookie).

  • httpOnly

    boolean

    Đúng nếu cookie được đánh dấu là HttpOnly (tức là tập lệnh phía máy khách không thể truy cập vào cookie).

  • tên

    chuỗi

    Tên của cookie.

  • partitionKey

    CookiePartitionKey không bắt buộc

    Chrome 119 trở lên browser.* kể từ Chrome 148

    Khoá phân vùng để đọc hoặc sửa đổi cookie bằng thuộc tính Phân vùng.

  • đường dẫn

    chuỗi

    Đường dẫn của cookie.

  • sameSite

    SameSiteStatus

    Chrome 51 trở lên browser.* kể từ Chrome 148

    Trạng thái cùng trang web của cookie (tức là liệu cookie có được gửi cùng với các yêu cầu trên nhiều trang web hay không).

  • bảo mật

    boolean

    True nếu cookie được đánh dấu là Bảo mật (tức là phạm vi của cookie bị giới hạn ở các kênh bảo mật, thường là HTTPS).

  • phiên

    boolean

    True nếu cookie là cookie của phiên, trái ngược với cookie liên tục có ngày hết hạn.

  • storeId

    chuỗi

    Mã của kho lưu trữ cookie chứa cookie này, như được cung cấp trong getAllCookieStores().

  • value

    chuỗi

    Giá trị của cookie.

CookieDetails

Chrome 88 trở lên trình duyệt.* kể từ Chrome 148

Thông tin chi tiết để xác định cookie.

Thuộc tính

  • tên

    chuỗi

    Tên của cookie cần truy cập.

  • partitionKey

    CookiePartitionKey không bắt buộc

    Chrome 119 trở lên browser.* kể từ Chrome 148

    Khoá phân vùng để đọc hoặc sửa đổi cookie bằng thuộc tính Phân vùng.

  • storeId

    chuỗi không bắt buộc

    Mã nhận dạng của kho cookie để tìm cookie. Theo mặc định, kho cookie của bối cảnh thực thi hiện tại sẽ được sử dụng.

  • url

    chuỗi

    URL liên kết với cookie cần truy cập. Đối số này có thể là một URL đầy đủ, trong trường hợp đó, mọi dữ liệu theo sau đường dẫn URL (ví dụ: chuỗi truy vấn) sẽ bị bỏ qua. Nếu quyền của máy chủ lưu trữ cho URL này không được chỉ định trong tệp kê khai, thì lệnh gọi API sẽ không thành công.

CookiePartitionKey

Chrome 119 trở lên browser.* kể từ Chrome 148

Đại diện cho khoá phân vùng của cookie được phân vùng.

Thuộc tính

  • hasCrossSiteAncestor

    boolean không bắt buộc

    Chrome 130 trở lên browser.* kể từ Chrome 148

    Cho biết liệu cookie có được đặt trong bối cảnh nhiều trang web hay không. Điều này ngăn một trang web cấp cao nhất được nhúng trong bối cảnh liên trang truy cập vào cookie do trang web cấp cao nhất đặt trong bối cảnh cùng trang.

  • topLevelSite

    chuỗi không bắt buộc

    Trang web cấp cao nhất có cookie được phân vùng.

CookieStore

Biểu thị một kho lưu trữ cookie trong trình duyệt. Ví dụ: cửa sổ chế độ ẩn danh sử dụng kho lưu trữ cookie riêng biệt với cửa sổ không ẩn danh.

Thuộc tính

  • id

    chuỗi

    Giá trị nhận dạng riêng biệt của kho lưu trữ cookie.

  • tabIds

    number[]

    Giá trị nhận dạng của tất cả các thẻ trình duyệt dùng chung kho lưu trữ cookie này.

FrameDetails

Chrome 132 trở lên browser.* kể từ Chrome 148

Thông tin chi tiết để xác định khung hình.

Thuộc tính

  • documentId

    chuỗi không bắt buộc

    Giá trị nhận dạng riêng biệt của tài liệu. Nếu frameId và/hoặc tabId được cung cấp, thì các giá trị này sẽ được xác thực để khớp với tài liệu được tìm thấy theo mã tài liệu được cung cấp.

  • frameId

    number không bắt buộc

    Giá trị nhận dạng riêng biệt của khung trong thẻ.

  • tabId

    number không bắt buộc

    Giá trị nhận dạng riêng biệt của thẻ chứa khung.

OnChangedCause

Trình duyệt Chrome 44 trở lên .* kể từ Chrome 148

Lý do cơ bản khiến cookie thay đổi. Nếu một cookie được chèn hoặc xoá thông qua lệnh gọi rõ ràng đến "chrome.cookies.remove", thì "cause" sẽ là "explicit". Nếu một cookie tự động bị xoá do hết hạn, thì "cause" sẽ là "expired". Nếu một cookie bị xoá do bị ghi đè bằng ngày hết hạn đã qua, thì "cause" sẽ được đặt thành "expired_overwrite". Nếu một cookie tự động bị xoá do thu gom rác, thì "cause" sẽ là "evicted". Nếu một cookie tự động bị xoá do lệnh gọi "set" ghi đè lên cookie đó, thì "cause" sẽ là "overwrite". Hãy lên kế hoạch ứng phó cho phù hợp.

Enum

"evicted"

"expired"

"explicit"

"expired_overwrite"

"overwrite"

SameSiteStatus

Chrome 51 trở lên browser.* kể từ Chrome 148

Trạng thái "SameSite" của cookie (https://tools.ietf.org/html/draft-west-first-party-cookies). "no_restriction" tương ứng với cookie được đặt bằng "SameSite=None", "lax" tương ứng với "SameSite=Lax" và "strict" tương ứng với "SameSite=Strict". "unspecified" tương ứng với một cookie được đặt mà không có thuộc tính SameSite.

Enum

"no_restriction"

"lax"

"strict"

"unspecified"

Phương thức

get()

browser.cookies.get(
  details: CookieDetails,
): Promise<Cookie | undefined>

Truy xuất thông tin về một cookie. Nếu có nhiều cookie cùng tên cho URL đã cho, thì cookie có đường dẫn dài nhất sẽ được trả về. Đối với các cookie có cùng độ dài đường dẫn, cookie có thời gian tạo sớm nhất sẽ được trả về.

Thông số

Giá trị trả về

  • Promise<Cookie | undefined>

    Chrome 88 trở lên trình duyệt.* kể từ Chrome 148

getAll()

browser.cookies.getAll(
  details: object,
): Promise<Cookie[]>

Truy xuất tất cả cookie từ một kho lưu trữ cookie khớp với thông tin đã cho. Các cookie được trả về sẽ được sắp xếp, trong đó cookie có đường dẫn dài nhất sẽ xuất hiện trước. Nếu nhiều cookie có cùng độ dài đường dẫn, thì cookie có thời gian tạo sớm nhất sẽ được ưu tiên. Phương thức này chỉ truy xuất cookie cho những miền mà tiện ích có quyền của máy chủ lưu trữ.

Thông số

  • chi tiết

    đối tượng

    Thông tin để lọc cookie đang được truy xuất.

    • tên miền

      chuỗi không bắt buộc

      Hạn chế cookie được truy xuất đối với những cookie có miền khớp hoặc là miền con của miền này.

    • tên

      chuỗi không bắt buộc

      Lọc cookie theo tên.

    • partitionKey

      CookiePartitionKey không bắt buộc

      Chrome 119 trở lên browser.* kể từ Chrome 148

      Khoá phân vùng để đọc hoặc sửa đổi cookie bằng thuộc tính Phân vùng.

    • đường dẫn

      chuỗi không bắt buộc

      Giới hạn cookie được truy xuất ở những cookie có đường dẫn khớp chính xác với chuỗi này.

    • bảo mật

      boolean không bắt buộc

      Lọc cookie theo thuộc tính Secure.

    • phiên

      boolean không bắt buộc

      Lọc cookie phiên và cookie liên tục.

    • storeId

      chuỗi không bắt buộc

      Kho lưu trữ cookie để truy xuất cookie. Nếu bạn bỏ qua, kho cookie của bối cảnh thực thi hiện tại sẽ được sử dụng.

    • url

      chuỗi không bắt buộc

      Hạn chế cookie được truy xuất thành những cookie khớp với URL đã cho.

Giá trị trả về

  • Promise<Cookie[]>

    Chrome 88 trở lên trình duyệt.* kể từ Chrome 148

getAllCookieStores()

browser.cookies.getAllCookieStores(): Promise<CookieStore[]>

Liệt kê tất cả kho lưu trữ cookie hiện có.

Giá trị trả về

  • <CookieStore[]> hứa hẹn

    Chrome 88 trở lên trình duyệt.* kể từ Chrome 148

getPartitionKey()

Chrome 132 trở lên browser.* kể từ Chrome 148 
browser.cookies.getPartitionKey(
  details: FrameDetails,
): Promise<object>

Khoá phân vùng cho khung được chỉ định.

Thông số

Giá trị trả về

  • <object> hứa hẹn

remove()

browser.cookies.remove(
  details: CookieDetails,
): Promise<object | undefined>

Xoá cookie theo tên.

Thông số

Giá trị trả về

  • Promise<object | undefined>

    Chrome 88 trở lên trình duyệt.* kể từ Chrome 148

set()

browser.cookies.set(
  details: object,
): Promise<Cookie | undefined>

Đặt cookie bằng dữ liệu cookie đã cho; có thể ghi đè cookie tương đương nếu có.

Thông số

  • chi tiết

    đối tượng

    Thông tin chi tiết về cookie đang được đặt.

    • tên miền

      chuỗi không bắt buộc

      Miền của cookie. Nếu bạn bỏ qua, cookie sẽ trở thành cookie chỉ dành cho máy chủ lưu trữ.

    • expirationDate

      number không bắt buộc

      Ngày hết hạn của cookie, tính bằng số giây kể từ thời gian Unix. Nếu bạn bỏ qua, cookie sẽ trở thành cookie của phiên.

    • httpOnly

      boolean không bắt buộc

      Liệu cookie có nên được đánh dấu là HttpOnly hay không. Giá trị mặc định là false.

    • tên

      chuỗi không bắt buộc

      Tên của cookie. Để trống theo mặc định nếu bị bỏ qua.

    • partitionKey

      CookiePartitionKey không bắt buộc

      Chrome 119 trở lên browser.* kể từ Chrome 148

      Khoá phân vùng để đọc hoặc sửa đổi cookie bằng thuộc tính Phân vùng.

    • đường dẫn

      chuỗi không bắt buộc

      Đường dẫn của cookie. Giá trị mặc định là phần đường dẫn của tham số url.

    • sameSite

      SameSiteStatus không bắt buộc

      Chrome 51 trở lên browser.* kể từ Chrome 148

      Trạng thái cùng trang của cookie. Giá trị mặc định là "unspecified", tức là nếu bạn bỏ qua, cookie sẽ được đặt mà không chỉ định thuộc tính SameSite.

    • bảo mật

      boolean không bắt buộc

      Liệu cookie có nên được đánh dấu là An toàn hay không. Giá trị mặc định là false.

    • storeId

      chuỗi không bắt buộc

      Mã nhận dạng của kho lưu trữ cookie để đặt cookie. Theo mặc định, cookie được đặt trong kho lưu trữ cookie của bối cảnh thực thi hiện tại.

    • url

      chuỗi

      URI yêu cầu để liên kết với chế độ cài đặt cookie. Giá trị này có thể ảnh hưởng đến giá trị miền và đường dẫn mặc định của cookie được tạo. Nếu quyền của máy chủ lưu trữ cho URL này không được chỉ định trong tệp kê khai, thì lệnh gọi API sẽ không thành công.

    • value

      chuỗi không bắt buộc

      Giá trị của cookie. Để trống theo mặc định nếu bị bỏ qua.

Giá trị trả về

  • Promise<Cookie | undefined>

    Chrome 88 trở lên trình duyệt.* kể từ Chrome 148

Sự kiện

onChanged

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

Được kích hoạt khi một cookie được đặt hoặc xoá. Trong trường hợp đặc biệt, xin lưu ý rằng việc cập nhật thuộc tính của cookie được triển khai dưới dạng quy trình gồm hai bước: cookie cần cập nhật trước tiên sẽ bị xoá hoàn toàn, tạo ra thông báo có "nguyên nhân" là "ghi đè" . Sau đó, một cookie mới sẽ được ghi kèm theo các giá trị đã cập nhật, tạo ra thông báo thứ hai có "cause" (nguyên nhân) là "explicit" (rõ ràng).

Thông số

  • callback

    hàm

    Tham số callback có dạng như sau: 

    (changeInfo: object) => void

    • changeInfo

      đối tượng

      • nguyên nhân

        OnChangedCause

        Lý do cơ bản khiến cookie thay đổi.

      • bánh quy

        Cookie

        Thông tin về cookie đã được đặt hoặc xoá.

      • đã xóa

        boolean

        Đúng nếu một cookie đã bị xoá.