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

`browsingContext.setViewport` command

· 52CE 我爱测

The `browsingContext.setViewport` command of the `browsingContext` module changes viewport characteristics, such as the viewport size and the device pixel ratio, for one or more top-level contexts.

The browsingContext.setViewport command of the browsingContext module changes viewport characteristics, such as the viewport size and the device pixel ratio, for one or more top-level contexts.

Syntax

/* With the required `context` parameter */
{
  "method": "browsingContext.setViewport",
  "params": {
    "context": "93ee5bd6-d256-4608-a002-9a8995cc0e5f"
  }
}

/* With the required `userContexts` parameter */
{
  "method": "browsingContext.setViewport",
  "params": {
    "userContexts": ["a812d4d0-8c8f-4c78-9de1-3e5c5b3b3c3c"]
  }
}

/* With required and optional parameters */
{
  "method": "browsingContext.setViewport",
  "params": {
    "context": "93ee5bd6-d256-4608-a002-9a8995cc0e5f",
    "viewport": {
      "width": 1280,
      "height": 720
    },
    "devicePixelRatio": 3.0
  }
}

Parameters

The params field contains:

  • context
    • : A string that contains the ID of the top-level context in which to apply the viewport settings. Context IDs are returned by commands such as browsingContext.getTree.

      This field cannot be used if userContexts is also specified.

  • userContexts

For both context and userContexts, the params field can also contain:

  • devicePixelRatio
    • : A number greater than 0.0 that overrides the Window.devicePixelRatio, or null to remove the override and restore the actual device pixel ratio. If not specified, the device pixel ratio is left unchanged.
  • viewport
    • : An object that specifies the new viewport size using the following fields, or null to reset to the browser's default viewport size:

      • height
        • : A non-negative integer that specifies the viewport height in CSS pixels.
      • width
        • : A non-negative integer that specifies the viewport width in CSS pixels.

      If not specified, the viewport size is left unchanged.

Return value

The result field in the response is an empty object ({}).

Errors

  • invalid argument
    • : Thrown in any of the following cases:
      • A required parameter is missing or has an invalid type.
      • Both context and userContexts are provided in the same request.
      • Neither context nor userContexts is provided.
      • The context specified by context is not a top-level context.
  • no such frame
    • : No context with the given context ID is found.
  • no such user context
    • : No user context with the given user context ID is found.
  • unsupported operation
    • : The browser cannot adjust the viewport with the given parameters.

Description

This command allows you to change the characteristics of the viewport of a specific context, which can be useful to emulate narrow viewports or test responsive design. Specify context to apply the viewport settings to a single top-level context or userContexts to apply them to every top-level context in one or more user contexts.

When userContexts is specified, the viewport size and devicePixelRatio you provide apply to every top-level context currently in each given user context. They also apply to every top-level context created later in that user context until you change or clear them with another setViewport command.

Examples

Resizing a single tab's viewport

With a WebDriver BiDi connection and an active session, send the following message to resize a tab's viewport to 480x640 CSS pixels:

{
  "id": 1,
  "method": "browsingContext.setViewport",
  "params": {
    "context": "93ee5bd6-d256-4608-a002-9a8995cc0e5f",
    "viewport": {
      "width": 480,
      "height": 640
    }
  }
}

The browser responds as follows:

{
  "id": 1,
  "type": "success",
  "result": {}
}

Overriding the device pixel ratio

Using the same connection and session as in the first example, send the following message to simulate a high-density display without changing the viewport size:

{
  "id": 2,
  "method": "browsingContext.setViewport",
  "params": {
    "context": "93ee5bd6-d256-4608-a002-9a8995cc0e5f",
    "devicePixelRatio": 3.0
  }
}

The browser responds as follows:

{
  "id": 2,
  "type": "success",
  "result": {}
}

Applying a viewport override to a user context

Using the same connection and session as in the first example, send the following message to apply the viewport settings to every top-level context in the specified user context:

{
  "id": 3,
  "method": "browsingContext.setViewport",
  "params": {
    "userContexts": ["a812d4d0-8c8f-4c78-9de1-3e5c5b3b3c3c"],
    "viewport": {
      "width": 375,
      "height": 667
    }
  }
}

The browser responds as follows:

{
  "id": 3,
  "type": "success",
  "result": {}
}

Removing a viewport override

Using the same connection and session as in the first example, send the following message to restore the default viewport size on a context by setting viewport to null:

{
  "id": 4,
  "method": "browsingContext.setViewport",
  "params": {
    "context": "93ee5bd6-d256-4608-a002-9a8995cc0e5f",
    "viewport": null
  }
}

The browser responds as follows:

{
  "id": 4,
  "type": "success",
  "result": {}
}

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

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

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