Document Picture-in-Picture API로 흥미로운 사용 사례를 활용하세요.

Jad Joubran

게시일: 2025년 3월 4일

문서 PIP 모드 API (문서 PIP API)를 사용하면 웹 애플리케이션이 임의의 HTML 콘텐츠를 표시할 수 있는 항상 맨 위에 있는 부동 창 (PIP 모드 창)을 열 수 있습니다.

이 API는 <video>용 PIP API를 기반으로 하며, 이를 통해 PIP 창에서 동영상을 계속 시청할 수 있습니다.

문서 PIP API는 임의의 HTML 콘텐츠를 표시할 수 있으므로 이를 사용하여 흥미로운 새로운 사용 사례를 구현할 수 있습니다.

브라우저 지원 및 점진적 개선

작성 시점에는 Document Picture-in-Picture API의 사용 가능 여부가 제한되어 있습니다.

하지만 점진적 개선 또는 단계적 저하와 함께 사용하는 것을 막지는 않습니다.

사용 사례를 계획할 때는 표준 기능이 아닌 점진적 개선으로 취급해야 합니다. 이 도움말에서는 그레이스풀 디그레이션의 예를 보여줍니다.

Document PiP API로 학습자의 사용자 환경 개선

LearnHTMLCSS.online은 시맨틱하고 접근성 있는 HTML과 CSS를 가르치는 대화형 학습 플랫폼입니다. 대화형 텍스트 편집기와 브라우저 미리보기 창을 제공합니다.

다음 스크린캐스트는 앱의 레이아웃을 보여줍니다. 화면은 두 개의 열로 나뉩니다. 첫 번째 열에는 코드 편집기가 포함되어 있습니다. 두 번째 열에는 탭 레이아웃이 포함되어 있습니다. 기본적으로 사용자는 챌린지의 안내를 볼 수 있으며 브라우저 탭을 클릭하여 실시간 미리보기를 볼 수 있습니다.

학생은 브라우저 미리보기 창을 최대화하고 싶을 때가 있습니다. 이 기회를 통해 문서 PIP 모드 API를 지원할 수 있습니다.

이를 구현하려면 먼저 브라우저 지원을 확인하세요.

const isPipSupported = "documentPictureInPicture" in window;

이제 이 변수를 사용하여 documentPictureInPicture 호출을 래핑하거나 Document PiP를 사용하는 함수에서 조기 반환할 수 있습니다. 다음 코드는 문서 PIP 지원 여부를 확인한 후 문서 PIP 창을 엽니다.

async function initDocumentPip() {
  if (!isPipSupported) {
    return false;
  }

  const pipWindow = await documentPictureInPicture.requestWindow({
    width: window.innerWidth,
    height: window.innerHeight,
  });
}

사용 사례에 따라 창의 너비와 높이를 지정할 수 있습니다. 특정 요소, 현재 문서를 일치시키거나 고정 값을 제공할 수 있습니다.

지금까지는 빈 문서가 있습니다. 이제 콘텐츠로 채워야 합니다.

// htmlCode is the HTML code of the challenge
pipWindow.document.documentElement.innerHTML = htmlCode;

CSS 코드에 문제가 있는 경우 CSS도 동기화해야 합니다.

작업이 끝났습니다. 이제 별도의 PIP 창에서 열리는 최대화 버튼이 있습니다.브라우저 미리보기 탭을 최대화하는 것 외에도 외부 모니터가 있는 경우 별도의 화면으로 이동하거나 열 레이아웃에서 기본 웹 앱과 브라우저 미리보기 탭을 재정렬할 수도 있습니다.

대체

이 API는 사용 가능 여부가 제한적입니다. 이 API가 지원되지 않는 브라우저와 기기에서는 대체 (단계적 저하) 동작을 제공해야 합니다.

최대화 버튼이 전체 브라우저 미리보기 탭을 가져오는 대신 현재 웹 앱의 남은 공간을 모두 차지하도록 할 수 있습니다.

https://learnhtmlcss.online/app.html?id=2096에서 다양한 브라우저로 이 동작을 시도해 보세요.

도움말의 작은 세부정보에 주의하세요. isPipSupported이 true이면 최대화/최소화 버튼의 도움말이 PIP 모드 시작과 PIP 모드 종료 사이에서 전환됩니다. 반면 isPipSupported가 false인 경우 대체 동작은 최대화 및 최소화로 설명됩니다.

보시다시피 문서 PIP API는 점진적 개선 또는 우아한 다운그레이드와 결합하면 웹 앱의 흥미로운 새로운 사용 사례를 열 수 있습니다.

브라우저 지원이 제한적이라고 해서 제한을 받지 마세요. 적절한 대체 사용 사례를 마련하는 것도 잊지 마세요.

문서 PiP 문서를 확인하여 이 API의 다양한 예와 사용 사례를 살펴보세요.