browser.events

תיאור

מרחב השמות chrome.events מכיל סוגים נפוצים שמשמשים ממשקי API ששולחים אירועים כדי להודיע לכם כשמשהו מעניין קורה.

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

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 פועלים כך.

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

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

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

כללים

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

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 חייב להכיל מזהה ייחודי שלא נמצא בשימוש בכלל אחר, או מזהה ריק.

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

הסרת כללים

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

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

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

אחזור כללים

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

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

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

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

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

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

סוגים

Event

אובייקט שמאפשר להוסיף ולהסיר פונקציות event listener לאירוע ב-Chrome.

מאפיינים

• addListener

  void

  רושמת קריאה חוזרת (callback) של רכיב event listener לאירוע.

  הפונקציה addListener נראית כך:

  (callback: H) => {...}

  • callback

    H

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

• addRules

  void

  רושם כללים לטיפול באירועים.

  הפונקציה addRules נראית כך:

  (rules: Rule<anyany>[], callback?: function) => {...}

  • כללים

    Rule<anyany>[]‎

    כללים לרישום. הכללים האלה לא מחליפים כללים שנרשמו בעבר.

  • callback

    function optional

    הפרמטר callback נראה כך:

    (rules: Rule<anyany>[]) => void

    • כללים

      Rule<anyany>[]‎

      כללים שנרשמו, הפרמטרים האופציונליים מלאים בערכים.

• getRules

  void

  הפונקציה מחזירה את הכללים שרשומים כרגע.

  הפונקציה getRules נראית כך:

  (ruleIdentifiers?: string[], callback: function) => {...}

  • ruleIdentifiers

    string[] אופציונלי

    אם מועבר מערך, מוחזרים רק כללים עם מזהים שכלולים במערך הזה.

  • callback

    פונקציה

    הפרמטר callback נראה כך:

    (rules: Rule<anyany>[]) => void

    • כללים

      Rule<anyany>[]‎

      כללים שנרשמו, הפרמטרים האופציונליים מלאים בערכים.

• hasListener

  void

  הפונקציה hasListener נראית כך:

  (callback: H) => {...}

  • callback

    H

    ה-listener שסטטוס הרישום שלו ייבדק.

  • החזרות

    בוליאני

    הערך True אם callback רשום לאירוע.

• hasListeners

  void

  הפונקציה hasListeners נראית כך:

  () => {...}

  • החזרות

    בוליאני

    הערך True אם רכיבי event listener כלשהם רשומים לאירוע.

• removeListener

  void

  מבטלת את הרישום של קריאה חוזרת (callback) של רכיב event listener מאירוע.

  הפונקציה removeListener נראית כך:

  (callback: H) => {...}

  • callback

    H

    ה-listener שצריך לבטל את הרישום שלו.

• removeRules

  void

  ביטול הרישום של כללים שרשומים כרגע.

  הפונקציה removeRules נראית כך:

  (ruleIdentifiers?: string[], callback?: function) => {...}

  • ruleIdentifiers

    string[] אופציונלי

    אם מועבר מערך, רק כללים עם מזהים שכלולים במערך הזה לא רשומים.

  • callback

    function optional

    הפרמטר callback נראה כך:

    () => void

Rule

תיאור של כלל הצהרתי לטיפול באירועים.

מאפיינים

• פעולות

  any[]‎

  רשימת הפעולות שמופעלות אם אחד מהתנאים מתקיים.

• מצבים רפואיים

  any[]‎

  רשימת תנאים שיכולים להפעיל את הפעולות.

• id [מזהה]

  מחרוזת אופציונלי

  מזהה אופציונלי שמאפשר להפנות לכלל הזה.

• הקמפיין

  מספר אופציונלי

  עדיפות אופציונלית של הכלל הזה. ברירת המחדל היא 100.

• tags

  string[] אופציונלי

  אפשר להשתמש בתגים כדי להוסיף הערות לכללים ולבצע פעולות בקבוצות של כללים.

UrlFilter

מסנן כתובות URL לפי קריטריונים שונים. מידע נוסף על סינון אירועים כל הקריטריונים הם תלויי אותיות רישיות.

מאפיינים

• cidrBlocks

  string[] אופציונלי

  ‫Chrome 123 ואילך ‫browser.* ‎ החל מ-Chrome 148

  יש התאמה אם החלק של המארח בכתובת ה-URL הוא כתובת IP והוא כלול באחד מבלוקי ה-CIDR שצוינו במערך.

