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

Auf Anforderung enthält ein windows.Window ein Array von tabs.Tab-Objekten. Du musst Deklariere die Berechtigung "tabs" in deinem Manifest, wenn du Zugriff auf die url benötigst. pendingUrl-, title- oder favIconUrl-Properties von tabs.Tab. Beispiel:

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

Konzepte und Verwendung

Aktuelles Fenster

Viele Funktionen im Erweiterungssystem verwenden das optionale Argument windowId, das standardmäßig den aktuellen Fenster.

Das aktuelle Fenster ist das Fenster mit dem Code, der gerade ausgeführt wird. Es ist dass sich dies vom obersten oder fokussierten Fenster unterscheiden kann.

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

Bei Service Workern wird der Wert des aktuellen Fensters auf den letzten aktiven Wert zurückgesetzt . Unter bestimmten Umständen wird kein aktuelles Fenster für Hintergrundseiten angezeigt.

Beispiele

Um diese API auszuprobieren, installieren Sie das Windows API-Beispiel aus chrome-extension-samples zu erstellen.

<ph type="x-smartling-placeholder">
</ph> Zwei Fenster mit jeweils einem Tab
Zwei Fenster mit jeweils einem Tab.

Typen

CreateType

Chrome (ab Version 44)

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

Enum

"normal"
Gibt das Fenster als Standardfenster an.

"popup"
Gibt das Fenster als Pop-up-Fenster an.

"panel"
Gibt das Fenster als Feld an.

QueryOptions

Chrome (ab Version 88)

Attribute

  • populate

    Boolescher Wert optional

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

  • windowTypes

    WindowType[] optional

    Wenn festgelegt, wird der zurückgegebene windows.Window nach Typ gefiltert. Wenn kein Filter festgelegt ist, wird „['normal', 'popup']“ als Standardfilter verwendet.

Window

Attribute

  • alwaysOnTop

    boolean

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

  • Fokussiert

    boolean

    Gibt an, ob das Fenster derzeit im Fokus ist.

  • Höhe

    Zahl optional

    Die Höhe des Fensters, einschließlich des Frames, in Pixeln. Unter bestimmten Umständen kann einem Fenster keine height-Eigenschaft zugewiesen werden. beispielsweise bei der Abfrage geschlossener Fenster über die sessions API.

  • id

    Zahl optional

    Die ID des Fensters. Fenster-IDs sind innerhalb einer Browsersitzung eindeutig. Unter bestimmten Umständen kann einem Fenster keine ID-Eigenschaft zugewiesen werden. z. B. bei der Abfrage von Fenstern mit der sessions API. In diesem Fall kann eine Sitzungs-ID vorhanden sein.

  • inkognito

    boolean

    Gibt an, ob das Fenster im Inkognitomodus ist.

  • links

    Zahl optional

    Der Versatz des Fensters vom linken Rand des Bildschirms in Pixeln. Unter bestimmten Umständen kann einem Fenster keine left-Eigenschaft zugewiesen werden. beispielsweise bei der Abfrage geschlossener Fenster über die sessions API.

  • sessionId

    String optional

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

  • Bundesstaat

    WindowState optional

    Der Status dieses Browserfensters.

  • Tabs

    Tabulatortaste[] optional

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

  • oben

    Zahl optional

    Der Versatz des Fensters vom oberen Rand des Bildschirms in Pixeln. Unter bestimmten Umständen kann einem Fenster keine top-Eigenschaft zugewiesen werden. beispielsweise bei der Abfrage geschlossener Fenster über die sessions API.

  • Typ

    WindowType optional

    Die Art des Browserfensters.

  • Breite

    Zahl optional

    Die Breite des Fensters, einschließlich des Rahmens, in Pixeln. Unter bestimmten Umständen kann einem Fenster keine width-Eigenschaft zugewiesen werden. beispielsweise bei der Abfrage geschlossener Fenster über die sessions API.

WindowState

Chrome (ab Version 44)

