useFullscreen

useFullscreen (전체 화면)

useFullscreen 훅은 주어진 요소나 전체 페이지로 전체 화면 모드를 진입/종료하게 해줘요. Fullscreen API를 사용해요.

출처: 문서

본문

useFullscreen 훅은 Fullscreen API를 사용해 주어진 요소에 대한 전체 화면 진입/종료를 가능하게 해줘요. 기본적으로 ref를 제공하지 않으면 훅은 document.documentElement를 대상으로 해요.

import { useFullscreenDocument } from '@mantine/hooks';
import { Button } from '@mantine/core';

function Demo() {
  const { toggle, fullscreen } = useFullscreenDocument();

  return (
    <Button onClick={toggle}>
      {fullscreen ? 'Exit Fullscreen' : 'Enter Fullscreen'}
    </Button>
  );
}

사용자 정의 대상 요소 (Custom target element)

이 훅은 루트로 사용할 요소에 전달할 수 있는 선택적 ref 함수를 반환해요. 최종 사용자를 혼란스럽게 하거나 가두지 않도록 모범 사례를 따르는 것을 잊지 마세요.

import { useFullscreenElement } from '@mantine/hooks';
import { Button, Stack } from '@mantine/core';

function RefDemo() {
  const { ref, toggle, fullscreen } = useFullscreenElement();

  return (
    <Stack>
      <img
        ref={ref}
        src="https://images.unsplash.com/photo-1688920556232-321bd176d0b4?ixlib=rb-4.0.3&ixid=M3wxMjA3fDB8MHxwaG90by1wYWdlfHx8fGVufDB8fHx8fA%3D%3D&auto=format&fit=crop&w=400&q=80"
        alt="demo"
        style={{ width: 300, borderRadius: 8 }}
      />
      <Button onClick={toggle}>
        {fullscreen ? 'Exit Fullscreen' : 'View Image Fullscreen'}
      </Button>
    </Stack>
  );
}

모바일 Safari 제한 (Mobile Safari limitations)

모바일 Safari(iPhone 포함)는 Fullscreen API 지원이 제한적이에요. 대부분의 경우 전체 화면은 <video> 요소에서만 지원되며 임의의 요소(document.documentElement 포함)에서는 동작하지 않을 수 있어요.

useFullscreen은 가능한 경우 Safari 전용 폴백을 포함하지만, 브라우저/플랫폼 제한을 우회할 수는 없어요.

또한 전체 화면 진입은 일반적으로 직접적인 사용자 상호작용(예: 버튼 클릭)이 필요하다는 점에 유의하세요.

정의 (Definition)

interface UseFullscreenElementReturnValue {
  ref: React.RefCallback;
  toggle: () => Promise<void>;
  fullscreen: boolean;
}

interface UseFullscreenDocumentReturnValue {
  toggle: () => Promise<void>;
  fullscreen: boolean;
}

function useFullscreenElement(): UseFullscreenElementReturnValue
function useFullscreenDocument(): UseFullscreenDocumentReturnValue

Exported types

UseFullscreenElementReturnValue와 UseFullscreenDocumentReturnValue 타입은 @mantine/hooks 패키지에서 내보내져요.

import type { UseFullscreenElementReturnValue, UseFullscreenDocumentReturnValue } from '@mantine/hooks';

더 알아보기 (Learn more)