browsingContext.create Befehl

Syntax

{
  "method": "browsingContext.create",
  "params": {
    "type": "tab"
  }
}

Parameter

Das params-Feld enthält:

background Optional

Ein Boolean, der angibt, ob der Kontext im Hintergrund oder im Vordergrund erstellt wird. Der Standardwert ist false.

• false: Der Kontext wird in den Vordergrund gebracht und erhält den Fokus, nachdem er erstellt wurde.
• true: Der Kontext wird im Hintergrund erstellt. Siehe browsingContext.activate, um ihn in den Vordergrund zu bringen und ihm den Fokus zu geben.

referenceContext Optional

Ein String, der die ID eines vorhandenen Top-Level-Kontextes enthält, der zur Positionierung des neuen Kontextes verwendet wird. Kontext-IDs werden von Befehlen wie browsingContext.getTree zurückgegeben.

Wenn type "tab" ist, öffnet sich der neue Kontext im selben Fenster wie der durch referenceContext spezifizierte Kontext. Wenn type "window" ist oder referenceContext weggelassen wird, bestimmt der Browser, wo der neue Kontext erscheint.

Der neue Kontext erbt den Benutzerkontext des angegebenen Referenzkontextes, es sei denn, userContext wird explizit angegeben.

type

Ein String, der den Typ des zu erstellenden Kontextes spezifiziert. Er akzeptiert einen der folgenden Werte:

• "tab": Erstellt den Kontext als Tab in einem bestehenden Fenster. Wenn referenceContext angegeben ist, öffnet sich der neue Tab daneben.
• "window": Erstellt den Kontext in einem neuen Browserfenster.

userContext Optional

Ein String, der die ID des Benutzerkontextes enthält, in dem der Kontext erstellt wird. Benutzerkontext-IDs werden von browser.getUserContexts oder browser.createUserContext zurückgegeben.

Wenn nicht spezifiziert, verwendet der neue Kontext den "default" Benutzerkontext oder erbt den Benutzerkontext von referenceContext, wenn angegeben.

Rückgabewert

Das result-Objekt in der Antwort enthält folgende Felder:

context

Ein String, der die ID des neu erstellten Kontextes enthält.

Fehler

invalid argument

Ein erforderlicher Parameter fehlt oder hat einen ungültigen Typ. Dieser Fehler wird auch zurückgegeben, wenn der durch referenceContext spezifizierte Kontext kein Top-Level-Kontext ist.

no such frame

Kein Kontext mit der angegebenen referenceContext-ID gefunden.

no such user context

Kein Benutzerkontext mit der angegebenen userContext-ID gefunden.

unsupported operation

Der Browser kann keinen neuen Top-Level-Kontext erstellen.

Beschreibung

Der browsingContext.create Befehl erstellt immer einen Top-Level-Kontext. Der type-Parameter bestimmt, wie der neue Kontext im Browser erscheint: "window" erstellt ein neues Client-Fenster, während "tab" es als Tab in einem bestehenden Client-Fenster öffnet.

Standardmäßig erhält der neue Kontext sofort den Fokus. Um dieses Verhalten zu deaktivieren, setzen Sie background auf true. Sie können später einen Hintergrundkontext mit browsingContext.activate in den Vordergrund bringen.

Wenn Sie möchten, dass sich der neue Tab neben einem bestimmten bestehenden Tab öffnet, geben Sie die Kontext-ID dieses Tabs als referenceContext an. Ohne diese Angabe platziert der Browser den neuen Tab nach eigenem Ermessen.

Standardmäßig wird der neue Kontext dem "default" Benutzerkontext hinzugefügt und teilt Speicher mit anderen Tabs in diesem Kontext. Um ihn zu isolieren, das heißt, ihm separate Cookies und Sitzungsdaten zuzuweisen, geben Sie einen anderen Benutzerkontext mit userContext an.

Beispiele

Erstellen eines Tabs

Mit einer WebDriver BiDi-Verbindung und einer aktiven Sitzung senden Sie die folgende Nachricht, um einen neuen Tab zu erstellen:

{
  "id": 1,
  "method": "browsingContext.create",
  "params": {
    "type": "tab"
  }
}

Bei erfolgreicher Erstellung antwortet der Browser mit der Kontext-ID des neuen Tabs:

{
  "id": 1,
  "type": "success",
  "result": {
    "context": "5e5e96e8-5247-4f22-9b35-a4a2d841cbaa"
  }
}

Da background nicht angegeben ist, öffnet sich der Tab standardmäßig im Vordergrund.

Erstellen eines Tabs neben einem bestehenden Kontext

Das folgende Beispiel zeigt, wie man einen Tab im Hintergrund neben einem bestehenden Tab innerhalb des angegebenen Benutzerkontextes erstellt.

Zuerst erhalten Sie die Kontext-ID des Referenz-Tabs mit browsingContext.getTree und die Benutzerkontext-ID mit browser.getUserContexts oder browser.createUserContext. Dann senden Sie die folgende Nachricht:

{
  "id": 2,
  "method": "browsingContext.create",
  "params": {
    "type": "tab",
    "referenceContext": "5e5e96e8-5247-4f22-9b35-a4a2d841cbaa",
    "background": true,
    "userContext": "3a8e2d1f-4b5c-6d7e-8f9a-0b1c2d3e4f5a"
  }
}

Der Browser öffnet den neuen Tab im selben Fenster wie der Referenz-Kontext und antwortet wie folgt:

{
  "id": 2,
  "type": "success",
  "result": {
    "context": "b2e3f461-8a5c-4d12-9b87-c3d4e5f6a7b8"
  }
}

Erstellen eines Fensters im Hintergrund

Senden Sie die folgende Nachricht, um ein neues Fenster zu erstellen, ohne es zu aktivieren:

{
  "id": 3,
  "method": "browsingContext.create",
  "params": {
    "type": "window",
    "background": true
  }
}

Der Browser antwortet mit der Kontext-ID des neuen Fensters wie folgt:

{
  "id": 3,
  "type": "success",
  "result": {
    "context": "d87a0c61-7b0e-4e8b-b4f0-0a7d5af2e0c3"
  }
}

Spezifikationen

Browser-Kompatibilität

Siehe auch

• browsingContext.activate Befehl
• browsingContext.close Befehl
• browsingContext.getTree Befehl
• browsingContext.contextCreated Ereignis
• browsingContext.contextDestroyed Ereignis