VisualViewport

这是一个实验中的功能
此功能某些浏览器尚在开发中,请参考浏览器兼容性表格以得到在不同浏览器中适合使用的前缀。由于该功能对应的标准文档可能被重新修订,所以在未来版本的浏览器中该功能的语法和行为可能随之改变。

 Visual Viewport API 提供了当前页面的视觉视口接口,即 VisualViewport 。对于每个页面容器来说(如 iframe),都存在有一个独立的 window 对象。每个页面容器的 window 对象都有一个独立的 VisualViewport 属性。

你可以使用 Window.visualViewport 获得对应 window 的视觉视口 API。

注意:与布局视口(layout viewport)不同的是:只有最上层的 window 才有视觉视口(visual viewport)这一概念。因此只有最上层 window 的 VisualViewport 属性才是有效的,其他层的视觉视口属性可看作是布局视口属性的别名。比如,对于一个 <iframe> ,其对应的视觉视口属性 VisualViewport.width 相当于对应的布局视口属性,如 document.documentElement.clientWidth.

属性

VisualViewport 从其父元素继承属性 EventTarget

VisualViewport.offsetLeft 只读
返回视觉视口的左边框到布局视口的左边框的 CSS 像素距离。
VisualViewport.offsetTop 只读
返回视觉视口的上边框到布局视口的上边框的 CSS 像素距离。
VisualViewport.pageLeft 只读
返回相对于初始的 viewport 属性的 X 轴坐标所对应的 CSS 像素数。
VisualViewport.pageTop 只读
返回相对于初始的 viewport 属性的 Y 轴坐标所对应的 CSS 像素数。
VisualViewport.width 只读
返回视觉视口的宽度所对应的 CSS 像素数。
VisualViewport.height 只读
返回视觉视口的高度所对应的 CSS 像素数。
VisualViewport.scale 只读
返回当前视觉视口所应用的缩放比例。

Events

通过使用 addEventListener() 或者将监听回调函数赋值给对应的 oneventname 属性,可以为对应的视口事件添加监听。

resize
当视觉视口被改变时触发。
也可以为 VisualViewport.onresize 属性赋值来添加监听。
scroll
当视觉视口滑动时触发。
也可以为 VisualViewport.onscroll 属性赋值来添加监听。

例子

缩放检测并隐藏元素

这个例子取自 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 可能会导致其他元素在滚动页面时出现闪烁。

规范

规范 状态 提交
Visual Viewport API
VisualViewport
Draft Initial definition.

浏览器兼容性

