chrome.windows

Descrição

Use a API chrome.windows para interagir com as janelas do navegador. Você pode usar esta API para criar, modificar e reorganizar janelas no navegador.

Permissões

Quando solicitado, um windows.Window contém uma matriz de objetos tabs.Tab. Declare a permissão "tabs" no manifesto se você precisar de acesso às propriedades url, pendingUrl, title ou favIconUrl de tabs.Tab. Exemplo:

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

Conceitos e uso

Janela atual

Muitas funções no sistema de extensão usam um argumento windowId opcional, que tem como padrão a janela atual.

A janela atual é a janela que contém o código que está em execução no momento. É importante perceber que ela pode ser diferente da janela superior ou em foco.

Por exemplo, digamos que uma extensão crie algumas guias ou janelas de um único arquivo HTML e que esse arquivo HTML contenha uma chamada para tabs.query(). A janela atual é aquela que contém a página que fez a chamada, independente de qual seja a janela superior.

No caso de service workers, o valor da janela atual retorna para a última janela ativa. Em algumas circunstâncias, pode não haver uma janela atual para páginas de segundo plano.

Exemplos

Para testar essa API, instale o exemplo da API Windows (link em inglês) no repositório chrome-extension-samples.

Duas janelas, cada uma com uma guia
Duas janelas, cada uma com uma guia.

Tipos

CreateType

Chrome 44 ou mais recente

Especifica o tipo de janela do navegador que será criada. O uso do elemento "panel" foi descontinuado e está disponível apenas para extensões na lista de permissões no Chrome OS.

Tipo enumerado

"normal"
especifica a janela como padrão.

"pop-up"
Especifica a janela como uma janela pop-up.

"panel"
Especifica a janela como um painel.

QueryOptions

Chrome 88 ou mais recente

Propriedades

  • populate

    booleano opcional

    Se for verdadeiro, o objeto windows.Window terá uma propriedade tabs que contém uma lista dos objetos tabs.Tab. Os objetos Tab vão conter apenas as propriedades url, pendingUrl, title e favIconUrl se o arquivo de manifesto da extensão incluir a permissão "tabs".

  • windowTypes

    WindowType[] opcional

    Se definido, o windows.Window retornado será filtrado com base no tipo. Se não for definido, o filtro padrão será definido como ['normal', 'popup'].

Window

Propriedades

  • alwaysOnTop

    boolean

    Se a janela está definida para ficar sempre na parte de cima.

  • foco

    boolean

    Se a janela é a janela em foco no momento.

  • altura

    número opcional

    Indica a altura da janela, incluindo o frame, em pixels. Em alguns casos, uma janela pode não receber uma propriedade height. Por exemplo, ao consultar janelas fechadas pela API sessions.

  • id

    número opcional

    ID da janela. Os IDs de janela são exclusivos dentro de uma sessão do navegador. Em alguns casos, uma janela pode não receber uma propriedade ID. Por exemplo, ao consultar janelas usando a API sessions. Nesse caso, um ID de sessão pode estar presente.

  • navegação anônima

    boolean

    Se a janela é anônima.

  • à esquerda

    número opcional

    O deslocamento da janela a partir da borda esquerda da tela em pixels. Em alguns casos, uma janela pode não receber uma propriedade left. Por exemplo, ao consultar janelas fechadas pela API sessions.

  • sessionId

    string opcional

    O ID da sessão usado para identificar de forma exclusiva uma janela, extraído da API sessions.

  • state

    WindowState opcional

    O estado desta janela do navegador.

  • guias

    Tab[] opcional

    Matriz de objetos tabs.Tab que representam as guias atuais na janela.

  • superior

    número opcional

    O deslocamento da janela a partir da borda superior da tela em pixels. Em alguns casos, uma janela pode não receber uma propriedade top. Por exemplo, ao consultar janelas fechadas pela API sessions.

  • digitar

    WindowType (opcional)

    O tipo de janela do navegador.

  • largura

    número opcional

    Indica a largura da janela, incluindo o frame, em pixels. Em alguns casos, uma janela pode não receber uma propriedade width. Por exemplo, ao consultar janelas fechadas pela API sessions.

WindowState

Chrome 44 ou mais recente

O estado desta janela do navegador. Em alguns casos, uma janela pode não receber uma propriedade state. Por exemplo, ao consultar janelas fechadas pela API sessions.

Tipo enumerado

"normal"
Estado de janela normal (não minimizado, maximizado ou tela cheia).

"minimizado"
estado da janela minimizada.

"maximizado"
Estado da janela maximizado.

"fullscreen"
Estado da janela em tela cheia.

"locked-fullscreen"
Estado da janela de tela cheia bloqueada. Não é possível sair desse estado de tela cheia por ação do usuário e só está disponível para extensões da lista de permissões no ChromeOS.

