chrome.windows

Beschreibung

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

Berechtigungen

Bei Anfrage enthält ein windows.Window ein Array mit 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"],
  ...
}

Konzepte und Nutzung

Das aktuelle Fenster

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

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

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

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

Beispiele

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

Zwei Fenster mit jeweils einem Tab
Zwei Fenster mit jeweils einem Tab.

Typen

CreateType

Chrome 44 und höher

Gibt an, welche Art von Browserfenster erstellt werden soll. „Bereich“ wurde eingestellt und ist nur für vorhandene Erweiterungen auf der Zulassungsliste unter Chrome OS verfügbar.

Enum

"normal"
Gibt das Fenster als Standardfenster an.

"popup"
Gibt an, dass das Fenster ein Pop-up-Fenster ist.

"panel"
Gibt das Fenster als Steuerfeld an.

QueryOptions

Chrome 88 und höher

Attribute

  • populate

    Boolescher Wert optional

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

  • windowTypes

    WindowType[] optional

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

Window

Attribute

  • alwaysOnTop

    boolean

    Gibt an, ob das Fenster immer im Vordergrund sein soll.

  • Fokussiert

    boolean

    Gibt an, ob das Fenster das fokussierte Fenster ist.

  • Höhe

    Nummer optional

    Die Höhe des Fensters, einschließlich des Rahmens, in Pixeln. In einigen Fällen kann einem Fenster keine height-Eigenschaft zugewiesen werden, z. B. beim Abfragen geschlossener Fenster über die sessions API.

  • id

    Nummer optional

    Die ID des Fensters. Fenster-IDs sind innerhalb einer Browsersitzung eindeutig. In einigen Fällen kann einem Fenster keine ID-Eigenschaft zugewiesen werden, z. B. wenn Fenster mit der sessions API abgefragt werden und in diesem Fall eine Sitzungs-ID vorhanden sein kann.

  • inkognito

    boolean

    Gibt an, ob das Fenster inkognito ist.

  • links

    Nummer optional

    Der Abstand des Fensters vom linken Rand des Bildschirms in Pixeln. In einigen Fällen kann einem Fenster keine left-Eigenschaft zugewiesen werden, z. B. beim Abfragen geschlossener Fenster über die sessions API.

  • sessionId

    String optional

    Die Sitzungs-ID zur eindeutigen Identifizierung eines Fensters, die von der sessions API abgerufen wird.

  • state

    WindowState optional

    Der Status dieses Browserfensters.

  • Tabs

    Tabulatortaste[] optional

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

  • oben

    Nummer optional

    Der Abstand des Fensters vom oberen Rand des Bildschirms in Pixeln. In einigen Fällen kann einem Fenster keine top-Eigenschaft zugewiesen werden, z. B. beim Abfragen geschlossener Fenster über die sessions API.

  • Typ

    WindowType optional

    Die Art des Browserfensters.

  • Breite

    Nummer optional

    Die Breite des Fensters, einschließlich des Rahmens, in Pixeln. In einigen Fällen kann einem Fenster keine width-Eigenschaft zugewiesen werden, z. B. beim Abfragen geschlossener Fenster über die sessions API.

WindowState

Chrome 44 und höher

Der Status dieses Browserfensters. In einigen Fällen kann einem Fenster keine state-Eigenschaft zugewiesen werden, z. B. beim Abfragen geschlossener Fenster über die sessions API.

Enum

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

"minimized"
Minimierter Fensterstatus.

"maximiert"
Maximierter Fensterstatus.

"fullscreen"
Status des Vollbildfensters

"locked-fullscreen"
Gesperrter Vollbildfensterstatus. Der Vollbildmodus kann nicht durch Nutzeraktion 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. In manchen Fällen kann einem Fenster keine type-Eigenschaft zugewiesen werden, 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 Stil einer Chrome App. Erweiterungen können nur ihre eigenen Steuerfeldfenster sehen.

"app"
In dieser API verworfen Ein Chrome App-Fenster. Erweiterungen können nur ihre eigenen App-Fenster sehen.

"devtools"
Ein Fenster mit den Entwicklertools.

Attribute

WINDOW_ID_CURRENT

Der windowId-Wert, der das aktuelle Fenster darstellt.

Wert

-2

WINDOW_ID_NONE

Der Wert für windowId, der angibt, dass kein Chrome-Browserfenster vorhanden ist.

Wert

-1

Methoden

