Nội dung mô tả
Không gian tên chrome.events
chứa các loại phổ biến mà các sự kiện gửi API sử dụng để thông báo cho bạn khi có điều gì đó thú vị xảy ra.
Khái niệm và cách sử dụng
Event
là một đối tượng cho phép bạn nhận được thông báo khi có điều thú vị xảy ra. Dưới đây là
ví dụ về cách sử dụng sự kiện chrome.alarms.onAlarm
để nhận thông báo mỗi khi chuông báo đã trôi qua:
chrome.alarms.onAlarm.addListener((alarm) => {
appendToLog(`alarms.onAlarm -- name: ${alarm.name}, scheduledTime: ${alarm.scheduledTime}`);
});
Như ví dụ minh hoạ, bạn đăng ký nhận thông báo bằng addListener()
. Đối số cho addListener()
luôn là một hàm mà bạn xác định để xử lý sự kiện, nhưng các tham số cho hàm này phụ thuộc vào sự kiện mà bạn đang xử lý. Khi kiểm tra tài liệu về alarms.onAlarm
, bạn có thể thấy rằng hàm có một tham số duy nhất: đối tượng alarms.Alarm
có thông tin chi tiết về chuông báo đã trôi qua.
Ví dụ về các API sử dụng Sự kiện: alarms, i18n, identity, thời gian chạy. Hầu hết API chrome đều làm như vậy.
Trình xử lý sự kiện khai báo
Trình xử lý sự kiện khai báo cung cấp một phương tiện để xác định các quy tắc bao gồm các điều kiện và hành động khai báo. Các điều kiện được đánh giá trong trình duyệt thay vì công cụ JavaScript để giảm độ trễ trọn vòng và cho phép hiệu quả rất cao.
Ví dụ: trình xử lý sự kiện khai báo được sử dụng trong Declarative Content API (API Nội dung khai báo). Trang này mô tả các khái niệm cơ bản của tất cả các trình xử lý sự kiện khai báo.
Quy tắc
Quy tắc đơn giản nhất có thể bao gồm một hoặc nhiều điều kiện và một hoặc nhiều hành động:
const rule = {
conditions: [ /* my conditions */ ],
actions: [ /* my actions */ ]
};
Nếu đáp ứng bất kỳ điều kiện nào thì tất cả các hành động sẽ được thực thi.
Ngoài các điều kiện và thao tác, bạn có thể cung cấp cho mỗi quy tắc một giá trị nhận dạng. Việc này giúp đơn giản hoá việc huỷ đăng ký các quy tắc đã đăng ký trước đó, cũng như mức độ ưu tiên để xác định mức độ ưu tiên giữa các quy tắc. Các mức độ ưu tiên chỉ được xem xét nếu các quy tắc xung đột với nhau hoặc cần được thực thi theo một thứ tự cụ thể. Các hành động được thực thi theo thứ tự giảm dần mức độ ưu tiên của các quy tắc.
const rule = {
id: "my rule", // optional, will be generated if not set.
priority: 100, // optional, defaults to 100.
conditions: [ /* my conditions */ ],
actions: [ /* my actions */ ]
};
Đối tượng sự kiện
Đối tượng sự kiện có thể hỗ trợ các quy tắc. Các đối tượng sự kiện này không gọi hàm callback khi sự kiện xảy ra, nhưng sẽ kiểm tra xem bất kỳ quy tắc đã đăng ký 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 liên kết với quy tắc này. Các đối tượng sự kiện hỗ trợ API khai báo có 3 phương thức liên quan: events.Event.addRules()
, events.Event.removeRules()
và events.Event.getRules()
.
Thêm quy tắc
Để thêm quy tắc, hãy gọi hàm addRules()
của đối tượng sự kiện. Phương thức này lấy một mảng các thực thể quy tắc làm tham số đầu tiên và một hàm callback được gọi khi hoàn thành.
const rule_list = [rule1, rule2, ...];
addRules(rule_list, (details) => {...});
Nếu các quy tắc được chèn thành công, tham số details
chứa một mảng các quy tắc được chèn sẽ xuất hiện theo thứ tự như trong rule_list
được truyền, trong đó các tham số không bắt buộc id
và priority
được điền bằng các giá trị đã tạo. Nếu có bất kỳ quy tắc nào không hợp lệ, chẳng hạn như vì quy tắc đó chứa điều kiện hoặc hành động không hợp lệ, thì sẽ không có quy tắc nào được thêm và biến runtime.lastError được đặt khi gọi hàm gọi lại. Mỗi quy tắc trong rule_list
phải chứa một giá trị nhận dạng duy nhất chưa được một quy tắc khác sử dụng hoặc chưa có một giá trị nhận dạng trống.
Xoá quy tắc
Để xoá quy tắc, hãy gọi hàm removeRules()
. Phương thức này chấp nhận một mảng giá trị nhận dạng quy tắc (không bắt buộc) làm tham số đầu tiên và một hàm callback làm tham số thứ hai.
const rule_ids = ["id1", "id2", ...];
removeRules(rule_ids, () => {...});
Nếu rule_ids
là một mảng giá trị nhận dạng, thì mọi quy tắc có giá trị nhận dạng được liệt kê trong mảng đó sẽ bị xoá. Nếu rule_ids
liệt kê một giá trị nhận dạng không xác định, thì giá trị nhận dạng này sẽ tự động bị bỏ qua. Nếu rule_ids
là undefined
, thì mọi quy tắc đã đăng ký của tiện ích này sẽ bị xoá. Hàm callback()
được gọi khi các quy tắc bị xoá.
Truy xuất quy tắc
Để truy xuất danh sách các quy tắc đã đăng ký, hãy gọi hàm getRules()
. Phương thức này chấp nhận một mảng (không bắt buộc) gồm các giá trị nhận dạng quy tắc có cùng ngữ nghĩa như removeRules()
và một hàm callback.
const rule_ids = ["id1", "id2", ...];
getRules(rule_ids, (details) => {...});
Tham số details
được truyền đến hàm callback()
tham chiếu đến một mảng quy tắc, bao gồm cả các tham số không bắt buộc đã được điền.
Hiệu suất
Để đạt được hiệu suất tối đa, bạn nên ghi nhớ các nguyên tắc sau.
Đăng ký và huỷ đăng ký hàng loạt quy tắc. Sau mỗi lần đăng ký hoặc huỷ đăng ký, Chrome cần cập nhật cấu trúc dữ liệu nội bộ. Việc cập nhật này là một thao tác tiêu tốn nhiều tài nguyên.
const rule1 = {...}; const rule2 = {...}; chrome.declarativeWebRequest.onRequest.addRules([rule1]); chrome.declarativeWebRequest.onRequest.addRules([rule2]);
const rule1 = {...}; const rule2 = {...}; chrome.declarativeWebRequest.onRequest.addRules([rule1, rule2]);
Ưu tiên khớp chuỗi con hơn biểu thức chính quy trong events.UrlFilter. Quá trình so khớp dựa trên chuỗi con cực kỳ nhanh.
const match = new chrome.declarativeWebRequest.RequestMatcher({ url: {urlMatches: "example.com/[^?]*foo" } });
const match = new chrome.declarativeWebRequest.RequestMatcher({ url: {hostSuffix: "example.com", pathContains: "foo"} });
Nếu có nhiều quy tắc áp dụng cùng một thao tác, hãy hợp nhất các quy tắc thành một. Quy tắc sẽ kích hoạt hành động ngay sau khi một điều kiện được đáp ứng. Điều này giúp tăng tốc độ khớp và giảm mức tiêu thụ bộ nhớ cho các nhóm hành động trùng lặp.
const condition1 = new chrome.declarativeWebRequest.RequestMatcher({ url: { hostSuffix: 'example.com' } }); const condition2 = new chrome.declarativeWebRequest.RequestMatcher({ url: { hostSuffix: 'foobar.com' } }); const rule1 = { conditions: [condition1], actions: [new chrome.declarativeWebRequest.CancelRequest()] }; const rule2 = { conditions: [condition2], actions: [new chrome.declarativeWebRequest.CancelRequest()] }; chrome.declarativeWebRequest.onRequest.addRules([rule1, rule2]);
const condition1 = new chrome.declarativeWebRequest.RequestMatcher({ url: { hostSuffix: 'example.com' } }); const condition2 = new chrome.declarativeWebRequest.RequestMatcher({ url: { hostSuffix: 'foobar.com' } }); const rule = { conditions: [condition1, condition2], actions: [new chrome.declarativeWebRequest.CancelRequest()] }; chrome.declarativeWebRequest.onRequest.addRules([rule]);
Sự kiện đã lọc
Sự kiện được lọc là một cơ chế cho phép trình nghe chỉ định một nhóm nhỏ các sự kiện mà họ quan tâm. Trình nghe sử dụng bộ lọc sẽ không được gọi cho các sự kiện không vượt qua bộ lọc, giúp mã nghe có tính khai báo và hiệu quả hơn. service worker không cần được đánh thức để xử lý các sự kiện mà nó không quan tâm.
Mục đích của sự kiện được lọc là cho phép chuyển đổi từ mã lọc thủ công.
chrome.webNavigation.onCommitted.addListener((event) => { if (hasHostSuffix(event.url, 'google.com') || hasHostSuffix(event.url, 'google.com.au')) { // ... } });
chrome.webNavigation.onCommitted.addListener((event) => { // ... }, {url: [{hostSuffix: 'google.com'}, {hostSuffix: 'google.com.au'}]});
Sự kiện hỗ trợ những bộ lọc cụ thể có ý nghĩa đối với sự kiện đó. Danh sách bộ lọc mà một sự kiện hỗ trợ sẽ được liệt kê trong tài liệu cho sự kiện đó ở mục "bộ lọc".
Khi so khớp URL (như trong ví dụ trên), các bộ lọc sự kiện đều hỗ trợ cùng khả năng so khớp URL như có thể biểu thị với events.UrlFilter
, ngoại trừ tính năng so khớp giao thức và cổng.
Loại
Event
Một đối tượng cho phép thêm và xoá trình nghe của một sự kiện trên Chrome.
Thuộc tính
-
addListener
void
Đăng ký lệnh gọi lại của trình nghe sự kiện cho một sự kiện.
Hàm
addListener
sẽ có dạng như sau:(callback: H) => {...}
-
số gọi lại
Số lần bị đánh trúng bóng
Được gọi khi một sự kiện xảy ra. Các thông số của hàm này phụ thuộc vào loại sự kiện.
-
-
addRules
void
Đăng ký các quy tắc để xử lý các sự kiện.
Hàm
addRules
sẽ có dạng như sau:(rules: Rule<anyany>[], callback?: function) => {...}
-
quy tắc
Quy tắc<any>[]
Các quy tắc cần đăng ký. Các quy tắc này không thay thế các quy tắc đã đăng ký trước đây.
-
số gọi lại
hàm không bắt buộc
Tham số
callback
sẽ có dạng như sau:(rules: Rule<anyany>[]) => void
-
quy tắc
Quy tắc<any>[]
Các quy tắc đã được đăng ký, các thông số không bắt buộc sẽ được điền bằng các giá trị.
-
-
-
getRules
void
Trả về các quy tắc hiện đã được đăng ký.
Hàm
getRules
sẽ có dạng như sau:(ruleIdentifiers?: string[], callback: function) => {...}
-
ruleIdentifiers
string[] không bắt buộc
Nếu một mảng được truyền thì chỉ các quy tắc có giá trị nhận dạng có trong mảng này mới được trả về.
-
số gọi lại
hàm
Tham số
callback
sẽ có dạng như sau:(rules: Rule<anyany>[]) => void
-
quy tắc
Quy tắc<any>[]
Các quy tắc đã được đăng ký, các thông số không bắt buộc sẽ được điền bằng các giá trị.
-
-
-
hasListener
void
Hàm
hasListener
sẽ có dạng như sau:(callback: H) => {...}
-
số gọi lại
Số lần bị đánh trúng bóng
Trình nghe có trạng thái đăng ký sẽ được kiểm tra.
-
giá trị trả về
boolean
Đúng nếu bạn đăng ký lệnh gọi lại cho sự kiện.
-
-
hasListeners
void
Hàm
hasListeners
sẽ có dạng như sau:() => {...}
-
giá trị trả về
boolean
Đúng nếu có bất kỳ trình nghe sự kiện nào được đăng ký cho sự kiện.
-
-
removeListener
void
Huỷ đăng ký lệnh gọi lại của trình nghe sự kiện khỏi một sự kiện.
Hàm
removeListener
sẽ có dạng như sau:(callback: H) => {...}
-
số gọi lại
Số lần bị đánh trúng bóng
Trình nghe này sẽ bị huỷ đăng ký.
-
-
removeRules
void
Huỷ đăng ký các quy tắc hiện đã được đăng ký.
Hàm
removeRules
sẽ có dạng như sau:(ruleIdentifiers?: string[], callback?: function) => {...}
-
ruleIdentifiers
string[] không bắt buộc
Nếu một mảng được truyền, thì chỉ các quy tắc có giá trị nhận dạng có trong mảng này mới bị huỷ đăng ký.
-
số gọi lại
hàm không bắt buộc
Tham số
callback
sẽ có dạng như sau:() => void
-
Rule
Nội dung mô tả quy tắc khai báo để xử lý sự kiện.
Thuộc tính
-
thao tác
bất kỳ[]
Danh sách các hành động được kích hoạt nếu một trong các điều kiện được đáp ứng.
-
conditions
bất kỳ[]
Danh sách các điều kiện có thể kích hoạt hành động.
-
id
chuỗi không bắt buộc
Giá trị nhận dạng không bắt buộc cho phép tham chiếu đến quy tắc này.
-
của chiến dịch
số không bắt buộc
Mức độ ưu tiên không bắt buộc của quy tắc này. Giá trị mặc định là 100.
-
thẻ
string[] không bắt buộc
Có thể sử dụng thẻ để chú thích quy tắc và thực hiện thao tác trên bộ quy tắc.
UrlFilter
Lọc URL theo nhiều tiêu chí. Xem phần lọc sự kiện. Tất cả tiêu chí đều phân biệt chữ hoa chữ thường.
Thuộc tính
-
cidrBlocks
string[] không bắt buộc
Chrome 123 trở lênSo khớp xem phần máy chủ lưu trữ của URL là một địa chỉ IP và nằm trong bất kỳ khối CIDR nào được chỉ định trong mảng.
-
hostContains
chuỗi không bắt buộc
So khớp xem tên máy chủ của URL có chứa chuỗi được chỉ định hay không. Để kiểm tra xem thành phần tên máy chủ có tiền tố "foo" hay không, hãy sử dụng hostcontains: ".foo". Tên này khớp với "www.foobar.com" và "foo.com", vì một dấu chấm ngầm ẩn được thêm vào đầu tên máy chủ lưu trữ. Tương tự, bạn có thể sử dụng hostcontains để so khớp với hậu tố thành phần ("foo.") và so khớp chính xác với các thành phần (".foo."). Hậu tố và so khớp chính xác cho các thành phần cuối cần được thực hiện riêng biệt bằng hostSuffix, vì không có dấu chấm ngầm ẩn nào được thêm vào cuối tên máy chủ.
-
hostEquals
chuỗi không bắt buộc
So khớp xem tên máy chủ của URL có bằng với một chuỗi đã chỉ định hay không.
-
hostPrefix
chuỗi không bắt buộc
So khớp xem tên máy chủ của URL bắt đầu bằng một chuỗi đã chỉ định hay không.
-
hostSuffix
chuỗi không bắt buộc
So khớp xem tên máy chủ lưu trữ của URL có kết thúc bằng một chuỗi đã chỉ định hay không.
-
originAndPathMatches
chuỗi không bắt buộc
So khớp xem URL không có phân đoạn truy vấn và mã nhận dạng phân đoạn có khớp với một biểu thức chính quy đã chỉ định hay không. Số cổng bị xoá khỏi URL nếu khớp với số cổng mặc định. Biểu thức chính quy sử dụng cú pháp RE2.
-
pathContains
chuỗi không bắt buộc
So khớp xem phân đoạn đường dẫn của URL có chứa chuỗi được chỉ định hay không.
-
pathEquals
chuỗi không bắt buộc
So khớp xem phân đoạn đường dẫn của URL có bằng với một chuỗi đã chỉ định hay không.
-
pathPrefix
chuỗi không bắt buộc
So khớp xem phân đoạn đường dẫn của URL bắt đầu bằng một chuỗi đã chỉ định hay không.
-
pathSuffix
chuỗi không bắt buộc
So khớp xem phân đoạn đường dẫn của URL có kết thúc bằng một chuỗi đã chỉ định hay không.
-
ports
(number | number[🥭] không bắt buộc
So khớp xem cổng của URL có nằm trong bất kỳ danh sách cổng nào được chỉ định hay không. Ví dụ:
[80, 443, [1000, 1200]]
khớp với tất cả yêu cầu trên cổng 80, 443 và trong phạm vi 1000-1200. -
queryContains
chuỗi không bắt buộc
So khớp xem phân đoạn truy vấn của URL có chứa chuỗi được chỉ định hay không.
-
queryEquals
chuỗi không bắt buộc
So khớp xem phân đoạn truy vấn của URL có bằng với một chuỗi đã chỉ định hay không.
-
queryPrefix
chuỗi không bắt buộc
So khớp xem phân đoạn truy vấn của URL có bắt đầu bằng một chuỗi đã chỉ định hay không.
-
querySuffix
chuỗi không bắt buộc
So khớp xem phân đoạn truy vấn của URL có kết thúc bằng một chuỗi đã chỉ định hay không.
-
schemes
string[] không bắt buộc
So khớp xem lược đồ của URL có bằng với bất kỳ lược đồ nào được chỉ định trong mảng hay không.
-
urlContains
chuỗi không bắt buộc
So khớp xem URL (không có giá trị nhận dạng phân đoạn) có chứa chuỗi được chỉ định hay không. Số cổng bị xoá khỏi URL nếu khớp với số cổng mặc định.
-
urlEquals
chuỗi không bắt buộc
So khớp xem URL (không có giá trị nhận dạng phân đoạn) có bằng với một chuỗi được chỉ định hay không. Số cổng bị xoá khỏi URL nếu khớp với số cổng mặc định.
-
urlMatches
chuỗi không bắt buộc
So khớp xem URL (không có mã nhận dạng phân đoạn) có khớp với biểu thức chính quy đã chỉ định hay không. Số cổng bị xoá khỏi URL nếu khớp với số cổng mặc định. Biểu thức chính quy sử dụng cú pháp RE2.
-
urlPrefix
chuỗi không bắt buộc
So khớp xem URL (không có mã nhận dạng phân đoạn) bắt đầu bằng một chuỗi đã chỉ định hay không. Số cổng bị xoá khỏi URL nếu khớp với số cổng mặc định.
-
urlSuffix
chuỗi không bắt buộc
So khớp xem URL (không có giá trị nhận dạng phân đoạn) kết thúc bằng một chuỗi đã chỉ định hay không. Số cổng bị xoá khỏi URL nếu khớp với số cổng mặc định.