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, זהות, זמן ריצה. רוב ממשקי ה-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() ופונקציית קריאה חוזרת.

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

  void

  רישום קריאה חוזרת של event listener לאירוע.

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

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

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

    H

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

• addRules

  void

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

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

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

  • כללים

    כלל<anyany>[]

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

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

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

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

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

    • כללים

      כלל<anyany>[]

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

• getRules

  void

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

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

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

  • ruleIdentifiers

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

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

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

    פונקציה

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

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

    • כללים

      כלל<anyany>[]

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

• hasListener

  void

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

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

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

    H

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

  • החזרות

    boolean

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

• hasListeners

  void

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

  ()=> {...}

  • החזרות

    boolean

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

• removeListener

  void

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

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

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

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

    H

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

• removeRules

  void

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

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

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

  • ruleIdentifiers

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

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

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

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

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

    ()=>void

Rule

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

תכונות

• פעולות

  כל[]

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

• conditions

  כל[]

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

• id

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

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

• הקמפיין

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

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

• תגים

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

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

UrlFilter

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

תכונות

• 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 ובטווח 1000-1200.

• queryContains

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

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

• queryEquals

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

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

• queryPrefix

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

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

• querySuffix

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

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

• schemes

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

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

• urlContains

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

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

• urlEquals

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

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

• urlMatches

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

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

• urlPrefix

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

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

• urlSuffix

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

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