chrome.contentSettings

refresh date: 2026-09-25 robots: noindex

Descrição

Use a API chrome.contentSettings para mudar as configurações que controlam se os sites podem usar recursos como cookies, JavaScript e plug-ins. De modo geral, as configurações de conteúdo permitem personalizar o comportamento do Chrome por site, em vez de globalmente.

Permissões

contentSettings

Manifesto

É necessário declarar a permissão "contentSettings" no manifesto da extensão para usar a API. Por exemplo:

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

Padrões de configuração de conteúdo

Você pode usar padrões para especificar os sites afetados por cada configuração de conteúdo. Por exemplo, https://*.youtube.com/* especifica youtube.com e todos os subdomínios dele. A sintaxe dos padrões de configuração de conteúdo é igual à dos padrões de correspondência, com algumas diferenças:

  • Para URLs http, https e ftp, o caminho precisa ser um caractere curinga (/*). Para URLs file, o caminho precisa ser completamente especificado e não pode conter caracteres curinga.
  • Ao contrário dos padrões de correspondência, os padrões de configuração de conteúdo podem especificar um número de porta. Se um número de porta for especificado, o padrão só vai corresponder a sites com essa porta. Se nenhum número de porta for especificado, o padrão corresponderá a todas as portas.

Precedência do padrão

Quando mais de uma regra de configuração de conteúdo se aplica a um determinado site, a regra com o padrão mais específico tem precedência.

Por exemplo, os seguintes padrões são ordenados por precedência:

  1. https://www.example.com/*
  2. https://*.example.com/* (correspondente a example.com e todos os subdomínios)
  3. <all_urls> (correspondente a todos os URLs)

Três tipos de caracteres curinga afetam a especificidade de um padrão:

  • Caracteres curinga na porta (por exemplo, https://www.example.com:*/*)
  • Caracteres curinga no esquema (por exemplo, *://www.example.com:123/*)
  • Caracteres curinga no nome do host (por exemplo, https://*.example.com:123/*)

Se um padrão for mais específico do que outro em uma parte, mas menos específico em outra, as diferentes partes serão verificadas na seguinte ordem: nome do host, esquema, porta. Por exemplo, os padrões a seguir são ordenados por precedência:

  1. https://www.example.com:*/* Especifica o nome do host e o esquema.
  2. *:/www.example.com:123/* Não é tão alta, porque, embora especifique o nome do host, não especifica o esquema.
  3. https://*.example.com:123/* Menor porque, embora especifique a porta e o esquema, ele tem um caractere curinga no nome do host.

Padrões primários e secundários

O URL considerado ao decidir qual configuração de conteúdo aplicar depende do tipo de conteúdo. Por exemplo, para contentSettings.notifications, as configurações são baseadas no URL mostrado na omnibox. Esse URL é chamado de "principal".

Alguns tipos de conteúdo podem considerar URLs adicionais. Por exemplo, se um site tem permissão para definir um contentSettings.cookies, isso é decidido com base no URL da solicitação HTTP (que é o URL principal nesse caso) e no URL mostrado na omnibox (chamado de URL "secundário").

Se várias regras tiverem padrões primários e secundários, a regra com o padrão primário mais específico terá precedência. Se várias regras tiverem o mesmo padrão principal, aquela com o padrão secundário mais específico terá precedência. Por exemplo, a lista a seguir de pares de padrões primários/secundários é ordenada por precedência:

PrecedênciaPadrão principalPadrão secundário
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>

Identificadores de recursos

Os identificadores de recursos permitem especificar configurações de conteúdo para subtipos específicos de um tipo de conteúdo. No momento, o único tipo de conteúdo que aceita identificadores de recursos é contentSettings.plugins, em que um identificador de recurso identifica um plug-in específico. Ao aplicar as configurações de conteúdo, primeiro as configurações do plug-in específico são verificadas. Se não houver configurações para o plug-in específico, as configurações gerais de conteúdo para plug-ins serão verificadas.

Por exemplo, se uma regra de configuração de conteúdo tiver o identificador de recurso adobe-flash-player e o padrão <all_urls>, ela terá precedência sobre uma regra sem um identificador de recurso e o padrão https://www.example.com/*, mesmo que esse padrão seja mais específico.

Para receber uma lista de identificadores de recursos para um tipo de conteúdo, chame o método contentSettings.ContentSetting.getResourceIdentifiers. A lista retornada pode mudar com o conjunto de plug-ins instalados na máquina do usuário, mas o Chrome tenta manter os identificadores estáveis nas atualizações de plug-ins.

Exemplos

Para testar essa API, instale o exemplo da API contentSettings do repositório chrome-extension-samples.

Tipos

AutoVerifyContentSetting

Chrome 113 ou mais recente

Enumeração

"allow"

"block"

CameraContentSetting

Chrome 46 ou mais recente

Enumeração

"allow"

"block"

"ask"

ClipboardContentSetting

Chrome 121+

Enumeração

"allow"

"block"

"ask"

ContentSetting

Propriedades

  • limpar

    void

    Promessa

    Limpa todas as regras de configuração de conteúdo definidas por esta extensão.

    A função clear é semelhante a: 

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

    • detalhes

      objeto

      • escopo

        Escopo opcional

        Onde limpar a configuração (padrão: normal).

    • callback

      função optional

      O parâmetro callback é semelhante a: 

      () => void

    • retorna

      Promessa<void>

      Chrome 96 ou mais recente

      As promessas só são compatíveis com o Manifest V3 e versões mais recentes. Outras plataformas precisam usar callbacks.

  • get

    void

    Promessa

    Recebe a configuração de conteúdo atual para um determinado par de URLs.

    A função get é semelhante a: 

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

    • detalhes

      objeto

      • incognito

        booleano opcional

        Se as configurações de conteúdo devem ser verificadas para uma sessão de navegação anônima. (padrão: falso)

      • primaryUrl

        string

        O URL principal para o qual a configuração de conteúdo deve ser recuperada. O significado de um URL principal depende do tipo de conteúdo.

      • resourceIdentifier

        ResourceIdentifier opcional

        Um identificador mais específico do tipo de conteúdo para o qual as configurações devem ser recuperadas.

      • secondaryUrl

        string opcional

        O URL secundário para o qual a configuração de conteúdo deve ser recuperada. O padrão é o URL principal. O significado de um URL secundário depende do tipo de conteúdo, e nem todos os tipos de conteúdo usam URLs secundários.

    • callback

      função optional

      O parâmetro callback é semelhante a: 

      (details: object) => void

      • detalhes

        objeto

        • Configuração

          T

          A configuração de conteúdo. Consulte a descrição dos objetos ContentSetting individuais para ver os valores possíveis.

    • retorna

      Promise<object>

      Chrome 96 ou mais recente

      As promessas só são compatíveis com o Manifest V3 e versões mais recentes. Outras plataformas precisam usar callbacks.

  • getResourceIdentifiers

    void

    Promessa

    A função getResourceIdentifiers é semelhante a: 

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

    • callback

      função optional

      O parâmetro callback é semelhante a: 

      (resourceIdentifiers?: ResourceIdentifier[]) => void

      • resourceIdentifiers

        ResourceIdentifier[] opcional

        Uma lista de identificadores de recursos para esse tipo de conteúdo ou undefined se esse tipo de conteúdo não usar identificadores de recursos.

    • retorna

      Promise<ResourceIdentifier[]>

      Chrome 96 ou mais recente

      As promessas só são compatíveis com o Manifest V3 e versões mais recentes. Outras plataformas precisam usar callbacks.

  • set

    void

    Promessa

    Aplica uma nova regra de configuração de conteúdo.

    A função set é semelhante a: 

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

    • detalhes

      objeto

      • primaryPattern

        string

        O padrão do URL principal. Para detalhes sobre o formato de um padrão, consulte Padrões de configuração de conteúdo.

      • resourceIdentifier

        ResourceIdentifier opcional

        O identificador de recurso para o tipo de conteúdo.

      • escopo

        Escopo opcional

        Onde definir a configuração (padrão: normal).

      • secondaryPattern

        string opcional

        O padrão do URL secundário. Por padrão, todos os URLs são correspondidos. Para detalhes sobre o formato de um padrão, consulte Padrões de configuração de conteúdo.

      • Configuração

        qualquer

        A configuração aplicada por essa regra. Consulte a descrição dos objetos ContentSetting individuais para ver os valores possíveis.

    • callback

      função optional

      O parâmetro callback é semelhante a: 

      () => void

    • retorna

      Promessa<void>

      Chrome 96 ou mais recente

      As promessas só são compatíveis com o Manifest V3 e versões mais recentes. Outras plataformas precisam usar callbacks.

CookiesContentSetting

Chrome 44+

Enumeração

"allow"

"block"

"session_only"

FullscreenContentSetting

Chrome 44+

Valor

"allow"

ImagesContentSetting

Chrome 44+

Enumeração

"allow"

"block"

JavascriptContentSetting

Chrome 44+

Enumeração

"allow"

"block"

LocationContentSetting

Chrome 44+

Enumeração

"allow"

"block"

"ask"

MicrophoneContentSetting

Chrome 46 ou mais recente

Enumeração

"allow"

"block"

"ask"

MouselockContentSetting

Chrome 44+

Valor

"allow"

MultipleAutomaticDownloadsContentSetting

Chrome 44+

Enumeração

"allow"

"block"

"ask"

NotificationsContentSetting

Chrome 44+

Enumeração

"allow"

"block"

"ask"

PluginsContentSetting

Chrome 44+

Valor

"block"

PopupsContentSetting

Chrome 44+

Enumeração

"allow"

"block"

PpapiBrokerContentSetting

Chrome 44+

Valor

"block"

ResourceIdentifier

O único tipo de conteúdo que usa identificadores de recursos é contentSettings.plugins. Para mais informações, consulte Identificadores de recursos.

Propriedades

  • descrição

    string opcional

    Uma descrição do recurso legível por humanos.

  • ID

    string

    O identificador de recurso para o tipo de conteúdo fornecido.

Scope

Chrome 44+

O escopo do ContentSetting. Um dos seguintes: regular: configuração para o perfil normal (que é herdada pelo perfil de navegação anônima se não for substituída em outro lugar). incognito\_session\_only: configuração para o perfil de navegação anônima que só pode ser definida durante uma sessão de navegação anônima e é excluída quando a sessão termina (substitui as configurações normais).

Enumeração

"regular"

"incognito_session_only"

SoundContentSetting

Chrome 141+

Enumeração

"allow"

"block"

Propriedades

automaticDownloads

Se os sites podem baixar vários arquivos automaticamente. Uma das seguintes opções: allow: permitir que os sites façam o download de vários arquivos automaticamente. block: não permitir que os sites façam o download de vários arquivos automaticamente. ask: perguntar quando um site quiser fazer o download de arquivos automaticamente após o primeiro arquivo. O padrão é ask. O URL principal é o URL do frame de nível superior. O URL secundário não é usado.

Tipo

ContentSetting<MultipleAutomaticDownloadsContentSetting>

autoVerify

Chrome 113 ou mais recente

Se os sites podem usar a API Private State Tokens. Uma das seguintes opções: allow: permitir que os sites usem a API Private State Tokens. block: impedir que os sites usem a API Private State Tokens. O padrão é allow. Ao chamar set(), o padrão do URL principal precisa ser <all_urls>. O URL secundário não é usado.

Tipo

ContentSetting<AutoVerifyContentSetting>

camera

Chrome 46 ou mais recente

Se os sites podem acessar a câmera. Uma das seguintes opções: allow: permitir que os sites acessem a câmera block: não permitir que os sites acessem a câmera ask: perguntar quando um site quiser acessar a câmera O padrão é ask. O URL principal é o URL do documento que solicitou acesso à câmera. O URL secundário não é usado. OBSERVAÇÃO: a configuração "allow" não é válida se os dois padrões forem "<all_urls>".

Tipo

ContentSetting<CameraContentSetting>

clipboard

Chrome 121+

Se os sites podem acessar a área de transferência usando recursos avançados da API Async Clipboard. Os recursos "avançados" incluem tudo além de gravar formatos integrados após uma interação inicial, ou seja, a capacidade de ler, gravar formatos personalizados e gravar sem uma interação inicial. Uma das seguintes opções: allow: permitir que os sites usem recursos avançados da área de transferência block: não permitir que os sites usem recursos avançados da área de transferência ask: perguntar quando um site quiser usar recursos avançados da área de transferência O padrão é ask. O URL principal é o URL do documento que solicitou acesso à área de transferência. O URL secundário não é usado.

Tipo

ContentSetting<ClipboardContentSetting>

cookies

Se os sites podem definir cookies e outros dados locais. Uma destas opções: allow: aceitar cookies, block: bloquear cookies, session\_only: aceitar cookies apenas para a sessão atual. O padrão é allow. O URL principal é o URL que representa a origem do cookie. O URL secundário é o URL do frame de nível superior.

Tipo

ContentSetting<CookiesContentSetting>

fullscreen

Obsoleto. Não tem mais efeito. A permissão de tela cheia agora é concedida automaticamente para todos os sites. O valor é sempre allow.

Tipo

ContentSetting<FullscreenContentSetting>

images

Se as imagens devem ser mostradas. Uma das opções allow: mostrar imagens, block: não mostrar imagens. O padrão é allow. O URL principal é o URL do frame de nível superior. O URL secundário é o URL da imagem.

Tipo

ContentSetting<ImagesContentSetting>

javascript

Se o JavaScript deve ser executado. Uma das opções allow: executar JavaScript, block: não executar JavaScript. O padrão é allow. O URL principal é o URL do frame de nível superior. O URL secundário não é usado.

Tipo

ContentSetting<JavascriptContentSetting>

location

Se a geolocalização é permitida. Uma das seguintes opções: allow: permitir que os sites rastreiem seu local físico, block: não permitir que os sites rastreiem seu local físico, ask: perguntar antes de permitir que os sites rastreiem seu local físico. O padrão é ask. O URL principal é o URL do documento que solicitou os dados de local. O URL secundário é o URL do frame de nível superior, que pode ou não ser diferente do URL de solicitação.

Tipo

ContentSetting<LocationContentSetting>

microphone

Chrome 46 ou mais recente

Se os sites podem acessar o microfone. Uma das seguintes opções: allow: permitir que os sites acessem o microfone. block: não permitir que os sites acessem o microfone. ask: perguntar quando um site quiser acessar o microfone. O padrão é ask. O URL principal é o URL do documento que solicitou acesso ao microfone. O URL secundário não é usado. OBSERVAÇÃO: a configuração "allow" não é válida se os dois padrões forem "<all_urls>".

Tipo

ContentSetting<MicrophoneContentSetting>

mouselock

Obsoleto. Não tem mais efeito. A permissão de bloqueio do mouse agora é concedida automaticamente para todos os sites. O valor é sempre allow.

Tipo

ContentSetting<MouselockContentSetting>

notifications

Se os sites podem mostrar notificações na área de trabalho. Uma das seguintes opções: allow: permitir que os sites mostrem notificações na área de trabalho, block: não permitir que os sites mostrem notificações na área de trabalho, ask: perguntar quando um site quiser mostrar notificações na área de trabalho. O padrão é ask. O URL principal é o URL do documento que quer mostrar a notificação. O URL secundário não é usado.

Tipo

ContentSetting<NotificationsContentSetting>

plugins

Obsoleto. Como o suporte ao Flash foi removido no Chrome 88, essa permissão não tem mais efeito. O valor é sempre block. As chamadas para set() e clear() serão ignoradas.

Tipo

ContentSetting<PluginsContentSetting>

popups

Se os sites podem mostrar pop-ups. Uma das seguintes opções: allow: permitir que os sites mostrem pop-ups block: não permitir que os sites mostrem pop-ups O padrão é block. O URL principal é o URL do frame de nível superior. O URL secundário não é usado.

Tipo

ContentSetting<PopupsContentSetting>

unsandboxedPlugins

Obsoleto. Antes, controlava se os sites podiam executar plug-ins sem sandbox. No entanto, com a remoção do processo do agente do Flash no Chrome 88, essa permissão não tem mais efeito. O valor é sempre block. As chamadas para set() e clear() serão ignoradas.

Tipo

ContentSetting<PpapiBrokerContentSetting>