chrome.windows

Descrição

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

Permissões

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

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

Conceitos e uso

A janela atual

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

A janela atual é aquela que contém o código em execução. Está é 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 a partir de um único arquivo HTML e que a O arquivo HTML contém uma chamada para tabs.query(). A janela atual é a janela que contém o página que fez a chamada, não importa qual seja a janela superior.

No caso de service workers, o valor da janela atual volta para o último elemento ativo. janela. Em algumas circunstâncias, pode não haver uma janela atual para páginas de fundo.

Exemplos

Para testar essa API, instale o exemplo da API para Windows em chrome-extension-samples repositório de dados.

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

Tipos

CreateType

Chrome 44 ou superior

Especifica o tipo de janela do navegador a ser criado. "painel" foi descontinuado e está disponível apenas para extensões da lista de permissões atuais no Chrome OS.

Enumeração

"normal"
Especifica a janela como uma janela padrão.

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

"panel"
Especifica a janela como um painel.

QueryOptions

Chrome 88 ou superior

Propriedades

  • populate

    booleano opcional

    Se verdadeiro, o objeto windows.Window tem uma propriedade tabs que contém uma lista dos objetos tabs.Tab. Os objetos Tab só terão 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

    booleano

    Indica se a janela está definida para estar sempre na parte superior.

  • foco

    booleano

    Se a janela é atualmente a janela em foco.

  • altura

    número opcional

    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 opcional

    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, caso em que um ID de sessão pode estar presente.

  • navegação anônima

    booleano

    Se a janela é anônima.

  • esquerda

    número opcional

    O deslocamento da janela da 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 exclusivamente uma janela, extraído da API sessions.

  • estado

    WindowState opcional

    O estado da 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 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 opcional

    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 ou superior

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 de janela normal (não minimizado, maximizado ou tela cheia).

"minimized"
Estado da janela minimizado.

"maximized"
Estado da janela maximizado.

"fullscreen"
Estado da janela em tela cheia.

"tela cheia bloqueada"
Estado da janela em tela cheia bloqueada. O usuário não pode sair desse estado de tela cheia. Ele está disponível apenas para extensões da lista de permissões no ChromeOS.

WindowType

Chrome 44 ou superior

O tipo de janela do navegador. Em algumas circunstâncias, uma janela pode não receber uma propriedade type. 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ó têm acesso às próprias janelas de painel.

"app"
Descontinuado nesta API. Uma janela do app do Chrome. As extensões só têm acesso às próprias janelas dos apps.

" DevTools"
Uma janela das Ferramentas para desenvolvedores.

Propriedades

WINDOW_ID_CURRENT

O valor de windowId que representa a janela atual.

Valor

Menos de 2

WINDOW_ID_NONE

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

Valor

Menos de 1

Métodos

create()

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

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

Parâmetros

  • createData

    objeto opcional

    • foco

      booleano opcional

      Se true, abre uma janela ativa. Se 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 nos painéis.

    • setSelfAsOpener

      booleano opcional

      Chrome 64 ou superior

      Se true, o "window.opener" da janela recém-criada seja definido para o autor da chamada e esteja na mesma unidade de contextos de navegação relacionados que ele.

    • estado

      WindowState opcional

      Chrome 44 ou superior

      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 nos painéis.

    • tipo

      CreateType opcional

      Especifica o tipo de janela do navegador a ser criado.

    • url

      string | string[] opcional

      Um URL ou matriz de URLs que serão abertos como guias na janela. Os URLs totalmente qualificados precisam incluir um esquema, por exemplo, "http://www.google.com.br", não "www.google.com.br". URLs não totalmente qualificados são considerados relativos dentro da 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 opcional

    O parâmetro callback tem esta aparência: 

    (window?: Window) => void

    • janela

      Janela opcional

      Contém detalhes sobre a janela criada.

Retorna

  • Promise<Window | indefinido>

    Chrome 88 ou superior

    O 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()

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

Extrai detalhes sobre uma janela.

Parâmetros

  • windowId

    number

  • queryOptions

    QueryOptions opcional

    Chrome 88 ou superior
  • callback

    função opcional

    O parâmetro callback tem esta aparência: 

    (window: Window) => void

Retorna

  • Promise<Window>

    Chrome 88 ou superior

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

getAll()

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

Recebe todas as janelas.

Parâmetros

  • queryOptions

    QueryOptions opcional

    Chrome 88 ou superior
  • callback

    função opcional

    O parâmetro callback tem esta aparência: 

    (windows: Window[]) => void

Retorna

  • Promise<Window[]>

    Chrome 88 ou superior

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

getCurrent()

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

Recebe a janela atual.

Parâmetros

  • queryOptions

    QueryOptions opcional

    Chrome 88 ou superior
  • callback

    função opcional

    O parâmetro callback tem esta aparência: 

    (window: Window) => void

Retorna

  • Promise<Window>

    Chrome 88 ou superior

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

getLastFocused()

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

Acessa a janela que foi focada mais recentemente — normalmente a janela "em cima".

Parâmetros

  • queryOptions

    QueryOptions opcional

    Chrome 88 ou superior
  • callback

    função opcional

    O parâmetro callback tem esta aparência: 

    (window: Window) => void

Retorna

  • Promise<Window>

    Chrome 88 ou superior

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

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 opcional

    O parâmetro callback tem esta aparência: 

    () => void

Retorna

  • Promessa<void>

    Chrome 88 ou superior

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

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. propriedades não especificadas permanecem inalteradas.

Parâmetros

  • windowId

    number

  • updateInfo

    objeto

    • drawAttention

      booleano opcional

      Se true, faz com que a janela seja mostrada de uma forma que chame a atenção do usuário para a janela, 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 de drawAttention anterior.

    • foco

      booleano opcional

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

    • altura

      número opcional

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

    • esquerda

      número opcional

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

    • estado

      WindowState opcional

      O novo estado da janela. As opções "minimizado", "maximizado" e "tela cheia" não podem ser combinados com "left", "top", "width" ou "height".

    • superior

      número opcional

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

    • largura

      número opcional

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

  • callback

    função opcional

    O parâmetro callback tem esta aparência: 

    (window: Window) => void

Retorna

  • Promise&lt;Window&gt;

    Chrome 88 ou superior

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

Eventos

onBoundsChanged

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

Disparado quando uma janela é redimensionada. este evento só é enviado 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 superior

    O parâmetro callback tem esta aparência: 

    (window: Window) => void

    • janela

      Janela

      Detalhes da janela criada.

  • filtros

    objeto opcional

    • windowTypes

      WindowType[]

      Condições a que o tipo de janela que está sendo criado precisa atender. Por padrão, ela satisfaz ['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 perderem o foco. Observação:em alguns gerenciadores de janelas do Linux, WINDOW_ID_NONE é sempre enviado imediatamente antes da troca de uma janela do Chrome para outra.

Parâmetros

  • callback

    função

    Chrome 46 ou superior

    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 da janela que está sendo removido precisam atender. Por padrão, ela 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 superior

    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 da janela que está sendo removido precisam atender. Por padrão, ela satisfaz ['normal', 'popup'].