VisualViewport - 表示给定窗口的可视视口

VisualViewport 是 Visual Viewport API 的接口，表示给定窗口的可视视口。对于包含 iframe 的页面，每个 iframe 以及所包含的页面都将具有唯一的窗口对象。页面上的每个窗口都有一个唯一的 VisualViewport，表示与该窗口关联的属性。

您可以使用 Window.visualViewport 获得窗口的可视视口。

注意：仅顶层窗口具有与布局视口不同的可视视口。因此，通常只有顶层窗口的 VisualViewport 对象才有用。对于 <iframe>，像 VisualViewport.width 这样的可视视口指标始终对应于 document.documentElement .clientWidth。

属性

VisualViewport 还从其父接口 EventTarget 继承了属性。

VisualViewport.offsetLeft 只读

返回可视视口的左边缘相对于布局视口的左边缘的偏移量（以 CSS 像素为单位）。

VisualViewport.offsetTop 只读

返回可视视口的顶部边缘与布局视口的顶部边缘之间的偏移量（以 CSS 像素为单位）。

VisualViewport.pageLeft 只读

返回可视视口相对于顶部边缘的初始包含块原点的 x 坐标（以 CSS 像素为单位）。

VisualViewport.pageTop 只读

返回可视视口相对于顶部边缘的初始包含块原点的 y 坐标（以 CSS 像素为单位）。

VisualViewport.width 只读

返回可视视口的宽度（以 CSS 像素为单位）。

VisualViewport.height 只读

返回可视视口的高度（以 CSS 像素为单位）。

VisualViewport.scale 只读

返回应用于可视视口的收缩缩放比例因子。

事件

使用 addEventListener() 或通过为 oneventname 属性分配事件监听器来监听这个接口的事件。

resize

调整视口大小时触发。也可以通过 VisualViewport.onresize 属性处理。

scroll

滚动可视视口时触发。也可以通过 VisualViewport.onscroll 属性处理。

实例

在缩放时隐藏覆盖的框

此实例摘自 可视视口 README，展示了如何编写简单的代码，当用户放大时，隐藏覆盖框（例如，其中可能包含广告）。这是一种改善页面放大时用户体验的好方法。也可以查看在线实例。

var bottomBar = document.getElementById('bottombar');
var viewport = window.visualViewport;

function resizeHandler() {
   if (viewport.scale > 1.3)
     bottomBar.style.display = "none";
   else
     bottomBar.style.display = "block";
}

window.visualViewport.addEventListener('resize', resizeHandler);

模拟位置：设备固定

此实例也取自可视视口 README，展示了如何使用此 API 模拟 position: device-fixed，它将元素固定到可视视口。也可以查看在线实例。

var bottomBar = document.getElementById('bottombar');
var viewport = window.visualViewport;
function viewportHandler() {
  var layoutViewport = document.getElementById('layoutViewport');

  // 由于条形图的位置是固定的，因此我们需要将其从可视视口到布局视口原点的偏移量进行偏移。
  var offsetLeft = viewport.offsetLeft;
  var offsetTop = viewport.height
              - layoutViewport.getBoundingClientRect().height
              + viewport.offsetTop;

  // 如果使用 width:100％，也可以通过设置 style.left 和 style.top 来实现。
  bottomBar.style.transform = 'translate(' +
                              offsetLeft + 'px,' +
                              offsetTop + 'px) ' +
                              'scale(' + 1/viewport.scale + ')'
}
window.visualViewport.addEventListener('scroll', viewportHandler);
window.visualViewport.addEventListener('resize', viewportHandler);

注意：应谨慎使用此技术；以这种方式模拟 position: device-fixed 会导致固定元素在滚动过程中闪烁。

规范

规范	状态	备注
Visual Viewport API VisualViewport 的定义	草稿	初始定义。

桌面浏览器兼容性

移动浏览器兼容性

相关链接

• Web 视口说明 — Web 视口概念的有用说明，包括可视视口和布局视口之间的区别。