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](https://developer.chrome.com/static/docs/extensions/reference/api/windows/images/windows.png?authuser=6&hl=de)
Typen
CreateType
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
Attribute
-
populate
Boolescher Wert optional
Wenn der Wert „true“ ist, hat das Objekt
windows.Window
das Attributtabs
, das eine Liste dertabs.Tab
-Objekte enthält. DieTab
-Objekte enthalten nur dann die Eigenschaftenurl
,pendingUrl
,title
undfavIconUrl
, 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 diesessions
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 dersessions
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 diesessions
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 diesessions
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 diesessions
API.
WindowState
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
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()
chrome.windows.create(
createData?: object,
callback?: function,
)
Erstellt bzw. öffnet ein neues Browserfenster, in dem optional Größe, Position oder Standard-URL angegeben wird.
Parameter
-
createData
Objekt optional
-
Fokussiert
Boolescher Wert optional
Wenn
true
, wird ein aktives Fenster geöffnet. Fallsfalse
, 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öherBei
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öherDer Anfangszustand des Fensters. Die Status
minimized
,maximized
undfullscreen
können nicht mitleft
,top
,width
oderheight
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ückgabe
-
Promise<Window | undefined>
Chrome 88 und höherPromise-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()
chrome.windows.get(
windowId: number,
queryOptions?: QueryOptions,
callback?: function,
)
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
-
Fenster
-
Rückgabe
-
Promise<Window>
Chrome 88 und höherPromise-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()
chrome.windows.getAll(
queryOptions?: QueryOptions,
callback?: function,
)
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
-
Fenster
Fenster[]
-
Rückgabe
-
Promise<Window[]>
Chrome 88 und höherPromise-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()
chrome.windows.getCurrent(
queryOptions?: QueryOptions,
callback?: function,
)
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
-
Fenster
-
Rückgabe
-
Promise<Window>
Chrome 88 und höherPromise-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()
chrome.windows.getLastFocused(
queryOptions?: QueryOptions,
callback?: function,
)
Ruft das Fenster ab, auf das zuletzt den Fokus gelegt wurde. Dies ist normalerweise das Fenster "oben".
Parameter
-
queryOptions
QueryOptions optional
Chrome 88 und höher -
callback
Funktion optional
Der Parameter
callback
sieht so aus:(window: Window) => void
-
Fenster
-
Rückgabe
-
Promise<Window>
Chrome 88 und höherPromise-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()
chrome.windows.remove(
windowId: number,
callback?: function,
)
Entfernt (schließt) ein Fenster und alle darin enthaltenen Tabs.
Parameter
-
windowId
Zahl
-
callback
Funktion optional
Der Parameter
callback
sieht so aus:() => void
Rückgabe
-
Promise<void>
Chrome 88 und höherPromise-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()
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.
Parameter
-
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 Siefalse
fest, um eine vorherigedrawAttention
-Anfrage abzubrechen. -
Fokussiert
Boolescher Wert optional
Wenn
true
, wird das Fenster in den Vordergrund gebracht. Kann nicht mit dem Status "minimiert" kombiniert werden. Beifalse
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
-
Fenster
-
Rückgabe
-
Promise<Window>
Chrome 88 und höherPromise-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.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.
Parameter
-
callback
Funktion
Der Parameter
callback
sieht so aus:(window: Window) => void
-
Fenster
-
onCreated
chrome.windows.onCreated.addListener(
callback: function,
filters?: object,
)
Wird ausgelöst, wenn ein Fenster erstellt wird
Parameter
-
callback
Funktion
Chrome 46 und höherDer Parameter
callback
sieht so aus:(window: Window) => void
-
Fenster
Details zum erstellten Fenster.
-
-
Filter
Objekt optional
-
windowTypes
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.
Parameter
-
callback
Funktion
Chrome 46 und höherDer Parameter
callback
sieht so aus:(windowId: number) => void
-
windowId
Zahl
ID des neu fokussierten Fensters.
-
-
Filter
Objekt optional
-
windowTypes
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
Parameter
-
callback
Funktion
Chrome 46 und höherDer Parameter
callback
sieht so aus:(windowId: number) => void
-
windowId
Zahl
ID des entfernten Fensters.
-
-
Filter
Objekt optional
-
windowTypes
Bedingungen, die der zu entfernende Fenstertyp erfüllen muss. Standardmäßig erfüllt er
['normal', 'popup']
.
-