폴더블 포스처
폴더블·듀얼스크린 기기의 접힘 상태(posture)를 감지해 웹 레이아웃을 적응시킵니다.
한눈에 보기
포스처 Bridge는 폴더블 기기의 접힘 상태를 웹에 알려줍니다. 기기가 책처럼 반으로 접히거나(세로 힌지), 노트북처럼 눕혀지면(가로 힌지), 웹이 그 상태에 맞춰 레이아웃을 2분할하거나 컨트롤 위치를 바꿀 수 있습니다.
상태(posture) | 의미 | 권장 레이아웃 |
|---|---|---|
flat | 완전히 펼침(또는 일반 폰·태블릿) | 일반 단일 레이아웃 |
book | 세로 힌지(좌/우 분할, 책 모드) | 좌/우 2분할(목록 + 상세) |
tabletop | 가로 힌지(상/하 분할, 노트북 모드) | 상단 콘텐츠 / 하단 컨트롤 |
folded | 접힘(커버 화면) — iOS 전용 | 컴팩트 UI |
unknown | 판별 불가 | flat처럼 처리 |
무중단 — 켜서 쓸 때만 동작
이 기능은 기존 동작을 바꾸지 않습니다. 일반 폰·태블릿과 구버전 OS에서는 항상 flat이며, 웹이 포스처 API를 호출할 때만 반영됩니다. 폴더블 타겟이 생기기 전까지는 적용하지 않아도 됩니다.
브릿지 API
// 현재 posture 조회 (async — 콜백으로 응답). 콜백명 생략 시 기본 'onPosture'
window.unveilyBridge.getPosture('onPosture');
// getPosture 응답 핸들러 — 웹이 구현
window.onPosture = function (result) { applyPosture(result); };
// native가 posture를 바꿀 때 호출하는 push 핸들러 — 웹이 구현
window.onPostureChange = function (result) { applyPosture(result); };result 형태
{
"postureContractVersion": 1,
"posture": "flat", // flat | book | tabletop | folded | unknown
"isFoldable": true,
"hingeAngle": 128, // iOS: 숫자 / Android: 항상 null
"hingeOrientation": "vertical", // vertical | horizontal | null
"orientation": "portrait", // portrait | landscape
"segments": [ { "x": 0, "y": 0, "width": 540, "height": 960 } ] // iOS만 제공
}book= 세로 힌지(좌/우 분할) ·tabletop= 가로 힌지(상/하 분할)- 비폴더블 기기 →
{ "isFoldable": false, "posture": "flat" }, push 없음
⚠️ 반드시 지킬 플랫폼 호환 처리
iOS와 Android는 분할 영역을 다른 방식으로 제공합니다. 아래를 모두 견뎌야 한쪽 플랫폼에서 깨지지 않습니다.
분할 영역(segments)은 폴백 순서로
어느 한쪽 소스만 가정하지 마세요. 아래 순서로 처리합니다.
- CSS Viewport Segments API(
env(viewport-segment-*))가 있으면 사용 — Android(Chromium WebView) 지원 - 없으면 브릿지 result의
segments사용 — iOS(WKWebView는 CSS API 미지원, 대신 native segments 제공) - 둘 다 없으면
postureenum으로 분기
추가로:
hingeAngle이null일 수 있습니다 (Android는 항상 null). 숫자라고 가정하지 마세요.folded가 안 올 수 있습니다 (Android는 닫힘 상태를 감지하지 못함 — iOS 커버 화면 전용).folded수신에 핵심 로직을 걸지 마세요.- Android는
segments키가 아예 없을 수 있고, iOS는 CSS Viewport Segments API가 없습니다. 둘 다 견뎌야 합니다. - 모르는 필드·값은 무시하세요(전방 호환).
로드 시 1회 호출 (중요)
페이지가 로드되기 전에 생긴 posture 변화는 push로 받지 못합니다. 그래서 로드 시 getPosture()를 한 번 호출해 현재 상태를 받아야 합니다.
window.addEventListener('unveilyGlueReady', () => {
try { window.unveilyBridge.getPosture('onPosture'); } catch (e) {}
}, { once: true });unveilyGlueReady는 SDK가 브릿지 글루 주입을 끝내면 발생시키는 이벤트입니다. (상세: 내비게이션 — 타이밍)
push 트리거와 회전의 관계
onPostureChange push는 posture / isFoldable / hingeOrientation 중 하나라도 바뀌면 발생합니다.
- 안 접히는 기기(
isFoldable: false)는 회전해도 push가 없습니다. 회전 대응은 기존window.onOrientationChanged/ CSS media query /window.resize로 처리하세요. - 폴더블은 회전하면
hingeOrientation이 바뀌어 push가 옵니다(양 플랫폼 동일):- 반접힘 상태에서 회전 → posture도
book↔tabletop으로 바뀜 - 펼친 상태(
flat)에서 회전 → posture는flat그대로,hingeOrientation만vertical↔horizontal
- 반접힘 상태에서 회전 → posture도
push를 받으면 다시 읽기
push를 받으면 posture가 같더라도 hingeOrientation/orientation을 다시 읽어 레이아웃에 반영하세요.
적용 예시
function applyPosture(result) {
const { posture, hingeOrientation } = result;
const root = document.documentElement;
switch (posture) {
case 'book': // 세로 힌지 → 좌/우 2분할
root.dataset.layout = 'split-horizontal';
break;
case 'tabletop': // 가로 힌지 → 상/하 분할
root.dataset.layout = 'split-vertical';
break;
case 'folded': // iOS 커버 화면
root.dataset.layout = 'compact';
break;
default: // flat / unknown
root.dataset.layout = 'single';
}
}
// 로드 시 1회 + 변화 시 push
window.onPosture = applyPosture;
window.onPostureChange = applyPosture;
window.addEventListener('unveilyGlueReady', () => {
try { window.unveilyBridge.getPosture('onPosture'); } catch (e) {}
}, { once: true });데모
SDK 테스트 페이지(test_bridge)의 "Foldable Posture" 카드에서 실제 동작을 확인할 수 있습니다. iPhone Duo 시뮬레이터 / Pixel Fold 에뮬레이터에서 접힘·회전 시 값 변화를 볼 수 있습니다.