תיאור
אפשר להשתמש ב-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
void
הפונקציה
constructor
נראית כך:(arg: PageStateMatcher) => {...}
-
arg
-
החזרות
-
-
css
string[] אופציונלי
התאמה אם כל סלקטורים ב-CSS במערך תואמים לרכיבים המוצגים במסגרת עם אותו מקור כמו המסגרת הראשית של הדף. כל הסלקטורים במערך הזה חייבים להיות בוררים מורכבים כדי לזרז את ההתאמה. הערה: פירוט של מאות סלקטורים ב-CSS או פירוט של סלקטורים ב-CSS שתואמים למאות פעמים בדף יכולים להאט את מהירות הטעינה של אתרים.
-
isBookmarked
בוליאני אופציונלי
Chrome 45 ואילךתואם אם מצב הדף עם הסימנייה שווה לערך שצוין. לשם כך יש צורך בהרשאת הסימניות.
-
pageUrl
UrlFilter אופציונלי
תואם אם מתקיימים התנאים של
UrlFilter
לכתובת ה-URL ברמה העליונה של הדף.
RequestContentScript
פעולת אירוע מוצהרת שמחדירה סקריפט תוכן.
אזהרה: הפעולה הזו עדיין ניסיונית ולא נתמכת בגרסאות build יציבות של 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) => {...}
-
arg
-
החזרות
-
-
imageData
ImageData | אובייקט אופציונלי
אובייקט
ImageData
או מילון {size -> ImageData} שמייצג את הסמל להגדרה. אם הסמל מצוין כמילון, התמונה שתשמש תיבחר בהתאם לדחיסות הפיקסלים של המסך. אם מספר הפיקסלים של התמונה שיכולים להתאים ליחידת שטח אחת הואscale
, נבחרה תמונה בגודלscale * n
, כאשר n הוא גודל הסמל בממשק המשתמש. יש לציין לפחות תמונה אחת. לתשומת ליבך,details.imageData = foo
שווה ערך ל-details.imageData = {'16': foo}
.
ShowAction
פעולה מוצהרת שמגדירה את פעולה בסרגל הכלים של התוסף למצב פעיל, כל עוד מתקיימים התנאים התואמים. אפשר להשתמש בפעולה הזו בלי הרשאות מארח. אם לתוסף יש את ההרשאה activeTab, לחיצה על פעולת הדף מעניקה גישה לכרטיסייה הפעילה.
בדפים שבהם התנאים לא מתקיימים, הפעולה בסרגל הכלים של התוסף תופיע בגווני אפור, ולחיצה עליה תפתח את תפריט ההקשר במקום להפעיל את הפעולה.
תכונות
-
Constructor
void
הפונקציה
constructor
נראית כך:(arg: ShowAction) => {...}
-
arg
-
החזרות
-
ShowPageAction
יש להשתמש ב-declarativeContent.ShowAction
.
פעולה מוצהרת שמגדירה את פעולת הדף של התוסף למצב פעיל, כל עוד מתקיימים התנאים התואמים. ניתן להשתמש בפעולה הזו ללא הרשאות מארח, אבל לתוסף חייבת להיות פעולה בדף. אם לתוסף יש את ההרשאה activeTab, לחיצה על פעולת הדף מעניקה גישה לכרטיסייה הפעילה.
בדפים שבהם התנאים לא מתקיימים, הפעולה בסרגל הכלים של התוסף תופיע בגווני אפור, ולחיצה עליה תפתח את תפריט ההקשר במקום להפעיל את הפעולה.
תכונות
-
Constructor
void
הפונקציה
constructor
נראית כך:(arg: ShowPageAction) => {...}
-
arg
-
החזרות
-
אירועים
onPageChanged
מספק את Declarative Event API שכולל את addRules
, removeRules
ו-getRules
.