大网数据广告活动
Web 标准与前端开发

`script.getRealms` command

· 52CE 我爱测

The `script.getRealms` command of the `script` module returns a list of all realms. You can optionally filter the list by context or by the type of realm.

The script.getRealms command of the script module returns a list of all realms. You can optionally filter the list by context or by the type of realm.

Syntax

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

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

Parameters

The params field can contain:

  • context
    • : A string that contains the ID of the context whose realms you want to list. Context IDs are returned by commands such as browsingContext.getTree. If not specified, realms of all contexts are returned.
  • type
    • : A string that contains the type of realm you want to list. It can take one of the following values:

      • "window": A realm whose global object is a Window. This includes sandbox realms.
      • "worker": A realm whose global object is a WorkerGlobalScope, but not one of the more specific dedicated, shared, or service worker global scopes.
      • "dedicated-worker": A realm whose global object is a DedicatedWorkerGlobalScope.
      • "shared-worker": A realm whose global object is a SharedWorkerGlobalScope.
      • "service-worker": A realm whose global object is a ServiceWorkerGlobalScope.
      • "worklet": A realm whose global object is a WorkletGlobalScope, but not one of the more specific audio or paint worklet global scopes.
      • "audio-worklet": A realm whose global object is an AudioWorkletGlobalScope.
      • "paint-worklet": A realm whose global object is a PaintWorkletGlobalScope.

      If the type field is not specified, realms of all types are returned.

Return value

The result object in the response contains the following field:

  • realms
    • : An array of realm objects, one for each matching realm, or an empty array if there are no matching realms. The value of the type field in each object determines the other fields that are present:
      • context
        • : A string that contains the ID of the context to which the realm belongs. This field is included only when the type field value is "window".
      • origin
        • : A string with the origin of the realm.
      • owners
        • : A single-element array that contains the ID of the realm that owns the worker. This field is included only when the type field value is "dedicated-worker".
      • realm
        • : A string that contains the ID of the realm.
      • sandbox
        • : A string that contains the name of the sandbox realm. This field is included only for a sandbox realm, which is of type "window".
      • type
        • : A string that indicates the type of realm. See the type parameter for possible values.

Errors

  • invalid argument
    • : A parameter has an invalid type. This error is also returned when type is not one of the recognized realm types.
  • no such frame
    • : No context with the given context ID is found.

Description

The script.getRealms command lets you discover realm IDs, which you can then pass to commands such as script.evaluate, script.callFunction, or script.disown instead of a context ID. Since worker and worklet realms have no associated context ID, referring to a realm directly is the only way to run a script in them.

A context can have several realms, so filtering by context can return the realm of the active document, any sandbox realms, and any realms of the workers that the document owns. The realms of child contexts are not included. To get the realms of a child context, call the command with the ID of that context.

Only realms that are ready to run scripts are returned, so a realm that is still initializing does not appear in the result. Realm IDs change on each cross-document navigation, so make sure to fetch them again after navigating.

Examples

Getting all realms

Assume you have a WebDriver BiDi connection and an active session.

Suppose a tab is open at https://example.com and the page has started a dedicated worker. You also created a sandbox realm named myAutomationSandbox earlier using script.evaluate.

Send the following message to get every available realm:

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

The browser responds with the three realms as follows:

{
  "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"
      }
    ]
  }
}

Getting only the window realms of one context

Using the same connection and session as in the previous example, suppose you open a second tab at https://example.net. The new tab has its own context.

Send the following message to get only the window realms of the first tab, the one at https://example.com:

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

The browser responds with only the realms that match the specified context and type. The realm of the dedicated worker does not match the type, and the realm of the second tab belongs to a different context, so both are omitted from the response:

{
  "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"
      }
    ]
  }
}

Specifications

Browser compatibility

See also

来源:MDN Web Docs / Mozilla 贡献者 · 作者与贡献记录 · CC BY-SA 2.5。离线整理了版式、链接和媒体显示。

资料来源与适用范围

资料来源
MDN Web Docs / Mozilla 贡献者
适用范围
请按文中版本与环境说明核对
内容语言
中文;命令、路径和错误标识保留技术原文
本地收录日期
2026-11-15
授权说明
CC BY-SA 2.5

正文与所需资源由本站本地存储。查看来源及更新记录 ↗

请按适用版本和实际日志确认原因;本站没有对每一种系统或设备逐项执行文中的操作。