path: root/files/zh-cn/web/api/fullscreen_api/index.html

---
title: 全屏 API
slug: Web/API/Fullscreen_API
tags:
  - API
  - DOM
  - 全屏 API
  - 图像
  - 屏幕
  - 引用
  - 指南
  - 游戏
translation_of: Web/API/Fullscreen_API
---
<p>{{DefaultAPISidebar("Fullscreen API")}}</p>

<p class="summary"> <strong><code>全屏 API</code></strong> 为使用用户的整个屏幕展现网络内容提供了一种简单的方式，并且在不需要时退出全屏模式。这种 API 让你可以简单地控制浏览器，使得一个元素与其子元素，如果存在的话，可以占据整个屏幕，并在此期间，从屏幕上隐藏所有的浏览器用户界面以及其他应用。</p>

<p class="summary">可以在<a href="/zh-CN/docs/Web/API/Fullscreen_API/Guide">全屏 API 指南</a>这篇文章了解更多细节。</p>

<div class="note">
<p><strong>注意：</strong>当前并不是所有的浏览器都支持该 API，大多数浏览器需要使用供应商前缀或者尚未实现该规范。下面的浏览器兼容性表 {{anch("Browser compatibility")}} 可以看到各个浏览器对此的支持（你也可以使用 <a href="https://github.com/rafrex/fscreen">Fscreen</a> 来提供跨浏览器 API 访问）。</p>
</div>

<h2 id="Specification" name="Specification">接口</h2>

<p>全屏 API 没有它自己的接口实现。相反，它提供了一些其他接口以供实现全屏所需的方法、属性、事件处理函数。接下来会列出所有细节。</p>

<h2 id="方法">方法</h2>

<p>全屏 API 在 {{DOMxRef("Document")}} 和 {{DOMxRef("Element")}} 接口中增加了一些方法，可用于允许打开关闭全屏模式。</p>

<h3 id="Document_中的方法">Document 中的方法</h3>

<dl>
 <dt>{{DOMxRef("Document.exitFullscreen()")}}</dt>
 <dd>用于请求从全屏模式切换到窗口模式，会返回一个 {{jsxref("Promise")}}，会在全屏模式完全关闭的时候被置为 resolved 状态。</dd>
</dl>

<h3 id="Element_中的方法">Element 中的方法</h3>

<dl>
 <dt>{{DOMxRef("Element.requestFullscreen()")}}</dt>
 <dd>请求浏览器（user agent）将特定元素（甚至延伸到它的后代元素）置为全屏模式，隐去屏幕上的浏览器所有 UI 元素，以及其它应用。返回一个 {{jsxref("Promise")}}，并会在全屏模式被激活的时候变成 resolved 状态。</dd>
</dl>

<h2 id="Specification" name="Specification">属性</h2>

<p><em>{{DOMxRef("Document")}} 提供了可以用于判断是否支持和启用全屏模式的属性，也能得知现在是否处在全屏模式、哪一个元素在使用屏幕等信息。</em></p>

<dl>
 <dt>{{DOMxRef("DocumentOrShadowRoot.fullscreenElement")}}</dt>
 <dd><code>fullscreenElement</code> 属性提供了当前在 DOM （或者 shadow DOM）里被展示为全屏模式的 {{DOMxRef("Element")}}，如果这个值为 <code>null</code>，文档不处于全屏模式。</dd>
 <dt></dt>
 <dt>{{DOMxRef("Document.fullscreenEnabled")}}</dt>
 <dd><code>fullscreenEnabled</code> 属性提供了启用全屏模式的可能性。当它的值是 <code>false</code> 的时候，表示全屏模式不可用（可能的原因有 <code>"fullscreen"</code> 特性不被允许，或全屏模式不被支持等 ）。</dd>
</dl>

<h3 id="事件处理程序">事件处理程序</h3>

<p>Fullscreen API 定义了两个事件，可用于检测全屏模式的打开和关闭，以及在全屏和窗口模式之间切换过程中发生的错误。<em>{{DOMxRef("Document")}} </em>和 <em> {{DOMxRef("Element")}} </em>接口提供了这些事件的事件处理函数。</p>

<div class="blockIndicator note">
<p><strong>注意：</strong>这些事件处理函数特性不可以当成 HTML 内容属性来使用。 换句话说，你无法在 HTML 内容中为 {{Event("fullscreenchange")}} 和 {{Event("fullscreenerror")}} 指定事件处理程序，你必须通过  JavaScript 代码添加它们。</p>
</div>

