useSafeArea
Lynx 앱에서 top/right/bottom/left Safe Area inset 값을 가져오는 훅입니다.
Import
useSafeArea는 @seed-design/lynx-react 패키지에 포함되어 있습니다. 앱이 SeedProvider의 safeAreaInsets로 넘긴 값을 px 문자열로 반환합니다.
컴포넌트의 배경이나 가로 스크롤 영역을 화면 끝까지 넓히려면 Safe Area 가이드의 extendSafeAreaX 사용법과 확장 전후 비교를 참고하세요.
Usage
기본 사용
Box와 함께 사용
Box의 pt, pr, pb, pl에 지정하는 "safeArea"도 내부적으로 useSafeArea와 같은 Safe Area resolve 로직을 사용합니다.
Overlay에서 다른 Safe Area 쓰기
같은 LynxView의 <overlay>처럼 영역마다 다른 inset이 필요하면 그 영역 안에 SafeAreaProvider를 중첩합니다. 그 아래의 useSafeArea()와 Box의 "safeArea"는 가장 가까운 Provider 값을 씁니다.
동작 방식
값 소스 우선순위는 다음과 같습니다.
- 가장 가까운
SafeAreaProvider또는SeedProvider의safeAreaInsets lynx.__globalProps.safeAreaInset*(다음 메이저 버전에서 제거 예정)env(safe-area-inset-*)
Provider 값은 보정하지 않고 그대로 px 문자열로 반환합니다. 0도 유효한 값이므로 "0px"가 됩니다.
Provider가 없으면 이전 버전과 같이 호스트가 넣은 safeAreaInset* global props를 읽습니다. 0 이상의 유한한 숫자는 px 문자열로 바꾸고, 값이 없으면 CSS env() 문자열을 반환해 실제 px 해석을 Lynx layout 단계에 맡깁니다. global props 값이 쓰이면 개발 빌드에서 키마다 한 번 경고합니다. 이 경로와 env() fallback은 다음 메이저 버전에서 제거될 예정입니다.
0과 값 생략의 차이
호스트가 네이티브 레이아웃에서 이미 Safe Area 여백을 확보했다면 Lynx에 추가 여백이 필요하지 않은 방향의 inset을 SeedProvider에 0으로 넘길 수 있습니다. 넘긴 0을 그대로 사용하므로 이미 확보한 여백이 한 번 더 적용되지 않습니다.
반대로 Lynx 화면이 시스템 영역까지 펼쳐져 있고 콘텐츠를 보호할 여백이 필요하다면 실제 inset을 넘겨야 합니다. 0은 기기의 inset을 자동으로 조회하라는 의미가 아닙니다. 이 규칙은 Box의 Safe Area padding·bleed처럼 같은 값을 사용하는 스타일에도 적용됩니다.
API
Return
| Property | Type | Description |
|---|---|---|
safeAreaInsetTop | string | top Safe Area inset 값입니다. |
safeAreaInsetRight | string | right Safe Area inset 값입니다. |
safeAreaInsetBottom | string | bottom Safe Area inset 값입니다. |
safeAreaInsetLeft | string | left Safe Area inset 값입니다. |
사용 시 주의사항
- Provider와 호스트 global props가 모두 없으면 CSS
env(safe-area-inset-*)fallback을 반환합니다. 이 값은 JavaScript에서 px로 resolve되지 않고 style/layout 단계에서 해석됩니다. Android에서는env()가 동작하지 않아0처럼 보일 수 있습니다. BottomSheet.Content처럼 컴포넌트 구조상 Safe Area가 필요한 경우에는 컴포넌트 내부에서 bottom Safe Area를 처리합니다.p,px,py같은 shorthand에는"safeArea"를 지정할 수 없습니다.- BG → FG 딥링크 진입처럼 native Safe Area 계산 타이밍이 흔들릴 수 있는 환경에서는 호스트가 안정적인 값을 주는지 확인하고, 그 값을
SeedProvider로 넘기세요.
Last updated on