דף זה תורגם על ידי Cloud Translation API.

chrome.declarativeContent

תיאור

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

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

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

סוגים

ImageDataType

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

סוג

ImageData

PageStateMatcher

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

מאפיינים

constructor

void

הפונקציה constructor נראית כך:
```
(arg: PageStateMatcher) => {...}
```
- arg
  
  PageStateMatcher
- החזרות
  PageStateMatcher
css

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

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

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

גרסה 45 ואילך של Chrome

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

UrlFilter אופציונלי

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

RequestContentScript

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

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

מאפיינים

constructor

void

הפונקציה constructor נראית כך:
```
(arg: RequestContentScript) => {...}
```
- arg
  
  RequestContentScript
- החזרות
  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) => {...}
```
- arg
  
  SetIcon
- החזרות
  SetIcon
imageData

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

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

ShowAction

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

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

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

מאפיינים

constructor

void

הפונקציה constructor נראית כך:
```
(arg: ShowAction) => {...}
```
- arg
  
  ShowAction
- החזרות
  ShowAction

ShowPageAction

הופסקה השימוש בהם בגרסה 97 של Chrome

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

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

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

מאפיינים

constructor

void

הפונקציה constructor נראית כך:
```
(arg: ShowPageAction) => {...}
```
- arg
  
  ShowPageAction
- החזרות
  ShowPageAction

אירועים

onPageChanged

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

תנאים

PageStateMatcher

פעולות