Các tiện ích Manifest V2 đã bị gỡ khỏi Cửa hàng Chrome trực tuyến vào ngày 31 tháng 8 năm 2026. Hãy di chuyển tiện ích của bạn sang Manifest V3 để người dùng có thể sử dụng lại tiện ích.

Google sử dụng công nghệ AI để dịch nội dung sang ngôn ngữ bạn ưu tiên. Bản dịch bằng AI có thể có lỗi.

chrome.declarativeContent

refresh date: 2026-09-25 robots: noindex

Mô tả

Sử dụng API chrome.declarativeContent để thực hiện các hành động tuỳ thuộc vào nội dung của trang mà không cần quyền đọc nội dung của trang.

Quyền

declarativeContent

Cách sử dụng

Declarative Content API cho phép bạn bật hành động của tiện ích tuỳ thuộc vào URL của một trang web hoặc nếu bộ chọn CSS khớp với một phần tử trên trang mà không cần thêm quyền của máy chủ lưu trữ 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 thao tác 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ả hành động sẽ được thực thi. Các thao tác là setIcon và showAction.

PageStateMatcher khớp với các trang web khi và chỉ khi tất cả tiêu chí được liệt kê đều được đáp ứng. Nó có thể khớp với URL trang, bộ chọn phức hợp CSS hoặc trạng thái được đánh dấu của một trang. Quy tắc sau đây cho phép 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 cả thao tác của tiện ích cho các trang web của Google có video, bạn có thể thêm điều kiện thứ hai, vì mỗi điều kiện đều đủ để kích hoạt tất cả thao tác đượ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ó quy tắc nào có ít nhất một điều kiện được đáp ứng hay không và thực thi các hành động. Các quy tắc vẫn tồn tại trong các phiên duyệt web; do đó, trong 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 đó, sau đó 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]);
  });
});

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

So khớp URL trang

PageStateMatcher.pageurl sẽ khớp khi các tiêu chí về URL được đáp ứng. Tiêu chí phổ biến nhất là phép nối của máy chủ 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 trình bày một vài ví dụ:

Tiêu chí	Liên kết
`{ hostSuffix: 'google.com' }`	Tất cả URL của Google
`{ pathPrefix: '/docs/extensions'` }	URL tài liệu về 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ả 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

Điều kiện PageStateMatcher.css phải là bộ chọn phức hợp, nghĩa là bạn không thể đưa bộ kết hợp như khoảng trắng hoặc ">" vào bộ chọn. Điều này giúp Chrome so khớp các 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 nên dùng)
`a`	`div p`
`iframe.special[src^='http']`	`p>span.highlight`
`ns\|*`	`p + ol`
`#abcd:checked`	`p::first-line`

Điều kiện CSS chỉ khớp với các phần tử hiển thị: nếu một 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ử đó là display:none, thì điều kiện đó sẽ không 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ị các phần tử khác ẩn đi vẫn có thể khiến điều kiện của bạn khớp.

Khớp trạng thái đã đánh dấu trang

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

Loại

ImageDataType

Xem https://developer.mozilla.org/en-US/docs/Web/API/ImageData.

Loại

ImageData

PageStateMatcher

Khớp với trạng thái của một trang web dựa trên nhiều tiêu chí.

Thuộc tính

hàm khởi tạo

void

Hàm constructor có dạng như sau:
```
(arg: PageStateMatcher) => {...}
```
- arg
  
  PageStateMatcher
- returns
  PageStateMatcher
css

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

Khớp nếu tất cả bộ chọn CSS trong mảng khớp với các phần tử 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ả 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 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

Khớp nếu trạng thái được đánh dấu của trang bằng với giá trị đã chỉ định. Cần có quyền đối với dấu trang.
pageUrl

UrlFilter không bắt buộc

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 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) => {...}
```
- arg
  
  RequestContentScript
- returns
  RequestContentScript
allFrames

boolean không bắt buộc

Liệu tập lệnh nội dung có chạy trong tất cả các khung của trang phù hợp hay chỉ trong khung trên cùng. Giá trị 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 vào dưới dạng một phần của tập lệnh nội dung.
js

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

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

boolean không bắt buộc

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

SetIcon

Thao tác sự kiện khai báo đặt biểu tượng hình vuông n-dip cho thao tác trên trang hoặc thao tác 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ủ lưu trữ, nhưng tiện ích phải có thao tác trên trang hoặc trình duyệt.

Bạn phải chỉ định chính xác một trong hai thuộc tính imageData hoặc path. Cả hai đều là từ điển liên kết một số pixel với một hình ảnh đại diện. Biểu thị hình ảnh trong imageData là một đối tượng ImageData; ví dụ: từ phần tử canvas, trong khi biểu thị hình ảnh trong path là đường dẫn đến tệp hình ảnh liên quan đến tệp kê khai của tiện ích. Nếu scale pixel màn hình vừa với một pixel không phụ thuộc vào thiết bị, thì biểu tượng scale * n sẽ được sử dụng. Nếu thiếu tỷ lệ đó, 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) => {...}
```
- arg
  
  SetIcon
- returns
  SetIcon
imageData

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

Đối tượng ImageData hoặc từ điển {size -> ImageData} đại diện cho một biểu tượng cần đặt. Nếu biểu tượng được chỉ định dưới dạng từ điển, thì hình ảnh được sử dụng sẽ được chọn tuỳ thuộc vào mật độ pixel của màn hình. Nếu số lượng điểm ảnh vừa với một đơn vị không gian màn hình bằng scale, thì 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 hành động khai báo sự kiện đặt hành động trên thanh công cụ 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ủ lưu trữ. Nếu tiện ích có quyền activeTab, thì việc nhấp vào thao tác trên trang sẽ cấp quyền truy cập vào thẻ đang hoạt động.

Trên các 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ó màu xám và khi nhấp vào thao tác đó, trình đơn theo bối cảnh sẽ mở ra thay vì kích hoạt thao tác.

Thuộc tính

hàm khởi tạo

void

Hàm constructor có dạng như sau:
```
(arg: ShowAction) => {...}
```
- arg
  
  ShowAction
- returns
  ShowAction

ShowPageAction

Không dùng nữa kể từ Chrome 97

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

Một hành động khai báo sự kiện đặ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ủ lưu trữ, nhưng tiện ích phải có thao tác trên trang. Nếu tiện ích có quyền activeTab, thì việc nhấp vào thao tác trên trang sẽ cấp quyền truy cập vào thẻ đang hoạt động.

Thuộc tính

hàm khởi tạo

void

Hàm constructor có dạng như sau:
```
(arg: ShowPageAction) => {...}
```
- arg
  
  ShowPageAction
- returns
  ShowPageAction

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

chrome.declarativeContent Sử dụng bộ sưu tập để sắp xếp ngăn nắp các trang Lưu và phân loại nội dung dựa trên lựa chọn ưu tiên của bạn.

Mô tả

Quyền

Cách sử dụng

Quy tắc

So khớp URL trang

So khớp CSS

Khớp trạng thái đã đánh dấu trang

Loại

ImageDataType

Loại

PageStateMatcher

Thuộc tính

RequestContentScript

Thuộc tính

SetIcon

Thuộc tính

ShowAction

Thuộc tính

ShowPageAction

Thuộc tính

Sự kiện

onPageChanged

Điều kiện

Thao tác

chrome.declarativeContent