תיאור
צריך להשתמש ב-API chrome.contentSettings
כדי לשנות הגדרות שקובעות אם אתרים יכולים להשתמש בתכונות כמו קובצי cookie, JavaScript ויישומי פלאגין. באופן כללי, הגדרות התוכן מאפשרות להתאים אישית את התנהגות Chrome על בסיס אתר מסוים במקום על בסיס גלובלי.
הרשאות
contentSettings
כדי להשתמש ב-API, צריך להצהיר על ההרשאה "contentSettings"
במניפסט של התוסף. לדוגמה:
{
"name": "My extension",
...
"permissions": [
"contentSettings"
],
...
}
מושגים ושימוש
דפוסים של הגדרות תוכן
תוכלו להשתמש בתבניות כדי לציין את האתרים שאליהם משפיעה כל הגדרת תוכן. לדוגמה,
https://*.youtube.com/*
מציין את youtube.com ואת כל תתי-הדומיין שלו. התחביר של תוכן
הגדרת דפוסים זהה לדפוסי התאמה, למעט כמה הבדלים:
- בכתובות URL מסוג
http
,https
ו-ftp
, הנתיב חייב להיות תו כללי לחיפוש (/*
). עבורfile
כתובות URL, הנתיב יש לציין באופן מלא ולא לכלול תווים כלליים לחיפוש. - בניגוד להתאמה לתבניות, התבניות של הגדרות התוכן יכולות לציין מספר יציאה. אם יציאה מספר צוין, הדפוס תואם רק לאתרים עם אותה יציאה. אם לא צוין מספר יציאה שצוין, הדפוס תואם לכל היציאות.
קדימות של תבניות
כאשר יותר מכלל אחד של הגדרת תוכן חל על אתר נתון, הכלל עם הכלל הספציפי יותר הדפוס מקבל עדיפות.
לדוגמה, התבניות הבאות מסודרות לפי קדימות:
https://www.example.com/*
https://*.example.com/*
(תואם ל-example.com ולכל תתי-הדומיין)<all_urls>
(תואם לכל כתובת URL)
שלושה סוגים של תווים כלליים לחיפוש משפיעים על מידת הספציפיות של הדפוס:
- תווים כלליים לחיפוש ביציאה (לדוגמה
https://www.example.com:*/*
) - תווים כלליים לחיפוש בסכימה (לדוגמה
*://www.example.com:123/*
) - תווים כלליים לחיפוש בשם המארח (לדוגמה
https://*.example.com:123/*
)
אם דפוס הוא ספציפי יותר מדפוס אחר בחלק מסוים אבל פחות ספציפי בחלק אחר, החלקים השונים נבדקים בסדר הבא: שם מארח, סכמה, יציאה. לדוגמה, הדפוסים הבאים מסודרים לפי קדימות:
https://www.example.com:*/*
מציינת את שם המארח והסכימה.*:/www.example.com:123/*
לא גבוה כל כך, כי למרות שהוא מציין את שם המארח, הוא לא מציין את הסכמה.https://*.example.com:123/*
נמוכה יותר כי למרות שהיא מציינת את היציאה והסכמה, יש לה תו כללי לחיפוש בשם המארח.
דפוסים ראשיים ומשניים
כתובת ה-URL שלפיהם אנחנו מחליטים איזו הגדרת תוכן להחיל תלויה בסוג התוכן.
לדוגמה, עבור contentSettings.notifications
ההגדרות מבוססות על כתובת ה-URL שמוצגת
סרגל הכתובות. כתובת ה-URL הזו נקראת 'ראשית' כתובת URL.
בסוגי תוכן מסוימים אפשר להביא בחשבון כתובות URL נוספות. לדוגמה, אם לאתר מותר
מגדירים את הפרמטר contentSettings.cookies
על סמך כתובת ה-URL של בקשת ה-HTTP (
כתובת ה-URL הראשית במקרה הזה), וגם כתובת ה-URL שמוצגת בסרגל הכתובות (שנקראת כתובת ה-URL המשנית
כתובת URL).
אם למספר כללים יש דפוסים ראשיים ומשניים, הכלל עם הכלל הראשי הספציפי יותר הדפוס מקבל עדיפות. אם יש מספר כללים עם אותו דפוס ראשי, הכלל עם אותו דפוס ראשי תבנית משנית ספציפית יותר מקבלת עדיפות. לדוגמה, הרשימה הבאה של צמדים של תבניות ראשיות/משניות מסודרים לפי קדימות:
קדימות | דפוס ראשי | דפוס משני |
---|---|---|
1 | https://www.moose.com/* , | https://www.wombat.com/* |
2 | https://www.moose.com/* , | <all_urls> |
3 | <all_urls> , | https://www.wombat.com/* |
4 | <all_urls> , | <all_urls> |
מזהי המשאבים
מזהי משאבים מאפשרים לקבוע הגדרות תוכן לסוגי משנה ספציפיים של סוג תוכן.
בשלב הזה, סוג התוכן היחיד שתומך במזהי משאבים הוא contentSettings.plugins
,
כאשר מזהה משאב מזהה פלאגין ספציפי. כשמחילים הגדרות תוכן, תחילה
ההגדרות של הפלאגין הספציפי מסומנות. אם לא נמצאו הגדרות עבור
של יישומי פלאגין, הגדרות התוכן הכלליות עבור יישומי פלאגין נבדקות.
לדוגמה, אם כלל של הגדרת תוכן כולל את מזהה המשאב adobe-flash-player
וגם את המזהה
דפוס <all_urls>
, הוא מקבל עדיפות על פני כלל ללא מזהה משאב וללא הדפוס
https://www.example.com/*
, גם אם הדפוס הזה ספציפי יותר.
אפשר לקבל רשימה של מזהי משאבים לסוג תוכן כלשהו באמצעות קריאה
contentSettings.ContentSetting.getResourceIdentifiers()
. הרשימה שמוחזרת יכולה להשתנות עם:
קבוצת יישומי הפלאגין המותקנים במחשב של המשתמש, אך Chrome מנסה לשמור על יציבות המזהים
בכל עדכוני יישומי הפלאגין.
דוגמאות
כדי לנסות את ה-API הזה, צריך להתקין את הדוגמה של ContentSettings API מchrome-extension-samples. של מאגר הנתונים.
סוגים
AutoVerifyContentSetting
Enum
"allow"
"block"
CameraContentSetting
Enum
"allow"
"block"
"ask"
ClipboardContentSetting
Enum
"allow"
"block"
"ask"
ContentSetting
מאפיינים
-
נקה
ריק
הבטחהניקוי כל הכללים של הגדרות התוכן שהוגדרו על ידי התוסף הזה.
הפונקציה
clear
נראית כך:(details: object, callback?: function) => {...}
-
פרטים
אובייקט
-
היקף
היקף אופציונלי
היכן לנקות את ההגדרה (ברירת מחדל: רגילה).
-
-
קריאה חוזרת (callback)
פונקציה אופציונלית
הפרמטר
callback
נראה כך:() => void
-
החזרות
הבטחה<Empty>
Chrome מגרסה 96 ואילךהבטחות נתמכות במניפסט מגרסה V3 ואילך, אבל ניתנות קריאות חוזרות (callback) בשביל תאימות לאחור. לא ניתן להשתמש בשתיהן באותה בקשה להפעלת פונקציה. ההבטחה הזו מצליחה לפתור את הבעיה באותו סוג שמועבר לקריאה החוזרת.
-
-
get
ריק
הבטחההפונקציה מקבלת את הגדרת התוכן הנוכחית עבור זוג נתון של כתובות URL.
הפונקציה
get
נראית כך:(details: object, callback?: function) => {...}
-
פרטים
אובייקט
-
גלישה פרטית
ערך בוליאני אופציונלי
הגדרה שקובעת אם לבדוק את הגדרות התוכן לסשן פרטי. (ברירת המחדל היא False)
-
primaryUrl
מחרוזת
כתובת ה-URL הראשית שעבורה יש לאחזר את הגדרת התוכן. לתשומת ליבכם: המשמעות של כתובת ה-URL הראשית תלויה בסוג התוכן.
-
resourceIdentifier
ResourceIdentifier אופציונלי
מזהה ספציפי יותר של סוג התוכן שעבורו צריך לאחזר את ההגדרות.
-
secondaryUrl
מחרוזת אופציונלי
כתובת ה-URL המשנית שעבורה יש לאחזר את הגדרת התוכן. ברירת המחדל היא כתובת ה-URL הראשית. חשוב לשים לב שהמשמעות של כתובת URL משנית תלויה בסוג התוכן, ולא כל סוגי התוכן משתמשים בכתובות URL משניות.
-
-
קריאה חוזרת (callback)
פונקציה אופציונלית
הפרמטר
callback
נראה כך:(details: object) => void
-
פרטים
אובייקט
-
הגדרה
T
הגדרת התוכן. ניתן לעיין בתיאור של האובייקטים הנפרדים ContentSetting כדי לראות את הערכים האפשריים.
-
-
-
החזרות
Promise<object>
Chrome מגרסה 96 ואילךהבטחות נתמכות במניפסט מגרסה V3 ואילך, אבל ניתנות קריאות חוזרות (callback) בשביל תאימות לאחור. לא ניתן להשתמש בשתיהן באותה בקשה להפעלת פונקציה. ההבטחה הזו מצליחה לפתור את הבעיה באותו סוג שמועבר לקריאה החוזרת.
-
-
getResourceIdentifiers
ריק
הבטחההפונקציה
getResourceIdentifiers
נראית כך:(callback?: function) => {...}
-
קריאה חוזרת (callback)
פונקציה אופציונלית
הפרמטר
callback
נראה כך:(resourceIdentifiers?: ResourceIdentifier[]) => void
-
resourceIdentifiers
ResourceIdentifier[] אופציונלי
רשימה של מזהי משאבים לסוג התוכן הזה, או
undefined
אם סוג התוכן הזה לא משתמש במזהי משאבים.
-
-
החזרות
Promise<ResourceIdentifier[]>
Chrome מגרסה 96 ואילךהבטחות נתמכות במניפסט מגרסה V3 ואילך, אבל ניתנות קריאות חוזרות (callback) בשביל תאימות לאחור. לא ניתן להשתמש בשתיהן באותה בקשה להפעלת פונקציה. ההבטחה הזו מצליחה לפתור את הבעיה באותו סוג שמועבר לקריאה החוזרת.
-
-
הוגדר
ריק
הבטחההחלת כלל חדש של הגדרת תוכן.
הפונקציה
set
נראית כך:(details: object, callback?: function) => {...}
-
פרטים
אובייקט
-
primaryPattern
מחרוזת
הדפוס של כתובת ה-URL הראשית. לפרטים על הפורמט של תבנית, אפשר לעיין במאמר תבניות של הגדרות תוכן.
-
resourceIdentifier
ResourceIdentifier אופציונלי
מזהה המשאב של סוג התוכן.
-
היקף
היקף אופציונלי
היכן להגדיר את ההגדרה (ברירת מחדל: רגילה).
-
secondaryPattern
מחרוזת אופציונלי
הדפוס של כתובת ה-URL המשנית. ברירת המחדל היא 'התאמה לכל כתובות ה-URL'. לפרטים על הפורמט של תבנית, אפשר לעיין במאמר תבניות של הגדרות תוכן.
-
הגדרה
כל
ההגדרה שהוחלה על ידי הכלל הזה. ניתן לעיין בתיאור של האובייקטים הנפרדים ContentSetting כדי לראות את הערכים האפשריים.
-
-
קריאה חוזרת (callback)
פונקציה אופציונלית
הפרמטר
callback
נראה כך:() => void
-
החזרות
הבטחה<Empty>
Chrome מגרסה 96 ואילךהבטחות נתמכות במניפסט מגרסה V3 ואילך, אבל ניתנות קריאות חוזרות (callback) בשביל תאימות לאחור. לא ניתן להשתמש בשתיהן באותה בקשה להפעלת פונקציה. ההבטחה הזו מצליחה לפתור את הבעיה באותו סוג שמועבר לקריאה החוזרת.
-
CookiesContentSetting
Enum
"allow"
"block"
"session_only"
FullscreenContentSetting
ערך
"allow"
ImagesContentSetting
Enum
"allow"
"block"
JavascriptContentSetting
Enum
"allow"
"block"
LocationContentSetting
Enum
"allow"
"block"
"ask"
MicrophoneContentSetting
Enum
"allow"
"block"
"ask"
MouselockContentSetting
ערך
"allow"
MultipleAutomaticDownloadsContentSetting
Enum
"allow"
"block"
"ask"
NotificationsContentSetting
Enum
"allow"
"block"
"ask"
PluginsContentSetting
ערך
"block"
PopupsContentSetting
Enum
"allow"
"block"
PpapiBrokerContentSetting
ערך
"block"
ResourceIdentifier
סוג התוכן היחיד שמשתמשים במזהי משאבים הוא contentSettings.plugins
. מידע נוסף זמין במאמר מזהי משאבים.
מאפיינים
-
תיאור
מחרוזת אופציונלי
תיאור קריא (לבני אדם) של המשאב.
-
id [מזהה]
מחרוזת
מזהה המשאב של סוג התוכן הנתון.
Scope
ההיקף של הגדרות התוכן. אחד מ-
regular
: הגדרה לפרופיל רגיל (עוברת בירושה לפרופיל הפרטי אם היא לא משתנה במקום אחר),
incognito\_session\_only
: הגדרה לפרופיל פרטי, שניתן להגדיר רק במהלך גלישה פרטית, ונמחקת בסיום הסשן הפרטי (מבטלת את ההגדרות הרגילות).
Enum
"רגיל"
"browsing_session_only"
מאפיינים
automaticDownloads
האם לאפשר לאתרים להוריד מספר קבצים באופן אוטומטי. אחד מ-
allow
: מתן הרשאה לאתרים להוריד מספר קבצים באופן אוטומטי,
block
: לא לאפשר לאתרים להוריד מספר קבצים באופן אוטומטי,
ask
: יש לשאול כשאתר רוצה להוריד קבצים באופן אוטומטי אחרי הקובץ הראשון.
ברירת המחדל היא ask
.
כתובת ה-URL הראשית היא כתובת ה-URL של המסגרת ברמה העליונה. כתובת ה-URL המשנית לא בשימוש.
autoVerify
האם להתיר לאתרים להשתמש ב-Private State Tokens API. אחד מ-
allow
: מתן הרשאה לאתרים להשתמש ב-Private State Tokens API,
block
: חסימת האפשרות של אתרים להשתמש ב-Private State Tokens API.
ברירת המחדל היא allow
.
כתובת ה-URL הראשית היא כתובת ה-URL של המסגרת ברמה העליונה. כתובת ה-URL המשנית לא בשימוש. הערה: בעת קריאה אל set()
, הדפוס הראשי חייב להיות .
סוג
camera
האם לאפשר לאתרים לגשת למצלמה. אחד מ-
allow
: אפשר לאתרים לגשת למצלמה,
block
: לא לאפשר לאתרים לגשת למצלמה,
ask
: תוצג שאלה כשאתר מבקש גישה למצלמה.
ברירת המחדל היא ask
.
כתובת ה-URL הראשית היא כתובת ה-URL של המסמך שביקש גישה למצלמה. כתובת ה-URL המשנית לא בשימוש.
הערה: הפרמטר 'allow' לא חוקית אם שתי הדפוסים הם ''.
סוג
clipboard
האם לאפשר לאתרים לגשת ללוח העריכה באמצעות יכולות מתקדמות של ה-API של הלוח האסינכרוני. 'מתקדם' היכולות כוללות כל דבר מלבד כתיבת פורמטים מובנים לאחר פעולת משתמש, כלומר היכולת לקרוא, לכתוב פורמטים מותאמים אישית ואת היכולת לכתוב ללא פעולת משתמש. אחד מ-
allow
: מתן הרשאה לאתרים להשתמש ביכולות מתקדמות ללוח העריכה,
block
: לא לאפשר לאתרים להשתמש ביכולות מתקדמות של לוח העריכה,
ask
: צריך לשאול אותי כשאתר רוצה להשתמש ביכולות מתקדמות ללוח העריכה.
ברירת המחדל היא ask
.
כתובת ה-URL הראשית היא כתובת ה-URL של המסמך שביקש גישה ללוח. כתובת ה-URL המשנית לא בשימוש.
סוג
cookies
האם לאפשר הגדרה של קובצי cookie ונתונים מקומיים אחרים על ידי אתרים. אחד מ-
allow
: קבלת קובצי Cookie,
block
: חסימת קובצי cookie,
session\_only
: קבלת קובצי Cookie רק בשביל הסשן הנוכחי.
ברירת המחדל היא allow
.
כתובת ה-URL הראשית היא כתובת ה-URL שמייצגת את מקור קובץ ה-cookie. כתובת ה-URL המשנית היא כתובת ה-URL של המסגרת ברמה העליונה.
סוג
fullscreen
הוצא משימוש. אין יותר השפעה. ההרשאה למסך מלא הוענקה עכשיו באופן אוטומטי לכל האתרים. הערך הוא תמיד allow
.
סוג
images
הגדרה שקובעת אם להציג תמונות. אחד מ-
allow
: הצגת תמונות,
block
: אין להציג תמונות.
ברירת המחדל היא allow
.
כתובת ה-URL הראשית היא כתובת ה-URL של המסגרת ברמה העליונה. כתובת ה-URL המשנית היא כתובת ה-URL של התמונה.
סוג
javascript
האם להריץ JavaScript. אחד מ-
allow
: הרצת JavaScript,
block
: לא להפעיל JavaScript.
ברירת המחדל היא allow
.
כתובת ה-URL הראשית היא כתובת ה-URL של המסגרת ברמה העליונה. כתובת ה-URL המשנית לא בשימוש.
סוג
location
האם לאפשר מיקום גיאוגרפי. אחד מ-
allow
: אפשר לאתרים לעקוב אחר המיקום הפיזי שלך,
block
: לא לאפשר לאתרים לעקוב אחר המיקום הפיזי שלך
ask
: יש לשאול לפני שמאפשרים לאתרים לעקוב אחר המיקום הפיזי שלך.
ברירת המחדל היא ask
.
כתובת ה-URL הראשית היא כתובת ה-URL של המסמך שביקש נתוני מיקום. כתובת ה-URL המשנית היא כתובת ה-URL של המסגרת ברמה העליונה (שיכולה להיות שונה מכתובת ה-URL שמבקשת אותה).
סוג
microphone
האם לאפשר לאתרים לגשת למיקרופון. אחד מ-
allow
: אפשר לאתרים לגשת למיקרופון,
block
: לא לאפשר לאתרים לגשת למיקרופון,
ask
: יש לשאול כשאתר מבקש גישה למיקרופון.
ברירת המחדל היא ask
.
כתובת ה-URL הראשית היא כתובת ה-URL של המסמך שביקש גישה למיקרופון. כתובת ה-URL המשנית לא בשימוש.
הערה: הפרמטר 'allow' לא חוקית אם שתי הדפוסים הם ''.
סוג
mouselock
הוצא משימוש. אין יותר השפעה. ההרשאה לנעילת העכבר הוענקה עכשיו באופן אוטומטי לכל האתרים. הערך הוא תמיד allow
.
סוג
notifications
האם לאפשר לאתרים להציג התראות בשולחן העבודה. אחד מ-
allow
: אפשר לאתרים להציג התראות בשולחן העבודה,
block
: לא לאפשר לאתרים להציג התראות בשולחן העבודה,
ask
: צריך לשאול כשאתר רוצה להציג התראות בשולחן העבודה.
ברירת המחדל היא ask
.
כתובת ה-URL הראשית היא כתובת ה-URL של המסמך שבו תוצג ההתראה. כתובת ה-URL המשנית לא בשימוש.
סוג
plugins
הוצא משימוש. התמיכה ב-Flash הוסרה ב-Chrome 88, ולכן להרשאה הזו אין יותר השפעה. הערך הוא תמיד block
. המערכת תתעלם משיחות אל set()
ואל clear()
.
סוג
popups
האם לאפשר לאתרים להציג חלונות קופצים. אחד מ-
allow
: אפשר לאתרים להציג חלונות קופצים,
block
: לא לאפשר לאתרים להציג חלונות קופצים.
ברירת המחדל היא block
.
כתובת ה-URL הראשית היא כתובת ה-URL של המסגרת ברמה העליונה. כתובת ה-URL המשנית לא בשימוש.
סוג
unsandboxedPlugins
הוצא משימוש. בעבר, נקבע אם לאפשר לאתרים להפעיל יישומי פלאגין ללא ארגז חול. עם זאת, לאחר הסרה של תהליך הברוקר של Flash ב-Chrome 88, להרשאה הזו כבר אין השפעה. הערך הוא תמיד block
. המערכת תתעלם משיחות אל set()
ואל clear()
.