chrome.declarativeContent

תאריך הרענון: 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, ואחריו התנאים 'מכיל', 'שווה ל', 'מתחיל ב' או 'מסתיים ב'. בטבלה הבאה מופיעות כמה דוגמאות:

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

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

התאמה של שירות CSS

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

בוררים מורכבים (OK) בוררים מורכבים (לא תקינים)
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

    void

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

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

  • css

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

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

  • isBookmarked

    ‫boolean אופציונלי

    ‫Chrome 45 ואילך

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

  • pageUrl

    ‫UrlFilter אופציונלי

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

RequestContentScript

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

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

מאפיינים

  • constructor

    void

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

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

  • allFrames

    ‫boolean אופציונלי

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

  • css

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

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

  • js

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

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

  • matchAboutBlank

    ‫boolean אופציונלי

    האם להוסיף את סקריפט התוכן ב-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 optional

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

ShowAction

‫Chrome 97 ואילך

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

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

מאפיינים

ShowPageAction

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

במקומה יש להשתמש בdeclarativeContent.ShowAction.

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

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

מאפיינים

אירועים

onPageChanged

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

תנאים

PageStateMatcher

פעולות

RequestContentScript

SetIcon

ShowPageAction

ShowAction