• hostContains

  מחרוזת אופציונלי

  התאמה אם שם המארח של כתובת ה-URL מכיל מחרוזת מסוימת. כדי לבדוק אם לרכיב של שם מארח יש את הקידומת "foo", משתמשים ב-hostContains: '.foo'. הערך הזה תואם ל-"www.foobar.com" ול-"foo.com", כי נקודה מתווספת באופן משתמע בתחילת שם המארח. באופן דומה, אפשר להשתמש ב-hostContains כדי להתאים לסיומת של רכיב ('foo.') ולהתאים באופן מדויק לרכיבים ('.foo.'). צריך לבצע התאמה מדויקת והתאמה לסיומת של הרכיבים האחרונים בנפרד באמצעות hostSuffix, כי לא מתווספת נקודה משתמעת בסוף שם המארח.

• hostEquals

  מחרוזת אופציונלי

  התאמה אם שם המארח של כתובת ה-URL שווה למחרוזת שצוינה.

• hostPrefix

  מחרוזת אופציונלי

  התאמה אם שם המארח של כתובת ה-URL מתחיל במחרוזת שצוינה.

• hostSuffix

  מחרוזת אופציונלי

  התאמה אם שם המארח של כתובת ה-URL מסתיים במחרוזת שצוינה.

• originAndPathMatches

  מחרוזת אופציונלי

  התאמה אם כתובת ה-URL ללא קטע השאילתה ומזהה המקטע תואמת לביטוי רגולרי שצוין. מספרי היציאות יוסרו מכתובת ה-URL אם הם תואמים למספר היציאה שמוגדר כברירת מחדל. הביטויים הרגולריים משתמשים בתחביר RE2.

• pathContains

  מחרוזת אופציונלי

  התאמה אם קטע הנתיב של כתובת ה-URL מכיל מחרוזת מסוימת.

• pathEquals

  מחרוזת אופציונלי

  התאמה אם קטע הנתיב של כתובת ה-URL שווה למחרוזת שצוינה.

• pathPrefix

  מחרוזת אופציונלי

  התאמה אם קטע הנתיב של כתובת ה-URL מתחיל במחרוזת שצוינה.

• pathSuffix

  מחרוזת אופציונלי

  התאמה אם קטע הנתיב של כתובת ה-URL מסתיים במחרוזת שצוינה.

• ports

  (number | number[])[] אופציונלי

  התאמה אם היציאה של כתובת ה-URL כלולה באחת מרשימות היציאות שצוינו. לדוגמה, [80, 443, [1000, 1200]] תואם לכל הבקשות ביציאות 80,‏ 443 ובטווח 1000-1200.

• queryContains

  מחרוזת אופציונלי

  התאמה אם פלח השאילתה של כתובת ה-URL מכיל מחרוזת מסוימת.

• queryEquals

  מחרוזת אופציונלי

  התאמה אם פלח השאילתה של כתובת ה-URL שווה למחרוזת שצוינה.

• queryPrefix

  מחרוזת אופציונלי

  התאמה אם פלח השאילתה של כתובת ה-URL מתחיל במחרוזת שצוינה.

• querySuffix

  מחרוזת אופציונלי

  התאמה אם פלח השאילתה של כתובת ה-URL מסתיים במחרוזת שצוינה.

• סכמות

  string[] אופציונלי

  התאמה אם הסכימה של כתובת ה-URL שווה לאחת מהסכימות שצוינו במערך.

• urlContains

  מחרוזת אופציונלי

  התאמה אם כתובת ה-URL (ללא מזהה מקטע) מכילה מחרוזת מסוימת. מספרי היציאות יוסרו מכתובת ה-URL אם הם תואמים למספר היציאה שמוגדר כברירת מחדל.

• urlEquals

  מחרוזת אופציונלי

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

• urlMatches

  מחרוזת אופציונלי

  התאמה אם כתובת ה-URL (ללא מזהה מקטע) תואמת לביטוי רגולרי שצוין. מספרי היציאות יוסרו מכתובת ה-URL אם הם תואמים למספר היציאה שמוגדר כברירת מחדל. הביטויים הרגולריים משתמשים בתחביר RE2.

• urlPrefix

  מחרוזת אופציונלי

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

• urlSuffix

  מחרוזת אופציונלי

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