Nội dung mô tả
Sử dụng API chrome.contentSettings
để thay đổi các chế độ cài đặt kiểm soát việc trang web có thể sử dụng các tính năng như cookie, JavaScript và trình bổ trợ hay không. Nói chung, chế độ cài đặt nội dung cho phép bạn tuỳ chỉnh hành vi của Chrome trên từng trang web thay vì trên toàn hệ thống.
Quyền
contentSettings
Bạn phải khai báo quyền "contentSettings"
trong tệp kê khai của tiện ích để sử dụng API này. Ví dụ:
{
"name": "My extension",
...
"permissions": [
"contentSettings"
],
...
}
Khái niệm và cách sử dụng
Mẫu cài đặt nội dung
Bạn có thể sử dụng các mẫu để chỉ định những trang web chịu ảnh hưởng của mỗi chế độ cài đặt nội dung. Ví dụ: https://*.youtube.com/*
chỉ định youtube.com và tất cả các miền con của miền đó. Cú pháp cho mẫu cài đặt nội dung cũng giống như mẫu so khớp, nhưng có một số điểm khác biệt:
- Đối với các URL
http
,https
vàftp
, đường dẫn phải là ký tự đại diện (/*
). Đối với các URLfile
, đường dẫn phải được chỉ định đầy đủ và không được chứa ký tự đại diện. - Trái ngược với mẫu khớp, mẫu cài đặt nội dung có thể chỉ định số cổng. Nếu số cổng được chỉ định, mẫu chỉ so khớp các trang web có cổng đó. Nếu không có số cổng nào được chỉ định, thì mẫu sẽ khớp với tất cả các cổng.
Mức độ ưu tiên của mẫu
Khi nhiều quy tắc cài đặt nội dung áp dụng cho một trang web nhất định, quy tắc có mẫu cụ thể hơn sẽ được ưu tiên.
Ví dụ: các mẫu sau đây được sắp xếp theo mức độ ưu tiên:
https://www.example.com/*
https://*.example.com/*
(khớp example.com và tất cả các miền con)<all_urls>
(phù hợp với mọi URL)
Có 3 loại ký tự đại diện ảnh hưởng đến mức độ cụ thể của một mẫu:
- Ký tự đại diện trong cổng (ví dụ:
https://www.example.com:*/*
) - Ký tự đại diện trong giao thức (ví dụ:
*://www.example.com:123/*
) - Ký tự đại diện trong tên máy chủ (ví dụ:
https://*.example.com:123/*
)
Nếu một mẫu cụ thể hơn mẫu khác trong một phần nhưng ít cụ thể hơn ở phần khác, thì các phần khác nhau sẽ được kiểm tra theo thứ tự sau: tên máy chủ, giao thức, cổng. Ví dụ: các mẫu sau đây được sắp xếp theo mức độ ưu tiên:
https://www.example.com:*/*
Chỉ định tên máy chủ và giao thức.*:/www.example.com:123/*
Không cao vì mặc dù chỉ định tên máy chủ nhưng không chỉ định lược đồ.https://*.example.com:123/*
Thấp hơn vì mặc dù chỉ định cổng và giao thức, nhưng tên máy chủ lại có ký tự đại diện.
Mẫu chính và phụ
URL được xem xét khi quyết định chế độ cài đặt nội dung cần áp dụng sẽ phụ thuộc vào loại nội dung.
Ví dụ: đối với contentSettings.notifications
, chế độ cài đặt được dựa trên URL xuất hiện trong thanh địa chỉ. URL này được gọi là URL "chính".
Một số loại nội dung có thể xem xét URL bổ sung. Ví dụ: việc một trang web có được phép đặt contentSettings.cookies
hay không được quyết định dựa trên URL của yêu cầu HTTP (là URL chính trong trường hợp này) cũng như URL xuất hiện trong thanh địa chỉ (còn gọi là URL "phụ").
Nếu nhiều quy tắc có mẫu chính và phụ, thì quy tắc có mẫu chính cụ thể hơn sẽ được ưu tiên. Nếu có nhiều quy tắc có cùng một mẫu chính, thì quy tắc có mẫu phụ cụ thể hơn sẽ được ưu tiên. Ví dụ: danh sách các cặp mẫu chính/phụ sau đây được sắp xếp theo mức độ ưu tiên:
Quyền ưu tiên | Mẫu chính | Hình mở khoá |
---|---|---|
1 | https://www.moose.com/* , | https://www.wombat.com/* |
2 | https://www.moose.com/* , | <all_urls> |
3 | <all_urls> , | https://www.wombat.com/* |
4 | <all_urls> , | <all_urls> |
Giá trị nhận dạng tài nguyên
Giá trị nhận dạng tài nguyên cho phép bạn chỉ định các chế độ cài đặt nội dung cho các loại phụ cụ thể của loại nội dung.
Hiện tại, loại nội dung duy nhất hỗ trợ giá trị nhận dạng tài nguyên là contentSettings.plugins
, trong đó giá trị nhận dạng tài nguyên xác định một trình bổ trợ cụ thể. Khi áp dụng chế độ cài đặt nội dung, trước tiên, hệ thống sẽ kiểm tra chế độ cài đặt cho trình bổ trợ cụ thể. Nếu không tìm thấy chế độ cài đặt nào cho một trình bổ trợ cụ thể, thì chế độ cài đặt nội dung chung cho các trình bổ trợ sẽ được kiểm tra.
Ví dụ: nếu một quy tắc cài đặt nội dung có giá trị nhận dạng tài nguyên adobe-flash-player
và mẫu <all_urls>
, thì quy tắc này sẽ được ưu tiên hơn một quy tắc không có giá trị nhận dạng tài nguyên và mẫu https://www.example.com/*
, ngay cả khi mẫu đó cụ thể hơn.
Bạn có thể lấy danh sách giá trị nhận dạng tài nguyên cho một loại nội dung bằng cách gọi phương thức contentSettings.ContentSetting.getResourceIdentifiers()
. Danh sách được trả về có thể thay đổi theo nhóm trình bổ trợ đã cài đặt trên máy của người dùng. Tuy nhiên, Chrome sẽ cố gắng giữ cho các giá trị nhận dạng ổn định sau các bản cập nhật trình bổ trợ.
Ví dụ
Để dùng thử API này, hãy cài đặt ví dụ về API contentSettings trong kho lưu trữ chrome-extension-samples.
Loại
AutoVerifyContentSetting
Liệt kê
"block"
CameraContentSetting
Liệt kê
"block"
ClipboardContentSetting
Liệt kê
"block"
ContentSetting
Thuộc tính
-
xóa
void
Cam kếtXoá tất cả quy tắc cài đặt nội dung do tiện ích này đặt.
Hàm
clear
sẽ có dạng như sau:(details: object, callback?: function) => {...}
-
chi tiết
đối tượng
-
xác định phạm vi của thứ nguyên.
Phạm vi không bắt buộc
Nơi xoá chế độ cài đặt (mặc định: thông thường).
-
-
số gọi lại
hàm không bắt buộc
Tham số
callback
sẽ có dạng như sau:() => void
-
giá trị trả về
Promise<void>
Chrome 96 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 để 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.
-
-
get
void
Cam kếtLấy chế độ cài đặt nội dung hiện tại của một cặp URL nhất định.
Hàm
get
sẽ có dạng như sau:(details: object, callback?: function) => {...}
-
chi tiết
đối tượng
-
ẩn danh
boolean không bắt buộc
Xem có kiểm tra chế độ cài đặt nội dung cho phiên ẩn danh hay không. (mặc định là sai)
-
primaryUrl
string
URL chính cần truy xuất chế độ cài đặt nội dung. Xin lưu ý rằng ý nghĩa của URL chính phụ thuộc vào loại nội dung.
-
resourceIdentifier
ResourceIdentifier không bắt buộc
Giá trị nhận dạng cụ thể hơn của loại nội dung cần truy xuất chế độ cài đặt.
-
secondaryUrl
chuỗi không bắt buộc
URL phụ cần truy xuất chế độ cài đặt nội dung. Giá trị mặc định là URL chính. Xin lưu ý rằng ý nghĩa của URL phụ phụ thuộc vào loại nội dung và không phải loại nội dung nào cũng sử dụng URL phụ.
-
-
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
-
cài đặt
T
Chế độ cài đặt nội dung. Xem nội dung mô tả của từng đối tượng Contentsetting để biết các giá trị có thể có.
-
-
-
giá trị trả về
Promise<object>
Chrome 96 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 để 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.
-
-
getResourceIdentifiers
void
Cam kếtHàm
getResourceIdentifiers
sẽ có dạng như sau:(callback?: function) => {...}
-
số gọi lại
hàm không bắt buộc
Tham số
callback
sẽ có dạng như sau:(resourceIdentifiers?: ResourceIdentifier[]) => void
-
resourceIdentifiers
ResourceIdentifier[] không bắt buộc
Danh sách giá trị nhận dạng tài nguyên cho loại nội dung này hoặc
undefined
nếu loại nội dung này không sử dụng giá trị nhận dạng tài nguyên.
-
-
giá trị trả về
Promise<ResourceIdentifier[]>
Chrome 96 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 để 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
void
Cam kếtÁp dụng quy tắc cài đặt nội dung mới.
Hàm
set
sẽ có dạng như sau:(details: object, callback?: function) => {...}
-
chi tiết
đối tượng
-
primaryPattern
string
Mẫu cho URL chính. Để biết chi tiết về định dạng của mẫu, hãy xem Mẫu cài đặt nội dung.
-
resourceIdentifier
ResourceIdentifier không bắt buộc
Giá trị nhận dạng tài nguyên cho loại nội dung.
-
xác định phạm vi của thứ nguyên.
Phạm vi không bắt buộc
Nơi đặt chế độ cài đặt (mặc định: thông thường).
-
secondaryPattern
chuỗi không bắt buộc
Mẫu cho URL phụ. Mặc định khớp với tất cả URL. Để biết chi tiết về định dạng của một mẫu, hãy xem Mẫu cài đặt nội dung.
-
cài đặt
Bất kỳ
Chế độ cài đặt do quy tắc này áp dụng. Xem nội dung mô tả của từng đối tượng Contentsetting để biết các giá trị có thể có.
-
-
số gọi lại
hàm không bắt buộc
Tham số
callback
sẽ có dạng như sau:() => void
-
giá trị trả về
Promise<void>
Chrome 96 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 để 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.
-
CookiesContentSetting
Liệt kê
"block"
"session_only"
FullscreenContentSetting
Giá trị
ImagesContentSetting
Liệt kê
"block"
JavascriptContentSetting
Liệt kê
"block"
LocationContentSetting
Liệt kê
"block"
MicrophoneContentSetting
Liệt kê
"block"
MouselockContentSetting
Giá trị
MultipleAutomaticDownloadsContentSetting
Liệt kê
"block"
NotificationsContentSetting
Liệt kê
"block"
PluginsContentSetting
Giá trị
"block"
PopupsContentSetting
Liệt kê
"block"
PpapiBrokerContentSetting
Giá trị
"block"
ResourceIdentifier
Loại nội dung duy nhất sử dụng giá trị nhận dạng tài nguyên là contentSettings.plugins
. Để biết thêm thông tin, hãy xem phần Giá trị nhận dạng tài nguyên.
Thuộc tính
-
description
chuỗi không bắt buộc
Nội dung mô tả tài nguyên mà con người có thể đọc được.
-
id
string
Giá trị nhận dạng tài nguyên cho loại nội dung nhất định.
Scope
Phạm vi của ContentCài đặt. Một trong các regular
: chế độ cài đặt cho hồ sơ thông thường (kế thừa hồ sơ ẩn danh này nếu không bị ghi đè ở nơi khác), incognito\_session\_only
: chế độ cài đặt cho hồ sơ ẩn danh mà bạn chỉ có thể đặt trong phiên ẩn danh và sẽ bị xoá khi phiên truy cập ẩn danh kết thúc (ghi đè chế độ cài đặt thông thường).
Liệt kê
"regular"
Thuộc tính
automaticDownloads
Liệu có cho phép các trang web tự động tải nhiều tệp xuống hay không. Một trong allow
: Cho phép các trang web tự động tải nhiều tệp xuống,block
: Không cho phép các trang web tự động tải nhiều tệp xuống, ask
: Hỏi khi một trang web muốn tự động tải các tệp xuống sau tệp đầu tiên.
Mặc định là ask
.
URL chính là URL của khung cấp cao nhất. URL phụ không được sử dụng.
autoVerify
Liệu có cho phép các trang web sử dụng API Mã thông báo trạng thái riêng tư hay không. Một trong allow
: Cho phép các trang web sử dụng API Mã thông báo trạng thái riêng tư, block
: Chặn các trang web sử dụng API Mã thông báo trạng thái riêng tư.
Mặc định là allow
.
URL chính là URL của khung cấp cao nhất. URL phụ không được sử dụng. LƯU Ý: Khi gọi set()
, mẫu chính phải là .
camera
Liệu có cho phép các trang web truy cập vào camera hay không. Một trong allow
: Cho phép các trang web truy cập vào camera, block
: Không cho phép các trang web truy cập vào camera, ask
: Hỏi khi một trang web muốn truy cập vào camera.
Mặc định là ask
.
URL chính là URL của tài liệu đã yêu cầu quyền truy cập vào máy ảnh. URL phụ không được sử dụng.
LƯU Ý: Cài đặt 'cho phép' không hợp lệ nếu cả hai mẫu đều là ''.
clipboard
Liệu có cho phép các trang web truy cập vào bảng nhớ tạm thông qua các chức năng nâng cao của API Bảng nhớ tạm không đồng bộ hay không. Chức năng "Nâng cao" bao gồm mọi chức năng ngoài khả năng viết các định dạng tích hợp sau một cử chỉ của người dùng, tức là khả năng đọc, khả năng ghi các định dạng tuỳ chỉnh và khả năng viết mà không cần cử chỉ của người dùng. Một trong allow
: Cho phép các trang web sử dụng chức năng nâng cao của bảng nhớ tạm, block
: Không cho phép các trang web sử dụng chức năng nâng cao của bảng nhớ tạm, ask
: Hỏi khi một trang web muốn dùng các tính năng nâng cao của bảng nhớ tạm.
Mặc định là ask
.
URL chính là URL của tài liệu yêu cầu quyền truy cập vào bảng nhớ tạm. URL phụ không được sử dụng.
cookies
Liệu có cho phép các trang web đặt cookie và dữ liệu cục bộ khác hay không. Một trong các giá trị allow
: Chấp nhận cookie, block
: Chặn cookie, session\_only
: Chỉ chấp nhận cookie cho phiên hiện tại.
Mặc định là allow
.
URL chính là URL đại diện cho nguồn gốc cookie. URL phụ là URL của khung cấp cao nhất.
fullscreen
Không dùng nữa. Không còn bất kỳ ảnh hưởng nào. Giờ đây, quyền truy cập chế độ toàn màn hình sẽ tự động được cấp cho tất cả trang web. Giá trị luôn là allow
.
images
Liệu có hiển thị hình ảnh hay không. Một trong allow
: Cho thấy hình ảnh, block
: Không hiện hình ảnh.
Mặc định là allow
.
URL chính là URL của khung cấp cao nhất. URL phụ là URL của hình ảnh.
javascript
Liệu có chạy JavaScript hay không. Một trong các allow
: Chạy JavaScript, block
: Không chạy JavaScript.
Mặc định là allow
.
URL chính là URL của khung cấp cao nhất. URL phụ không được sử dụng.
location
Liệu có cho phép định vị vị trí hay không. Một trong allow
: Cho phép các trang web theo dõi vị trí thực của bạn, block
: Không cho phép các trang web theo dõi vị trí thực của bạn, ask
: Hỏi trước khi cho phép các trang web theo dõi vị trí thực của bạn.
Mặc định là ask
.
URL chính là URL của tài liệu yêu cầu dữ liệu vị trí. URL phụ là URL của khung cấp cao nhất (có thể khác hoặc không khác với URL yêu cầu).
microphone
Liệu có cho phép các trang web truy cập vào micrô hay không. Một trong các lựa chọn sau: allow
: Cho phép các trang web truy cập vào micrô, block
: Không cho phép các trang web truy cập vào micrô, ask
: Hỏi khi một trang web muốn truy cập vào micrô.
Mặc định là ask
.
URL chính là URL của tài liệu yêu cầu quyền truy cập vào micrô. URL phụ không được sử dụng.
LƯU Ý: Cài đặt 'cho phép' không hợp lệ nếu cả hai mẫu đều là ''.
mouselock
Không dùng nữa. Không còn bất kỳ ảnh hưởng nào. Giờ đây, quyền khoá chuột sẽ được cấp tự động cho tất cả trang web. Giá trị luôn là allow
.
notifications
Liệu có cho phép các trang web hiển thị thông báo trên màn hình hay không. Một trong các lựa chọn sau: allow
: Cho phép các trang web hiển thị thông báo trên màn hình, block
: Không cho phép các trang web hiển thị thông báo trên màn hình, ask
: Hỏi khi một trang web muốn hiển thị thông báo trên màn hình.
Mặc định là ask
.
URL chính là URL của tài liệu muốn hiển thị thông báo. URL phụ không được sử dụng.
plugins
Không dùng nữa. Khi tính năng hỗ trợ Flash trong Chrome 88 bị loại bỏ, quyền này sẽ không có hiệu lực nữa. Giá trị luôn là block
. Các lệnh gọi đến set()
và clear()
sẽ bị bỏ qua.
popups
Liệu có cho phép các trang web hiển thị cửa sổ bật lên hay không. Một trong allow
: Cho phép các trang web hiển thị cửa sổ bật lên,
block
: Không cho phép các trang web hiển thị cửa sổ bật lên.
Mặc định là block
.
URL chính là URL của khung cấp cao nhất. URL phụ không được sử dụng.
unsandboxedPlugins
Không dùng nữa. Trước đây, kiểm soát việc có cho phép các trang web chạy plugin không được đặt hộp cát hay không, tuy nhiên, với quy trình Flash môi giới bị loại bỏ trong Chrome 88, quyền này không còn có tác dụng nữa. Giá trị luôn là block
. Các lệnh gọi đến set()
và clear()
sẽ bị bỏ qua.