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.

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

  • janela

    Janela

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

  • windows

    Janela[]

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

  • janela

    Janela

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

  • janela

    Janela

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

  • janela

    Janela

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

  • janela

    Janela

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'].