视觉视口的定义

视觉视口 是一种 视口，其 滚动区域 是另一个 视口，称为 布局视口。

除了滚动之外，视觉视口 还允许对其 布局视口 应用缩放变换。此变换应用于 布局视口 的画布，并且不会影响其内部坐标空间。

缩放变换的大小称为视觉视口的 缩放因子。

窗口 对象有一个 关联的 视觉视口，它是一个 VisualViewport 对象。每个 视觉视口 都与一个永不改变的 窗口 对象关联。视觉视口 的 关联文档 是其 关联的 窗口的 关联文档。

对 Window 接口的扩展

本文档扩展了 [[HTML]] 中定义的 Window 接口。

            partial interface Window {
              [SameObject, Replaceable] readonly attribute VisualViewport? visualViewport;
            };
          

visualViewport

如果 关联文档是 完全活动的，则返回与 窗口 关联的 VisualViewport 对象。否则，返回 null。

直观地说，VisualViewport 对象仅在其 窗口的 文档当前正在呈现时返回并有用。如果保留了对 VisualViewport 的引用，而其 关联文档当前未被呈现，则该 VisualViewport 中的值不得透露任何关于 浏览上下文的信息。

VisualViewport 接口

一个 VisualViewport 对象表示一个 文档正在被呈现的 视觉视口，如果它是 完全活动的。页面中的每个 窗口都有其独特的 VisualViewport 对象。

在任何浏览上下文中呈现的文档，包括嵌套的浏览上下文，都将拥有其自己的视觉视口。然而，大多数用户代理仅在顶级浏览上下文中修改视觉视口。在嵌套浏览上下文中的视觉视口是为了方便而提供的。

例如：如果脚本保留了对 iframe 的 VisualViewport 的引用，然后将 iframe 导航到另一个位置，从该 VisualViewport 引用读取的值将返回 0，因为其窗口的文档不再在浏览内容中呈现；它不再是完全活动的。

除非另有说明，本节中返回的所有值均以 CSS 像素 定义。

            [Exposed=Window]
            interface VisualViewport : EventTarget {
              readonly attribute double offsetLeft;
              readonly attribute double offsetTop;

              readonly attribute double pageLeft;
              readonly attribute double pageTop;

              readonly attribute double width;
              readonly attribute double height;

              readonly attribute double scale;

              readonly attribute FrozenArray<DOMRect>? segments;

              attribute EventHandler onresize;
              attribute EventHandler onscroll;
            };
          

offsetLeft

如果 视觉视口的 关联文档不是 完全活动的，返回 0。

否则，返回 视觉视口左边缘与 布局视口左边缘的偏移量。

offsetTop

如果 视觉视口的 关联文档不是 完全活动的，返回 0。

否则，返回视觉视口顶部边缘与 布局视口顶部边缘的偏移量。

pageLeft

如果 视觉视口的 关联文档不是 完全活动的，返回 0。

否则，返回视觉视口左边缘与 布局视口的 初始包含块左边缘的偏移量。

pageTop

如果 视觉视口的 关联文档不是 完全活动的，返回 0。

否则，返回视觉视口顶部边缘与 布局视口的 初始包含块顶部边缘的偏移量。

width

如果 视觉视口的 关联文档不是 完全活动的，返回 0。

否则，返回视觉视口的宽度（以 CSS 像素为单位）。此值不包括固定到视觉视口的任何渲染的 经典滚动条 的宽度。

固定到视觉视口的滚动条是指在视觉视口缩放和平移时，其大小或位置不会改变的滚动条。 由于此值以 CSS 像素为单位，因此在排除滚动条宽度时，用户代理必须考虑滚动条在 CSS 像素中的大小。也就是说，如果视口被放大且滚动条对用户的大小未改变，则排除的量会减少。

height

如果 视觉视口的 关联文档不是 完全活动的，返回 0。

否则，返回视觉视口的高度（以 CSS 像素为单位）。此值不包括固定到视觉视口的任何渲染的经典滚动条的高度。

由于宽度和高度属性均以 CSS 像素表示，增加页面缩放或捏合缩放都会导致这些值缩小。

scale

返回 视觉视口的 缩放因子。可以使用以下算法计算：

虽然通常被称为捏合缩放因子，但它也可以通过其他方式影响，例如当用户代理居中并放大一个聚焦的输入元素时。

1. 如果 视觉视口的 关联文档不是 完全活动的，返回 0 并中止这些步骤。

2. 如果没有输出设备，返回 1 并中止这些步骤。

3. 令 CSS 像素大小 为 CSS 参考像素 的大小，按当前 页面缩放和与此 窗口关联的 视觉视口的 缩放因子 缩放。

4. 令 设备像素大小 为输出设备的设备像素大小。

5. 令 设备无关像素大小 为 设备像素大小 和 devicePixelRatio 的乘积。

   视觉视口缩放（例如捏合缩放）不会影响 devicePixelRatio。

6. 返回 CSS 像素大小 除以 设备无关像素大小 的结果。

segments

视口段属性目前正在开发中，并被认为是实验性的。

返回一个 DOMRects 数组，表示每个现有视口段的尺寸。

视口段表示视觉视口中位于单独显示器或逻辑显示区域的区域。 当视觉视口跨越设备的一些物理特性时，这些特性反过来传达了可用于内容的空间的逻辑分离。

当只有一个视口段时，segments 为 null。从 iframe 上下文中调用时返回 null。

根据每个视口段返回的数据，开发者可以推断可用的铰链数量以及铰链方向。 浏览器窗口可以移动/调整大小，从而改变段的数量和/或其尺寸。在这些情况下，将触发 resize 事件，此时作者应重新查询此属性，因为返回的 FrozenArray 只是当前状态的快照。

onresize

用于 resize 事件的事件处理程序属性。

onscroll

用于 scroll 事件的事件处理程序属性。

对 CSSOM-VIEW Events 部分的补充

将以下步骤追加为 运行调整大小步骤 的最后一步：

将 运行滚动步骤 的第 1.1 步替换为：