Trang này được dịch bởi Cloud Translation API.

chrome.contentSettings

Mô tả

Dùng API chrome.contentSettings để thay đổi 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, các chế độ cài đặt nội dung cho phép bạn tuỳ chỉnh hành vi của Chrome theo từng trang web thay vì trên toàn bộ.

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. Ví dụ:

{
  "name": "My extension",
  ...
  "permissions": [
    "contentSettings"
  ],
  ...
}

Khái niệm và cách sử dụng

Mẫu chế độ cài đặt nội dung

Bạn có thể sử dụng mẫu để chỉ định những trang web mà mỗi chế độ cài đặt nội dung ảnh hưởng đến. Ví dụ: https://*.youtube.com/* chỉ định youtube.com và tất cả miền con của miền này. Cú pháp cho mẫu cài đặt nội dung giống như mẫu khớp, chỉ có một vài điểm khác biệt:

Đối với URL http, https và ftp, đường dẫn phải là ký tự đại diện (/*). Đối với URL file, đườ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 so khớp, mẫu chế độ cài đặt nội dung có thể chỉ định số cổng. Nếu bạn chỉ định số cổng, thì mẫu này chỉ khớp với những trang web có cổng đó. Nếu bạn không chỉ định số cổng, 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 thứ tự ưu tiên:

https://www.example.com/*
https://*.example.com/* (khớp với example.com và tất cả miền con)
<all_urls> (khớp với mọi URL)

Có ba 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 giản đồ (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ột mẫu khác ở một phần nhưng lại ít cụ thể hơn ở một 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 bằng vì mặc dù tên máy chủ chỉ định rõ nhưng lại không chỉ định lược đồ.
https://*.example.com:123/* Thấp hơn vì mặc dù chỉ định cổng và lược đồ, nhưng trong tên máy chủ có một ký tự đại diện.

Mẫu chính và phụ

URL được tính đến khi quyết định áp dụng chế độ cài đặt nội dung nào tuỳ thuộc vào loại nội dung. Ví dụ: đối với chế độ cài đặt contentSettings.notifications, chế độ cài đặt 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ể tính đến các URL khác. 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 hiển thị trong thanh địa chỉ (được gọi là URL "phụ").

Nếu nhiều quy tắc có mẫu chính và mẫu 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ẫ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	Mẫu phụ
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>`

Không hỗ trợ mẫu phụ cho chế độ cài đặt nội dung hình ảnh.

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 chế độ cài đặt nội dung cho các loại nội dung phụ cụ thể. 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 sẽ 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, chế độ cài đặt cho trình bổ trợ cụ thể sẽ được kiểm tra. Nếu không tìm thấy chế độ cài đặt nào cho trình bổ trợ cụ thể, thì hệ thống sẽ kiểm tra chế độ cài đặt nội dung chung cho trình bổ trợ.

Ví dụ: nếu 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 đó sẽ được ưu tiên hơn 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 bộ trình bổ trợ đã cài đặt trên máy của người dùng, nhưng Chrome cố gắng giữ cho giá trị nhận dạng ổn định trong 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

Chrome 113 trở lên

Enum

"khối"

CameraContentSetting

Chrome 46 trở lên

Enum

"khối"

ClipboardContentSetting

Chrome 121 trở lên

Enum

"khối"

"ask"

ContentSetting

Thuộc tính

xóa

void

Hứa

Xoá tất cả quy tắc cài đặt nội dung do tiện ích này đặt.

Hàm clear có dạng như sau:
```
(details: object, callback?: function) => {...}
```
- chi tiết
  
  đối tượng
  - phạm vi
    
    Phạm vi không bắt buộc
    
    Nơi xoá chế độ cài đặt (mặc định: thông thường).
- lệnh gọi lại
  
  hàm không bắt buộc
  
  Tham số callback có dạng như sau:
```
() => void
```
- returns
  Promise<void>
  
  Chrome 96 trở lên
  
  Lời hứa được hỗ trợ trong Tệp kê khai V3 trở lên, nhưng lệnh gọi lại được cung cấp để đảm bảo 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ẽ phân giải bằng cùng một loại được truyền đến lệnh gọi lại.
get

void

Promise

Lấy chế độ cài đặt nội dung hiện tại cho một cặp URL nhất định.

Hàm get có dạng như sau:
```
(details: object, callback?: function) => {...}
```
- chi tiết
  
  đối tượng
  - ẩn danh
    
    boolean không bắt buộc
    
    Liệu có nên kiểm tra chế độ cài đặt nội dung cho một phiên duyệt web ẩn danh hay không. (mặc định là false)
  - primaryUrl
    
    chuỗi
    
    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 về 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ụ mà chế độ cài đặt nội dung sẽ được truy xuất. Giá trị mặc định là URL chính. Xin lưu ý rằng ý nghĩa của URL 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ụ.
- lệnh gọi lại
  
  hàm không bắt buộc
  
  Tham số callback 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. Hãy xem nội dung mô tả về từng đối tượng ContentSetting để biết các giá trị có thể có.
- returns
  Promise<object>
  
  Chrome 96 trở lên
  
  Lời hứa được hỗ trợ trong Tệp kê khai V3 trở lên, nhưng lệnh gọi lại được cung cấp để đảm bảo 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ẽ phân giải bằng cùng một loại được truyền đến lệnh gọi lại.
getResourceIdentifiers

void

Promise

Hàm getResourceIdentifiers có dạng như sau:
```
(callback?: function) => {...}
```
- lệnh gọi lại
  
  hàm không bắt buộc
  
  Tham số callback 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.
- returns
  Promise<ResourceIdentifier[]>
  
  Chrome 96 trở lên
  
  Lời hứa được hỗ trợ trong Tệp kê khai V3 trở lên, nhưng lệnh gọi lại được cung cấp để đảm bảo 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 được phân giải cùng một loại được truyền đến lệnh gọi lại.
đặt

void

Hứa

Áp dụng một quy tắc cài đặt nội dung mới.

Hàm set có dạng như sau:
```
(details: object, callback?: function) => {...}
```
- chi tiết
  
  đối tượng
  - primaryPattern
    
    chuỗi
    
    Mẫu cho URL chính. Để biết thông tin chi tiết về định dạng mẫu, hãy xem phần 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.
  - phạm vi
    
    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 mẫu, hãy xem Mẫu cài đặt nội dung.
  - cài đặt
    
    bất kỳ
    
    Chế độ cài đặt do quy tắc này áp dụng. Xem thông tin mô tả về từng đối tượng Cài đặt nội dung riêng lẻ để biết các giá trị có thể có.
- lệnh gọi lại
  
  hàm không bắt buộc
  
  Tham số callback có dạng như sau:
```
() => void
```
- returns
  Promise<void>
  
  Chrome 96 trở lên
  
  Lời hứa được hỗ trợ trong Tệp kê khai V3 trở lên, nhưng lệnh gọi lại được cung cấp để đảm bảo 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ẽ phân giải bằng cùng một loại được truyền đến lệnh gọi lại.

CookiesContentSetting

Chrome 44 trở lên

Enum

"session_only"

FullscreenContentSetting

Chrome 44 trở lên

Giá trị

ImagesContentSetting

Chrome 44 trở lên

Enum

"khối"

JavascriptContentSetting

Chrome 44 trở lên

Enum

"khối"

LocationContentSetting

Chrome 44 trở lên

Enum

"khối"

MicrophoneContentSetting

Chrome 46 trở lên

Enum

"khối"

MouselockContentSetting

Chrome 44 trở lên

Giá trị

MultipleAutomaticDownloadsContentSetting

Chrome 44 trở lên

Enum

"khối"

NotificationsContentSetting

Chrome 44 trở lên

Enum

"khối"

PluginsContentSetting

Chrome 44 trở lên

Giá trị

"khối"

PopupsContentSetting

Chrome 44 trở lên

Enum

"khối"

PpapiBrokerContentSetting

Chrome 44 trở lên

Giá trị

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

Mô tả tài nguyên mà con người có thể đọc được.
id

chuỗi

Giá trị nhận dạng tài nguyên cho loại nội dung đã cho.

Scope

Chrome 44 trở lên

Phạm vi của ContentCài đặt. Một trong các giá trị sau: regular: chế độ cài đặt cho hồ sơ thông thường (được hồ sơ ẩn danh kế thừa 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ể thiết lập trong một phiên ẩn danh và sẽ bị xoá khi phiên ẩn danh kết thúc (ghi đè chế độ cài đặt thông thường).

Enum

"incognito_session_only"

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 các lựa chọn sau: 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 có trang web muốn tự động tải tệp xuống sau tệp đầu tiên. Giá trị 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.

Loại

ContentSetting<MultipleAutomaticDownloadsContentSetting>

autoVerify

Chrome 113 trở lên

Liệu có cho phép các trang web sử dụng Private State Tokens API hay không. Một trong các tuỳ chọn sau: 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à .

Loại

ContentSetting<AutoVerifyContentSetting>

camera

Chrome 46 trở lên

Liệu có cho phép các trang web truy cập vào máy ảnh hay không. Một trong các lệnh 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 có trang web muốn truy cập vào camera. Giá trị 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 Ý: Chế độ cài đặt "cho phép" không hợp lệ nếu cả hai mẫu đều là "".

Loại

ContentSetting<CameraContentSetting>

clipboard

Chrome 121 trở lên

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. Các chức năng "Nâng cao" bao gồm mọi tính năng ngoài việc viết các định dạng tích hợp sẵn sau một cử chỉ của người dùng, tức là khả năng đọc, viết định dạng tuỳ chỉnh và viết mà không cần cử chỉ của người dùng. Một trong các lựa chọn allow: Cho phép các trang web dùng các chức năng nâng cao của bảng nhớ tạm, block: Không cho phép các trang web dùng các tính năng nâng cao của bảng nhớ tạm, ask: Hỏi khi có trang web muốn dùng các chức 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.

Loại

ContentSetting<ClipboardContentSetting>

cookies

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 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. Giá trị 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.

Loại

ContentSetting<CookiesContentSetting>

fullscreen

Không dùng nữa. Không còn hiệu lực nữa. Quyền toàn màn hình hiện được tự động cấp cho mọi trang web. Giá trị luôn là allow.

Loại

ContentSetting<FullscreenContentSetting>

images

Liệu có hiển thị hình ảnh hay không. Một trong các giá trị sau: allow: Hiển thị hình ảnh, block: Không hiển thị 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.

Loại

ContentSetting<ImagesContentSetting>

javascript

Liệu có chạy JavaScript hay không. Một trong các giá trị sau: allow: Chạy JavaScript, block: Không chạy JavaScript. Giá trị 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.

Loại

ContentSetting<JavascriptContentSetting>

location

Có cho phép tính năng Định vị địa lý hay không. Một trong các lựa chọn sau: 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 ý kiến 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).

Loại

ContentSetting<LocationContentSetting>

microphone

Chrome 46 trở lên

Liệu có cho phép các trang web truy cập vào micrô hay không. Một trong các trường hợp 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 có trang web muốn truy cập vào micrô. Giá trị 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 Ý: Chế độ cài đặt "cho phép" không hợp lệ nếu cả hai mẫu đều là "".

Loại

ContentSetting<MicrophoneContentSetting>

mouselock

Không dùng nữa. Không còn hiệu lực nữa. Quyền khoá chuột hiện được cấp tự động cho mọi trang web. Giá trị luôn là allow.

Loại

ContentSetting<MouselockContentSetting>

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 trang web hiển thị thông báo trên màn hình, block: Không cho phép trang web hiển thị thông báo trên màn hình, ask: Hỏi khi trang web muốn hiển thị thông báo trên màn hình. Giá trị 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.

Loại

ContentSetting<NotificationsContentSetting>

plugins

Không dùng nữa. Khi chúng tôi không còn hỗ trợ Flash trong Chrome 88, quyền này sẽ không còn 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.

Loại

ContentSetting<PluginsContentSetting>

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 các tuỳ chọn sau: allow: Cho phép trang web hiển thị cửa sổ bật lên, block: Không cho phép trang web hiển thị cửa sổ bật lên. Giá trị 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.

Loại

ContentSetting<PopupsContentSetting>

unsandboxedPlugins

Không dùng nữa. Trước đây, quyền này kiểm soát việc có cho phép các trang web chạy trình bổ trợ không có hộp cát hay không. Tuy nhiên, do quá trình dàn xếp Flash đã bị xoá trong Chrome 88, nên quyền này không còn 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.

Loại

ContentSetting<PpapiBrokerContentSetting>