chrome.windows

Descripción

Usa la API de chrome.windows para interactuar con las ventanas del navegador. Puedes usar esta API para crear, modificar y reorganizar ventanas en el navegador.

Permisos

Cuando se solicita, un objeto windows.Window contiene un array de objetos tabs.Tab. Debes declarar el permiso "tabs" en tu manifiesto si necesitas acceder a las propiedades url, pendingUrl, title o favIconUrl de tabs.Tab. Por ejemplo:

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

Conceptos y uso

La ventana actual

Muchas funciones del sistema de extensiones toman un argumento windowId opcional, cuyo valor predeterminado es la ventana actual.

La ventana actual es la que contiene el código que se está ejecutando actualmente. Es importante tener en cuenta que esto puede ser diferente de la ventana principal o enfocada.

Por ejemplo, supongamos que una extensión crea unas pocas pestañas o ventanas a partir de un solo archivo HTML y que el archivo contiene una llamada a tabs.query(). La ventana actual es la que contiene la página que realizó la llamada, sin importar cuál sea la ventana superior.

En el caso de los service worker, el valor de la ventana actual recurre a la última ventana activa. En algunas circunstancias, es posible que no haya una ventana actual para las páginas en segundo plano.

Ejemplos

Para probar esta API, instala el ejemplo de la API de Windows del repositorio chrome-extension-samples.

Dos ventanas, cada una con una pestaña.

Tipos

CreateType

Chrome 44 y versiones posteriores

Especifica qué tipo de ventana del navegador crear. El “panel” dejó de estar disponible y solo está disponible para las extensiones existentes incluidas en la lista de entidades permitidas en ChromeOS.

Enum

"normal"
Especifica la ventana como una ventana estándar.

"popup"
Especifica la ventana como una ventana emergente.

"panel"
Especifica la ventana como un panel.

QueryOptions

Chrome 88 y versiones posteriores

Propiedades

• populate

  booleano opcional

  Si es verdadero, el objeto windows.Window tiene una propiedad tabs que contiene una lista de los objetos tabs.Tab. Los objetos Tab solo contienen las propiedades url, pendingUrl, title y favIconUrl si el archivo de manifiesto de la extensión incluye el permiso "tabs".

• windowTypes

  WindowType[] opcional

  Si se configura, el windows.Window que se muestra se filtra según su tipo. Si no se establece, el filtro predeterminado se establece en ['normal', 'popup'].

Window

Propiedades

• alwaysOnTop

  boolean

  Indica si la ventana está configurada para estar siempre en la parte superior.

• enfocados

  boolean

  Si la ventana es actualmente la ventana enfocada.

• alto

  número opcional

  Indica la altura de la ventana, incluido el marco, en píxeles. En algunas circunstancias, es posible que no se le asigne una propiedad height a una ventana; por ejemplo, cuando se consultan ventanas cerradas desde la API de sessions.

• id

  número opcional

  El ID de la ventana. Los IDs de ventana son únicos dentro de la sesión del navegador. En algunas circunstancias, es posible que no se le asigne una propiedad ID a una ventana. Por ejemplo, cuando se consultan ventanas mediante la API de sessions, en cuyo caso podría haber un ID de sesión.

• incógnito

  boolean

  Si la ventana es de incógnito.

• izquierda

  número opcional

  Desplazamiento de la ventana desde el borde izquierdo de la pantalla en píxeles. En algunas circunstancias, es posible que no se le asigne una propiedad left a una ventana; por ejemplo, cuando se consultan ventanas cerradas desde la API de sessions.

• sessionId

  cadena opcional

  Es el ID de sesión que se usa para identificar una ventana de forma única, que se obtiene de la API de sessions.

• state

  WindowState opcional

  Es el estado de esta ventana del navegador.

• pestañas

  Tab[] opcional

  Es el array de objetos tabs.Tab que representan las pestañas actuales en la ventana.

• superior

  número opcional

  Desplazamiento de la ventana desde el borde superior de la pantalla en píxeles. En algunas circunstancias, es posible que no se le asigne una propiedad top a una ventana; por ejemplo, cuando se consultan ventanas cerradas desde la API de sessions.

• tipo

  WindowType opcional

  Es el tipo de ventana del navegador.

