chrome.windows

refresh date: 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

Bei einer Anfrage 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"],
  ...
}

Aktuelles Fenster

Viele Funktionen im Erweiterungssystem verwenden ein optionales windowId-Argument, das standardmäßig auf das aktuelle Fenster verweist.

Das aktuelle Fenster ist das Fenster, das den Code enthält, der gerade ausgeführt wird. Es ist wichtig zu wissen, dass sich dieses Fenster vom obersten oder fokussierten Fenster unterscheiden kann.

Angenommen, eine Erweiterung erstellt mehrere Tabs oder Fenster aus einer einzelnen HTML-Datei und die HTML-Datei enthält einen Aufruf von tabs.query(). Das aktuelle Fenster ist das Fenster, das die Seite enthält, die den Aufruf ausgeführt hat, unabhängig davon, welches Fenster das oberste ist.

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

Beispiele

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

Typen

CreateType

Chrome 44 oder 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 Steuerfeld an.

QueryOptions

Chrome 88 oder 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 der 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 werden soll.

• Fokussiert

  boolean

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

• Höhe

  number optional

  Die Höhe des Fensters einschließlich des Rahmens in Pixeln. In einigen Fällen wird einem Fenster möglicherweise kein height-Attribut 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. In einigen Fällen wird einem Fenster möglicherweise kein ID-Attribut zugewiesen, z. B. wenn Fenster über die sessions API abgefragt werden. In diesem Fall ist möglicherweise eine Sitzungs-ID vorhanden.

• inkognito

  boolean

  Gibt an, ob das Fenster ein Inkognitofenster ist.

• links

  number optional

  Der Abstand des Fensters vom linken Bildschirmrand in Pixeln. In einigen Fällen wird einem Fenster möglicherweise kein left-Attribut 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 und über die sessions API abgerufen wird.

• 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 Abstand des Fensters vom oberen Bildschirmrand in Pixeln. In einigen Fällen wird einem Fenster möglicherweise kein top-Attribut 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, einschließlich des Rahmens, in Pixeln. In einigen Fällen wird einem Fenster möglicherweise kein width-Attribut zugewiesen, z. B. wenn geschlossene Fenster über die sessions API abgefragt werden.

WindowState

Chrome 44 oder höher

Der Status dieses Browserfensters. In einigen Fällen wird einem Fenster möglicherweise kein state-Attribut zugewiesen, z. B. wenn geschlossene Fenster über die sessions API abgefragt werden.

Enum

"normal"
Normaler Fensterstatus (nicht minimiert, maximiert oder Vollbild).

"minimized"
Fenster ist minimiert.

"maximized"
Maximierter Fensterstatus.

"fullscreen"
Vollbildmodus.

WindowType

Chrome 44 oder höher

Der Typ des Browserfensters. Unter bestimmten Umständen wird einem Fenster möglicherweise kein type-Attribut zugewiesen, z. B. beim Abfragen geschlossener Fenster über die sessions API.

Enum

"normal"
Ein normales Browserfenster.

"popup"
Ein Browser-Pop-up.

"panel"
In dieser API verworfen. Ein Fenster im Bereichsstil einer Chrome-App. Erweiterungen können nur ihre eigenen Steuerfeld-Fenster sehen.

"app"
In dieser API verworfen. Ein Chrome-App-Fenster. Erweiterungen können nur ihre eigenen App-Fenster 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 optionaler Größe, Position oder Standard-URL.

Parameter

• createData

  Objekt 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 nicht angegeben, wird standardmäßig die 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 die das neue Fenster vom linken Bildschirmrand entfernt positioniert werden soll. Wenn nicht angegeben, wird das neue Fenster natürlich vom zuletzt fokussierten Fenster versetzt. Dieser Wert wird für Panels ignoriert.

  • setSelfAsOpener

    Boolesch optional

    Chrome 64 oder höher

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

  • Bundesstaat

    WindowState optional

    Chrome 44 oder höher

    Der Anfangszustand 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 die das neue Fenster vom oberen Bildschirmrand entfernt positioniert werden soll. Wenn nicht angegeben, wird das neue Fenster natürlich 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“, nicht „www.google.com“. Nicht vollständig qualifizierte URLs werden innerhalb der Erweiterung als relativ 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

  function 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 oder 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 oder höher