WindowType

Chrome 44 ou mais recente

O tipo de janela do navegador. Em alguns casos, uma janela pode não receber uma propriedade type. Por exemplo, ao consultar janelas fechadas pela API sessions.

Tipo enumerado

"normal"
Uma janela normal do navegador.

"pop-up"
Um pop-up do navegador.

"panel"
Descontinuado nesta API. Uma janela em estilo de painel do app do Chrome. As extensões só podem ver as próprias janelas do painel.

"app"
Descontinuado nesta API. Uma janela do app do Chrome. As extensões só podem ver as próprias janelas do app.

"devtools"
Uma janela de Ferramentas para desenvolvedores.

Propriedades

WINDOW_ID_CURRENT

O valor de windowId que representa a janela atual.

Valor

-2

WINDOW_ID_NONE

O valor de windowId que representa a ausência de uma janela do navegador Chrome.

Valor

1

Métodos

create()

Promessa 
chrome.windows.create(
  createData?: object,
  callback?: function,
)

Cria (abre) uma nova janela do navegador com qualquer tamanho, posição ou URL padrão opcionais fornecidos.

Parâmetros

  • createData

    objeto opcional

    • foco

      booleano opcional

      Se for true, abre uma janela ativa. Se for false, abre uma janela inativa.

    • altura

      número opcional

      A altura em pixels da nova janela, incluindo o frame. Se não for especificado, o padrão será uma altura natural.

    • navegação anônima

      booleano opcional

      Se a nova janela deve ser uma janela anônima.

    • à esquerda

      número opcional

      O número de pixels para posicionar a nova janela a partir da borda esquerda da tela. Se não for especificada, a nova janela será deslocada naturalmente da última janela em foco. Esse valor é ignorado para painéis.

    • setSelfAsOpener

      booleano opcional

      Chrome 64 ou mais recente

      Se for true, o "window.opener" da janela recém-criada será definido como o autor da chamada e estará na mesma unidade de contextos de navegação relacionados que o autor da chamada.

    • state

      WindowState opcional

      Chrome 44 ou mais recente

      O estado inicial da janela. Os estados minimized, maximized e fullscreen não podem ser combinados com left, top, width ou height.

    • tabId

      número opcional

      O ID da guia a ser adicionada à nova janela.

    • superior

      número opcional

      O número de pixels para posicionar a nova janela a partir da borda superior da tela. Se não for especificada, a nova janela será deslocada naturalmente da última janela em foco. Esse valor é ignorado para painéis.

    • digitar

      CreateType opcional

      Especifica o tipo de janela do navegador que será criada.

    • url

      string|string[] optional

      Um URL ou matriz de URLs a serem abertos como guias na janela. Os URLs totalmente qualificados precisam incluir um esquema, como "http://www.google.com.br", não "www.google.com.br". Os URLs não totalmente qualificados são considerados relativos na extensão. O padrão é a página "Nova guia".

    • largura

      número opcional

      A largura em pixels da nova janela, incluindo o frame. Se não for especificado, o padrão será uma largura natural.

  • callback

    função optional

    O parâmetro callback tem esta aparência: 

    (window?: Window)=>void

    • janela

      Janela opcional

      Contém detalhes sobre a janela criada.

Retorna

  • Promessa<Janela|indefinida>

    Chrome 88 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()

Promessa 
chrome.windows.get(
  windowId: number,
  queryOptions?: QueryOptions,
  callback?: function,
)

Recebe detalhes sobre uma janela.

Parâmetros

  • windowId

    number

  • queryOptions

    QueryOptions opcional

    Chrome 88 ou mais recente
  • callback

    função optional

    O parâmetro callback tem esta aparência: 

    (window: Window)=>void

Retorna

  • Promise<Window>

    Chrome 88 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.

getAll()

Promessa 
chrome.windows.getAll(
  queryOptions?: QueryOptions,
  callback?: function,
)

Extrai todas as janelas.

Parâmetros

  • queryOptions

    QueryOptions opcional

    Chrome 88 ou mais recente
  • callback

    função optional

    O parâmetro callback tem esta aparência: 

    (windows: Window[])=>void

Retorna

  • Promessa<janela[]>

    Chrome 88 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.

getCurrent()

Promessa 
chrome.windows.getCurrent(
  queryOptions?: QueryOptions,
  callback?: function,
)

Recebe a janela atual.

Parâmetros

  • queryOptions

    QueryOptions opcional

    Chrome 88 ou mais recente
  • callback

    função optional

    O parâmetro callback tem esta aparência: 

    (window: Window)=>void

Retorna

  • Promise<Window>

    Chrome 88 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.

getLastFocused()

Promessa 
chrome.windows.getLastFocused(
  queryOptions?: QueryOptions,
  callback?: function,
)

Recupera a janela que foi focada mais recentemente, normalmente a janela "acima".