• ancho

  número opcional

  Corresponde al ancho de la ventana, incluido el marco, en píxeles. En algunas circunstancias, es posible que no se le asigne una propiedad width a una ventana; por ejemplo, cuando se consultan ventanas cerradas desde la API de sessions.

WindowState

Chrome 44 y versiones posteriores

Es el estado de esta ventana del navegador. En algunas circunstancias, es posible que no se le asigne una propiedad state a una ventana; por ejemplo, cuando se consultan ventanas cerradas desde la API de sessions.

Enum

“normal”
Estado de ventana normal (sin minimizar, maximizado ni pantalla completa).

“minimized”
Estado de la ventana minimizado.

"maximized"
Estado de la ventana maximizado.

"fullscreen"
Estado de la ventana de pantalla completa.

“pantalla completa bloqueada”
Estado de ventana de pantalla completa bloqueada. El usuario no puede salir de este estado de pantalla completa mediante una acción del usuario y solo está disponible para las extensiones incluidas en la lista de entidades permitidas en ChromeOS.

WindowType

Chrome 44 y versiones posteriores

Es el tipo de ventana del navegador. En algunos casos, es posible que una ventana no tenga asignada una propiedad type; por ejemplo, cuando se consultan ventanas cerradas desde la API de sessions.

Enum

"normal"
Una ventana del navegador normal.

"popup"
Una ventana emergente del navegador.

"panel"
Obsoleto en esta API. Ventana de estilo de panel de la app de Chrome. Las extensiones solo pueden ver sus propias ventanas de panel.

"app"
Ya no está disponible en esta API. Ventana de la app de Chrome Las extensiones solo pueden ver sus propias ventanas de la app.

"devtools"
Una ventana de Herramientas para desarrolladores

Propiedades

WINDOW_ID_CURRENT

El valor de windowId que representa la ventana actual.

Valor

-2

WINDOW_ID_NONE

Es el valor de windowId que representa la ausencia de una ventana del navegador Chrome.

Valor

-1

Métodos

create()

Promesa

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

Crea (abre) una nueva ventana del navegador con cualquier tamaño, posición o URL predeterminada opcional que se haya proporcionado.

Parámetros

• createData

  objeto opcional

  • enfocados

    booleano opcional

    Si es true, se abre una ventana activa. Si es false, se abre una ventana inactiva.

  • alto

    número opcional

    La altura en píxeles de la nueva ventana, incluido el marco. Si no se especifica, el valor predeterminado es una altura natural.

  • incógnito

    booleano opcional

    Indica si la ventana nueva debe ser de incógnito.

  • izquierda

    número opcional

    Número de píxeles para posicionar la ventana nueva desde el borde izquierdo de la pantalla. Si no se especifica, la ventana nueva se desplaza naturalmente respecto de la última ventana enfocada. Este valor se ignora para los paneles.

  • setSelfAsOpener

    booleano opcional

    Chrome 64 y versiones posteriores

    Si es true, el "window.opener" de la ventana recién creada se establece para el llamador y se encuentra en la misma unidad de contextos de navegación relacionados que el llamador.

  • state

    WindowState opcional

    Chrome 44 y versiones posteriores

    El estado inicial de la ventana. Los estados minimized, maximized y fullscreen no se pueden combinar con left, top, width ni height.

  • tabId

    número opcional

    El ID de la pestaña que se agregará a la ventana nueva.

  • superior

    número opcional

    Número de píxeles para posicionar la ventana nueva desde el borde superior de la pantalla. Si no se especifica, la ventana nueva se desplaza naturalmente respecto de la última ventana enfocada. Este valor se ignora para los paneles.

  • tipo

    CreateType opcional

    Especifica qué tipo de ventana del navegador crear.

  • url

    string|string[] optional

    Una URL o un array de URLs para abrir como pestañas en la ventana. Las URLs completamente calificadas deben incluir un esquema, p.ej., "http://www.google.com", no "www.google.com". Las URLs no completamente calificadas se consideran relativas dentro de la extensión. La configuración predeterminada es la página Nueva pestaña.

  • ancho

    número opcional

    Es el ancho en píxeles de la nueva ventana, incluido el marco. Si no se especifica, el valor predeterminado es un ancho natural.