• callback

  function optional

  Der Parameter callback sieht so aus:

  (window: Window) => void

  • Fenster

    Fenster

Ausgabe

• Promise<Window>

  Chrome 88 oder 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 oder höher
• callback

  function optional

  Der Parameter callback sieht so aus:

  (windows: Window[]) => void

  • Fenster

    Fenster[]

Ausgabe

• Promise<Window[]>

  Chrome 88 oder 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 oder höher
• callback

  function optional

  Der Parameter callback sieht so aus:

  (window: Window) => void

  • Fenster

    Fenster

Ausgabe

• Promise<Window>

  Chrome 88 oder 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 fokussiert war – in der Regel das Fenster „oben“.

Parameter

• queryOptions

  QueryOptions optional

  Chrome 88 oder höher
• callback

  function optional

  Der Parameter callback sieht so aus:

  (window: Window) => void

  • Fenster

    Fenster

Ausgabe

• Promise<Window>

  Chrome 88 oder 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

  function optional

  Der Parameter callback sieht so aus:

  () => void

Ausgabe

• Promise<void>

  Chrome 88 oder 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 Attribute an, die geändert werden sollen. Nicht angegebene Attribute bleiben unverändert.

Parameter

• windowId

  Zahl

• updateInfo

  Objekt

  • drawAttention

    Boolesch optional

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

  • Fokussiert

    Boolesch optional

    Wenn true, wird das Fenster in den Vordergrund gebracht. Kann nicht mit dem Status „minimized“ kombiniert werden. Wenn false, wird das nächste Fenster in der Z-Reihenfolge in den Vordergrund gebracht; kann nicht mit dem Status „fullscreen“ oder „maximized“ kombiniert werden.

  • Höhe

    number optional

    Die Höhe, auf die die Größe des Fensters angepasst werden soll, in Pixeln. Dieser Wert wird für Panels ignoriert.

  • links

    number optional

    Der Abstand vom linken Bildschirmrand, um das Fenster in Pixeln 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 Abstand vom oberen Bildschirmrand, um das Fenster in Pixeln zu verschieben. Dieser Wert wird für Panels ignoriert.

  • Breite

    number optional

    Die Breite, auf die die Größe des Fensters angepasst werden soll, in Pixeln. Dieser Wert wird für Panels ignoriert.

• callback

  function optional

  Der Parameter callback sieht so aus:

  (window: Window) => void

  • Fenster

    Fenster

Ausgabe

• Promise<Window>

  Chrome 88 oder 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 oder 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 wurden, und nicht für laufende Änderungen.

Parameter

• callback

  Funktion

  Der Parameter callback sieht so aus:

  (window: Window) => void

  • Fenster

    Fenster

onCreated

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

Wird ausgelöst, wenn ein Fenster erstellt wird.

Parameter

• callback

  Funktion

  Chrome 46 oder höher

  Der Parameter callback sieht so aus:

  (window: Window) => void

  • Fenster

    Fenster

    Details des erstellten Fensters.

• Filter

  Objekt optional

  • windowTypes

    WindowType[]

    Bedingungen, die der Typ des erstellten Fensters 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 oder höher

  Der Parameter callback sieht so aus:

  (windowId: number) => void

  • windowId

    Zahl

    ID des neu fokussierten Fensters.

• Filter

  Objekt optional

  • windowTypes

    WindowType[]

    Bedingungen, die der zu entfernende Fenstertyp erfüllen muss. 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 oder höher

  Der Parameter callback sieht so aus:

  (windowId: number) => void

  • windowId

    Zahl

    ID des entfernten Fensters.

• Filter

  Objekt optional

  • windowTypes

    WindowType[]

    Bedingungen, die der zu entfernende Fenstertyp erfüllen muss. Standardmäßig wird ['normal', 'popup'] erfüllt.