> For the complete documentation index, see [llms.txt](https://docs.decentraland.org/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.decentraland.org/creator/content-creator-ko/build-for-mobile/develop/safe-area.md). # 모바일 안전 영역 씬 UI가 모바일에서 안전하게 배치될 수 있는 영역입니다. 기기의 하드웨어 여백과 클라이언트 자체 컨트롤을 피해 배치하세요. 휴대폰에서는 UI가 안전하게 사용할 수 있는 화면 공간을 갉아먹는 서로 무관한 두 가지가 있습니다: * **기기의 하드웨어 여백** — 노치나 카메라 컷아웃, 상태 표시줄, 홈 인디케이터, 둥근 모서리입니다. 그 아래에 그려진 UI는 일부가 가려지거나 탭하기 어렵습니다. * **Decentraland 클라이언트 자체의 컨트롤** — 조이스틱, 채팅, 프로필, 카메라 컨트롤, 액션 버튼입니다. 그 아래에 배치된 씬 UI는 시각적으로 충돌하고 같은 탭을 두고 경쟁하게 됩니다. 둘 중 어느 것도 직접 측정할 필요가 없습니다. 클라이언트가 런타임에 두 영역을 모두 보고하며 SDK는 당신이 선택한 영역 안에 UI를 배치합니다. 다음과 같은 [`screenInset`](/creator/content-creator-ko/sdk7/2d-ui/onscreen-ui.md#screen-inset-area) 렌더러 옵션: | 원하는 것 | 전달할 값 | | --------------------------- | ------------------------------------- | | 하드웨어 여백을 피함 | 없음 — `screenInset: 'device'` 가 기본값입니다 | | 하드웨어 여백을 피함 **및** 클라이언트 컨트롤 | `screenInset: 'interactable'` | | 화면 전체를 사용하며, 여백은 직접 처리합니다 | `screenInset: 'none'` | ```ts // 모바일 컨트롤과 충돌하면 안 되는 씬 UI에 권장 ReactEcsRenderer.setUiRenderer(uiComponent, { screenInset: 'interactable' }) ``` {% hint style="warning" %} **클라이언트 지원**: `'interactable'` 모바일 클라이언트가 필요합니다 `1.12.1` 이상이어야 합니다. 더 पुराने 클라이언트에서는 해당 영역이 0으로 보고되어 UI가 화면 전체를 덮도록 되돌아갑니다. 또한 같은 릴리스에서 다음이 정규화됩니다. `'device'` 영역이 Android와 iOS 간에. **데스크톱에서도 무시되는 것은 아닙니다** — 데스크톱 클라이언트는 화면 왼쪽 약 25%를 자체 UI용으로 예약하므로 `'interactable'` 데스크톱 레이아웃도 변경됩니다. 다음을 사용해 분기하세요: [`isMobile()`](/creator/content-creator-ko/build-for-mobile/develop/detect-platform.md) 휴대폰에서만 인셋을 적용하고 싶다면. {% endhint %} 참고 [화면 인셋 영역](/creator/content-creator-ko/sdk7/2d-ui/onscreen-ui.md#screen-inset-area) 전체 참고 자료: 실제 기기에서 세 영역을 나란히 보는 모습, 렌더러별 동작, 그리고 다음과의 관계를 [가상 화면](/creator/content-creator-ko/sdk7/2d-ui/onscreen-ui.md#default-virtual-size). ## 클라이언트 컨트롤이 있는 위치 `'interactable'` 영역을 제공합니다 **각 익스플로러가 씬 UI용으로 지정한** — 이는 모든 클라이언트 컨트롤이 그 밖에 있다는 보장을 의도적으로 의미하지 않습니다. 모바일 클라이언트에서는 왼쪽 열(채팅, 프로필, 조이스틱, 이모트)을 제외한 기기 세이프 영역이며, 오른쪽 아래의 액션 버튼은 그 영역 위에 그려집니다 **의도적으로**.
Scene UI inset to the area the mobile client reports as free of its own HUD

screenInset: 'interactable' 모바일 클라이언트에서 1.12.1. 자주색 사각형은 씬 UI이고, 초록색 윤곽선은 상호작용 가능 영역입니다. 왼쪽 열은 제외되며, 오른쪽 아래의 액션 버튼은 그 영역 위에 있습니다.

따라서 `'interactable'`, 이 부분은 혼잡하다고 생각하세요: * **오른쪽 아래** — 액션 버튼과 상호작용 버튼이 위에 그려집니다. 여기에 배치한 것은 여전히 도달 가능하지만, 탭을 두고 경쟁하게 됩니다. * **오른쪽 위** — 프로필과 카메라 컨트롤이 영역 바로 바깥에 위치하므로, 그 모서리에 붙인 UI는 클라이언트 HUD의 일부처럼 보입니다. 영역에 무엇이 포함되는지는 각 익스플로러의 판단이며 버전마다 달라질 수 있습니다. 런타임에 읽어 오고, 절대 하드코딩하지 말며, 대상 플랫폼에서 확인하세요. ## 씬 UI를 배치할 위치 * **화면 중앙** — 사용자가 읽고 응답해야 하는 대화 상자 등. * **상단 중앙** — 동작이 필요 없는 메시지, 상태, 알림. * **하단 중앙, 상호작용 버튼 위** — 상황에 맞는 힌트. * **오른쪽 아래 모서리는 아님** — 상호작용 가능 영역 안쪽이라도, 그곳은 액션 버튼의 자리입니다. ## 대신 UI의 일부를 감싸세요 다음으로 제외했다면 `screenInset: 'none'` 그리고 UI의 일부만 보호하고 싶다면, 다음으로 감싸세요: `ScreenInsetArea` 또는 `InteractableArea` 컴포넌트입니다. 각 컴포넌트는 해당 영역을 읽어 자식에게 적용합니다. 다음에서 가져오세요: `@dcl/sdk/react-ecs`: ```tsx import ReactEcs, { ReactEcsRenderer, UiEntity, ScreenInsetArea } from '@dcl/sdk/react-ecs' import { Color4 } from '@dcl/sdk/math' export function setupUi() { ReactEcsRenderer.setUiRenderer(() => ( {/* 100% × 100% 크기의 자식은 안전한 인셋 영역을 정확히 채웁니다 */} ), { screenInset: 'none' }) } ``` 두 컴포넌트는 클라이언트가 보고하는 값을 사용해 절대 위치를 지정하므로, `positionType` 및 `위치` 그들의 필드 `uiTransform` 는 예약되어 있으며 — 여기에 설정한 값은 무시됩니다. 그 외의 모든 `uiTransform` 속성(`padding`, `flexDirection`, `alignItems`, …) 및 UI 컴포넌트(`uiBackground`, `onMouseDown`, …)는 평소처럼 동작합니다. 회전하거나 시스템 바가 나타나거나 사라질 때처럼 영역이 바뀌면 자동으로 반응하며, 다음을 보정합니다: [UI 배율 계수](/creator/content-creator-ko/sdk7/2d-ui/onscreen-ui.md#screen-virtual-scale), 따라서 가상 화면 크기가 무엇이든 여백이 올바르게 적용됩니다. {% hint style="warning" %} **📔 인셋을 두 번 적용하지 마세요:** 다음 `screenInset: 'none'` 위 코드 조각의 이 부분이 중요합니다. 렌더러가 이미 일치하는 인셋을 적용하는데 UI를 컴포넌트로 감싸면, UI가 여백의 두 배만큼 안쪽으로 밀립니다. 둘 중 하나만 선택하세요. {% endhint %} {% hint style="info" %} **📱 모바일 전용:** 기기 인셋은 다음에서만 실제 값을 가집니다: **모바일 클라이언트**. 다음에서는 **데스크톱 클라이언트** 그 값은 `(0, 0, 0, 0)`, 따라서 `screenInset: 'device'` 및 `ScreenInsetArea` 컴포넌트는 그곳에서 아무런 영향을 주지 않으며, UI는 그것들이 없을 때와 정확히 동일하게 렌더링됩니다. 상호작용 가능 영역은 기기 인셋과 달리 *일 때* 데스크톱에서 0이 아닙니다. {% endhint %} ## 왜 중요한가 클라이언트 컨트롤과 겹치는 씬 UI는 다음과 같은 문제가 생깁니다: * 조이스틱, 상호작용 버튼, 또는 카메라 컨트롤 뒤에 일부가 가려집니다. * 그 컨트롤들과 탭을 두고 경쟁하게 됩니다 — 플레이어가 실수로 둘 중 하나를 눌러버릴 수 있습니다. * 모바일에서 씬이 망가진 것처럼 느껴지게 하여, 피처링과 유지율에 악영향을 줍니다. 항상 실제 기기에서 다음을 사용해 확인하세요: [미리보기 QR 코드](/creator/content-creator-ko/build-for-mobile/develop/preview-on-mobile.md). ## 관련 * [화면 인셋 영역](/creator/content-creator-ko/sdk7/2d-ui/onscreen-ui.md#screen-inset-area) — 전체 `screenInset` 참조 자료. * [모바일 UI 모범 사례](/creator/content-creator-ko/build-for-mobile/develop/ui-best-practices.md) * [코드에서 플랫폼 감지](/creator/content-creator-ko/build-for-mobile/develop/detect-platform.md) — 다음을 사용하세요: `isMobile()` 레이아웃을 전환합니다. * [화면 UI](/creator/content-creator-ko/sdk7/2d-ui/onscreen-ui.md) * [UX 및 UI 가이드](/creator/content-creator-ko/sdk7/designing-the-experience/ux-ui-guide.md) --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter: ``` GET https://docs.decentraland.org/creator/content-creator-ko/build-for-mobile/develop/safe-area.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.