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
É necessário declarar a permissão "contentSettings"
no manifesto da extensão para usar a API. Por
exemplo:
{
"name": "My extension",
...
"permissions": [
"contentSettings"
],
...
}
Conceitos e uso
Padrões de configuração de conteúdo
Você pode usar padrões para especificar os sites que cada configuração de conteúdo afeta. Por exemplo,
https://*.youtube.com/*
especifica youtube.com e todos os subdomínios. A sintaxe dos padrões de
configuração de conteúdo é a mesma dos padrões de correspondência, com algumas diferenças:
- Para URLs
http
,https
eftp
, o caminho precisa ser um caractere curinga (/*
). Para URLsfile
, 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 vai 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 padrões a seguir são ordenados por precedência:
https://www.example.com/*
https://*.example.com/*
(corresponde a example.com e todos os subdomínios)<all_urls>
(corresponde a todos os URLs)
Três tipos de curingas 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 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 seguintes padrões são ordenados por precedência:
https://www.example.com:*/*
Especifica o nome do host e o esquema.*:/www.example.com:123/*
Não tão alto, porque, embora especifique o nome do host, não especifica o esquema.https://*.example.com:123/*
Menor, porque, embora especifique a porta e o esquema, tem um caractere curinga no nome do host.
Padrões primários e secundários
O URL considerado ao decidir qual configuração aplicar depende do tipo de conteúdo.
Por exemplo, as configurações de contentSettings.notifications
são baseadas no URL mostrado na
omnibox. Esse URL é chamado de "principal".
Alguns tipos de conteúdo podem levar outros URLs em consideração. Por exemplo, se um site pode
definir um contentSettings.cookies
é decidido com base no URL da solicitação HTTP (que é o
URL principal neste caso) e no URL mostrado na caixa de pesquisa (chamado de URL "secundário").
Se várias regras tiverem padrões primário e secundário, a regra com o padrão primário mais específico terá precedência. Se várias regras tiverem o mesmo padrão principal, a regra com o padrão secundário mais específico terá precedência. Por exemplo, a lista a seguir de pares de padrões primário/secundário é ordenada por precedência:
Precedência | Padrão principal | Padrão secundário |
---|---|---|
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> |
Não há suporte para padrões secundários na configuração de conteúdo de imagens.
Identificadores de recursos
Os identificadores de recursos permitem especificar configurações de conteúdo para subtipos específicos de um tipo de conteúdo.
Atualmente, o único tipo de conteúdo compatível com identificadores de recurso é contentSettings.plugins
,
em que um identificador de recurso identifica um plug-in específico. Ao aplicar as configurações de conteúdo, as
configurações do plug-in específico são verificadas primeiro. Se não houver configurações encontradas para o plug-in
específico, as configurações de conteúdo gerais 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
<all_urls>
, mesmo que esse padrão seja mais específico.https://www.example.com/*
Para conferir uma lista de identificadores de recursos de 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 do plug-in.
Exemplos
Para testar essa API, instale o exemplo da API contentSettings do repositório chrome-extension-samples.
Tipos
AutoVerifyContentSetting
Enumeração
"allow"
"block"
CameraContentSetting
Enumeração
"allow"
"block"
"ask"
ClipboardContentSetting
Enumeração
"allow"
"block"
"ask"
ContentSetting
Propriedades
-
limpar
void
PromessaLimpar todas as regras de configuração de conteúdo definidas por essa extensão.
A função
clear
é semelhante a esta:(details: object, callback?: function) => {...}
-
detalhes
objeto
-
escopo
Escopo opcional
Onde limpar a configuração (padrão: normal).
-
-
callback
função opcional
O parâmetro
callback
tem este formato:() => void
-
retorna
Promise<void>
Chrome 96 e versões mais recentesAs promessas têm suporte no Manifest V3 e versões mais recentes, mas os callbacks são fornecidos para compatibilidade com versões anteriores. Não é possível usar os dois na mesma chamada de função. A promessa é resolvida com o mesmo tipo transmitido para o callback.
-
-
get
void
PromessaRecebe a configuração de conteúdo atual para um determinado par de URLs.
A função
get
é semelhante a esta:(details: object, callback?: function) => {...}
-
detalhes
objeto
-
navegação anônima
booleano opcional
Define se as configurações de conteúdo de uma sessão anônima serão verificadas. (padrão: false)
-
primaryUrl
string
O URL principal para o qual a configuração de conteúdo precisa 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 serão extraídas.
-
secondaryUrl
string opcional
O URL secundário para o qual a configuração de conteúdo precisa 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 opcional
O parâmetro
callback
tem este formato:(details: object) => void
-
detalhes
objeto
-
Configuração
T
A configuração de conteúdo. Consulte a descrição dos objetos individuais do ContentSetting para conferir os valores possíveis.
-
-
-
retorna
Promise<object>
Chrome 96 e versões mais recentesAs promessas têm suporte no Manifest V3 e versões mais recentes, mas os callbacks são fornecidos para compatibilidade com versões anteriores. Não é possível usar os dois na mesma chamada de função. A promessa é resolvida com o mesmo tipo transmitido para o callback.
-
-
getResourceIdentifiers
void
PromessaA função
getResourceIdentifiers
é semelhante a esta:(callback?: function) => {...}
-
callback
função opcional
O parâmetro
callback
tem este formato:(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 e versões mais recentesAs promessas têm suporte no Manifest V3 e versões mais recentes, mas os callbacks são fornecidos para compatibilidade com versões anteriores. Não é possível usar os dois na mesma chamada de função. A promessa é resolvida com o mesmo tipo transmitido para o callback.
-
-
set
void
PromessaAplica uma nova regra de configuração de conteúdo.
A função
set
é semelhante a esta:(details: object, callback?: function) => {...}
-
detalhes
objeto
-
primaryPattern
string
O padrão do URL principal. Para mais detalhes sobre o formato de um padrão, consulte Padrões de configuração de conteúdo.
-
resourceIdentifier
ResourceIdentifier opcional
Identificador do 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, corresponde a todos os URLs. Para saber mais sobre o formato de um padrão, consulte Padrões de configuração de conteúdo.
-
Configuração
qualquer um
A configuração aplicada por essa regra. Consulte a descrição dos objetos individuais do ContentSetting para conferir os valores possíveis.
-
-
callback
função opcional
O parâmetro
callback
tem este formato:() => void
-
retorna
Promise<void>
Chrome 96 e versões mais recentesAs promessas têm suporte no Manifest V3 e versões mais recentes, mas os callbacks são fornecidos para compatibilidade com versões anteriores. Não é possível usar os dois na mesma chamada de função. A promessa é resolvida com o mesmo tipo transmitido para o callback.
-
CookiesContentSetting
Enumeração
"allow"
"block"
"session_only"
FullscreenContentSetting
Valor
"allow"
ImagesContentSetting
Enumeração
"allow"
"block"
JavascriptContentSetting
Enumeração
"allow"
"block"
LocationContentSetting
Enumeração
"allow"
"block"
"ask"
MicrophoneContentSetting
Enumeração
"allow"
"block"
"ask"
MouselockContentSetting
Valor
"allow"
MultipleAutomaticDownloadsContentSetting
Enumeração
"allow"
"block"
"ask"
NotificationsContentSetting
Enumeração
"allow"
"block"
"ask"
PluginsContentSetting
Valor
"block"
PopupsContentSetting
Enumeração
"allow"
"block"
PpapiBrokerContentSetting
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 legível por humanos do recurso.
-
id
string
O identificador de recurso para o tipo de conteúdo especificado.
Scope
O escopo da ContentSetting. Uma de
regular
: configuração para o perfil normal (que é herdado pelo perfil anônimo se não for substituído em outro lugar),
incognito\_session\_only
: configuração para o perfil anônimo que só pode ser definida durante uma sessão anônima e é excluída quando a sessão anônima termina (substitui as configurações normais).
Enumeração
"regular"
"incognito_session_only"
Propriedades
automaticDownloads
Permitir que os sites façam o download automático de vários arquivos. Uma das opções é
allow
: permitir que os sites façam o download automático de vários arquivos,
block
: não permitir que os sites façam o download automático de vários arquivos,
ask
: perguntar quando um site quer fazer o download automático de arquivos após o primeiro.
O padrão é ask
.
O URL principal é o URL do frame de nível superior. O URL secundário não é usado.
autoVerify
Permitir que os sites usem a API Private State Tokens. Um dos seguintes:
allow
: permitir que os sites usem a API Private State Tokens,
block
: bloquear os sites de usar a API Private State Tokens.
O padrão é allow
.
O URL principal é o URL do frame de nível superior. O URL secundário não é usado. OBSERVAÇÃO: ao chamar set()
, o padrão principal precisa ser .
camera
Permitir que sites acessem a câmera. Uma das opções
allow
: Permitir que sites acessem a câmera,
block
: Não permitir que sites acessem a câmera,
ask
: Perguntar quando um site quiser acessar a câmera.
O padrão é ask
.
O URL principal é o do documento que solicitou o acesso à câmera. O URL secundário não é usado.
OBSERVAÇÃO: a configuração "permitir" não é válida se os dois padrões forem "'".
clipboard
Permitir que os sites acessem a área de transferência usando recursos avançados da API Async Clipboard. Os recursos "avançados" incluem tudo além da gravação de formatos integrados após um gesto do usuário, ou seja, a capacidade de ler, gravar formatos personalizados e gravar sem um gesto do usuário. 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 do documento que solicitou o acesso à área de transferência. O URL secundário não é usado.
cookies
Permitir que cookies e outros dados locais sejam definidos por sites. 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 que representa a origem do cookie. O URL secundário é o URL do frame de nível superior.
fullscreen
Obsoleto. Não tem mais efeito. A permissão de tela cheia agora é concedida automaticamente para todos os sites. O valor é sempre allow
.
images
Indica se as imagens vão ser mostradas. Um dos
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 da imagem.
javascript
Se o JavaScript será executado. Um dos
allow
: executa JavaScript,
block
: não executa JavaScript.
O padrão é allow
.
O URL principal é o URL do frame de nível superior. O URL secundário não é usado.
location
Se a geolocalização será permitida. Uma das opções é
allow
: permitir que sites rastreiem sua localização física,
block
: não permitir que sites rastreiem sua localização física,
ask
: perguntar antes de permitir que sites rastreiem sua localização física.
O padrão é ask
.
O URL principal é o do documento que solicitou dados de local. O URL secundário é o URL do frame de nível superior, que pode ou não ser diferente do URL solicitante.
microphone
Permite que os sites acessem o microfone. Uma das seguintes opções:
allow
: permitir que sites acessem o microfone,
block
: não permitir que sites acessem o microfone,
ask
: perguntar quando um site quiser acessar o microfone.
O padrão é ask
.
O URL principal é o do documento que solicitou o acesso ao microfone. O URL secundário não é usado.
OBSERVAÇÃO: a configuração "permitir" não é válida se os dois padrões forem "'".
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
.
notifications
Define se os sites podem mostrar notificações na área de trabalho. Uma das opções abaixo:
allow
: permitir que sites mostrem notificações na área de trabalho,
block
: não permitir que 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 do documento que quer mostrar a notificação. O URL secundário não é usado.
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.
popups
Permitir que os sites mostrem pop-ups. Uma das 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.
unsandboxedPlugins
Obsoleto. Anteriormente, era possível controlar se os sites podiam executar plug-ins sem sandbox. No entanto, com a remoção do processo de intermediário 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.