chrome.windows

refresh date: 2026-09-25 robots: noindex

Descrizione

Utilizza l'API chrome.windows per interagire con le finestre del browser. Puoi utilizzare questa API per creare, modificare e riorganizzare le finestre nel browser.

Manifest

Quando richiesto, un windows.Window contiene un array di oggetti tabs.Tab. Devi dichiarare l'autorizzazione "tabs" nel tuo manifest se hai bisogno di accedere alle proprietà url, pendingUrl, title o favIconUrl di tabs.Tab. Ad esempio:

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

La finestra corrente

Molte funzioni del sistema di estensioni accettano un argomento windowId facoltativo, che per impostazione predefinita è la finestra corrente.

La finestra corrente è quella che contiene il codice attualmente in esecuzione. È importante tenere presente che questa finestra può essere diversa da quella in primo piano o attiva.

Ad esempio, supponiamo che un'estensione crei alcune schede o finestre da un singolo file HTML e che il file HTML contenga una chiamata a tabs.query(). La finestra corrente è quella che contiene la pagina che ha effettuato la chiamata, indipendentemente dalla finestra più in alto.

Nel caso dei service worker, il valore della finestra corrente viene sostituito con quello dell'ultima finestra attiva. In alcune circostanze, potrebbe non essere presente una finestra corrente per le pagine in background.

Esempi

Due finestre, ciascuna con una scheda

Per provare questa API, installa l'esempio di API windows dal repository chrome-extension-samples.

Tipi

CreateType

Chrome 44 e versioni successive

Specifica il tipo di finestra del browser da creare. "panel" è deprecato ed è disponibile solo per le estensioni esistenti 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

Chrome 88 e versioni successive

Proprietà

  • compilare

    boolean facoltativo

    Se true, l'oggetto windows.Window ha una proprietà tabs che contiene un elenco degli oggetti tabs.Tab. Gli oggetti Tab contengono le proprietà url, pendingUrl, title e favIconUrl solo se il file manifest dell'estensione include l'autorizzazione "tabs".

  • windowTypes

    WindowType[] facoltativo

    Se impostato, il valore windows.Window restituito viene filtrato in base al tipo. Se non viene impostato, il filtro predefinito è ['normal', 'popup'].

Window

Proprietà

  • alwaysOnTop

    booleano

    Indica se la finestra è impostata per essere sempre in primo piano.

  • Focalizzati

    booleano

    Indica se la finestra è attualmente quella attiva.

  • altezza

    number optional

    L'altezza della finestra, inclusa la cornice, in pixel. In alcune circostanze, a una finestra potrebbe non essere assegnata una proprietà height, ad esempio quando si esegue una query sulle finestre chiuse dall'API sessions.

  • id

    number optional

    L'ID della finestra. Gli ID finestra sono univoci all'interno di una sessione del browser. In alcune circostanze, a una finestra potrebbe non essere assegnata una proprietà ID, ad esempio quando si eseguono query sulle finestre utilizzando l'API sessions, nel qual caso potrebbe essere presente un ID sessione.

  • incognito

    booleano

    Indica se la finestra è in incognito.

  • sinistra

    number optional

    L'offset della finestra dal bordo sinistro dello schermo in pixel. In alcune circostanze, a una finestra potrebbe non essere assegnata una proprietà left, ad esempio quando si esegue una query sulle finestre chiuse dall'API sessions.

  • sessionId

    stringa facoltativa

    L'ID sessione utilizzato per identificare in modo univoco una finestra, ottenuto dall'API sessions.

  • stato

    WindowState facoltativo

    Lo stato di questa finestra del browser.

  • schede

    Tab[] facoltativo

    Array di oggetti tabs.Tab che rappresentano le schede correnti nella finestra.

  • in alto

    number optional

    L'offset della finestra dal bordo superiore dello schermo in pixel. In alcune circostanze, a una finestra potrebbe non essere assegnata una proprietà top, ad esempio quando si esegue una query sulle finestre chiuse dall'API sessions.

  • tipo

    WindowType facoltativo

    Il tipo di finestra del browser.

  • larghezza

    number optional

    La larghezza della finestra, inclusa la cornice, in pixel. In alcune circostanze, a una finestra potrebbe non essere assegnata una proprietà width, ad esempio quando si esegue una query sulle finestre chiuse dall'API sessions.

WindowState

Chrome 44 e versioni successive

Lo stato di questa finestra del browser. In alcune circostanze, a una finestra potrebbe non essere assegnata una proprietà state, ad esempio quando si esegue una query sulle finestre chiuse dall'API sessions.

Enum

"normal"
Stato normale della finestra (non ridotta a icona, ingrandita o a schermo intero).

"minimized"
Stato della finestra ridotta a icona.

"maximized"
Stato della finestra ingrandita.

"fullscreen"
Stato della finestra a schermo intero.

WindowType

Chrome 44 e versioni successive

Il tipo di finestra del browser. In alcune circostanze, a una finestra potrebbe non essere assegnata una proprietà type, ad esempio quando si eseguono query su finestre chiuse dall'API sessions.

