chrome.events

refresh date: 2026-09-25 robots: noindex

Mô tả

Event là một đối tượng cho phép bạn nhận được thông báo khi có sự kiện thú vị xảy ra. Sau đây là ví dụ về cách sử dụng sự kiện chrome.alarms.onAlarm để nhận thông báo bất cứ khi nào báo thức đã hết giờ:

chrome.alarms.onAlarm.addListener(function(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 API chrome đều làm đượ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 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à mang lại hiệu quả rất cao.

Ví dụ: trình xử lý sự kiện khai báo được dùng trong Declarative Web Request API và 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:

var rule = {
  conditions: [ /* my conditions */ ],
  actions: [ /* my actions */ ]
};

Nếu bất kỳ điều kiện nào được đáp ứng, tất cả các hành động sẽ được thực hiện.

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. Bạn chỉ cần cân nhắc mức độ ưu tiên 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 về mức độ ưu tiên của các quy tắc.

var 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 các quy tắc, hãy gọi hàm addRules() của đối tượng sự kiện. Nó 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.

var rule_list = [rule1, rule2, ...];
function addRules(rule_list, function callback(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 một đ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 mà hiện không đượ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.

var rule_ids = ["id1", "id2", ...];
function removeRules(rule_ids, function callback() {...});

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 hiện đã đăng ký, hãy gọi hàm getRules(). Thành phần 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.

var rule_ids = ["id1", "id2", ...];
function getRules(rule_ids, function callback(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 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ộ. Thao tác cập nhật này tốn nhiều tài nguyên.

Thay vì:

var rule1 = {...};
var rule2 = {...};
chrome.declarativeWebRequest.onRequest.addRules([rule1]);
chrome.declarativeWebRequest.onRequest.addRules([rule2]);

prefer:

var rule1 = {...};
var rule2 = {...};
chrome.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 chóng.

Thay vì:

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

prefer:

var match = new chrome.declarativeWebRequest.RequestMatcher({
    url: {hostSuffix: "example.com", pathContains: "foo"} });

Nếu có nhiều quy tắc dùng chung các hành động, hãy hợp nhất các quy tắc đó thành một quy tắc. 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 quá trình so khớp và giảm mức tiêu thụ bộ nhớ cho các nhóm hành động trùng lặp.

Thay vì:

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

prefer:

  var 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 những sự kiện không vượt qua bộ lọc, điều này giúp mã nghe mang tính 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 như sau:

chrome.webNavigation.onCommitted.addListener(function(e) {
  if (hasHostSuffix(e.url, 'google.com') ||
      hasHostSuffix(e.url, 'google.com.au')) {
    // ...
  }
});

thành:

chrome.webNavigation.onCommitted.addListener(function(e) {
  // ...
}, {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 cho sự kiện đó trong phần "filters" (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.