Update compatibility data on GitHub
DesktopMobile
ChromeEdgeFirefoxInternet ExplorerOperaSafariAndroid webviewChrome for AndroidFirefox for AndroidOpera for AndroidSafari on iOSSamsung Internet
VisualViewport
Experimental
Chrome Full support 61Edge Full support 79Firefox Full support 63
Disabled
Full support 63
Disabled
Disabled From version 63: this feature is behind the dom.visualviewport.enabled preference (needs to be set to true). To change preferences in Firefox, visit about:config.
IE No support NoOpera Full support 48Safari Full support 13WebView Android Full support 61Chrome Android Full support 61Firefox Android Full support 68
Full support 68
Full support 63
Disabled
Disabled From version 63: this feature is behind the dom.visualviewport.enabled preference (needs to be set to true). To change preferences in Firefox, visit about:config.
Opera Android Full support 45Safari iOS Full support 13Samsung Internet Android Full support 8.0
height
Experimental
Chrome Full support 61Edge Full support 79Firefox Full support 63
Disabled
Full support 63
Disabled
Disabled From version 63: this feature is behind the dom.visualviewport.enabled preference (needs to be set to true). To change preferences in Firefox, visit about:config.
IE No support NoOpera Full support 48Safari Full support 13WebView Android Full support 61Chrome Android Full support 61Firefox Android Full support 68
Full support 68
Full support 63
Disabled
Disabled From version 63: this feature is behind the dom.visualviewport.enabled preference (needs to be set to true). To change preferences in Firefox, visit about:config.
Opera Android Full support 45Safari iOS Full support 13Samsung Internet Android Full support 8.0
offsetLeft
Experimental
Chrome Full support 61Edge Full support 79Firefox Full support 63
Disabled
Full support 63
Disabled
Disabled From version 63: this feature is behind the dom.visualviewport.enabled preference (needs to be set to true). To change preferences in Firefox, visit about:config.
IE No support NoOpera Full support 48Safari Full support 13WebView Android Full support 61Chrome Android Full support 61Firefox Android Full support 68
Full support 68
Full support 63
Disabled
Disabled From version 63: this feature is behind the dom.visualviewport.enabled preference (needs to be set to true). To change preferences in Firefox, visit about:config.
Opera Android Full support 45Safari iOS Full support 13Samsung Internet Android Full support 8.0
offsetTop
Experimental
Chrome Full support 61Edge Full support 79Firefox Full support 63
Disabled
Full support 63
Disabled
Disabled From version 63: this feature is behind the dom.visualviewport.enabled preference (needs to be set to true). To change preferences in Firefox, visit about:config.
IE No support NoOpera Full support 48Safari Full support 13WebView Android Full support 61Chrome Android Full support 61Firefox Android Full support 68
Full support 68
Full support 63
Disabled
Disabled From version 63: this feature is behind the dom.visualviewport.enabled preference (needs to be set to true). To change preferences in Firefox, visit about:config.
Opera Android Full support 45Safari iOS Full support 13Samsung Internet Android Full support 8.0
onresize
Experimental
Chrome Full support 62
Full support 62
Partial support 61
Edge Full support 79Firefox Full support 66
Disabled
Full support 66
Disabled
Disabled From version 66: this feature is behind the dom.visualviewport.enabled preference (needs to be set to true). To change preferences in Firefox, visit about:config.
IE No support NoOpera Full support 49
Full support 49
Partial support 48
Safari Full support 13WebView Android Full support 62
Full support 62
Partial support 61
Chrome Android Full support 62
Full support 62
Partial support 61
Firefox Android Full support 68
Full support 68
Full support 66
Disabled
Disabled From version 66: this feature is behind the dom.visualviewport.enabled preference (needs to be set to true). To change preferences in Firefox, visit about:config.
Opera Android Full support 46
Full support 46
Partial support 45
Safari iOS Full support 13Samsung Internet Android Full support 8.0
Full support 8.0
Partial support 8.0
onscroll
Experimental
Chrome Full support 62
Full support 62
Partial support 61
Edge Full support 79Firefox Full support 66
Disabled
Full support 66
Disabled
Disabled From version 66: this feature is behind the dom.visualviewport.enabled preference (needs to be set to true). To change preferences in Firefox, visit about:config.
IE No support NoOpera Full support 49
Full support 49
Partial support 48
Safari Full support 13WebView Android Full support 62
Full support 62
Partial support 61
Chrome Android Full support 62
Full support 62
Partial support 61
Firefox Android Full support 68
Full support 68
Full support 66
Disabled
Disabled From version 66: this feature is behind the dom.visualviewport.enabled preference (needs to be set to true). To change preferences in Firefox, visit about:config.
Opera Android Full support 46
Full support 46
Partial support 45
Safari iOS Full support 13Samsung Internet Android Full support 8.0
Full support 8.0
Partial support 8.0
pageLeft
Experimental
Chrome Full support 61Edge Full support 79Firefox Full support 63
Disabled
Full support 63
Disabled
Disabled From version 63: this feature is behind the dom.visualviewport.enabled preference (needs to be set to true). To change preferences in Firefox, visit about:config.
IE No support NoOpera Full support 48Safari Full support 13WebView Android Full support 61Chrome Android Full support 61Firefox Android Full support 68
Full support 68
Full support 63
Disabled
Disabled From version 63: this feature is behind the dom.visualviewport.enabled preference (needs to be set to true). To change preferences in Firefox, visit about:config.
Opera Android Full support 45Safari iOS Full support 13Samsung Internet Android Full support 8.0
pageTop
Experimental
Chrome Full support 61Edge Full support 79Firefox Full support 63
Disabled
Full support 63
Disabled
Disabled From version 63: this feature is behind the dom.visualviewport.enabled preference (needs to be set to true). To change preferences in Firefox, visit about:config.
IE No support NoOpera Full support 48Safari Full support 13WebView Android Full support 61Chrome Android Full support 61Firefox Android Full support 68
Full support 68
Full support 63
Disabled
Disabled From version 63: this feature is behind the dom.visualviewport.enabled preference (needs to be set to true). To change preferences in Firefox, visit about:config.
Opera Android Full support 45Safari iOS Full support 13Samsung Internet Android Full support 8.0
resize event
Experimental
Chrome Full support 62
Full support 62
Partial support 61
Edge Full support 79Firefox Full support 66
Disabled
Full support 66
Disabled
Disabled From version 66: this feature is behind the dom.visualviewport.enabled preference (needs to be set to true). To change preferences in Firefox, visit about:config.
IE No support NoOpera Full support 49
Full support 49
Partial support 48
Safari Full support 13WebView Android Full support 62
Full support 62
Partial support 61
Chrome Android Full support 62
Full support 62
Partial support 61
Firefox Android Full support 68
Full support 68
Full support 66
Disabled
Disabled From version 66: this feature is behind the dom.visualviewport.enabled preference (needs to be set to true). To change preferences in Firefox, visit about:config.
Opera Android Full support 46
Full support 46
Partial support 45
Safari iOS Full support 13Samsung Internet Android Full support 8.0
Full support 8.0
Partial support 8.0
scale
Experimental
Chrome Full support 61Edge Full support 79Firefox Full support 63
Disabled
Full support 63
Disabled
Disabled From version 63: this feature is behind the dom.visualviewport.enabled preference (needs to be set to true). To change preferences in Firefox, visit about:config.
IE No support NoOpera Full support 48Safari Full support 13WebView Android Full support 61Chrome Android Full support 61Firefox Android Full support 68
Full support 68
Full support 63
Disabled
Disabled From version 63: this feature is behind the dom.visualviewport.enabled preference (needs to be set to true). To change preferences in Firefox, visit about:config.
Opera Android Full support 45Safari iOS Full support 13Samsung Internet Android Full support 8.0
scroll event
Experimental
Chrome Full support 62
Full support 62
Partial support 61
Edge Full support 79Firefox Full support 66
Disabled
Full support 66
Disabled
Disabled From version 66: this feature is behind the dom.visualviewport.enabled preference (needs to be set to true). To change preferences in Firefox, visit about:config.
IE No support NoOpera Full support 49
Full support 49
Partial support 48
Safari Full support 13WebView Android Full support 62
Full support 62
Partial support 61
Chrome Android Full support 62
Full support 62
Partial support 61
Firefox Android Full support 68
Full support 68
Full support 66
Disabled
Disabled From version 66: this feature is behind the dom.visualviewport.enabled preference (needs to be set to true). To change preferences in Firefox, visit about:config.
Opera Android Full support 46
Full support 46
Partial support 45
Safari iOS Full support 13Samsung Internet Android Full support 8.0
Full support 8.0
Partial support 8.0
width
Experimental
Chrome Full support 61Edge Full support 79Firefox Full support 63
Disabled
Full support 63
Disabled
Disabled From version 63: this feature is behind the dom.visualviewport.enabled preference (needs to be set to true). To change preferences in Firefox, visit about:config.
IE No support NoOpera Full support 48Safari Full support 13WebView Android Full support 61Chrome Android Full support 61Firefox Android Full support 68
Full support 68
Full support 63
Disabled
Disabled From version 63: this feature is behind the dom.visualviewport.enabled preference (needs to be set to true). To change preferences in Firefox, visit about:config.
Opera Android Full support 45Safari iOS Full support 13Samsung Internet Android Full support 8.0

Legend

Full support  
Full support
No support  
No support
Experimental. Expect behavior to change in the future.
Experimental. Expect behavior to change in the future.
User must explicitly enable this feature.
User must explicitly enable this feature.

参照

  • Web 视口说明 — 解释了什么是浏览器视口和视觉视口和布局视口的区别。