> 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/ui-best-practices.md).

# Melhores práticas de UI

O que fazer e o que não fazer ao conceber UIs de cena que funcionem bem em mobile.

Ainda não existe uma fórmula comprovada para a UI móvel de Decentraland — a plataforma é nova e continuamos a iterar. As recomendações nesta página são as melhores práticas atuais, sintetizadas a partir do trabalho em cenas reais. Use-as como ponto de partida e teste num dispositivo real.

{% embed url="<https://www.youtube.com/watch?v=5OmTTzpPdDc>" %}

## FAÇA

* **Crie UI específicas para dispositivos móveis**, ou adapte a UI ao tamanho do ecrã e à plataforma. Use [`isMobile()`](https://docs.decentraland.org/creator/content-creator-pt/criar-para-mobile/desenvolver/detect-platform.md) para criar ramificações.
* **Mantenha a UI essencial dentro da** [**área segura**](https://docs.decentraland.org/creator/content-creator-pt/criar-para-mobile/desenvolver/safe-area.md)**.** As margens de hardware do dispositivo (entalhe, barra de estado, indicador do ecrã inicial) são excluídas por predefinição — basta não desativar esta opção com `screenInset: 'none'`. Os controlos do próprio cliente ocupam uma área separada e `screenInset: 'interactable'` resolve parte desse problema: posiciona a UI no retângulo que o Explorer designa para a UI da cena. Em dispositivos móveis, isso deixa livres os controlos do lado esquerdo; os botões de ação no canto inferior direito são desenhados sobre essa área por predefinição, por isso tenha em conta [esses cantos](https://docs.decentraland.org/creator/content-creator-pt/criar-para-mobile/desenvolver/safe-area.md#where-the-client-controls-live) . `'interactable'` requer o cliente móvel `1.12.1` ou uma versão mais recente — os clientes mais antigos não comunicam quaisquer margens e a UI cobre todo o ecrã.
* **Reduza as opções ao mínimo.** Mostre apenas aquilo de que o jogador precisa naquele momento e revele o resto progressivamente.
* **Coloque as caixas de diálogo interativas no centro do ecrã** — em qualquer lugar onde o jogador tenha de ler e responder.
* **Coloque as mensagens não interativas na parte superior central** — estados, notificações e informações contextuais.
* **Oculte os controlos táteis por trás de uma UI em ecrã inteiro.** Quando estiver aberto um quadro de pontuação, uma loja ou um painel de resultados, o jogador não precisa de saltar nem de premir E. Consulte [UI em ecrã inteiro sobre os botões de ação](#full-screen-ui-over-the-action-buttons).

## NÃO FAÇA

* **Não dimensione os elementos da UI apenas em píxeis, sem ter em conta o ecrã virtual.** Os valores em píxeis são escalados em relação à `virtualWidth` / `virtualHeight` resolução de referência descrita em [UI no ecrã](https://docs.decentraland.org/creator/content-creator-pt/scenes-sdk7/ui-2d/onscreen-ui.md#screen-virtual-scale) — `1600x720` por predefinição em dispositivos móveis, `1920x1080` em computadores e na Web. Saiba a que resolução de referência correspondem os seus valores em píxeis, especifique-a se não for a predefinida e combine-a com um dimensionamento adaptado à plataforma. Desative o ecrã virtual (passando um tamanho de `0`) apenas se quiser realmente usar píxeis brutos do Canvas.
* **Não coloque elementos fora da área segura.** Entrarão em conflito com os controlos do cliente.
* **Não ancore a UI no canto superior esquerdo nem na margem esquerda.** É aí que o cliente desenha o chat, o perfil e o joystick virtual, todos sobre a UI da sua cena. Ancore-a à direita ou ao centro, ou use `screenInset: 'interactable'`. Consulte [Nunca ancore a UI no canto superior esquerdo](https://docs.decentraland.org/creator/content-creator-pt/scenes-sdk7/conceber-a-experiencia/ux-ui-guide.md#never-anchor-your-ui-to-the-top-left).
* **Não coloque elementos interativos no canto inferior direito.** Os botões de ação são desenhados sobre essa região e os toques aí são encaminhados para os botões do cliente, não para a sua cena.
* **Não dependa de botões pequenos.** É difícil tocar em alvos pequenos num ecrã tátil.
* **Não associe ações de teclas a `IA_SECONDARY` ou `IA_ACTION_3`–`IA_ACTION_6`** (as teclas `F` e `1`/`2`/`3`/`4` de um teclado), a menos que a sua cena mostre esses botões. Por predefinição, ficam ocultos em dispositivos móveis (SDK 7.32.0+). Consulte [Input em dispositivos móveis](https://docs.decentraland.org/creator/content-creator-pt/criar-para-mobile/desenvolver/input-on-mobile.md).

## UI em ecrã inteiro sobre os botões de ação

`screenInset: 'interactable'` mantém a sua UI afastada dos controlos do lado esquerdo, mas os botões de ação no canto inferior direito são desenhados sobre essa área por predefinição. Um painel que ocupe toda a área continua a ficar tapado nessa zona, e os toques aí acionam os botões do cliente em vez da sua UI.

Para um **HUD de jogo** que tenha de continuar utilizável enquanto o jogador se move, mantenha-o afastado do canto inferior direito: ancore-o no canto superior direito ou ao centro, na parte superior.

Para uma **UI que interrompa o jogo**, como um placar, uma loja ou um ecrã de resultados, oculte os controlos táteis enquanto estiver aberta e volte a mostrá-los ao fechá-la:

```ts
import { TouchScreenControls } from '@dcl/sdk/ecs'

function openScoreboard() {
  TouchScreenControls.hideAll()
  TouchScreenControls.hideJoystick()
  // ... mostrar a sua UI
}

function closeScoreboard() {
  TouchScreenControls.showDefault()
  TouchScreenControls.showJoystick()
  // ... ocultar a sua UI
}
```

Use `showDefault()` em vez de `showAll()` para restaurar os botões: as cenas começam apenas com os botões de salto, ponteiro e ação principal visíveis, por isso `showAll()` voltaria a mostrar cinco botões que o jogador nunca teve. Tanto a predefinição de três botões como `showDefault()` requerem o SDK 7.32.0 ou posterior; em versões mais antigas do SDK, os oito botões são apresentados e `showAll()` é a única forma de os restaurar. `showDefault()` restaura apenas os botões do comando, por isso combine-o com `showJoystick()`. Ambos os métodos auxiliares não fazem nada em computadores, por isso não é necessário verificar a plataforma. Consulte [Controlos no ecrã](https://docs.decentraland.org/creator/content-creator-pt/scenes-sdk7/interatividade/touch-screen-controls.md) para ver o componente completo.

Se o Avatar também tiver de parar de se mover enquanto o painel estiver aberto, adicione um [modificador de entrada](https://docs.decentraland.org/creator/content-creator-pt/scenes-sdk7/interatividade/avatares/locomotion.md#freeze-the-player) adicional.

## Dimensionamento

A antiga regra prática — *desenhar no computador e, depois, aumentar 3× o tamanho da UI para dispositivos móveis* — surgiu antes de duas alterações no SDK e já não deve ser aplicada sem ponderação. Atualmente, grande parte desse aumento de 3× é aplicada automaticamente:

* **`devicePixelRatio` não tem qualquer efeito na disposição da UI.** Agora, a UI dimensionada em píxeis é apresentada `devicePixelRatio` vezes maior do que antes — normalmente **2–3× num telemóvel**, e também em portáteis com ecrã Retina. Não é possível desativar esta opção.
* **O ecrã virtual tem valores predefinidos consoante a plataforma**, `1600x720` em dispositivos móveis, em comparação com `1920x1080` em computadores e na Web, pelo que o mesmo valor em píxeis já ocupa cerca de 1,2× mais espaço no ecrã de um telemóvel.

Comece com os tamanhos para computador sem alterações e faça medições num dispositivo real — consulte [Pré-visualizar em dispositivos móveis](https://docs.decentraland.org/creator/content-creator-pt/criar-para-mobile/desenvolver/preview-on-mobile.md) — e aumente a escala apenas quando os alvos de toque ou o texto forem realmente demasiado pequenos. Use [`isMobile()`](https://docs.decentraland.org/creator/content-creator-pt/criar-para-mobile/desenvolver/detect-platform.md) para criar ramificações quando for realmente necessário que sejam diferentes.

## Relacionados

* [Funcionalidades em falta](https://docs.decentraland.org/creator/content-creator-pt/criar-para-mobile/cliente-movel/missing-features.md)
* [Área segura em dispositivos móveis](https://docs.decentraland.org/creator/content-creator-pt/criar-para-mobile/desenvolver/safe-area.md)
* [Detetar a plataforma a partir do código](https://docs.decentraland.org/creator/content-creator-pt/criar-para-mobile/desenvolver/detect-platform.md)
* [Interface no ecrã](https://docs.decentraland.org/creator/content-creator-pt/scenes-sdk7/ui-2d/onscreen-ui.md)
* [Guia de UX e UI](https://docs.decentraland.org/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/ui-best-practices.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.
