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 mais geral, as configurações de conteúdo permitem que você personalize o comportamento do Chrome para cada site, e não globalmente.
Permissões
contentSettings
Declare a permissão "contentSettings"
no manifesto da sua 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 afetados por cada configuração de conteúdo. Por exemplo:
https://*.youtube.com/*
especifica youtube.com e todos os subdomínios dele. A sintaxe do conteúdo
de configuração de padrões é o mesmo usado para 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 totalmente especificado e não pode conter caracteres curinga. - Diferente dos padrões de correspondência, os padrões de configuração de conteúdo podem especificar um número de porta. Se uma porta for especificado, o padrão corresponderá apenas a sites com essa porta. Se nenhum número de porta for especificado, o padrão corresponde a todas as portas.
Precedência do padrão
Quando mais de uma regra de configuração de conteúdo se aplicar a um determinado site, a regra com a configuração de conteúdo tem precedência.
Por exemplo, os seguintes padrões são ordenados por precedência:
https://www.example.com/*
https://*.example.com/*
(correspondente a example.com e todos os subdomínios)<all_urls>
(correspondente 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 é mais específico do que outro em uma parte, mas menos específico em outra, as diferentes partes são verificadas na seguinte ordem: nome do host, esquema, porta. Por exemplo, o 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, ele 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 de conteúdo aplicar depende do tipo de conteúdo.
Por exemplo, para contentSettings.notifications
, as configurações são baseadas no URL mostrado no
omnibox. Esse URL é chamado de URL principal, URL.
Alguns tipos de conteúdo podem levar outros URLs em consideração. Por exemplo, se um site tem permissão para
definido, um contentSettings.cookies
é decidido com base no URL da solicitação HTTP (que é o
URL principal nesse caso), assim como o URL mostrado na omnibox (chamado de "secundário"
URL).
Se várias regras tiverem padrões primários e secundários, aquela com a regra mais específica tem precedência. Se várias regras tiverem o mesmo padrão principal, a regra com a um padrão secundário mais específico terá precedência. Por exemplo, a seguinte lista de pares de padrões primário/secundário são ordenados 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> |
Identificadores de recursos
Os identificadores de recursos permitem definir 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 recursos é contentSettings.plugins
,
em que um identificador de recurso identifica um plug-in específico. Ao aplicar as configurações de conteúdo, primeiro o
as configurações do plug-in específico estão verificadas. Se nenhuma configuração for encontrada para o
as configurações gerais de conteúdo dos 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 tem 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.
Você pode obter uma lista de identificadores de recurso para um tipo de conteúdo chamando 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 em chrome-extension-samples repositório de dados.
Tipos
AutoVerifyContentSetting
Enumeração
"permitir"
"block"
CameraContentSetting
Enumeração
"permitir"
"block"
"perguntar"
ClipboardContentSetting
Enumeração
"permitir"
"block"
"perguntar"
ContentSetting
Propriedades
-
limpar
void
PromessaLimpa todas as regras de configuração de conteúdo definidas por esta extensão.
A função
clear
tem esta aparência:(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 esta aparência:() => void
-
retorna
Promessa<void>
Chrome 96 ou versão mais recenteO Manifesto V3 e versões mais recentes oferecem suporte a promessas, mas callbacks são fornecidos para a compatibilidade com versões anteriores. Não é possível usar ambos na mesma chamada de função. A promessa é resolvida com o mesmo tipo passado ao retorno de chamada.
-
-
get
void
PromessaExtrai a configuração de conteúdo atual para um determinado par de URLs.
A função
get
tem esta aparência:(details: object, callback?: function) => {...}
-
detalhes
objeto
-
navegação anônima
booleano opcional
Define se as configurações de conteúdo para uma sessão de navegação anônima serão verificadas. (o padrão é "false")
-
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 precisam 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 eles usam URLs secundários.
-
-
callback
função opcional
O parâmetro
callback
tem esta aparência:(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 possíveis valores.
-
-
-
retorna
Promise<object>
Chrome 96 ou versão mais recenteO Manifesto V3 e versões mais recentes oferecem suporte a promessas, mas callbacks são fornecidos para a compatibilidade com versões anteriores. Não é possível usar ambos na mesma chamada de função. A promessa é resolvida com o mesmo tipo passado ao retorno de chamada.
-
-
getResourceIdentifiers
void
PromessaA função
getResourceIdentifiers
tem esta aparência:(callback?: function) => {...}
-
callback
função opcional
O parâmetro
callback
tem esta aparência:(resourceIdentifiers?: ResourceIdentifier[]) => void
-
resourceIdentifiers
ResourceIdentifier[] opcional
Uma lista de identificadores de recurso para este tipo de conteúdo, ou
undefined
se o tipo de conteúdo não usar identificadores de recurso.
-
-
retorna
Promessa<ResourceIdentifier[]>
Chrome 96 ou versão mais recenteO Manifesto V3 e versões mais recentes oferecem suporte a promessas, mas callbacks são fornecidos para a compatibilidade com versões anteriores. Não é possível usar ambos na mesma chamada de função. A promessa é resolvida com o mesmo tipo passado ao retorno de chamada.
-
-
set
void
PromessaAplica uma nova regra de configuração de conteúdo.
A função
set
tem esta aparência:(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. O padrão é corresponder a todos os URLs. Para detalhes 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 esta regra. Consulte a descrição dos objetos ContentSetting individuais para ver os possíveis valores.
-
-
callback
função opcional
O parâmetro
callback
tem esta aparência:() => void
-
retorna
Promessa<void>
Chrome 96 ou versão mais recenteO Manifesto V3 e versões mais recentes oferecem suporte a promessas, mas callbacks são fornecidos para a compatibilidade com versões anteriores. Não é possível usar ambos na mesma chamada de função. A promessa é resolvida com o mesmo tipo passado ao retorno de chamada.
-
CookiesContentSetting
Enumeração
"permitir"
"block"
"session_only"
FullscreenContentSetting
Valor
"permitir"
ImagesContentSetting
Enumeração
"permitir"
"block"
JavascriptContentSetting
Enumeração
"permitir"
"block"
LocationContentSetting
Enumeração
"permitir"
"block"
"perguntar"
MicrophoneContentSetting
Enumeração
"permitir"
"block"
"perguntar"
MouselockContentSetting
Valor
"permitir"
MultipleAutomaticDownloadsContentSetting
Enumeração
"permitir"
"block"
"perguntar"
NotificationsContentSetting
Enumeração
"permitir"
"block"
"perguntar"
PluginsContentSetting
Valor
"block"
PopupsContentSetting
Enumeração
"permitir"
"block"
PpapiBrokerContentSetting
Valor
"block"
ResourceIdentifier
O único tipo de conteúdo que usa identificadores de recurso é contentSettings.plugins
. Para mais informações, consulte Identificadores de recursos.
Propriedades
-
descrição
string opcional
Uma descrição legível do recurso.
-
id
string
O identificador de recurso para o tipo de conteúdo fornecido.
Scope
O escopo da ContentSetting. Um de
regular
: configuração para o perfil normal (que é herdado pelo perfil de navegação anônima se não for substituído em outro lugar),
incognito\_session\_only
: configuração para 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 de navegação anônima termina (substitui as configurações normais).
Enumeração
"normal"
"anonymous_session_only"
Propriedades
automaticDownloads
Define se os sites podem fazer o download de vários arquivos automaticamente. Um de
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.
autoVerify
Define se os sites podem usar a API Private State Tokens. Um de
allow
: permitir que os sites usem a API Private State Tokens.
block
: impede que os sites usem 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 .
Tipo
camera
Define se os sites podem acessar a câmera. Um de
allow
: permite que os sites acessem a câmera.
block
: não permite 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 regra "allow" não será válida se ambos os padrões forem ''.
Tipo
clipboard
Define se os sites podem acessar a área de transferência usando recursos avançados da API Async Clipboard. "Avançado" os recursos incluem qualquer coisa além da criação de formatos integrados após um gesto do usuário, ou seja, a capacidade de ler, escrever formatos personalizados e a capacidade de escrever sem um gesto do usuário. Um de
allow
: permitir que os sites usem recursos avançados de á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
cookies
Define se cookies e outros dados locais serão definidos pelos sites. Um de
allow
: aceitar cookies,
block
: bloquear cookies,
session\_only
: aceita cookies apenas para a sessão atual.
O padrão é allow
.
O URL principal é aquele que representa a origem do cookie. O URL secundário é o URL do frame de nível superior.
Tipo
fullscreen
Obsoleto. Não tem mais efeito. A permissão para tela cheia agora é concedida automaticamente para todos os sites. O valor é sempre allow
.
Tipo
images
Indica se as imagens serão mostradas. Um de
allow
: mostrar imagens,
block
: não mostra 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
javascript
Define se o JavaScript será executado. Um de
allow
: executa JavaScript,
block
: não execute JavaScript.
O padrão é allow
.
O URL principal é o URL do frame de nível superior. O URL secundário não é usado.
Tipo
location
Define se a geolocalização será permitida. Um de
allow
: permite que os sites rastreiem sua localização física.
block
: não permite que os sites rastreiem sua localização física.
ask
: pergunte antes de permitir que sites rastreiem sua localização física.
O padrão é ask
.
O URL principal é o URL do documento que solicitou os dados de localização. O URL secundário é o URL do frame de nível superior (que pode ou não ser diferente do URL solicitante).
Tipo
microphone
Define se os sites podem acessar o microfone. Um de
allow
: permite 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 regra "allow" não será válida se ambos os padrões forem ''.
Tipo
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
notifications
Define se os sites podem mostrar notificações na área de trabalho. Um de
allow
: permite 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 quer mostrar notificações na área de trabalho.
O padrão é ask
.
O URL principal é o URL do documento que deseja exibir a notificação. O URL secundário não é usado.
Tipo
plugins
Obsoleto. Com a remoção do suporte ao Flash no Chrome 88, essa permissão não terá mais efeito. O valor é sempre block
. As chamadas para set()
e clear()
serão ignoradas.
Tipo
popups
Define se os sites podem mostrar pop-ups. Um de
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
unsandboxedPlugins
Obsoleto. Anteriormente, a permissão era controlada para permitir que os sites executassem plug-ins fora do sandbox. No entanto, com o processo de agente do Flash 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.