Interfejs Document Picture-in-Picture API pozwala otworzyć okno zawsze na górze, które może zostać wypełnione dowolną treścią HTML. Rozszerzają on istniejący interfejs API obrazu w obrazie dla <video>
, który zezwala na umieszczanie w oknie obrazu w obrazie tylko elementu HTML <video>
.
Okno obrazu w obrazie w interfejsie Document Picture-in-Picture API jest podobne do pustego okna z tym samym źródłem otwartego w window.open()
, z pewnymi różnicami:
- Okno obrazu w obrazie unosi się nad innymi oknami.
- Okno obrazu w obrazie nigdy nie przekracza poziomu otwarcia.
- Nie można poruszać się po oknie Obraz w obrazie.
- Witryna nie może ustawić położenia okna obrazu w obrazie.
Obecny stan,
Step | Stan |
---|---|
1. Utwórz wyjaśnienie | Zakończono |
2. Utwórz wstępną wersję roboczą specyfikacji | W toku |
3. Zbieranie opinii i ulepszanie projektu | W toku |
4. Testowanie origin | Zakończono |
5. Uruchom | Zakończono (na komputerze) |
Przykłady zastosowań
Spersonalizowany odtwarzacz wideo
Strona internetowa może umożliwiać korzystanie z funkcji obraz w obrazie za pomocą dotychczasowego interfejsu Picture-in-Picture API for <video>
, ale jego stosowanie jest bardzo ograniczone. Istniejące okno obrazu w obrazie akceptuje kilka opcji wejściowych i ma ograniczone możliwości określania ich stylu. Dzięki funkcji „Dokument w obrazie w obrazie” witryna może udostępniać własne elementy sterujące i dane wejściowe (np. napisy, playlisty, pasek czasu, ocenianie filmów jako lubiane i nielubiane) w celu zwiększenia wygody użytkowników korzystających z funkcji obraz w obrazie.
Wideokonferencje
Często użytkownicy opuszczają kartę przeglądarki podczas rozmowy wideo z różnych powodów (np. prezentując inną kartę podczas rozmowy lub wykonując inne zadania), a jednocześnie chcą zobaczyć rozmowę, dlatego jest to doskonały przypadek użycia funkcji Obraz w obrazie. Przypominamy, że obecne możliwości zapewniane przez stronę do prowadzenia rozmów wideo za pomocą interfejsu API Picture-in-Picture API w <video>
są ograniczone stylem i metodami wprowadzania. Dzięki funkcji „Dokument w obrazie w obrazie” witryna może łatwo łączyć wiele strumieni wideo w jedno okno bez konieczności korzystania z łamanych narzędzi typu canvas i udostępniać niestandardowe elementy sterujące, takie jak wysyłanie wiadomości, wyciszanie innych użytkowników czy podnoszenie ręki.
Produktywność
Badania pokazują, że użytkownicy potrzebują więcej sposobów na zachowanie produktywności w internecie. Funkcja Dokument w obrazie w obrazie zapewnia aplikacjom internetowym elastyczność, która pozwala im osiągnąć więcej. Niezależnie od tego, czy chodzi o edytowanie tekstu, robienie notatek, listy zadań, wiadomości i czat, czy narzędzia do projektowania i programowania, aplikacje internetowe mogą teraz zapewnić stały dostęp do swoich treści.
Interfejs
Właściwości
documentPictureInPicture.window
- Zwraca bieżące okno obrazu w obrazie (jeśli jest dostępne). W przeciwnym razie zwraca
null
.
Metody
documentPictureInPicture.requestWindow(options)
Zwraca obietnicę, która obowiązuje po otwarciu okna obrazu w obrazie. Obietnica jest odrzucana, jeśli została wywołana bez gestu użytkownika. Słownik
options
zawiera następujące opcjonalne elementy:width
- Określa początkową szerokość okna obrazu w obrazie.
height
- Określa początkową wysokość okna obrazu w obrazie.
disallowReturnToOpener
- Ukrywa przycisk „Powrót do karty” w oknie obrazu w obrazie, jeśli ma wartość Prawda. Domyślnie ma wartość Fałsz.
Wydarzenia
documentPictureInPicture.onenter
- Uruchamiany
documentPictureInPicture
, gdy otwarte jest okno obrazu w obrazie.
Przykłady
Poniższy kod HTML pozwala skonfigurować niestandardowy odtwarzacz wideo i element przycisku otwierający odtwarzacz w oknie obrazu w obrazie.
<div id="playerContainer">
<div id="player">
<video id="video"></video>
</div>
</div>
<button id="pipButton">Open Picture-in-Picture window</button>
Otwieranie okna obrazu w obrazie
Poniższy kod JavaScript wywołuje funkcję documentPictureInPicture.requestWindow()
, gdy użytkownik kliknie przycisk, aby otworzyć puste okno obrazu w obrazie. Zwrócona obietnica zostaje rozpoznana za pomocą obiektu JavaScript okna obrazu w obrazie. Odtwarzacz zostanie przeniesiony do tego okna za pomocą elementu 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);
});
Ustawianie rozmiaru okna obrazu w obrazie
Aby ustawić rozmiar okna obrazu w obrazie, ustaw opcje width
i height
opcji documentPictureInPicture.requestWindow()
na odpowiedni rozmiar okna funkcji Obraz w obrazie. Chrome może ograniczyć wartości opcji, jeśli są za duże lub za małe, aby zmieścić się w przyjaznym dla użytkownika oknie.
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);
});
Ukrywanie przycisku „Powrót do karty” w oknie obrazu w obrazie
Aby w oknie obrazu w obrazie ukryć przycisk, który umożliwia użytkownikowi powrót do karty otwierającej, ustaw opcję disallowReturnToOpener
na documentPictureInPicture.requestWindow()
na 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,
});
});
Kopiowanie arkuszy stylów do okna Obraz w obrazie
Aby skopiować wszystkie arkusze stylów CSS z okna źródłowego, użyj pętli styleSheets
umieszczonej w dokumencie lub umieszczonego w nim i dołącz je do okna obrazu w obrazie. Pamiętaj, że jest to kopia jednorazowa.
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);
});
Uchwyt po zamknięciu okna obrazu w obrazie
Sprawdzaj zdarzenie okna "pagehide"
, aby wiedzieć, kiedy okno obrazu w obrazie zostaje zamknięte (ponieważ witryna je zainicjowała lub użytkownik zamknął ręcznie). Dobrym miejscem do przywracania elementów z okna obrazu w obrazie jest moduł obsługi zdarzeń, jak pokazano poniżej.
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);
});
});
Zamknij okno obrazu w obrazie automatycznie, korzystając z metody close()
.
// Close the Picture-in-Picture window programmatically.
// The "pagehide" event will fire normally.
pipWindow.close();
Wysłuchaj, gdy witryna włączy tryb obrazu w obrazie
Słuchaj zdarzenia "enter"
w aplikacji documentPictureInPicture
, aby wiedzieć, kiedy otworzy się okno obrazu w obrazie. Zdarzenie zawiera obiekt window
umożliwiający dostęp do okna obrazu w obrazie.
documentPictureInPicture.addEventListener("enter", (event) => {
const pipWindow = event.window;
});
Uzyskiwanie dostępu do elementów w oknie obrazu w obrazie
Dostęp do elementów w oknie obrazu w obrazie możesz uzyskać, korzystając z obiektu zwróconego przez documentPictureInPicture.requestWindow()
lub documentPictureInPicture.window
, jak pokazano poniżej.
const pipWindow = documentPictureInPicture.window;
if (pipWindow) {
// Mute video playing in the Picture-in-Picture window.
const pipVideo = pipWindow.document.querySelector("#video");
pipVideo.muted = true;
}
Obsługa zdarzeń z okna obrazu w obrazie
Twórz przyciski i elementy sterujące oraz reaguj na zdarzenia wejściowe użytkownika, takie jak "click"
, w zwykły sposób w języku 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);
Zmiana rozmiaru okna obrazu w obrazie
Zmień rozmiar okna obrazu w obrazie za pomocą metod resizeBy()
i resizeTo()
Okno. Obie metody wymagają gestu użytkownika.
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);
Aktywuj okno otwierające
Aby z poziomu okna obrazu w obrazie zaznaczyć okno, które otwiera, użyj metody focus()
Okno. Ta metoda wymaga gestu użytkownika.
const returnToTabButton = pipWindow.document.createElement("button");
returnToTabButton.textContent = "Return to opener tab";
returnToTabButton.addEventListener("click", () => {
window.focus();
});
pipWindow.document.body.append(returnToTabButton);
Tryb wyświetlania obrazu w obrazie CSS
Korzystając z trybu wyświetlania picture-in-picture
CSS, możesz tworzyć konkretne reguły CSS, które będą stosowane tylko wtedy, gdy aplikacja internetowa jest widoczna tylko w trybie obrazu w obrazie (jest ona częścią tej aplikacji).
@media all and (display-mode: picture-in-picture) {
body {
margin: 0;
}
h1 {
font-size: 0.8em;
}
}
Wykrywanie funkcji
Aby sprawdzić, czy interfejs Document Picture-in-Picture API jest obsługiwany, użyj kodu:
if ('documentPictureInPicture' in window) {
// The Document Picture-in-Picture API is supported.
}
Przykłady
Odtwarzacz VideoJS
Możesz pobawić się prezentacją odtwarzacza VideoJS w interfejsie Document Picture-in-Picture API. Zapoznaj się z kodem źródłowym.
Pomodoro
Tomodoro, aplikacja internetowa pomodoro, również korzysta z interfejsu Document Picture-in-Picture API, gdy tylko jest dostępny (patrz żądanie pull w GitHub).
Prześlij opinię
Zgłoś problemy w GitHubie wraz z sugestiami i pytaniami.
Przydatne linki
- Wyjaśnienie publiczne
- Specyfikacja WICG
- Błąd śledzenia w Chromium
- Wpis na ChromeStatus.com
- Komponent Blink:
Blink>Media>PictureInPicture
- Przegląd tagów
- Zamiar eksperymentu
- Zamiar wysyłki
Podziękowania
Baner powitalny: Jakob Owens.