initial commit

1 files changed, 133 insertions, 0 deletions

diff --git a/files/zh-cn/web/api/visualviewport/index.html b/files/zh-cn/web/api/visualviewport/index.html
new file mode 100644
index 0000000000..e07f4aa91d
--- /dev/null
+++ b/files/zh-cn/web/api/visualviewport/index.html
@@ -0,0 +1,133 @@
+---
+title: VisualViewport
+slug: Web/API/VisualViewport
+tags:
+  - API
+  - Experimental
+  - Interface
+  - NeedsTranslation
+  - Reference
+  - TopicStub
+  - Visual Viewport API
+  - VisualViewport
+  - viewport
+translation_of: Web/API/VisualViewport
+---
+<p>{{SeeCompatTable}}{{APIRef("Visual Viewport")}}</p>
+
+<p> <a href="https://wiki.developer.mozilla.org/en-US/docs/Web/API/Visual_Viewport_API">Visual Viewport API</a> 提供了当前页面的视觉视口接口，即 <strong><code>VisualViewport</code></strong> 。对于每个页面容器来说（如 iframe），都存在有一个独立的 window 对象。每个页面容器的 window 对象都有一个独立的 <code>VisualViewport</code> 属性。</p>
+
+<p>你可以使用 {{domxref("Window.visualViewport")}} 获得对应 window 的视觉视口 API。</p>
+
+<div class="note">
+<p><strong>注意</strong>：与布局视口（layout viewport）不同的是：只有最上层的 window 才有视觉视口（visual viewport）这一概念。因此只有最上层 window 的 <code>VisualViewport</code> 属性才是有效的，其他层的视觉视口属性可看作是布局视口属性的别名。比如，对于一个 {{htmlelement("iframe")}} ，其对应的视觉视口属性 {{domxref("VisualViewport.width")}} 相当于对应的布局视口属性，如 {{domxref("Element.clientWidth", "document.documentElement.clientWidth")}}.</p>
+</div>
+
+<h2 id="属性">属性</h2>
+
+<p><em><code>VisualViewport</code></em> 从其父元素继承属性 <em>{{domxref("EventTarget")}}</em>。</p>
+
+<dl>
+ <dt>{{domxref("VisualViewport.offsetLeft")}} {{readonlyinline}}</dt>
+ <dd>返回视觉视口的左边框到布局视口的左边框的 CSS 像素距离。</dd>
+ <dt>{{domxref("VisualViewport.offsetTop")}} {{readonlyinline}}</dt>
+ <dd>返回视觉视口的上边框到布局视口的上边框的 CSS 像素距离。</dd>
+ <dt>{{domxref("VisualViewport.pageLeft")}} {{readonlyinline}}</dt>
+ <dd>返回相对于初始的 viewport 属性的 X 轴坐标所对应的 CSS 像素数。</dd>
+ <dt>{{domxref("VisualViewport.pageTop")}} {{readonlyinline}}</dt>
+ <dd>返回相对于初始的 viewport 属性的 Y 轴坐标所对应的 CSS 像素数。</dd>
+ <dt>{{domxref("VisualViewport.width")}} {{readonlyinline}}</dt>
+ <dd>返回视觉视口的宽度所对应的 CSS 像素数。</dd>
+ <dt>{{domxref("VisualViewport.height")}} {{readonlyinline}}</dt>
+ <dd>返回视觉视口的高度所对应的 CSS 像素数。</dd>
+ <dt>{{domxref("VisualViewport.scale")}} {{readonlyinline}}</dt>
+ <dd>返回当前视觉视口所应用的缩放比例。</dd>
+</dl>
+
+<h2 id="Events">Events</h2>
+
+<p>通过使用 <code><a href="https://wiki.developer.mozilla.org/en-US/docs/Web/API/EventTarget/addEventListener">addEventListener()</a></code> 或者将监听回调函数赋值给对应的 <code>on<em>eventname</em></code> 属性，可以为对应的视口事件添加监听。</p>
+
+<dl>
+ <dt><code><a href="https://wiki.developer.mozilla.org/en-US/docs/Web/API/VisualViewport/resize_event">resize</a></code></dt>
+ <dd>当视觉视口被改变时触发。</dd>
+ <dd>也可以为 {{domxref("VisualViewport.onresize")}} 属性赋值来添加监听。</dd>
+ <dt><code><a href="https://wiki.developer.mozilla.org/en-US/docs/Web/API/VisualViewport/scroll_event">scroll</a></code></dt>
+ <dd>当视觉视口滑动时触发。</dd>
+ <dd>也可以为 {{domxref("VisualViewport.onscroll")}} 属性赋值来添加监听。</dd>
+</dl>
+
+<h2 id="例子">例子</h2>
+
+<h3 class="highlight-spanned" id="缩放检测并隐藏元素"><span class="highlight-span">缩放检测并隐藏元素</span></h3>
+
+<p>这个例子取自 <a href="https://github.com/WICG/visual-viewport">Visual Viewport README</a>，展示了如何在用户缩放时隐藏某个盒子（或元素）。这对于增强一个页面在缩放时的用户体验有重要意义。同样，你也可以查看另一个 <a href="https://wicg.github.io/visual-viewport/examples/hide-on-zoom.html">例子</a> 。</p>
+
+<pre class="brush: js line-numbers language-js"><code class="language-js"><span class="keyword token">var</span> bottomBar <span class="operator token">=</span> document<span class="punctuation token">.</span><span class="function token">getElementById</span><span class="punctuation token">(</span><span class="string token">'bottombar'</span><span class="punctuation token">)</span><span class="punctuation token">;</span>
+<span class="keyword token">var</span> viewport <span class="operator token">=</span> window<span class="punctuation token">.</span>visualViewport<span class="punctuation token">;</span>
+
+<span class="keyword token">function</span> <span class="function token">resizeHandler</span><span class="punctuation token">(</span><span class="punctuation token">)</span> <span class="punctuation token">{</span>
+   <span class="keyword token">if</span> <span class="punctuation token">(</span>viewport<span class="punctuation token">.</span>scale <span class="operator token">&gt;</span> <span class="number token">1.3</span><span class="punctuation token">)</span>
+     bottomBar<span class="punctuation token">.</span>style<span class="punctuation token">.</span>display <span class="operator token">=</span> <span class="string token">"none"</span><span class="punctuation token">;</span>
+   <span class="keyword token">else</span>
+     bottomBar<span class="punctuation token">.</span>style<span class="punctuation token">.</span>display <span class="operator token">=</span> <span class="string token">"block"</span><span class="punctuation token">;</span>
+<span class="punctuation token">}</span>
+
+window<span class="punctuation token">.</span>visualViewport<span class="punctuation token">.</span><span class="function token">addEventListener</span><span class="punctuation token">(</span><span class="string token">'resize'</span><span class="punctuation token">,</span> resizeHandler<span class="punctuation token">)</span><span class="punctuation token">;</span></code></pre>
+
+<h3 class="highlight-spanned" id="模拟_position_属性：device-fixed"><span class="highlight-span">模拟 position 属性：device-fixed</span></h3>
+
+<p>这个例子同样取自 <a href="https://github.com/WICG/visual-viewport">Visual Viewport README</a> ，展示了如何使用视觉视口 API，从而模拟 <code>position: device-fixed</code> 的 CSS 属性。类似于 <code>position: fixed</code> ，这一属性可将被设置的元素固定在视觉视口特定位置。此外，你也可以查看另一个 <a href="https://wicg.github.io/visual-viewport/examples/fixed-to-viewport.html">例子</a> 。</p>
+
+<pre class="brush: js line-numbers language-js"><code class="language-js"><span class="keyword token">var</span> bottomBar <span class="operator token">=</span> document<span class="punctuation token">.</span><span class="function token">getElementById</span><span class="punctuation token">(</span><span class="string token">'bottombar'</span><span class="punctuation token">)</span><span class="punctuation token">;</span>
+<span class="keyword token">var</span> viewport <span class="operator token">=</span> window<span class="punctuation token">.</span>visualViewport<span class="punctuation token">;</span>
+<span class="keyword token">function</span> <span class="function token">viewportHandler</span><span class="punctuation token">(</span><span class="punctuation token">)</span> <span class="punctuation token">{</span>
+  <span class="keyword token">var</span> layoutViewport <span class="operator token">=</span> document<span class="punctuation token">.</span><span class="function token">getElementById</span><span class="punctuation token">(</span><span class="string token">'layoutViewport'</span><span class="punctuation token">)</span><span class="punctuation token">;</span>
+
+  <span class="comment token">// Since the bar is position: fixed we need to offset it by the visual</span>
+  <span class="comment token">// viewport's offset from the layout viewport origin.</span>
+  <span class="keyword token">var</span> offsetLeft <span class="operator token">=</span> viewport<span class="punctuation token">.</span>offsetLeft<span class="punctuation token">;</span>
+  <span class="keyword token">var</span> offsetTop <span class="operator token">=</span> viewport<span class="punctuation token">.</span>height
+              <span class="operator token">-</span> layoutViewport<span class="punctuation token">.</span><span class="function token">getBoundingClientRect</span><span class="punctuation token">(</span><span class="punctuation token">)</span><span class="punctuation token">.</span>height
+              <span class="operator token">+</span> viewport<span class="punctuation token">.</span>offsetTop<span class="punctuation token">;</span>
+
+  <span class="comment token">// You could also do this by setting style.left and style.top if you</span>
+  <span class="comment token">// use width: 100% instead.</span>
+  bottomBar<span class="punctuation token">.</span>style<span class="punctuation token">.</span>transform <span class="operator token">=</span> <span class="string token">'translate('</span> <span class="operator token">+</span>
+                              offsetLeft <span class="operator token">+</span> <span class="string token">'px,'</span> <span class="operator token">+</span>
+                              offsetTop <span class="operator token">+</span> <span class="string token">'px) '</span> <span class="operator token">+</span>
+                              <span class="string token">'scale('</span> <span class="operator token">+</span> <span class="number token">1</span><span class="operator token">/</span>viewport<span class="punctuation token">.</span>scale <span class="operator token">+</span> <span class="string token">')'</span>
+<span class="punctuation token">}</span>
+window<span class="punctuation token">.</span>visualViewport<span class="punctuation token">.</span><span class="function token">addEventListener</span><span class="punctuation token">(</span><span class="string token">'scroll'</span><span class="punctuation token">,</span> viewportHandler<span class="punctuation token">)</span><span class="punctuation token">;</span>
+window<span class="punctuation token">.</span>visualViewport<span class="punctuation token">.</span><span class="function token">addEventListener</span><span class="punctuation token">(</span><span class="string token">'resize'</span><span class="punctuation token">,</span> viewportHandler<span class="punctuation token">)</span><span class="punctuation token">;</span></code></pre>
+
+<div class="blockIndicator note">
+<p><strong>注意</strong>：应小心使用上述方案，使用这种方式模拟的 <code>position: device-fixed</code> 可能会导致其他元素在滚动页面时出现闪烁。</p>
+</div>
+
+<h2 id="规范">规范</h2>
+
+<table class="standard-table">
+ <tbody>
+  <tr>
+   <th scope="col">规范</th>
+   <th scope="col">状态</th>
+   <th scope="col">提交</th>
+  </tr>
+  <tr>
+   <td>{{SpecName('Visual Viewport','#the-visualviewport-interface','VisualViewport')}}</td>
+   <td>{{Spec2('Visual Viewport')}}</td>
+   <td>Initial definition.</td>
+  </tr>
+ </tbody>
+</table>
+
+<h2 id="浏览器兼容性">浏览器兼容性</h2>
+
+<p>{{Compat("api.VisualViewport")}}</p>
+
+<h2 id="参照">参照</h2>
+
+<ul>
+ <li><a href="https://github.com/bokand/bokand.github.io/blob/master/web_viewports_explainer.md">Web 视口说明</a> — 解释了什么是浏览器视口和视觉视口和布局视口的区别。</li>
+</ul>