chrome.contentSettings

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 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 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:

  1. https://www.example.com/*
  2. https://*.example.com/* (khớp example.com và tất cả các miền con)
  3. <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:

  1. https://www.example.com:*/* Chỉ định tên máy chủ và giao thức.
  2. *:/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 đồ.
  3. 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ênMẫu chínhHình mở khoá
1https://www.moose.com/*,https://www.wombat.com/*
2https://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

Chrome 113 trở lên

Liệt kê

"block"

CameraContentSetting

Chrome 46 trở lên

Liệt kê

"block"

ClipboardContentSetting

Chrome 121 trở lên

Liệt kê

"block"

ContentSetting

Thuộc tính

  • xóa

    void

    Cam kết

    Xoá 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ê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.

  • get

    void

    Cam kết

    Lấ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ê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.

  • getResourceIdentifiers

    void

    Cam kết

    Hà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ê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

    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ê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.

CookiesContentSetting

Chrome 44 trở lên

Liệt kê

"block"

"session_only"

FullscreenContentSetting

Chrome 44 trở lên

Giá trị

ImagesContentSetting

Chrome 44 trở lên

Liệt kê

"block"

JavascriptContentSetting

Chrome 44 trở lên

Liệt kê

"block"

LocationContentSetting

Chrome 44 trở lên

Liệt kê

"block"

MicrophoneContentSetting

Chrome 46 trở lên

Liệt kê

"block"

MouselockContentSetting

Chrome 44 trở lên

Giá trị

MultipleAutomaticDownloadsContentSetting

Chrome 44 trở lên

Liệt kê

"block"

NotificationsContentSetting

Chrome 44 trở lên

Liệt kê

"block"

PluginsContentSetting

Chrome 44 trở lên

Giá trị

"block"

PopupsContentSetting

Chrome 44 trở lên

Liệt kê

"block"

PpapiBrokerContentSetting

Chrome 44 trở lên

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

Chrome 44 trở lên

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.

Loại

ContentSetting<MultipleAutomaticDownloadsContentSetting>

autoVerify

Chrome 113 trở lên

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à .

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 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à ''.

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. 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.

Loại

ContentSetting<ClipboardContentSetting>

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.

Loại

ContentSetting<CookiesContentSetting>

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.

Loại

ContentSetting<FullscreenContentSetting>

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.

Loại

ContentSetting<ImagesContentSetting>

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.

Loại

ContentSetting<JavascriptContentSetting>

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).

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 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à ''.

Loại

ContentSetting<MicrophoneContentSetting>

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.

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 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.

Loại

ContentSetting<NotificationsContentSetting>

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.

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 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.

Loại

ContentSetting<PopupsContentSetting>

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.

Loại

ContentSetting<PpapiBrokerContentSetting>