> 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-pt/criar-para-mobile/desenvolver/safe-area.md).

# Área Segura no Mobile

Onde a UI da scene pode ficar com segurança no mobile — fora das margens de hardware do dispositivo e dos próprios controles do client.

Num telemóvel, duas coisas independentes consomem o espaço do ecrã que a tua UI pode usar com segurança:

* **As margens de hardware do dispositivo** — o notch ou corte da câmara, a barra de estado, o indicador de início e os cantos arredondados. A UI desenhada por baixo deles fica parcialmente oculta ou é difícil de tocar.
* **Os controlos próprios do cliente Decentraland** — joystick, chat, perfil, controlos da câmara, botões de ação. A UI da scene colocada por baixo deles entra em conflito visualmente e compete pelos mesmos toques.

Não tens de medir nenhum dos dois. O cliente reporta ambas as áreas em runtime e o SDK posiciona a tua UI dentro da que escolheste, com a [`screenInset`](/creator/content-creator-pt/scenes-sdk7/ui-2d/onscreen-ui.md#screen-inset-area) opção do renderer:

| O que queres                                                | O que passar                                   |
| ----------------------------------------------------------- | ---------------------------------------------- |
| Livre das margens de hardware                               | nada — `screenInset: 'device'` é o predefinido |
| Livre das margens de hardware **e** os controlos do cliente | `screenInset: 'interactable'`                  |
| O ecrã inteiro, as margens são da tua responsabilidade      | `screenInset: 'none'`                          |

```ts
// Recomendado para UI da scene que não deve entrar em conflito com os controlos móveis
ReactEcsRenderer.setUiRenderer(uiComponent, { screenInset: 'interactable' })
```

{% hint style="warning" %}
**Suporte do cliente**: `'interactable'` requer cliente móvel `1.12.1` ou mais recente. Em clientes mais antigos, a área é reportada como zero e a UI passa a cobrir o ecrã inteiro. Essa mesma versão normaliza a `'device'` área entre Android e iOS.

**Não é um no-op no desktop** — o cliente desktop reserva cerca de 25% do lado esquerdo do ecrã para a sua própria UI, por isso `'interactable'` também altera o teu layout no desktop. Faz branching com [`isMobile()`](/creator/content-creator-pt/criar-para-mobile/desenvolver/detect-platform.md) se só quiseres o inset nos telemóveis.
{% endhint %}

Veja [Área de screenInset](/creator/content-creator-pt/scenes-sdk7/ui-2d/onscreen-ui.md#screen-inset-area) para a referência completa: as três áreas lado a lado num dispositivo real, o comportamento por renderer e a forma como se relacionam com o [ecrã virtual](/creator/content-creator-pt/scenes-sdk7/ui-2d/onscreen-ui.md#default-virtual-size).

## Onde vivem os controlos do cliente

`'interactable'` dá-te a área **que cada explorer designa para UI da scene** — isto não é de propósito uma promessa de que todos os controlos do cliente ficam fora dela. No cliente móvel, é a área segura do dispositivo menos a coluna do lado esquerdo (chat, perfil, joystick, emotes); os botões de ação no canto inferior direito são desenhados por cima da área **por design**.

<figure><img src="https://2402076176-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FoPnXBby9S6MrsW83Y9qZ%2Fuploads%2Fgit-blob-c0c75a80bed756d6b2b1483a7cca0cadef26c77e%2Fscreeninset-interactable.png?alt=media" alt="Scene UI inset to the area the mobile client reports as free of its own HUD"><figcaption><p><code>screenInset: 'interactable'</code> no cliente móvel <code>1.12.1</code>. O retângulo magenta é a UI da scene, o contorno verde delimita a área interactable. A coluna do lado esquerdo é excluída; os botões de ação no canto inferior direito ficam sobre a área.</p></figcaption></figure>

Portanto, mesmo com `'interactable'`, trata estas zonas como cheias:

* **Canto inferior direito** — os botões de ação e o botão de interação são desenhados por cima. Tudo o que colocares aqui continua acessível, mas compete pelos toques.
* **Canto superior direito** — os controlos de perfil e da câmara ficam mesmo fora da área, por isso a UI encostada a esse canto parece fazer parte do HUD do cliente.

O que a área cobre é uma decisão de cada explorer e pode mudar entre versões. Lê-a em runtime, nunca a codifiques fixamente, e verifica-a nas plataformas que pretendes.

## Onde colocar a UI da scene

* **Centro do ecrã** — diálogos acionáveis, qualquer coisa que o jogador precise de ler e responder.
* **Topo-centro** — mensagens não acionáveis, estado e notificações.
* **Centro inferior, acima do botão de interação** — sugestões sensíveis ao contexto.
* **Não no canto inferior direito** — mesmo dentro da área interactable, isso pertence aos botões de ação.

## Envolve antes parte da tua UI

Se optaste por não usar com `screenInset: 'none'` e quiseres proteger apenas parte da tua UI, envolve-a no componente `ScreenInsetArea` ou no `InteractableArea` Cada um lê a sua área correspondente e aplica-a aos seus filhos. Importa-os de `@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(() => (
    <ScreenInsetArea>
      {/* Um filho com 100% × 100% ocupa exatamente a área segura do inset */}
      <UiEntity
        uiTransform={{ width: '100%', height: '100%' }}
        uiBackground={{ color: Color4.create(0, 0, 0, 0.5) }}
      />
    </ScreenInsetArea>
  ), { screenInset: 'none' })
}
```

Ambos os componentes posicionam-se de forma absoluta usando os valores reportados pelo cliente, por isso os `positionType` e `position` campos dos seus `uiTransform` ficam reservados — qualquer valor que definas para eles é ignorado. Todas as outras `uiTransform` propriedades (`padding`, `flexDirection`, `alignItems`, …) e componentes de UI (`uiBackground`, `onMouseDown`, …) funcionam normalmente. Reagem automaticamente quando a área muda, por exemplo ao rodar o dispositivo ou quando as barras do sistema aparecem ou desaparecem, e compensam o [fator de escala da UI](/creator/content-creator-pt/scenes-sdk7/ui-2d/onscreen-ui.md#screen-virtual-scale), por isso as margens ficam corretamente, independentemente do tamanho do teu ecrã virtual.

{% hint style="warning" %}
**📔 Não apliques o inset duas vezes:** o `screenInset: 'none'` no excerto acima é importante. Envolver a tua UI num componente enquanto o renderer também aplica o inset correspondente empurra a tua UI para dentro com o dobro da margem. Escolhe um ou outro.
{% endhint %}

{% hint style="info" %}
**📱 Apenas móvel:** os insets do dispositivo só têm valores reais no **cliente móvel**. No **cliente desktop** são `(0, 0, 0, 0)`nulos, `screenInset: 'device'` quanto a `ScreenInsetArea` por isso os componentes não têm efeito aí e a tua UI é renderizada exatamente como seria sem eles. A área interactable, ao contrário dos insets do dispositivo, *é* não é zero no desktop.
{% endhint %}

## Porque é importante

A UI da scene que se sobrepuser aos controlos do cliente vai:

* Ficar parcialmente oculta atrás do joystick, do botão de interação ou dos controlos da câmara.
* Competir por toques com esses controlos — os jogadores vão ativar acidentalmente um ou outro.
* Fazer com que a tua scene pareça avariada no móvel, o que prejudica o destaque e a retenção.

Verifica sempre num dispositivo real usando o [código QR de preview](/creator/content-creator-pt/criar-para-mobile/desenvolver/preview-on-mobile.md).

## Relacionados

* [Área de screenInset](/creator/content-creator-pt/scenes-sdk7/ui-2d/onscreen-ui.md#screen-inset-area) — a `screenInset` referência completa.
* [Boas práticas de UI para mobile](/creator/content-creator-pt/criar-para-mobile/desenvolver/ui-best-practices.md)
* [Deteta a plataforma a partir do código](/creator/content-creator-pt/criar-para-mobile/desenvolver/detect-platform.md) — usa `isMobile()` para trocar layouts.
* [UI no ecrã](/creator/content-creator-pt/scenes-sdk7/ui-2d/onscreen-ui.md)
* [Guia de UX & UI](/creator/content-creator-pt/scenes-sdk7/conceber-a-experiencia/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 by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.decentraland.org/creator/content-creator-pt/criar-para-mobile/desenvolver/safe-area.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

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.