<h4 id="Document_上的事件处理程序">Document 上的事件处理程序</h4>

<dl>
 <dt>{{DOMxRef("Document.onfullscreenchange")}}</dt>
 <dd><br>
 {{Event("fullscreenchange")}} 事件的处理程序，当进入全屏或退出全屏时，事件将被发送到{{DOMxRef("Document")}}上。此处理程序仅在整个文档全屏模式更改时有效。</dd>
 <dt>{{DOMxRef("Document.onfullscreenerror")}}</dt>
 <dd><br>
 {{Event("fullscreenerror")}} 事件的处理程序，当进入全屏或退出全屏出错时，事件将被发送到 {{DOMxRef("Document")}} 上，仅对整个文档的全屏模式更改出错时候有效。</dd>
 <dt></dt>
</dl>

<h4 id="Element_上的事件处理程序">Element 上的事件处理程序</h4>

<dl>
 <dt>{{DOMxRef("Element.onfullscreenchange")}}</dt>
 <dd>当全屏事件发生时，该事件会被发送到该元素，表明该元素进入或退出全屏模式</dd>
 <dt>{{DOMxRef("Element.onfullscreenerror")}}</dt>
 <dd>{{Event("fullscreenerror")}} 事件的处理程序，当指定的 {{DOMxRef("Element")}} 改变全屏模式时候出现错误，该事件将被发送到指定的 {{DOMxRef("Element")}} 上。</dd>
 <dt>
 <h3 id="废弃属性">废弃属性</h3>
 </dt>
 <dt>{{DOMxRef("Document.fullscreen")}} {{Deprecated_Inline}}</dt>
 <dd>一个布尔值，文档内任意一个元素以全屏模式程序时该值为<code>true</code>，否则为 <code>false</code>。</dd>
 <dd>
 <div class="blockIndicator note">
 <p>Note：请改用 {{DOMxRef("ShadowRoot")}} 或 {{DOMxRef("Document")}} 上的 {{DOMxRef("Document.fullscreenElement", "fullscreenElement")}} 属性；如果它不是 null，则它是就是当前在全屏模式下显示的元素。</p>
 </div>
 </dd>
</dl>

<h2 id="Things_your_users_want_to_know" name="Things_your_users_want_to_know">事件</h2>

<p>全屏 API 定义了两个事件：1.可用来检测全屏模式何时打开和关闭。2.在全屏模式和窗口模式之间切换过程中何时发生错误。</p>

<dl>
 <dt>{{Event("fullscreenchange")}}</dt>
 <dd>当全屏或退出全屏时发送消息给（监听的）的 {{DOMxRef("Document")}} 或 {{DOMxRef("Element")}} 。</dd>
 <dt>{{Event("fullscreenerror")}}</dt>
 <dd>当全屏或退出全屏是发生了错误时，将错误消息发送给（监听的）的 {{DOMxRef("Document")}} 或 {{DOMxRef("Element")}} 。</dd>
</dl>

<h2 id="Things_your_users_want_to_know" name="Things_your_users_want_to_know">Dictionaries</h2>

<dl>
 <dt>{{DOMxRef("FullscreenOptions")}}</dt>
 <dd>在调用 {{DOMxRef("Element.requestFullscreen", "requestFullscreen()")}} 时可以设置选项。</dd>
</dl>

<h2 id="Things_your_users_want_to_know" name="Things_your_users_want_to_know">访问控制</h2>

<p>全屏模式可由功能策略（ <a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Feature_Policy">Feature Policy</a>）控制。全屏模式功能由字符串“full screen”标识，默认的允许列表值为“self”，这意味着在顶级文档上下文 以及 从与顶级文档相同的源加载的嵌套上下文中允许使用全屏模式。</p>

<p>请参阅使用功能策略（<a href="/zh-CN/docs/Web/HTTP/Feature_Policy/Using_Feature_Policy"> Feature Policy</a> ）以了解有关使用功能策略控制对API的访问的更多信息。</p>

<h2 id="Things_your_users_want_to_know" name="Things_your_users_want_to_know">使用说明</h2>

<p>用户通过按 <kbd>ESC</kbd>  键（或 <kbd>F11）</kbd>即可退出全屏模式，而不是等着站点或应用的代码来做这件事。确定你在你的用户界面里提供合适的界面元素来告知用户这个可选项。</p>

<div class="blockIndicator note">
<p><strong>注意：</strong>当处在全屏模式中，浏览其他页面，切换标签页，或者切换到其他应用（例如使用 <kbd>Alt</kbd>-<kbd>Tab</kbd>）也会导致退出全屏模式。</p>
</div>

