chrome.cookies

Nội dung mô tả

Dùng API chrome.cookies để truy vấn và sửa đổi cookie, cũng như nhận thông báo khi chúng 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ủ cho mọi máy chủ 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 phân vùng cho phép trang web đánh dấu rằng một số cookie nhất định cần được khoá dựa trên nguồn gốc của khung cấp cao nhất. 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 không được 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 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. Để biết các ví dụ khác và để được trợ giúp khi xem mã nguồn, hãy xem phần Mẫu.

Loại

Biểu thị thông tin về cookie HTTP.

Thuộc tính

  • tên miền

    string

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

  • expirationDate

    số không bắt buộc

    Ngày hết hạn của cookie dưới dạng số giây kể từ thời gian bắt đầu của hệ thống UNIX. Không được cung cấp cho cookie 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ữ 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à các tập lệnh phía máy khách không thể truy cập cookie).

  • tên

    string

    Tên của cookie.

  • partitionKey

    CookiePartitionKey không bắt buộc

    Chrome 119 trở lên

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

  • path

    string

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

  • sameSite

    SameSiteStatus

    Chrome 51 trở lên

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

  • bảo mật

    boolean

    Đúng 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 đối với các kênh bảo mật, thường là HTTPS).

  • phiên hoạt động

    boolean

    "True" nếu cookie là cookie của phiên, chứ không phải cookie cố định có ngày hết hạn.

  • storeId

    string

    Mã cửa hàng cookie chứa cookie này, như được cung cấp trong getAllCookieStores().

  • value

    string

    Giá trị của cookie.

CookieDetails

Chrome 88 trở lên

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

Thuộc tính

  • tên

    string

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

  • partitionKey

    CookiePartitionKey không bắt buộc

    Chrome 119 trở lên

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

  • storeId

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

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

  • url

    string

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

CookiePartitionKey

Chrome 119 trở lên

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

Thuộc tính

  • topLevelSite

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

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

CookieStore

Đại diện cho kho 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 từ cửa sổ không ẩn danh.

Thuộc tính

  • id

    string

    Giá trị nhận dạng duy nhất của cửa hàng bánh quy.

  • tabIds

    số[]

    Giá trị nhận dạng của mọi thẻ trình duyệt có chung kho cookie này.

OnChangedCause

Chrome 44 trở lên

Lý do cơ bản dẫn đến thay đổi của cookie. Nếu cookie đã được chèn hoặc bị xoá thông qua một lệnh gọi rõ ràng đến "chrome.cookie.remove", thì "nguyên nhân" sẽ là "phản cảm". Nếu một cookie tự động bị xoá do hết hạn, thì "nguyên nhân" sẽ là "đã hết hạn". Nếu cookie đã bị xoá do bị ghi đè do ngày hết hạn đã hết hạn, thì "nguyên nhân" sẽ được đặt thành "expiry_overwrite". Nếu một cookie bị xoá tự động do thu gom rác, thì "nguyên nhân" sẽ bị "loại bỏ". Nếu một cookie tự động bị xoá do lệnh gọi "set" ghi đè cookie đó, thì "nguyên nhân" sẽ là "ghi đè". Hãy lên kế hoạch phản hồi cho phù hợp.

Liệt kê

SameSiteStatus

Chrome 51 trở lên

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 với 'SameSite=None', 'lax' thành 'SameSite=Lax' và 'strict' thành 'SameSite=Strict'. "unspecified" tương ứng với tập hợp cookie không có thuộc tính SameSite.

Liệt kê

"no_restriction"

"lax"

Phương thức

get()

Cam kết 
chrome.cookies.get(
  details: CookieDetails,
  callback?: function,
)

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

Tham số

  • chi tiết

    CookieDetails

  • số gọi lại

    hàm không bắt buộc

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

    (cookie?: Cookie)=>void

    • bánh quy

      Cookie không bắt buộc

      Chứa thông tin chi tiết về cookie. Tham số này rỗng nếu không tìm thấy cookie như vậy.

Giá trị trả về

  • Lời hứa<Cookie|không xác định>

    Chrome 88 trở lên

    Lời hứa được hỗ trợ trong Manifest V3 trở lên nhưng lệnh gọi lại được cung cấp để có khả năng tương thích ngược. Bạn không thể sử dụng cả hai trong cùng một lệnh gọi hàm. Lời hứa sẽ được phân giải bằng cùng một loại được truyền đến lệnh gọi lại.

getAll()

Cam kết 
chrome.cookies.getAll(
  details: object,
  callback?: function,
)

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 đó những cookie có đường dẫn dài nhất sẽ được sắp xếp trước. Nếu nhiều cookie có cùng độ dài đường dẫn thì những cookie có thời gian tạo sớm nhất sẽ được ưu tiên trước. Phương thức này chỉ truy xuất cookie cho những miền mà tiện ích có quyền lưu trữ.

