דף זה תורגם על ידי 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

Chrome 113 ואילך

Enum

CameraContentSetting

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

Enum

"block"

"ask"

ClipboardContentSetting

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

Enum

"block"

ContentSetting

מאפיינים

נקה

ריק

Promise

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

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

ריק

Promise

הפונקציה מקבלת את הגדרת התוכן הנוכחית עבור זוג נתון של כתובות 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 ואילך
  
  יש תמיכה ב-Promises ב-Manifest V3 ואילך, אבל פונקציות קריאה חוזרת (callbacks) ניתנות לצורך תאימות לאחור. אי אפשר להשתמש בשניהם באותה קריאה לפונקציה. ההבטחה ניתנת לפתרון באותו הסוג שמועבר לקריאה החוזרת.
getResourceIdentifiers

ריק

Promise

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

ריק

Promise

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

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

CookiesContentSetting

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

Enum

"block"

"session_only"

FullscreenContentSetting

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

ערך

"allow"

ImagesContentSetting

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

Enum

JavascriptContentSetting

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

Enum

LocationContentSetting

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

Enum

"block"

"ask"

MicrophoneContentSetting

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

Enum

"block"

"ask"

MouselockContentSetting

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

ערך

"allow"

MultipleAutomaticDownloadsContentSetting

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

Enum

"block"

"ask"

NotificationsContentSetting

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

Enum

"block"

"ask"

PluginsContentSetting

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

ערך

"block"

PopupsContentSetting

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

Enum

PpapiBrokerContentSetting

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

ערך

"block"

ResourceIdentifier

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

מאפיינים

תיאור

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

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

מחרוזת

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

Scope

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

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

Enum

מאפיינים

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 ואילך

האם לאפשר לאתרים לגשת ללוח העריכה באמצעות יכולות מתקדמות של ה-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>