browser.events

תיאור

מושגים ושימוש

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

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

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

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

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

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

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

כללים

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

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

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

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

const 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() של אובייקט האירוע. הפרמטר הראשון שלה הוא מערך של מופעי כללים, והפרמטר השני הוא פונקציית קריאה חוזרת שמופעלת בסיום.

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

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

הסרת כללים

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

const rule_ids = ["id1", "id2", ...];
removeRules(rule_ids, () => {...});

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

אחזור כללים

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

const rule_ids = ["id1", "id2", ...];
getRules(rule_ids, (details) => {...});

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

ביצועים

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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