chrome.events

תיאור

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

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

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

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

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

דוגמאות לממשקי API באמצעות אירועים: התראות, i18n, זהות, זמן ריצה. רוב Chrome ממשקי API כן.

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

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

משתמשים בגורמים הצהרתיים לטיפול באירועים, לדוגמה, Declarative Content API בדף הזה מתוארים המושגים הבסיסיים של כל האירועים המוצהרים של ה-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 חייב להכיל ערך ייחודי של שלא נמצא בשימוש בכלל אחר או במזהה ריק.

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

הסרת כללים

כדי להסיר כללים, צריך להפעיל את הפונקציה 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 = {...};
chrome.declarativeWebRequest.onRequest.addRules([rule1]);
chrome.declarativeWebRequest.onRequest.addRules([rule2]);

העדפה

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

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

במקום

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

העדפה

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

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

במקום

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

העדפה

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

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

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

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

במקום

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

העדפה

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

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

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

סוגים

Event

אובייקט שמאפשר להוסיף ולהסיר מאזינים לאירוע ב-Chrome.

מאפיינים

• addListener

  ריק

  רושם callback של event listener לאירוע.

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

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

  • קריאה חוזרת (callback)

    H

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

• addRules

  ריק

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

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

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

  • כללים

    כלל<anyany>[]

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

  • קריאה חוזרת (callback)

    פונקציה אופציונלית

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

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

    • כללים

      כלל<anyany>[]

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

• getRules

  ריק

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

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

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

  • ruleIdentifiers

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

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

  • קריאה חוזרת (callback)

    פונקציה

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

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

    • כללים

      כלל<anyany>[]

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

• hasListener

  ריק

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

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

  • קריאה חוזרת (callback)

    H

    המאזינים שסטטוס הרישום שלו ייבדק.

  • החזרות

    בוליאני

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

• hasListeners

  ריק

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

  () => {...}

  • החזרות

    בוליאני

    הערך הוא True אם יש פונקציות event listener רשומים לאירוע.

• removeListener

  ריק

  ביטול ההרשמה של קריאה חוזרת לאירוע של האזנה לאירוע.

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

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

  • קריאה חוזרת (callback)

    H

    מאזינים שהרישום שלהם יבוטל.

• removeRules

  ריק

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

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

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

  • ruleIdentifiers

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

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

  • קריאה חוזרת (callback)

    פונקציה אופציונלית

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

    () => void

Rule

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

מאפיינים

• פעולות

  כל[]

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

• תנאים

  כל[]

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

• id [מזהה]

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

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

• הקמפיין

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

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

• תגים

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

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

UrlFilter

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

מאפיינים

• cidrBlocks

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

  Chrome 123 ואילך

  תואם אם החלק המארח של כתובת ה-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

  (מספר | מספר[])[] אופציונלי

  תואם אם היציאה של כתובת ה-URL כלולה באחת מרשימות היציאות שצוינו. לדוגמה, [80, 443, [1000, 1200]] תואם לכל הבקשות ביציאה 80, 443 ובטווח 1,000-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 אם הם תואמים למספר היציאה שמוגדר כברירת מחדל.