Safe Area
기기의 safe area inset을 화면에 반영하고, 배경과 스크롤 영역을 화면 끝까지 채우는 방법을 알아봅니다.
요소를 safe area 안에 둘지, 화면 끝까지 채울지 정하는 기준은 Safe Area 패턴을 참고하세요. 이 문서는 그 기준을 React로 구현하는 방법을 설명합니다.
Viewport 설정
safe area inset을 반영하려면 viewport-fit=cover가 포함된 viewport 메타 태그를 사용하세요.
이 설정이 없으면 iOS WebKit은 env(safe-area-inset-*)를 0으로 계산합니다. 따라서 아래에서 설명하는 컴포넌트와 속성도 inset을 반영하지 않습니다.
inset을 반영하는 컴포넌트
다음 컴포넌트는 별도로 설정하지 않아도 inset을 반영합니다. 자세한 동작은 각 컴포넌트 문서를 참고하세요.
| 컴포넌트 | 반영하는 방향 |
|---|---|
| App Screen | 좌우, AppBar의 상단. 콘텐츠의 상단과 하단은 layerOffsetTop, layerOffsetBottom 속성으로 조정합니다. |
| Bottom Sheet | 하단 |
| Side Panel | 상단, 하단, 패널이 붙은 쪽 |
| Snackbar | 좌우, 하단 |
화면 끝까지 채우기
AppScreenContent처럼 inset만큼 안쪽으로 들어간 컨테이너 안에서 요소를 화면 끝까지 넓히는 방법은 두 가지입니다.
- 화면 끝까지 넓어져야 하는 일부 컴포넌트는
extendSafeAreaX속성을 제공합니다. 동작은 각 컴포넌트 문서를 참고하세요. - 그 밖의 요소는
Box의 속성에"safeArea"값을 지정합니다. 이 값을 받는 속성은 Box의 Safe Area를 참고하세요.
아래 예제는 두 방법을 모두 보여 줍니다. 상단의 스위치로 컴포넌트의 extendSafeAreaX와 Image Frame의 bleedX="safeArea"를 켜고 끌 수 있습니다. 좌우 inset이 있는 기기에서 열어야 차이가 보입니다.
문서에서 전후 비교하기
각 컴포넌트의 비교 예제에는 가상의 좌우 inset과 붉은 빗금을 표시합니다. 빗금은 콘텐츠를 피해야 하는 inset 영역이며, 두 경계선 사이는 안전 영역입니다. 스위치를 켜면 배경과 스크롤 영역이 빗금 영역까지 넓어지고 콘텐츠에 필요한 여백은 유지됩니다. 이는 같은 버전에서 옵션을 끄고 켠 비교이며, 실제 기기의 inset 측정값이 아닙니다.
- Tabs
- Chip Tabs
- Page Banner
- Attachment Field
- Attachment Display Field:
controlProps.extendSafeAreaX를 사용합니다. - Image Frame:
extendSafeAreaX대신bleedX="safeArea"를 사용합니다.
Box로 넓히기
- 이미지처럼 요소 전체가 화면 끝까지 이어져야 하면
bleedX="safeArea"를 지정합니다. - 배경은 화면 끝까지 채우고 내용은 safe area 안에 두려면
bleedX와 함께pl,pr에도"safeArea"를 지정합니다. 화면 여백(spacingX.globalGutter)은 안쪽 요소에 지정합니다. - 화면 하단에 고정하는 바는
pb="safeArea"도 지정해서 하단 inset만큼 내용을 올립니다.
가로 스크롤 영역
가로 스크롤 영역도 bleedX와 pl, pr에 "safeArea"를 지정해 화면 끝까지 넓힙니다. 스크롤하기 전에는 첫 항목이 safe area 경계에서 화면 여백만큼 떨어져 시작하고, 끝까지 스크롤하면 마지막 항목 뒤에도 inset과 화면 여백이 남습니다.
가로 스크롤 컨테이너는 flex 컨테이너(display="flex")로 두세요. iOS 26.4 미만의 WebKit은 block 컨테이너 안에서 block 레벨 요소가 가로로 넘치면, 컨테이너의 끝쪽 padding을 스크롤 범위에 넣지 않습니다. 이때는 pr="safeArea"로 지정한 inset이 스크롤 범위에서 빠져서, 끝까지 스크롤해도 마지막 항목이 오른쪽 inset 영역에 걸립니다.
Last updated on