如何在 JavaScript 中使用全屏

使用浏览器的全屏 API，可请求指定元素进入全屏模式，使用 document.exitFullscreen() 退出，并监听 fullscreenchange 以同步界面状态。请在按钮点击等用户操作中调用请求，并处理其 Promise，因为浏览器可能会拒绝请求。

了解全屏 API

全屏模式应用于某个元素，例如视频播放器、游戏、演示文稿或页面容器。浏览器通过 document.fullscreenElement 暴露当前处于全屏模式的元素；没有元素处于全屏模式时，该属性为 null。全屏 API 由浏览器控制，因此请求是否可用或获准，可能取决于用户操作、浏览上下文和设备。

如需了解方法和事件的详细信息，请参阅 MDN 的全屏 API 文档。

方法 1：使用 requestFullscreen() 进入全屏模式

选择要放大的元素，并在响应点击时调用 requestFullscreen()。全屏 API 需要安全上下文，通常为 HTTPS。如果页面不处于安全上下文或缺少该方法，此功能可能不可用；如果请求并非由用户手势触发，或浏览上下文或设备不允许，也可能被拒绝。下面的页面片段是静态浏览器示例；其 API 行为取决于浏览器，且这里没有将其作为运行时输出呈现。

<button id="enter-fullscreen">Enter full screen</button>
<button id="exit-fullscreen">Exit full screen</button>
<div id="player">Video or other content</div>
<p id="status" role="status"></p>
<script>
const enterButton = document.getElementById('enter-fullscreen');
const exitButton = document.getElementById('exit-fullscreen');
const player = document.getElementById('player');
const status = document.getElementById('status');

enterButton.addEventListener('click', async () => {
  if (typeof player.requestFullscreen !== 'function') {
    status.textContent = 'Full-screen mode is unavailable.';
    return;
  }

  try {
    await player.requestFullscreen();
  } catch (error) {
    status.textContent = 'The browser did not enter full-screen mode.';
  }
});

exitButton.addEventListener('click', async () => {
  if (!document.fullscreenElement) return;
  try {
    await document.exitFullscreen();
  } catch (error) {
    status.textContent = 'The browser did not exit full-screen mode.';
  }
});

document.addEventListener('fullscreenchange', () => {
  const active = document.fullscreenElement === player;
  status.textContent = active
    ? 'Player is full screen.'
    : document.fullscreenElement
      ? 'Another element is full screen.'
      : 'Full-screen mode has ended.';
  enterButton.disabled = active;
  exitButton.disabled = !document.fullscreenElement;
});
</script>

上面的浏览器示例使用真实的 DOM 元素。下面这个独立示例使用替代对象来展示 Promise 流程，以及请求完成后返回的消息。运行此示例：

const element = {
  requestFullscreen: () => Promise.resolve()
};

async function enterFullscreen(target) {
  await target.requestFullscreen();
  return 'Full-screen request completed';
}

enterFullscreen(element).then(console.log);

Full-screen request completed

在你的页面中，将请求放在点击处理程序内，以确保它由用户手势触发。不要依赖带厂商前缀的方法来保证兼容性；请检查标准方法是否存在，并在方法缺失或 Promise 被拒绝时，确保界面的其余部分仍可使用。如果 API 看起来不可用，也请确认页面是否通过安全上下文提供，通常为 HTTPS。

方法 2：使用 exitFullscreen() 退出全屏模式

调用 document.exitFullscreen() 退出全屏模式。该方法会返回一个 Promise，因此也要像进入全屏模式时一样处理拒绝情况。用户也可以通过浏览器或设备控件退出；界面应反映这一状态变化，不要假设只有页面自己的退出按钮才能结束全屏模式。

例如，在浏览器页面中，为退出按钮添加点击处理程序，并在 document.fullscreenElement 存在时调用 document.exitFullscreen()。捕获被拒绝的 Promise，并显示有用的状态消息。此静态说明并未实际执行具体的浏览器交互。

方法 3：处理全屏状态变化事件

在 document 上监听 fullscreenchange。全屏状态发生变化时会触发此事件，包括用户通过浏览器控件退出全屏时。每次都读取 document.fullscreenElement：值非 null 表示当前的全屏元素；值为 null 则表示全屏模式已结束。根据此状态更新按钮标签、状态文本或其他控件。浏览器以全屏模式显示元素时，可以使用 CSS 的 :fullscreen 伪类为其设置样式。

总结

在用户操作中对指定元素调用 requestFullscreen()，并处理其 Promise；如果提供退出控件，则使用 document.exitFullscreen()。监听 fullscreenchange 并读取 document.fullscreenElement，这样界面也能响应用户在页面之外发起的退出操作。浏览器和设备的行为可能有所不同，因此应保留可用的非全屏操作方式。

常见问题

1. 如何检查某个元素是否处于全屏模式？ 检查 document.fullscreenElement 是否为该元素。没有活动元素时，它的值为 null。

2. 任何元素都能进入全屏模式吗？ API 接受一个元素，但浏览器策略和所在的浏览上下文可能影响请求是否成功。请在用户操作中发起请求，并处理失败情况。

3. requestFullscreen() 为什么可能失败？ 该方法可能不可用，例如页面不处于安全上下文（通常为 HTTPS）时。请求也可能缺少用户手势，或被当前浏览上下文或设备拒绝。请检查方法是否可用，并处理返回的 Promise。

4. 如何设置全屏内容的样式？ 使用 CSS :fullscreen 伪类，为元素处于全屏模式时应用样式。