chrome.events

Nội dung mô tả

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.