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, una windows.Window contiene un array de objetos tabs.Tab. Debes declara el permiso "tabs" en tu manifiesto si necesitas acceder a url. Propiedades pendingUrl, title o favIconUrl de tabs.Tab. Por ejemplo:

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

Conceptos y uso

El período actual

Muchas funciones del sistema de extensión toman un argumento windowId opcional, cuyo valor predeterminado es el en el período actual.

La ventana actual es la que contiene el código que se está ejecutando actualmente. Es es importante saber que esta puede ser diferente de la ventana superior o enfocada.

Por ejemplo, supongamos que una extensión crea algunas pestañas o ventanas a partir de un único archivo HTML, y que la El archivo HTML contiene una llamada a tabs.query(). La ventana actual es la que contiene la la página que realizó la llamada, independientemente de cuál sea la ventana superior.

En el caso de los service workers, el valor de la ventana actual recurre al último activo en la ventana modal. En algunas circunstancias, es posible que no haya una ventana actual para las páginas de fondo.

Ejemplos

Para probar esta API, instala el ejemplo de la API de Windows desde chrome-extension-samples en un repositorio de confianza.

Dos ventanas, cada una con una pestaña
Dos ventanas, cada una con una pestaña.

Tipos

CreateType

Chrome 44 y versiones posteriores

Especifica qué tipo de ventana del navegador crear. "panel" dejó de estar disponible y solo está disponible para las extensiones existentes incluidas en la lista de entidades permitidas de 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

  • propagar

    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 la estableces, el filtro predeterminado se establecerá en ['normal', 'popup'].

Window

Propiedades

  • alwaysOnTop

    boolean

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

  • enfocados

    boolean

    Indica si la ventana es actualmente la que se centra.

  • alto

    número opcional

    Es la altura de la ventana, incluido el marco, en píxeles. En algunas circunstancias, es posible que a una ventana no se le asigne una propiedad height. 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 una sesión del navegador. En algunas circunstancias, es posible que a una ventana no se le asigne una propiedad ID. Por ejemplo, cuando se consultan ventanas con la API de sessions, en cuyo caso puede haber un ID de sesión.

  • incógnito

    boolean

    Indica 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 a una ventana no se le asigne una propiedad left. por ejemplo, cuando se consultan ventanas cerradas desde la API de sessions.

  • sessionId

    string opcional

    El ID de sesión que se usa para identificar de forma inequívoca una ventana, 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 de 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 a una ventana no se le asigne una propiedad top. 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

    Es el ancho de la ventana, incluido el marco, en píxeles. En algunas circunstancias, es posible que a una ventana no se le asigne una propiedad width. 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 a una ventana no se le asigne una propiedad state. por ejemplo, cuando se consultan ventanas cerradas desde la API de sessions.

Enum

"normal"
Estado normal de la ventana (no minimizada, maximizada ni de pantalla completa)

"minimized"
Estado de ventana minimizado.

"maximized"
Estado de ventana maximizada.

"fullscreen"
Estado de la ventana en pantalla completa.

"locked-fullscreen"
Estado de ventana de pantalla completa bloqueada. La acción del usuario no puede salir de este estado de pantalla completa y solo está disponible para las extensiones incluidas en la lista de entidades permitidas de ChromeOS.

WindowType

Chrome 44 y versiones posteriores

Es el tipo de ventana del navegador. En algunas circunstancias, es posible que a una ventana no se le asigne 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. Una ventana con estilo de panel de la app de Chrome. Las extensiones solo pueden ver sus propias ventanas de panel.

"app"
Obsoleto en esta API. Una ventana de la app de Chrome. Las extensiones solo pueden ver las ventanas propias de la app.

"Herramientas para desarrolladores"
Una ventana de Herramientas para desarrolladores.

Propiedades

WINDOW_ID_CURRENT

El valor de windowId que representa la ventana actual.

Valor

−2

WINDOW_ID_NONE