Enum

"normal"
Una normale finestra del browser.

"popup"
Un popup del browser.

"panel"
Deprecato in questa API. Una finestra di un'app di Chrome in stile riquadro. Le estensioni possono vedere solo le proprie finestre del riquadro.

"app"
Deprecato in questa API. Una finestra di un'app di Chrome. Le estensioni possono vedere solo le finestre delle proprie app.

"devtools"
Una finestra degli 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()

Promise 
chrome.windows.create(
  createData?: object,
  callback?: function,
): Promise<Window | undefined>

Crea (apre) una nuova finestra del browser con dimensioni, posizione o URL predefinito facoltativi.

Parametri

  • createData

    object facoltativo

    • Focalizzati

      boolean facoltativo

      Se true, apre una finestra attiva. Se false, apre una finestra non attiva.

    • altezza

      number optional

      L'altezza in pixel della nuova finestra, inclusa la cornice. Se non specificato, il valore predefinito è un'altezza naturale.

    • incognito

      boolean facoltativo

      Indica se la nuova finestra deve essere una finestra Incognito.

    • sinistra

      number optional

      Il numero di pixel per posizionare la nuova finestra dal bordo sinistro dello schermo. Se non viene specificato, la nuova finestra viene spostata naturalmente rispetto all'ultima finestra attiva. Questo valore viene ignorato per i pannelli.

    • setSelfAsOpener

      boolean facoltativo

      Chrome 64 e versioni successive

      Se true, l'attributo "window.opener" della finestra appena creata viene impostato sul chiamante e si trova nella stessa unità di contesti di navigazione correlati del chiamante.

    • stato

      WindowState facoltativo

      Chrome 44 e versioni successive

      Lo stato iniziale della finestra. Gli stati minimized, maximized e fullscreen non possono essere combinati con left, top, width o height.

    • tabId

      number optional

      L'ID della scheda da aggiungere alla nuova finestra.

    • in alto

      number optional

      Il numero di pixel per posizionare la nuova finestra dal bordo superiore dello schermo. Se non viene specificato, la nuova finestra viene spostata naturalmente rispetto all'ultima finestra attiva. Questo valore viene ignorato per i pannelli.

    • 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

      number optional

      La larghezza in pixel della nuova finestra, inclusa la cornice. Se non specificato, il valore predefinito è una larghezza naturale.

  • callback

    funzione elemento facoltativo

    Il parametro callback ha il seguente aspetto: 

    (window?: Window) => void

    • finestra

      Window facoltativo

      Contiene i dettagli della finestra creata.

Resi

  • Promise<Window | undefined>

    Chrome 88 e versioni successive

    Le promise sono supportate solo per Manifest V3 e versioni successive, mentre le altre piattaforme devono utilizzare i callback.

get()

Promise 
chrome.windows.get(
  windowId: number,
  queryOptions?: QueryOptions,
  callback?: function,
): Promise<Window>

Recupera i dettagli di una finestra.

Parametri

  • windowId

    numero

  • queryOptions

    QueryOptions facoltativo

    Chrome 88 e versioni successive
  • callback

    funzione elemento facoltativo

    Il parametro callback ha il seguente aspetto: 

    (window: Window) => void

Resi

  • Promise<Window>

    Chrome 88 e versioni successive

    Le promise sono supportate solo per Manifest V3 e versioni successive, mentre le altre piattaforme devono utilizzare i callback.

getAll()

Promise 
chrome.windows.getAll(
  queryOptions?: QueryOptions,
  callback?: function,
): Promise<Window[]>

Recupera tutte le finestre.

Parametri

  • queryOptions

    QueryOptions facoltativo

    Chrome 88 e versioni successive
  • callback

    funzione elemento facoltativo

    Il parametro callback ha il seguente aspetto: 

    (windows: Window[]) => void

Resi

  • Promise<Window[]>

    Chrome 88 e versioni successive

    Le promise sono supportate solo per Manifest V3 e versioni successive, mentre le altre piattaforme devono utilizzare i callback.

getCurrent()

Promise 
chrome.windows.getCurrent(
  queryOptions?: QueryOptions,
  callback?: function,
): Promise<Window>

Recupera la finestra corrente.

Parametri

  • queryOptions

    QueryOptions facoltativo

    Chrome 88 e versioni successive
  • callback

    funzione elemento facoltativo

    Il parametro callback ha il seguente aspetto: 

    (window: Window) => void

Resi

  • Promise<Window>

    Chrome 88 e versioni successive

    Le promise sono supportate solo per Manifest V3 e versioni successive, mentre le altre piattaforme devono utilizzare i callback.

getLastFocused()

Promise 
chrome.windows.getLastFocused(
  queryOptions?: QueryOptions,
  callback?: function,
): Promise<Window>

Recupera la finestra che è stata attivata più di recente, in genere la finestra "in primo piano".

Parametri

  • queryOptions

    QueryOptions facoltativo

    Chrome 88 e versioni successive
  • callback

    funzione elemento facoltativo

    Il parametro callback ha il seguente aspetto: 

    (window: Window) => void

