chrome.types

refresh date: 2026-09-25 robots: noindex

Descrição

A API chrome.types contém declarações de tipo para o Chrome.

Configurações do Chrome

O protótipo ChromeSetting fornece um conjunto comum de funções (get(), set() e clear()), além de um editor de eventos (onChange) para as configurações do navegador Chrome. Os exemplos de configurações de proxy demonstram como essas funções devem ser usadas.

Escopo e ciclo de vida

O Chrome distingue três escopos diferentes de configurações do navegador:

regular
As configurações definidas no escopo regular se aplicam às janelas normais do navegador e são herdadas pelas janelas anônimas, se não forem substituídas. Essas configurações são armazenadas no disco e permanecem em vigor até serem limpas pela extensão de controle ou até que ela seja desativada ou desinstalada.
incognito_persistent
As configurações definidas no escopo incognito_persistent se aplicam apenas às janelas anônimas. Para isso, elas substituem as configurações de regular. Essas configurações são armazenadas no disco e permanecem em vigor até que sejam limpas pela extensão de controle ou que ela seja desativada ou desinstalada.
incognito_session_only
As configurações definidas no escopo incognito_session_only se aplicam apenas às janelas anônimas. Para isso, elas substituem as configurações de regular e incognito_persistent. Essas configurações não são armazenadas no disco e são apagadas quando a última janela anônima é fechada. Elas só podem ser definidas quando pelo menos uma janela anônima está aberta.

Precedência

O Chrome gerencia as configurações em diferentes camadas. A lista a seguir descreve as camadas que podem influenciar as configurações efetivas, em ordem crescente de precedência.

  1. Configurações do sistema fornecidas pelo sistema operacional
  2. Parâmetros de linha de comando
  3. Configurações fornecidas por extensões
  4. Políticas

Como a lista indica, as políticas podem anular as mudanças especificadas com a extensão. Use a função get() para determinar se a extensão é capaz de fornecer uma configuração ou se ela será substituída.

Como discutido acima, o Chrome permite usar configurações diferentes para janelas normais e anônimas. O exemplo a seguir ilustra o comportamento. Suponha que nenhuma política substitua as configurações e que uma extensão possa definir configurações para janelas normais (R) e configurações para janelas anônimas (I).

  • Se apenas (R) estiver definido, essas configurações serão válidas para janelas normais e anônimas.
  • Se apenas (I) estiver definido, essas configurações serão válidas apenas para janelas anônimas. As janelas normais usam as configurações determinadas pelas camadas inferiores (opções de linha de comando e configurações do sistema).
  • Se (R) e (I) estiverem definidos, as respectivas configurações serão usadas para janelas normais e anônimas.

Se duas ou mais extensões quiserem definir a mesma configuração com valores diferentes, a extensão instalada mais recentemente terá precedência sobre as outras. Se a extensão instalada mais recentemente definir apenas (I), as configurações das janelas normais poderão ser definidas por extensões instaladas anteriormente.

O valor efetivo de uma configuração é o que resulta da consideração das regras de precedência. Ele é usado pelo Chrome.

Tipos

ChromeSetting

Uma interface que permite acessar uma configuração do navegador Chrome. Consulte accessibilityFeatures para ver um exemplo.

Propriedades

  • onChange

    Event<functionvoidvoid>

    Acionado após as mudanças na configuração.

    A função onChange.addListener é semelhante a: 

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

    • callback

      função

      O parâmetro callback é semelhante a: 

      (details: object) => void

      • detalhes

        objeto

        • incognitoSpecific

          booleano opcional

          Se o valor que mudou é específico da sessão de navegação anônima. Essa propriedade só estará presente se o usuário tiver ativado a extensão no modo de navegação anônima.

        • levelOfControl

          LevelOfControl

          O nível de controle da configuração.

        • valor

          T

          O valor da configuração após a mudança.

  • limpar

    void

    Promessa

    Limpa a configuração, restaurando qualquer valor padrão.

    A função clear é semelhante a: 

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

    • detalhes

      objeto

      Qual configuração limpar.

    • callback

      função optional

      O parâmetro callback é semelhante a: 

      () => void

    • retorna

      Promessa<void>

      Chrome 96 ou mais recente

      Chamado ao final da operação de limpeza.

      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 o valor de uma configuração.

    A função get é semelhante a: 

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

    • detalhes

      objeto

      Qual configuração considerar.

      • incognito

        booleano opcional

        Se o valor que se aplica à sessão de navegação anônima deve ser retornado (o padrão é falso).

    • callback

      função optional

      O parâmetro callback é semelhante a: 

      (details: object) => void

      • detalhes

        objeto

        Detalhes do valor em vigor.

        • incognitoSpecific

          booleano opcional

          Se o valor efetivo é específico da sessão de navegação anônima. Essa propriedade só estará presente se a propriedade incognito no parâmetro details de get() for verdadeira.

        • levelOfControl

          LevelOfControl

          O nível de controle da configuração.

        • valor

          T

          O valor da configuração.

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

  • set

    void

    Promessa

    Define o valor de uma configuração.

    A função set é semelhante a: 

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

    • detalhes

      objeto

      Qual configuração mudar.

      • escopo

        ChromeSettingScope opcional

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

      • valor

        T

        O valor da configuração. Cada configuração tem um tipo de valor específico, que é descrito junto com a configuração. Uma extensão não deve definir um valor de um tipo diferente.

    • callback

      função optional

      O parâmetro callback é semelhante a: 

      () => void

    • retorna

      Promessa<void>

      Chrome 96 ou mais recente

      Chamado na conclusão da operação de definição.

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

ChromeSettingScope

Chrome 44+

O escopo da ChromeSetting. Uma

  • 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).
  • regular\_only: configuração apenas para o perfil normal (não herdada pelo perfil de navegação anônima).
  • incognito\_persistent: configuração para o perfil anônimo que sobrevive às reinicializações do navegador (substitui as preferências normais).
  • 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 preferências regular e incognito_persistent).

Enumeração

"regular"

"regular_only"

"incognito_persistent"

"incognito_session_only"

LevelOfControl

Chrome 44+

Uma

  • not\_controllable: não pode ser controlado por nenhuma extensão
  • controlled\_by\_other\_extensions: controlado por extensões com maior precedência
  • controllable\_by\_this\_extension: pode ser controlado por esta extensão
  • controlled\_by\_this\_extension: controlado por esta extensão

Enumeração

"not_controllable"

"controlled_by_other_extensions"

"controllable_by_this_extension"

"controlled_by_this_extension"