chrome.windows

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 Bedarf 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 Attribute url, pendingUrl, title oder favIconUrl von tabs.Tab benötigen. Beispiel:

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

Das aktuelle Fenster

Viele Funktionen im Erweiterungssystem akzeptieren das optionale Argument windowId, 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 fokussierten 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 enthält, von der der Aufruf stammt, 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 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 Browsertyp erstellt werden soll. „panel“ ist veraltet und 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

    boolean optional

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

  • windowTypes

    WindowType[] optional

    Wenn diese Option festgelegt ist, 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 kein ID-Attribut 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 Abstand 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 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. Unter Umständen wird einem Fenster keine top-Eigenschaft zugewiesen, z. B. wenn geschlossene Fenster über die sessions API abgefragt werden.

  • Typ

    WindowType optional

    Die Art 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).

„minimiert“
Minimierter Fensterstatus.

„maximized“
Maximierter Fensterstatus.

"fullscreen"
Vollbildfensterstatus.

„locked-fullscreen“
Status des gesperrten Vollbildfensters. Dieser Vollbildmodus kann nicht durch Nutzeraktionen beendet werden und ist nur für Erweiterungen auf der Zulassungsliste unter Chrome OS verfügbar.

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 eingestellt. 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

      boolean 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

      boolean 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 zu positionieren. Wenn nicht angegeben, wird das neue Fenster auf natürliche Weise vom zuletzt fokussierten Fenster versetzt. Dieser Wert wird für Bereiche ignoriert.

    • setSelfAsOpener

      boolean optional

      Chrome 64 und 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 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 Bereiche ignoriert.

    • Typ

      CreateType optional

      Gibt an, welcher Browsertyp 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 gelten als relativ innerhalb der Erweiterung. 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 den Fokus hatte – in der Regel das Fenster, das „oben“ ist.

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>

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 Attribute eines Fensters. Geben Sie nur die Eigenschaften an, die geändert werden sollen. Nicht angegebene Eigenschaften bleiben unverändert.

Parameter

  • windowId

    Zahl

  • updateInfo

    Objekt

    • drawAttention

      boolean 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. Setzen Sie diesen Wert auf false, um eine vorherige drawAttention-Anfrage abzubrechen.

    • Fokussiert

      boolean 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 Bereiche ignoriert.

    • links

      number optional

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

    • Breite

      number optional

      Die Breite, auf die das Fenster in Pixeln skaliert werden soll. Dieser Wert wird für Bereiche 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 gesendet, 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

    • Fenster

      Fenster

      Details zum erstellten Fenster.

  • 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-Fenster-Managern 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 der Typ des zu entfernenden Fensters 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 und höher

    Der Parameter callback sieht so aus: 

    (windowId: number) => void

    • windowId

      Zahl

      ID des entfernten Fensters.

  • Filter

    object optional

    • windowTypes

      WindowType[]

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