browser.windows

Beschrijving

Gebruik de chrome.windows API om te communiceren met browservensters. Je kunt deze API gebruiken om vensters in de browser te maken, aan te passen en opnieuw te rangschikken.

Rechten

Indien aangevraagd, bevat een windows.Window een matrix van tabs.Tab-objecten. Je moet het recht "tabs" declareren in je manifest als je toegang nodig hebt tot de eigenschappen url, pendingUrl, title of favIconUrl van tabs.Tab. Voorbeeld:

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

Concepten en gebruik

Het huidige venster

Veel functies in het extensiesysteem hebben een optioneel argument windowId, dat standaard het huidige venster is.

Het huidige venster is het venster dat de code bevat die op dat moment wordt uitgevoerd. Het is belangrijk om te beseffen dat dit kan verschillen van het bovenste of gefocuste venster.

Stel dat een extensie een paar tabbladen of vensters maakt op basis van één HTML-bestand en dat het HTML-bestand een aanroep naar tabs.query() bevat. Het huidige venster is het venster met de pagina die de aanroep heeft gedaan, ongeacht wat het bovenste venster is.

In het geval van servicemedewerkers valt de waarde van het huidige venster terug naar het laatst actieve venster. In sommige omstandigheden is er misschien geen huidig venster voor achtergrondpagina's.

Voorbeelden

Als je deze API wilt proberen, installeer je het voorbeeld van de Windows API uit de repository chrome-extension-samples.

2 vensters met elk 1 tabblad
2 vensters, elk met 1 tabblad.

Typen

CreateType

Chrome 44+ browser.* sinds Chrome 148

Hiermee geef je aan welk type browservenster je wilt maken. 'panel' is beëindigd en is alleen beschikbaar voor bestaande extensies op de toelatingslijst in ChromeOS.

Enum

"normal"
Hiermee wordt het venster ingesteld als een standaardvenster.

"popup"
Hiermee wordt het venster ingesteld als pop-upvenster.

"panel"
Hiermee wordt het venster ingesteld als een deelvenster.

QueryOptions

Chrome 88+ browser.* sinds Chrome 148

Eigenschappen

  • invullen

    booleaans optioneel

    Als dit waar is, heeft het object windows.Window een property tabs die een lijst met de objecten tabs.Tab bevat. De Tab-objecten bevatten alleen de eigenschappen url, pendingUrl, title en favIconUrl als het manifestbestand van de extensie het recht "tabs" bevat.

  • windowTypes

    WindowType[] optioneel

    Als deze optie is ingesteld, wordt de geretourneerde windows.Window gefilterd op basis van het type. Als je dit beleid niet instelt, wordt het standaardfilter ingesteld op ['normal', 'popup'].

Window

Eigenschappen

  • alwaysOnTop

    booleaans

    Of het venster is ingesteld om altijd bovenaan te staan.

  • gefocust

    booleaans

    Of het venster op dit moment het venster met focus is.

  • hoogte

    number optioneel

    De hoogte van het venster, inclusief het frame, in pixels. In sommige omstandigheden wordt er geen height-property aan een venster toegewezen, bijvoorbeeld als je gesloten vensters opvraagt via de sessions API.

  • id

    number optioneel

    De ID van het venster. Venster-ID's zijn uniek binnen een browsersessie. In sommige omstandigheden wordt er misschien geen ID-property aan een venster toegewezen, bijvoorbeeld als je vensters opvraagt via de sessions API. In dat geval is er misschien een sessie-ID aanwezig.

  • incognito

    booleaans

    Of het venster incognito is.

  • links

    number optioneel

    De afstand van het venster tot de linkerrand van het scherm in pixels. In sommige omstandigheden wordt er geen left-property aan een venster toegewezen, bijvoorbeeld als je gesloten vensters opvraagt via de sessions API.

  • sessionId

    tekenreeks optioneel

    De sessie-ID die wordt gebruikt om een venster uniek te identificeren, verkregen via de sessions API.

  • status

    WindowState optioneel

    De status van dit browservenster.

  • tabbladen

    Tab[] optioneel

    Matrix van tabs.Tab-objecten die de huidige tabbladen in het venster vertegenwoordigen.

  • boven

    number optioneel

    De afstand van het venster tot de bovenrand van het scherm in pixels. In sommige omstandigheden wordt er geen top-property aan een venster toegewezen, bijvoorbeeld als je gesloten vensters opvraagt via de sessions API.

  • type

    WindowType optioneel

    Het type browservenster.

  • breedte

    number optioneel

    De breedte van het venster, inclusief het frame, in pixels. In sommige omstandigheden wordt er geen width-property aan een venster toegewezen, bijvoorbeeld als je gesloten vensters opvraagt via de sessions API.

WindowState

Chrome 44+ browser.* sinds Chrome 148

De status van dit browservenster. In sommige omstandigheden wordt er geen state-property aan een venster toegewezen, bijvoorbeeld als je gesloten vensters opvraagt via de sessions API.

Enum

normal
Normale vensterstatus (niet geminimaliseerd, gemaximaliseerd of op volledig scherm).

