chrome.windows

Aktualisierungsdatum: 2026-09-25 robots: noindex

Beschreibung

Verwenden Sie die chrome.windows API, um mit Browserfenstern zu interagieren. Mit dieser API können Sie Fenster im Browser erstellen, ändern und neu anordnen.

Manifest

Wenn angefordert, enthält ein windows.Window ein Array von tabs.Tab-Objekten. Sie müssen die Berechtigung "tabs" in Ihrem Manifest deklarieren, wenn Sie Zugriff auf die Properties url, pendingUrl, title oder favIconUrl von tabs.Tab benötigen. Beispiel:

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

Das aktuelle Fenster

Viele Funktionen im Erweiterungssystem akzeptieren ein optionales windowId-Argument, das standardmäßig auf das aktuelle Fenster festgelegt ist.

Das aktuelle Fenster ist das Fenster, das den Code enthält, der gerade ausgeführt wird. Das kann sich vom obersten oder aktiven Fenster unterscheiden.

Angenommen, eine Erweiterung erstellt einige Tabs oder Fenster aus einer einzelnen HTML-Datei und diese HTML-Datei enthält einen Aufruf von tabs.query(). Das aktuelle Fenster ist das Fenster, das die Seite mit dem Aufruf enthält, unabhängig davon, welches das oberste Fenster ist.

Bei Service Workern wird der Wert des aktuellen Fensters auf das zuletzt aktive Fenster zurückgesetzt. Unter Umständen gibt es kein aktuelles Fenster für Hintergrundseiten.

Beispiele

Zwei Fenster mit jeweils einem Tab

Wenn Sie diese API ausprobieren möchten, installieren Sie das Windows-API-Beispiel aus dem Repository chrome-extension-samples.

Typen

CreateType

Chrome 44 und höher

Gibt an, welcher Typ von Browserfenster erstellt werden soll. „panel“ wird nicht mehr unterstützt und ist nur für vorhandene Erweiterungen auf der Zulassungsliste unter ChromeOS verfügbar.

Enum

„normal“
Gibt das Fenster als Standardfenster an.

„popup“
Gibt das Fenster als Pop-up-Fenster an.

„panel“
Gibt das Fenster als Bereich an.

QueryOptions

Chrome 88 und höher

Attribute

  • populate

    Boolesch optional

    Wenn „true“, hat das windows.Window-Objekt ein tabs-Attribut, das eine Liste der tabs.Tab-Objekte enthält. Die Tab-Objekte enthalten die Properties url, pendingUrl, title und favIconUrl nur, wenn die Manifestdatei der Erweiterung die Berechtigung "tabs" enthält.

  • windowTypes

    WindowType[] optional

    Wenn festgelegt, wird das zurückgegebene windows.Window nach seinem Typ gefiltert. Wenn nicht festgelegt, wird der Standardfilter auf ['normal', 'popup'] gesetzt.

Window

Attribute

  • alwaysOnTop

    boolean

    Gibt an, ob das Fenster immer im Vordergrund angezeigt wird.

  • Fokussiert

    boolean

    Gibt an, ob das Fenster derzeit das aktive Fenster ist.

  • Höhe

    number optional

    Die Höhe des Fensters in Pixeln, einschließlich des Rahmens. Unter Umständen wird einem Fenster keine height-Eigenschaft zugewiesen, z. B. wenn geschlossene Fenster über die sessions API abgefragt werden.

  • id

    number optional

    Die ID des Fensters. Fenster-IDs sind innerhalb einer Browsersitzung eindeutig. Unter Umständen wird einem Fenster keine ID-Property zugewiesen, z. B. wenn Sie Fenster mit der sessions API abfragen. In diesem Fall ist möglicherweise eine Sitzungs-ID vorhanden.

  • Inkognito

    boolean

    Gibt an, ob das Fenster im Inkognitomodus geöffnet ist.

  • links

    number optional

    Der Offset des Fensters vom linken Bildschirmrand in Pixeln. Unter Umständen wird einem Fenster keine left-Eigenschaft zugewiesen, z. B. wenn geschlossene Fenster über die sessions API abgefragt werden.

  • sessionId

    String optional

    Die Sitzungs-ID, die zur eindeutigen Identifizierung eines Fensters verwendet wird. Sie wird über die sessions API abgerufen.

  • Bundesstaat

    WindowState optional

    Der Status dieses Browserfensters.

  • tabs

    Tab[] optional

    Array von tabs.Tab-Objekten, die die aktuellen Tabs im Fenster darstellen.

  • oben

    number optional

    Der Offset des Fensters vom oberen Bildschirmrand in Pixeln. Unter Umständen wird einem Fenster keine top-Eigenschaft zugewiesen, z. B. wenn geschlossene Fenster über die sessions API abgefragt werden.

  • Typ

    WindowType optional

    Der Typ des Browserfensters.

  • Breite

    number optional

    Die Breite des Fensters in Pixeln, einschließlich des Rahmens. Unter Umständen wird einem Fenster keine width-Eigenschaft zugewiesen, z. B. wenn geschlossene Fenster über die sessions API abgefragt werden.

