`browsingContext.getTree` Befehl

Der browsingContext.getTree Befehl des browsingContext Moduls gibt den Baum aller Top-Level-Kontexte oder den Teilbaum zurück, der mit dem angegebenen Kontext beginnt.

Syntax

json

/* Without optional parameters */
{
  "method": "browsingContext.getTree",
  "params": {}
}

/* With optional parameters */
{
  "method": "browsingContext.getTree",
  "params": {
    "maxDepth": 1,
    "root": "93ee5bd6-d256-4608-a002-9a8995cc0e5f"
  }
}

Parameter

Das params Feld kann enthalten:

maxDepth Optional: Eine nicht-negative Ganzzahl, die die maximale Tiefe des zurückzugebenden Baumes angibt. Wenn nicht enthalten, was dem Wert null entspricht, wird der vollständige Baum zurückgegeben. Ein Wert von 0 gibt nur den Wurzelkontext selbst zurück. Wenn beispielsweise ein Top-Level-Kontext ein <iframe> enthält, welches selbst ein weiteres <iframe> enthält, gibt ein maxDepth von 0 nur den Top-Level-Kontext zurück; ein maxDepth von 1 gibt den Top-Level-Kontext und das erste <iframe> zurück, aber nicht das verschachtelte.
root Optional: Ein String, der die ID des Kontextes enthält, der als Wurzel des zurückgegebenen Baumes verwendet werden soll. Kontext-IDs werden von Befehlen wie browsingContext.create oder Ereignissen wie browsingContext.contextCreated zurückgegeben. Wenn nicht enthalten, werden alle Top-Level-Kontexte zurückgegeben.

Rückgabewert

Das result Objekt in der Antwort enthält die folgenden Felder:

contexts

Ein Array von Kontextobjekten, die jeweils die Eigenschaften eines Kontextes repräsentieren. Jedes Objekt hat die folgenden Felder:

children: Ein Array von Kontextobjekten, das die untergeordneten Kontexte dieses Kontextes darstellt. Jedes untergeordnete Objekt hat die gleiche Struktur mit seinem eigenen children Array, was eine rekursive Darstellung des Kontextbaumes ergibt. Ein leeres Array zeigt an, dass der Kontext keine Kinder hat, während ein null Wert anzeigt, dass Kinder von der Antwort ausgeschlossen sind, z.B. wenn das maxDepth Limit erreicht ist.
clientWindow: Ein String, der die ID des Client-Fensters enthält, das diesen Kontext wiedergibt.
context: Ein String, der die ID des Kontextes enthält.
originalOpener: Ein String, der die ID des Kontextes enthält, der diesen Kontext ursprünglich geöffnet hat. Der Wert ist null, wenn der Kontext direkt geöffnet wurde (nicht von einem anderen Kontext).

Hinweis: originalOpener wird einmal gesetzt, wenn der Kontext erstellt wird. Es ändert sich nie und behält immer die ID des öffnenden Kontextes. Dies unterscheidet sich von der JavaScript window.opener Eigenschaft, die das Fenster referenziert, das das aktuelle Fenster geöffnet hat — es wird null, wenn das rel=noopener Attribut im Link oder das noopener Fenstermerkmal in window.open() angegeben ist.
parent Optional: Ein String, der die ID des übergeordneten Kontextes enthält. Der Wert ist null, wenn der Kontext keinen übergeordneten Kontext hat. Dieses Feld ist nur für die Wurzel-Einträge im zurückgegebenen Array vorhanden.
url: Ein String, der die URL des Kontextes einschließlich des Fragments enthält.
userContext: Ein String, der die ID des Benutzerkontextes enthält, der mit diesem Kontext verknüpft ist.

Fehler

invalid argument: Ein erforderlicher Parameter fehlt oder hat einen ungültigen Typ.
no such frame: Kein Kontext mit der gegebenen root ID gefunden.

Bei einer WebDriver BiDi-Verbindung und einer aktiven Sitzung betrachten Sie ein Szenario, in dem zwei Tabs im Browser geöffnet sind: Der erste Tab bei https://example.com/page1.html hat ein <iframe>, das https://example.com/frame.html lädt, und der zweite Tab zeigt https://example.com/page2.html:

Browser
├── https://example.com/page1.html (Tab 1)
│   └── https://example.com/frame.html (<iframe>)
└── https://example.com/page2.html (Tab 2)

Senden Sie die folgende Nachricht, um den vollständigen Kontextbaum zu erhalten:

json

{
  "id": 1,
  "method": "browsingContext.getTree",
  "params": {}
}

Das contexts Array listet die zwei Top-Level-Kontexte auf. Das <iframe> innerhalb von Tab 1 erscheint verschachtelt unter seinem children. Der Browser antwortet wie folgt:

json

