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

chrome.contentSettings

תיאור

שימוש ב-chrome.contentSettings API כדי לשנות את ההגדרות ששולטות ביכולת של אתרים להשתמש בתכונות כמו קובצי cookie, ‏JavaScript ויישומי פלאגין. באופן כללי, הגדרות התוכן מאפשרות לכם להתאים אישית את התנהגות Chrome בכל אתר בנפרד, במקום באופן גלובלי.

הרשאות

contentSettings

כדי להשתמש ב-API, צריך להצהיר על ההרשאה "contentSettings" במניפסט של התוסף. לדוגמה:

{
  "name": "My extension",
  ...
  "permissions": [
    "contentSettings"
  ],
  ...
}

מושגים ושימוש

דפוסים של הגדרות תוכן

אתם יכולים להשתמש בדפוסים כדי לציין את האתרים שאליהם חלה כל הגדרת תוכן. לדוגמה, הערך https://*.youtube.com/* מציין את youtube.com ואת כל תת-הדומיינים שלו. התחביר של דפוסי הגדרת התוכן זהה לזה של דפוסי ההתאמה, עם כמה הבדלים:

בכתובות ה-URL מסוג http,‏ https ו-ftp, הנתיב חייב להיות תו כללי לחיפוש (/*). בכתובות ה-URL מסוג file, הנתיב חייב להיות מפורט במלואו ואסור שיכיל תווים כלליים לחיפוש.
בניגוד לתבניות התאמה, תבניות של הגדרות תוכן יכולות לציין מספר יציאה. אם מצוין מספר יציאה, הדפוס יתאים רק לאתרים עם אותה היציאה. אם לא מציינים מספר יציאה, הדפוס תואם לכל היציאות.

קדימות של דפוסים

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

לדוגמה, הדפוסים הבאים מסודרים לפי תעדוף:

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 'משנית').

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

קדימות	דפוס ראשי	דפוס משני
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/*, גם אם התבנית הזו ספציפית יותר.

כדי לקבל רשימה של מזהי משאבים לסוג תוכן מסוים, אפשר להפעיל את ה-method‏ contentSettings.ContentSetting.getResourceIdentifiers(). הרשימה שתוחזר עשויה להשתנות בהתאם לקבוצת הפלאגינים המותקנים במחשב של המשתמש, אבל Chrome מנסה לשמור על יציבות המזהים במהלך עדכוני הפלאגין.

דוגמאות

כדי לנסות את ה-API הזה, צריך להתקין את הדוגמה ל-contentSettings API מהמאגר chrome-extension-samples.

סוגים

AutoVerifyContentSetting

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

Enum

"allow"

"block"

CameraContentSetting

Chrome מגרסה 46 ואילך

Enum

"allow"

"block"

"ask"

ClipboardContentSetting

Chrome מגרסה 121 ואילך

Enum

"allow"

"block"

"ask"

ContentSetting

מאפיינים

נקה

void

Promise

מחיקת כל כללי הגדרת התוכן שהוגדרו על ידי התוסף הזה.

הפונקציה clear נראית כך:
```
(details: object, callback?: function) => {...}
```
- פרטים
  
  אובייקט
  - היקף
    
    היקף אופציונלי
    
    איפה לנקות את ההגדרה (ברירת המחדל: רגיל).
- קריאה חוזרת (callback)
  
  פונקציה אופציונלי
  
  הפרמטר callback נראה כך:
```
() => void
```
- החזרות
  Promise<void>
  
  גרסה 96 ואילך של Chrome
  
  יש תמיכה ב-Promises ב-Manifest V3 ואילך, אבל פונקציות קריאה חוזרת (callbacks) ניתנות לצורך תאימות לאחור. אי אפשר להשתמש בשניהם באותה קריאה לפונקציה. הפתרון של ההבטחה יהיה באותו סוג שהוענק ל-callback.
get

void

Promise

הפונקציה מקבלת את הגדרת התוכן הנוכחית של שתי כתובות URL נתונות.

הפונקציה get נראית כך:
```
(details: object, callback?: function) => {...}
```
- פרטים
  
  אובייקט
  - מצב פרטי
    
    בוליאני אופציונלי
    
    האם לבדוק את הגדרות התוכן בסשן פרטי. (ברירת המחדל היא false)
  - primaryUrl
    
    string
    
    כתובת ה-URL הראשית שאליה צריך לאחזר את הגדרת התוכן. חשוב לזכור שהמשמעות של כתובת URL ראשית תלויה בסוג התוכן.
  - resourceIdentifier
    
    ResourceIdentifier אופציונלי
    
    מזהה ספציפי יותר של סוג התוכן שעבורו צריך לאחזר את ההגדרות.
  - secondaryUrl
    
    מחרוזת אופציונלי
    
    כתובת ה-URL המשנית שלגביה צריך לאחזר את הגדרת התוכן. ברירת המחדל היא כתובת ה-URL הראשית. חשוב לזכור שהמשמעות של כתובת URL משנית תלויה בסוג התוכן, ולא בכל סוגי התוכן נעשה שימוש בכתובות URL משניות.
- קריאה חוזרת (callback)
  
  פונקציה אופציונלי
  
  הפרמטר callback נראה כך:
```
(details: object) => void
```
  - פרטים
    
    אובייקט
    
    הגדרה
    
    T
    
    הגדרת התוכן. הערכים האפשריים מפורטים בתיאור של אובייקטי ContentSetting השונים.
- החזרות
  Promise<object>
  
  גרסה 96 ואילך של Chrome
  
  יש תמיכה ב-Promises ב-Manifest V3 ואילך, אבל פונקציות קריאה חוזרת (callbacks) ניתנות לצורך תאימות לאחור. אי אפשר להשתמש בשניהם באותה קריאה לפונקציה. הפתרון של ההבטחה יהיה באותו סוג שהוענק ל-callback.
getResourceIdentifiers

void

Promise

הפונקציה getResourceIdentifiers נראית כך:
```
(callback?: function) => {...}
```
- קריאה חוזרת (callback)
  
  פונקציה אופציונלי
  
  הפרמטר callback נראה כך:
```
(resourceIdentifiers?: ResourceIdentifier[]) => void
```
  - resourceIdentifiers
    
    ResourceIdentifier[] אופציונלי
    
    רשימה של מזהי משאבים לסוג התוכן הזה, או undefined אם בסוג התוכן הזה לא נעשה שימוש במזהי משאבים.
- החזרות
  Promise<ResourceIdentifier[]>
  
  גרסה 96 ואילך של Chrome
  
  יש תמיכה ב-Promises ב-Manifest V3 ואילך, אבל פונקציות קריאה חוזרת (callbacks) ניתנות לצורך תאימות לאחור. אי אפשר להשתמש בשניהם באותה קריאה לפונקציה. הפתרון של ההבטחה יהיה באותו סוג שהוענק ל-callback.
הוגדר

void

Promise

החלת כלל חדש להגדרת תוכן.

הפונקציה set נראית כך:
```
(details: object, callback?: function) => {...}
```
- פרטים
  
  אובייקט
  - primaryPattern
    
    string
    
    התבנית של כתובת ה-URL הראשית. פרטים על הפורמט של תבנית מופיעים במאמר תבניות של הגדרות תוכן.
  - resourceIdentifier
    
    ResourceIdentifier אופציונלי
    
    מזהה המשאב של סוג התוכן.
  - היקף
    
    היקף אופציונלי
    
    המיקום שבו מגדירים את ההגדרה (ברירת המחדל: רגיל).
  - secondaryPattern
    
    מחרוזת אופציונלי
    
    התבנית של כתובת ה-URL המשנית. ברירת המחדל היא התאמה לכל כתובות ה-URL. פרטים על הפורמט של התבנית מופיעים בקטע תבניות של הגדרות תוכן.
  - הגדרה
    
    כל
    
    ההגדרה שחלה על הכלל הזה. הערכים האפשריים מפורטים בתיאור של אובייקטי ContentSetting השונים.
- קריאה חוזרת (callback)
  
  פונקציה אופציונלי
  
  הפרמטר callback נראה כך:
```
() => void
```
- החזרות
  Promise<void>
  
  גרסה 96 ואילך של Chrome
  
  יש תמיכה ב-Promises ב-Manifest V3 ואילך, אבל פונקציות קריאה חוזרת (callbacks) ניתנות לצורך תאימות לאחור. אי אפשר להשתמש בשניהם באותה קריאה לפונקציה. הפתרון של ההבטחה יהיה באותו סוג שהוענק ל-callback.

CookiesContentSetting

Chrome מגרסה 44 ואילך

Enum

"allow"

"block"

"session_only"

FullscreenContentSetting

Chrome מגרסה 44 ואילך

ערך

"allow"

ImagesContentSetting

Chrome מגרסה 44 ואילך

Enum

"allow"

"block"

JavascriptContentSetting

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

Enum

"allow"

"block"

LocationContentSetting

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

Enum

"allow"

"block"

"ask"

MicrophoneContentSetting

Chrome מגרסה 46 ואילך

Enum

"allow"

"block"

"ask"

MouselockContentSetting

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

ערך

"allow"

MultipleAutomaticDownloadsContentSetting

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

Enum

"allow"

"block"

"ask"

NotificationsContentSetting

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

Enum

"allow"

"block"

"ask"

PluginsContentSetting

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

ערך

"block"

PopupsContentSetting

Chrome מגרסה 44 ואילך

Enum

"allow"

"block"

PpapiBrokerContentSetting

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

ערך

"block"

ResourceIdentifier

סוג התוכן היחיד שמשתמש במזהי משאבים הוא contentSettings.plugins. מידע נוסף זמין במאמר מזהי משאבים.

מאפיינים

תיאור

מחרוזת אופציונלי

תיאור קריא של המשאב.
id [מזהה]

string

מזהה המשאב של סוג התוכן הנתון.

Scope

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

ההיקף של ContentSetting. אחת מהאפשרויות הבאות: regular: הגדרה לפרופיל רגיל (שפרופיל הפרטיות יורש אם לא הוגדרה הגדרה אחרת במקום אחר), incognito\_session\_only: הגדרה לפרופיל הפרטיות שאפשר להגדיר רק במהלך סשן פרטי, והיא נמחקת בסיום הסשן הפרטי (מבטלת את ההגדרות הרגילות).

Enum

"regular"

"incognito_session_only"

מאפיינים

automaticDownloads

האם לאפשר לאתרים להוריד מספר קבצים באופן אוטומטי. אחת מהאפשרויות הבאות: allow: לאפשר לאתרים להוריד קבצים מרובים באופן אוטומטי, block: לא לאפשר לאתרים להוריד קבצים מרובים באופן אוטומטי, ask: לבקש אישור כשאתר רוצה להוריד קבצים באופן אוטומטי אחרי הקובץ הראשון. ברירת המחדל היא ask. כתובת ה-URL הראשית היא כתובת ה-URL של המסגרת ברמה העליונה. לא נעשה שימוש בכתובת ה-URL המשנית.

סוג

ContentSetting<MultipleAutomaticDownloadsContentSetting>

autoVerify

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

האם לאפשר לאתרים להשתמש ב-Private State Tokens API. אחת מהאפשרויות הבאות: allow: מתן הרשאה לאתרים להשתמש ב-Private State Tokens API,‏ block: חסימה של אתרים מפני שימוש ב-Private State Tokens API. ברירת המחדל היא allow. כתובת ה-URL הראשית היא כתובת ה-URL של המסגרת ברמה העליונה. לא נעשה שימוש בכתובת ה-URL המשנית. הערה: כשקוראים ל-set(), התבנית הראשית חייבת להיות ‎ .

סוג

ContentSetting<AutoVerifyContentSetting>

camera

Chrome מגרסה 46 ואילך

אם לאתרים תהיה גישה למצלמה. אחת מהאפשרויות הבאות: allow: מתן גישה לאתרים למצלמה, block: אי מתן גישה לאתרים למצלמה, ask: הצגת בקשה כשאתר רוצה לגשת למצלמה. ברירת המחדל היא ask. כתובת ה-URL הראשית היא כתובת ה-URL של המסמך שבו נשלחה הבקשה לגישה למצלמה. לא נעשה שימוש בכתובת ה-URL המשנית. הערה: ההגדרה 'הרשאה' לא תקפה אם שני התבניות הן ''.

סוג

ContentSetting<CameraContentSetting>

clipboard

Chrome מגרסה 121 ואילך

האם לאפשר לאתרים לגשת ללוח העריכה באמצעות יכולות מתקדמות של Async Clipboard API. יכולות 'מתקדמות' כוללות כל דבר מלבד כתיבת פורמטים מובנים אחרי פעולת משתמש, כלומר היכולת לקרוא, היכולת לכתוב פורמטים מותאמים אישית והיכולת לכתוב בלי פעולת משתמש. אחת מהאפשרויות הבאות: allow: לאפשר לאתרים להשתמש ביכולות מתקדמות של לוח העריכה, block: לא לאפשר לאתרים להשתמש ביכולות מתקדמות של לוח העריכה, ask: לבקש אישור כשאתר רוצה להשתמש ביכולות מתקדמות של לוח העריכה. ברירת המחדל היא ask. כתובת ה-URL הראשית היא כתובת ה-URL של המסמך שביקשו ממנו גישה ללוח העריכה. לא נעשה שימוש בכתובת ה-URL המשנית.

סוג

ContentSetting<ClipboardContentSetting>

cookies

האם לאפשר לאתרים להגדיר קובצי cookie ונתונים מקומיים אחרים. אחת מהאפשרויות הבאות: allow: אישור קובצי cookie, block: חסימה של קובצי cookie, session\_only: אישור קובצי cookie רק לסשן הנוכחי. ברירת המחדל היא allow. כתובת ה-URL הראשית היא כתובת ה-URL שמייצגת את מקור קובץ ה-cookie. כתובת ה-URL המשנית היא כתובת ה-URL של המסגרת ברמה העליונה.

סוג

ContentSetting<CookiesContentSetting>

fullscreen

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

סוג

ContentSetting<FullscreenContentSetting>

images

האם להציג תמונות. אחת מהאפשרויות הבאות: allow: הצגת תמונות, block: לא להציג תמונות. ברירת המחדל היא allow. כתובת ה-URL הראשית היא כתובת ה-URL של המסגרת ברמה העליונה. כתובת ה-URL המשנית היא כתובת ה-URL של התמונה.

סוג

ContentSetting<ImagesContentSetting>

javascript

האם להריץ JavaScript. אחת מהאפשרויות הבאות: allow: הפעלת JavaScript,‏ block: אי הפעלת JavaScript. ברירת המחדל היא allow. כתובת ה-URL הראשית היא כתובת ה-URL של המסגרת ברמה העליונה. לא נעשה שימוש בכתובת ה-URL המשנית.

סוג

ContentSetting<JavascriptContentSetting>

location

האם לאפשר מיקום גיאוגרפי. אחת מהאפשרויות הבאות: allow: לאפשר לאתרים לעקוב אחרי המיקום הפיזי שלכם, block: לא לאפשר לאתרים לעקוב אחרי המיקום הפיזי שלכם, ask: לבקש אישור לפני שמאפשרים לאתרים לעקוב אחרי המיקום הפיזי שלכם. ברירת המחדל היא ask. כתובת ה-URL הראשית היא כתובת ה-URL של המסמך שבו בוצעה הבקשה לקבלת נתוני מיקום. כתובת ה-URL המשנית היא כתובת ה-URL של המסגרת ברמה העליונה (היא עשויה להיות שונה מכתובת ה-URL של מבצע הבקשה).

סוג

ContentSetting<LocationContentSetting>

microphone

Chrome מגרסה 46 ואילך

האם לאפשר לאתרים לגשת למיקרופון. אחת מהאפשרויות הבאות: allow: מתן גישה לאתרים למיקרופון, block: אי מתן גישה לאתרים למיקרופון, ask: הצגת בקשה כשאתר רוצה לגשת למיקרופון. ברירת המחדל היא ask. כתובת ה-URL הראשית היא כתובת ה-URL של המסמך שביקשה גישה למיקרופון. לא נעשה שימוש בכתובת ה-URL המשנית. הערה: ההגדרה 'הרשאה' לא תקפה אם שני התבניות הן ''.

סוג

ContentSetting<MicrophoneContentSetting>

mouselock

הוצא משימוש. אין לה יותר השפעה. ההרשאה לנעילת העכבר מוענקת עכשיו באופן אוטומטי לכל האתרים. הערך הוא תמיד allow.

סוג

ContentSetting<MouselockContentSetting>

notifications

אם לאפשר לאתרים להציג התראות בשולחן העבודה. אחת מהאפשרויות הבאות: allow: האתרים יכולים להציג התראות בשולחן העבודה, block: האתרים לא יכולים להציג התראות בשולחן העבודה, ask: שאל בכל פעם שאתר רוצה להציג התראות בשולחן העבודה. ברירת המחדל היא ask. כתובת ה-URL הראשית היא כתובת ה-URL של המסמך שבו רוצים להציג את ההתראה. לא נעשה שימוש בכתובת ה-URL המשנית.

סוג

ContentSetting<NotificationsContentSetting>

plugins

הוצא משימוש. התמיכה ב-Flash הוסרה ב-Chrome 88, ולכן ההרשאה הזו כבר לא רלוונטית. הערך הוא תמיד block. המערכת תתעלם מהשיחות אל set() ו-clear().

סוג

ContentSetting<PluginsContentSetting>

popups

האם לאפשר לאתרים להציג חלונות קופצים. אחת מהאפשרויות הבאות: allow: לאפשר לאתרים להציג חלונות קופצים, block: לא לאפשר לאתרים להציג חלונות קופצים. ברירת המחדל היא block. כתובת ה-URL הראשית היא כתובת ה-URL של המסגרת ברמה העליונה. לא נעשה שימוש בכתובת ה-URL המשנית.

סוג

ContentSetting<PopupsContentSetting>

unsandboxedPlugins

הוצא משימוש. בעבר, ההרשאה הזו שלטה אם לאפשר לאתרים להפעיל יישומי פלאגין ללא ארגז חול. עם זאת, לאחר ההסרה של תהליך Flash Broker ב-Chrome 88, ההרשאה הזו כבר לא משפיעה. הערך הוא תמיד block. המערכת תתעלם מהשיחות אל set() ו-clear().

סוג

ContentSetting<PpapiBrokerContentSetting>