chrome.events

תיאור

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 באמצעות אירועים: התראות, i18n, זהות, זמן ריצה. רוב Chrome ממשקי API כן.

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

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

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

כללים

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

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

עדיף:

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

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

במקום:

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

העדפה:

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

עדיף:

  var rule = { conditions: [condition1, condition2],
                actions: [new chrome.declarativeWebRequest.CancelRequest()]};
  chrome.declarativeWebRequest.onRequest.addRules([rule]);

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

אירועים מסוננים הם מנגנון שמאפשר למאזינים לציין קבוצת משנה של אירועים שבהם אתם מעוניינים. האזנה שעושה שימוש במסנן לא תופעל לאירועים שלא עוברים את שהופך את קוד ההאזנה להצהרתי ויעיל יותר. צריכים של 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'}]});

אירועים תומכים במסננים ספציפיים שיש להם משמעות לאותו אירוע. רשימת המסננים שאירוע יופיעו במסמכי התיעוד של האירוע ב'מסננים'. .

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