Befehl script.getRealms

Syntax

/* With no parameters */
{
  "method": "script.getRealms",
  "params": {}
}

/* With optional parameters */
{
  "method": "script.getRealms",
  "params": {
    "context": "93ee5bd6-d256-4608-a002-9a8995cc0e5f",
    "type": "window"
  }
}

Parameter

Das Feld params kann Folgendes enthalten:

context Optional

Ein String mit der ID des Kontexts, dessen Realms Sie auflisten möchten. Kontext-IDs werden von Befehlen wie browsingContext.getTree zurückgegeben. Wenn das Feld nicht angegeben ist, werden die Realms aller Kontexte zurückgegeben.

type Optional

Ein String mit dem Realm-Typ, den Sie auflisten möchten. Er kann einen der folgenden Werte annehmen:

• "window": Ein Realm, dessen globales Objekt ein Window ist. Dazu gehören Sandbox-Realms.
• "worker": Ein Realm, dessen globales Objekt ein WorkerGlobalScope ist, jedoch keiner der spezifischeren globalen Geltungsbereiche für Dedicated Worker, Shared Worker oder Service Worker.
• "dedicated-worker": Ein Realm, dessen globales Objekt ein DedicatedWorkerGlobalScope ist.
• "shared-worker": Ein Realm, dessen globales Objekt ein SharedWorkerGlobalScope ist.
• "service-worker": Ein Realm, dessen globales Objekt ein ServiceWorkerGlobalScope ist.
• "worklet": Ein Realm, dessen globales Objekt ein WorkletGlobalScope ist, jedoch keiner der spezifischeren globalen Geltungsbereiche für Audio- oder Paint-Worklets.
• "audio-worklet": Ein Realm, dessen globales Objekt ein AudioWorkletGlobalScope ist.
• "paint-worklet": Ein Realm, dessen globales Objekt ein PaintWorkletGlobalScope ist.

Wenn das Feld type nicht angegeben ist, werden Realms aller Typen zurückgegeben.

Rückgabewert

Das Objekt result in der Antwort enthält das folgende Feld:

realms

Ein Array von Realm-Objekten, eines für jeden passenden Realm, oder ein leeres Array, wenn keine passenden Realms vorhanden sind. Der Wert des Felds type in jedem Objekt bestimmt, welche weiteren Felder vorhanden sind:

context Optional

Ein String mit der ID des Kontexts, zu dem der Realm gehört. Dieses Feld ist nur enthalten, wenn der Wert von type "window" ist.

origin

Ein String mit der Origin des Realms.

owners Optional

Ein Array mit einem einzigen Element: der ID des Realms, dem der Worker gehört. Dieses Feld ist nur enthalten, wenn der Wert von type "dedicated-worker" ist.

realm

Ein String mit der ID des Realms.

sandbox Optional

Ein String mit dem Namen des Sandbox-Realms. Dieses Feld ist nur bei einem Sandbox-Realm enthalten, dessen Typ "window" ist.

type

Ein String, der den Realm-Typ angibt. Mögliche Werte finden Sie beim Parameter type.

Fehler

invalid argument

Ein Parameter hat einen ungültigen Typ. Dieser Fehler wird auch zurückgegeben, wenn type keiner der erkannten Realm-Typen ist.

no such frame

Es wurde kein Kontext mit der angegebenen context-ID gefunden.

Beschreibung

Mit dem Befehl script.getRealms können Sie Realm-IDs ermitteln. Diese können Sie anschließend anstelle einer Kontext-ID an Befehle wie script.evaluate, script.callFunction oder script.disown übergeben. Da Worker- und Worklet-Realms keine zugehörige Kontext-ID haben, können Sie ein Skript darin nur ausführen, indem Sie direkt auf den Realm verweisen.

