Trang này được dịch bởi Cloud Translation API.

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

François Beaufort

Hỗ trợ trình duyệt

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 tương tự như một cửa sổ trống cùng nguồn mở qua window.open(), với 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.

Cửa sổ Hình trong hình đang phát video giới thiệu Sintel. — Cửa sổ Hình trong hình được tạo bằng API Hình trong hình của tài liệu (bản minh hoạ).

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

Bước	Trạng thái
1. Tạo video giải thích	Hoàn tất
2. Tạo bản nháp ban đầu của quy cách	Đang tiến hành
3. Thu thập ý kiến phản hồi và lặp lại thiết kế	Đang tiến hành
4. Bản dùng thử theo nguyên gốc	Hoàn tất
5. Chạy	Hoàn tất (Máy tính)

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 hiện có cho <video>, tuy nhiên, trải nghiệm 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ế. Với một Tài liệu đầy đủ ở chế độ Hình trong hình, trang web có thể cung cấp các chế độ điều khiển và phương thức nhập tuỳ chỉnh (ví dụ: bản chú thích, danh sách phát, thanh tua, lượt thích và không thích video) để cải thiện trải nghiệm xem video ở chế độ 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 cho 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. Đây là trường hợp sử dụng chính của chế độ 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 cho thấy người dùng cần có thêm nhiều cách để làm việc hiệu quả trên web. Chế độ Hình trong hình cho tài liệu 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, 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

Mã JavaScript sau đây gọi documentPictureInPicture.requestWindow() khi người dùng nhấp vào nút để 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" của cửa sổ để biết thời điểm cửa sổ Hình trong hình bị đóng (do trang web khởi tạo hoặc do người dùng đóng 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 mở cửa sổ Hình trong hình. 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ạ bên dưới.

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ý 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 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 Chế độ 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 màn hình minh hoạ trình phát VideoJS của API 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.