Hình trong hình cho mọi Phần tử, chứ không chỉ <video>

François Beaufort

API Hình trong hình của tài liệu cho phép mở một cửa sổ luôn ở trên cùng có thể được điền sẵn nội dung HTML tuỳ ý. API này mở rộng API Hình trong hình cho <video> hiện có, chỉ cho phép đặt phần tử <video> HTML vào cửa sổ Hình trong hình.

Cửa sổ Hình trong hình trong API Hình trong hình của tài liệu cũng tương tự như cửa sổ cùng nguồn gốc trống được mở qua window.open(), nhưng có một số điểm khác biệt:

• Cửa sổ Hình trong hình nổi trên các cửa sổ khác.
• Cửa sổ Hình trong hình không bao giờ tồn tại lâu hơn cửa sổ đang mở.
• Không thể điều hướng cửa sổ Hình trong hình.
• Trang web không thể đặt vị trí cửa sổ Hình trong hình.

Trạng thái hiện tại

Trường hợp sử dụng

Trình phát video tuỳ chỉnh

Một trang web có thể cung cấp trải nghiệm xem video Hình trong hình bằng API Hình trong hình cho <video> hiện có. Tuy nhiên, API này rất hạn chế. Cửa sổ Hình trong hình hiện tại chấp nhận một số ít dữ liệu đầu vào và có khả năng tạo kiểu hạn chế. Nhờ có toàn bộ Tài liệu ở chế độ Hình trong hình, trang web có thể cung cấp các chế độ điều khiển và thông tin đầu vào tuỳ chỉnh (ví dụ: phụ đề, danh sách phát, dấu chấm tua thời gian, thích và không thích video) để cải thiện trải nghiệm xem video Hình trong hình của người dùng.

Hội nghị truyền hình

Người dùng thường rời khỏi thẻ trình duyệt trong phiên hội nghị truyền hình vì nhiều lý do (ví dụ: trình bày một thẻ khác trong cuộc gọi hoặc làm nhiều việc cùng lúc) trong khi vẫn muốn xem cuộc gọi. Vì vậy, đây là một trường hợp sử dụng chính cho tính năng Hình trong hình. Xin nhắc lại rằng trải nghiệm hiện tại mà trang web hội nghị truyền hình có thể cung cấp thông qua API Hình trong hình cho <video> bị hạn chế về kiểu và phương thức nhập. Với một Tài liệu đầy đủ ở chế độ Hình trong hình, trang web có thể dễ dàng kết hợp nhiều luồng video thành một cửa sổ PiP mà không cần dựa vào các thủ thuật canvas và cung cấp các chế độ điều khiển tuỳ chỉnh như gửi tin nhắn, tắt tiếng người dùng khác hoặc giơ tay.

Năng suất

Nghiên cứu đã chỉ ra rằng người dùng cần có thêm nhiều cách để làm việc hiệu quả trên web. Chế độ tài liệu trong Hình trong hình giúp các ứng dụng web linh hoạt hơn trong việc hoàn thành nhiều việc hơn. Giờ đây, dù là chỉnh sửa văn bản, ghi chú, danh sách việc cần làm, nhắn tin và trò chuyện hay các công cụ thiết kế và phát triển, ứng dụng web đều có thể luôn truy cập được nội dung của mình.

Giao diện

Thuộc tính

documentPictureInPicture.window

Trả về cửa sổ Hình trong hình hiện tại (nếu có). Nếu không, hàm sẽ trả về null.

Phương thức

documentPictureInPicture.requestWindow(options)

Trả về một lời hứa sẽ giải quyết khi cửa sổ Hình trong hình được mở. Lời hứa sẽ từ chối nếu được gọi mà không có cử chỉ của người dùng. Từ điển options chứa các thành phần sau đây (không bắt buộc):

width

Đặt chiều rộng ban đầu của cửa sổ Hình trong hình.

height

Đặt chiều cao ban đầu của cửa sổ Hình trong hình.

disallowReturnToOpener

Ẩn nút "quay lại thẻ" trong cửa sổ Hình trong hình nếu giá trị là true. Giá trị này là false theo mặc định.

preferInitialWindowPlacement

Mở cửa sổ Hình trong hình ở vị trí và kích thước mặc định nếu đúng. Giá trị này là false theo mặc định.

Sự kiện

documentPictureInPicture.onenter

Được kích hoạt trên documentPictureInPicture khi mở cửa sổ Hình trong hình.

Ví dụ

Mã HTML sau đây thiết lập trình phát video tuỳ chỉnh và phần tử nút để mở trình phát video trong cửa sổ Hình trong hình.

<div id="playerContainer">
  <div id="player">
    <video id="video"></video>
  </div>
