chrome.windows

refresh date: 2026-09-25 robots: noindex

Descrição

Use a API chrome.windows para interagir com as janelas do navegador. Use essa API para criar, modificar e reorganizar janelas no navegador.

Manifesto

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

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

A janela atual

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

A janela atual é aquela que contém o código em execução. É importante perceber que isso 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 o arquivo HTML contenha uma chamada para tabs.query(). A janela atual é aquela que contém a página que fez a chamada, independentemente de qual seja a janela mais alta.

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

Exemplos

Duas janelas, cada uma com uma guia

Para testar essa API, instale o exemplo de API do Windows do repositório chrome-extension-samples.

Tipos

CreateType

Chrome 44+

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

Enumeração

"normal"
Especifica a janela como padrão.

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

"panel"
Especifica a janela como um painel.

QueryOptions

Chrome 88+

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 só vão conter 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 é filtrado com base no tipo. Se não for definido, o filtro padrão será ['normal', 'popup'].

Window

Propriedades

  • alwaysOnTop

    booleano

    Se a janela está definida para ficar sempre em primeiro plano.

  • foco

    booleano

    Se a janela está em foco no momento.

  • altura

    número optional

    A altura da janela, incluindo o frame, em pixels. Em algumas circunstâncias, uma janela pode não receber uma propriedade height. Por exemplo, ao consultar janelas fechadas na API sessions.

  • ID

    número optional

    O ID da janela. Os IDs de janela são exclusivos em uma sessão do navegador. Em algumas circunstâncias, uma janela pode não receber uma propriedade ID. Por exemplo, ao consultar janelas usando a API sessions, um ID de sessão pode estar presente.

  • incognito

    booleano

    Se a janela é anônima.

  • esquerda

    número optional

    O deslocamento da janela em relação à borda esquerda da tela, em pixels. Em algumas circunstâncias, uma janela pode não receber uma propriedade left. Por exemplo, ao consultar janelas fechadas na API sessions.

  • sessionId

    string opcional

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

  • estado

    WindowState opcional

    O estado da janela do navegador.

  • tabs

    Tab[] opcional

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

  • superior

    número optional

    O deslocamento da janela em relação à borda superior da tela, em pixels. Em algumas circunstâncias, uma janela pode não receber uma propriedade top. Por exemplo, ao consultar janelas fechadas na API sessions.

  • tipo

    WindowType opcional

    O tipo de janela do navegador.

  • largura

    número optional

    A largura da janela, incluindo o frame, em pixels. Em algumas circunstâncias, uma janela pode não receber uma propriedade width. Por exemplo, ao consultar janelas fechadas na API sessions.

WindowState

Chrome 44+

O estado da janela do navegador. Em algumas circunstâncias, uma janela pode não receber uma propriedade state. Por exemplo, ao consultar janelas fechadas na API sessions.

Enumeração

"normal"
Estado normal da janela (não minimizada, maximizada ou em tela cheia).

"minimized"
Estado de janela minimizada.

"maximized"
Estado de janela maximizada.

"fullscreen"
Estado de janela em tela cheia.

WindowType

Chrome 44+

O tipo de janela do navegador. Em algumas circunstâncias, uma janela pode não ter uma propriedade type atribuída. Por exemplo, ao consultar janelas fechadas na API sessions.

Enumeração

"normal"
Uma janela normal do navegador.

"popup"
Um pop-up do navegador.

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

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

"devtools"
Uma janela de ferramentas para desenvolvedores.

Propriedades

WINDOW_ID_CURRENT

O valor windowId que representa a janela atual.

Valor

-2

WINDOW_ID_NONE

O valor 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,
): Promise<Window | undefined>

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

Parâmetros

  • createData

    objeto optional

    • foco

      booleano opcional

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

    • altura

      número optional

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

    • incognito

      booleano opcional

      Se a nova janela deve ser anônima.

    • esquerda

      número optional

      O número de pixels para posicionar a nova janela a partir da borda esquerda da tela. Se não for especificado, 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.

    • estado

      WindowState opcional

      Chrome 44+

      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 optional

      O ID da guia que será adicionada à nova janela.

    • superior

      número optional

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

    • tipo

      CreateType opcional

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

    • url

      string | string[] opcional

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

    • largura

      número optional

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

  • callback

    função optional

    O parâmetro callback é semelhante a: 

    (window?: Window) => void

    • janela

      Janela opcional

      Contém detalhes sobre a janela criada.

