# Safe Area URL: /react/components/concepts/safe-area Source: https://github.com/daangn/seed-design/blob/dev/docs/content/react/components/concepts/safe-area.mdx 기기의 safe area inset을 화면에 반영하고, 배경과 스크롤 영역을 화면 끝까지 채우는 방법을 알아봅니다. 요소를 safe area 안에 둘지, 화면 끝까지 채울지 정하는 기준은 [Safe Area 패턴](/patterns/safe-area)을 참고하세요. 이 문서는 그 기준을 React로 구현하는 방법을 설명합니다. ## Viewport 설정 safe area inset을 반영하려면 `viewport-fit=cover`가 포함된 `viewport` 메타 태그를 사용하세요. ```html ``` 이 설정이 없으면 iOS WebKit은 `env(safe-area-inset-*)`를 0으로 계산합니다. 따라서 아래에서 설명하는 컴포넌트와 속성도 inset을 반영하지 않습니다. ## inset을 반영하는 컴포넌트 다음 컴포넌트는 별도로 설정하지 않아도 inset을 반영합니다. 자세한 동작은 각 컴포넌트 문서를 참고하세요. | 컴포넌트 | 반영하는 방향 | | --- | --- | | [App Screen](/react/stackflow/app-screen#safe-area) | 좌우, `AppBar`의 상단. 콘텐츠의 상단과 하단은 `layerOffsetTop`, `layerOffsetBottom` 속성으로 조정합니다. | | [Bottom Sheet](/react/components/bottom-sheet) | 하단 | | [Side Panel](/react/components/side-panel) | 상단, 하단, 패널이 붙은 쪽 | | [Snackbar](/react/components/snackbar) | 좌우, 하단 | ## 화면 끝까지 채우기 `AppScreenContent`처럼 inset만큼 안쪽으로 들어간 컨테이너 안에서 요소를 화면 끝까지 넓히는 방법은 두 가지입니다. - 화면 끝까지 넓어져야 하는 일부 컴포넌트는 `extendSafeAreaX` 속성을 제공합니다. 동작은 각 컴포넌트 문서를 참고하세요. - 그 밖의 요소는 `Box`의 속성에 `"safeArea"` 값을 지정합니다. 이 값을 받는 속성은 [Box의 Safe Area](/react/components/layout/box#safe-area)를 참고하세요. 아래 예제는 두 방법을 모두 보여 줍니다. 상단의 스위치로 컴포넌트의 `extendSafeAreaX`와 Image Frame의 `bleedX="safeArea"`를 켜고 끌 수 있습니다. 좌우 inset이 있는 기기에서 열어야 차이가 보입니다. ```tsx import type { StaticActivityComponentType } from "@stackflow/react/future"; import { Box, HStack, ImageFrame, ImageFrameFloater, ImageFrameIndicator, ImageFrameReactionButton, Text, VStack, } from "@seed-design/react"; import { useEffect, useRef, useState, type ReactNode } from "react"; import { ActionButton } from "seed-design/ui/action-button"; import { AppBar, AppBarBackButton, AppBarLeft, AppBarMain } from "seed-design/ui/app-bar"; import { AppScreen, AppScreenContent } from "seed-design/ui/app-screen"; import { AttachmentDropzone, AttachmentField, AttachmentInput, } from "seed-design/ui/attachment-field"; import { ChipTabsList, ChipTabsRoot, ChipTabsTrigger } from "seed-design/ui/chip-tabs"; import { ActionablePageBanner } from "seed-design/ui/page-banner"; import { Switch } from "seed-design/ui/switch"; import { TabsCarousel, TabsContent, TabsList, TabsRoot, TabsTrigger } from "seed-design/ui/tabs"; import img from "../assets/peng.jpeg"; declare module "@stackflow/config" { interface Register { ActivitySafeAreaBleed: {}; } } const CATEGORIES = [ "전체", "디지털기기", "생활가전", "가구/인테리어", "생활/주방", "유아동", "여성의류", "남성패션/잡화", "뷰티/미용", ]; const TABS = ["추천", "인기", "최신"]; const mockedFiles = Array.from({ length: 8 }, (_, i) => { const file = new File(["file content"], `file${i + 1}.txt`, { type: "text/plain" }); Object.defineProperty(file, "size", { value: 1 }); return file; }); const Section = ({ title, description, children, }: { title: string; description: string; children: ReactNode; }) => ( {title} {description} {children} ); function SafeAreaReadout() { const [insets, setInsets] = useState({ left: 0, right: 0 }); const leftRef = useRef(null); const rightRef = useRef(null); useEffect(() => { const measure = () => setInsets({ left: leftRef.current?.offsetWidth ?? 0, right: rightRef.current?.offsetWidth ?? 0, }); measure(); window.addEventListener("resize", measure); return () => window.removeEventListener("resize", measure); }, []); return ( <>
safe area: 왼쪽 {insets.left}px · 오른쪽 {insets.right}px ); } const ActivitySafeAreaBleed: StaticActivityComponentType<"ActivitySafeAreaBleed"> = () => { const [extendSafeAreaX, setExtendSafeAreaX] = useState(true); return (
{TABS.map((tab) => ( {tab} ))} {TABS.map((tab) => ( {tab} 패널 ))}
{CATEGORIES.map((category) => ( {category} ))}
{CATEGORIES.map((category) => ( {category} ))}
({ id: `${index}`, file, status: "pending", }))} extendSafeAreaX={extendSafeAreaX} rootProps={{ style: { "--seed-attachment-input-extend-x": "var(--seed-dimension-spacing-x-global-gutter)", } as React.CSSProperties, }} >
({ id: `${index}`, file, status: "pending", }))} extendSafeAreaX={extendSafeAreaX} rootProps={{ style: { "--seed-attachment-input-extend-x": "var(--seed-dimension-spacing-x-global-gutter)", } as React.CSSProperties, }} >
1 / 5 center
{/* Before iOS 26.4, WebKit leaves a block scroll container's end padding out of the scroll range when a block-level child overflows; a flex container keeps it, so the last item stops at the safe area edge. */} {Array.from({ length: 10 }, (_, index) => ( {index + 1} ))}
배경은 화면 끝까지, 글자는 safe area 안쪽에 있어요.
{Array.from({ length: 6 }, (_, index) => ( 아래 하단 바가 콘텐츠 위에 고정되는지 확인하기 위한 문단이에요. 하단 바는 배경을 화면 끝까지 채우고, 버튼은 safe area 안쪽에 둬요. ))} 확인
); }; export default ActivitySafeAreaBleed; ``` ### 문서에서 전후 비교하기 각 컴포넌트의 비교 예제에는 가상의 좌우 inset과 붉은 빗금을 표시합니다. **빗금은 콘텐츠를 피해야 하는 inset 영역**이며, 두 경계선 사이는 안전 영역입니다. 스위치를 켜면 배경과 스크롤 영역이 빗금 영역까지 넓어지고 콘텐츠에 필요한 여백은 유지됩니다. 이는 같은 버전에서 옵션을 끄고 켠 비교이며, 실제 기기의 inset 측정값이 아닙니다. - [Tabs](/react/components/tabs#extending-to-safe-area) - [Chip Tabs](/react/components/chip-tabs#extending-to-safe-area) - [Page Banner](/react/components/page-banner#extending-to-safe-area) - [Attachment Field](/react/components/attachment-field#extending-to-safe-area) - [Attachment Display Field](/react/components/attachment-display-field#extending-to-safe-area): `controlProps.extendSafeAreaX`를 사용합니다. - [Image Frame](/react/components/image-frame#extending-to-safe-area): `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 영역에 걸립니다.