Resi

  • Promise<Window>

    Chrome 88 e versioni successive

    Le promise sono supportate solo per Manifest V3 e versioni successive, mentre le altre piattaforme devono utilizzare i callback.

remove()

Promise 
chrome.windows.remove(
  windowId: number,
  callback?: function,
): Promise<void>

Rimuove (chiude) una finestra e tutte le schede al suo interno.

Parametri

  • windowId

    numero

  • callback

    funzione elemento facoltativo

    Il parametro callback ha il seguente aspetto: 

    () => void

Resi

  • Promise<void>

    Chrome 88 e versioni successive

    Le promise sono supportate solo per Manifest V3 e versioni successive, mentre le altre piattaforme devono utilizzare i callback.

update()

Promise 
chrome.windows.update(
  windowId: number,
  updateInfo: object,
  callback?: function,
): Promise<Window>

Aggiorna le proprietà di una finestra. Specifica solo le proprietà da modificare. Le proprietà non specificate rimangono invariate.

Parametri

  • windowId

    numero

  • updateInfo

    oggetto

    • drawAttention

      boolean facoltativo

      Se true, la finestra viene visualizzata in modo da attirare l'attenzione dell'utente, senza modificare la finestra attiva. L'effetto dura finché l'utente non sposta lo stato attivo sulla finestra. Questa opzione non ha effetto se la finestra è già attiva. Imposta su false per annullare una richiesta drawAttention precedente.

    • Focalizzati

      boolean facoltativo

      Se true, porta la finestra in primo piano; non può essere combinato con lo stato "minimized". Se false, porta in primo piano la finestra successiva nell'ordine z; non può essere combinato con lo stato "fullscreen" o "maximized".

    • altezza

      number optional

      L'altezza in pixel della finestra ridimensionata. Questo valore viene ignorato per i pannelli.

    • sinistra

      number optional

      L'offset dal bordo sinistro dello schermo in pixel per spostare la finestra. Questo valore viene ignorato per i pannelli.

    • stato

      WindowState facoltativo

      Il nuovo stato della finestra. Gli stati "minimized", "maximized" e "fullscreen" non possono essere combinati con "left", "top", "width" o "height".

    • in alto

      number optional

      L'offset dal bordo superiore dello schermo in cui spostare la finestra in pixel. Questo valore viene ignorato per i pannelli.

    • larghezza

      number optional

      La larghezza in pixel per il ridimensionamento della finestra. Questo valore viene ignorato per i pannelli.

  • callback

    funzione elemento facoltativo

    Il parametro callback ha il seguente aspetto: 

    (window: Window) => void

Resi

  • Promise<Window>

    Chrome 88 e versioni successive

    Le promise sono supportate solo per Manifest V3 e versioni successive, mentre le altre piattaforme devono utilizzare i callback.

Eventi

onBoundsChanged

Chrome 86 e versioni successive 
chrome.windows.onBoundsChanged.addListener(
  callback: function,
)

Attivato quando una finestra è stata ridimensionata; questo evento viene inviato solo quando vengono applicati i nuovi limiti e non per le modifiche in corso.

Parametri

  • callback

    funzione

    Il parametro callback ha il seguente aspetto: 

    (window: Window) => void

onCreated

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

Attivato quando viene creata una finestra.

Parametri

  • callback

    funzione

    Chrome 46+

    Il parametro callback ha il seguente aspetto: 

    (window: Window) => void

    • finestra

      Finestra

      Dettagli della finestra creata.

  • filtri

    object facoltativo

    • windowTypes

      WindowType[]

      Condizioni che il tipo di finestra in fase di creazione deve soddisfare. Per impostazione predefinita, soddisfa ['normal', 'popup'].

onFocusChanged

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

Attivato quando la finestra attualmente attiva cambia. Restituisce chrome.windows.WINDOW_ID_NONE se tutte le finestre di Chrome hanno perso lo stato attivo. Nota: su alcuni gestori di finestre Linux, WINDOW_ID_NONE viene sempre inviato immediatamente prima di un passaggio da una finestra di Chrome a un'altra.

Parametri

  • callback

    funzione

    Chrome 46+

    Il parametro callback ha il seguente aspetto: 

    (windowId: number) => void

    • windowId

      numero

      ID della finestra appena attivata.

  • filtri

    object facoltativo

    • windowTypes

      WindowType[]

      Condizioni che il tipo di finestra rimosso deve soddisfare. Per impostazione predefinita, soddisfa ['normal', 'popup'].

onRemoved

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

Attivato quando una finestra viene rimossa (chiusa).

Parametri

  • callback

    funzione

    Chrome 46+

    Il parametro callback ha il seguente aspetto: 

    (windowId: number) => void

    • windowId

      numero

      ID della finestra rimossa.

  • filtri

    object facoltativo

    • windowTypes

      WindowType[]

      Condizioni che il tipo di finestra rimosso deve soddisfare. Per impostazione predefinita, soddisfa ['normal', 'popup'].