chrome.types

Descrição

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

Configurações do Chrome

O tipo ChromeSetting fornece um conjunto comum de funções (get(), set() e clear()), bem como 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 entre 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 por janelas anônimas se não forem substituídas. Essas configurações são armazenadas no disco e permanecem em vigor até que sejam apagadas pela extensão aplicável ou até que ela seja desativada ou desinstalada.
incognito_persistent
As configurações definidas no escopo incognito_persistent se aplicam apenas a janelas anônimas. Para eles, elas substituim as configurações de regular. Essas configurações são armazenadas no disco e permanecem em vigor até que sejam limpadas pela extensão aplicável ou até que ela seja desativada ou desinstalada.
incognito_session_only
As configurações definidas no escopo incognito_session_only se aplicam apenas a janelas anônimas. Para eles, elas substituem as configurações de regular e incognito_persistent. Essas configurações não são armazenadas no disco e são limpas quando a última janela anônima é fechada. Eles só podem ser definidos 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 indica a lista, as políticas podem substituir todas as alterações especificadas com sua extensão. É possível usar a função get() para determinar se a extensão é capaz de fornecer uma configuração ou se essa configuração seria substituída.

Conforme discutido anteriormente, o Chrome permite o uso de 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 pode 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 só vão ser válidas 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 pelas extensões instaladas anteriormente.

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

Tipos

ChromeSetting

Uma interface que permite acesso a uma configuração do navegador Chrome. Consulte accessibilityFeatures para conferir um exemplo.

Propriedades

  • onChange

    Evento<functionvoid>

    Disparado depois que a configuração é alterada.

    A função onChange.addListener tem esta aparência: 

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

    • callback

      função

      O parâmetro callback tem esta aparência: 

      (details: object)=>void

      • detalhes

        objeto

        • incognitoSpecific

          booleano opcional

          Indica se o valor alterado é específico para a sessão anônima. Esta propriedade estará presente apenas se o usuário tiver ativado a extensão no modo de navegação anônima.

        • levelOfControl

          LevelOfControl

          Nível de controle da configuração.

        • valor

          T

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

  • limpar

    void

    Promessa

    Apaga a configuração e restaura qualquer valor padrão.

    A função clear tem esta aparência: 

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

    • detalhes

      objeto

      Qual configuração limpar.

    • callback

      função optional

      O parâmetro callback tem esta aparência: 

      ()=>void

    • retorna

      Promise<void>

      Chrome 96 ou mais recente

      Promessas são compatíveis com o Manifest V3 e versões mais recentes, mas 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 que é passado para o callback.

  • get

    void

    Promessa

    Extrai o valor de uma configuração.

    A função get tem esta aparência: 

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

    • detalhes

      objeto

      Qual configuração considerar.

      • navegação anônima

        booleano opcional

        Define se o valor que se aplica à sessão anônima deve ser retornado (falso padrão).

    • callback

      função optional

      O parâmetro callback tem esta aparência: 

      (details: object)=>void

      • detalhes

        objeto

        Detalhes do valor efetivo no momento.

        • incognitoSpecific

          booleano opcional

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

        • levelOfControl

          LevelOfControl

          Nível de controle da configuração.

        • valor

          T

          O valor da configuração.

    • retorna

      Promise<object>

      Chrome 96 ou mais recente

      Promessas são compatíveis com o Manifest V3 e versões mais recentes, mas 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 que é passado para o callback.

  • set

    void

    Promessa

    Define o valor de uma configuração.

    A função set tem esta aparência: 

    (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 tipo diferente.

    • callback

      função optional

      O parâmetro callback tem esta aparência: 

      ()=>void

    • retorna

      Promise<void>

      Chrome 96 ou mais recente

      Promessas são compatíveis com o Manifest V3 e versões mais recentes, mas 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 que é passado para o callback.

ChromeSettingScope

Chrome 44 ou mais recente

O escopo da ChromeSetting. Uma

  • regular: configuração do perfil normal (herdado pelo perfil de navegação anônima se não for substituído em outro lugar);
  • regular\_only: configuração apenas para o perfil normal (não herdado pelo perfil de navegação anônima);
  • incognito\_persistent: configuração do perfil de navegação anônima que sobrevive às reinicializações do navegador (substitui as preferências normais).
  • incognito\_session\_only: configuração do perfil de navegação anônima que só pode ser definida durante uma sessão anônima e é excluída quando a sessão é encerrada (modifica preferências regulares e de navegação anônima).

Tipo enumerado

"regular_only"

LevelOfControl

Chrome 44 ou mais recente

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

Tipo enumerado

"not_controllable"

"controllable_by_this_extension"