chrome.declarativeContent

refresh date: 2026-09-25 robots: noindex

תיאור

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

הרשאות

declarativeContent

שימוש

Declarative 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, ואחריהם Contains,‏ Equals,‏ Prefix או Suffix. בטבלה הבאה מופיעות כמה דוגמאות:

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

סוגים

ImageDataType

מידע נוסף זמין בכתובת https://developer.mozilla.org/en-US/docs/Web/API/ImageData.

סוג

ImageData

PageStateMatcher

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

מאפיינים

  • constructor

    void

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

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

  • css

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

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

  • isBookmarked

    בוליאני אופציונלי

    ‫Chrome 45 ואילך

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

  • pageUrl

    ‫UrlFilter אופציונלי

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

RequestContentScript

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

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

מאפיינים

  • constructor

    void

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

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

  • allFrames

    בוליאני אופציונלי

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

  • css

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

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

  • js

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

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

  • matchAboutBlank

    בוליאני אופציונלי

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

SetIcon

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

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

מאפיינים

  • constructor

    void

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

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

  • imageData

    ‫ImageData | object אופציונלי

    אובייקט 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