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

`browsingContext.getTree` command

· 52CE 我爱测

The `browsingContext.getTree` command of the `browsingContext` module returns the tree of all top-level contexts or the subtree starting with the specified context.

The browsingContext.getTree command of the browsingContext module returns the tree of all top-level contexts or the subtree starting with the specified context.

Syntax

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

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

Parameters

The params field can contain:

  • maxDepth
    • : A non-negative integer that specifies the maximum depth of the tree to return. If not included, which is equivalent to the value null, the full tree is returned. A value of 0 returns only the root context itself. For example, if a top-level context contains an <iframe>, which itself contains another <iframe>, then a maxDepth of 0 returns only the top-level context; a maxDepth of 1 returns the top-level context and the first <iframe>, but not the nested one.
  • root

Return value

The result object in the response contains the following fields:

  • contexts
    • : An array of context objects, each representing the properties of a context. Each object has the following fields:
      • children

        • : An array of context objects that represents the child contexts of this context. Each child object has the same structure, with its own children array, making this a recursive representation of the context tree. An empty array indicates that the context has no children, while a null value indicates that children are excluded from the response, such as when the maxDepth limit is reached.
      • clientWindow

        • : A string that contains the ID of the client window that contains this context.
      • context

        • : A string that contains the ID of the context.
      • originalOpener

        • : A string that contains the ID of the context that originally opened this context. The value is null if the context was opened directly (not by another context).

          [!NOTE] originalOpener is set once when the context is created. It never changes and always retains the opener's context ID. This differs from the JavaScript window.opener property, which references the window that opened the current window — it becomes null if the rel=noopener attribute is used on the link or if the noopener window feature is specified in window.open().

      • parent

        • : A string that contains the ID of the parent context. The value is null if the context has no parent. This field is present only for the root-level items in the returned array.
      • url

        • : A string that contains the URL of the context, including the fragment.
      • userContext

        • : A string that contains the ID of the user context associated with this context.

Errors

  • invalid argument
    • : A required parameter is missing or has an invalid type.
  • no such frame
    • : No context with the given root ID is found.

Examples

Getting all top-level contexts

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

Suppose two tabs are open in the browser: the first tab at https://example.com/page1.html has an <iframe> loading https://example.com/frame.html, and the second tab shows 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)

Send the following message to get the full context tree:

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

The contexts array lists the two top-level contexts. The <iframe> inside Tab 1 appears nested under its children. The browser responds as follows:

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

Getting a subtree from a specific context

Using the same setup as in the previous example, to get only Tab 1 and its immediate child context, send the following message with Tab 1's context ID as root and maxDepth set to 1:

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

The browser responds with Tab 1 and its immediate child. The children field for the iframe is null; the maxDepth setting of 1 limits the response to one level below the root, so the <iframe>'s own children are not included:

{
  "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 this example, if the root parameter of the browsingContext.getTree message were set to the iframe's context ID ("6442450945"), the <iframe>'s parent field in the response would be "93ee5bd6-d256-4608-a002-9a8995cc0e5f" (Tab 1's context ID) rather than null.

To limit the lookup to only the root context with no children, set maxDepth to 0:

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

The browser responds as follows:

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

Identifying the opener of a context

Expanding on the same setup, consider that Tab 2 (https://example.com/page2.html) was opened from Tab 1 (https://example.com/page1.html) using window.open(). Send the following message to see how this relationship is conveyed in the response:

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

The browser responds with the full context tree. The originalOpener field identifies the context that opened Tab 2:

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

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

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

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