视窗视口

基线广泛可用

此功能已建立良好，并在许多设备和浏览器版本上运行。它已在各种浏览器中可用，自 2021 年 8 月.

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

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

注意：只有顶层窗口的视窗视口与布局视口不同。因此，通常只有顶层窗口的 VisualViewport 对象才有用。对于 <iframe>，视窗视口度量（如 VisualViewport.width）始终对应于布局视口度量（如 document.documentElement.clientWidth）。

实例属性

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

VisualViewport.offsetLeft 只读: 以 CSS 像素为单位返回视窗视口左边缘相对于布局视口左边缘的偏移量。
VisualViewport.offsetTop 只读: 以 CSS 像素为单位返回视窗视口上边缘相对于布局视口上边缘的偏移量。
VisualViewport.pageLeft 只读: 以 CSS 像素为单位返回视窗视口相对于顶边初始包含块原点的 x 坐标。
VisualViewport.pageTop 只读: 以 CSS 像素为单位返回视窗视口相对于顶边初始包含块原点的 y 坐标。
VisualViewport.width 只读: 以 CSS 像素为单位返回视窗视口的宽度。
VisualViewport.height 只读: 以 CSS 像素为单位返回视窗视口的高度。
VisualViewport.scale 只读: 返回应用于视窗视口的捏合缩放比例。

实例方法

还从其父接口 EventTarget 继承方法。

事件

使用 addEventListener() 或通过将事件侦听器分配给此接口的相应 oneventname 属性来侦听这些事件。

调整大小: 当视窗视口大小发生改变时触发。也可通过 onresize 属性访问。
滚动: 当视窗视口滚动时触发。也可通过 onscroll 属性访问。
滚动结束: 当视窗视口上的滚动操作结束时触发。也可通过 onscrollend 属性访问。

示例

在缩放时隐藏叠加框

此示例来自视窗视口自述文件，展示了如何编写一段简单的代码，在用户放大时隐藏叠加框（例如可能包含广告）。这是一种在页面放大时改善用户体验的好方法。一个实时示例也可用。

const bottomBar = document.getElementById("bottombar");
const viewport = window.visualViewport;

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

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

模拟位置：设备固定

此示例也来自视窗视口自述文件，展示了如何使用此 API 模拟 position: device-fixed，它将元素固定到视窗视口。一个实时示例也可用。

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

  // Since the bar is position: fixed we need to offset it by the visual
  // viewport's offset from the layout viewport origin.
  const offsetLeft = viewport.offsetLeft;
  const offsetTop =
    viewport.height -
    layoutViewport.getBoundingClientRect().height +
    viewport.offsetTop;

  // You could also do this by setting style.left and style.top if you
  // use width: 100% instead.
  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 会导致固定元素在滚动时闪烁。

规范

规范
CSSOM 视图模块 # the-visualviewport-interface

浏览器兼容性

BCD 表格仅在启用 JavaScript 的浏览器中加载。

另请参阅

Web 视口说明 — 对 Web 视口概念的有用解释，包括视窗视口和布局视口之间的区别。