"minimized"
De vensterstatus is geminimaliseerd.

"maximized"
Gemaximaliseerde vensterstatus.

"fullscreen"
Vensterstatus Volledig scherm.

WindowType

Chrome 44+ browser.* sinds Chrome 148

Het type browservenster. In sommige omstandigheden wordt er geen type-property aan een venster toegewezen, bijvoorbeeld als je gesloten vensters opvraagt via de sessions-API.

Enum

normal
Een normaal browservenster.

popup
Een browserpop-up.

"panel"
Beëindigd in deze API. Een venster in de stijl van een Chrome-app-deelvenster. Extensies kunnen alleen hun eigen deelvensters zien.

"app"
Beëindigd in deze API. Een Chrome-app-venster. Extensies kunnen alleen de eigen vensters van de app zien.

"devtools"
Een venster met tools voor ontwikkelaars.

Eigenschappen

WINDOW_ID_CURRENT

De windowId-waarde die het huidige venster vertegenwoordigt.

Waarde

-2

WINDOW_ID_NONE

De windowId-waarde die de afwezigheid van een Chrome-browservenster vertegenwoordigt.

Waarde

-1

Methoden

create()

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

Maakt (opent) een nieuw browservenster met de optionele grootte, positie of standaard-URL die je hebt opgegeven.

Parameters

  • createData

    object optioneel

    • gefocust

      booleaans optioneel

      Als true, wordt een actief venster geopend. Als false, wordt een inactief venster geopend.

    • hoogte

      number optioneel

      De hoogte in pixels van het nieuwe venster, inclusief het frame. Als je niets invoert, wordt standaard een natuurlijke hoogte gebruikt.

    • incognito

      booleaans optioneel

      Of het nieuwe venster een incognitovenster moet zijn.

    • links

      number optioneel

      Het aantal pixels om het nieuwe venster te positioneren vanaf de linkerrand van het scherm. Als je dit niet opgeeft, wordt het nieuwe venster op een natuurlijke manier verschoven ten opzichte van het laatste venster waarop de focus lag. Deze waarde wordt genegeerd voor deelvensters.

    • setSelfAsOpener

      booleaans optioneel

      Chrome 64+ browser.* sinds Chrome 148

      Als true, wordt de 'window.opener' van het nieuwe venster ingesteld op de aanroeper en bevindt deze zich in dezelfde eenheid van gerelateerde browsecontexten als de aanroeper.

    • status

      WindowState optioneel

      Chrome 44+ browser.* sinds Chrome 148

      De beginstatus van het venster. De staten minimized, maximized en fullscreen kunnen niet worden gecombineerd met left, top, width of height.

    • tabId

      number optioneel

      De ID van het tabblad dat je aan het nieuwe venster wilt toevoegen.

    • boven

      number optioneel

      Het aantal pixels om het nieuwe venster te positioneren vanaf de bovenrand van het scherm. Als je dit niet opgeeft, wordt het nieuwe venster op een natuurlijke manier verschoven ten opzichte van het laatste venster waarop de focus lag. Deze waarde wordt genegeerd voor deelvensters.

    • type

      CreateType optioneel

      Hiermee geef je aan welk type browservenster je wilt maken.

    • url

      string | string[] optioneel

      Een URL of matrix van URL's die als tabbladen in het venster moeten worden geopend. Volledig gekwalificeerde URL's moeten een schema bevatten, bijvoorbeeld 'http://www.google.com', niet 'www.google.com'. Niet-volledig gekwalificeerde URL's worden als relatief beschouwd binnen de extensie. Standaard wordt de pagina Nieuw tabblad ingesteld.

    • breedte

      number optioneel

      De breedte in pixels van het nieuwe venster, inclusief het frame. Als je dit niet opgeeft, wordt standaard een natuurlijke breedte gebruikt.

Retourzendingen

  • Promise<Window | undefined>

    Chrome 88+ browser.* sinds Chrome 148

get()

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

Krijgt informatie over een venster.

Parameters

  • windowId

    getal

  • queryOptions

    QueryOptions optioneel

    Chrome 88+ browser.* sinds Chrome 148

Retourzendingen

  • Promise<Window>

    Chrome 88+ browser.* sinds Chrome 148

getAll()

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

Haalt alle vensters op.

Parameters

  • queryOptions

    QueryOptions optioneel

    Chrome 88+ browser.* sinds Chrome 148

Retourzendingen

  • Promise<Window[]>

    Chrome 88+ browser.* sinds Chrome 148

getCurrent()

browser.windows.getCurrent(
  queryOptions?: QueryOptions,
): Promise<Window>

Haalt het huidige venster op.

Parameters

  • queryOptions

    QueryOptions optioneel

    Chrome 88+ browser.* sinds Chrome 148

Retourzendingen

  • Promise<Window>

    Chrome 88+ browser.* sinds Chrome 148

getLastFocused()

browser.windows.getLastFocused(
  queryOptions?: QueryOptions,
): Promise<Window>

Haalt het venster op dat het laatst de focus had, meestal het venster 'bovenaan'.