WindowState

Chrome 44 und höher

Der Status dieses Browserfensters. Unter Umständen wird einem Fenster keine state-Eigenschaft zugewiesen, z. B. wenn geschlossene Fenster über die sessions API abgefragt werden.

Enum

„normal“
Normaler Fensterstatus (nicht minimiert, maximiert oder im Vollbildmodus).

„minimized“
Minimierter Fensterstatus.

„maximized“
Maximierter Fensterstatus.

„fullscreen“
Vollbildfensterstatus.

WindowType

Chrome 44 und höher

Der Typ des Browserfensters. Unter Umständen wird einem Fenster keine type-Eigenschaft zugewiesen, z. B. wenn geschlossene Fenster über die sessions API abgefragt werden.

Enum

„normal“
Ein normales Browserfenster.

„popup“
Ein Browser-Pop-up.

„panel“
In dieser API verworfen. Ein Fenster im Stil eines Chrome-App-Panels. Erweiterungen können nur ihre eigenen Fenster sehen.

„app“
In dieser API eingestellt. Ein Chrome-App-Fenster. Erweiterungen können nur die Fenster ihrer eigenen App sehen.

„devtools“
Ein Entwicklertools-Fenster.

Attribute

WINDOW_ID_CURRENT

Der windowId-Wert, der das aktuelle Fenster darstellt.

Wert

–2

WINDOW_ID_NONE

Der „windowId“-Wert, der das Fehlen eines Chrome-Browserfensters darstellt.

Wert

–1

Methoden

create()

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

Erstellt (öffnet) ein neues Browserfenster mit optionalen Größen-, Positions- oder Standard-URLs.

Parameter

  • createData

    object optional

    • Fokussiert

      Boolesch optional

      Wenn true, wird ein aktives Fenster geöffnet. Wenn false, wird ein inaktives Fenster geöffnet.

    • Höhe

      number optional

      Die Höhe des neuen Fensters in Pixeln, einschließlich des Rahmens. Wenn nichts angegeben ist, wird standardmäßig eine natürliche Höhe verwendet.

    • Inkognito

      Boolesch optional

      Gibt an, ob das neue Fenster ein Inkognitofenster sein soll.

    • links

      number optional

      Die Anzahl der Pixel, um das neue Fenster vom linken Bildschirmrand aus zu positionieren. Wenn nicht angegeben, wird das neue Fenster auf natürliche Weise vom zuletzt fokussierten Fenster versetzt. Dieser Wert wird für Panels ignoriert.

    • setSelfAsOpener

      Boolesch optional

      Chrome 64 und höher

      Wenn true, wird „window.opener“ des neu erstellten Fensters auf den Aufrufer gesetzt und befindet sich in derselben Einheit verwandter Browserkontexte wie der Aufrufer.

    • Bundesstaat

      WindowState optional

      Chrome 44 und höher

      Der ursprüngliche Status des Fensters. Die Status minimized, maximized und fullscreen können nicht mit left, top, width oder height kombiniert werden.

    • tabId

      number optional

      Die ID des Tabs, der dem neuen Fenster hinzugefügt werden soll.

    • oben

      number optional

      Die Anzahl der Pixel, um das neue Fenster vom oberen Bildschirmrand zu positionieren. Wenn nicht angegeben, wird das neue Fenster auf natürliche Weise vom zuletzt fokussierten Fenster versetzt. Dieser Wert wird für Panels ignoriert.

    • Typ

      CreateType optional

      Gibt an, welcher Typ von Browserfenster erstellt werden soll.

    • URL

      string | string[] optional

      Eine URL oder ein Array von URLs, die als Tabs im Fenster geöffnet werden sollen. Vollständig qualifizierte URLs müssen ein Schema enthalten, z.B. „http://www.google.com“ und nicht „www.google.com“. Nicht vollständig qualifizierte URLs werden als relativ innerhalb der Erweiterung betrachtet. Standardmäßig wird die Seite „Neuer Tab“ verwendet.

    • Breite

      number optional

      Die Breite des neuen Fensters in Pixeln, einschließlich des Rahmens. Wenn nichts angegeben ist, wird standardmäßig die natürliche Breite verwendet.

  • callback

    Funktion optional

    Der Parameter callback sieht so aus: 

    (window?: Window) => void

    • Fenster

      Fenster optional

      Enthält Details zum erstellten Fenster.