Der Status dieses Browserfensters. Unter bestimmten Umständen kann einem Fenster keine state-Eigenschaft zugewiesen werden. beispielsweise bei der Abfrage geschlossener Fenster über die sessions API.

Enum

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

"minimized"
Status des minimierten Fensters.

"maximized"
Status des maximierten Fensters

"Vollbild"
Vollbildfenster-Status

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

WindowType

Chrome (ab Version 44)

Die Art des Browserfensters. Unter bestimmten Umständen kann einem Fenster keine type-Eigenschaft zugewiesen werden. beispielsweise bei der Abfrage geschlossener Fenster über die sessions API.

Enum

"normal"
Ein normales Browserfenster.

"popup"
Ein Browser-Pop-up.

"panel"
In dieser API eingestellt. Ein Fenster im Stil eines Steuerfelds der Chrome App. Erweiterungen können nur ihre eigenen Steuerfeldfenster sehen.

"app"
In dieser API eingestellt. Ein Chrome-App-Fenster. Erweiterungen können nur das eigene App-Fenster sehen.

"devtools"
Ein Fenster mit Entwicklertools.

Attribute

WINDOW_ID_CURRENT

Der windowId-Wert, der das aktuelle Fenster darstellt.

Wert

-2

WINDOW_ID_NONE

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

Wert

-1

Methoden

create()

<ph type="x-smartling-placeholder"></ph> Versprechen 
chrome.windows.create(
  createData?: object,
  callback?: function,
)

Erstellt bzw. öffnet ein neues Browserfenster mit optionaler Angabe von Größe, Position oder Standard-URL.

Parameter

  • createData

    Objekt optional

    • Fokussiert

      Boolescher Wert optional

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

    • Höhe

      Zahl optional

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

    • inkognito

      Boolescher Wert optional

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

    • links

      Zahl optional

      Die Anzahl der Pixel, um das neue Fenster vom linken Bildschirmrand entfernt zu positionieren. Wenn nicht angegeben, wird das neue Fenster automatisch vom letzten fokussierten Fenster verschoben. Dieser Wert wird bei Steuerfeldern ignoriert.

    • setSelfAsOpener

      Boolescher Wert optional

      Chrome (ab Version 64)

      Wenn true, ist der Wert für "window.opener" des neu erstellten Fensters wird auf den Aufrufer festgelegt und befindet sich in derselben Einheit für verwandte Browserkontexte wie der Aufrufer.

    • Bundesstaat

      WindowState optional

      Chrome (ab Version 44)

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

    • tabId

      Zahl optional

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

    • oben

      Zahl optional

      Die Anzahl der Pixel, um das neue Fenster vom oberen Bildschirmrand aus zu positionieren. Wenn nicht angegeben, wird das neue Fenster automatisch vom letzten fokussierten Fenster verschoben. Dieser Wert wird bei Steuerfeldern 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. Vollständig qualifizierte URLs müssen ein Schema wie "http://www.google.com", nicht "www.google.com". Nicht vollständig qualifizierte URLs werden innerhalb der Erweiterung als relativ zueinander angesehen. Die Standardeinstellung ist die Seite „Neuer Tab“.

    • Breite

      Zahl optional

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

  • callback

    Funktion optional

    Der Parameter callback sieht so aus: <ph type="x-smartling-placeholder"></ph>

    (window?: Window) => void

    • Fenster

      Fenster optional

      Enthält Details zum erstellten Fenster.

Gibt Folgendes zurück:

  • Promise&lt;Window | nicht definiert>

    Chrome (ab Version 88)

    Promise-Objekte werden in Manifest V3 und höher unterstützt, Callbacks sind jedoch für Abwärtskompatibilität. Sie können nicht beide in demselben Funktionsaufruf verwenden. Die Promise wird mit demselben Typ aufgelöst, der an das Callback übergeben wird.

get()

<ph type="x-smartling-placeholder"></ph> Versprechen 
chrome.windows.get(
  windowId: number,
  queryOptions?: QueryOptions,
  callback?: function,
)

