chrome.contentSettings

refresh date: 2026-09-25 robots: noindex

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. Più in generale, le impostazioni dei contenuti ti consentono di personalizzare il comportamento di Chrome per ogni sito anziché a livello globale.

Autorizzazioni

contentSettings

Manifest

Per utilizzare l'API, devi dichiarare l'autorizzazione "contentSettings" nel manifest dell'estensione. Ad esempio:

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

Pattern delle impostazioni 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 dei pattern delle impostazioni dei contenuti è la stessa dei pattern di corrispondenza, con alcune differenze:

  • Per gli URL http, https e ftp, il percorso deve essere un carattere jolly (/*). Per gli URL file, il percorso deve essere specificato completamente e non deve contenere caratteri jolly.
  • A differenza dei pattern di corrispondenza, i pattern delle impostazioni dei contenuti possono specificare un numero di porta. Se viene 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 dei pattern

Quando per un determinato sito si applicano più regole di impostazione dei contenuti, la regola con il pattern più specifico ha la precedenza.

Ad esempio, i seguenti pattern sono ordinati per precedenza:

  1. https://www.example.com/*
  2. https://*.example.com/* (corrisponde a example.com e a tutti i sottodomini)
  3. <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 diverse parti vengono controllate nel seguente ordine: nome host, schema, porta. Ad esempio, i seguenti pattern sono ordinati per precedenza:

  1. https://www.example.com:*/* Specifica il nome host e lo schema.
  2. *:/www.example.com:123/* Non è così elevata perché, sebbene specifichi il nome host, non specifica lo schema.
  3. https://*.example.com:123/* Più basso perché, sebbene specifichi la porta e lo schema, contiene un carattere jolly nel nome host.

Pattern principali e secondari

L'URL preso in considerazione per decidere quale impostazione dei contenuti applicare dipende dal tipo di contenuti. Ad esempio, per contentSettings.notifications le impostazioni si basano sull'URL mostrato nella omnibox. Questo URL è chiamato URL "principale".

Alcuni tipi di contenuti possono prendere in considerazione URL aggiuntivi. Ad esempio, l'autorizzazione di un sito a impostare un contentSettings.cookies viene decisa in base all'URL della richiesta HTTP (che in questo caso è l'URL principale) e all'URL mostrato nella omnibox (chiamato URL "secondario").

Se più regole hanno pattern principali e secondari, la regola con il pattern principale più specifico ha la precedenza. Se più regole hanno lo stesso pattern principale, la regola con il pattern secondario più specifico ha la precedenza. Ad esempio, il seguente elenco di coppie di pattern principali/secondari è ordinato per precedenza:

PrecedenzaPattern principalePattern secondario
1https://www.moose.com/*,https://www.wombat.com/*
2https://www.moose.com/*,<all_urls>
3<all_urls>,https://www.wombat.com/*
4<all_urls>,<all_urls>

Identificatori di risorse

Gli identificatori delle risorse consentono di specificare le impostazioni dei contenuti per sottotipi specifici di un tipo di contenuti. Attualmente, l'unico tipo di contenuti che supporta gli identificatori di risorse è contentSettings.plugins, dove un identificatore di risorse identifica un plug-in specifico. Quando si applicano le impostazioni dei contenuti, vengono prima controllate le impostazioni del plug-in specifico. Se non vengono trovate impostazioni per il plug-in specifico, vengono controllate le impostazioni dei contenuti generali per i plug-in.

Ad esempio, se una regola di impostazione dei contenuti ha l'identificatore della risorsa adobe-flash-player e il pattern <all_urls>, ha la precedenza su una regola senza un identificatore della risorsa e il pattern https://www.example.com/*, anche se questo pattern è più specifico.

Puoi ottenere un elenco di identificatori di risorse per un tipo di contenuti chiamando il metodo contentSettings.ContentSetting.getResourceIdentifiers. L'elenco restituito può cambiare in base all'insieme di plug-in installati sul computer dell'utente, ma Chrome tenta di mantenere gli identificatori stabili tra gli aggiornamenti dei plug-in.

Esempi

Per provare questa API, installa l'esempio di API contentSettings dal repository chrome-extension-samples.

Tipi

AutoVerifyContentSetting

Chrome 113 e versioni successive

Enum

"allow"

"block"

CameraContentSetting

Chrome 46+

Enum

"allow"

"block"

"ask"

ClipboardContentSetting

Chrome 121 e versioni successive

Enum

"allow"

"block"

"ask"

ContentSetting

Proprietà

  • cancella

    void

    Promise

    Cancella tutte le regole di impostazione dei contenuti impostate da questo set di regole.

    La funzione clear ha il seguente aspetto: 

    (details: object, callback?: function) => {...}

    • dettagli

      oggetto

      • ambito

        Ambito facoltativo

        Dove cancellare l'impostazione (valore predefinito: regular).

    • callback

      funzione elemento facoltativo

      Il parametro callback ha il seguente aspetto: 

      () => void

    • returns

      Promise<void>

      Chrome 96 e versioni successive

      Le promise sono supportate solo per Manifest V3 e versioni successive, mentre le altre piattaforme devono utilizzare i callback.

  • get

    void

    Promise

    Recupera l'impostazione dei contenuti corrente per una determinata coppia di URL.

    La funzione get ha il seguente aspetto: 

    (details: object, callback?: function) => {...}

    • dettagli

      oggetto

      • incognito

        boolean facoltativo

        Indica se controllare le impostazioni dei contenuti per una sessione in incognito. (valore predefinito: false)

      • primaryUrl

        stringa

        L'URL principale per cui recuperare l'impostazione dei contenuti. Tieni presente che il significato di un URL principale dipende dal tipo di contenuti.

      • resourceIdentifier

        ResourceIdentifier facoltativo

        Un identificatore più specifico del tipo di contenuti per cui recuperare le impostazioni.

      • secondaryUrl

        stringa facoltativa

        L'URL secondario per cui recuperare 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 che non tutti i tipi di contenuti utilizzano URL secondari.

    • callback

      funzione elemento facoltativo

      Il parametro callback ha il seguente aspetto: 

      (details: object) => void

      • dettagli

        oggetto

        • impostazione

          T

          L'impostazione dei contenuti. Per i valori possibili, consulta la descrizione dei singoli oggetti ContentSetting.

    • returns

      Promise<object>

      Chrome 96 e versioni successive

      Le promise sono supportate solo per Manifest V3 e versioni successive, mentre le altre piattaforme devono utilizzare i callback.

  • getResourceIdentifiers

    void

    Promise

    La funzione getResourceIdentifiers ha il seguente aspetto: 

    (callback?: function) => {...}

    • callback

      funzione elemento facoltativo

      Il parametro callback ha il seguente aspetto: 

      (resourceIdentifiers?: ResourceIdentifier[]) => void

      • resourceIdentifiers

        ResourceIdentifier[] facoltativo

        Un elenco di identificatori di risorse per questo tipo di contenuti o undefined se questo tipo di contenuti non utilizza identificatori di risorse.

    • returns

      Promise<ResourceIdentifier[]>

      Chrome 96 e versioni successive

      Le promise sono supportate solo per Manifest V3 e versioni successive, mentre le altre piattaforme devono utilizzare i callback.

  • imposta

    void

    Promise

    Applica una nuova regola per le impostazioni dei contenuti.

    La funzione set ha il seguente aspetto: 

    (details: object, callback?: function) => {...}

    • dettagli

      oggetto

      • primaryPattern

        stringa

        Il pattern per l'URL principale. Per i dettagli sul formato di un pattern, consulta Pattern di impostazione dei contenuti.

      • resourceIdentifier

        ResourceIdentifier facoltativo

        L'identificatore della risorsa per il tipo di contenuti.

      • ambito

        Ambito facoltativo

        Dove configurare l'impostazione (valore predefinito: normale).

      • secondaryPattern

        stringa facoltativa

        Il pattern per l'URL secondario. Per impostazione predefinita, corrisponde a tutti gli URL. Per informazioni dettagliate sul formato di un pattern, consulta Pattern delle impostazioni dei contenuti.

      • impostazione

        qualsiasi

        L'impostazione applicata da questa regola. Per i valori possibili, consulta la descrizione dei singoli oggetti ContentSetting.

    • callback

      funzione elemento facoltativo

      Il parametro callback ha il seguente aspetto: 

      () => void

    • returns

      Promise<void>

      Chrome 96 e versioni successive

      Le promise sono supportate solo per Manifest V3 e versioni successive, mentre le altre piattaforme devono utilizzare i callback.

CookiesContentSetting

Chrome 44 e versioni successive

Enum

"allow"

"block"

"session_only"

FullscreenContentSetting

Chrome 44 e versioni successive

Valore

"allow"

ImagesContentSetting

Chrome 44 e versioni successive

Enum

"allow"

"block"

JavascriptContentSetting

Chrome 44 e versioni successive

Enum

"allow"

"block"

LocationContentSetting

Chrome 44 e versioni successive

Enum

"allow"

"block"

"ask"

MicrophoneContentSetting

Chrome 46+

Enum

"allow"

"block"

"ask"

MouselockContentSetting

Chrome 44 e versioni successive

Valore

"allow"

MultipleAutomaticDownloadsContentSetting

Chrome 44 e versioni successive

Enum

"allow"

"block"

"ask"

NotificationsContentSetting

Chrome 44 e versioni successive

Enum

"allow"

"block"

"ask"

PluginsContentSetting

Chrome 44 e versioni successive

Valore

"block"

PopupsContentSetting

Chrome 44 e versioni successive

Enum

"allow"

"block"

PpapiBrokerContentSetting

Chrome 44 e versioni successive

Valore

"block"

ResourceIdentifier

L'unico tipo di contenuti che utilizza gli identificatori delle risorse è contentSettings.plugins. Per saperne di più, consulta Identificatori delle risorse.

Proprietà

  • descrizione

    stringa facoltativa

    Una descrizione della risorsa leggibile da una persona.

  • id

    stringa

    L'identificatore della risorsa per il tipo di contenuti specificato.

Scope

Chrome 44 e versioni successive

L'ambito di ContentSetting. Uno dei seguenti: regular: impostazione per il profilo normale (che viene ereditata dal profilo Incognito se non viene sostituita altrove), incognito\_session\_only: impostazione per il profilo Incognito che può essere impostata solo durante una sessione in incognito e viene eliminata al termine della sessione in incognito (sostituisce le impostazioni normali).

Enum

"regular"

"incognito_session_only"

SoundContentSetting

Chrome 141 e versioni successive

Enum

"allow"

"block"

Proprietà

automaticDownloads

Indica se consentire ai siti di scaricare automaticamente più file. Uno dei seguenti: allow: Consenti ai siti di scaricare automaticamente più file, block: Non consentire ai siti di scaricare automaticamente più file, ask: Chiedi quando un sito vuole scaricare automaticamente i 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.

Tipo

ContentSetting<MultipleAutomaticDownloadsContentSetting>

autoVerify

Chrome 113 e versioni successive

Consente di stabilire se i siti possono 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. Quando chiami set(), il pattern URL principale deve essere <all_urls>. L'URL secondario non viene utilizzato.

Tipo

ContentSetting<AutoVerifyContentSetting>

camera

Chrome 46+

Indica se consentire ai siti di accedere alla fotocamera. Uno dei seguenti valori: 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 "allow" non è valida se entrambi i pattern sono "<all_urls>".

Tipo

ContentSetting<CameraContentSetting>

clipboard

Chrome 121 e versioni successive

Specifica se consentire ai siti di accedere agli appunti tramite le funzionalità avanzate dell'API Async Clipboard. Le funzionalità "avanzate" includono tutto ciò che non sia la scrittura di formati integrati dopo un'attivazione dall'utente, ovvero la possibilità di leggere, di scrivere formati personalizzati e di scrivere senza un'attivazione dall'utente. Uno dei seguenti: allow: consenti ai siti di utilizzare le funzionalità avanzate degli appunti, block: non consentire ai siti di utilizzare le funzionalità avanzate degli appunti, ask: chiedi quando un sito vuole utilizzare 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.

Tipo

ContentSetting<ClipboardContentSetting>

cookies

Consente di stabilire se consentire ai siti web di impostare cookie e altri dati locali. Uno dei seguenti valori: allow: accetta i cookie, block: blocca i 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.

Tipo

ContentSetting<CookiesContentSetting>

fullscreen

Deprecato. Non ha più alcun effetto. L'autorizzazione per lo schermo intero è ora concessa automaticamente per tutti i siti. Il valore è sempre allow.

Tipo

ContentSetting<FullscreenContentSetting>

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.

Tipo

ContentSetting<ImagesContentSetting>

javascript

Se eseguire JavaScript. Uno di 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.

Tipo

ContentSetting<JavascriptContentSetting>

location

Consenti geolocalizzazione. Uno tra allow: Consenti ai siti di rilevare la tua posizione fisica, block: Non consentire ai siti di rilevare la tua posizione fisica, ask: Chiedi prima di consentire ai siti di rilevare 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 di richiesta).

Tipo

ContentSetting<LocationContentSetting>

microphone

Chrome 46+

Indica se consentire ai siti di accedere al microfono. Uno tra 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 "allow" non è valida se entrambi i pattern sono "<all_urls>".

Tipo

ContentSetting<MicrophoneContentSetting>

mouselock

Deprecato. Non ha più alcun effetto. L'autorizzazione di blocco del mouse ora viene concessa automaticamente per tutti i siti. Il valore è sempre allow.

Tipo

ContentSetting<MouselockContentSetting>

notifications

Specifica se consentire ai siti di mostrare notifiche desktop. Uno tra allow: Consenti ai siti di mostrare notifiche desktop, block: Non consentire ai siti di mostrare notifiche desktop, ask: Chiedi quando un sito vuole mostrare notifiche desktop. Il valore predefinito è ask. L'URL principale è l'URL del documento che vuole mostrare la notifica. L'URL secondario non viene utilizzato.

Tipo

ContentSetting<NotificationsContentSetting>

plugins

Deprecato. Con la rimozione del supporto di Flash in Chrome 88, questa autorizzazione non ha più alcun effetto. Il valore è sempre block. Le chiamate a set() e clear() verranno ignorate.

Tipo

ContentSetting<PluginsContentSetting>

popups

Indica 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.

Tipo

ContentSetting<PopupsContentSetting>

unsandboxedPlugins

Deprecato. In precedenza, controllava se consentire ai siti di eseguire plug-in senza sandbox. Tuttavia, con la rimozione del processo del broker Flash in Chrome 88, questa autorizzazione non ha più alcun effetto. Il valore è sempre block. Le chiamate a set() e clear() verranno ignorate.

Tipo

ContentSetting<PpapiBrokerContentSetting>