<h2 id="Specification" name="Specification">示例</h2>

<p>在这个例子中，网页中显示了一个视频。按下 <kbd>Enter</kbd> 键让用户在视频的窗口显示和全屏显示之间切换。</p>

<p><a href="https://mdn.github.io/dom-examples/fullscreen-api/index.html">查看在线演示</a></p>

<h3 id="监听_Enter_键">监听 <kbd>Enter</kbd> 键</h3>

<p>当页面加载时，这段代码会运行，设置一个事件监听器以监听 <kbd>Enter</kbd> 键。</p>

<pre class="brush: js notranslate">document.addEventListener("keydown", function(e) {
  if (e.keyCode == 13) {
    toggleFullScreen();
  }
}, false);
</pre>

<h3 id="切换全屏模式">切换全屏模式</h3>

<p>当用户按下 <kbd>Enter</kbd> 键时，这段代码会被调用，像上面看到的那样。</p>

<pre class="notranslate"><code>function toggleFullScreen() {
  if (!document.fullscreenElement) {
      document.documentElement.requestFullscreen();
  } else {
    if (document.exitFullscreen) {
      document.exitFullscreen();
    }
  }
}</code>
</pre>

<p>这段代码首先检查 <a href="https://developer.mozilla.org/zh-CN/docs/Web/API/Document" title="Document接口表示任何在浏览器中已经加载好的网页，并作为一个入口去操作网页内容（也就是DOM tree）。DOM tree包括像 &lt;body> 、&lt;table>这样的还有其他的元素。它提供了全局操作document的功能，像获取网页的URL和在document里创建一个新的元素。"><code>document</code></a> 的 <code>fullscreenElement</code> 属性的值（亦要检查带有前缀 <code>moz</code>、<code>ms<font face="Arial, x-locale-body, sans-serif">、</font></code><code>webkit</code>）。如果其为 <code>null</code>，文档当前处于窗口模式中，所以我们需要切换到全屏模式。通过调用 <a href="https://developer.mozilla.org/zh-CN/docs/Web/API/Element/requestFullscreen" title="Element.requestFullscreen() 方法用于发出异步请求使元素进入全屏模式。"><code>element.requestFullscreen()</code></a>，可以切换到全屏模式。</p>

<p>如果全屏模式已经激活（<code>fullscreenElement</code> 不为 <code>null</code>），我们可以调用 <a href="https://developer.mozilla.org/zh-CN/docs/Web/API/Document/exitFullscreen" title="Document.exitFullscreen() 方法用于让当前文档退出全屏模式（原文表述不准确，详见备注）。调用这个方法会让文档回退到上一个调用Element.requestFullscreen()方法进入全屏模式之前的状态。"><code>document.exitFullscreen()</code></a>（或其前缀化的版本，这取决于你使用的浏览器）。</p>

<h2 id="规范">规范</h2>

<table class="standard-table">
 <thead>
  <tr>
   <th scope="col">规范</th>
   <th scope="col">状态</th>
   <th scope="col">备注</th>
  </tr>
 </thead>
 <tbody>
  <tr>
   <td>{{SpecName("Fullscreen")}}</td>
   <td>{{Spec2("Fullscreen")}}</td>
   <td>初始版本.</td>
  </tr>
 </tbody>
</table>

<h2 id="Browser_compatibility" name="Browser_compatibility">浏览器兼容性</h2>

<p>所有的浏览器都实现了这个API。然而一些带有前缀的实现在拼写上略微有些差别；例如，不同于 <code>requestFullscreen()</code>，存在一个 <code>MozRequestFullScreen()</code>。</p>

<p>{{Compat("api.Document.fullscreen")}}</p>

<p>{{Compat("api.Document.fullscreenEnabled")}}</p>

<div id="compat-desktop"></div>

<h2 id="另见">另见</h2>

<ul>
 <li><a href="/en-US/docs/Web/API/Fullscreen_API">Using fullscreen mode</a></li>
 <li>{{ domxref("Element.requestFullscreen()") }}</li>
 <li>{{ domxref("Document.exitFullscreen()") }}</li>
 <li>{{ domxref("Document.fullscreen") }}</li>
 <li>{{ domxref("Document.fullscreenElement") }}</li>
 <li>{{ cssxref(":fullscreen") }}, {{cssxref("::backdrop")}}</li>
 <li>{{ HTMLAttrXRef("allowfullscreen", "iframe") }}</li>
</ul>