chrome.events

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ó một điều gì đó thú vị xảy ra. Sau đây là một ví dụ về cách sử dụng sự kiện chrome.alarms.onAlarm để nhận thông báo mỗi khi một chuông báo trôi qua:

chrome.alarms.onAlarm.addListener((alarm) => {
  appendToLog(`alarms.onAlarm -- name: ${alarm.name}, scheduledTime: ${alarm.scheduledTime}`);
});

Trong ví dụ này, bạn đăng ký thông báo bằng addListener(). Đối số với addListener() luôn là một hàm bạn xác định để xử lý sự kiện, nhưng các tham số đến giá trị phụ thuộc vào sự kiện bạn đang xử lý. Đang 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ó các thông tin chi tiết về chuông báo đã trôi qua.

Các API mẫu sử dụng Sự kiện: báo thức, i18n, identity, thời gian chạy. Hầu hết Chrome API thì có.

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 khai báo và hành động. Các điều kiện được đánh giá trong trình duyệt thay vì công cụ JavaScript, công cụ này giúp giảm độ trễ trọn vòng và cho phép hiệu quả rất cao.

Trình xử lý sự kiện khai báo được dùng, chẳng hạn như trong Khai báo Content API. Trang này mô tả các khái niệm cơ bản của tất cả sự kiện khai báo trình xử lý.

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 bất kỳ điều kiện nào được đáp ứng, thì tất cả các hành động sẽ được thực thi.

Ngoài các điều kiện và hành động, bạn có thể cung cấp cho mỗi quy tắc một mã nhận dạng để đơn giản hoá huỷ đăng ký các quy tắc đã đăng ký trước đó và 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 cách cụ thể đơn đặt hàng. Các thao tác được thực thi theo thứ tự giảm dần của 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

Các đối tượng sự kiện có thể hỗ trợ quy tắc. Những đối tượng sự kiện này không gọi một hàm callback khi sự kiện xảy ra nhưng kiểm tra xem có bất kỳ quy tắc đã đăng ký nào có ít nhất một điều kiện được thực hiện hay không và thực thi các hành động liên quan đến quy tắc này. Các đối tượng sự kiện hỗ trợ API khai báo có 3 các phương thức phù hợp: 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ải lấy một mảng các thực thể quy tắc làm tham số đầu tiên và hàm callback được gọi khi hoàn tất.

const rule_list = [rule1, rule2, ...];
addRules(rule_list, (details) => {...});

Nếu các quy tắc đã được chèn thành công, thì tham số details sẽ chứa một mảng các quy tắc được chèn xuất hiện theo thứ tự như trong rule_list đã chuyển, trong đó các tham số không bắt buộc id và priority đã được điền các giá trị đã tạo. Nếu có bất kỳ quy tắc nào không hợp lệ, ví dụ: do quy tắc đó chứa điều kiện hoặc hành động không hợp lệ, không có quy tắc nào được thêm và biến runtime.lastError được đặt khi hàm callback được gọi. Mỗi quy tắc trong rule_list phải chứa một quy tắc duy nhất giá trị nhận dạng chưa được quy tắc khác sử dụng hoặc giá trị nhận dạng trống.

Xoá quy tắc

Để xoá quy tắc, hãy gọi hàm removeRules(). Hàm này chấp nhận một loạt các giá trị nhận dạng quy tắc (không bắt buộc) làm tham số đầu tiên và 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ì tất cả quy tắc có giá trị nhận dạng được liệt kê trong mảng đó đều đã bị xóa. Nếu rule_ids liệt kê một giá trị nhận dạng mà 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, tất cả quy tắc đã đăng ký của tiện ích này đều bị xoá. callback() được gọi khi các quy tắc đã bị xoá.

Truy xuất quy tắc

Để truy xuất danh sách quy tắc đã đăng ký, hãy gọi hàm getRules(). Ứng dụng 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 các quy tắc bao gồm tham số không bắt buộc.

Hiệu suất

Để đạt được hiệu suất tối đa, bạn nên lưu ý các nguyên tắc sau.

Đăng ký và huỷ đăng ký nhiều quy tắc cùng một lú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ộ. Cập nhật này là một thao tác tốn kém.

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 so khớp chuỗi con thay vì 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 có cùng hành động, 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 khi một điều kiện duy nhất được đáp ứng. Việc này giúp đẩy nhanh khớp và giảm mức sử dụng 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à cơ chế cho phép người nghe chỉ định một nhóm nhỏ sự kiện 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 giúp mã nghe rõ ràng và hiệu quả hơn. service worker cần không 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ợ các 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 đó trong "bộ lọc" .

Khi so khớp các URL (như trong ví dụ ở trên), bộ lọc sự kiện hỗ trợ so khớp cùng một URL các chức năng có thể biểu thị bằng events.UrlFilter, ngoại trừ việc so khớp giao thức và cổng.