chrome.declarativeContent

תיאור

אפשר להשתמש ב-API chrome.declarativeContent כדי לבצע פעולות בהתאם לתוכן בדף, בלי לבקש הרשאה לקרוא את תוכן הדף.

הרשאות

declarativeContent

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

ה-Delarative Content API מאפשר להפעיל את פעולת התוסף בהתאם לכתובת ה-URL של או אם סלקטור ב-CSS תואם לרכיב בדף, בלי שיהיה צורך להוסיף הרשאות מארח או להחדיר סקריפט תוכן.

להשתמש בהרשאה activeTab כדי לבצע אינטראקציה עם דף אחרי שהמשתמש לוחץ על פעולת התוסף.

כללים

כללים מורכבים מתנאים ומפעולות. אם אחד מהתנאים מתקיים, כל הפעולות בוצעה. הפעולות הן setIcon() ו-showAction().

הערך PageStateMatcher תואם לדפי אינטרנט, אך רק אם כולם מופיעים ברשימה בקריטריונים. היא יכולה להתאים לכתובת URL של דף או לבורר מורכב של css. או מצב הסימניות של הדף. הכלל הבא מפעיל פעולת התוסף בדפי Google כאשר קיים שדה סיסמה:

let rule1 = {
  conditions: [
    new chrome.declarativeContent.PageStateMatcher({
      pageUrl: { hostSuffix: '.google.com', schemes: ['https'] },
      css: ["input[type='password']"]
    })
  ],
  actions: [ new chrome.declarativeContent.ShowAction() ]
};

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

let rule2 = {
  conditions: [
    new chrome.declarativeContent.PageStateMatcher({
      pageUrl: { hostSuffix: '.google.com', schemes: ['https'] },
      css: ["input[type='password']"]
    }),
    new chrome.declarativeContent.PageStateMatcher({
      css: ["video"]
    })
  ],
  actions: [ new chrome.declarativeContent.ShowAction() ]
};

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

chrome.runtime.onInstalled.addListener(function(details) {
  chrome.declarativeContent.onPageChanged.removeRules(undefined, function() {
    chrome.declarativeContent.onPageChanged.addRules([rule2]);
  });
});

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

התאמה לכתובת URL של דף

הערך PageStateMatcher.pageurl תואם לעמידה בקריטריונים של כתובת ה-URL. הקריטריונים הנפוצים ביותר הם שרשור של מארח, נתיב או כתובת URL, ואחריו 'מכיל', 'שווה', 'קידומת' או סיומת. הטבלה הבאה כוללת כמה דוגמאות:

קריטריונים משחקים
{ hostSuffix: 'google.com' } כל כתובות ה-URL של Google
{ pathPrefix: '/docs/extensions' } כתובות URL של מסמכי תוסף
{ urlContains: 'developer.chrome.com' } כל כתובות ה-URL של מסמכי תיעוד למפתחים ב-Chrome

כל הקריטריונים הם תלויי אותיות רישיות. רשימה מלאה של הקריטריונים זמינה ב-UrlFilter.

התאמת CSS

PageStateMatcher.css התנאים חייבים להיות סלקטורים מורכבים, כלומר, אי אפשר לכלול שילובים כמו רווחים לבנים או ">" ב- הסלקטורים. כך Chrome יכול להתאים את הסלקטורים בצורה יעילה יותר.

בוררים מורכבים (אישור) בוררים מורכבים (לא תקין)
a div p
iframe.special[src^='http'] p>span.highlight
ns|* p + ol
#abcd:checked p::first-line

תנאי CSS מתאימים רק לרכיבים מוצגים: אם רכיב שתואם לסלקטור שלכם הוא display:none או אחד מרכיבי ההורה שלו הוא display:none, הוא לא גורם לתנאי להתאים לבחירה. רכיבים מסוג visibility:hidden, ממוקמים מחוץ למסך או מוסתרים על ידי אלמנטים אחרים עדיין יכולה להתאים לתנאי.