Tham 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

      Giới hạn cookie được truy xuất cho những cookie có miền trùng 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

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

    • path

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

      Giới hạn cookie được truy xuất cho 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 (Bảo mật) tương ứng.

    • phiên hoạt động

      boolean không bắt buộc

      Lọc ra cookie phiên so với cookie cố định.

    • storeId

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

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

    • url

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

      Giới hạn cookie được truy xuất thành những cookie phù hợp với URL đã cho.

  • số gọi lại

    hàm không bắt buộc

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

    (cookies: Cookie[])=>void

    • cookie

      Cookie[]

      Tất cả cookie hiện có và chưa hết hạn khớp với thông tin về cookie đã cho.

Giá trị trả về

  • Promise<Cookie[]>

    Chrome 88 trở lên

    Lời hứa được hỗ trợ trong Manifest V3 trở lên nhưng lệnh gọi lại được cung cấp để có khả năng tương thích ngược. Bạn không thể sử dụng cả hai trong cùng một lệnh gọi hàm. Lời hứa sẽ được phân giải bằng cùng một loại được truyền đến lệnh gọi lại.

getAllCookieStores()

Cam kết 
chrome.cookies.getAllCookieStores(
  callback?: function,
)

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

Tham số

  • số gọi lại

    hàm không bắt buộc

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

    (cookieStores: CookieStore[])=>void

    • cookieStores

      CookieStore[]

      Tất cả cửa hàng cookie hiện có.

Giá trị trả về

  • Promise<CookieStore[]>

    Chrome 88 trở lên

    Lời hứa được hỗ trợ trong Manifest V3 trở lên nhưng lệnh gọi lại được cung cấp để có khả năng tương thích ngược. Bạn không thể sử dụng cả hai trong cùng một lệnh gọi hàm. Lời hứa sẽ được phân giải bằng cùng một loại được truyền đến lệnh gọi lại.

remove()

Cam kết 
chrome.cookies.remove(
  details: CookieDetails,
  callback?: function,
)

Xoá cookie theo tên.

Tham số

  • chi tiết

    CookieDetails

  • số gọi lại

    hàm không bắt buộc

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

    (details?: object)=>void

    • chi tiết

      đối tượng không bắt buộc

      Chứa thông tin chi tiết về cookie đã bị xoá. Nếu không xoá được vì bất kỳ lý do gì, giá trị này sẽ là "rỗng" và runtime.lastError sẽ được đặt.

      • tên

        string

        Tên của cookie đã bị xoá.

      • partitionKey

        CookiePartitionKey không bắt buộc

        Chrome 119 trở lên

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

      • storeId

        string

        Mã của kho lưu trữ cookie mà từ đó cookie bị xoá.

      • url

        string

        URL được liên kết với cookie đã bị xoá.

Giá trị trả về

  • Promise<object|undefined>

    Chrome 88 trở lên

    Lời hứa được hỗ trợ trong Manifest V3 trở lên nhưng lệnh gọi lại được cung cấp để có khả năng tương thích ngược. Bạn không thể sử dụng cả hai trong cùng một lệnh gọi hàm. Lời hứa sẽ được phân giải bằng cùng một loại được truyền đến lệnh gọi lại.

set()

Cam kết 
chrome.cookies.set(
  details: object,
  callback?: function,
)

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

Tham 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ị bỏ qua, cookie này sẽ trở thành cookie chỉ lưu trữ.

    • expirationDate

      số không bắt buộc

      Ngày hết hạn của cookie dưới dạng số giây kể từ thời gian bắt đầu của hệ thống UNIX. Nếu bị bỏ qua, cookie này sẽ trở thành cookie phiên.

    • httpOnly

      boolean không bắt buộc

      Liệu cookie có đượ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

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

    • path

      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

      Trạng thái cùng trang web của cookie. Giá trị mặc định là "không được chỉ định", tức là nếu bị 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ó được đánh dấu là Bảo mật hay không. Giá trị mặc định là false.

    • storeId

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

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

    • url

      string

      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 miền mặc định và các giá trị đường dẫn của cookie đã tạo. Nếu quyền của máy chủ cho URL này không được chỉ định trong tệp kê khai, 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.

  • số gọi lại

    hàm không bắt buộc

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

    (cookie?: Cookie)=>void

    • bánh quy

      Cookie không bắt buộc

      Chứa thông tin chi tiết về cookie đã được đặt. Nếu không thiết lập được vì bất kỳ lý do gì, giá trị này sẽ là "rỗng" và runtime.lastError sẽ được đặt.

Giá trị trả về

  • Lời hứa<Cookie|không xác định>

    Chrome 88 trở lên

    Lời hứa được hỗ trợ trong Manifest V3 trở lên nhưng lệnh gọi lại được cung cấp để có khả năng tương thích ngược. Bạn không thể sử dụng cả hai trong cùng một lệnh gọi hàm. Lời hứa sẽ được phân giải bằng cùng một loại được truyền đến lệnh gọi lại.

Sự kiện

onChanged

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

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

Tham số

  • số gọi lại

    hàm

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

    (changeInfo: object)=>void

    • changeInfo

      đối tượng

      • Lý do cơ bản dẫn đến thay đổi của cookie.

      • bánh quy

        Cookie

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

      • đã xóa

        boolean

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