</div>
<button id="pipButton">Open Picture-in-Picture window</button>

Mở cửa sổ Hình trong hình

JavaScript sau đây gọi documentPictureInPicture.requestWindow() khi người dùng nhấp vào nút này để mở một cửa sổ Hình trong hình trống. Lời hứa được trả về sẽ phân giải bằng đối tượng JavaScript của cửa sổ Hình trong hình. Trình phát video được di chuyển sang cửa sổ đó bằng append().

pipButton.addEventListener('click', async () => {
  const player = document.querySelector("#player");

  // Open a Picture-in-Picture window.
  const pipWindow = await documentPictureInPicture.requestWindow();

  // Move the player to the Picture-in-Picture window.
  pipWindow.document.body.append(player);
});

Đặt kích thước của cửa sổ Hình trong hình

Để đặt kích thước của cửa sổ Hình trong hình, hãy đặt các tuỳ chọn width và height của documentPictureInPicture.requestWindow() thành kích thước cửa sổ Hình trong hình mong muốn. Chrome có thể kẹp các giá trị tuỳ chọn nếu các giá trị đó quá lớn hoặc quá nhỏ để vừa với kích thước cửa sổ thân thiện với người dùng.

pipButton.addEventListener("click", async () => {
  const player = document.querySelector("#player");

  // Open a Picture-in-Picture window whose size is
  // the same as the player's.
  const pipWindow = await documentPictureInPicture.requestWindow({
    width: player.clientWidth,
    height: player.clientHeight,
  });

  // Move the player to the Picture-in-Picture window.
  pipWindow.document.body.append(player);
});

Ẩn nút "quay lại thẻ" của cửa sổ Hình trong hình

Để ẩn nút trong cửa sổ Hình trong hình cho phép người dùng quay lại thẻ trình mở, hãy đặt tuỳ chọn disallowReturnToOpener của documentPictureInPicture.requestWindow() thành true.

pipButton.addEventListener("click", async () => {
  // Open a Picture-in-Picture window which hides the "back to tab" button.
  const pipWindow = await documentPictureInPicture.requestWindow({
    disallowReturnToOpener: true,
  });
});

Mở cửa sổ Hình trong hình ở vị trí và kích thước mặc định

Để không sử dụng lại vị trí hoặc kích thước của cửa sổ Hình trong hình trước đó, hãy đặt tuỳ chọn preferInitialWindowPlacement của documentPictureInPicture.requestWindow() thành true.

pipButton.addEventListener("click", async () => {
  // Open a Picture-in-Picture window in its default position / size.
  const pipWindow = await documentPictureInPicture.requestWindow({
    preferInitialWindowPlacement: true,
  });
});

Sao chép trang kiểu vào cửa sổ Hình trong hình

Để sao chép tất cả các trang kiểu CSS từ cửa sổ ban đầu, hãy lặp lại styleSheets được liên kết rõ ràng vào hoặc nhúng vào tài liệu và thêm các trang kiểu đó vào cửa sổ Hình trong hình. Xin lưu ý rằng đây là bản sao một lần.

pipButton.addEventListener("click", async () => {
  const player = document.querySelector("#player");

  // Open a Picture-in-Picture window.
  const pipWindow = await documentPictureInPicture.requestWindow();

  // Copy style sheets over from the initial document
  // so that the player looks the same.
  [...document.styleSheets].forEach((styleSheet) => {
    try {
      const cssRules = [...styleSheet.cssRules].map((rule) => rule.cssText).join('');
      const style = document.createElement('style');

      style.textContent = cssRules;
      pipWindow.document.head.appendChild(style);
    } catch (e) {
      const link = document.createElement('link');

      link.rel = 'stylesheet';
      link.type = styleSheet.type;
      link.media = styleSheet.media;
      link.href = styleSheet.href;
      pipWindow.document.head.appendChild(link);
    }
  });

  // Move the player to the Picture-in-Picture window.
  pipWindow.document.body.append(player);
});

Xử lý khi cửa sổ Hình trong hình đóng

Theo dõi sự kiện "pagehide" trong cửa sổ để biết thời điểm cửa sổ Hình trong hình đóng (do trang web đã khởi chạy hoặc người dùng đóng cửa sổ theo cách thủ công). Trình xử lý sự kiện là một nơi phù hợp để đưa các phần tử trở lại cửa sổ Hình trong hình như minh hoạ ở đây.

pipButton.addEventListener("click", async () => {
  const player = document.querySelector("#player");

  // Open a Picture-in-Picture window.
  const pipWindow = await documentPictureInPicture.requestWindow();

  // Move the player to the Picture-in-Picture window.
  pipWindow.document.body.append(player);

  // Move the player back when the Picture-in-Picture window closes.
  pipWindow.addEventListener("pagehide", (event) => {
    const playerContainer = document.querySelector("#playerContainer");
    const pipPlayer = event.target.querySelector("#player");
    playerContainer.append(pipPlayer);
  });
});

