browser.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ó điều gì đó thú vị xảy ra. Dưới đây là ví dụ về cách sử dụng sự kiện browser.alarms.onAlarm để nhận thông báo bất cứ khi nào báo thức đã hết thời gian:

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

Như ví dụ cho thấy, bạn đăng ký nhận thông báo bằng cách sử dụ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 này có một tham số duy nhất: một đối tượng alarms.Alarm có thông tin chi tiết về báo thức đã trôi qua.

Ví dụ về các API sử dụng Sự kiện: alarms, i18n, identity, runtime. Hầu hết các API của Chrome đều làm được điều nà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úp giảm độ trễ khứ hồi và cho phép đạt hiệu suất rất cao.

Ví dụ: trình xử lý sự kiện khai báo được dùng trong Declarative Content API. Trang này mô tả các khái niệm cơ bản của tất 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 một trong các điều kiện đượ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ể chỉ định 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 đó và một mức độ ưu tiên để xác định thứ tự ưu tiên giữa các quy tắ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 thao tác được thực thi theo thứ tự giảm dần về 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ợ 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 mà kiểm tra xem có 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 được 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 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, tham số details sẽ chứa một mảng các quy tắc được chèn xuất hiện theo cùng một thứ tự như trong rule_list đã 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ị được tạo. Nếu có quy tắc không hợp lệ (ví dụ: vì quy tắc đó chứa điều kiện hoặc hành động không hợp lệ), thì không có quy tắc nào được thêm và biến runtime.lastError sẽ được đặt khi hàm callback được gọi. Mỗi quy tắc trong rule_list phải chứa một giá trị nhận dạng riêng biệt chưa được dùng bởi một quy tắc khác hoặc một giá trị nhận dạng trống.

Xoá quy tắc

Để xoá các quy tắc, hãy gọi hàm removeRules(). 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 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ì tất cả các 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ẽ bị bỏ qua một cách âm thầm. Nếu rule_ids là undefined, tất cả các 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(). Thẻ 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 với 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() đề cập đến một mảng các 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 các 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ộ. Bản cập nhật này là một thao tác tốn kém.

const rule1 = {...};
const rule2 = {...};
browser.declarativeWebRequest.onRequest.addRules([rule1]);
browser.declarativeWebRequest.onRequest.addRules([rule2]);

const rule1 = {...};
const rule2 = {...};
browser.declarativeWebRequest.onRequest.addRules([rule1, rule2]);

Ưu tiên so khớp chuỗi con hơn biểu thức chính quy trong events.UrlFilter. Tính năng so khớp dựa trên chuỗi con hoạt động cực kỳ nhanh.

const match = new browser.declarativeWebRequest.RequestMatcher({
  url: {urlMatches: "example.com/[^?]*foo" }
});

const match = new browser.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. Các quy tắc sẽ kích hoạt hành động ngay khi một điều kiện được đáp ứng. Điều này giúp tăng tốc độ so khớp và giảm mức tiêu thụ bộ nhớ cho các nhóm thao tác trùng lặp.

const condition1 = new browser.declarativeWebRequest.RequestMatcher({
  url: { hostSuffix: 'example.com' }
});
const condition2 = new browser.declarativeWebRequest.RequestMatcher({
  url: { hostSuffix: 'foobar.com' }
});
const rule1 = { conditions: [condition1],
                actions: [new browser.declarativeWebRequest.CancelRequest()]
              };
const rule2 = { conditions: [condition2],
                actions: [new browser.declarativeWebRequest.CancelRequest()]
              };
browser.declarativeWebRequest.onRequest.addRules([rule1, rule2]);

const condition1 = new browser.declarativeWebRequest.RequestMatcher({
  url: { hostSuffix: 'example.com' }
});
const condition2 = new browser.declarativeWebRequest.RequestMatcher({
  url: { hostSuffix: 'foobar.com' }
});
const rule = { conditions: [condition1, condition2],
              actions: [new browser.declarativeWebRequest.CancelRequest()]
             };
browser.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 những sự kiện không vượt qua bộ lọc, điều này giúp mã nghe khai báo và hiệu quả hơn. Trình chạy dịch vụ không cần được đánh thức để xử lý các sự kiện mà nó không quan tâm.

Các sự kiện được lọc nhằm cho phép chuyển đổi từ mã lọc thủ công.

browser.webNavigation.onCommitted.addListener((event) => {
  if (hasHostSuffix(event.url, 'google.com') ||
      hasHostSuffix(event.url, 'google.com.au')) {
    // ...
  }
});

browser.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 các bộ lọc mà một sự kiện hỗ trợ sẽ được liệt kê trong tài liệu về sự kiện đó trong phần "bộ lọc".

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