{
  "id": 1,
  "type": "success",
  "result": {
    "contexts": [
      {
        "context": "93ee5bd6-d256-4608-a002-9a8995cc0e5f", // Tab 1
        "children": [
          // Tab 1 has one child <iframe>
          {
            "context": "6442450945", // The <iframe>
            "children": [], // No child contexts
            "originalOpener": null,
            "url": "https://example.com/frame.html",
            "userContext": "default",
            "clientWindow": "08c697a1-2664-447d-9c88-52bcee3bb386"
          }
        ],
        "originalOpener": null,
        "url": "https://example.com/page1.html",
        "userContext": "default",
        "clientWindow": "08c697a1-2664-447d-9c88-52bcee3bb386",
        "parent": null
      },
      {
        "context": "32ed30da-24ad-459d-8f0d-660526e92d96", // Tab 2
        "children": [], // No child contexts
        "originalOpener": "93ee5bd6-d256-4608-a002-9a8995cc0e5f",
        "url": "https://example.com/page2.html",
        "userContext": "default",
        "clientWindow": "08c697a1-2664-447d-9c88-52bcee3bb386",
        "parent": null
      }
    ]
  }
}

Abrufen eines Teilbaums von einem bestimmten Kontext

Verwenden Sie das gleiche Setup wie im vorherigen Beispiel, um nur Tab 1 und seinen unmittelbaren untergeordneten Kontext zu erhalten, senden Sie die folgende Nachricht mit der Kontext-ID von Tab 1 als root und setzen Sie maxDepth auf 1:

json

{
  "id": 2,
  "method": "browsingContext.getTree",
  "params": {
    "root": "93ee5bd6-d256-4608-a002-9a8995cc0e5f",
    "maxDepth": 1
  }
}

Der Browser antwortet mit Tab 1 und seinem unmittelbaren Kind. Das children Feld für das iframe ist null; die maxDepth Einstellung von 1 begrenzt die Antwort auf eine Ebene unterhalb der Wurzel, sodass die eigenen Kinder des <iframe> nicht enthalten sind:

json

{
  "id": 2,
  "type": "success",
  "result": {
    "contexts": [
      {
        "context": "93ee5bd6-d256-4608-a002-9a8995cc0e5f",
        "children": [
          {
            "context": "6442450945",
            "children": null,
            "originalOpener": null,
            "url": "https://example.com/frame.html",
            "userContext": "default",
            "clientWindow": "08c697a1-2664-447d-9c88-52bcee3bb386"
          }
        ],
        "originalOpener": null,
        "url": "https://example.com/page1.html",
        "userContext": "default",
        "clientWindow": "08c697a1-2664-447d-9c88-52bcee3bb386",
        "parent": null
      }
    ]
  }
}

In diesem Beispiel, wenn der root Parameter der browsingContext.getTree Nachricht auf die Kontext-ID des iframes gesetzt ist ("6442450945"), wäre das parent Feld des <iframe> in der Antwort "93ee5bd6-d256-4608-a002-9a8995cc0e5f" (die Kontext-ID von Tab 1) anstelle von null.

Um die Suche auf nur den Wurzelkontext ohne Kinder zu beschränken, setzen Sie maxDepth auf 0:

json

{
  "id": 3,
  "method": "browsingContext.getTree",
  "params": {
    "root": "93ee5bd6-d256-4608-a002-9a8995cc0e5f",
    "maxDepth": 0
  }
}

Der Browser antwortet wie folgt:

json

{
  "id": 3,
  "type": "success",
  "result": {
    "contexts": [
      {
        "context": "93ee5bd6-d256-4608-a002-9a8995cc0e5f",
        "children": null,
        "originalOpener": null,
        "url": "https://example.com/page1.html",
        "userContext": "default",
        "clientWindow": "08c697a1-2664-447d-9c88-52bcee3bb386",
        "parent": null
      }
    ]
  }
}

Identifizierung des Öffners eines Kontextes

Erweitern Sie das gleiche Setup und beachten Sie, dass Tab 2 (https://example.com/page2.html) von Tab 1 (https://example.com/page1.html) mit window.open() geöffnet wurde. Senden Sie die folgende Nachricht, um zu sehen, wie diese Beziehung in der Antwort übermittelt wird:

json

{
  "id": 4,
  "method": "browsingContext.getTree",
  "params": {}
}

Der Browser antwortet mit dem vollständigen Kontextbaum. Das originalOpener Feld identifiziert den Kontext, der Tab 2 geöffnet hat:

json

{
  "id": 4,
  "type": "success",
  "result": {
    "contexts": [
      {
        "context": "93ee5bd6-d256-4608-a002-9a8995cc0e5f",
        "children": [
          {
            "context": "6442450945",
            "children": [],
            "originalOpener": null,
            "url": "https://example.com/frame.html",
            "userContext": "default",
            "clientWindow": "08c697a1-2664-447d-9c88-52bcee3bb386"
          }
        ],
        "originalOpener": null, // Opened directly
        "url": "https://example.com/page1.html",
        "userContext": "default",
        "clientWindow": "08c697a1-2664-447d-9c88-52bcee3bb386",
        "parent": null
      },
      {
        "context": "32ed30da-24ad-459d-8f0d-660526e92d96",
        "children": [],
        "originalOpener": "93ee5bd6-d256-4608-a002-9a8995cc0e5f", // Opened by Tab 1
        "url": "https://example.com/page2.html",
        "userContext": "default",
        "clientWindow": "08c697a1-2664-447d-9c88-52bcee3bb386",
        "parent": null
      }
    ]
  }
}