useSafeArea

Lynx 앱에서 top/right/bottom/left safe area inset 값을 가져오는 훅입니다.

사용 가능 버전@seed-design/[email protected]

Import

import { useSafeArea } from "@seed-design/lynx-react";

useSafeArea는 @seed-design/lynx-react 패키지에 포함되어 있습니다. host 앱이 주입하는 lynx.__globalProps.safeAreaInsetTop / safeAreaInsetRight / safeAreaInsetBottom / safeAreaInsetLeft 값을 우선 읽고, 값이 없으면 Lynx CSS env(safe-area-inset-*)를 fallback으로 반환합니다.

Usage

기본 사용

import { useSafeArea } from "@seed-design/lynx-react";

function Screen() {
  const { safeAreaInsetTop, safeAreaInsetBottom } = useSafeArea();

  return (
    <view
      style={{
        paddingTop: `calc(16px + ${safeAreaInsetTop})`,
        paddingBottom: safeAreaInsetBottom,
      }}
    >
      <text>Content</text>
    </view>
  );
}

Box와 함께 사용

import { Box } from "@seed-design/lynx-react";

function Screen() {
  return (
    <Box pt="safeArea" pb="safeArea">
      <text>Content</text>
    </Box>
  );
}

Box의 pt, pr, pb, pl에 지정하는 "safeArea"도 내부적으로 useSafeArea와 같은 safe area resolve 로직을 사용합니다.

동작 방식

값 소스 우선순위는 다음과 같습니다.

lynx.__globalProps.safeAreaInset*
env(safe-area-inset-*)

host가 유효한 숫자 값을 주입하면 해당 값을 px 문자열로 변환합니다. 값이 없으면 CSS env() 문자열을 반환하고, 실제 px 해석은 Lynx layout 단계에 맡깁니다.

host가 0을 주입했을 때는 방향에 따라 다르게 동작합니다.

top/bottom: 0을 값이 없는 것으로 보고 env() 문자열을 반환합니다.
left/right: 0px를 그대로 반환합니다.

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 값입니다.

사용 시 주의사항

host global props가 없으면 CSS env(safe-area-inset-*) fallback을 반환합니다. 이 값은 JavaScript에서 px로 resolve되지 않고 style/layout 단계에서 해석됩니다.
BottomSheet.Content처럼 컴포넌트 구조상 safe area가 필요한 경우에는 컴포넌트 내부에서 bottom safe area를 처리합니다.
p, px, py 같은 shorthand에는 "safeArea"를 지정할 수 없습니다.
host 앱이 left/right 값을 주입하지 않는 구버전이면 좌우는 env() fallback을 사용합니다.
BG → FG 딥링크 진입처럼 native safe area 계산 타이밍이 흔들릴 수 있는 환경에서는 host 앱이 lynx.__globalProps.safeAreaInset* 값을 안정적으로 주입하는지 확인해야 합니다.

useSafeArea

목차