Fullscreen API

Giao diện

Fullscreen API không có giao diện riêng. Thay vào đó, nó mở rộng một số giao diện khác để thêm các phương thức, thuộc tính và trình xử lý sự kiện cần thiết cho chức năng toàn màn hình. Các mục đó được liệt kê trong các phần sau.

Phương thức thể hiện

Fullscreen API thêm các phương thức vào các giao diện Document và Element để cho phép bật và tắt chế độ toàn màn hình.

Phương thức thể hiện trên giao diện Document

Document.exitFullscreen()

Yêu cầu user agent chuyển từ chế độ toàn màn hình về chế độ cửa sổ. Phương thức trả về một Promise sẽ được giải quyết khi chế độ toàn màn hình đã tắt hoàn toàn.

Phương thức thể hiện trên giao diện Element

Element.requestFullscreen()

Yêu cầu user agent đưa phần tử được chỉ định, và theo đó là các phần tử con của nó, vào chế độ toàn màn hình, đồng thời loại bỏ mọi thành phần giao diện của trình duyệt cũng như mọi ứng dụng khác khỏi màn hình. Phương thức trả về một Promise sẽ được giải quyết khi chế độ toàn màn hình đã được kích hoạt.

Thuộc tính thể hiện

Document.fullscreenElement / ShadowRoot.fullscreenElement

Thuộc tính fullscreenElement cho biết Element nào hiện đang được hiển thị ở chế độ toàn màn hình trên DOM (hoặc shadow DOM). Nếu giá trị là null, tài liệu (hoặc shadow DOM) không ở chế độ toàn màn hình.

Document.fullscreenEnabled

Thuộc tính fullscreenEnabled cho biết liệu có thể vào chế độ toàn màn hình hay không. Giá trị là false nếu chế độ toàn màn hình không khả dụng vì bất kỳ lý do nào, chẳng hạn tính năng "fullscreen" không được phép hoặc không được hỗ trợ.

Thuộc tính lỗi thời

Document.fullscreen Deprecated

Một giá trị Boolean là true nếu tài liệu có phần tử hiện đang được hiển thị ở chế độ toàn màn hình; ngược lại trả về false.

Note: Hãy dùng thuộc tính fullscreenElement trên Document hoặc ShadowRoot; nếu giá trị của nó không phải null, thì đó là Element hiện đang được hiển thị ở chế độ toàn màn hình.

Sự kiện

fullscreenchange

Được gửi tới một Element khi nó chuyển vào hoặc ra khỏi chế độ toàn màn hình.

fullscreenerror

Được gửi tới một Element nếu xảy ra lỗi trong lúc cố gắng chuyển nó vào hoặc ra khỏi chế độ toàn màn hình.

Kiểm soát quyền truy cập

Khả năng dùng chế độ toàn màn hình có thể được kiểm soát bằng Permissions Policy. Tính năng chế độ toàn màn hình được nhận diện bằng chuỗi "fullscreen", với giá trị danh sách cho phép mặc định là "self", nghĩa là chế độ toàn màn hình được phép trong ngữ cảnh tài liệu cấp cao nhất, cũng như trong các ngữ cảnh duyệt web lồng nhau được tải từ cùng origin với tài liệu ở mức cao nhất.

Lưu ý khi dùng

Người dùng có thể thoát khỏi chế độ toàn màn hình bằng cách nhấn phím ESC (hoặc F11) thay vì chờ site hoặc ứng dụng thực hiện việc đó bằng chương trình. Hãy bảo đảm bạn cung cấp, ở đâu đó trong giao diện người dùng, các thành phần phù hợp để cho người dùng biết rằng tùy chọn này có sẵn.

Ví dụ

Cách dùng fullscreen đơn giản

Trong ví dụ này, một video được trình bày trong trang web. Nhấn phím Enter cho phép người dùng chuyển đổi giữa chế độ cửa sổ và chế độ toàn màn hình của video.

Xem ví dụ trực tiếp

Theo dõi phím Enter

Khi trang được tải, mã này được chạy để thiết lập trình nghe sự kiện theo dõi phím Enter.

const video = document.getElementById("video");

// Khi nhấn ENTER, gọi phương thức toggleFullScreen
document.addEventListener("keydown", (e) => {
  if (e.key === "Enter") {
    toggleFullScreen(video);
  }
});

Chuyển đổi chế độ toàn màn hình

Mã này được bộ xử lý sự kiện ở trên gọi khi người dùng nhấn phím Enter.

function toggleFullScreen(video) {
  if (!document.fullscreenElement) {
    // Nếu tài liệu không ở chế độ toàn màn hình
    // hãy đưa video vào chế độ toàn màn hình
    video.requestFullscreen();
  } else {
    // Ngược lại, thoát khỏi chế độ toàn màn hình
    document.exitFullscreen?.();
  }
}

Đoạn mã này bắt đầu bằng cách xem giá trị của thuộc tính fullscreenElement của document. Nếu giá trị là null, tài liệu hiện đang ở chế độ cửa sổ, vì vậy cần chuyển sang chế độ toàn màn hình; nếu không, đó là phần tử hiện đang ở chế độ toàn màn hình. Việc chuyển sang chế độ toàn màn hình được thực hiện bằng cách gọi Element.requestFullscreen() trên phần tử <video>.

Nếu chế độ toàn màn hình đã kích hoạt (fullscreenElement không phải null), chúng ta gọi exitFullscreen() trên document để tắt chế độ toàn màn hình.

Thông số kỹ thuật

Tương thích trình duyệt

api.Document.fullscreenElement

api.Document.fullscreenEnabled

api.Document.exitFullscreen

api.Element.requestFullscreen

Xem thêm

• Element.requestFullscreen()
• Document.exitFullscreen()
• Document.fullscreen
• Document.fullscreenElement
• :fullscreen, ::backdrop
• allowfullscreen