Ausgabe

  • Promise<Window | undefined>

    Chrome 88 und höher

    Promises werden nur für Manifest V3 und höher unterstützt. Auf anderen Plattformen müssen Callbacks verwendet werden.

get()

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

Ruft Details zu einem Fenster ab.

Parameter

  • windowId

    Zahl

  • queryOptions

    QueryOptions optional

    Chrome 88 und höher
  • callback

    Funktion optional

    Der Parameter callback sieht so aus: 

    (window: Window) => void

Ausgabe

  • Promise<Window>

    Chrome 88 und höher

    Promises werden nur für Manifest V3 und höher unterstützt. Auf anderen Plattformen müssen Callbacks verwendet werden.

getAll()

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

Ruft alle Fenster ab.

Parameter

  • queryOptions

    QueryOptions optional

    Chrome 88 und höher
  • callback

    Funktion optional

    Der Parameter callback sieht so aus: 

    (windows: Window[]) => void

Ausgabe

  • Promise<Window[]>

    Chrome 88 und höher

    Promises werden nur für Manifest V3 und höher unterstützt. Auf anderen Plattformen müssen Callbacks verwendet werden.

getCurrent()

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

Ruft das aktuelle Fenster ab.

Parameter

  • queryOptions

    QueryOptions optional

    Chrome 88 und höher
  • callback

    Funktion optional

    Der Parameter callback sieht so aus: 

    (window: Window) => void

Ausgabe

  • Promise<Window>

    Chrome 88 und höher

    Promises werden nur für Manifest V3 und höher unterstützt. Auf anderen Plattformen müssen Callbacks verwendet werden.

getLastFocused()

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

Ruft das Fenster ab, das zuletzt im Fokus stand, in der Regel das „oberste“ Fenster.

Parameter

  • queryOptions

    QueryOptions optional

    Chrome 88 und höher
  • callback

    Funktion optional

    Der Parameter callback sieht so aus: 

    (window: Window) => void

Ausgabe

  • Promise<Window>

    Chrome 88 und höher

    Promises werden nur für Manifest V3 und höher unterstützt. Auf anderen Plattformen müssen Callbacks verwendet werden.

remove()

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

Entfernt (schließt) ein Fenster und alle darin enthaltenen Tabs.

Parameter

  • windowId

    Zahl

  • callback

    Funktion optional

    Der Parameter callback sieht so aus: 

    () => void

Ausgabe

  • Promise<void>

    Chrome 88 und höher

    Promises werden nur für Manifest V3 und höher unterstützt. Auf anderen Plattformen müssen Callbacks verwendet werden.

update()

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

Aktualisiert die Eigenschaften eines Fensters. Geben Sie nur die Properties an, die geändert werden sollen. Nicht angegebene Properties bleiben unverändert.