Parameters

  • queryOptions

    QueryOptions optioneel

    Chrome 88+ browser.* sinds Chrome 148

Retourzendingen

  • Promise<Window>

    Chrome 88+ browser.* sinds Chrome 148

remove()

browser.windows.remove(
  windowId: number,
): Promise<void>

Verwijdert (sluit) een venster en alle tabbladen erin.

Parameters

  • windowId

    getal

Retourzendingen

  • Promise<void>

    Chrome 88+ browser.* sinds Chrome 148

update()

browser.windows.update(
  windowId: number,
  updateInfo: object,
): Promise<Window>

Updatet de eigenschappen van een venster. Voer alleen de property's in die moeten worden gewijzigd. Niet-ingevoerde property's blijven ongewijzigd.

Parameters

  • windowId

    getal

  • updateInfo

    object

    • drawAttention

      booleaans optioneel

      Als true, wordt het venster zo weergegeven dat de aandacht van de gebruiker op het venster wordt gevestigd, zonder het venster met de focus te wijzigen. Het effect blijft actief totdat de gebruiker de focus naar het venster verplaatst. Deze optie heeft geen effect als het venster al de focus heeft. Stel in op false om een eerder drawAttention-verzoek te annuleren.

    • gefocust

      booleaans optioneel

      Als true, wordt het venster op de voorgrond geplaatst. Kan niet worden gecombineerd met de status minimized. Als false, wordt het volgende venster in de z-volgorde naar de voorgrond gebracht. Kan niet worden gecombineerd met de status 'fullscreen' of 'maximized'.

    • hoogte

      number optioneel

      De hoogte in pixels waarnaar het formaat van het venster moet worden aangepast. Deze waarde wordt genegeerd voor deelvensters.

    • links

      number optioneel

      De afstand vanaf de linkerrand van het scherm waarnaar het venster moet worden verplaatst, in pixels. Deze waarde wordt genegeerd voor deelvensters.

    • status

      WindowState optioneel

      De nieuwe status van het venster. De statussen geminimaliseerd, gemaximaliseerd en volledig scherm kunnen niet worden gecombineerd met links, boven, breedte of hoogte.

    • boven

      number optioneel

      De afstand vanaf de bovenrand van het scherm waarnaar het venster moet worden verplaatst, in pixels. Deze waarde wordt genegeerd voor deelvensters.

    • breedte

      number optioneel

      De breedte in pixels waarnaar het formaat van het venster moet worden aangepast. Deze waarde wordt genegeerd voor deelvensters.

Retourzendingen

  • Promise<Window>

    Chrome 88+ browser.* sinds Chrome 148

Evenementen

onBoundsChanged

Chrome 86+ browser.* sinds Chrome 148 
browser.windows.onBoundsChanged.addListener(
  callback: function,
)

Wordt geactiveerd als het formaat van een venster is aangepast. Deze gebeurtenis wordt alleen verstuurd als de nieuwe grenzen zijn vastgelegd en niet voor wijzigingen die nog worden uitgevoerd.

Parameters

  • callback

    functie

    De parameter callback ziet er zo uit: 

    (window: Window) => void

onCreated

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

Wordt geactiveerd als er een venster wordt gemaakt.

Parameters

  • callback

    functie

    Chrome 46+ browser.* sinds Chrome 148

    De parameter callback ziet er zo uit: 

    (window: Window) => void

    • venster

      Venster

      Details van het gemaakte venster.

  • filters

    object optioneel

    • windowTypes

      WindowType[]

      Voorwaarden waaraan het type van het venster dat wordt gemaakt, moet voldoen. Standaard voldoet deze aan ['normal', 'popup'].

onFocusChanged

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

Wordt geactiveerd als het venster met de focus verandert. Retourneert chrome.windows.WINDOW_ID_NONE als alle Chrome-vensters de focus hebben verloren. Opmerking: In sommige Linux-vensterbeheerders wordt WINDOW_ID_NONE altijd onmiddellijk gestuurd voordat er wordt overgeschakeld van het ene Chrome-venster naar het andere.

Parameters

  • callback

    functie

    Chrome 46+ browser.* sinds Chrome 148

    De parameter callback ziet er zo uit: 

    (windowId: number) => void

    • windowId

      getal

      ID van het venster dat nu de focus heeft.

  • filters

    object optioneel

    • windowTypes

      WindowType[]

      Voorwaarden waaraan het type van het venster dat wordt verwijderd, moet voldoen. Standaard voldoet deze aan ['normal', 'popup'].

onRemoved

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

Wordt geactiveerd als een venster wordt verwijderd (gesloten).

Parameters

  • callback

    functie

    Chrome 46+ browser.* sinds Chrome 148

    De parameter callback ziet er zo uit: 

    (windowId: number) => void

    • windowId

      getal

      ID van het verwijderde venster.

  • filters

    object optioneel

    • windowTypes

      WindowType[]

      Voorwaarden waaraan het type van het venster dat wordt verwijderd, moet voldoen. Standaard voldoet deze aan ['normal', 'popup'].