Đóng cửa sổ Hình trong hình theo phương thức lập trình bằng cách sử dụng phương thức close().

// Close the Picture-in-Picture window programmatically. 
// The "pagehide" event will fire normally.
pipWindow.close();

Nghe thời điểm trang web chuyển sang chế độ Hình trong hình

Theo dõi sự kiện "enter" trên documentPictureInPicture để biết thời điểm cửa sổ Hình trong hình được mở. Sự kiện này chứa một đối tượng window để truy cập vào cửa sổ Hình trong hình.

documentPictureInPicture.addEventListener("enter", (event) => {
  const pipWindow = event.window;
});

Truy cập vào các phần tử trong cửa sổ Hình trong hình

Truy cập các phần tử trong cửa sổ Hình trong hình từ đối tượng do documentPictureInPicture.requestWindow() trả về hoặc bằng documentPictureInPicture.window như minh hoạ dưới đây.

const pipWindow = documentPictureInPicture.window;
if (pipWindow) {
  // Mute video playing in the Picture-in-Picture window.
  const pipVideo = pipWindow.document.querySelector("#video");
  pipVideo.muted = true;
}

Xử lý các sự kiện từ cửa sổ Hình trong hình

Tạo các nút và thành phần điều khiển, đồng thời phản hồi các sự kiện đầu vào của người dùng như "click" như bình thường trong JavaScript.

// Add a "mute" button to the Picture-in-Picture window.
const pipMuteButton = pipWindow.document.createElement("button");
pipMuteButton.textContent = "Mute";
pipMuteButton.addEventListener("click", () => { 
  const pipVideo = pipWindow.document.querySelector("#video");
  pipVideo.muted = true;
});
pipWindow.document.body.append(pipMuteButton);

Đổi kích thước cửa sổ Hình trong hình

Sử dụng các phương thức Cửa sổ resizeBy() và resizeTo() để đổi kích thước cửa sổ Hình trong hình. Cả hai phương thức đều yêu cầu người dùng thực hiện một cử chỉ.

const resizeButton = pipWindow.document.createElement('button');
resizeButton.textContent = 'Resize';
resizeButton.addEventListener('click', () => {
  // Expand the Picture-in-Picture window's width by 20px and height by 30px.
  pipWindow.resizeBy(20, 30);
});
pipWindow.document.body.append(resizeButton);

Đặt tiêu điểm vào cửa sổ trình mở

Sử dụng phương thức Cửa sổ focus() để lấy tiêu điểm cửa sổ mở từ cửa sổ Hình trong hình. Phương thức này yêu cầu cử chỉ của người dùng.

const returnToTabButton = pipWindow.document.createElement("button");
returnToTabButton.textContent = "Return to opener tab";
returnToTabButton.addEventListener("click", () => {
  window.focus();
});
pipWindow.document.body.append(returnToTabButton);

Chế độ hiển thị hình trong hình của CSS

Sử dụng chế độ hiển thị picture-in-picture CSS để viết các quy tắc CSS cụ thể chỉ được áp dụng khi (một phần của) ứng dụng web hiển thị ở chế độ Hình trong hình.

@media all and (display-mode: picture-in-picture) {
  body {
    margin: 0;
  }
  h1 {
    font-size: 0.8em;
  }
}

Phát hiện tính năng

Để kiểm tra xem API Hình trong hình của tài liệu có được hỗ trợ hay không, hãy sử dụng:

if ('documentPictureInPicture' in window) {
  // The Document Picture-in-Picture API is supported.
}

Bản thu thử

Trình phát VideoJS

Bạn có thể chơi với minh hoạ trình phát VideoJS của API Chế độ hình trong hình cho tài liệu. Hãy nhớ xem mã nguồn.

Pomodoro

Tomodoro, một ứng dụng web pomodoro, cũng đang tận dụng API Chế độ hình trong hình của tài liệu khi có. Xem yêu cầu lấy dữ liệu trên GitHub của họ.

Chia sẻ ý kiến phản hồi của bạn

Gửi vấn đề trên GitHub kèm theo đề xuất và câu hỏi.

Đường liên kết hữu ích

• Thông báo giải thích công khai
• Quy cách của WICG
• Lỗi theo dõi Chromium
• Mục ChromeStatus.com
• Thành phần Blink: Blink>Media>PictureInPicture
• Bài đánh giá TAG
• Ý định thử nghiệm
• Ý định gửi hàng