chrome.declarativeContent

Mô tả

Hãy dùng API chrome.declarativeContent để thực hiện thao tác tuỳ thuộc vào nội dung của trang mà không yêu cầu quyền đọc nội dung của trang.

Quyền

declarativeContent

Cách sử dụng

Khai báo Content API cho phép bạn bật thao tác của tiện ích tuỳ thuộc vào URL của trang web hoặc nếu công cụ chọn CSS khớp với phần tử trên trang mà không cần thêm quyền của máy chủ hoặc chèn tập lệnh nội dung.

Sử dụng quyền activeTab để tương tác với một trang sau khi người dùng nhấp vào của tiện ích.

Quy tắc

Quy tắc bao gồm các điều kiện và hành động. Nếu bất kỳ điều kiện nào được đáp ứng, thì tất cả các hành động đều được đáp ứng thực thi. Các hành động đó là setIcon và showAction.

PageStateMatcher khớp với các trang web khi và chỉ khi tất cả được liệt kê đáp ứng các tiêu chí. Nó có thể khớp với URL trang, bộ chọn kết hợp css hoặc trạng thái được đánh dấu của một trang. Quy tắc sau đây bật hành động của tiện ích trên các trang của Google khi có trường mật khẩu:

let rule1 = {
  conditions: [
    new chrome.declarativeContent.PageStateMatcher({
      pageUrl: { hostSuffix: '.google.com', schemes: ['https'] },
      css: ["input[type='password']"]
    })
  ],
  actions: [ new chrome.declarativeContent.ShowAction() ]
};

Để bật thao tác của tiện ích cho các trang web của Google có video, bạn có thể thêm giây điều kiện, vì mỗi điều kiện đủ để kích hoạt tất cả hành động được chỉ định:

let rule2 = {
  conditions: [
    new chrome.declarativeContent.PageStateMatcher({
      pageUrl: { hostSuffix: '.google.com', schemes: ['https'] },
      css: ["input[type='password']"]
    }),
    new chrome.declarativeContent.PageStateMatcher({
      css: ["video"]
    })
  ],
  actions: [ new chrome.declarativeContent.ShowAction() ]
};

Sự kiện onPageChanged kiểm tra xem có bất kỳ quy tắc nào đã được thực hiện ít nhất một quy tắc hay không điều kiện và thực thi các thao tác. Các quy tắc vẫn tồn tại qua các phiên duyệt web; do đó, trong khoảng thời gian thời gian cài đặt tiện ích, trước tiên, bạn nên sử dụng removeRules để xoá các quy tắc đã cài đặt trước đó, rồi sử dụng addRules để đăng ký các quy tắc mới.

chrome.runtime.onInstalled.addListener(function(details) {
  chrome.declarativeContent.onPageChanged.removeRules(undefined, function() {
    chrome.declarativeContent.onPageChanged.addRules([rule2]);
  });
});

Khi có quyền activeTab, tiện ích của bạn sẽ không hiển thị bất kỳ quyền nào và khi người dùng nhấp vào thao tác với tiện ích, thao tác này sẽ chỉ chạy trên các trang có liên quan.

So khớp URL trang

PageStateMatcher.pageurl khớp với thời điểm đáp ứng các tiêu chí về URL. Chiến lược phát hành đĩa đơn tiêu chí phổ biến nhất là kết hợp lưu trữ, đường dẫn hoặc url, theo sau là Chứa, Bằng, Tiền tố hoặc Hậu tố. Bảng sau đây bao gồm một vài ví dụ:

Tiêu chí Khớp với
{ hostSuffix: 'google.com' } Tất cả URL của Google
{ pathPrefix: '/docs/extensions' } URL của tài liệu tiện ích
{ urlContains: 'developer.chrome.com' } Tất cả URL của tài liệu dành cho nhà phát triển Chrome

Tất cả các tiêu chí đều phân biệt chữ hoa chữ thường. Để xem danh sách đầy đủ các tiêu chí, hãy xem UrlFilter.

So khớp CSS

Các điều kiện PageStateMatcher.css phải là bộ chọn kết hợp, nghĩa là bạn không thể bao gồm các tổ hợp như khoảng trắng hoặc ">" trong bộ chọn. Điều này giúp Chrome so khớp bộ chọn hiệu quả hơn.

Bộ chọn phức hợp (OK) Bộ chọn phức tạp (Không OK)
a div p
iframe.special[src^='http'] p>span.highlight
ns|* p + ol
#abcd:checked p::first-line

Các điều kiện CSS chỉ khớp với các phần tử được hiển thị: nếu phần tử khớp với bộ chọn của bạn là display:none hoặc một trong các phần tử mẹ của phần tử này là display:none, nó sẽ không gây ra điều kiện khớp. Các phần tử được tạo kiểu bằng visibility:hidden, được đặt ngoài màn hình hoặc bị ẩn bởi các phần tử khác vẫn có thể làm cho điều kiện của bạn phù hợp.

So khớp trạng thái đã đánh dấu

Điều kiện PageStateMatcher.isBookmarked cho phép khớp trạng thái được đánh dấu trang của URL hiện tại trong hồ sơ của người dùng. Để tận dụng điều kiện này, "dấu trang" bạn phải khai báo quyền trong tệp kê khai tiện ích.

Loại

Loại

ImageData

PageStateMatcher

So khớp trạng thái của trang web dựa trên các tiêu chí khác nhau.