create()

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

Erstellt bzw. öffnet ein neues Browserfenster, in dem optional Größe, Position oder Standard-URL angegeben wird.

Parameters

  • createData

    Objekt optional

    • Fokussiert

      Boolescher Wert optional

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

    • Höhe

      Nummer optional

      Die Höhe des neuen Fensters, einschließlich des Frames, in Pixeln. Wenn keine Angabe erfolgt, wird standardmäßig eine natürliche Höhe verwendet.

    • inkognito

      Boolescher Wert optional

      Legt fest, ob das neue Fenster ein Inkognitofenster sein soll

    • links

      Nummer optional

      Die Anzahl der Pixel, um die das neue Fenster vom linken Rand des Bildschirms entfernt wird. Wenn nicht angegeben, wird das neue Fenster automatisch vom letzten fokussierten Fenster versetzt. Dieser Wert wird bei Bereichen ignoriert.

    • setSelfAsOpener

      Boolescher Wert optional

      Chrome 64 und höher

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

    • state

      WindowState optional

      Chrome 44 und höher

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

    • tabId

      Nummer optional

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

    • oben

      Nummer optional

      Die Anzahl der Pixel, die das neue Fenster vom oberen Bildschirmrand entfernt positioniert wird. Wenn nicht angegeben, wird das neue Fenster automatisch vom letzten fokussierten Fenster versetzt. Dieser Wert wird bei Bereichen ignoriert.

    • Typ

      CreateType optional

      Gibt an, welche Art 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. Voll qualifizierte URLs müssen ein Schema enthalten, z.B. „http://www.google.com“, nicht „www.google.com“. Nicht voll qualifizierte URLs werden innerhalb der Erweiterung als relativ betrachtet. Die Standardeinstellung ist die Seite „Neuer Tab“.

    • Breite

      Nummer optional

      Die Breite des neuen Fensters, einschließlich des Rahmens, in Pixeln. Wenn keine Angabe erfolgt, wird standardmäßig eine 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.

Rückgaben

  • Promise<Fenster|nicht definiert>

    Chrome 88 und höher

    Promise-Objekte werden in Manifest V3 und höher unterstützt, Callbacks werden jedoch aus Gründen der Abwärtskompatibilität bereitgestellt. Sie können nicht beide in einem Funktionsaufruf verwenden. Das Promise wird mit demselben Typ aufgelöst, der an den Callback übergeben wird.

get()

Versprechen 
chrome.windows.get(
  windowId: number,
  queryOptions?: QueryOptions,
  callback?: function,
)

Ruft Details zu einem Fenster ab.

Parameters

  • windowId

    Zahl

  • queryOptions

    QueryOptions optional

    Chrome 88 und höher
  • callback

    Funktion optional

    Der Parameter callback sieht so aus: 

    (window: Window)=>void

Rückgaben

  • Promise<Window>

    Chrome 88 und höher

    Promise-Objekte werden in Manifest V3 und höher unterstützt, Callbacks werden jedoch aus Gründen der Abwärtskompatibilität bereitgestellt. Sie können nicht beide in einem Funktionsaufruf verwenden. Das Promise wird mit demselben Typ aufgelöst, der an den Callback übergeben wird.

getAll()

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

Ruft alle Fenster ab.

Parameters

  • queryOptions

    QueryOptions optional

    Chrome 88 und höher
  • callback

    Funktion optional

    Der Parameter callback sieht so aus: 

    (windows: Window[])=>void

Rückgaben

  • Promise<Window[]>

    Chrome 88 und höher

    Promise-Objekte werden in Manifest V3 und höher unterstützt, Callbacks werden jedoch aus Gründen der Abwärtskompatibilität bereitgestellt. Sie können nicht beide in einem Funktionsaufruf verwenden. Das Promise wird mit demselben Typ aufgelöst, der an den Callback übergeben wird.

getCurrent()

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

Ruft das aktuelle Fenster ab.

Parameters

  • queryOptions

    QueryOptions optional

    Chrome 88 und höher
  • callback

    Funktion optional

    Der Parameter callback sieht so aus: 

    (window: Window)=>void

Rückgaben

  • Promise<Window>

    Chrome 88 und höher

    Promise-Objekte werden in Manifest V3 und höher unterstützt, Callbacks werden jedoch aus Gründen der Abwärtskompatibilität bereitgestellt. Sie können nicht beide in einem Funktionsaufruf verwenden. Das Promise wird mit demselben Typ aufgelöst, der an den Callback übergeben wird.

