chrome.windows

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.

Manifest

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

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

La finestra attuale

Molte funzioni nel sistema di estensioni prendono un argomento windowId facoltativo, che per impostazione predefinita finestra corrente.

La finestra attuale è quella che contiene il codice attualmente in esecuzione. È è importante capire che può essere diversa dalla finestra più in alto o con lo stato attivo.

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

Nel caso dei lavoratori di servizio, il valore della finestra attuale torna all'ultimo servizio attivo finestra. In alcuni casi, le pagine in background potrebbero non essere visualizzate al momento.

Esempi

Per provare questa API, installa l'esempio dell'API Windows da chrome-extension-samples repository Git.

Tipi

CreateType

Chrome 44 e versioni successive .

Specifica il tipo di finestra del browser da creare. "panel" è deprecata 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 un riquadro.

QueryOptions

Chrome 88 e versioni successive .

Proprietà

• compilare

  booleano 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 il criterio non viene configurato, il filtro predefinito è impostato su ['normal', 'popup'].

Window

Proprietà

• alwaysOnTop

  booleano

  Indica se la finestra è impostata per essere sempre in alto.

• Focalizzati

  booleano

  Se la finestra è attualmente selezionata.

• altezza

  numero facoltativo

  L'altezza della finestra, incluso il frame, in pixel. In alcuni casi, a una finestra potrebbe non essere assegnata una proprietà height. ad esempio, quando esegui query su finestre chiuse dall'API sessions.

• 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 su finestre utilizzando l'API sessions, nel qual caso potrebbe essere presente un ID sessione.

• in incognito

  booleano

  Indica se la finestra è in incognito.

• a sinistra

  numero facoltativo

  L'offset della finestra dal bordo sinistro dello schermo, in pixel. In alcuni casi, a una finestra potrebbe non essere assegnata una proprietà left. ad esempio, quando esegui query su finestre chiuse dall'API sessions.

• sessionId

  stringa facoltativo

  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

  Scheda[] facoltativo

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

• in alto

  numero facoltativo

  L'offset della finestra dal bordo superiore dello schermo in pixel. In alcuni casi, a una finestra potrebbe non essere assegnata una proprietà top. ad esempio, quando esegui query su finestre chiuse dall'API sessions.

• tipo

  WindowType facoltativo

  Il tipo di finestra del browser.

• larghezza

  numero facoltativo

  La larghezza della finestra, incluso il frame, in pixel. In alcuni casi, a una finestra potrebbe non essere assegnata una proprietà width. ad esempio, quando esegui query su finestre chiuse dall'API sessions.

WindowState

Chrome 44 e versioni successive .

Lo stato di questa finestra del browser. In alcuni casi, a una finestra potrebbe non essere assegnata una proprietà state. ad esempio, quando esegui query su finestre chiuse dall'API sessions.

Enum

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

"minimized"
Stato della finestra ridotta a icona.

"maximized"
Stato della finestra ingrandita.

"fullscreen"
Stato della finestra a schermo intero.

"locked-fullscreen"
Stato della finestra a schermo intero bloccata. Questo stato a schermo intero non può essere disattivato tramite un'azione dell'utente ed è disponibile solo per le estensioni incluse nella lista consentita su ChromeOS.

WindowType

Chrome 44 e versioni successive .

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 finestra del browser normale.

"popup"
Un 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 riquadri.

"app"
Deprecata in questa API. Una finestra dell'app di Chrome. Le estensioni possono vedere soltanto le proprie finestre dell'app.

"devtools"
Una finestra Strumenti per sviluppatori.

Proprietà

WINDOW_ID_CURRENT

Il valore windowId che rappresenta la finestra attuale.

Valore

-2

WINDOW_ID_NONE

Il valore windowId che rappresenta l'assenza di una finestra del browser Chrome.

Valore

-1

Metodi

create()

Promesso .

chrome.windows.create(
  createData?: object,
  callback?: function,
)

Crea (apre) una nuova finestra del browser in cui sono forniti eventuali URL predefiniti relativi a dimensioni, posizione o valori predefiniti.

Parametri

• createData

  oggetto facoltativo

  • Focalizzati

    booleano facoltativo

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

  • altezza

    numero facoltativo

    L'altezza in pixel della nuova finestra, incluso il frame. Se non specificata, 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 viene spostata naturalmente rispetto all'ultima finestra con lo stato attivo. Questo valore viene ignorato per i riquadri.

  • setSelfAsOpener

    booleano facoltativo

    Chrome 64 e versioni successive .

    Se true, viene restituito il valore "window.opener" della finestra appena creata è impostato per il 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

    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 viene spostata naturalmente rispetto all'ultima finestra con lo stato attivo. 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 qualificati 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 specificata, il valore predefinito è una larghezza naturale.