Parâmetros

  • queryOptions

    QueryOptions opcional

    Chrome 88 ou mais recente
  • callback

    função optional

    O parâmetro callback tem esta aparência: 

    (window: Window)=>void

Retorna

  • Promise<Window>

    Chrome 88 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.

remove()

Promessa 
chrome.windows.remove(
  windowId: number,
  callback?: function,
)

Remove (fecha) uma janela e todas as guias dentro dela.

Parâmetros

  • windowId

    number

  • callback

    função optional

    O parâmetro callback tem esta aparência: 

    ()=>void

Retorna

  • Promise<void>

    Chrome 88 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.

update()

Promessa 
chrome.windows.update(
  windowId: number,
  updateInfo: object,
  callback?: function,
)

Atualiza as propriedades de uma janela. Especifique apenas as propriedades que serão alteradas. As propriedades não especificadas não foram alteradas.

Parâmetros

  • windowId

    number

  • updateInfo

    objeto

    • drawAttention

      booleano opcional

      Se for true, faz com que a janela seja exibida de uma maneira que chame a atenção do usuário para ela, sem mudar a janela em foco. O efeito dura até que o usuário mude o foco para a janela. Essa opção não terá efeito se a janela já estiver em foco. Defina como false para cancelar uma solicitação anterior de drawAttention.

    • foco

      booleano opcional

      Se for true, traz a janela para a frente. Não pode ser combinado com o estado "minimizado". Se for false, traz a próxima janela na ordem z para a frente; não pode ser combinada com o estado "tela cheia" ou "maximizada".

    • altura

      número opcional

      A altura para redimensionar a janela em pixels. Esse valor é ignorado para painéis.

    • à esquerda

      número opcional

      O deslocamento em pixels da borda esquerda da tela para onde a janela deve ser movida. Esse valor é ignorado para painéis.

    • state

      WindowState opcional

      O novo estado da janela. Os estados "minimizado", "maximizado" e "tela cheia" não podem ser combinados com "esquerda", "superior", "largura" ou "altura".

    • superior

      número opcional

      O deslocamento em pixels a partir da borda superior da tela para onde a janela será movida. Esse valor é ignorado para painéis.

    • largura

      número opcional

      A largura para redimensionar a janela em pixels. Esse valor é ignorado para painéis.

  • callback

    função optional

    O parâmetro callback tem esta aparência: 

    (window: Window)=>void

Retorna

  • Promise<Window>

    Chrome 88 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.

Eventos

onBoundsChanged

Chrome 86 ou mais recente 
chrome.windows.onBoundsChanged.addListener(
  callback: function,
)

Disparado quando uma janela é redimensionada. Este evento é distribuído somente quando os novos limites são confirmados, e não para alterações em andamento.

Parâmetros

  • callback

    função

    O parâmetro callback tem esta aparência: 

    (window: Window)=>void

onCreated

chrome.windows.onCreated.addListener(
  callback: function,
  filters?: object,
)

Disparado quando uma janela é criada.

Parâmetros

  • callback

    função

    Chrome 46 ou mais recente

    O parâmetro callback tem esta aparência: 

    (window: Window)=>void

    • janela

      Janela

      Detalhes da janela criada.

  • filtros

    objeto opcional

    • windowTypes

      WindowType[]

      Condições que o tipo de janela que está sendo criada precisa atender. Por padrão, atende a ['normal', 'popup'].

onFocusChanged

chrome.windows.onFocusChanged.addListener(
  callback: function,
  filters?: object,
)

Disparado quando a janela em foco é alterada. Retorna chrome.windows.WINDOW_ID_NONE se todas as janelas do Chrome tiverem perdido o foco. Observação:em alguns gerenciadores de janelas do Linux, WINDOW_ID_NONE é sempre enviado imediatamente antes da mudança de uma janela do Chrome para outra.

Parâmetros

  • callback

    função

    Chrome 46 ou mais recente

    O parâmetro callback tem esta aparência: 

    (windowId: number)=>void

    • windowId

      number

      ID da janela recém-focada.

  • filtros

    objeto opcional

    • windowTypes

      WindowType[]

      Condições a que o tipo de janela que está sendo removido precisa atender. Por padrão, atende a ['normal', 'popup'].

onRemoved

chrome.windows.onRemoved.addListener(
  callback: function,
  filters?: object,
)

Disparado quando uma janela é removida (fechada).

Parâmetros

  • callback

    função

    Chrome 46 ou mais recente

    O parâmetro callback tem esta aparência: 

    (windowId: number)=>void

    • windowId

      number

      ID da janela removida.

  • filtros

    objeto opcional

    • windowTypes

      WindowType[]

      Condições a que o tipo de janela que está sendo removido precisa atender. Por padrão, atende a ['normal', 'popup'].