getLastFocused()

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

Ruft das Fenster ab, auf das zuletzt den Fokus gelegt wurde. Dies ist normalerweise das Fenster "oben".

Parameters

  • queryOptions

    QueryOptions optional

    Chrome 88 und höher
  • callback

    Funktion optional

    Der Parameter callback sieht so aus: 

    (window: Window)=>void

Rückgaben

  • Promise<Window>

    Chrome 88 und höher

    Promise-Objekte werden in Manifest V3 und höher unterstützt, Callbacks werden jedoch aus Gründen der Abwärtskompatibilität bereitgestellt. Sie können nicht beide in einem Funktionsaufruf verwenden. Das Promise wird mit demselben Typ aufgelöst, der an den Callback übergeben wird.

remove()

Versprechen 
chrome.windows.remove(
  windowId: number,
  callback?: function,
)

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

Parameters

  • windowId

    Zahl

  • callback

    Funktion optional

    Der Parameter callback sieht so aus: 

    ()=>void

Rückgaben

  • Promise<void>

    Chrome 88 und höher

    Promise-Objekte werden in Manifest V3 und höher unterstützt, Callbacks werden jedoch aus Gründen der Abwärtskompatibilität bereitgestellt. Sie können nicht beide in einem Funktionsaufruf verwenden. Das Promise wird mit demselben Typ aufgelöst, der an den Callback übergeben wird.

update()

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

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

Parameters

  • windowId

    Zahl

  • updateInfo

    Objekt

    • drawAttention

      Boolescher Wert optional

      Bei true wird das Fenster so angezeigt, dass die Aufmerksamkeit des Nutzers auf das Fenster gelenkt wird, ohne das Fenster im Fokus zu ändern. Der Effekt dauert an, bis der Nutzer den Fokus auf das Fenster wechselt. Diese Option hat keine Auswirkungen, wenn das Fenster bereits im Fokus ist. Legen Sie false fest, um eine vorherige drawAttention-Anfrage abzubrechen.

    • Fokussiert

      Boolescher Wert optional

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

    • Höhe

      Nummer optional

      Höhe in Pixel, auf die die Fenstergröße geändert werden soll Dieser Wert wird bei Bereichen ignoriert.

    • links

      Nummer optional

      Der Abstand vom linken Rand des Bildschirms, in den das Fenster verschoben werden soll, in Pixeln. Dieser Wert wird bei Bereichen ignoriert.

    • state

      WindowState optional

      Der neue Status des Fensters. Die Status „minimiert“, „maximiert“ und „Vollbild“ können nicht mit „links“, „oben“, „breite“ oder „höhe“ kombiniert werden.

    • oben

      Nummer optional

      Der Abstand vom oberen Rand des Bildschirms, in den das Fenster verschoben werden soll, in Pixeln. Dieser Wert wird bei Bereichen ignoriert.

    • Breite

      Nummer optional

      Die Breite, auf die die Fenstergröße geändert werden soll, in Pixel. Dieser Wert wird bei Bereichen ignoriert.

  • callback

    Funktion optional

    Der Parameter callback sieht so aus: 

    (window: Window)=>void

Rückgaben

  • Promise<Window>

    Chrome 88 und höher

    Promise-Objekte werden in Manifest V3 und höher unterstützt, Callbacks werden jedoch aus Gründen der Abwärtskompatibilität bereitgestellt. Sie können nicht beide in einem Funktionsaufruf verwenden. Das Promise wird mit demselben Typ aufgelöst, der an den Callback übergeben wird.

Veranstaltungen

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 für die neuen Grenzen ein Commit durchgeführt wurde, und nicht bei Änderungen in Bearbeitung.

Parameters

  • 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

Parameters

  • callback

    Funktion

    Chrome 46 und höher

    Der Parameter callback sieht so aus: 

    (window: Window)=>void

    • Fenster

      Fenster

      Details zum erstellten Fenster.

  • Filter

    Objekt optional

    • windowTypes

      WindowType[]

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

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 einem Wechsel von einem Chrome-Fenster zu einem anderen gesendet.

Parameters

  • callback

    Funktion

    Chrome 46 und 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 erfüllt er ['normal', 'popup'].

onRemoved

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

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

Parameters

  • callback

    Funktion

    Chrome 46 und 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 erfüllt er ['normal', 'popup'].