Retorna

  • Promise<Window | undefined>

    Chrome 88+

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

get()

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

Recebe detalhes sobre uma janela.

Parâmetros

  • windowId

    número

  • queryOptions

    QueryOptions opcional

    Chrome 88+
  • callback

    função optional

    O parâmetro callback é semelhante a: 

    (window: Window) => void

Retorna

  • Promise<Window>

    Chrome 88+

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

getAll()

Promessa 
chrome.windows.getAll(
  queryOptions?: QueryOptions,
  callback?: function,
): Promise<Window[]>

Recebe todas as janelas.

Parâmetros

  • queryOptions

    QueryOptions opcional

    Chrome 88+
  • callback

    função optional

    O parâmetro callback é semelhante a: 

    (windows: Window[]) => void

Retorna

  • Promise<Window[]>

    Chrome 88+

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

getCurrent()

Promessa 
chrome.windows.getCurrent(
  queryOptions?: QueryOptions,
  callback?: function,
): Promise<Window>

Recebe a janela atual.

Parâmetros

  • queryOptions

    QueryOptions opcional

    Chrome 88+
  • callback

    função optional

    O parâmetro callback é semelhante a: 

    (window: Window) => void

Retorna

  • Promise<Window>

    Chrome 88+

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

getLastFocused()

Promessa 
chrome.windows.getLastFocused(
  queryOptions?: QueryOptions,
  callback?: function,
): Promise<Window>

Recebe a janela que estava em foco mais recentemente, normalmente a janela "em cima".

Parâmetros

  • queryOptions

    QueryOptions opcional

    Chrome 88+
  • callback

    função optional

    O parâmetro callback é semelhante a: 

    (window: Window) => void

Retorna

  • Promise<Window>

    Chrome 88+

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

remove()

Promessa 
chrome.windows.remove(
  windowId: number,
  callback?: function,
): Promise<void>

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

Parâmetros

  • windowId

    número

  • callback

    função optional

    O parâmetro callback é semelhante a: 

    () => void

Retorna

  • Promessa<void>

    Chrome 88+

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

update()

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

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

Parâmetros

  • windowId

    número

  • 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, 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 drawAttention anterior.

    • foco

      booleano opcional

      Se for true, traz a janela para frente. Não pode ser combinado com o estado "minimized". Se for false, traz a próxima janela na ordem Z para a frente. Não pode ser combinado com o estado "fullscreen" ou "maximized".

    • altura

      número optional

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

    • esquerda

      número optional

      O deslocamento da borda esquerda da tela para mover a janela em pixels. Esse valor é ignorado para painéis.

    • estado

      WindowState opcional

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

    • superior

      número optional

      O deslocamento da borda de cima da tela para mover a janela em pixels. Esse valor é ignorado para painéis.

    • largura

      número optional

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

  • callback

    função optional

    O parâmetro callback é semelhante a: 

    (window: Window) => void

Retorna

  • Promise<Window>

    Chrome 88+

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

Eventos

onBoundsChanged

Chrome 86+ 
chrome.windows.onBoundsChanged.addListener(
  callback: function,
)

Disparado quando uma janela é redimensionada. Esse evento só é enviado quando os novos limites são confirmados, e não para mudanças em andamento.

Parâmetros

  • callback

    função

    O parâmetro callback é semelhante a: 

    (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 é semelhante a: 

    (window: Window) => void

    • janela

      Janela

      Detalhes da janela criada.

  • filtros

    objeto optional

    • windowTypes

      WindowType[]

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

onFocusChanged

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

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

Parâmetros

  • callback

    função

    Chrome 46 ou mais recente

    O parâmetro callback é semelhante a: 

    (windowId: number) => void

    • windowId

      número

      ID da janela que acabou de receber o foco.

  • filtros

    objeto optional

    • windowTypes

      WindowType[]

      Condições que o tipo de janela que está sendo removido precisa atender. Por padrão, ele satisfaz ['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 é semelhante a: 

    (windowId: number) => void

    • windowId

      número

      ID da janela removida.

  • filtros

    objeto optional

    • windowTypes

      WindowType[]

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