Esta página foi traduzida pela API Cloud Translation.

chrome.windows

Descrição

Use a API chrome.windows para interagir com 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ê precisa declarar a permissão "tabs" no manifesto se precisar acessar as propriedades url, pendingUrl, title ou favIconUrl de tabs.Tab. Exemplo:

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

Conceitos e uso

A 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 que contém o código em execução. É importante saber que isso pode ser diferente da janela principal 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 é a que contém a página que fez a chamada, não importa qual seja a janela mais acima.

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 aberta para páginas em segundo plano.

Exemplos

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

Tipos

CreateType

Chrome 44 ou mais recente

Especifica o tipo de janela do navegador a ser criada. "panel" está descontinuado e disponível apenas para extensões na lista de permissões 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 mais recente

Propriedades

populate

booleano opcional

Se for verdadeiro, o objeto windows.Window terá uma propriedade tabs que contém uma lista de objetos tabs.Tab. Os objetos Tab só contêm 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 dele. Se não for definido, o filtro padrão será ['normal', 'popup'].

Window

Propriedades

alwaysOnTop

booleano

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

booleano

Se a janela está em foco no momento.
altura

number 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 da API sessions.
ID

number 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.
navegação anônima

booleano

Indica se a janela é anônima.
esquerda

number optional

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 da API sessions.
sessionId

string opcional

O ID da sessão usado para identificar exclusivamente uma janela, obtido da API sessions.
estado

WindowState opcional

O estado desta janela do navegador.
guias

Tab[] optional

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

number optional

O deslocamento da janela 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 da API sessions.
tipo

WindowType opcional

O tipo de janela do navegador.
largura

number 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 da API sessions.

WindowState

Chrome 44 ou mais recente

O estado desta janela do navegador. Em algumas circunstâncias, uma janela pode não receber uma propriedade state. Por exemplo, ao consultar janelas fechadas da 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 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 ele está disponível apenas para extensões na lista de permissões do Chrome OS.

WindowType

Chrome 44 ou mais recente

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 da API sessions.

Enumeração

"normal"
Uma janela normal do navegador.

"popup"
Um pop-up do navegador.

"panel"
Descontinuado nesta API. Uma janela no estilo painel de um 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 das 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()

chrome.windows.create(
  createData?: object,
): Promise<Window | undefined>

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

Parâmetros

createData

objeto opcional
- foco
  
  booleano opcional
  
  Se true, abre uma janela ativa. Se false, abre uma janela inativa.
- altura
  
  number optional
  
  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
  
  Indica se a nova janela deve ser anônima.
- esquerda
  
  number optional
  
  O número de pixels para posicionar a nova janela na 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 true, o "window.opener" da janela recém-criada será definido como o chamador e estará na mesma unidade de contextos de navegação relacionados que o chamador.
- estado
  
  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
  
  number optional
  
  O ID da guia a ser adicionada à nova janela.
- superior
  
  number optional
  
  O número de pixels para posicionar a nova janela 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 a 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". URLs não totalmente qualificados são considerados relativos na extensão. O padrão é a página "Nova guia".
- largura
  
  number optional
  
  A largura em pixels da nova janela, incluindo o frame. Se não for especificado, o padrão será uma largura natural.

Retorna

Promise<Window | undefined>

Chrome 88 ou mais recente

get()

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

Recebe detalhes sobre uma janela.

Parâmetros

windowId

número
queryOptions

QueryOptions opcional

Chrome 88 ou mais recente

Retorna

Promise<Window>

Chrome 88 ou mais recente

getAll()

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

Recebe todas as janelas.

Parâmetros

queryOptions

QueryOptions opcional

Chrome 88 ou mais recente

Retorna

Promise<Window[]>

Chrome 88 ou mais recente

getCurrent()

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

Recebe a janela atual.

Parâmetros

queryOptions

QueryOptions opcional

Chrome 88 ou mais recente

Retorna

Promise<Window>

Chrome 88 ou mais recente

getLastFocused()

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

Recebe a janela que foi focada mais recentemente, geralmente a janela "na frente".

Parâmetros

queryOptions

QueryOptions opcional

Chrome 88 ou mais recente

Retorna

Promise<Window>

Chrome 88 ou mais recente

remove()

chrome.windows.remove(
  windowId: number,
): Promise<void>

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

Parâmetros

windowId

número

Retorna

Promise<void>

Chrome 88 ou mais recente

update()

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

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

Parâmetros

windowId

número
updateInfo

objeto
- drawAttention
  
  booleano opcional
  
  Se true, faz com que a janela seja mostrada 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 tem efeito se a janela já estiver em foco. Defina como false para cancelar uma solicitação 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
  
  number optional
  
  A altura para redimensionar a janela em pixels. Esse valor é ignorado para painéis.
- esquerda
  
  number 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
  
  number optional
  
  O deslocamento da borda superior da tela para mover a janela em pixels. Esse valor é ignorado para painéis.
- largura
  
  number optional
  
  A largura para redimensionar a janela em pixels. Esse valor é ignorado para painéis.

Retorna

Promise<Window>

Chrome 88 ou mais recente

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 tem esta aparência:
```
(window: Window) => void
```
- janela
  
  Janela

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 sendo criada precisa atender. Por padrão, ele atende a ['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 troca 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
  
  número
  
  ID da janela recém-focada.
filtros

objeto opcional
- windowTypes
  
  WindowType[]
  
  Condições que o tipo da janela a ser removida precisa atender. Por padrão, ele 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
  
  número
  
  ID da janela removida.
filtros

objeto opcional
- windowTypes
  
  WindowType[]
  
  Condições que o tipo da janela a ser removida precisa atender. Por padrão, ele atende a ['normal', 'popup'].

chrome.windows Mantenha tudo organizado com as coleções Salve e categorize o conteúdo com base nas suas preferências.

Descrição

Permissões

Conceitos e uso

A janela atual

Exemplos

Tipos

CreateType

Enumeração

QueryOptions

Propriedades

Window

Propriedades

WindowState

Enumeração

WindowType

Enumeração

Propriedades

WINDOW_ID_CURRENT

Valor

WINDOW_ID_NONE

Valor

Métodos

create()

Parâmetros

Retorna

get()

Parâmetros

Retorna

getAll()

Parâmetros

Retorna

getCurrent()

Parâmetros

Retorna

getLastFocused()

Parâmetros

Retorna

remove()

Parâmetros

Retorna

update()

Parâmetros

Retorna

Eventos

onBoundsChanged

Parâmetros

onCreated

Parâmetros

onFocusChanged

Parâmetros

onRemoved

Parâmetros

chrome.windows