Ruft Details zu einem Fenster ab.

Parameter

  • windowId

    Zahl

  • queryOptions

    QueryOptions optional

    Chrome (ab Version 88)
  • callback

    Funktion optional

    Der Parameter callback sieht so aus: <ph type="x-smartling-placeholder"></ph>

    (window: Window) => void

Gibt Folgendes zurück:

  • Promise&lt;Window&gt;

    Chrome (ab Version 88)

    Promise-Objekte werden in Manifest V3 und höher unterstützt, Callbacks sind jedoch für Abwärtskompatibilität. Sie können nicht beide in demselben Funktionsaufruf verwenden. Die Promise wird mit demselben Typ aufgelöst, der an das Callback übergeben wird.

getAll()

<ph type="x-smartling-placeholder"></ph> Versprechen 
chrome.windows.getAll(
  queryOptions?: QueryOptions,
  callback?: function,
)

Ruft alle Fenster ab.

Parameter

  • queryOptions

    QueryOptions optional

    Chrome (ab Version 88)
  • callback

    Funktion optional

    Der Parameter callback sieht so aus: <ph type="x-smartling-placeholder"></ph>

    (windows: Window[]) => void

Gibt Folgendes zurück:

  • Promise&lt;Window[]&gt;

    Chrome (ab Version 88)

    Promise-Objekte werden in Manifest V3 und höher unterstützt, Callbacks sind jedoch für Abwärtskompatibilität. Sie können nicht beide in demselben Funktionsaufruf verwenden. Die Promise wird mit demselben Typ aufgelöst, der an das Callback übergeben wird.

getCurrent()

<ph type="x-smartling-placeholder"></ph> Versprechen 
chrome.windows.getCurrent(
  queryOptions?: QueryOptions,
  callback?: function,
)

Ruft das aktuelle Fenster ab.

Parameter

  • queryOptions

    QueryOptions optional

    Chrome (ab Version 88)
  • callback

    Funktion optional

    Der Parameter callback sieht so aus: <ph type="x-smartling-placeholder"></ph>

    (window: Window) => void

Gibt Folgendes zurück:

  • Promise&lt;Window&gt;

    Chrome (ab Version 88)

    Promise-Objekte werden in Manifest V3 und höher unterstützt, Callbacks sind jedoch für Abwärtskompatibilität. Sie können nicht beide in demselben Funktionsaufruf verwenden. Die Promise wird mit demselben Typ aufgelöst, der an das Callback übergeben wird.

getLastFocused()

<ph type="x-smartling-placeholder"></ph> Versprechen 
chrome.windows.getLastFocused(
  queryOptions?: QueryOptions,
  callback?: function,
)

Ruft das Fenster ab, das zuletzt fokussiert war. Dies ist normalerweise das Fenster oben.

Parameter

  • queryOptions

    QueryOptions optional

    Chrome (ab Version 88)
  • callback

    Funktion optional

    Der Parameter callback sieht so aus: <ph type="x-smartling-placeholder"></ph>

    (window: Window) => void

Gibt Folgendes zurück:

  • Promise&lt;Window&gt;

    Chrome (ab Version 88)

    Promise-Objekte werden in Manifest V3 und höher unterstützt, Callbacks sind jedoch für Abwärtskompatibilität. Sie können nicht beide in demselben Funktionsaufruf verwenden. Die Promise wird mit demselben Typ aufgelöst, der an das Callback übergeben wird.

remove()

<ph type="x-smartling-placeholder"></ph> Versprechen 
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: <ph type="x-smartling-placeholder"></ph>

    () => void

Gibt Folgendes zurück:

  • Versprechen<void>

    Chrome (ab Version 88)

    Promise-Objekte werden in Manifest V3 und höher unterstützt, Callbacks sind jedoch für Abwärtskompatibilität. Sie können nicht beide in demselben Funktionsaufruf verwenden. Die Promise wird mit demselben Typ aufgelöst, der an das Callback übergeben wird.