Ein Kontext kann mehrere Realms haben. Wenn Sie nach context filtern, können daher der Realm des aktiven Dokuments, Sandbox-Realms und die Realms der Worker zurückgegeben werden, die dem Dokument gehören. Die Realms untergeordneter Kontexte sind nicht enthalten. Um die Realms eines untergeordneten Kontexts abzurufen, rufen Sie den Befehl mit der ID dieses Kontexts auf.

Es werden nur Realms zurückgegeben, die bereit sind, Skripte auszuführen. Ein Realm, der noch initialisiert wird, erscheint daher nicht im Ergebnis. Realm-IDs ändern sich bei jeder Navigation zu einem anderen Dokument. Rufen Sie sie nach einer solchen Navigation daher erneut ab.

Beispiele

Alle Realms abrufen

Angenommen, Sie haben eine WebDriver-BiDi-Verbindung und eine aktive Sitzung.

Angenommen, ein Tab ist unter https://example.com geöffnet und die Seite hat einen Dedicated Worker gestartet. Außerdem haben Sie zuvor mit script.evaluate einen Sandbox-Realm namens myAutomationSandbox erstellt.

Senden Sie die folgende Nachricht, um alle verfügbaren Realms abzurufen:

{
  "id": 1,
  "method": "script.getRealms",
  "params": {}
}

Der Browser antwortet mit den drei Realms wie folgt:

{
  "id": 1,
  "type": "success",
  "result": {
    "realms": [
      {
        "context": "93ee5bd6-d256-4608-a002-9a8995cc0e5f",
        "origin": "https://example.com",
        "realm": "7c37f4c0-abcd-1234-ef56-789012345678",
        "type": "window"
      },
      {
        "context": "93ee5bd6-d256-4608-a002-9a8995cc0e5f",
        "origin": "https://example.com",
        "realm": "e4f5a6b7-c8d9-4012-b3c4-d5e6f7a8b9c0",
        "sandbox": "myAutomationSandbox",
        "type": "window"
      },
      {
        "origin": "https://example.com",
        "owners": ["7c37f4c0-abcd-1234-ef56-789012345678"],
        "realm": "a1b2c3d4-e5f6-4708-9a1b-2c3d4e5f6071",
        "type": "dedicated-worker"
      }
    ]
  }
}

Nur die Window-Realms eines Kontexts abrufen

Angenommen, Sie öffnen mit derselben Verbindung und Sitzung wie im vorherigen Beispiel einen zweiten Tab unter https://example.net. Der neue Tab hat einen eigenen Kontext.

Senden Sie die folgende Nachricht, um nur die Window-Realms des ersten Tabs unter https://example.com abzurufen:

{
  "id": 2,
  "method": "script.getRealms",
  "params": {
    "context": "93ee5bd6-d256-4608-a002-9a8995cc0e5f",
    "type": "window"
  }
}

Der Browser antwortet nur mit den Realms, die dem angegebenen context und type entsprechen. Der Realm des Dedicated Workers entspricht nicht dem angegebenen type, und der Realm des zweiten Tabs gehört zu einem anderen context. Daher fehlen beide in der Antwort:

{
  "id": 2,
  "type": "success",
  "result": {
    "realms": [
      {
        "context": "93ee5bd6-d256-4608-a002-9a8995cc0e5f",
        "origin": "https://example.com",
        "realm": "7c37f4c0-abcd-1234-ef56-789012345678",
        "type": "window"
      },
      {
        "context": "93ee5bd6-d256-4608-a002-9a8995cc0e5f",
        "origin": "https://example.com",
        "realm": "e4f5a6b7-c8d9-4012-b3c4-d5e6f7a8b9c0",
        "sandbox": "myAutomationSandbox",
        "type": "window"
      }
    ]
  }
}

Spezifikationen

Browser-Kompatibilität

Siehe auch

• Befehl script.callFunction
• Befehl script.disown
• Befehl script.evaluate
• Ereignis script.realmCreated
• Ereignis script.realmDestroyed