Thuộc tính

  • hàm khởi tạo

    void

    Hàm constructor có dạng như sau: 

    (arg: PageStateMatcher) => {...}

  • css

    string[] không bắt buộc

    So khớp nếu tất cả bộ chọn CSS trong mảng khớp với các phần tử được hiển thị trong một khung có cùng nguồn gốc với khung chính của trang. Tất cả các bộ chọn trong mảng này phải là bộ chọn phức hợp để tăng tốc độ so khớp. Lưu ý: Việc liệt kê hàng trăm bộ chọn CSS hoặc liệt kê các bộ chọn CSS khớp với hàng trăm lần trên mỗi trang có thể làm chậm trang web.

  • isBookmarked

    boolean không bắt buộc

    Chrome 45 trở lên

    So khớp nếu trạng thái được đánh dấu trang của trang bằng giá trị được chỉ định. Yêu cầu quyền đối với dấu trang.

  • pageUrl

    UrlFilter không bắt buộc

    So khớp nếu các điều kiện của UrlFilter được đáp ứng cho URL cấp cao nhất của trang.

RequestContentScript

Hành động sự kiện khai báo chèn một tập lệnh nội dung.

CẢNH BÁO: Thao tác này vẫn đang trong giai đoạn thử nghiệm và không được hỗ trợ trên các bản dựng ổn định của Chrome.

Thuộc tính

  • hàm khởi tạo

    void

    Hàm constructor có dạng như sau: 

    (arg: RequestContentScript) => {...}

  • allFrames

    boolean không bắt buộc

    Tập lệnh nội dung chạy trong tất cả các khung của trang phù hợp hay chỉ trong khung trên cùng. Mặc định là false.

  • css

    string[] không bắt buộc

    Tên của các tệp CSS sẽ được chèn như một phần của tập lệnh nội dung.

  • JavaScript

    string[] không bắt buộc

    Tên của các tệp JavaScript sẽ được chèn như một phần của tập lệnh nội dung.

  • matchAboutBlank

    boolean không bắt buộc

    Liệu có chèn tập lệnh nội dung trên about:blank và about:srcdoc hay không. Mặc định là false.

SetIcon

Hành động sự kiện khai báo sẽ đặt biểu tượng hình vuông n-dip cho hành động trên trang hoặc hành động trên trình duyệt của tiện ích trong khi các điều kiện tương ứng được đáp ứng. Bạn có thể sử dụng thao tác này mà không cần quyền của máy chủ, nhưng tiện ích phải có một thao tác đối với trang hoặc trình duyệt.

Bạn phải chỉ định chính xác một trong hai giá trị imageData hoặc path. Cả hai đều là từ điển ánh xạ một số pixel tới hình ảnh biểu diễn. Nội dung biểu diễn hình ảnh trong imageData là một đối tượng ImageData; Ví dụ: từ một phần tử canvas, trong khi phần biểu diễn hình ảnh trong path là đường dẫn đến một tệp hình ảnh tương ứng với tệp kê khai của tiện ích. Nếu pixel màn hình scale vừa với pixel độc lập với thiết bị, thì biểu tượng scale * n sẽ được sử dụng. Nếu tỷ lệ đó bị thiếu, thì một hình ảnh khác sẽ được đổi kích thước thành kích thước bắt buộc.

Thuộc tính

  • hàm khởi tạo

    void

    Hàm constructor có dạng như sau: 

    (arg: SetIcon) => {...}

  • dữ liệu hình ảnh

    ImageData | đối tượng không bắt buộc

    Đối tượng ImageData hoặc từ điển {size -> ImageData} biểu thị một biểu tượng cần đặt. Nếu biểu tượng được chỉ định làm từ điển, hình ảnh được sử dụng sẽ được chọn tùy thuộc vào mật độ pixel của màn hình. Nếu số pixel hình ảnh vừa với một đơn vị không gian màn hình bằng scale, thì một hình ảnh có kích thước scale * n sẽ được chọn, trong đó n là kích thước của biểu tượng trong giao diện người dùng. Bạn phải chỉ định ít nhất một hình ảnh. Lưu ý rằng details.imageData = foo tương đương với details.imageData = {'16': foo}.

ShowAction

Chrome 97 trở lên

Một thao tác sự kiện khai báo giúp đặt thao tác trên thanh công cụ của tiện ích thành trạng thái bật trong khi đáp ứng các điều kiện tương ứng. Bạn có thể thực hiện thao tác này mà không cần quyền của máy chủ. Nếu tiện ích có quyền activeTab, thì thao tác nhấp vào trang sẽ cấp quyền truy cập vào thẻ đang hoạt động.

Trên những trang không đáp ứng điều kiện, thao tác trên thanh công cụ của tiện ích sẽ có thang màu xám và việc nhấp vào tiện ích sẽ mở trình đơn theo bối cảnh, thay vì kích hoạt thao tác.

Thuộc tính

ShowPageAction

Không được dùng nữa kể từ Chrome 97

Vui lòng sử dụng declarativeContent.ShowAction.

Một hành động sự kiện khai báo giúp đặt hành động trên trang của tiện ích thành trạng thái bật trong khi các điều kiện tương ứng được đáp ứng. Bạn có thể sử dụng thao tác này mà không cần quyền của máy chủ, nhưng tiện ích phải có một thao tác trên trang. Nếu tiện ích có quyền activeTab, thì thao tác nhấp vào trang sẽ cấp quyền truy cập vào thẻ đang hoạt động.

Trên những trang không đáp ứng điều kiện, thao tác trên thanh công cụ của tiện ích sẽ có thang màu xám và việc nhấp vào tiện ích sẽ mở trình đơn theo bối cảnh, thay vì kích hoạt thao tác.

Thuộc tính

Sự kiện

onPageChanged

Cung cấp API Sự kiện khai báo bao gồm addRules, removeRules và getRules.

Điều kiện

PageStateMatcher

Thao tác

RequestContentScript

SetIcon

ShowPageAction

ShowAction