update()

<ph type="x-smartling-placeholder"></ph> 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 spezifizierte Attribute 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 dass das fokussierte Fenster geändert wird. Der Effekt bleibt bestehen, 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

      Bei true wird das Fenster nach vorne gebracht; kann nicht mit dem Bundesstaat „minimized“ kombiniert werden. Bei false wird das nächste Fenster in der Z-Reihenfolge in den Vordergrund gerückt. kann nicht mit dem Status "Vollbild" kombiniert werden. oder „maximiert“.

    • Höhe

      Zahl optional

      Höhe, auf die die Größe des Fensters in Pixeln geändert werden soll. Dieser Wert wird bei Steuerfeldern ignoriert.

    • links

      Zahl optional

      Der Abstand vom linken Bildschirmrand, zu dem das Fenster verschoben werden soll, in Pixeln. Dieser Wert wird bei Steuerfeldern ignoriert.

    • Bundesstaat

      WindowState optional

      Der neue Status des Fensters. „Minimiert“, „Maximiert“ und „Vollbild“ Status können nicht mit 'left', 'top', 'width' oder 'height' kombiniert werden.

    • oben

      Zahl optional

      Der Abstand vom oberen Bildschirmrand, zu dem das Fenster verschoben werden soll, in Pixeln. Dieser Wert wird bei Steuerfeldern ignoriert.

    • Breite

      Zahl optional

      Die Breite, auf die die Größe des Fensters in Pixel angepasst werden soll. Dieser Wert wird bei Steuerfeldern ignoriert.

  • callback

    Funktion optional

    Der Parameter callback sieht so aus: <ph type="x-smartling-placeholder"></ph>

    (window: Window) => void

Gibt Folgendes zurück:

  • Promise&lt;Window&gt;

    Chrome (ab Version 88)

    Promise-Objekte werden in Manifest V3 und höher unterstützt, Callbacks sind jedoch für Abwärtskompatibilität. Sie können nicht beide in demselben Funktionsaufruf verwenden. Die Promise wird mit demselben Typ aufgelöst, der an das Callback übergeben wird.

Ereignisse

onBoundsChanged

Chrome (ab Version 86) 
chrome.windows.onBoundsChanged.addListener(
  callback: function,
)

Wird ausgelöst, wenn die Größe eines Fensters geändert wurde Dieses Ereignis wird nur dann ausgelöst, wenn für die neuen Grenzen ein Commit durchgeführt wurde. Bei laufenden Änderungen wird es nicht ausgelöst.

Parameter

  • callback

    Funktion

    Der Parameter callback sieht so aus: <ph type="x-smartling-placeholder"></ph>

    (window: Window) => void

onCreated

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

Wird ausgelöst, wenn ein Fenster erstellt wird

Parameter

  • callback

    Funktion

    Chrome (ab Version 46)

    Der Parameter callback sieht so aus: <ph type="x-smartling-placeholder"></ph>

    (window: Window) => void

    • Fenster

      Fenster

      Details zum erstellten Fenster.

  • Filter

    Objekt optional

    • windowTypes

      WindowType[]

      Bedingungen, die der Typ des zu erstellenden Fensters erfüllen muss. Standardmäßig erfüllt sie die Anforderungen ['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 nicht mehr im Fokus sind. Hinweis:Bei einigen Linux-Fenstermanagern wird WINDOW_ID_NONE immer direkt vor einem Wechsel von einem Chrome-Fenster zu einem anderen gesendet.

Parameter

  • callback

    Funktion

    Chrome (ab Version 46)

    Der Parameter callback sieht so aus: <ph type="x-smartling-placeholder"></ph>

    (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 sie die Anforderungen ['normal', 'popup'].

onRemoved

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

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

Parameter

  • callback

    Funktion

    Chrome (ab Version 46)

    Der Parameter callback sieht so aus: <ph type="x-smartling-placeholder"></ph>

    (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 sie die Anforderungen ['normal', 'popup'].