Parameter

  • windowId

    Zahl

  • updateInfo

    Objekt

    • drawAttention

      Boolesch optional

      Wenn true, wird das Fenster so angezeigt, dass die Aufmerksamkeit des Nutzers darauf gelenkt wird, ohne dass sich das aktive Fenster ändert. Der Effekt bleibt so lange bestehen, bis der Nutzer den Fokus auf das Fenster ändert. Diese Option hat keine Auswirkungen, wenn das Fenster bereits den Fokus hat. Legen Sie false fest, um eine vorherige drawAttention-Anfrage zu stornieren.

    • Fokussiert

      Boolesch optional

      Wenn true, wird das Fenster in den Vordergrund geholt. Kann nicht mit dem Status „minimiert“ kombiniert werden. Wenn false, wird das nächste Fenster in der Z-Reihenfolge in den Vordergrund geholt. Kann nicht mit dem Status „Vollbild“ oder „Maximiert“ kombiniert werden.

    • Höhe

      number optional

      Die Höhe, auf die das Fenster in Pixeln skaliert werden soll. Dieser Wert wird für Panels ignoriert.

    • links

      number optional

      Der Versatz vom linken Bildschirmrand, um das Fenster in Pixel zu verschieben. Dieser Wert wird für Panels ignoriert.

    • Bundesstaat

      WindowState optional

      Der neue Status des Fensters. Die Status „minimized“, „maximized“ und „fullscreen“ können nicht mit „left“, „top“, „width“ oder „height“ kombiniert werden.

    • oben

      number optional

      Der Versatz vom oberen Bildschirmrand, um das Fenster in Pixeln zu verschieben. Dieser Wert wird für Panels ignoriert.

    • Breite

      number optional

      Die Breite, auf die das Fenster in Pixeln skaliert werden soll. Dieser Wert wird für Panels ignoriert.

  • callback

    Funktion optional

    Der Parameter callback sieht so aus: 

    (window: Window) => void

Ausgabe

  • Promise<Window>

    Chrome 88 und höher

    Promises werden nur für Manifest V3 und höher unterstützt. Auf anderen Plattformen müssen Callbacks verwendet werden.

Ereignisse

onBoundsChanged

Chrome 86 und höher 
chrome.windows.onBoundsChanged.addListener(
  callback: function,
)

Wird ausgelöst, wenn die Größe eines Fensters geändert wurde. Dieses Ereignis wird nur ausgelöst, wenn die neuen Grenzen übernommen werden, nicht bei laufenden Änderungen.

Parameter

  • callback

    Funktion

    Der Parameter callback sieht so aus: 

    (window: Window) => void

onCreated

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

Wird ausgelöst, wenn ein Fenster erstellt wird.

Parameter

  • callback

    Funktion

    Chrome 46 und höher

    Der Parameter callback sieht so aus: 

    (window: Window) => void

  • Filter

    object optional

    • windowTypes

      WindowType[]

      Bedingungen, die der Typ des Fensters, das erstellt wird, erfüllen muss. Standardmäßig wird ['normal', 'popup'] erfüllt.

onFocusChanged

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

Wird ausgelöst, wenn sich das aktuell fokussierte Fenster ändert. Gibt chrome.windows.WINDOW_ID_NONE zurück, wenn alle Chrome-Fenster den Fokus verloren haben. Hinweis:Bei einigen Linux-Fenstermanagern wird WINDOW_ID_NONE immer unmittelbar vor dem Wechsel von einem Chrome-Fenster zu einem anderen gesendet.

Parameter

  • callback

    Funktion

    Chrome 46 und höher

    Der Parameter callback sieht so aus: 

    (windowId: number) => void

    • windowId

      Zahl

      ID des neu fokussierten Fensters.

  • Filter

    object optional

    • windowTypes

      WindowType[]

      Bedingungen, die erfüllt sein müssen, damit der Typ des Fensters entfernt werden kann. Standardmäßig wird ['normal', 'popup'] erfüllt.

onRemoved

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

Wird ausgelöst, wenn ein Fenster entfernt (geschlossen) wird.

Parameter

  • callback

    Funktion

    Chrome 46 und höher

    Der Parameter callback sieht so aus: 

    (windowId: number) => void

    • windowId

      Zahl

      Die ID des entfernten Fensters.

  • Filter

    object optional

    • windowTypes

      WindowType[]

      Bedingungen, die erfüllt sein müssen, damit der Typ des Fensters entfernt werden kann. Standardmäßig wird ['normal', 'popup'] erfüllt.