התאמה למצב הוספה לסימניות

התנאי PageStateMatcher.isBookmarked מאפשר התאמה של סימנייה של כתובת ה-URL הנוכחית בפרופיל המשתמש. כדי להשתמש בתנאי הזה, סימניות צריך להצהיר על הרשאה במניפסט התוסף.

סוגים

ImageDataType

פרטים נוספים זמינים בכתובת https://developer.mozilla.org/en-US/docs/Web/API/ImageData.

סוג

ImageData

PageStateMatcher

תואם למצב של דף אינטרנט על סמך קריטריונים שונים.

מאפיינים

  • constructor

    ריק

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

    (arg: PageStateMatcher) => {...}

  • css

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

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

  • isBookmarked

    ערך בוליאני אופציונלי

    Chrome 45+

    תואם אם מצב הדף עם הסימנייה שווה לערך שצוין. נדרשת הרשאת הסימניות.

  • pageUrl

    UrlFilter אופציונלי

    תואם אם מתקיימים התנאים של UrlFilter לגבי כתובת ה-URL ברמה העליונה של הדף.

RequestContentScript

פעולה הצהרתית באירוע שמחדירה סקריפט תוכן.

אזהרה: הפעולה הזו עדיין ניסיונית והיא לא נתמכת בגרסאות build יציבות של Chrome.

מאפיינים

  • constructor

    ריק

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

    (arg: RequestContentScript) => {...}

  • allFrames

    ערך בוליאני אופציונלי

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

  • css

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

    שמות של קובצי CSS להחדרה כחלק מסקריפט התוכן.

  • JavaScript

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

    שמות של קובצי JavaScript להחדרה כחלק מסקריפט התוכן.

  • matchAboutBlank

    ערך בוליאני אופציונלי

    הגדרה שקובעת אם להוסיף את סקריפט התוכן ב-about:blank וב-about:srcdoc. ברירת המחדל היא false.

SetIcon

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

יש לציין בדיוק אחד מתוך imageData או path. שניהם מילונים שממפים מספר פיקסלים לייצוג תמונה. הייצוג של התמונה ב-imageData הוא אובייקט ImageData. לדוגמה, מאלמנט canvas, ואילו ייצוג התמונה ב-path הוא הנתיב לקובץ תמונה ביחס למניפסט של התוסף. אם scale פיקסלים של המסך מתאימים לפיקסל שלא תלוי במכשיר, יוצג הסמל scale * n. אם קנה המידה הזה חסר, הגודל של תמונה אחרת ישתנה לגודל הנדרש.

מאפיינים

  • constructor

    ריק

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

    (arg: SetIcon) => {...}

  • imageData

    ImageData | אובייקט אופציונלי

    אובייקט ImageData או מילון {size -> ImageData} מייצג סמל להגדרה. אם הסמל מצוין כמילון, התמונה שבה נעשה שימוש תיבחר בהתאם לדחיסות הפיקסלים של המסך. אם מספר הפיקסלים של התמונה שמתאימים ליחידה אחת של שטח מסך שווה ל-scale, נבחרת תמונה בגודל scale * n, כאשר n מייצג את גודל הסמל בממשק המשתמש. צריך לציין לפחות תמונה אחת. חשוב לשים לב: details.imageData = foo שוות ערך לפונקציה details.imageData = {'16': foo}.

ShowAction

Chrome מגרסה 97 ואילך

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

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

מאפיינים

ShowPageAction

הוצא משימוש מאז Chrome 97

יש להשתמש ב-declarativeContent.ShowAction.

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

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

מאפיינים

אירועים

onPageChanged

מספקת את Declarative Event API שמכיל addRules, removeRules ו-getRules.

תנאים

PageStateMatcher

פעולות

RequestContentScript

SetIcon

ShowPageAction

ShowAction