Screen.setOrientation

함수형 API setDeviceOrientation으로도 같은 기능을 쓸 수 있어요.

기능 설명

기기 화면 방향을 설정해요. 특정 화면에서 가로/세로 모드를 강제할 때 유용해요.

앱 전체에 영향을 미치므로, 특정 화면에서만 쓰려면 화면을 벗어날 때 이전 상태로 복구해 주세요.

토스앱 Android/iOS 5.215.0 이상에서 사용할 수 있어요. 미지원 버전에서 호출하면 UNSUPPORTED_APP_VERSION 에러가 발생해요.

타입

Screen.setOrientation(options: SetDeviceOrientationOptions): Promise<void>;

Params

type DeviceOrientation = "portrait" | "landscape";

interface SetDeviceOrientationOptions {
  type: DeviceOrientation;
}

Response

없음.

에러 코드

에러 코드는 catch한 에러의 error.code 값이에요.

코드	설명
UNSUPPORTED_APP_VERSION	실행 중인 토스앱 버전이 이 기능을 지원하지 않으면 호출 즉시 발생해요. Screen.setOrientation.isSupported()로 사전 확인하고, 발생 시 error.message(업데이트 안내 문구)를 사용자에게 보여주세요.

예시 코드

import { Screen } from "@apps-in-toss/web-framework";

// 동영상 화면에 진입할 때 가로 모드로 전환해요.
try {
  await Screen.setOrientation({ type: "landscape" });
} catch (error) {
  console.error(error);
}

// 화면을 벗어날 때 세로 모드로 복구해요.
window.addEventListener("pagehide", () => {
  Screen.setOrientation({ type: "portrait" }).catch(() => {
    // ignore
  });
});