那些被忽略但很好用的 Web API / FullScreen

一起来延伸视野，迎接更大的画面吧！

今天要介绍的 FullScreen API 会被忽略的原因可能是因会需要使用到它的情境比较少，但如果你撰写网站的经验有累积到一定程度的话，应该或多或少还是有需要它的可能性。虽然使用度没有那麽高，不过我们还是把它整理到我们的系列文章中一起分享给大家吧。

FullScreen

FullScreen API 主要是帮我们处理全萤幕显示的功能，大部分都会运用在影片的呈现，像是内嵌的 Youtube 影片都会内建这个功能让使用者切换，不过如果今天影片并没有上传 Youtube 的打算，或是你今天想要全萤幕显示的是其他元素时，你就可以运用这个 API。

# Document.fullscreenEnabled

这是一个唯读属性，用来确认目前的页面是否允许我们开启全萤幕显示，所以在你操作之前，可以先确认该属性是否为 true。

绝大多数的大型企业，如 Facebook、Google 都会有自己嵌入 iframe 的政策，它们通常就会禁止你使用全萤幕来显示。

const enabled = document.fullscreenEnabled;

# Document.fullscreen

这也是一个唯读属性，用来确认目前的页面是否正处於全萤幕模式。

console.log(document.fullscreen)

# Element.requestFullscreen

这个的话就是主要用来开启全萤幕的 API 了，这里的 Element 代表的是 DOM 元素，所以看到这里可以发现 FullScreen API 并没有提供一个全域物件，FullScreen API 反而是多个不同 methods 的总称。

要使用的话就是先选定要全萤幕的元素，然後呼叫：

const images = document.querySelectorAll("img");
images.forEach(img => {
  img.addEventListener("click", function(){
    this.requestFullscreen();
  });
});

这边要注意的是 requestFullscreen 不能直接在页面载入时呼叫，如果你这麽做会接到浏览器的错误警告，API can only be initiated by a user gesture，跟你说该 API 只能被使用者的手势触发，也就是说我们必须要透过事件的方式处理。

另外 requestFullscreen 其实会回传 Promise，当全萤幕显示完毕後就会被 resolve，所以你可以做到这样的效果：

const images = document.querySelectorAll("img");
images.forEach(img => {
  img.addEventListener("click", function(){
    this.requestFullscreen().then(()=>{
      this.src = "ugly.jpg";
    });
  });
});

# Document.exitFullscreen

有开启全萤幕，自然就会有关闭的部分，基本上使用者可以自己按 ESC 键离开全萤幕模式，不过你也可以透过 exitFullscreen 来触发这件事，例如让 Enter 键也可以关闭：

document.addEventListener("keydown", function(e) {
  if (e.keyCode == 13) document.exitFullscreen().then(()=>{
    alert(document.fullscreen)
  });
});

当然了，exitFullscreen 也是会回传 Promise 的，可以使用 then 来串接。不过要注意 exitFullscreen 这个 method 是在 Document 底下喔！

# Document.fullscreenElement

fullscreenElement 是一个唯读的属性，它会指向目前正在全萤幕模式的元素。

const images = document.querySelector("img");
images.addEventListener("click", function(){
  this.requestFullscreen().then(()=>{
    console.log(this === document.fullscreenElement); // true
  });
});

# 浏览器支援度

看完今天的介绍後，你可能觉得全萤幕是一个非常基本的功能，但其实 FullScreen API 在浏览器中的支援度还不是非常完整，所以当我们想要使用的时候可能要做一些额外的处理：

document.fullscreenEnabled = 
  document.fullscreenEnabled ||
  document.mozFullScreenEnabled ||
  document.documentElement.webkitRequestFullScreen;

function requestFullscreen(element) {
  if (element.requestFullscreen) {
    element.requestFullscreen();
  } else if (element.mozRequestFullScreen) {
    element.mozRequestFullScreen();
  } else if (element.webkitRequestFullScreen) {
    element.webkitRequestFullScreen(Element.ALLOW_KEYBOARD_INPUT);
  }
}

if (document.fullscreenEnabled) {
  requestFullscreen(document.documentElement);
}

目前是 IE11 和 Safari 还需要加上前缀词，且另外 iphone 是完全不支援的，也希望之後 FullScreen API 的支援度可以越来越完善，我们前端工程师才不用写这些冗长的 code。