• callback

  Función opcional

  El parámetro callback se ve de la siguiente manera:

  (window?: Window)=>void

  • ventana

    Ventana opcional

    Contiene detalles sobre la ventana creada.

Devuelve

• Promesa<Window|undefined>

  Chrome 88 y versiones posteriores

  Las promesas son compatibles con Manifest V3 y versiones posteriores, pero se proporcionan devoluciones de llamada para brindar retrocompatibilidad. No puedes usar ambos en la misma llamada a función. La promesa se resuelve con el mismo tipo que se pasa a la devolución de llamada.

get()

Promesa

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

Obtiene detalles sobre una ventana.

Parámetros

• windowId

  número

• queryOptions

  QueryOptions opcionales

  Chrome 88 y versiones posteriores
• callback

  Función opcional

  El parámetro callback se ve de la siguiente manera:

  (window: Window)=>void

  • ventana

    Ventana

Devuelve

• Promesa<Window>

  Chrome 88 y versiones posteriores

  Las promesas son compatibles con Manifest V3 y versiones posteriores, pero se proporcionan devoluciones de llamada para brindar retrocompatibilidad. No puedes usar ambos en la misma llamada a función. La promesa se resuelve con el mismo tipo que se pasa a la devolución de llamada.

getAll()

Promesa

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

Obtiene todas las ventanas.

Parámetros

• queryOptions

  QueryOptions opcionales

  Chrome 88 y versiones posteriores
• callback

  Función opcional

  El parámetro callback se ve de la siguiente manera:

  (windows: Window[])=>void

  • windows

    Ventana

Devuelve

• Promesa<Window[]>

  Chrome 88 y versiones posteriores

  Las promesas son compatibles con Manifest V3 y versiones posteriores, pero se proporcionan devoluciones de llamada para brindar retrocompatibilidad. No puedes usar ambos en la misma llamada a función. La promesa se resuelve con el mismo tipo que se pasa a la devolución de llamada.

getCurrent()

Promesa

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

Obtiene el período actual.

Parámetros

• queryOptions

  QueryOptions opcionales

  Chrome 88 y versiones posteriores
• callback

  Función opcional

  El parámetro callback se ve de la siguiente manera:

  (window: Window)=>void

  • ventana

    Ventana

Devuelve

• Promesa<Window>

  Chrome 88 y versiones posteriores

  Las promesas son compatibles con Manifest V3 y versiones posteriores, pero se proporcionan devoluciones de llamada para brindar retrocompatibilidad. No puedes usar ambos en la misma llamada a función. La promesa se resuelve con el mismo tipo que se pasa a la devolución de llamada.

getLastFocused()

Promesa

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

Obtiene la ventana en la que se enfocó recientemente; por lo general, la ventana "en la parte superior".

Parámetros

• queryOptions

  QueryOptions opcionales

  Chrome 88 y versiones posteriores
• callback

  Función opcional

  El parámetro callback se ve de la siguiente manera:

  (window: Window)=>void

  • ventana

    Ventana

Devuelve

• Promesa<Window>

  Chrome 88 y versiones posteriores

  Las promesas son compatibles con Manifest V3 y versiones posteriores, pero se proporcionan devoluciones de llamada para brindar retrocompatibilidad. No puedes usar ambos en la misma llamada a función. La promesa se resuelve con el mismo tipo que se pasa a la devolución de llamada.

remove()

Promesa

chrome.windows.remove(
  windowId: number,
  callback?: function,
)

Quita (cierra) una ventana y todas las pestañas que contiene.

Parámetros

• windowId

  número

• callback

  Función opcional

  El parámetro callback se ve de la siguiente manera:

  ()=>void

Devuelve

• Promise<void>

  Chrome 88 y versiones posteriores

  Las promesas son compatibles con Manifest V3 y versiones posteriores, pero se proporcionan devoluciones de llamada para brindar retrocompatibilidad. No puedes usar ambos en la misma llamada a función. La promesa se resuelve con el mismo tipo que se pasa a la devolución de llamada.

update()

Promesa

chrome.windows.update(
  windowId: number,
  updateInfo: object,
  callback?: function,
)

Actualiza las propiedades de una ventana. Especifica solo las propiedades que deben cambiarse. Las propiedades no especificadas no se modifican.

