chrome.events

תאריך הרענון: 2026-09-25 robots: noindex

תיאור

Event הוא אובייקט שמאפשר לקבל התראה כשקורה משהו מעניין. הנה דוגמה לשימוש באירוע chrome.alarms.onAlarm כדי לקבל התראה בכל פעם שחלף זמן האזעקה:

chrome.alarms.onAlarm.addListener(function(alarm) {
  appendToLog('alarms.onAlarm --'
              + ' name: '          + alarm.name
              + ' scheduledTime: ' + alarm.scheduledTime);
});

כפי שאפשר לראות בדוגמה, אתם נרשמים לקבלת התראות באמצעות addListener(). הארגומנט של addListener() הוא תמיד פונקציה שאתם מגדירים כדי לטפל באירוע, אבל הפרמטרים של הפונקציה תלויים באירוע שבו אתם מטפלים. אם בודקים את התיעוד של alarms.onAlarm, אפשר לראות שלפונקציה יש פרמטר יחיד: אובייקט alarms.Alarm שמכיל פרטים על הזמן שחלף מאז ההתראה.

דוגמאות לממשקי API שמשתמשים באירועים: alarms, ‏ i18n, ‏ identity, ‏ runtime. רוב ממשקי ה-API של Chrome עושים זאת.

גורמים הצהרתיים שמטפלים באירועים

ה-event handlers הדקלרטיביים מאפשרים להגדיר כללים שמורכבים מתנאים ומפעולות דקלרטיביים. התנאים נבדקים בדפדפן ולא במנוע JavaScript, מה שמקטין את זמן האחזור של הלוך ושוב ומאפשר יעילות גבוהה מאוד.

לדוגמה, נעשה שימוש ב-Declarative event handlers ב-Declarative Web Request API וב-Declarative Content API. בדף הזה מוסברים המושגים הבסיסיים של כל הפונקציות לטיפול באירועים דקלרטיביים.

כללים

הכלל הפשוט ביותר האפשרי מורכב מתנאי אחד או יותר ומפעולה אחת או יותר:

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

אם אחד מהתנאים מתקיים, כל הפעולות מבוצעות.

בנוסף לתנאים ולפעולות, אפשר לתת לכל כלל מזהה שמפשט את ביטול הרישום של כללים שנרשמו בעבר, וגם עדיפות כדי להגדיר את סדר הפעולות בין הכללים. המערכת מתייחסת לעדיפויות רק אם הכללים סותרים זה את זה או אם צריך להפעיל אותם בסדר מסוים. הפעולות מבוצעות בסדר יורד של העדיפות של הכללים שלהן.

var rule = {
  id: "my rule",  // optional, will be generated if not set.
  priority: 100,  // optional, defaults to 100.
  conditions: [ /* my conditions */ ],
  actions: [ /* my actions */ ]
};

אובייקטים של אירועים

יכול להיות שאובייקטים של אירועים יתמכו בכללים. אובייקטים של אירועים כאלה לא מפעילים פונקציית קריאה חוזרת כשמתרחשים אירועים, אלא בודקים אם לכלל רשום יש לפחות תנאי אחד שמתקיים, ומבצעים את הפעולות שמשויכות לכלל הזה. לאובייקטים של אירועים שתומכים ב-API הדקלרטיבי יש שלוש שיטות רלוונטיות: events.Event.addRules,‏ events.Event.removeRules ו-events.Event.getRules.

הוספת כללים

כדי להוסיף כללים, קוראים לפונקציה addRules() של אובייקט האירוע. הפרמטר הראשון שלה הוא מערך של מופעי כללים, והפרמטר השני הוא פונקציית קריאה חוזרת שמופעלת בסיום.

var rule_list = [rule1, rule2, ...];
function addRules(rule_list, function callback(details) {...});

אם הכללים הוכנסו בהצלחה, הפרמטר details מכיל מערך של כללים שהוכנסו בסדר שבו הם מופיעים בפרמטר rule_list שהועבר, כאשר הפרמטרים האופציונליים id ו-priority מולאו בערכים שנוצרו. אם כלל כלשהו לא תקין, למשל כי הוא הכיל תנאי או פעולה לא תקינים, אף אחד מהכללים לא יתווסף והמשתנה runtime.lastError יוגדר כשפונקציית הקריאה החוזרת תופעל. כל כלל ב-rule_list צריך להכיל מזהה ייחודי שלא נמצא כרגע בשימוש בכלל אחר, או מזהה ריק.

הסרת כללים

כדי להסיר כללים, קוראים לפונקציה removeRules(). היא מקבלת מערך אופציונלי של מזהי כללים כפרמטר הראשון ופונקציית קריאה חוזרת כפרמטר השני.

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

אם rule_ids הוא מערך של מזהים, כל הכללים שמכילים מזהים שמופיעים במערך יוסרו. אם rule_ids מציג מזהה לא מוכר, המערכת מתעלמת ממנו בלי להציג הודעה. אם הערך של rule_ids הוא undefined, כל הכללים הרשומים של התוסף הזה יוסרו. הפונקציה callback() מופעלת כשהכללים הוסרו.

אחזור כללים

כדי לאחזר רשימה של כללים שרשומים כרגע, קוראים לפונקציה getRules(). הפונקציה מקבלת מערך אופציונלי של מזהי כללים עם אותה סמנטיקה כמו removeRules ופונקציית קריאה חוזרת.

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

הפרמטר details שמועבר לפונקציה callback() מתייחס למערך של כללים, כולל פרמטרים אופציונליים שמולאו.

ביצועים

כדי להשיג ביצועים מקסימליים, חשוב לפעול לפי ההנחיות הבאות.

רישום וביטול רישום של כללים בכמות גדולה. אחרי כל רישום או ביטול רישום, Chrome צריך לעדכן את מבני הנתונים הפנימיים. העדכון הזה הוא פעולה יקרה.

במקום:

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]);

עדיף להשתמש בהתאמה של מחרוזת משנה במקום בביטויים רגולריים ב-events.UrlFilter. התאמה שמבוססת על מחרוזת משנה היא מהירה מאוד.

במקום:

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

prefer:‎

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

אם יש הרבה כללים עם אותן פעולות, כדאי למזג אותם לכלל אחד. הפעולות של הכללים מופעלות ברגע שתנאי אחד מתקיים. כך אפשר להאיץ את ההתאמה ולצמצם את צריכת הזיכרון של קבוצות כפולות של פעולות.

במקום:

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]);

אירועים מסוננים

אירועים מסוננים הם מנגנון שמאפשר לפונקציות event listener לציין קבוצת משנה של אירועים שהן מתעניינות בהם. פונקציית listener שמשתמשת במסנן לא תופעל עבור אירועים שלא עוברים את המסנן, מה שהופך את קוד ה-listening ליעיל יותר וקל יותר להבנה. אין צורך להפעיל service worker כדי לטפל באירועים שלא רלוונטיים לו.

המסננים נועדו לאפשר מעבר מקוד סינון ידני כמו זה:

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

לזה:

chrome.webNavigation.onCommitted.addListener(function(e) {
  // ...
}, {url: [{hostSuffix: 'google.com'},
          {hostSuffix: 'google.com.au'}]});

אירועים תומכים במסננים ספציפיים שרלוונטיים לאירוע. רשימת המסננים שאירוע תומך בהם מופיעה במסמכי התיעוד של האירוע בקטע filters (מסננים).

כשמתאימים כתובות URL (כמו בדוגמה שלמעלה), מסנני אירועים תומכים באותן יכולות של התאמת כתובות URL שאפשר להגדיר באמצעות events.UrlFilter, למעט התאמה של סכימה ויציאה.