VisualViewport
Baseline Widely available
This feature is well established and works across many devices and browser versions. It’s been available across browsers since August 2021.
Visual Viewport API (en-US) 提供了当前页面的视觉视口接口,即 VisualViewport
。对于每个页面容器来说(如 iframe),都存在有一个独立的 window 对象。每个页面容器的 window 对象都有一个独立的 VisualViewport
属性。
你可以使用 Window.visualViewport
获得对应 window 的视觉视口 API。
备注: 与布局视口(layout viewport)不同的是:只有最上层的 window 才有视觉视口(visual viewport)这一概念。因此只有最上层 window 的 VisualViewport
属性才是有效的,其他层的视觉视口属性可看作是布局视口属性的别名。比如,对于一个 <iframe>
,其对应的视觉视口属性 VisualViewport.width
(en-US) 相当于对应的布局视口属性,如 document.documentElement.clientWidth
.
属性
VisualViewport
从其父元素继承属性 EventTarget
。
VisualViewport.offsetLeft
(en-US) 只读-
返回视觉视口的左边框到布局视口的左边框的 CSS 像素距离。
VisualViewport.offsetTop
只读-
返回视觉视口的上边框到布局视口的上边框的 CSS 像素距离。
VisualViewport.pageLeft
(en-US) 只读-
返回相对于初始的 viewport 属性的 X 轴坐标所对应的 CSS 像素数。
VisualViewport.pageTop
(en-US) 只读-
返回相对于初始的 viewport 属性的 Y 轴坐标所对应的 CSS 像素数。
VisualViewport.width
(en-US) 只读-
返回视觉视口的宽度所对应的 CSS 像素数。
VisualViewport.height
(en-US) 只读-
返回视觉视口的高度所对应的 CSS 像素数。
VisualViewport.scale
(en-US) 只读-
返回当前视觉视口所应用的缩放比例。
Events
通过使用 addEventListener()
或者将监听回调函数赋值给对应的 oneventname
属性,可以为对应的视口事件添加监听。
resize
(en-US)-
当视觉视口被改变时触发。 也可以为
VisualViewport.onresize
(en-US) 属性赋值来添加监听。 scroll
(en-US)-
当视觉视口滑动时触发。 也可以为
VisualViewport.onscroll
(en-US) 属性赋值来添加监听。
例子
缩放检测并隐藏元素
这个例子取自 Visual Viewport 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);
模拟 position 属性:device-fixed
这个例子同样取自 Visual Viewport README ,展示了如何使用视觉视口 API,从而模拟 position: device-fixed
的 CSS 属性。类似于 position: fixed
,这一属性可将被设置的元素固定在视觉视口特定位置。此外,你也可以查看另一个 例子 。
var bottomBar = document.getElementById("bottombar");
var viewport = window.visualViewport;
function viewportHandler() {
var 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.
var offsetLeft = viewport.offsetLeft;
var 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
可能会导致其他元素在滚动页面时出现闪烁。
规范
Specification |
---|
CSSOM View Module # the-visualviewport-interface |
浏览器兼容性
BCD tables only load in the browser
参照
- Web 视口说明 — 解释了什么是浏览器视口和视觉视口和布局视口的区别。