Descrizione
Utilizza l'API chrome.contentSettings
per modificare le impostazioni che controllano se i siti web possono utilizzare funzionalità come cookie, JavaScript e plug-in. In termini più generali, le impostazioni dei contenuti consentono di personalizzare il comportamento di Chrome in base al sito anziché a livello globale.
Autorizzazioni
contentSettings
Per usare l'API, devi dichiarare l'autorizzazione "contentSettings"
nel manifest dell'estensione. Ad
esempio:
{
"name": "My extension",
...
"permissions": [
"contentSettings"
],
...
}
Concetti e utilizzo
Pattern di impostazione dei contenuti
Puoi utilizzare i pattern per specificare i siti web interessati da ogni impostazione dei contenuti. Ad esempio,
https://*.youtube.com/*
specifica youtube.com e tutti i relativi sottodomini. La sintassi per i pattern di impostazione dei contenuti è la stessa dei pattern di corrispondenza, con alcune differenze:
- Per gli URL
http
,https
eftp
, il percorso deve essere un carattere jolly (/*
). Per gli URLfile
, il percorso deve essere completamente specificato e non deve contenere caratteri jolly. - A differenza dei pattern di corrispondenza, i pattern di impostazione dei contenuti possono specificare un numero di porta. Se è specificato un numero di porta, il pattern corrisponde solo ai siti web con quella porta. Se non viene specificato alcun numero di porta, il pattern corrisponde a tutte le porte.
Precedenza pattern
Se più di una regola di impostazione dei contenuti si applica a un determinato sito, la regola con il pattern più specifico ha la precedenza.
Ad esempio, i seguenti pattern sono ordinati in base alla precedenza:
https://www.example.com/*
https://*.example.com/*
(corrisponde a example.com e a tutti i sottodomini)<all_urls>
(corrisponde a ogni URL)
Esistono tre tipi di caratteri jolly che influiscono sulla specificità di un pattern:
- Caratteri jolly nella porta (ad esempio
https://www.example.com:*/*
) - Caratteri jolly nello schema (ad esempio
*://www.example.com:123/*
) - Caratteri jolly nel nome host (ad esempio
https://*.example.com:123/*
)
Se un pattern è più specifico di un altro in una parte, ma meno specifico in un'altra, le varie parti vengono controllate nel seguente ordine: nome host, schema, porta. Ad esempio, i seguenti pattern sono ordinati in base alla precedenza:
https://www.example.com:*/*
Specifica il nome host e lo schema.*:/www.example.com:123/*
Non così alto perché, sebbene specifichi il nome host, non specifica lo schema.https://*.example.com:123/*
Inferiore perché, sebbene specifichi la porta e lo schema, contiene un carattere jolly nel nome host.
Pattern primari e secondari
L'URL preso in considerazione per decidere quale impostazione dei contenuti applicare dipende dal tipo di contenuti.
Ad esempio, le impostazioni di contentSettings.notifications
si basano sull'URL mostrato nella omnibox. Questo URL è chiamato URL "principale".
Alcuni tipi di contenuti possono prendere in considerazione altri URL. Ad esempio, l'autorizzazione a impostare un elemento contentSettings.cookies
per un sito viene deciso in base all'URL della richiesta HTTP (in questo caso l'URL principale) e all'URL mostrato nella omnibox (l'URL "secondario").
Se più regole hanno pattern primari e secondari, la regola con il pattern principale più specifico ha la precedenza. Se più regole hanno lo stesso pattern principale, quella con il pattern secondario più specifico ha la precedenza. Ad esempio, il seguente elenco di coppie di pattern primari/secondari è ordinato in base alla precedenza:
Precedenza | Pattern principale | Pattern secondario |
---|---|---|
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> |
Identificatori di risorse
Gli identificatori di risorse consentono di specificare le impostazioni dei contenuti per sottotipi specifici di un tipo di contenuto.
Attualmente, l'unico tipo di contenuti che supporta gli identificatori di risorsa è contentSettings.plugins
, in cui un identificatore di risorsa identifica un plug-in specifico. Quando applichi le impostazioni dei contenuti, prima vengono controllate le impostazioni del plug-in specifico. Se non vengono trovate impostazioni per il plug-in specifico, vengono controllate le impostazioni generali dei contenuti per i plug-in.
Ad esempio, se una regola di impostazione dei contenuti ha l'identificatore di risorsa adobe-flash-player
e il pattern <all_urls>
, ha la precedenza su una regola senza identificatore di risorsa e il pattern https://www.example.com/*
, anche se si tratta di un pattern più specifico.
Puoi ottenere un elenco di identificatori di risorse per un tipo di contenuto chiamando il metodo contentSettings.ContentSetting.getResourceIdentifiers()
. L'elenco restituito può cambiare con l'insieme di plug-in installati sul computer dell'utente, ma Chrome cerca di mantenere gli identificatori stabili negli aggiornamenti dei plug-in.
Esempi
Per provare questa API, installa l'esempio di API contentSettings dal repository chrome-extension-samples.
Tipi
AutoVerifyContentSetting
Enum
"block"
CameraContentSetting
Enum
"block"
ClipboardContentSetting
Enum
"block"
ContentSetting
Proprietà
-
cancella
void
PromessaCancella tutte le regole di impostazione dei contenuti impostate da questa estensione.
La funzione
clear
ha il seguente aspetto:(details: object, callback?: function) => {...}
-
dettagli
oggetto
-
ambito
Ambito facoltativo
Dove cancellare l'impostazione (impostazione predefinita: normale).
-
-
callback
funzione facoltativa
Il parametro
callback
ha il seguente aspetto:() => void
-
returns
Promise<void>
Chrome 96 e versioni successiveLe promesse sono supportate in Manifest V3 e versioni successive, ma vengono forniti callback per garantire la compatibilità con le versioni precedenti. Non puoi utilizzarli entrambi nella stessa chiamata di funzione. La promessa viene risolta con lo stesso tipo trasmesso al callback.
-
-
get
void
PromessaRecupera l'impostazione dei contenuti corrente per una determinata coppia di URL.
La funzione
get
ha il seguente aspetto:(details: object, callback?: function) => {...}
-
dettagli
oggetto
-
in incognito
booleano facoltativo
Se controllare le impostazioni dei contenuti per una sessione di navigazione in incognito. (valore predefinito false)
-
primaryUrl
stringa
L'URL principale per il quale deve essere recuperata l'impostazione dei contenuti. Tieni presente che il significato di un URL principale dipende dal tipo di contenuti.
-
resourceIdentifier
Facoltativo ResourceIdentifier
Un identificatore più specifico del tipo di contenuti per cui devono essere recuperate le impostazioni.
-
secondaryUrl
stringa facoltativo
L'URL secondario per il quale deve essere recuperata l'impostazione dei contenuti. Il valore predefinito è l'URL principale. Tieni presente che il significato di un URL secondario dipende dal tipo di contenuti e non tutti i tipi di contenuti utilizzano URL secondari.
-
-
callback
funzione facoltativa
Il parametro
callback
ha il seguente aspetto:(details: object) => void
-
dettagli
oggetto
-
impostazione
T
L'impostazione dei contenuti. Consulta la descrizione dei singoli oggetti ContentSetting per i valori possibili.
-
-
-
returns
Promise<object>
Chrome 96 e versioni successiveLe promesse sono supportate in Manifest V3 e versioni successive, ma vengono forniti callback per garantire la compatibilità con le versioni precedenti. Non puoi utilizzarli entrambi nella stessa chiamata di funzione. La promessa viene risolta con lo stesso tipo trasmesso al callback.
-
-
getResourceIdentifiers
void
PromessaLa funzione
getResourceIdentifiers
ha il seguente aspetto:(callback?: function) => {...}
-
callback
funzione facoltativa
Il parametro
callback
ha il seguente aspetto:(resourceIdentifiers?: ResourceIdentifier[]) => void
-
resourceIdentifiers
ResourceIdentifier[] facoltativo
Un elenco di identificatori di risorse per questo tipo di contenuto oppure
undefined
se questo tipo di contenuto non utilizza identificatori di risorse.
-
-
returns
Promise<ResourceIdentifier[]>
Chrome 96 e versioni successiveLe promesse sono supportate in Manifest V3 e versioni successive, ma vengono forniti callback per garantire la compatibilità con le versioni precedenti. Non puoi utilizzarli entrambi nella stessa chiamata di funzione. La promessa viene risolta con lo stesso tipo trasmesso al callback.
-
-
imposta
void
PromessaApplica una nuova regola di impostazione dei contenuti.
La funzione
set
ha il seguente aspetto:(details: object, callback?: function) => {...}
-
dettagli
oggetto
-
primaryPattern
stringa
Il pattern dell'URL principale. Per maggiori dettagli sul formato di un pattern, consulta la sezione Pattern per l'impostazione dei contenuti.
-
resourceIdentifier
Facoltativo ResourceIdentifier
L'identificatore di risorsa per il tipo di contenuti.
-
ambito
Ambito facoltativo
Dove configurare l'impostazione (impostazione predefinita: regolare).
-
secondaryPattern
stringa facoltativo
Il pattern dell'URL secondario. Il valore predefinito corrisponde a tutti gli URL. Per maggiori dettagli sul formato di un pattern, consulta la sezione Pattern per l'impostazione dei contenuti.
-
impostazione
Qualsiasi
L'impostazione applicata da questa regola. Consulta la descrizione dei singoli oggetti ContentSetting per i valori possibili.
-
-
callback
funzione facoltativa
Il parametro
callback
ha il seguente aspetto:() => void
-
returns
Promise<void>
Chrome 96 e versioni successiveLe promesse sono supportate in Manifest V3 e versioni successive, ma vengono forniti callback per garantire la compatibilità con le versioni precedenti. Non puoi utilizzarli entrambi nella stessa chiamata di funzione. La promessa viene risolta con lo stesso tipo trasmesso al callback.
-
CookiesContentSetting
Enum
"block"
"session_only"
FullscreenContentSetting
Valore
ImagesContentSetting
Enum
"block"
JavascriptContentSetting
Enum
"block"
LocationContentSetting
Enum
"block"
MicrophoneContentSetting
Enum
"block"
MouselockContentSetting
Valore
MultipleAutomaticDownloadsContentSetting
Enum
"block"
NotificationsContentSetting
Enum
"block"
PluginsContentSetting
Valore
"block"
PopupsContentSetting
Enum
"block"
PpapiBrokerContentSetting
Valore
"block"
ResourceIdentifier
L'unico tipo di contenuti che utilizza gli identificatori di risorsa è contentSettings.plugins
. Per ulteriori informazioni, consulta Identificatori delle risorse.
Proprietà
-
descrizione
stringa facoltativo
Una descrizione leggibile della risorsa.
-
id
stringa
L'identificatore di risorsa per il tipo di contenuto specificato.
Scope
L'ambito dell'impostazione ContentSetting. Uno dei seguenti:
regular
: impostazione per il profilo regolare (che viene ereditato dal profilo in incognito se non viene sostituito altrove),
incognito\_session\_only
: impostazione per il profilo in incognito che può essere impostato solo durante una sessione in incognito e viene eliminata al termine della sessione in incognito (esegue l'override delle impostazioni normali).
Enum
"incognito_session_only"
Proprietà
automaticDownloads
Indica se consentire ai siti di scaricare automaticamente più file. Uno di
allow
: consenti ai siti di scaricare automaticamente più file,
block
: non consentire ai siti di scaricare automaticamente più file,
ask
: chiedi ai siti di scaricare automaticamente file dopo il primo file.
Il valore predefinito è ask
.
L'URL principale è l'URL del frame di primo livello. L'URL secondario non viene utilizzato.
autoVerify
Indica se consentire ai siti di utilizzare l'API Private State Tokens. Uno dei seguenti:
allow
: Consenti ai siti di utilizzare l'API Private State Tokens,
block
: Impedisci ai siti di utilizzare l'API Private State Tokens.
Il valore predefinito è allow
.
L'URL principale è l'URL del frame di primo livello. L'URL secondario non viene utilizzato. NOTA: quando chiami set()
, il pattern principale deve essere .
camera
Se consentire ai siti di accedere alla videocamera. Uno di
allow
: consenti ai siti di accedere alla fotocamera,
block
: non consentire ai siti di accedere alla fotocamera,
ask
: chiedi quando un sito vuole accedere alla fotocamera.
Il valore predefinito è ask
.
L'URL principale è l'URL del documento che ha richiesto l'accesso alla fotocamera. L'URL secondario non viene utilizzato.
NOTA: l'impostazione "consenti" non è valida se entrambi i pattern sono "".
clipboard
Se consentire ai siti di accedere agli appunti tramite le funzionalità avanzate dell'API Async Clipboard. Le funzionalità "avanzate" includono tutto ciò che riguarda la scrittura di formati integrati dopo un gesto dell'utente, ad esempio la possibilità di leggere, di scrivere formati personalizzati e di scrivere senza un gesto dell'utente. Uno di
allow
: consenti ai siti di utilizzare le funzionalità avanzate degli appunti,
block
: non consentire ai siti di usare funzionalità avanzate degli appunti,
ask
: chiedi quando un sito vuole usare le funzionalità avanzate degli appunti.
Il valore predefinito è ask
.
L'URL principale è l'URL del documento che ha richiesto l'accesso agli appunti. L'URL secondario non viene utilizzato.
cookies
Se consentire l'impostazione di cookie e altri dati locali da parte dei siti web. Uno dei seguenti:
allow
: Accetta cookie,
block
: Blocca cookie,
session\_only
: Accetta i cookie solo per la sessione corrente.
Il valore predefinito è allow
.
L'URL principale è l'URL che rappresenta l'origine del cookie. L'URL secondario è l'URL del frame di primo livello.
fullscreen
Obsoleta. Non ha più alcun effetto. L'autorizzazione per la visualizzazione a schermo intero viene ora concessa automaticamente per tutti i siti. Il valore è sempre allow
.
images
Se mostrare le immagini. Uno dei seguenti:
allow
: mostra immagini,
block
: non mostrare immagini.
Il valore predefinito è allow
.
L'URL principale è l'URL del frame di primo livello. L'URL secondario è l'URL dell'immagine.
javascript
Se eseguire JavaScript. Uno dei seguenti:
allow
: esegui JavaScript,
block
: non eseguire JavaScript.
Il valore predefinito è allow
.
L'URL principale è l'URL del frame di primo livello. L'URL secondario non viene utilizzato.
location
Se consentire la geolocalizzazione. Uno di
allow
: consenti ai siti di monitorare la tua posizione fisica,
block
: non consentire ai siti di monitorare la tua posizione fisica,
ask
: chiedi prima di consentire ai siti di monitorare la tua posizione fisica.
Il valore predefinito è ask
.
L'URL principale è l'URL del documento che ha richiesto i dati sulla posizione. L'URL secondario è l'URL del frame di primo livello (che può essere o meno diverso dall'URL richiedente).
microphone
Se consentire ai siti di accedere al microfono. Uno dei seguenti:
allow
: Consenti ai siti di accedere al microfono,
block
: Non consentire ai siti di accedere al microfono,
ask
: Chiedi quando un sito vuole accedere al microfono.
Il valore predefinito è ask
.
L'URL principale è l'URL del documento che ha richiesto l'accesso al microfono. L'URL secondario non viene utilizzato.
NOTA: l'impostazione "consenti" non è valida se entrambi i pattern sono "".
mouselock
Obsoleta. Non ha più alcun effetto. L'autorizzazione per il blocco del mouse viene ora concessa automaticamente per tutti i siti. Il valore è sempre allow
.
notifications
Se consentire ai siti di mostrare notifiche desktop. Uno dei seguenti:
allow
: Consenti ai siti di mostrare le notifiche desktop,
block
: Non consentire ai siti di mostrare notifiche desktop,
ask
: Chiedi quando un sito vuole mostrare le notifiche desktop.
Il valore predefinito è ask
.
L'URL principale è l'URL del documento che vuole mostrare la notifica. L'URL secondario non viene utilizzato.
plugins
Obsoleta. Poiché il supporto Flash è stato rimosso in Chrome 88, questa autorizzazione non ha più alcun effetto. Il valore è sempre block
. Le chiamate a set()
e clear()
verranno ignorate.
popups
Se consentire ai siti di mostrare popup. Uno dei seguenti:
allow
: consenti ai siti di mostrare popup,
block
: non consentire ai siti di mostrare popup.
Il valore predefinito è block
.
L'URL principale è l'URL del frame di primo livello. L'URL secondario non viene utilizzato.
unsandboxedPlugins
Obsoleta. In precedenza, veniva controllata se consentiva ai siti di eseguire plug-in senza sandbox; tuttavia, dopo la rimozione del processo Flash broker in Chrome 88, questa autorizzazione non ha più alcun effetto. Il valore è sempre block
. Le chiamate a set()
e clear()
verranno ignorate.