El valor 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 opcional, posición o URL predeterminada.

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

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

    • incógnito

      booleano opcional

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

    • izquierda

      número opcional

      Es la cantidad de píxeles para posicionar la nueva ventana desde el borde izquierdo de la pantalla. Si no se especifica, la ventana nueva se desplaza de forma natural a partir 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 configura para el emisor y está en la misma unidad de contextos de navegación relacionados que el emisor.

    • state

      WindowState opcional

      Chrome 44 y versiones posteriores

      Es 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

      Es la cantidad de píxeles que se deben colocar en la posición de la ventana nueva desde el borde superior de la pantalla. Si no se especifica, la ventana nueva se desplaza de forma natural a partir 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[] opcional

      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 que no califican por completo se consideran relativas dentro de la extensión. El valor predeterminado es la página Nueva pestaña.

    • ancho

      número opcional

      Indica el ancho en píxeles de la ventana nueva, 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

    • en la ventana modal.

      Ventana opcional

      Contiene detalles sobre la ventana creada.

Muestra

  • Promise<Window | indefinido>

    Chrome 88 y versiones posteriores

    Las promesas son compatibles con Manifest V3 y versiones posteriores, pero se proporcionan devoluciones de llamada para retrocompatibilidad. No puedes usar ambos en la misma llamada a función. El 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 opcional

    Chrome 88 y versiones posteriores
  • callback

    función opcional

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

    (window: Window) => void

Muestra

  • Promise<Window>

    Chrome 88 y versiones posteriores

    Las promesas son compatibles con Manifest V3 y versiones posteriores, pero se proporcionan devoluciones de llamada para retrocompatibilidad. No puedes usar ambos en la misma llamada a función. El 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 opcional

    Chrome 88 y versiones posteriores
  • callback

    función opcional

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

    (windows: Window[]) => void

Muestra

  • Promise<Window[]>

    Chrome 88 y versiones posteriores

    Las promesas son compatibles con Manifest V3 y versiones posteriores, pero se proporcionan devoluciones de llamada para retrocompatibilidad. No puedes usar ambos en la misma llamada a función. El 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 la ventana actual.

Parámetros

  • queryOptions

    QueryOptions opcional

    Chrome 88 y versiones posteriores
  • callback

    función opcional

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

    (window: Window) => void

Muestra

  • Promise<Window>

    Chrome 88 y versiones posteriores

    Las promesas son compatibles con Manifest V3 y versiones posteriores, pero se proporcionan devoluciones de llamada para retrocompatibilidad. No puedes usar ambos en la misma llamada a función. El 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ó más recientemente; por lo general, la ventana "en la parte superior".

Parámetros

  • queryOptions

    QueryOptions opcional

    Chrome 88 y versiones posteriores
  • callback

    función opcional

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

    (window: Window) => void

Muestra

  • Promise<Window>

    Chrome 88 y versiones posteriores

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

remove()

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

Elimina (cierra) una ventana y todas las pestañas adentro.

Parámetros

  • windowId

    número

  • callback

    función opcional

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

    () => void

Muestra

  • Promesa<void>

    Chrome 88 y versiones posteriores

    Las promesas son compatibles con Manifest V3 y versiones posteriores, pero se proporcionan devoluciones de llamada para retrocompatibilidad. No puedes usar ambos en la misma llamada a función. El 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 se cambiarán. las propiedades sin especificar 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 enfoque de 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 pueden combinar con el estado "minimized". Si es false, lleva al frente la siguiente ventana en orden z; No se puede combinar con el estado "pantalla completa". o "maximizada".

    • alto

      número opcional

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

    • izquierda

      número opcional

      Desplazamiento del borde izquierdo de la pantalla al que se mueve la ventana en píxeles. Este valor se ignora para los paneles.

    • state

      WindowState opcional

      Es el nuevo estado de la ventana. los valores "minimizado", "maximizado" y "pantalla completa" no se pueden combinar con “left”, “top”, “width” o “height”.

    • superior

      número opcional

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

    • ancho

      número opcional

      Es el 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

Muestra

  • Promise&lt;Window&gt;

    Chrome 88 y versiones posteriores

    Las promesas son compatibles con Manifest V3 y versiones posteriores, pero se proporcionan devoluciones de llamada para retrocompatibilidad. No puedes usar ambos en la misma llamada a función. El 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 despacha cuando se confirman los nuevos límites, y no para los cambios en curso.

Parámetros

  • callback

    función

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

    (window: Window) => void

onCreated

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

Se activa cuando se crea una ventana.

Parámetros

  • callback

    función

    Chrome 46 y versiones posteriores

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

    (window: Window) => void

    • en la ventana modal.

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

    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 enfocada recientemente.

  • 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

    función

    Chrome 46 y versiones posteriores

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

    (windowId: number) => void

    • windowId

      número

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