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

Tệp kê khai

Bạn phải khai báo thuộc tính "contentSettings" trong tệp kê khai của tiện ích để sử dụng API. Ví dụ:

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

Các quy luật trong chế độ cài đặt nội dung

Bạn có thể sử dụng các mẫu để chỉ định các trang web chịu ảnh hưởng của từng 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 này. Cú pháp cho nội dung mẫu cài đặt cũng giống như mẫu khớp, chỉ có một vài điểm khác biệt:

  • Đối với các URL http, httpsftp, đường dẫn phải là ký tự đại diện (/*). Đối với file URL, đườ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 yêu cầu chuyển số điện thoại được chỉ định, mẫu chỉ khớp với các trang web có cổng đó. Nếu không có số cổng đã chỉ định, mẫu khớp với tất cả các cổng.

Mức độ ưu tiên của mẫu

Khi có nhiều quy tắc về chế độ cài đặt nội dung áp dụng cho một trang web nhất định, thì quy tắc có nội dung cụ thể hơn sẽ được ưu tiên hơn.

Ví dụ: các mẫu sau được sắp xếp theo mức độ ưu tiên:

  1. https://www.example.com/*
  2. https://*.example.com/* (trùng khớp với example.com và tất cả các miền con)
  3. <all_urls> (phù hợp với mọi URL)

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

Mẫu chính và phụ

URL được tính đến khi quyết định chế độ cài đặt nội dung sẽ áp dụng sẽ phụ thuộc vào loại nội dung. Ví dụ: đối với chế độ cài đặt contentSettings.notifications, chế độ cài đặt là dựa trên URL xuất hiện trong thanh địa chỉ. URL này được gọi là "chính" URL.

Một số loại nội dung có thể tính đến các URL khác. Ví dụ: liệu một trang web có được phép Việc đặt contentSettings.cookies sẽ đượ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à "phụ" URL).

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 hơ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 sau các cặp mẫu chính/phụ được sắp xếp theo mức độ ưu tiên:

Quyền ưu tiênMẫu chínhMẫu phụ
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 chế độ cài đặt nội dung cho các loại phụ cụ thể của một 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 các chế độ cài đặt nội dung, trước tiên cài đặt cho trình bổ trợ cụ thể được kiểm tra. Nếu không tìm thấy chế độ cài đặt nào cho trình bổ trợ, thì chế độ cài đặt nội dung chung cho trình bổ trợ sẽ được chọn.

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 so với 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ể nhận 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 Phương thức contentSettings.ContentSetting.getResourceIdentifiers. Danh sách được trả về có thể thay đổi với tập hợp các plugin đã cài đặt trên máy của người dùng, nhưng Chrome cố gắng giữ cho các giá trị nhận dạng đó ổn định trên 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 chrome-extension-samples kho lưu trữ.

Loại

AutoVerifyContentSetting

Chrome 113 trở lên

Enum

"cho phép"

"block"

CameraContentSetting

Chrome 46 trở lên

Enum

"cho phép"

"block"

"hỏi"

ClipboardContentSetting

Chrome 121 trở lên

Enum

"cho phép"

"block"

"hỏi"

ContentSetting

Thuộc tính

  • xóa

    void

    Lời hứa

    Xóa tất cả cá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).

    • số gọi lại

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

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

      () => void

    • returns

      Lời hứa<vô hiệu>

      Chrome 96 trở lên

      Lời hứa chỉ được hỗ trợ cho Manifest V3 trở lên, các nền tảng khác cần sử dụng lệnh gọi lại.

  • get

    void

    Lời hứa

    Xem 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ó 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 mà 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ụ 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ụ 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 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ó.

    • returns

      Promise&lt;object&gt;

      Chrome 96 trở lên

      Lời hứa chỉ được hỗ trợ cho Manifest V3 trở lên, các nền tảng khác cần sử dụng lệnh gọi lại.

  • getResourceIdentifiers

    void

    Lời hứa

    Hàm getResourceIdentifiers 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.

    • returns

      Cam kết<ResourceIdentifier[]>

      Chrome 96 trở lên

      Lời hứa chỉ được hỗ trợ cho Manifest V3 trở lên, các nền tảng khác cần sử dụng lệnh gọi lại.

  • đặt

    void

    Lời 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

        string

        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 là khớp với tất cả URL. Để 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.

      • cài đặt

        bất kỳ

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

    • số gọi lại

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

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

      () => void

    • returns

      Lời hứa<vô hiệu>

      Chrome 96 trở lên

      Lời hứa chỉ được hỗ trợ cho Manifest V3 trở lên, các nền tảng khác cần sử dụng lệnh gọi lại.

CookiesContentSetting

Chrome 44 trở lên

Enum

"cho phép"

"block"

&quot;session_only&quot;

FullscreenContentSetting

Chrome 44 trở lên

Giá trị

"cho phép"

ImagesContentSetting

Chrome 44 trở lên

Enum

"cho phép"

"block"

JavascriptContentSetting

Chrome 44 trở lên

Enum

"cho phép"

"block"

LocationContentSetting

Chrome 44 trở lên

Enum

"cho phép"

"block"

"hỏi"

MicrophoneContentSetting

Chrome 46 trở lên

Enum

"cho phép"

"block"

"hỏi"

MouselockContentSetting

Chrome 44 trở lên

Giá trị

"cho phép"

MultipleAutomaticDownloadsContentSetting

Chrome 44 trở lên

Enum

"cho phép"

"block"

"hỏi"

NotificationsContentSetting

Chrome 44 trở lên

Enum

"cho phép"

"block"

"hỏi"

PluginsContentSetting

Chrome 44 trở lên

Giá trị

"block"

PopupsContentSetting

Chrome 44 trở lên

Enum

"cho phép"

"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 bài viết 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

    string

    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 số 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 phiên truy cập ẩ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).

Enum

"regular"

"anonymous_session_only"

Thuộc tính

automaticDownloads

Có cho phép các trang web tự động tải nhiều tệp xuống hay không. Một trong số 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. 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

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 số 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: Không cho 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

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 số 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. 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 Ý: 'cho phép' không hợp lệ nếu cả hai mẫu là ''.

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. "Nâng cao" chẳng hạn như khả năng viết các định dạng tích hợp sẵn sau một cử chỉ của người dùng (ví dụ: 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 số allow: Cho phép các trang web sử dụng các tính 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 các tính năng nâng cao của bảng nhớ tạm, ask: Hỏi khi một trang web muốn sử dụng các chức năng bảng nhớ tạm nâng cao. 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 cookie và dữ liệu cục bộ khác do các trang web đặt hay không. Một trong số 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 của cookie. URL phụ là URL của khung cấp cao nhất.

fullscreen

Không dùng nữa. Không còn tác dụng 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.

images

Liệu có hiển thị hình ảnh hay không. Một trong số 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.

javascript

Liệu có chạy JavaScript hay không. Một trong số 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 số 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

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 số 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 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 Ý: 'cho phép' không hợp lệ nếu cả hai mẫu là ''.

mouselock

Không dùng nữa. Không còn tác dụng 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.

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 số 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 có 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 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()clear() sẽ bị bỏ qua.

popups

Có cho phép các trang web hiển thị cửa sổ bật lên hay không. Một trong số allow: Cho phép các 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. 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, chúng tôi kiểm soát việc có cho phép các trang web chạy plugin không có hộp cát hay không. Tuy nhiên, khi quy trình trình môi giới Flash bị xóa trong Chrome 88, quyền này không còn hiệu lực nữa. Giá trị luôn là block. Các lệnh gọi đến set()clear() sẽ bị bỏ qua.