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](https://developer.chrome.google.cn/static/docs/extensions/reference/api/windows/images/windows.png?authuser=7&hl=es-419)
Tipos
CreateType
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
Propiedades
-
propagar
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 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 desessions
. -
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 desessions
, 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 desessions
. -
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 desessions
. -
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 desessions
.
WindowState
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
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()
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 esfalse
, 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 posterioresSi 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 posterioresEs el 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
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 posterioresLas 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()
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.
-
Muestra
-
Promise<Window>
Chrome 88 y versiones posterioresLas 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()
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
-
Muestra
-
Promise<Window[]>
Chrome 88 y versiones posterioresLas 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()
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.
-
Muestra
-
Promise<Window>
Chrome 88 y versiones posterioresLas 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()
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.
-
Muestra
-
Promise<Window>
Chrome 88 y versiones posterioresLas 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()
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 posterioresLas 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()
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 enfalse
para cancelar una solicituddrawAttention
anterior. -
enfocados
booleano opcional
Si es
true
, lleva la ventana al frente. no se pueden combinar con el estado "minimized". Si esfalse
, 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.
-
Muestra
-
Promise<Window>
Chrome 88 y versiones posterioresLas 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.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.
-
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 posterioresEl parámetro
callback
se ve de la siguiente manera:(window: Window) => void
-
en la ventana modal.
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 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 posterioresEl 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
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 posterioresEl 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
Condiciones que debe cumplir el tipo de ventana que se quitará. De forma predeterminada, cumple con
['normal', 'popup']
.
-