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](https://developer.chrome.google.cn/static/docs/extensions/reference/api/windows/images/windows.png?authuser=9&hl=pt)
Tipos
CreateType
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
Propriedades
-
populate
booleano opcional
Se for verdadeiro, o objeto
windows.Window
terá uma propriedadetabs
que contém uma lista dos objetostabs.Tab
. Os objetosTab
vão conter apenas as propriedadesurl
,pendingUrl
,title
efavIconUrl
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.
-
height
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 APIsessions
. -
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 APIsessions
. 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 APIsessions
. -
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 APIsessions
. -
Tipo
WindowType (opcional)
O tipo de janela do navegador.
-
width
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 APIsessions
.
WindowState
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
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()
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 forfalse
, abre uma janela inativa. -
height
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 recenteSe 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 recenteO estado inicial da janela. Os estados
minimized
,maximized
efullscreen
não podem ser combinados comleft
,top
,width
ouheight
. -
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.
-
Tipo
CreateType opcional
Especifica o tipo de janela do navegador que será criada.
-
url
string | string[] opcional
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".
-
width
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
-
Promise<Window | undefined>
Chrome 88 ou mais recentePromessas 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()
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
-
janela
-
Retorna
-
Promise<Window>
Chrome 88 ou mais recentePromessas 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()
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
-
windows
Janela[]
-
Retorna
-
Promessa<janela[]>
Chrome 88 ou mais recentePromessas 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()
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
-
janela
-
Retorna
-
Promise<Window>
Chrome 88 ou mais recentePromessas 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()
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
-
janela
-
Retorna
-
Promise<Window>
Chrome 88 ou mais recentePromessas 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()
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 recentePromessas 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()
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 comofalse
para cancelar uma solicitação anterior dedrawAttention
. -
foco
booleano opcional
Se for
true
, traz a janela para a frente. Não pode ser combinado com o estado "minimizado". Se forfalse
, traz a próxima janela na ordem z para a frente; não pode ser combinada com o estado "tela cheia" ou "maximizada". -
height
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.
-
width
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
-
janela
-
Retorna
-
Promise<Window>
Chrome 88 ou mais recentePromessas 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.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
-
janela
-
onCreated
chrome.windows.onCreated.addListener(
callback: function,
filters?: object,
)
Disparado quando uma janela é criada.
Parâmetros
-
callback
função
Chrome 46 ou mais recenteO parâmetro
callback
tem esta aparência:(window: Window) => void
-
janela
Detalhes da janela criada.
-
-
filtros
objeto opcional
-
windowTypes
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 recenteO parâmetro
callback
tem esta aparência:(windowId: number) => void
-
windowId
number
ID da janela recém-focada.
-
-
filtros
objeto opcional
-
windowTypes
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 recenteO parâmetro
callback
tem esta aparência:(windowId: number) => void
-
windowId
number
ID da janela removida.
-
-
filtros
objeto opcional
-
windowTypes
Condições a que o tipo de janela que está sendo removido precisa atender. Por padrão, atende a
['normal', 'popup']
.
-