• callback

  funzione facoltativa

  Il parametro callback ha il seguente aspetto:

  (window?: Window) => void

  • finestra

    Finestra facoltativa

    Contiene i dettagli sulla finestra creata.

Resi

• Promise<Window | non definito>

  Chrome 88 e versioni successive .

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

get()

Promesso .

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

    Finestra

Resi

• Promise<Window>

  Chrome 88 e versioni successive .

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

getAll()

Promesso .

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[]

Resi

• Promise<Window[]>

  Chrome 88 e versioni successive .

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

getCurrent()

Promesso .

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

    Finestra

Resi

• Promise<Window>

  Chrome 88 e versioni successive .

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

getLastFocused()

Promesso .

chrome.windows.getLastFocused(
  queryOptions?: QueryOptions,
  callback?: function,
)

Restituisce la finestra sulla quale è stato attivato l'ultimo elemento, 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

    Finestra

Resi

• Promise<Window>

  Chrome 88 e versioni successive .

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

remove()

Promesso .

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

Resi

• Promesso<void>

  Chrome 88 e versioni successive .

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

update()

Promesso .

chrome.windows.update(
  windowId: number,
  updateInfo: object,
  callback?: function,
)

Aggiorna le proprietà di una finestra. Specificare solo le proprietà da modificare. le proprietà non specificate non sono state modificate.

Parametri

• windowId

  numero

• updateInfo

  oggetto

  • drawAttention

    booleano facoltativo

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

  • Focalizzati

    booleano facoltativo

    Se true, porta il finestrino in primo piano; non può essere combinato con lo stato "ridotto". Se false, porta in primo piano la finestra successiva dell'ordine Z; non può essere combinato con lo stato "schermo intero" o "massimizzato".

  • altezza

    numero facoltativo

    L'altezza in pixel per ridimensionare la finestra. Questo valore viene ignorato per i riquadri.

  • a sinistra

    numero facoltativo

    L'offset dal bordo sinistro dello schermo su cui spostare la finestra, espressa in pixel. Questo valore viene ignorato per i riquadri.

  • stato

    WindowState facoltativo

    Il nuovo stato della finestra. Le opzioni "minimizzato", "ingrandito" e "a schermo intero" gli stati non possono essere combinati con "left", "top", "width" o "height".

  • in alto

    numero facoltativo

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

  • larghezza

    numero facoltativo

    La larghezza in pixel per ridimensionare la finestra. Questo valore viene ignorato per i riquadri.

• callback

  funzione facoltativa

  Il parametro callback ha il seguente aspetto:

  (window: Window) => void

  • finestra

    Finestra

Resi

• Promise&lt;Window&gt;

  Chrome 88 e versioni successive .

  Le promesse 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 viene ridimensionata. questo evento viene inviato solo quando viene eseguito il commit dei nuovi limiti, non per le modifiche in corso.

Parametri

• callback

  funzione

  Il parametro callback ha il seguente aspetto:

  (window: Window) => void

  • finestra

    Finestra

onCreated

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

Attivato quando viene creata una finestra.

Parametri

• callback

  funzione

  Chrome 46 e versioni successive .

  Il parametro callback ha il seguente aspetto:

  (window: Window) => void

  • finestra

    Finestra

    Dettagli della finestra creata.

• filtri

  oggetto facoltativo

  • windowTypes

    WindowType[]

    Condizioni che devono essere soddisfatte dal tipo di finestra che viene creato. Per impostazione predefinita, soddisfa ['normal', 'popup'].

onFocusChanged

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

Attivato quando cambia la finestra attualmente evidenziata. Restituisce chrome.windows.WINDOW_ID_NONE se tutte le finestre di Chrome non sono più attive. Nota:su 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 successive .

  Il parametro callback ha il seguente aspetto:

  (windowId: number) => void

  • windowId

    numero

    ID della finestra appena evidenziata.

• filtri

  oggetto facoltativo

  • windowTypes

    WindowType[]

    Condizioni che devono essere soddisfatte dal tipo di finestra da rimuovere. Per impostazione predefinita, soddisfa ['normal', 'popup'].

onRemoved

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

Attivato quando viene rimossa (chiusa una finestra)

Parametri

• callback

  funzione

  Chrome 46 e versioni successive .

  Il parametro callback ha il seguente aspetto:

  (windowId: number) => void

  • windowId

    numero

    ID della finestra rimossa.

• filtri

  oggetto facoltativo

  • windowTypes

    WindowType[]

    Condizioni che devono essere soddisfatte dal tipo di finestra da rimuovere. Per impostazione predefinita, soddisfa ['normal', 'popup'].