Nội dung mô tả
API chrome.declarativeNetRequest
dùng để chặn hoặc sửa đổi các yêu cầu mạng bằng cách chỉ định các quy tắc khai báo. Điều này cho phép tiện ích sửa đổi yêu cầu mạng mà không chặn và xem nội dung, nhờ đó bảo vệ quyền riêng tư cao hơn.
Quyền
declarativeNetRequest
declarativeNetRequestWithHostAccess
declarativeNetRequestFeedback
host_permissions
Phạm vi cung cấp
Tệp kê khai
Ngoài các quyền nêu trên, một số loại bộ quy tắc và tập hợp quy tắc tĩnh cụ thể bắt buộc phải khai báo khoá tệp kê khai "declarative_net_request"
. Khoá này phải là một từ điển với một khoá duy nhất tên là "rule_resources"
. Khóa này là một mảng chứa từ điển thuộc loại Ruleset
, như được hiển thị dưới đây. (Lưu ý rằng tên "Ruleset" không xuất hiện trong JSON của tệp kê khai vì đó chỉ là một mảng.) Bộ quy tắc tĩnh sẽ được giải thích ở phần sau của tài liệu này.
{
"name": "My extension",
...
"declarative_net_request" : {
"rule_resources" : [{
"id": "ruleset_1",
"enabled": true,
"path": "rules_1.json"
}, {
"id": "ruleset_2",
"enabled": false,
"path": "rules_2.json"
}]
},
"permissions": [
"declarativeNetRequest",
"declarativeNetRequestFeedback",
],
"host_permissions": [
"http://www.blogger.com/*",
"http://*.google.com/*"
],
...
}
Khái niệm và cách sử dụng
Để sử dụng API này, hãy chỉ định một hoặc nhiều tập hợp quy tắc. Bộ quy tắc chứa một dãy các quy tắc. Một quy tắc thực hiện một trong những việc sau:
- Chặn một yêu cầu kết nối mạng.
- Nâng cấp giản đồ (http lên https).
- Ngăn chặn một yêu cầu bằng cách bỏ qua mọi quy tắc bị chặn phù hợp.
- Chuyển hướng một yêu cầu mạng.
- Sửa đổi tiêu đề của yêu cầu hoặc phản hồi.
Có ba loại bộ quy tắc, được quản lý theo những cách hơi khác nhau.
- Động
- Duy trì qua các phiên duyệt web và bản nâng cấp tiện ích, đồng thời được quản lý bằng JavaScript khi tiện ích đang được sử dụng.
- Phiên hoạt động
- Xoá khi trình duyệt tắt và khi phiên bản mới của tiện ích được cài đặt. Các quy tắc phiên được quản lý bằng JavaScript khi bạn sử dụng tiện ích.
- Tĩnh
- Đóng gói, cài đặt và cập nhật khi cài đặt hoặc nâng cấp một tiện ích. Quy tắc tĩnh được lưu trữ trong tệp quy tắc có định dạng JSON và được liệt kê trong tệp kê khai.
Một số phần tiếp theo sẽ giải thích chi tiết về các loại bộ quy tắc.
Tập hợp quy tắc động và ở phạm vi phiên hoạt động
Các quy tắc động và quy tắc phiên được quản lý bằng JavaScript khi sử dụng tiện ích.
- Các quy tắc động sẽ vẫn tồn tại trong các phiên duyệt web và bản nâng cấp tiện ích.
- Các quy tắc phiên sẽ bị xoá khi trình duyệt tắt và khi phiên bản mới của tiện ích được cài đặt.
Mỗi loại trong các loại bộ quy tắc này chỉ có một. Tiện ích có thể thêm hoặc xoá các quy tắc một cách linh động bằng cách gọi updateDynamicRules()
và updateSessionRules()
, miễn là các quy tắc đó không vượt quá giới hạn. Để biết thông tin về hạn mức quy tắc, hãy xem bài viết Hạn mức quy tắc. Bạn có thể xem ví dụ về cách này trong phần mã ví dụ.
Bộ quy tắc tĩnh
Không giống như quy tắc động và quy tắc phiên, các quy tắc tĩnh được đóng gói, cài đặt và cập nhật khi một tiện ích được cài đặt hoặc nâng cấp. Các quy tắc này được lưu trữ trong các tệp quy tắc ở định dạng JSON. Các khoá này được chỉ báo cho tiện ích bằng cách sử dụng các khoá "declarative_net_request"
và "rule_resources"
như mô tả ở trên, cũng như một hoặc nhiều Ruleset
từ điển. Từ điển Ruleset
chứa đường dẫn đến tệp quy tắc, mã nhận dạng cho bộ quy tắc có trong tệp và cho biết bộ quy tắc đang bật hay tắt. Hai yếu tố cuối cùng rất quan trọng khi bạn bật hoặc tắt bộ quy tắc theo phương thức lập trình.
{
...
"declarative_net_request" : {
"rule_resources" : [{
"id": "ruleset_1",
"enabled": true,
"path": "rules_1.json"
},
...
]
}
...
}
Để kiểm tra các tệp quy tắc, hãy tải tiện ích đã giải nén. Lỗi và cảnh báo về quy tắc tĩnh không hợp lệ chỉ hiển thị cho các tiện ích đã giải nén. Các quy tắc tĩnh không hợp lệ trong các tiện ích đóng gói sẽ bị bỏ qua.
Bật và tắt bộ quy tắc và bộ quy tắc tĩnh
Bạn có thể bật hoặc tắt cả các quy tắc tĩnh riêng lẻ và tập hợp quy tắc tĩnh hoàn chỉnh trong thời gian chạy.
Bộ quy tắc và bộ quy tắc tĩnh đang bật sẽ được duy trì trong các phiên trình duyệt. Cả hai đều không được duy trì khi cập nhật tiện ích, nghĩa là chỉ những quy tắc bạn đã chọn để lại trong tệp quy tắc mới có sẵn sau khi cập nhật.
Vì lý do về hiệu suất, cũng có những giới hạn về số lượng quy tắc và bộ quy tắc có thể được bật cùng một lúc. Gọi getAvailableStaticRuleCount()
để kiểm tra số lượng quy tắc bổ sung có thể được bật. Để biết thông tin về hạn mức quy tắc, hãy xem bài viết Hạn mức quy tắc.
Để bật hoặc tắt quy tắc tĩnh, hãy gọi updateStaticRules()
. Phương thức này lấy một đối tượng UpdateStaticRulesOptions
, chứa các mảng mã nhận dạng của các quy tắc để bật hoặc tắt. Các mã nhận dạng được xác định bằng khoá "id"
của từ điển Ruleset
.
Để bật hoặc tắt các rulesets tĩnh, hãy gọi updateEnabledRulesets()
. Phương thức này lấy một đối tượng UpdateRulesetOptions
, chứa các mảng mã nhận dạng của các quy tắc để bật hoặc tắt. Các mã nhận dạng được xác định bằng khoá "id"
của từ điển Ruleset
.
Xây dựng quy tắc
Bất kể loại nào, quy tắc bắt đầu bằng 4 trường như được hiển thị dưới đây. Trong khi khoá "id"
và "priority"
nhận một số, các phím "action"
và "condition"
có thể cung cấp một số điều kiện chặn và chuyển hướng. Quy tắc sau đây chặn tất cả các yêu cầu tập lệnh bắt nguồn từ "foo.com"
đến bất kỳ URL nào có "abc"
là chuỗi con.
{
"id" : 1,
"priority": 1,
"action" : { "type" : "block" },
"condition" : {
"urlFilter" : "abc",
"initiatorDomains" : ["foo.com"],
"resourceTypes" : ["script"]
}
}
Ký tự phù hợp với urlFilter
Khoá "condition"
của quy tắc cho phép khoá "urlFilter"
để thao tác trên các URL trong miền đã chỉ định. Bạn tạo các mẫu bằng mã thông báo so khớp mẫu. Dưới đây là một vài ví dụ.
urlFilter |
Khớp với | Không khớp |
---|---|---|
"abc" |
https://abcd.com https://example.com/abcd |
https://ab.com |
"abc*d" |
https://abcd.com https://example.com/abcxyzd |
https://abc.com |
"||a.example.com" |
https://a.example.com/ https://b.a.example.com/xyz |
https://example.com/ |
"|https*" |
https://example.com | http://example.com/ http://https.com |
"example*^123|" |
https://example.com/123 http://abc.com/example?123 |
https://example.com/1234 https://abc.com/example0123 |
Mức độ ưu tiên của quy tắc
Quy tắc được kích hoạt bởi các yêu cầu được gửi từ các trang web. Nếu nhiều quy tắc khớp với một yêu cầu cụ thể thì các quy tắc đó phải được ưu tiên. Mục này giải thích cách chúng được ưu tiên. Quá trình ưu tiên diễn ra trong hai giai đoạn.
- Mức độ ưu tiên được xác định cho các quy tắc trong một tiện ích.
- Nếu nhiều tiện ích có thể áp dụng quy tắc cho một yêu cầu, thì mức độ ưu tiên sẽ được xác định cho tất cả các tiện ích khớp với một yêu cầu cụ thể.
Suy nghĩ về việc so khớp theo cách này: bất kỳ quy tắc nào mà một tiện ích cụ thể ưu tiên thì sẽ được ưu tiên so với các quy tắc từ các tiện ích khác.
Mức độ ưu tiên của quy tắc trong một tiện ích
Trong một phần mở rộng, việc ưu tiên được thực hiện bằng quy trình sau đây:
- Quy tắc có mức độ ưu tiên cao nhất do nhà phát triển xác định (nói cách khác là trường
"priority"
) sẽ được trả về. Nếu có nhiều quy tắc có mức độ ưu tiên cao nhất do nhà phát triển xác định, thì các quy tắc sẽ được ưu tiên bằng trường
"action"
theo thứ tự sau:allow
allowAllRequests
block
upgradeScheme
redirect
Nếu loại hành động không phải là
block
hoặcredirect
, thì mọi quy tắcmodifyHeaders
phù hợp sẽ được đánh giá. Xin lưu ý rằng nếu có bất kỳ quy tắc nào có mức độ ưu tiên do nhà phát triển xác định thấp hơn mức độ ưu tiên được chỉ định choallow
vàallowAllRequests
, thì các quy tắc đó sẽ bị bỏ qua.Nếu nhiều quy tắc sửa đổi cùng một tiêu đề, thì việc sửa đổi sẽ được xác định bởi trường
"priority"
do nhà phát triển xác định và bằng các thao tác được chỉ định.- Nếu quy tắc thêm vào tiêu đề thì các quy tắc có mức độ ưu tiên thấp hơn chỉ có thể thêm vào tiêu đề đó. Không được phép thực hiện các thao tác đặt và xoá.
- Nếu một quy tắc đặt tiêu đề thì các quy tắc có mức ưu tiên thấp hơn chỉ có thể thêm vào tiêu đề đó. Bạn không được phép sửa đổi gì khác.
- Nếu quy tắc xoá tiêu đề thì các quy tắc có mức độ ưu tiên thấp hơn không thể sửa đổi thêm tiêu đề.
Mức độ ưu tiên quy tắc giữa các tiện ích
Nếu chỉ một tiện ích có quy tắc khớp với yêu cầu thì quy tắc đó sẽ được áp dụng. Tuy nhiên, nếu có nhiều tiện ích khớp với một yêu cầu, thì quy trình sau sẽ được sử dụng:
Các quy tắc được ưu tiên sử dụng trường
"action"
theo thứ tự sau:block
redirect
hoặcupgradeScheme
allow
hoặcallowAllRequests
Nếu có nhiều quy tắc trùng khớp, thì tiện ích được cài đặt gần đây nhất sẽ được ưu tiên.
Hạn mức quy tắc
Việc tải và đánh giá các quy tắc trong trình duyệt sẽ dẫn đến mức hao tổn hiệu suất, vì vậy, một số giới hạn sẽ được áp dụng khi sử dụng API. Giới hạn phụ thuộc vào loại quy tắc bạn đang sử dụng.
Quy tắc tĩnh
Quy tắc tĩnh là những quy tắc được chỉ định trong tệp quy tắc được khai báo trong tệp kê khai. Một tiện ích có thể chỉ định tối đa 50 rulesets tĩnh trong khoá tệp kê khai "rule_resources"
, nhưng chỉ có thể bật tối đa 10 bộ quy tắc trong số này cùng một lúc. Biểu ngữ thứ hai được gọi là MAX_NUMBER_OF_ENABLED_STATIC_RULESETS
. Nói chung, các quy tắc đó được đảm bảo ít nhất 30.000 quy tắc. Đây được gọi là GUARANTEED_MINIMUM_STATIC_RULES
.
Số lượng quy tắc có sẵn sau đó phụ thuộc vào số lượng quy tắc được bật bởi tất cả các tiện ích đã cài đặt trên trình duyệt của người dùng. Bạn có thể tìm thấy số này trong thời gian chạy bằng cách gọi getAvailableStaticRuleCount()
. Bạn có thể xem ví dụ về cách này trong phần mã ví dụ.
Quy tắc động và quy tắc phiên
Giới hạn áp dụng cho các quy tắc động và phiên đơn giản hơn so với các quy tắc tĩnh. Tổng số của cả hai trường này không được vượt quá 5.000. Đây được gọi là MAX_NUMBER_OF_DYNAMIC_AND_SESSION_RULES
.
Các quy tắc sử dụng biểu thức chính quy
Tất cả các loại quy tắc đều có thể sử dụng biểu thức chính quy; tuy nhiên, tổng số quy tắc biểu thức chính quy của mỗi loại không được vượt quá 1.000. Đây được gọi là MAX_NUMBER_OF_REGEX_RULES.
Ngoài ra, mỗi quy tắc phải nhỏ hơn 2KB sau khi được biên dịch. Điều này tương quan gần đúng với sự phức tạp của quy tắc. Nếu cố tải một quy tắc vượt quá giới hạn này, thì bạn sẽ thấy một cảnh báo như cảnh báo bên dưới và quy tắc này sẽ bị bỏ qua.
rules_1.json: Rule with id 1 specified a more complext regex than allowed
as part of the "regexFilter" key.
Tương tác với trình chạy dịch vụ
declarativeNetRequest chỉ áp dụng cho các yêu cầu đi đến ngăn xếp mạng. Dữ liệu này bao gồm các phản hồi từ bộ nhớ đệm HTTP, nhưng có thể không bao gồm các phản hồi đi qua trình xử lý onfetch
của một trình chạy dịch vụ. declarativeNetRequest sẽ không ảnh hưởng đến các phản hồi do trình chạy dịch vụ tạo ra hoặc được truy xuất từ CacheStorage
, nhưng sẽ ảnh hưởng đến các lệnh gọi đến fetch()
được thực hiện trong một trình chạy dịch vụ.
Tài nguyên có thể truy cập trên web
Quy tắc declarativeNetRequest không thể chuyển hướng từ yêu cầu tài nguyên công khai đến tài nguyên không thể truy cập trên web. Làm như vậy sẽ gây ra lỗi. Điều này đúng ngay cả khi tài nguyên có thể truy cập trên web được chỉ định thuộc sở hữu của tiện ích chuyển hướng. Để khai báo tài nguyên cho declarativeNetRequest, hãy dùng mảng "web_accessible_resources"
của tệp kê khai.
Ví dụ
Ví dụ về mã
Cập nhật các quy tắc động
Ví dụ sau đây trình bày cách gọi updateDynamicRules()
. Quy trình cho updateSessionRules()
cũng tương tự.
// Get arrays containing new and old rules
const newRules = await getNewRules();
const oldRules = await chrome.declarativeNetRequest.getDynamicRules();
const oldRuleIds = oldRules.map(rule => rule.id);
// Use the arrays to update the dynamic rules
await chrome.declarativeNetRequest.updateDynamicRules({
removeRuleIds: oldRuleIds,
addRules: newRules
});
Cập nhật bộ quy tắc tĩnh
Ví dụ sau đây cho thấy cách bật và tắt các bộ quy tắc trong khi xem xét số lượng bộ quy tắc tĩnh có sẵn và số lượng tối đa các bộ quy tắc tĩnh được bật. Bạn sẽ thực hiện việc này khi số lượng quy tắc tĩnh bạn cần vượt quá con số cho phép. Để làm được việc này, bạn nên cài đặt một số bộ quy tắc đồng thời tắt một số bộ quy tắc (đặt "Enabled"
thành false
trong tệp kê khai).
async function updateStaticRules(enableRulesetIds, disableCandidateIds) {
// Create the options structure for the call to updateEnabledRulesets()
let options = { enableRulesetIds: enableRulesetIds }
// Get the number of enabled static rules
const enabledStaticCount = await chrome.declarativeNetRequest.getEnabledRulesets();
// Compare rule counts to determine if anything needs to be disabled so that
// new rules can be enabled
const proposedCount = enableRulesetIds.length;
if (enabledStaticCount + proposedCount > chrome.declarativeNetRequest.MAX_NUMBER_OF_ENABLED_STATIC_RULESETS) {
options.disableRulesetIds = disableCandidateIds
}
// Update the enabled static rules
await chrome.declarativeNetRequest.updateEnabledRulesets(options);
}
Ví dụ về quy tắc
Các ví dụ bên dưới minh hoạ cách Chrome ưu tiên các quy tắc trong một tiện ích. Khi xem xét các quy tắc này, bạn nên mở quy tắc mức độ ưu tiên trong một cửa sổ riêng.
Khoá "ưu tiên"
Những ví dụ này yêu cầu quyền của máy chủ đối với *://*.example.com/*
.
Để xác định mức độ ưu tiên của một URL cụ thể, hãy xem khoá "priority"
(do nhà phát triển xác định), khoá "action"
và khoá "urlFilter"
. Những ví dụ này tham chiếu đến tệp quy tắc mẫu được hiển thị bên dưới.
- Điều hướng đến https://google.com
- Hai quy tắc bao gồm URL này: các quy tắc có mã nhận dạng 1 và 4. Quy tắc có mã 1 được áp dụng vì các hành động
"block"
có mức độ ưu tiên cao hơn các hành động"redirect"
. Các quy tắc còn lại không áp dụng vì chúng dành cho các URL dài hơn. - Điều hướng đến https://google.com/1234
- Do URL dài hơn nên quy tắc có mã nhận dạng 2 hiện cũng khớp với các quy tắc có mã nhận dạng 1 và 4. Quy tắc có mã 2 được áp dụng vì
"allow"
có mức độ ưu tiên cao hơn"block"
và"redirect"
. - Điều hướng đến https://google.com/12345
- Cả 4 quy tắc đều khớp với URL này. Quy tắc có mã nhận dạng 3 được áp dụng vì mức độ ưu tiên do nhà phát triển xác định là mức độ ưu tiên cao nhất trong nhóm.
[
{
"id": 1,
"priority": 1,
"action": { "type": "block" },
"condition": {"urlFilter": "google.com", "resourceTypes": ["main_frame"] }
},
{
"id": 2,
"priority": 1,
"action": { "type": "allow" },
"condition": { "urlFilter": "google.com/123", "resourceTypes": ["main_frame"] }
},
{
"id": 3,
"priority": 2,
"action": { "type": "block" },
"condition": { "urlFilter": "google.com/12345", "resourceTypes": ["main_frame"] }
},
{
"id": 4,
"priority": 1,
"action": { "type": "redirect", "redirect": { "url": "https://example.com" } },
"condition": { "urlFilter": "google.com", "resourceTypes": ["main_frame"] }
},
]
Chuyển hướng
Ví dụ bên dưới yêu cầu quyền của máy chủ đối với *://*.example.com/*
.
Ví dụ sau đây cho thấy cách chuyển hướng một yêu cầu từ example.com đến một trang nằm trong chính tiện ích. Đường dẫn phần mở rộng /a.jpg
phân giải thành chrome-extension://EXTENSION_ID/a.jpg
, trong đó EXTENSION_ID
là mã nhận dạng phần mở rộng của bạn. Để làm được điều này, tệp kê khai phải khai báo /a.jpg
là tài nguyên có thể truy cập trên web.
{
"id": 1,
"priority": 1,
"action": { "type": "redirect", "redirect": { "extensionPath": "/a.jpg" } },
"condition": {
"urlFilter": "https://www.example.com",
"resourceTypes": ["main_frame"]
}
}
Khoá sau đây dùng khoá "transform"
để chuyển hướng đến miền con của example.com, đồng thời sử dụng điểm neo tên miền ("||") để chặn các yêu cầu qua giao thức bất kỳ từ example.com. Khoá "scheme"
trong "transform"
chỉ định rằng lệnh chuyển hướng tới miền con sẽ luôn sử dụng "https".
{
"id": 1,
"priority": 1,
"action": {
"type": "redirect",
"redirect": {
"transform": { "scheme": "https", "host": "new.example.com" }
}
},
"condition": {
"urlFilter": "||example.com",
"resourceTypes": ["main_frame"]
}
}
Ví dụ sau đây sử dụng biểu thức chính quy để chuyển hướng từ https://www.abc.xyz.com/path
đến https://abc.xyz.com/path
. Trong khoá "regexFilter"
, hãy lưu ý cách thoát dấu chấm và nhóm chụp ảnh chọn "abc" hoặc "def". Khoá "regexSubstitution"
chỉ định kết quả khớp đầu tiên được trả về của biểu thức chính quy bằng cách sử dụng "\1". Trong trường hợp này, "abc" được lấy từ URL được chuyển hướng và được đặt vào giá trị thay thế.
{
"id": 1,
"priority": 1,
"action": {
"type": "redirect",
"redirect": {
"regexSubstitution": "https://\\1.xyz.com/"
}
},
"condition": {
"regexFilter": "^https://www\\.(abc|def)\\.xyz\\.com/",
"resourceTypes": [
"main_frame"
]
}
}
Tiêu đề
Ví dụ sau đây xoá tất cả cookie khỏi cả khung chính và mọi khung phụ.
{
"id": 1,
"priority": 1,
"action": {
"type": "modifyHeaders",
"requestHeaders": [{ "header": "cookie", "operation": "remove" }]
},
"condition": { "resourceTypes": ["main_frame", "sub_frame"] }
}
Loại
DomainType
Phần này cho biết yêu cầu là bên thứ nhất hay bên thứ ba trong khung tạo ra yêu cầu. Một yêu cầu được xem là bên thứ nhất nếu có cùng miền (eTLD+1) với khung phát sinh yêu cầu.
Liệt kê
"firstParty"
Yêu cầu mạng là bên thứ nhất trong khung mà yêu cầu mạng bắt nguồn.
"thirdParty"
Yêu cầu mạng là bên thứ ba có khung tạo ra yêu cầu mạng đó.
ExtensionActionOptions
Thuộc tính
-
displayActionCountAsBadgeText
boolean không bắt buộc
Liệu có tự động hiển thị số hành động cho một trang dưới dạng văn bản huy hiệu của tiện ích hay không. Lựa chọn ưu tiên này vẫn tồn tại qua nhiều phiên.
-
tabUpdate
TabActionCountUpdate không bắt buộc
Chrome 89 trở lênThông tin chi tiết về cách điều chỉnh số lượng hành động của thẻ.
GetDisabledRuleIdsOptions
Thuộc tính
-
rulesetId
string
Mã nhận dạng tương ứng với một
Ruleset
tĩnh.
GetRulesFilter
Thuộc tính
-
ruleIds
number[] không bắt buộc
Nếu được chỉ định thì chỉ những quy tắc có mã nhận dạng để so khớp mới được đưa vào.
HeaderOperation
Điều này mô tả các thao tác có thể có cho quy tắc "modifyHeaders".
Liệt kê
"append"
Thêm mục nhập mới cho tiêu đề đã chỉ định. Thao tác này không được hỗ trợ cho tiêu đề của yêu cầu.
"set"
Đặt giá trị mới cho tiêu đề đã chỉ định, xoá mọi tiêu đề hiện có có cùng tên.
"remove"
Xoá tất cả các mục nhập tiêu đề đã chỉ định.
IsRegexSupportedResult
Thuộc tính
-
isSupported
boolean
-
lý do
UnsupportedRegexReason không bắt buộc
Nêu lý do tại sao biểu thức chính quy không được hỗ trợ. Chỉ được cung cấp nếu
isSupported
sai.
MatchedRule
Thuộc tính
-
ruleId
number
Mã của quy tắc trùng khớp.
-
rulesetId
string
Mã của
Ruleset
chứa quy tắc này. Đối với quy tắc bắt nguồn từ bộ quy tắc động, giá trị này sẽ bằngDYNAMIC_RULESET_ID
.
MatchedRuleInfo
Thuộc tính
-
quy tắc
-
tabId
number
Mã thẻ của thẻ phát sinh yêu cầu nếu thẻ đó vẫn đang hoạt động. Khác -1.
-
timeStamp
number
Thời gian khớp với quy tắc. Dấu thời gian sẽ tương ứng với quy ước JavaScript cho thời gian, tức là số mili giây kể từ thời gian bắt đầu của hệ thống.
MatchedRuleInfoDebug
Thuộc tính
-
request
Thông tin chi tiết về yêu cầu được so khớp với quy tắc.
-
quy tắc
MatchedRulesFilter
Thuộc tính
-
minTimeStamp
số không bắt buộc
Nếu được chỉ định, chỉ so khớp các quy tắc sau dấu thời gian đã cho.
-
tabId
số không bắt buộc
Nếu được chỉ định, chỉ đối sánh các quy tắc cho thẻ đã cho. Khớp với các quy tắc không liên kết với thẻ đang hoạt động nào nếu được đặt thành -1.
ModifyHeaderInfo
Thuộc tính
-
tiêu đề
string
Tên của tiêu đề cần sửa đổi.
-
hoạt động
Thao tác được thực hiện đối với tiêu đề.
-
value
chuỗi không bắt buộc
Giá trị mới cho tiêu đề. Phải được chỉ định cho các thao tác
append
vàset
.
QueryKeyValue
Thuộc tính
-
phím
string
-
replaceOnly
boolean không bắt buộc
Chrome 94 trở lênNếu đúng, khoá truy vấn chỉ được thay thế khi đã có khoá. Nếu không, khoá cũng sẽ được thêm vào nếu bị thiếu. Giá trị mặc định là false.
-
value
string
QueryTransform
Thuộc tính
-
addOrReplaceParams
QueryKeyValue[] không bắt buộc
Danh sách các cặp khoá-giá trị của truy vấn sẽ được thêm hoặc thay thế.
-
removeParams
string[] không bắt buộc
Danh sách khoá truy vấn cần xoá.
Redirect
Thuộc tính
-
extensionPath
chuỗi không bắt buộc
Đường dẫn tương ứng với thư mục tiện ích. Phải bắt đầu bằng '/'.
-
regexSubstitution
chuỗi không bắt buộc
Mẫu thay thế cho các quy tắc chỉ định
regexFilter
. Kết quả phù hợp đầu tiên củaregexFilter
trong URL sẽ được thay thế bằng mẫu này. TrongregexSubstitution
, bạn có thể dùng các chữ số thoát dấu gạch chéo ngược (\1 đến \9) để chèn các nhóm thu thập tương ứng. \0 đề cập đến toàn bộ văn bản trùng khớp. -
biến đổi
URLTransform không bắt buộc
Các phép chuyển đổi URL cần thực hiện.
-
url
chuỗi không bắt buộc
URL chuyển hướng. Không cho phép chuyển hướng đến các URL JavaScript.
RegexOptions
Thuộc tính
-
isCaseSensitive
boolean không bắt buộc
Liệu
regex
được chỉ định có phân biệt chữ hoa chữ thường hay không. Mặc định là đúng. -
biểu thức chính quy
string
Expresson thông thường cần kiểm tra.
-
requireCapturing
boolean không bắt buộc
Liệu
regex
được chỉ định có yêu cầu chụp hay không. Bạn chỉ cần chụp lại đối với các quy tắc chuyển hướng chỉ định hành độngregexSubstition
. Giá trị mặc định là "false".
RequestDetails
Thuộc tính
-
documentId
chuỗi không bắt buộc
Chrome 106 trở lênGiá trị nhận dạng duy nhất cho tài liệu của khung nếu yêu cầu này là dành cho một khung.
-
documentLifecycle
DocumentLifecycle không bắt buộc
Chrome 106 trở lênVòng đời của tài liệu của khung, nếu yêu cầu này là dành cho một khung.
-
frameId
number
Giá trị 0 cho biết yêu cầu xảy ra trong khung chính; giá trị dương cho biết mã của khung phụ nơi yêu cầu xảy ra. Nếu tài liệu của một khung (phụ) được tải (
type
làmain_frame
hoặcsub_frame
),frameId
sẽ cho biết mã của khung này chứ không phải mã của khung bên ngoài. Mã khung là duy nhất trong một thẻ. -
frameType
FrameType không bắt buộc
Chrome 106 trở lênLoại khung, nếu yêu cầu này là dành cho một khung.
-
trình khởi tạo
chuỗi không bắt buộc
Nguồn nơi đưa ra yêu cầu. Điều này không thay đổi qua các lệnh chuyển hướng. Nếu đây là một nguồn gốc không rõ ràng, thì chuỗi "null" (null) sẽ được sử dụng.
-
method
string
Phương thức HTTP tiêu chuẩn.
-
parentDocumentId
chuỗi không bắt buộc
Chrome 106 trở lênGiá trị nhận dạng duy nhất cho tài liệu mẹ của khung nếu yêu cầu này là dành cho một khung và có thư mục mẹ.
-
parentFrameId
number
Mã của khung bao bọc khung đã gửi yêu cầu. Đặt thành -1 nếu không có khung mẹ nào.
-
requestId
string
Mã của yêu cầu. Mã yêu cầu là duy nhất trong một phiên trình duyệt.
-
tabId
number
Mã của thẻ nơi yêu cầu diễn ra. Đặt thành -1 nếu yêu cầu không liên quan đến một thẻ.
-
loại
Loại tài nguyên của yêu cầu.
-
url
string
URL của yêu cầu.
RequestMethod
Phần này mô tả phương thức yêu cầu HTTP của một yêu cầu mạng.
Liệt kê
"get"
"options"
"patch"
"put"
"other"
ResourceType
Phần này mô tả loại tài nguyên của yêu cầu mạng.
Liệt kê
"main_frame"
"sub_frame"
"script"
"font"
"xmlhttprequest"
"ping"
"csp_report"
"media"
"websocket"
"webtransport"
"webbundle"
"other"
Rule
Thuộc tính
-
hành động
Hành động cần thực hiện nếu quy tắc này phù hợp.
-
điều kiện
Điều kiện kích hoạt quy tắc này.
-
id
number
Mã nhận dạng duy nhất cho một quy tắc. Bắt buộc và phải >= 1.
-
của chiến dịch
số không bắt buộc
Mức độ ưu tiên của quy tắc. Giá trị mặc định là 1. Khi được chỉ định, phải >= 1.
RuleAction
Thuộc tính
-
chuyển hướng
Chuyển hướng không bắt buộc
Mô tả cách thực hiện hoạt động chuyển hướng. Chỉ hợp lệ cho quy tắc chuyển hướng.
-
requestHeaders
ModifyHeaderInfo[] không bắt buộc
Chrome 86 trở lênTiêu đề của yêu cầu để sửa đổi cho yêu cầu. Chỉ hợp lệ nếu RuleActionType là "modifyHeaders".
-
responseHeaders
ModifyHeaderInfo[] không bắt buộc
Chrome 86 trở lênCác tiêu đề phản hồi cần sửa đổi cho yêu cầu. Chỉ hợp lệ nếu RuleActionType là "modifyHeaders".
-
loại
Loại hành động cần thực hiện.
RuleActionType
Mô tả loại hành động cần thực hiện nếu một RuleCondition nhất định khớp với.
Liệt kê
"block"
Chặn yêu cầu kết nối mạng.
"redirect"
Chuyển hướng yêu cầu mạng.
"allow"
Cho phép yêu cầu kết nối mạng. Yêu cầu sẽ không bị chặn nếu có quy tắc cho phép phù hợp với yêu cầu đó.
"upgradeScheme"
Nâng cấp giao thức url yêu cầu mạng thành https nếu yêu cầu là http hoặc ftp.
"modifyHeaders"
Sửa đổi tiêu đề của yêu cầu/phản hồi từ yêu cầu mạng.
"allowAllRequests"
Cho phép tất cả yêu cầu trong một hệ phân cấp khung, bao gồm cả chính yêu cầu về khung.
RuleCondition
Thuộc tính
-
domainType
DomainType không bắt buộc
Chỉ định xem yêu cầu mạng là của bên thứ nhất hay bên thứ ba cho miền mà yêu cầu đó bắt nguồn. Nếu bỏ qua, tất cả yêu cầu sẽ được chấp nhận.
-
tên miền
string[] không bắt buộc
Không dùng nữa kể từ Chrome 101Sử dụng
initiatorDomains
Quy tắc này sẽ chỉ khớp với các yêu cầu mạng bắt nguồn từ danh sách
domains
. -
excludedDomains
string[] không bắt buộc
Không dùng nữa kể từ Chrome 101Sử dụng
excludedInitiatorDomains
Quy tắc này sẽ không khớp với các yêu cầu mạng bắt nguồn từ danh sách
excludedDomains
. -
excludedInitiatorDomains
string[] không bắt buộc
Chrome 101 trở lênQuy tắc này sẽ không khớp với các yêu cầu mạng bắt nguồn từ danh sách
excludedInitiatorDomains
. Nếu danh sách này trống hoặc bị bỏ qua thì không có miền nào bị loại trừ. Chế độ này sẽ được ưu tiên hơn so vớiinitiatorDomains
.Lưu ý:
- Các miền phụ như "a.example.com" cũng được cho phép.
- Các mục nhập chỉ được chứa ký tự ASCII.
- Sử dụng mã hóa mã hóa cho các miền được quốc tế hóa.
- URL này so khớp với trình tạo yêu cầu chứ không phải với URL yêu cầu.
- Miền phụ của các miền có trong danh sách cũng bị loại trừ.
-
excludedRequestDomains
string[] không bắt buộc
Chrome 101 trở lênQuy tắc này sẽ không khớp với các yêu cầu mạng khi các miền khớp với một yêu cầu trong danh sách
excludedRequestDomains
. Nếu danh sách này trống hoặc bị bỏ qua thì không có miền nào bị loại trừ. Chế độ này sẽ được ưu tiên hơn so vớirequestDomains
.Lưu ý:
- Các miền phụ như "a.example.com" cũng được cho phép.
- Các mục nhập chỉ được chứa ký tự ASCII.
- Sử dụng mã hóa mã hóa cho các miền được quốc tế hóa.
- Miền phụ của các miền có trong danh sách cũng bị loại trừ.
-
excludedRequestMethods
RequestMethod[] không bắt buộc
Chrome 91 trở lênDanh sách phương thức yêu cầu mà quy tắc sẽ không so khớp. Bạn chỉ được chỉ định một trong hai trong số
requestMethods
vàexcludedRequestMethods
. Nếu không có phương thức nào được chỉ định, thì tất cả phương thức yêu cầu đều được so khớp. -
excludedResourceTypes
ResourceType[] không bắt buộc
Danh sách các loại tài nguyên mà quy tắc sẽ không khớp. Bạn chỉ được chỉ định một trong hai trong số
resourceTypes
vàexcludedResourceTypes
. Nếu không có loại tài nguyên nào được chỉ định, thì mọi loại tài nguyên ngoại trừ "main_frame" sẽ bị chặn. -
excludedTabIds
number[] không bắt buộc
Chrome 92 trở lênDanh sách
tabs.Tab.id
mà quy tắc không khớp. Mãtabs.TAB_ID_NONE
loại trừ các yêu cầu không bắt nguồn từ thẻ. Chỉ hỗ trợ cho các quy tắc ở phạm vi phiên hoạt động. -
initiatorDomains
string[] không bắt buộc
Chrome 101 trở lênQuy tắc này sẽ chỉ khớp với các yêu cầu mạng bắt nguồn từ danh sách
initiatorDomains
. Nếu danh sách này bị bỏ qua, thì quy tắc sẽ áp dụng cho các yêu cầu từ tất cả các miền. Danh sách trống không được phép.Lưu ý:
- Các miền phụ như "a.example.com" cũng được cho phép.
- Các mục nhập chỉ được chứa ký tự ASCII.
- Sử dụng mã hóa mã hóa cho các miền được quốc tế hóa.
- URL này so khớp với trình tạo yêu cầu chứ không phải với URL yêu cầu.
- Miền phụ của các miền có trong danh sách cũng được so khớp.
-
isUrlFilterCaseSensitive
boolean không bắt buộc
Liệu
urlFilter
hoặcregexFilter
(tuỳ theo sự kiện nào được chỉ định) có phân biệt chữ hoa chữ thường hay không. Mặc định là sai. -
regexFilter
chuỗi không bắt buộc
Biểu thức chính quy để so khớp với url yêu cầu mạng. Thao tác này tuân theo cú pháp RE2.
Lưu ý: Bạn chỉ có thể chỉ định một trong hai trong số
urlFilter
hoặcregexFilter
.Lưu ý:
regexFilter
chỉ được bao gồm các ký tự ASCII. URL này được so khớp với URL mà máy chủ lưu trữ được mã hoá theo định dạng đâu (trong trường hợp miền quốc tế hoá) và mọi ký tự không phải ASCII khác là URL được mã hoá bằng utf-8. -
requestDomains
string[] không bắt buộc
Chrome 101 trở lênQuy tắc này sẽ chỉ so khớp các yêu cầu mạng khi miền khớp với một yêu cầu trong danh sách
requestDomains
. Nếu danh sách này bị bỏ qua, thì quy tắc sẽ áp dụng cho các yêu cầu từ tất cả các miền. Danh sách trống không được phép.Lưu ý:
- Các miền phụ như "a.example.com" cũng được cho phép.
- Các mục nhập chỉ được chứa ký tự ASCII.
- Sử dụng mã hóa mã hóa cho các miền được quốc tế hóa.
- Miền phụ của các miền có trong danh sách cũng được so khớp.
-
requestMethods
RequestMethod[] không bắt buộc
Chrome 91 trở lênDanh sách phương thức yêu cầu HTTP mà quy tắc có thể so khớp. Danh sách trống không được phép.
Lưu ý: Việc chỉ định điều kiện quy tắc
requestMethods
cũng sẽ loại trừ các yêu cầu không phải HTTP, còn việc chỉ địnhexcludedRequestMethods
thì không. -
resourceTypes
ResourceType[] không bắt buộc
Danh sách các loại tài nguyên mà quy tắc có thể khớp. Danh sách trống không được phép.
Lưu ý: thuộc tính này phải được chỉ định cho các quy tắc
allowAllRequests
và chỉ có thể bao gồm các loại tài nguyênsub_frame
vàmain_frame
. -
tabIds
number[] không bắt buộc
Chrome 92 trở lênDanh sách
tabs.Tab.id
mà quy tắc cần khớp. Mãtabs.TAB_ID_NONE
khớp với các yêu cầu không bắt nguồn từ thẻ. Danh sách trống không được phép. Chỉ hỗ trợ cho các quy tắc ở phạm vi phiên hoạt động. -
urlFilter
chuỗi không bắt buộc
Mẫu được so khớp với URL yêu cầu mạng. Các cấu trúc được hỗ trợ:
'*' : Ký tự đại diện: Khớp với số lượng ký tự bất kỳ.
'|' : Neo trái/phải: Nếu được sử dụng ở một trong hai cuối mẫu, chỉ định đầu/cuối tương ứng của url.
'||' : Liên kết tên miền: Nếu được sử dụng ở đầu mẫu, chỉ định phần đầu một miền (phụ) của URL.
'^' : Ký tự dấu phân cách: Ký tự này khớp với mọi ký tự ngoại trừ chữ cái, chữ số hoặc một trong các ký tự sau:
_
,-
,.
hoặc%
. Ký tự này cũng khớp với đuôi URL.Do đó,
urlFilter
bao gồm các phần sau: (Neo bên trái/Tên miền (không bắt buộc)) + mẫu + (Không bắt buộc liên kết bên phải).Nếu bị bỏ qua, tất cả URL đều khớp. Không được phép có chuỗi trống.
Không được phép dùng mẫu bắt đầu bằng
||*
. Sử dụng*
thay thế.Lưu ý: Bạn chỉ có thể chỉ định một trong hai trong số
urlFilter
hoặcregexFilter
.Lưu ý:
urlFilter
chỉ được bao gồm các ký tự ASCII. URL này được so khớp với URL mà máy chủ lưu trữ được mã hoá theo định dạng đâu (trong trường hợp miền quốc tế hoá) và mọi ký tự không phải ASCII khác là URL được mã hoá bằng utf-8. Ví dụ: khi URL yêu cầu là http://abc.р nướng?q=vi,urlFilter
sẽ được so khớp với URL http://abc.xn--p1ai/?q=%D1%84.
Ruleset
Thuộc tính
-
đang bật
boolean
Liệu bộ quy tắc có được bật theo mặc định hay không.
-
id
string
Chuỗi không trống xác định duy nhất bộ quy tắc. Những mã nhận dạng bắt đầu bằng '_' được dành riêng cho mục đích sử dụng nội bộ.
-
path
string
Đường dẫn của bộ quy tắc JSON tương ứng với thư mục tiện ích.
RulesMatchedDetails
Thuộc tính
-
rulesMatchedInfo
Các quy tắc khớp với bộ lọc đã cho.
TabActionCountUpdate
Thuộc tính
-
tăng dần
number
Số tiền để tăng số lượng hành động của thẻ. Giá trị âm sẽ giảm số lượng.
-
tabId
number
Thẻ cần cập nhật số lượng hành động.
TestMatchOutcomeResult
Thuộc tính
-
matchedRules
Các quy tắc (nếu có) phù hợp với yêu cầu giả định.
TestMatchRequestDetails
Thuộc tính
-
trình khởi tạo
chuỗi không bắt buộc
URL của trình khởi tạo (nếu có) cho yêu cầu giả định.
-
method
RequestMethod không bắt buộc
Phương thức HTTP chuẩn của yêu cầu giả định. Giá trị mặc định là "get" đối với các yêu cầu HTTP và sẽ bị bỏ qua đối với các yêu cầu không phải HTTP.
-
tabId
số không bắt buộc
Mã của thẻ nơi diễn ra yêu cầu giả định. Không cần tương ứng với mã thẻ thực. Giá trị mặc định là -1, nghĩa là yêu cầu không liên quan đến một thẻ.
-
loại
Loại tài nguyên của yêu cầu giả định.
-
url
string
URL của yêu cầu giả định.
UnsupportedRegexReason
Mô tả lý do tại sao một biểu thức chính quy cụ thể không được hỗ trợ.
Liệt kê
"syntaxError"
Biểu thức chính quy có cú pháp không chính xác hoặc sử dụng các tính năng không có trong cú pháp RE2.
"memoryLimitrd"
Biểu thức chính quy vượt quá giới hạn bộ nhớ.
UpdateRuleOptions
Thuộc tính
-
addRules
Quy tắc[] không bắt buộc
Quy tắc cần thêm.
-
removeRuleIds
number[] không bắt buộc
Mã của các quy tắc cần xoá. Mọi mã không hợp lệ sẽ bị bỏ qua.
UpdateRulesetOptions
Thuộc tính
UpdateStaticRulesOptions
Thuộc tính
URLTransform
Thuộc tính
-
chào mừng
chuỗi không bắt buộc
Phân mảnh mới cho yêu cầu. Phải để trống, trong trường hợp này, mảnh hiện có sẽ bị xoá hoặc phải bắt đầu bằng '#'.
-
người tổ chức
chuỗi không bắt buộc
Máy chủ lưu trữ mới cho yêu cầu.
-
mật khẩu
chuỗi không bắt buộc
Mật khẩu mới cho yêu cầu.
-
path
chuỗi không bắt buộc
Đường dẫn mới cho yêu cầu. Nếu trống, đường dẫn hiện tại sẽ bị xoá.
-
cổng
chuỗi không bắt buộc
Cổng mới cho yêu cầu. Nếu trống, cổng hiện có sẽ bị xoá.
-
query
chuỗi không bắt buộc
Truy vấn mới cho yêu cầu. Phải để trống, trong trường hợp nào truy vấn hiện tại bị xoá; hay phải bắt đầu bằng '?'.
-
queryTransform
QueryTransform không bắt buộc
Thêm, xoá hoặc thay thế cặp khoá-giá trị của cụm từ tìm kiếm.
-
lược đồ
chuỗi không bắt buộc
Giao thức mới cho yêu cầu. Các giá trị được phép là "http", "https", "ftp" và "chrome-extension".
-
tên người dùng
chuỗi không bắt buộc
Tên người dùng mới cho yêu cầu.
Thuộc tính
DYNAMIC_RULESET_ID
Mã quy tắc cho các quy tắc động được tiện ích thêm vào.
Giá trị
"_dynamic"
GETMATCHEDRULES_QUOTA_INTERVAL
Khoảng thời gian có thể thực hiện lệnh gọi MAX_GETMATCHEDRULES_CALLS_PER_INTERVAL getMatchedRules
, tính bằng phút. Các lệnh gọi bổ sung sẽ không thực hiện được ngay lập tức và đặt runtime.lastError
. Lưu ý: Các cuộc gọi getMatchedRules
liên kết với một cử chỉ của người dùng sẽ được miễn hạn mức.
Giá trị
10
GUARANTEED_MINIMUM_STATIC_RULES
Số lượng quy tắc tĩnh tối thiểu được đảm bảo cho tiện ích trên các tập hợp quy tắc tĩnh được bật của nó. Mọi quy tắc vượt quá giới hạn này sẽ được tính vào giới hạn quy tắc tĩnh trên toàn cầu.
Giá trị
30000
MAX_GETMATCHEDRULES_CALLS_PER_INTERVAL
Số lần getMatchedRules
có thể được gọi trong khoảng thời gian GETMATCHEDRULES_QUOTA_INTERVAL
.
Giá trị
20
MAX_NUMBER_OF_DYNAMIC_RULES
Số quy tắc động tối đa mà một tiện ích có thể thêm.
Giá trị
30000
MAX_NUMBER_OF_ENABLED_STATIC_RULESETS
Số lượng Rulesets
tĩnh tối đa mà một tiện ích có thể bật tại một thời điểm bất kỳ.
Giá trị
50
MAX_NUMBER_OF_REGEX_RULES
Số quy tắc biểu thức chính quy tối đa mà một tiện ích có thể thêm. Hạn mức này được đánh giá riêng cho tập hợp các quy tắc động và những quy tắc được chỉ định trong tệp tài nguyên quy tắc.
Giá trị
1000
MAX_NUMBER_OF_SESSION_RULES
Số quy tắc trong phạm vi phiên hoạt động tối đa mà một tiện ích có thể thêm.
Giá trị
5000
MAX_NUMBER_OF_STATIC_RULESETS
Số lượng Rulesets
tĩnh tối đa mà một tiện ích có thể chỉ định trong khoá tệp kê khai "rule_resources"
.
Giá trị
100
MAX_NUMBER_OF_UNSAFE_DYNAMIC_RULES
Số lượng quy tắc động "không an toàn" tối đa mà một tiện ích có thể thêm.
Giá trị
5000
MAX_NUMBER_OF_UNSAFE_SESSION_RULES
Số quy tắc trong phạm vi phiên hoạt động "không an toàn" tối đa mà một tiện ích có thể thêm.
Giá trị
5000
SESSION_RULESET_ID
Mã quy tắc cho các quy tắc trong phạm vi phiên hoạt động mà tiện ích đã thêm.
Giá trị
"_session"
Phương thức
getAvailableStaticRuleCount()
chrome.declarativeNetRequest.getAvailableStaticRuleCount(
callback?: function,
)
Trả về số lượng quy tắc tĩnh mà một tiện ích có thể bật trước khi đạt đến giới hạn quy tắc tĩnh trên toàn cầu.
Tham số
-
số gọi lại
hàm không bắt buộc
Tham số
callback
sẽ có dạng như sau:(count: number)=>void
-
số lượng
number
-
Giá trị trả về
-
Hứa hẹn<number>
Chrome 91 trở lênLờ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.
getDisabledRuleIds()
chrome.declarativeNetRequest.getDisabledRuleIds(
options: GetDisabledRuleIdsOptions,
callback?: function,
)
Trả về danh sách các quy tắc tĩnh trong Ruleset
đã cho hiện đang bị vô hiệu hoá.
Tham số
-
tùy chọn
Chỉ định bộ quy tắc để truy vấn.
-
số gọi lại
hàm không bắt buộc
Tham số
callback
sẽ có dạng như sau:(disabledRuleIds: number[])=>void
-
disabledRuleIds
số[]
-
Giá trị trả về
-
Hứa hẹn<number[]>
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.
getDynamicRules()
chrome.declarativeNetRequest.getDynamicRules(
filter?: GetRulesFilter,
callback?: function,
)
Trả về tập hợp các quy tắc động hiện tại cho tiện ích. Phương thức gọi có thể tuỳ ý lọc danh sách quy tắc đã tìm nạp bằng cách chỉ định filter
.
Tham số
-
filter
GetRulesFilter không bắt buộc
Chrome 111 trở lênĐối tượng để lọc danh sách các quy tắc đã tìm nạp.
-
số gọi lại
hàm không bắt buộc
Tham số
callback
sẽ có dạng như sau:(rules: Rule[])=>void
-
quy tắc
Quy tắc[]
-
Giá trị trả về
-
Lời hứa<Quy tắc[]>
Chrome 91 trở lênLờ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.
getEnabledRulesets()
chrome.declarativeNetRequest.getEnabledRulesets(
callback?: function,
)
Trả về mã nhận dạng cho tập hợp các quy tắc tĩnh đang bật.
Tham số
-
số gọi lại
hàm không bắt buộc
Tham số
callback
sẽ có dạng như sau:(rulesetIds: string[])=>void
-
rulesetIds
chuỗi[]
-
Giá trị trả về
-
Hứa hẹn<string[]>
Chrome 91 trở lênLờ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.
getMatchedRules()
chrome.declarativeNetRequest.getMatchedRules(
filter?: MatchedRulesFilter,
callback?: function,
)
Trả về tất cả quy tắc khớp cho phần mở rộng. Phương thức gọi có thể tuỳ ý lọc danh sách quy tắc phù hợp bằng cách chỉ định filter
. Phương thức này chỉ dành cho những tiện ích có quyền "declarativeNetRequestFeedback"
hoặc đã được cấp quyền "activeTab"
cho tabId
được chỉ định trong filter
. Lưu ý: Các quy tắc không liên kết với tài liệu đang hoạt động được so khớp cách đây hơn 5 phút sẽ không được trả về.
Tham số
-
filter
MatchedRulesFilter không bắt buộc
Một đối tượng để lọc danh sách các quy tắc phù hợp.
-
số gọi lại
hàm không bắt buộc
Tham số
callback
sẽ có dạng như sau:(details: RulesMatchedDetails)=>void
-
chi tiết
-
Giá trị trả về
-
Promise<RulesMatchedDetails>
Chrome 91 trở lênLờ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.
getSessionRules()
chrome.declarativeNetRequest.getSessionRules(
filter?: GetRulesFilter,
callback?: function,
)
Trả về tập hợp hiện tại các quy tắc trong phạm vi phiên hoạt động cho phần mở rộng. Phương thức gọi có thể tuỳ ý lọc danh sách quy tắc đã tìm nạp bằng cách chỉ định filter
.
Tham số
-
filter
GetRulesFilter không bắt buộc
Chrome 111 trở lênĐối tượng để lọc danh sách các quy tắc đã tìm nạp.
-
số gọi lại
hàm không bắt buộc
Tham số
callback
sẽ có dạng như sau:(rules: Rule[])=>void
-
quy tắc
Quy tắc[]
-
Giá trị trả về
-
Lời hứa<Quy tắc[]>
Chrome 91 trở lênLờ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.
isRegexSupported()
chrome.declarativeNetRequest.isRegexSupported(
regexOptions: RegexOptions,
callback?: function,
)
Kiểm tra xem biểu thức chính quy đã cho có được hỗ trợ dưới dạng điều kiện quy tắc regexFilter
hay không.
Tham số
-
regexOptions
Biểu thức chính quy cần kiểm tra.
-
số gọi lại
hàm không bắt buộc
Tham số
callback
sẽ có dạng như sau:(result: IsRegexSupportedResult)=>void
-
kết quả
-
Giá trị trả về
-
Promise<IsRegexSupportedResult>
Chrome 91 trở lênLờ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.
setExtensionActionOptions()
chrome.declarativeNetRequest.setExtensionActionOptions(
options: ExtensionActionOptions,
callback?: function,
)
Định cấu hình nếu số lượng hành động cho thẻ sẽ hiển thị dưới dạng văn bản huy hiệu của thao tác tiện ích và cung cấp cách tăng số lượng hành động đó.
Tham số
-
tùy chọn
-
số gọi lại
hàm không bắt buộc
Chrome 89 trở lênTham số
callback
sẽ có dạng như sau:()=>void
Giá trị trả về
-
Promise<void>
Chrome 91 trở lênLờ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.
testMatchOutcome()
chrome.declarativeNetRequest.testMatchOutcome(
request: TestMatchRequestDetails,
callback?: function,
)
Kiểm tra xem có quy tắc declarativeNetRequest của tiện ích nào khớp với yêu cầu giả định hay không. Lưu ý: Chỉ có sẵn cho các tiện ích đã giải nén vì đây là tuỳ chọn chỉ dùng trong quá trình phát triển tiện ích.
Tham số
-
request
-
số gọi lại
hàm không bắt buộc
Tham số
callback
sẽ có dạng như sau:(result: TestMatchOutcomeResult)=>void
-
kết quả
-
Giá trị trả về
-
Promise<TestMatchOutcomeResult>
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.
updateDynamicRules()
chrome.declarativeNetRequest.updateDynamicRules(
options: UpdateRuleOptions,
callback?: function,
)
Sửa đổi bộ quy tắc động hiện tại cho phần mở rộng. Trước tiên, những quy tắc có mã nhận dạng trong options.removeRuleIds
sẽ bị xoá, sau đó, những quy tắc đã cung cấp trong options.addRules
sẽ được thêm vào. Lưu ý:
- Quá trình cập nhật này diễn ra dưới dạng một thao tác nguyên tử: hoặc tất cả các quy tắc đã chỉ định được thêm vào và bị xoá, hoặc một lỗi sẽ được trả về.
- Các quy tắc này được duy trì trong các phiên duyệt web và trong các bản cập nhật tiện ích.
- Không thể xoá các quy tắc tĩnh được chỉ định trong gói tiện ích bằng hàm này.
MAX_NUMBER_OF_DYNAMIC_AND_SESSION_RULES
là số lượng quy tắc động và quy tắc phiên tối đa kết hợp mà một tiện ích có thể thêm.
Tham số
-
tùy chọnChrome 87 trở lên
-
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 91 trở lênLờ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.
updateEnabledRulesets()
chrome.declarativeNetRequest.updateEnabledRulesets(
options: UpdateRulesetOptions,
callback?: function,
)
Cập nhật bộ quy tắc tĩnh đang bật cho tiện ích. Trước tiên, các tập hợp quy tắc có mã nhận dạng trong options.disableRulesetIds
sẽ bị xoá, sau đó, các tập hợp quy tắc liệt kê trong options.enableRulesetIds
sẽ được thêm vào.
Lưu ý rằng bộ quy tắc tĩnh đang bật sẽ được duy trì trong các phiên chứ không phải qua các bản cập nhật tiện ích, tức là khoá tệp kê khai rule_resources
sẽ xác định tập hợp các bộ quy tắc tĩnh được bật trong mỗi bản cập nhật tiện ích.
Tham số
-
tùy chọnChrome 87 trở lên
-
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 91 trở lênLờ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.
updateSessionRules()
chrome.declarativeNetRequest.updateSessionRules(
options: UpdateRuleOptions,
callback?: function,
)
Sửa đổi tập hợp hiện tại các quy tắc trong phạm vi phiên hoạt động cho phần mở rộng. Trước tiên, những quy tắc có mã nhận dạng trong options.removeRuleIds
sẽ bị xoá, sau đó, những quy tắc đã cung cấp trong options.addRules
sẽ được thêm vào. Lưu ý:
- Quá trình cập nhật này diễn ra dưới dạng một thao tác nguyên tử: hoặc tất cả các quy tắc đã chỉ định được thêm vào và bị xoá, hoặc một lỗi sẽ được trả về.
- Các quy tắc này không được duy trì trong các phiên và được sao lưu trong bộ nhớ.
MAX_NUMBER_OF_DYNAMIC_AND_SESSION_RULES
là số lượng quy tắc động và quy tắc phiên tối đa kết hợp mà một tiện ích có thể thêm.
Tham số
-
tùy chọn
-
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 91 trở lênLờ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.
updateStaticRules()
chrome.declarativeNetRequest.updateStaticRules(
options: UpdateStaticRulesOptions,
callback?: function,
)
Tắt và bật các quy tắc tĩnh riêng lẻ trong Ruleset
. Các thay đổi đối với quy tắc thuộc về Ruleset
đã tắt sẽ có hiệu lực vào lần tới khi tính năng này được bật.
Tham số
-
tùy chọn
-
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>
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.
Sự kiện
onRuleMatchedDebug
chrome.declarativeNetRequest.onRuleMatchedDebug.addListener(
callback: function,
)
Được kích hoạt khi một quy tắc được khớp với một yêu cầu. Chỉ dành cho các tiện ích đã giải nén có quyền "declarativeNetRequestFeedback"
vì quyền này chỉ dùng cho mục đích gỡ lỗi.
Tham số
-
số gọi lại
hàm
Tham số
callback
sẽ có dạng như sau:(info: MatchedRuleInfoDebug)=>void
-
info
-