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 các cookie này 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 bất kỳ máy chủ nào có cookie 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 cần được khoá dựa vào nguồn gốc của khung cấp cao nhất. Ví dụ: điều này có nghĩa là 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. Chiến lược phát hành đĩa đơn
Bạn có thể sử 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 cho tiện ích, hãy xem Bộ nhớ và cookie.
Ví dụ
Bạn có thể tìm thấy một ví dụ đơn giản về việc sử dụng API cookie trong examples/api/cookies. Để xem 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
Cookie
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ữ 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à các tập lệnh phía máy khách không thể truy cập vào cookie đó).
-
tên
string
Tên của cookie.
-
partitionKey
CookiePartitionKey không bắt buộc
Chrome 119 trở lênKhoá phân vùng để đọc hoặc sửa đổi cookie bằng thuộc tính Được phân vùng.
-
đường dẫn
string
Đường dẫn của cookie.
-
sameSiteChrome 51 trở lên
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 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 chỉ giới hạn ở các kênh bảo mật, thường là HTTPS).
-
phiên
boolean
Đúng nếu cookie là cookie phiên, trái ngược với cookie cố định có ngày hết hạn.
-
storeId
string
Mã nhận dạng của 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
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ênKhoá 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 cửa hàng cookie mà bạn 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 được liên kết với cookie để truy cập. Đối số này có thể là một URL đầy đủ. Trong trường hợp đó, mọi dữ liệu đi 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ủ 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
Đạ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
Đang chờ xử lýCho biết liệu cookie có được đặt trong ngữ cảnh nhiều trang web hay không. Điều này ngăn không cho trang web cấp cao nhất được nhúng trong ngữ cảnh nhiều trang web truy cập vào cookie do trang web cấp cao nhất đặt trong cùng một trang web.
-
topLevelSite
chuỗi không bắt buộc
Trang web cấp cao nhất có chứa cookie được phân vùng.
CookieStore
Đại diện cho một cửa hàng cookie trong trình duyệt. Ví dụ: cửa sổ chế độ ẩn danh sử dụng một kho lưu trữ cookie riêng biệt với 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 tất cả thẻ trình duyệt chia sẻ kho cookie này.
OnChangedCause
Lý do cơ bản dẫn đến sự thay đổi của cookie. Trường hợp cookie được chèn hoặc xoá thông qua lệnh gọi rõ ràng đến "chrome.cookies.remove", "generate" (nguyên nhân) sẽ là "rõ ràng". Nếu một cookie tự động bị xoá do hết hạn, thì "nguyên nhân" sẽ "hết hạn". Nếu một cookie bị xoá do ngày hết hạn đã hết hạn ghi đè cookie, thì "nguyên nhân" sẽ được đặt thành "expiry_overwrite". Nếu cookie tự động bị xoá do việc thu thập rác, "nguyên nhân" sẽ bị "loại bỏ". Nếu cookie bị xoá tự động do "set" gọi điều đó là ghi đè lên, "nguyên nhân" sẽ bị "ghi đè". Lập kế hoạch ứng phó cho phù hợp.
Enum
SameSiteStatus
'SameSite' của cookie (https://tools.ietf.org/html/draft-west-first-party-cookies). "no_restriction" tương ứng với một cookie được đặt có 'SameSite=None', 'lax' thành 'SameSite=Lax' và 'strict' thành 'SameSite=Strict'. "không xác định" tương ứng với một tập hợp cookie không có thuộc tính SameSite.
Enum
Phương thức
get()
chrome.cookies.get(
details: CookieDetails,
callback?: function,
)
Truy xuất thông tin về một cookie. Nếu một URL nhất định có nhiều cookie cùng tên 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 | không xác định>
Chrome 88 trở lênLời hứa được hỗ trợ trong Manifest V3 trở lên nhưng lệnh gọi lại được cung cấp cho 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. Chiến lược phát hành đĩa đơn Promise phân giải cùng loại được truyền đến lệnh gọi lại.
getAll()
chrome.cookies.getAll(
details: object,
callback?: function,
)
Truy xuất tất cả cookie từ một kho lưu trữ cookie duy nhất khớp với thông tin đã cho. Cookie được trả về sẽ được sắp xếp, với những cookie có đường dẫn dài nhất 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. Phương thức này chỉ truy xuất cookie cho các miền mà tiện ích có quyền của máy chủ.
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 ở những cookie có miền khớp hoặc là miền con của cookie 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ênKhoá phân vùng để đọc hoặc sửa đổi cookie bằng thuộc tính Được 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 tài sản Bảo mật.
-
phiên
boolean không bắt buộc
Lọc ra cookie phiên và cookie lâu dài.
-
storeId
chuỗi không bắt buộc
Kho lưu trữ cookie để truy xuất cookie từ đó. Nếu bạn bỏ qua, kho cookie của ngữ cảnh thực thi hiện tại sẽ được dùng.
-
url
chuỗi không bắt buộc
Hạn chế cookie được truy xuất ở những cookie khớ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ó, chưa hết hạn khớp với thông tin cookie đã cung cấp.
-
Giá trị trả về
-
Promise<Cookie[]>
Chrome 88 trở lênLời hứa được hỗ trợ trong Manifest V3 trở lên nhưng lệnh gọi lại được cung cấp cho 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. Chiến lược phát hành đĩa đơn Promise phân giải cùng loại được truyền đến lệnh gọi lại.
getAllCookieStores()
chrome.cookies.getAllCookieStores(
callback?: function,
)
Liệt kê tất cả cửa hàng bánh quy hiện có.
Thông 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
Tất cả các cửa hàng bánh quy hiện có.
-
Giá trị trả về
-
Promise<CookieStore[]>
Chrome 88 trở lênLời hứa được hỗ trợ trong Manifest V3 trở lên nhưng lệnh gọi lại được cung cấp cho 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. Chiến lược phát hành đĩa đơn Promise phân giải cùng loại được truyền đến lệnh gọi lại.
remove()
chrome.cookies.remove(
details: CookieDetails,
callback?: function,
)
Xoá cookie theo tên.
Thông số
-
chi tiết
-
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 cứ lý do gì, giá trị này sẽ là "null" và giá trị
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ênKhoá 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 cửa hàng cookie mà từ đó cookie đã bị xoá.
-
url
string
URL liên kết với cookie đã bị loại bỏ.
-
-
Giá trị trả về
-
Promise<object | undefined>
Chrome 88 trở lênLời hứa được hỗ trợ trong Manifest V3 trở lên nhưng lệnh gọi lại được cung cấp cho 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. Chiến lược phát hành đĩa đơn Promise phân giải cùng loại được truyền đến lệnh gọi lại.
set()
chrome.cookies.set(
details: object,
callback?: function,
)
Đặt cookie với dữ liệu cookie nhất định; 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ị bỏ qua, cookie này sẽ trở thành cookie chỉ dành cho máy 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 của 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ạn bỏ qua mục này.
-
partitionKey
CookiePartitionKey không bắt buộc
Chrome 119 trở lênKhoá phân vùng để đọc hoặc sửa đổi cookie bằng thuộc tính Được 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ênTrạ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, thì 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 cửa hàng cookie mà bạn muốn đặt cookie. Theo mặc định, cookie được đặt trong kho 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 cài đặt của cookie. Giá trị này có thể ảnh hưởng đến miền và giá trị đường dẫn mặc định của cookie đã 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ạn bỏ qua mục này.
-
-
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 bạn không đặt được vì bất cứ lý do gì, giá trị này sẽ là "null" và giá trị
runtime.lastError
sẽ được đặt.
-
Giá trị trả về
-
Promise<Cookie | không xác định>
Chrome 88 trở lênLời hứa được hỗ trợ trong Manifest V3 trở lên nhưng lệnh gọi lại được cung cấp cho 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. Chiến lược phát hành đĩa đơn Promise phân giải cùng 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 trường hợp đặc biệt, hãy lưu ý rằng việc cập nhật các thuộc tính của cookie được triển khai theo quy trình 2 bước: trước tiên, cookie cần cập nhật sẽ được xoá hoàn toàn, tạo ra một thông báo có "nguyên nhân" trong số "ghi đè" của Google. Sau đó, một cookie mới được ghi cùng với các giá trị đã cập nhật, tạo ra thông báo thứ hai kèm theo "nguyên nhân" " tục tĩu".
Thông số
-
lệnh gọi lại
hàm
Tham số
callback
sẽ có dạng như sau:(changeInfo: object) => void
-
changeInfo
đối tượng
-
nguyên nhân
Lý do cơ bản dẫn đến sự thay đổi của cookie.
-
bánh quy
Thông tin về cookie được đặt hoặc bị xoá.
-
đã xóa
boolean
Đúng nếu cookie đã bị xoá.
-
-