Parámetros

• windowId

  número

• updateInfo

  objeto

  • drawAttention

    booleano opcional

    Si es true, hace que la ventana se muestre de una manera que llame la atención del usuario hacia la ventana, sin cambiar la ventana enfocada. El efecto dura hasta que el usuario cambia el foco a la ventana. Esta opción no tiene efecto si la ventana ya está enfocada. Configúralo en false para cancelar una solicitud drawAttention anterior.

  • enfocados

    booleano opcional

    Si es true, lleva la ventana al frente; no se puede combinar con el estado “minimizado”. Si es false, coloca la siguiente ventana en el orden Z al primer plano. No se puede combinar con el estado "pantalla completa" o "maximizado".

  • alto

    número opcional

    Altura en píxeles para cambiar el tamaño de la ventana. Este valor se ignora para los paneles.

  • izquierda

    número opcional

    Desplazamiento desde el borde izquierdo de la pantalla al que se moverá la ventana en píxeles. Este valor se ignora para los paneles.

  • state

    WindowState opcional

    Es el nuevo estado de la ventana. Los estados “minimizado”, “maximizado” y “pantalla completa” no se pueden combinar con los estados “izquierda”, “superior”, “ancho” o “altura”.

  • superior

    número opcional

    Desplazamiento desde el borde superior de la pantalla al que se moverá la ventana en píxeles. Este valor se ignora para los paneles.

  • ancho

    número opcional

    Ancho en píxeles al que se cambiará el tamaño de la ventana. Este valor se ignora para los paneles.

• callback

  Función opcional

  El parámetro callback se ve de la siguiente manera:

  (window: Window)=>void

  • ventana

    Ventana

Devuelve

• Promesa<Window>

  Chrome 88 y versiones posteriores

  Las promesas son compatibles con Manifest V3 y versiones posteriores, pero se proporcionan devoluciones de llamada para brindar retrocompatibilidad. No puedes usar ambos en la misma llamada a función. La promesa se resuelve con el mismo tipo que se pasa a la devolución de llamada.

Eventos

onBoundsChanged

Chrome 86 y versiones posteriores

chrome.windows.onBoundsChanged.addListener(
  callback: function,
)

Se activa cuando se cambia el tamaño de una ventana. Este evento solo se envía cuando se confirman los nuevos límites, no para los cambios en curso.

Parámetros

• callback

  la función

  El parámetro callback se ve de la siguiente manera:

  (window: Window)=>void

  • ventana

    Ventana

onCreated

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

Se activa cuando se crea una ventana.

Parámetros

• callback

  la función

  Chrome 46 y versiones posteriores

  El parámetro callback se ve de la siguiente manera:

  (window: Window)=>void

  • ventana

    Ventana

    Detalles de la ventana creada

• filtros

  objeto opcional

  • windowTypes

    WindowType

    Condiciones que debe cumplir el tipo de ventana que se crea. De forma predeterminada, cumple con ['normal', 'popup'].

onFocusChanged

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

Se activa cuando cambia la ventana enfocada actualmente. Muestra chrome.windows.WINDOW_ID_NONE si todas las ventanas de Chrome se perdieron el foco. Nota: En algunos administradores de ventanas de Linux, WINDOW_ID_NONE siempre se envía inmediatamente antes de cambiar de una ventana de Chrome a otra.

Parámetros

• callback

  la función

  Chrome 46 y versiones posteriores

  El parámetro callback se ve de la siguiente manera:

  (windowId: number)=>void

  • windowId

    número

    ID de la ventana que se acaba de enfocar.

• filtros

  objeto opcional

  • windowTypes

    WindowType

    Condiciones que debe cumplir el tipo de ventana que se quitará. De forma predeterminada, cumple con ['normal', 'popup'].

onRemoved

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

Se activa cuando se quita una ventana (se cierra).

Parámetros

• callback

  la función

  Chrome 46 y versiones posteriores

  El parámetro callback se ve de la siguiente manera:

  (windowId: number)=>void

  • windowId

    número

    ID de la ventana que se quitó.

• filtros

  objeto opcional

  • windowTypes

    WindowType

    Condiciones que debe cumplir el tipo de ventana que se quitará. De forma predeterminada, cumple con ['normal', 'popup'].