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](https://developer.chrome.google.cn/static/docs/extensions/reference/api/windows/images/windows.png?authuser=9&hl=es)
Tipos
CreateType
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
Propiedades
-
populate
booleano opcional
Si es verdadero, el objeto
windows.Window
tiene una propiedadtabs
que contiene una lista de los objetostabs.Tab
. Los objetosTab
solo contienen las propiedadesurl
,pendingUrl
,title
yfavIconUrl
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.
-
height
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 desessions
. -
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 desessions
, en cuyo caso es posible que haya 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 desessions
. -
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 desessions
. -
Tipo
WindowType opcional
Es el tipo de ventana del navegador.
-
width
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 desessions
.
WindowState
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
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()
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 esfalse
, se abre una ventana inactiva. -
height
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 posterioresSi 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 posterioresEl estado inicial de la ventana. Los estados
minimized
,maximized
yfullscreen
no se pueden combinar conleft
,top
,width
niheight
. -
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
cadena | 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 no completamente calificadas se consideran relativas dentro de la extensión. La configuración predeterminada es la página Nueva pestaña.
-
width
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
-
Promise<Window | undefined>
Chrome 88 y versiones posterioresLas 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()
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
-
Devuelve
-
Promesa<Window>
Chrome 88 y versiones posterioresLas 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()
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
-
Devuelve
-
Promesa<Window[]>
Chrome 88 y versiones posterioresLas 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()
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
-
Devuelve
-
Promesa<Window>
Chrome 88 y versiones posterioresLas 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()
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
-
Devuelve
-
Promesa<Window>
Chrome 88 y versiones posterioresLas 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()
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 posterioresLas 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()
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 enfalse
para cancelar una solicituddrawAttention
anterior. -
enfocados
booleano opcional
Si es
true
, lleva la ventana al frente; no se puede combinar con el estado “minimizado”. Si esfalse
, coloca la siguiente ventana en el orden Z al primer plano. No se puede combinar con el estado "pantalla completa" o "maximizado". -
height
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.
-
width
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
-
Devuelve
-
Promesa<Window>
Chrome 88 y versiones posterioresLas 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.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
-
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 posterioresEl parámetro
callback
se ve de la siguiente manera:(window: Window) => void
-
ventana
Detalles de la ventana creada
-
-
filtros
objeto opcional
-
windowTypes
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 posterioresEl 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
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 posterioresEl 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
Condiciones que debe cumplir el tipo de ventana que se quitará. De forma predeterminada, cumple con
['normal', 'popup']
.
-