Descrizione
Utilizza l'API chrome.windows
per interagire con le finestre del browser. Puoi utilizzare questa API per creare, modificare e ridisporre le finestre nel browser.
Autorizzazioni
Quando richiesto, un oggetto windows.Window
contiene un array di oggetti tabs.Tab
. Devi
dichiarare l'autorizzazione "tabs"
nel manifest se devi accedere alle proprietà url
,
pendingUrl
, title
o favIconUrl
di tabs.Tab
. Ad esempio:
{
"name": "My extension",
...
"permissions": ["tabs"],
...
}
Concetti e utilizzo
Finestra corrente
Molte funzioni nel sistema di estensioni utilizzano un argomento windowId
facoltativo, che imposta per impostazione predefinita la finestra corrente.
La finestra attuale è la finestra che contiene il codice attualmente in esecuzione. È importante capire che può essere diversa dalla finestra più alta o attiva.
Ad esempio, supponiamo che un'estensione crei alcune schede o finestre a partire da un singolo file HTML e che il file HTML contenga una chiamata a tabs.query()
. La finestra corrente è la finestra che contiene la pagina che ha effettuato la chiamata, indipendentemente dalla finestra più in alto.
Nel caso dei service worker, il valore della finestra attuale torna all'ultima finestra attiva. In alcuni casi, potrebbe non essere disponibile la finestra corrente per le pagine in background.
Esempi
Per provare questa API, installa l'esempio dell'API Windows dal repository chrome-extension-samples.
![Due finestre, ciascuna con una scheda](https://developer.chrome.google.cn/static/docs/extensions/reference/api/windows/images/windows.png?authuser=9&hl=it)
Tipi
CreateType
Specifica il tipo di finestra del browser da creare. L'etichetta "panel" è deprecata ed è disponibile solo per le estensioni incluse nella lista consentita su ChromeOS.
Enum
"normal"
Specifica la finestra come finestra standard.
"popup"
Specifica la finestra come finestra popup.
"panel"
Specifica la finestra come riquadro.
QueryOptions
Proprietà
-
compilare
booleano facoltativo
Se il valore è true, l'oggetto
windows.Window
ha una proprietàtabs
che contiene un elenco di oggettitabs.Tab
. Gli oggettiTab
contengono le proprietàurl
,pendingUrl
,title
efavIconUrl
solo se il file manifest dell'estensione include l'autorizzazione"tabs"
. -
windowTypes
WindowType[] facoltativo
Se impostato, la
windows.Window
restituita viene filtrata in base al tipo. Se non viene configurato, il filtro predefinito è impostato su['normal', 'popup']
.
Window
Proprietà
-
alwaysOnTop
boolean
Indica se la finestra è impostata per essere sempre in alto.
-
Mirati
boolean
Indica se la finestra è attualmente la finestra attiva.
-
altezza
numero facoltativo
L'altezza della finestra, incluso il frame, in pixel. In alcuni casi potrebbe non essere assegnata una proprietà
height
a una finestra, ad esempio quando esegui query su finestre chiuse dall'APIsessions
. -
id
numero facoltativo
L'ID della finestra. Gli ID finestra sono univoci all'interno di una sessione del browser. In alcuni casi a una finestra potrebbe non essere assegnata una proprietà
ID
, ad esempio quando si eseguono query sulle finestre utilizzando l'APIsessions
, nel qual caso potrebbe essere presente un ID sessione. -
in incognito
boolean
Indica se la finestra è in incognito.
-
a sinistra
numero facoltativo
L'offset della finestra dal bordo sinistro dello schermo in pixel. In alcuni casi potrebbe non essere assegnata una proprietà
left
a una finestra, ad esempio quando esegui query su finestre chiuse dall'APIsessions
. -
sessionId
stringa facoltativo
L'ID sessione utilizzato per identificare in modo univoco una finestra, ottenuto dall'API
sessions
. -
state
WindowState facoltativo
Lo stato di questa finestra del browser.
-
schede
Tab[] facoltativo
Array di oggetti
tabs.Tab
che rappresenta le schede correnti nella finestra. -
in alto
numero facoltativo
L'offset della finestra dal bordo superiore dello schermo in pixel. In alcuni casi potrebbe non essere assegnata una proprietà
top
a una finestra, ad esempio quando esegui query su finestre chiuse dall'APIsessions
. -
Tipo
WindowType facoltativo
Il tipo di finestra del browser.
-
larghezza
numero facoltativo
La larghezza della finestra, incluso il frame, in pixel. In alcuni casi potrebbe non essere assegnata una proprietà
width
a una finestra, ad esempio quando esegui query su finestre chiuse dall'APIsessions
.
WindowState
Lo stato di questa finestra del browser. In alcuni casi potrebbe non essere assegnata una proprietà state
a una finestra, ad esempio quando esegui query su finestre chiuse dall'API sessions
.
Enum
"normal"
Stato normale della finestra (non ridotto a icona, ingrandito o schermo intero).
"minimizzata"
Stato finestra ridotta a icona.
"maximized"
Stato finestra ingrandita.
"schermo intero"
Stato finestra a schermo intero.
"schermo intero bloccato"
Stato della finestra a schermo intero bloccata. Questo stato a schermo intero non può essere chiuso con un'azione dell'utente ed è disponibile solo per le estensioni incluse nella lista consentita su ChromeOS.
WindowType
Il tipo di finestra del browser. In alcuni casi, a una finestra potrebbe non essere assegnata una proprietà type
, ad esempio quando esegui query su finestre chiuse dall'API sessions
.
Enum
"normal"
Una normale finestra del browser.
"popup"
Popup del browser.
"panel"
Deprecato in questa API. Una finestra in stile riquadro dell'app di Chrome. Le estensioni possono vedere solo le proprie finestre dei riquadri.
"app"
Deprecato in questa API. Una finestra dell'app Chrome. Le estensioni possono vedere solo le finestre delle loro app.
"devtools"
Una finestra Strumenti per sviluppatori.
Proprietà
WINDOW_ID_CURRENT
Il valore windowId che rappresenta la finestra corrente.
Valore
-2
WINDOW_ID_NONE
Il valore windowId che rappresenta l'assenza di una finestra del browser Chrome.
Valore
-1
Metodi
create()
chrome.windows.create(
createData?: object,
callback?: function,
)
Crea (apre) una nuova finestra del browser con eventuali dimensioni, posizione o URL predefinito facoltativi forniti.
Parametri
-
createData
oggetto facoltativo
-
Mirati
booleano facoltativo
Se
true
, apre una finestra attiva. Sefalse
, apre una finestra non attiva. -
altezza
numero facoltativo
L'altezza in pixel della nuova finestra, incluso il frame. Se non specificato, il valore predefinito è un'altezza naturale.
-
in incognito
booleano facoltativo
Indica se la nuova finestra deve essere una finestra di navigazione in incognito.
-
a sinistra
numero facoltativo
Il numero di pixel per posizionare la nuova finestra dal bordo sinistro dello schermo. Se non specificata, la nuova finestra è naturalmente sfalsata rispetto all'ultima finestra attiva. Questo valore viene ignorato per i riquadri.
-
setSelfAsOpener
booleano facoltativo
Chrome 64 e versioni successiveSe
true
, "window.opener" della finestra appena creata è impostato sul chiamante e si trova nella stessa unità di contesti di navigazione correlati del chiamante. -
state
WindowState facoltativo
Chrome 44 e versioni successiveLo stato iniziale della finestra. Gli stati
minimized
,maximized
efullscreen
non possono essere combinati conleft
,top
,width
oheight
. -
tabId
numero facoltativo
L'ID della scheda da aggiungere alla nuova finestra.
-
in alto
numero facoltativo
Il numero di pixel per posizionare la nuova finestra dal bordo superiore dello schermo. Se non specificata, la nuova finestra è naturalmente sfalsata rispetto all'ultima finestra attiva. Questo valore viene ignorato per i riquadri.
-
Tipo
CreateType facoltativo
Specifica il tipo di finestra del browser da creare.
-
url
string | string[] facoltativo
Un URL o un array di URL da aprire come schede nella finestra. Gli URL completi devono includere uno schema, ad esempio "http://www.google.com", non "www.google.com". Gli URL non completi sono considerati relativi all'interno dell'estensione. Il valore predefinito è la pagina Nuova scheda.
-
larghezza
numero facoltativo
La larghezza in pixel della nuova finestra, incluso il frame. Se non specificato, il valore predefinito è la larghezza naturale.
-
-
callback
funzione facoltativa
Il parametro
callback
ha il seguente aspetto:(window?: Window) => void
-
finestra
Finestra facoltativa
Contiene i dettagli della finestra creata.
-
Ritorni
-
Promise<Window | undefined>
Chrome 88 e versioni successiveLe promesse sono supportate in Manifest V3 e versioni successive, ma vengono forniti callback per garantire la compatibilità con le versioni precedenti. Non puoi utilizzarli entrambi nella stessa chiamata di funzione. La promessa viene risolta con lo stesso tipo trasmesso al callback.
get()
chrome.windows.get(
windowId: number,
queryOptions?: QueryOptions,
callback?: function,
)
Recupera i dettagli di una finestra.
Parametri
-
windowId
numero
-
queryOptions
QueryOptions facoltativo
Chrome 88 e versioni successive -
callback
funzione facoltativa
Il parametro
callback
ha il seguente aspetto:(window: Window) => void
-
finestra
-
Ritorni
-
Promessa<Finestra>
Chrome 88 e versioni successiveLe promesse sono supportate in Manifest V3 e versioni successive, ma vengono forniti callback per garantire la compatibilità con le versioni precedenti. Non puoi utilizzarli entrambi nella stessa chiamata di funzione. La promessa viene risolta con lo stesso tipo trasmesso al callback.
getAll()
chrome.windows.getAll(
queryOptions?: QueryOptions,
callback?: function,
)
Recupera tutte le finestre.
Parametri
-
queryOptions
QueryOptions facoltativo
Chrome 88 e versioni successive -
callback
funzione facoltativa
Il parametro
callback
ha il seguente aspetto:(windows: Window[]) => void
-
finestre
Finestra[]
-
Ritorni
-
Promessa<Finestra[]>
Chrome 88 e versioni successiveLe promesse sono supportate in Manifest V3 e versioni successive, ma vengono forniti callback per garantire la compatibilità con le versioni precedenti. Non puoi utilizzarli entrambi nella stessa chiamata di funzione. La promessa viene risolta con lo stesso tipo trasmesso al callback.
getCurrent()
chrome.windows.getCurrent(
queryOptions?: QueryOptions,
callback?: function,
)
Recupera la finestra attuale.
Parametri
-
queryOptions
QueryOptions facoltativo
Chrome 88 e versioni successive -
callback
funzione facoltativa
Il parametro
callback
ha il seguente aspetto:(window: Window) => void
-
finestra
-
Ritorni
-
Promessa<Finestra>
Chrome 88 e versioni successiveLe promesse sono supportate in Manifest V3 e versioni successive, ma vengono forniti callback per garantire la compatibilità con le versioni precedenti. Non puoi utilizzarli entrambi nella stessa chiamata di funzione. La promessa viene risolta con lo stesso tipo trasmesso al callback.
getLastFocused()
chrome.windows.getLastFocused(
queryOptions?: QueryOptions,
callback?: function,
)
Consente di acquisire la finestra che è stata attivata più di recente, in genere la finestra "in alto".
Parametri
-
queryOptions
QueryOptions facoltativo
Chrome 88 e versioni successive -
callback
funzione facoltativa
Il parametro
callback
ha il seguente aspetto:(window: Window) => void
-
finestra
-
Ritorni
-
Promessa<Finestra>
Chrome 88 e versioni successiveLe promesse sono supportate in Manifest V3 e versioni successive, ma vengono forniti callback per garantire la compatibilità con le versioni precedenti. Non puoi utilizzarli entrambi nella stessa chiamata di funzione. La promessa viene risolta con lo stesso tipo trasmesso al callback.
remove()
chrome.windows.remove(
windowId: number,
callback?: function,
)
Rimuove (chiude) una finestra e tutte le schede al suo interno.
Parametri
-
windowId
numero
-
callback
funzione facoltativa
Il parametro
callback
ha il seguente aspetto:() => void
Ritorni
-
Promise<void>
Chrome 88 e versioni successiveLe promesse sono supportate in Manifest V3 e versioni successive, ma vengono forniti callback per garantire la compatibilità con le versioni precedenti. Non puoi utilizzarli entrambi nella stessa chiamata di funzione. La promessa viene risolta con lo stesso tipo trasmesso al callback.
update()
chrome.windows.update(
windowId: number,
updateInfo: object,
callback?: function,
)
Aggiorna le proprietà di una finestra. Specifica solo le proprietà da modificare; le proprietà non specificate rimangono invariate.
Parametri
-
windowId
numero
-
updateInfo
oggetto
-
drawAttention
booleano facoltativo
Se
true
, consente di visualizzare la finestra in modo da attirare l'attenzione dell'utente sulla finestra, senza modificare la finestra attiva. L'effetto dura finché l'utente non cambia lo stato attivo sulla finestra. Questa opzione non ha effetto se la finestra è già attiva. Impostafalse
per annullare una precedente richiesta didrawAttention
. -
Mirati
booleano facoltativo
Se
true
, porta la finestra in primo piano; non può essere combinata con lo stato "minimizzato". Sefalse
, mette in primo piano la finestra successiva in ordine z; non può essere combinata con lo stato "a schermo intero" o "ingrandito". -
altezza
numero facoltativo
L'altezza alla quale ridimensionare la finestra in pixel. Questo valore viene ignorato per i riquadri.
-
a sinistra
numero facoltativo
L'offset dal bordo sinistro dello schermo in cui spostare la finestra, in pixel. Questo valore viene ignorato per i riquadri.
-
state
WindowState facoltativo
Il nuovo stato della finestra. Gli stati "minimizzato", "maximized" e "a schermo intero" non possono essere combinati con "left", "top", "width" o "height".
-
in alto
numero facoltativo
L'offset dal bordo superiore dello schermo in cui spostare la finestra, in pixel. Questo valore viene ignorato per i riquadri.
-
larghezza
numero facoltativo
La larghezza alla quale ridimensionare la finestra in pixel. Questo valore viene ignorato per i riquadri.
-
-
callback
funzione facoltativa
Il parametro
callback
ha il seguente aspetto:(window: Window) => void
-
finestra
-
Ritorni
-
Promessa<Finestra>
Chrome 88 e versioni successiveLe promesse sono supportate in Manifest V3 e versioni successive, ma vengono forniti callback per garantire la compatibilità con le versioni precedenti. Non puoi utilizzarli entrambi nella stessa chiamata di funzione. La promessa viene risolta con lo stesso tipo trasmesso al callback.
Eventi
onBoundsChanged
chrome.windows.onBoundsChanged.addListener(
callback: function,
)
Viene attivato quando una finestra è stata ridimensionata; questo evento viene inviato solo quando viene eseguito il commit dei nuovi limiti e non per le modifiche in corso.
Parametri
-
callback
funzione
Il parametro
callback
ha il seguente aspetto:(window: Window) => void
-
finestra
-
onCreated
chrome.windows.onCreated.addListener(
callback: function,
filters?: object,
)
Attivato quando viene creata una finestra.
Parametri
-
callback
funzione
Chrome 46 e versioni successiveIl parametro
callback
ha il seguente aspetto:(window: Window) => void
-
finestra
Dettagli della finestra creata.
-
-
filtri
oggetto facoltativo
-
windowTypes
Condizioni che il tipo di finestra creato deve soddisfare. Per impostazione predefinita, soddisfa
['normal', 'popup']
.
-
onFocusChanged
chrome.windows.onFocusChanged.addListener(
callback: function,
filters?: object,
)
Attivato quando cambia la finestra attualmente attiva. Restituisce chrome.windows.WINDOW_ID_NONE
se tutte le finestre di Chrome hanno perso lo stato attivo. Nota:in alcuni gestori di finestre di Linux, WINDOW_ID_NONE
viene sempre inviato immediatamente prima del passaggio da una finestra di Chrome a un'altra.
Parametri
-
callback
funzione
Chrome 46 e versioni successiveIl parametro
callback
ha il seguente aspetto:(windowId: number) => void
-
windowId
numero
ID della finestra appena attivata.
-
-
filtri
oggetto facoltativo
-
windowTypes
Condizioni che devono essere soddisfatte dal tipo di finestra che viene rimosso. Per impostazione predefinita, soddisfa
['normal', 'popup']
.
-
onRemoved
chrome.windows.onRemoved.addListener(
callback: function,
filters?: object,
)
Si attiva quando una finestra viene rimossa (chiusa).
Parametri
-
callback
funzione
Chrome 46 e versioni successiveIl parametro
callback
ha il seguente aspetto:(windowId: number) => void
-
windowId
numero
ID della finestra rimossa.
-
-
filtri
oggetto facoltativo
-
windowTypes
Condizioni che devono essere soddisfatte dal tipo di finestra che viene rimosso. Per impostazione predefinita, soddisfa
['normal', 'popup']
.
-