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.

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

  • en la ventana modal.

    Ventana

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

  • windows

    Ventana

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

  • en la ventana modal.

    Ventana

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

  • en la ventana modal.

    Ventana

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

  • en la ventana modal.

    Ventana

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

  • en la ventana modal.

    Ventana

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