> 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/scenes-sdk7/ui-2d/ui-positioning.md). # Posicionamento da UI Defina a posição, escala, padding e outras propriedades de UI entities. Para todos os tipos de conteúdo de UI, use o `uiTransform` component para definir o tamanho, a posição e outras propriedades relacionadas com o alinhamento da entity. O `uiTransform` component funciona no espaço 2D do ecrã, muito semelhante ao `Transform` component funciona no espaço 3D da scene. ***arquivo ui.tsx:*** ```ts import { UiEntity, ReactEcs } from '@dcl/sdk/react-ecs' import { Color4 } from '@dcl/sdk/math' export const uiMenu = () => ( ) ``` ***arquivo index.ts:*** ```ts import { ReactEcsRenderer } from '@dcl/sdk/react-ecs' import { uiMenu } from './ui' export function main() { ReactEcsRenderer.setUiRenderer(uiMenu) } ``` {% hint style="warning" %} **📔 Observação**: Todos os trechos a seguir nesta página assumem que você tem um `.ts` semelhante ao acima, executando a `ReactEcsRenderer.setUiRenderer()` função. {% endhint %} ## Propriedades de posicionamento O alinhamento de UI entities baseia-se no modelo de alinhamento Flexbox. Este é um modelo muito poderoso para organizar dinamicamente entities aninhadas dentro de modals que podem variar em tamanho. {% hint style="info" %} **💡 Dica**: A implementação de UI da Decentraland baseia-se na de [Yoga](https://yogalayout.com/docs/). Leia [este artigo](https://www.joshwcomeau.com/css/interactive-guide-to-flexbox/) para uma cobertura muito acessível e aprofundada das propriedades disponíveis no Flexbox. {% endhint %} ### Tamanho da entity Use `width` e `height` para definir o tamanho da entity. São suportados os seguintes tipos de valores: * `do container, o container usará o valor`: O tamanho adapta-se para caber no conteúdo no interior. Isto é muito conveniente para texto que possa variar em comprimento. Escreva o valor como "auto". * **Percentagem**: Como uma percentagem das medidas do parent. Escreva o valor como uma string que termine em "%", por exemplo `10 %`. * **Pixels**: Escreva o valor como um número. * **Largura ou altura do ecrã**: Use vw (largura da vista) e vh (altura da vista) para indicar uma fração do tamanho total da janela em que Decentraland está a correr. Por exemplo `10vw` refere-se a 10% da largura da janela, `25vh` a 25% da altura da janela. Note que estas propriedades afetam o **default** tamanho desse item, o tamanho do item antes de serem efetuados quaisquer cálculos de flex grow e flex shrink. O tamanho final pode ser interpretado de forma diferente com base no tamanho da parent entity e nas propriedades Flexbox que estejam definidas. {% hint style="warning" %} **📔 Observação**: Em propriedades que suportam números e strings, para definir o valor em pixels, escreva um número. Para definir estes campos como uma percentagem das medidas do parent, escreva o valor como uma string que termine em "%", por exemplo `10 %`. Também pode definir um valor em pixels como string terminando a string em `px`, por exemplo `200px`. * Quando os valores são expressos como uma percentagem, estão sempre em relação ao container do parent. A entity de nível superior da sua UI também tem um parent: o renderer coloca-a dentro da área selecionada por [`screenInset`](/creator/content-creator-pt/scenes-sdk7/ui-2d/onscreen-ui.md#screen-inset-area), que por defeito é a área segura do dispositivo. Assim, uma entity de nível raiz `100%` é 100% dessa área — num telefone que é mais estreito do que o ecrã, no desktop os dois coincidem. Passe `screenInset: 'none'` se precisar de percentagens medidas em relação ao ecrã completo. * Se os valores forem expressos em pixels, não são afetados pela escala do parent, mas também não são **não** pixels crus do ecrã: são multiplicados pelo fator de escala de UI derivado do [ecrã virtual](/creator/content-creator-pt/scenes-sdk7/ui-2d/onscreen-ui.md#screen-virtual-scale), que está ativo por defeito. Um `width: 200` significa "200 px num ecrã do tamanho do ecrã virtual" e aumenta ou diminui proporcionalmente em qualquer outro. * Se os valores forem expressos em `vh` ou `vw`, são uma percentagem da janela completa, não afetados pela escala do parent, pelo ecrã virtual, nem por `screenInset`. Para o `do container, o container usará o valor` para que width/height funcionem, aplicam-se as seguintes regras: * O UiTransform que usa width/height como “auto” deve ter `alignSelf`: `“center”`/`“flex-start”`/`“flex-end”` OU `positionType: “absolute”` * Se o UiTransform de um child usar `positionType: “absolute”`, o parent não se adaptará ao seu tamanho/posição * Se o UiTransform de um child usar qualquer sobreposição de posição, o parent não se adaptará ao seu tamanho/posição {% endhint %} Estas outras propriedades também estão disponíveis para ajustar o tamanho de uma forma mais avançada: * `, que se ajusta para caber em todo o texto. Pode definir um` e `maxHeight`: *number* ou string (como height e width). O tamanho máximo que a entity pode ter. * `minWidth` e `minHeight`: *number* ou string (como height e width). O tamanho mínimo que a entity pode ter. Se o parent for demasiado pequeno para acomodar o tamanho mínimo das entities, estas transbordarão do parent. * `flexBasis`: Esta é uma forma independente do eixo de fornecer o tamanho padrão de um item ao longo do eixo principal. Definir o flex basis de um child é semelhante a definir a width desse child se o seu parent for um container com flex direction: row ou a definir a height de um child se o seu parent for um container com flex direction: column. ```ts import { UiEntity, ReactEcs } from '@dcl/sdk/react-ecs' import { Color4 } from '@dcl/sdk/math' export const uiMenu = () => ( ) ``` ### Organizar child entities Por defeito, as child entities são posicionadas em relação ao canto superior esquerdo do seu parent. Pode usar propriedades como `justifyContent` e `alignItems` para alterar este comportamento. {% hint style="info" %} **💡 Dica**: Quaisquer propriedades que se refiram a *content* referem-se a entities ao longo do eixo principal (determinado por `flexDirection`). Quaisquer propriedades que se refiram {% endhint %} * `flexDirection`: Flex direction controla a direção em que os children de um nó são dispostos. Isto também é referido como o eixo principal. O eixo principal é a direção em que os children são dispostos. O eixo cruzado é o eixo perpendicular ao eixo principal, ou o eixo em que as linhas de wrap são dispostas. Obtém o seu valor do `FlexDirectionType` type. As seguintes opções estão disponíveis: * `row` (PADRÃO) * `row-reverse` * `column` * `column-reverse` * `justifyContent`: Esta propriedade descreve como alinhar os children dentro do eixo principal do seu container. Por exemplo, pode usar esta propriedade para centrar um child horizontalmente dentro de um container com `flexDirection` definido como row ou verticalmente dentro de um container com `flexDirection` definido como column. O valor desta propriedade deve ser do `JustifyType` type. Os valores possíveis são: * `flex-start` (PADRÃO): Alinha os children de um container ao início do eixo principal do container. * `flex-end`: Alinha os children de um container ao fim do eixo principal do container. * `center`: Alinha os children de um container no centro do eixo principal do container. * `space-between`: Distribui os children uniformemente ao longo do eixo principal do container, distribuindo o espaço restante entre os children. * `space-around`: Distribui os children uniformemente ao longo do eixo principal do container, distribuindo o espaço restante à volta dos children. Em comparação com space-between, usar space-around fará com que o espaço seja distribuído no início do primeiro child e no fim do último child. * `space-evenly`: Distribui os children uniformemente ao longo do eixo principal do container, distribuindo o espaço restante para que os intervalos entre os children e entre os children e as margens do container sejam todos iguais. * `alignItems`: Descreve como alinhar os children ao longo do eixo cruzado do seu container. Align items é muito semelhante a justifyContent, mas em vez de se aplicar ao eixo principal, align items aplica-se ao eixo cruzado. Esta propriedade requer um valor do `AlignType` type. As seguintes opções estão disponíveis: * `stretch`: (PADRÃO) Estica os children de um container para corresponder à altura do eixo cruzado do container. * `flex-start`: Alinha os children de um container ao início do eixo cruzado do container. * `flex-end`: Alinha os children de um container ao fim do eixo cruzado do container. * `center`: Alinha os children de um container no centro do eixo cruzado do container. * `baseline`: Alinha os children de um container ao longo de uma baseline comum. Children individuais podem ser definidos como a baseline de referência para os seus parents. * `alignSelf`: Align self tem as mesmas opções e o mesmo efeito que `alignItems` mas, em vez de afetar os children dentro de um container, pode aplicar esta propriedade a um único child para alterar o seu alinhamento dentro do seu parent. align self substitui qualquer opção definida pelo parent com align items. Obtém o seu valor de `AlignType`, veja `alignItems` acima para detalhes sobre estas opções. * `alignContent`: Align content define a distribuição das linhas ao longo do eixo cruzado. Só tem efeito quando os itens são envolvidos em múltiplas linhas usando `flexWrap`. Obtém o seu valor do `AlignType` type. As seguintes opções estão disponíveis: * `flex-start`: (PADRÃO) Alinha as linhas envolvidas ao início do eixo cruzado do container. * `flex-end`: Alinha as linhas envolvidas ao fim do eixo cruzado do container. * `stretch`: Estica as linhas envolvidas para corresponder à altura do eixo cruzado do container. * `center`: Alinha as linhas envolvidas no centro do eixo cruzado do container. * `space-between`: Distribui as linhas envolvidas uniformemente ao longo do eixo principal do container, distribuindo o espaço restante entre as linhas. * `space-around`: Distribui as linhas envolvidas uniformemente ao longo do eixo principal do container, distribuindo o espaço restante à volta das linhas. Em comparação com space-between, usar space-around fará com que o espaço seja distribuído no início das primeiras linhas e no fim da última linha. * `flexGrow`: Isto descreve como qualquer espaço dentro de um container deve ser distribuído pelos seus children ao longo do eixo principal. Depois de dispor os seus children, um container distribuirá qualquer espaço restante de acordo com os valores de flex grow especificados pelos seus children. Flex grow aceita qualquer valor de ponto flutuante >= 0, sendo 0 o valor por defeito. Um container distribuirá qualquer espaço restante pelos seus children ponderado pelo valor de flex grow do child. * `flexShrink`: Descreve como reduzir os children ao longo do eixo principal no caso de o tamanho total dos children ultrapassar o tamanho do container no eixo principal. flex shrink é muito semelhante a flex grow e pode ser pensado da mesma forma se qualquer tamanho em excesso for considerado espaço restante negativo. Estas duas propriedades também funcionam bem em conjunto, permitindo que os children cresçam e encolham conforme necessário. Flex shrink aceita qualquer valor de ponto flutuante >= 0, sendo 1 o valor por defeito. Um container reduzirá os seus children ponderado pelo valor de flex shrink do child. * `overflow`: Determina o que acontece se o tamanho dos children de uma entity ultrapassar o seu parent. Usa valores do `OverflowType` . * `hidden`: As entities em excesso tornam-se invisíveis. * `visible`: As entities em excesso saem das margens do parent. * `scroll`: A área torna-se rolável, permitindo que o jogador percorra o conteúdo em excesso. Veja [Containers roláveis](#scrollable-containers) para mais detalhes. * `flexWrap`: A propriedade flex wrap é definida nos containers e controla o que acontece quando os children ultrapassam o tamanho do container ao longo do eixo principal. Por defeito, os children são envolvidos em múltiplas linhas ao longo do eixo principal, se necessário. Se o wrapping for desativado com `nowrap`, os children são forçados para uma única linha (o que pode reduzir entities). wrap-reverse comporta-se da mesma forma que wrap, mas a ordem das linhas é invertida. Esta propriedade obtém o seu valor do `FlexWrapType` . * `wrap` * `nowrap` * `wrap-reverse` ### Margens e padding * `margin`: Esta propriedade afeta o espaçamento à volta do exterior de um node. Um node com margin irá afastar-se dos limites do seu parent, mas também afastar a localização de quaisquer siblings. A margin de um node contribui para o tamanho total do seu parent se o parent tiver tamanho automático. Define o espaço entre a entity e as margens do seu parent. O valor esperado é um objeto que contém as propriedades `top`, `left`, `bottom`, e `right`. * `padding`: Esta propriedade afeta o tamanho do node ao qual é aplicada. O padding em Yoga funciona como se box-sizing: border-box; estivesse definido. Ou seja, o padding não será adicionado ao tamanho total de uma entity se esta tiver um tamanho explícito definido. Para nodes com tamanho automático, o padding aumentará o tamanho do node, bem como o afastamento da localização de quaisquer children. O valor esperado é um objeto que contém as propriedades `top`, `left`, `bottom`, e `right`. ### Ajustar finamente a posição No Flexbox, as posições das entities são maioritariamente determinadas pela forma como estão aninhadas, e pelas propriedades de arranjo definidas no parent e no child. Muitas vezes não precisa de definir a `position` property de todo. Mas, se quiser ajustar isso, ou substituir completamente o fluxo normal do Flexbox e definir uma posição absoluta, aqui estão as propriedades relevantes: * `positionType`: Define como as entities são posicionadas. Usa um valor do `PositionType` . * `relative`: (PADRÃO) Por defeito, uma entity é posicionada relativamente. Isto significa que uma entity é posicionada de acordo com o fluxo normal do layout e depois deslocada relativamente a essa posição com base nos valores de `top`, `right`, `bottom`, e `left`. O deslocamento não afeta a posição de quaisquer sibling ou parent entities. * `absolute`: Quando posicionada absolutamente, uma entity não participa no fluxo normal do layout. Em vez disso, é disposta de forma independente dos seus siblings. A posição é determinada com base no `top`, `right`, `bottom`, e `left` valores. * `position`: Os valores de posição `top`, `right`, `bottom`, e `left` comportam-se de forma diferente dependendo do `positionType`. Para uma entity relativa, deslocam a posição da entity na direção especificada. No entanto, para uma entity absoluta, estas propriedades especificam o deslocamento do lado da entity em relação ao mesmo lado no parent. O valor esperado é um objeto que contém as propriedades `top`, `left`, `bottom`, e `right`. {% hint style="warning" %} **📔 Observação** : Um valor positivo para `top` ou `left` mede a distância para dentro a partir dessa mesma margem do parent. Exemplo: para posicionar um component deixando uma margem de 20 pixels em relação ao parent nos lados superior e esquerdo, defina `position` como `{ top: 20, left: 20 }`. {% endhint %} ### Visibility * `display`: Determina se uma entity está visível ou não. Para tornar uma entity invisível, defina `display` como `none`. ### Z Index O `zIndex` property de um `UiEntity` determina a ordem em que as entities são renderizadas. Entities com um `zIndex` mais alto são renderizadas por cima de entities com um `zIndex`. O valor por defeito `zIndex` é 0. ```ts import { UiEntity, ReactEcs } from '@dcl/sdk/react-ecs' import { Color4 } from '@dcl/sdk/math' export const uiMenu = () => ( ) ``` {% hint style="warning" %} **📔 Observação** : A `zIndex` property só ordena elementos relativamente a siblings diretos; não pode ser usada para renderizar uma entity por cima de outras partes da árvore de layout. Em termos de html/CSS, cada elemento DCL UI cria um novo [stacking context](https://web.dev/learn/css/z-index#stacking_context). Para ordenar módulos de UI independentes adicionados com `addUiRenderer()` entre si, use as `zIndex` do [renderer options](/creator/content-creator-pt/scenes-sdk7/ui-2d/onscreen-ui.md#stacking-order-between-ui-modules) em vez disso. A UI padrão da Decentraland, incluindo o mapa, chat, etc., é sempre renderizada por cima de todos os outros elementos de UI. {% endhint %} ## Containers roláveis Quando uma UI entity tem mais conteúdo do que cabe no tamanho atribuído, pode tornar a área rolável definindo `overflow` como `scroll` na entity `uiTransform`. Para criar um container rolável, a parent entity deve ter um tamanho fixo (usando `width` e `height`), e os children devem exceder esse tamanho. ```ts import { UiEntity, Label, ReactEcs } from '@dcl/sdk/react-ecs' import { Color4 } from '@dcl/sdk/math' export const scrollableMenu = () => ( {/* Estes children excedem a altura de 400px do parent, tornando a área rolável */} ) ``` Isto é útil para criar listas longas, inventários, registos de chat, tabelas de classificação ou qualquer painel em que o conteúdo possa crescer para além do que cabe no ecrã. Também pode aninhar containers roláveis dentro de outros layouts de UI. Por exemplo, uma modal de diálogo com um cabeçalho fixo e um corpo rolável: ```ts import { UiEntity, Label, ReactEcs } from '@dcl/sdk/react-ecs' import { Color4 } from '@dcl/sdk/math' export const dialogWithScroll = () => ( {/* Cabeçalho fixo */} ) ``` {% hint style="info" %} **💡 Dica**: Use `flexGrow: 1` na scrollable entity para fazer com que preencha o espaço restante no parent, para que se adapte se outros siblings (como um cabeçalho ou rodapé) mudarem de tamanho. {% endhint %} ## Tamanho responsivo de UI Jogadores com tamanhos de ecrã diferentes podem ver o layout da sua UI de forma diferente. Os valores em pixels são escalados em relação ao [ecrã virtual](/creator/content-creator-pt/scenes-sdk7/ui-2d/onscreen-ui.md#screen-virtual-scale) por si, para que a mesma UI mantenha as suas proporções entre resoluções — **não precisa de calcular um fator de escala por si**, e fazê-lo aplicaria a escala duas vezes. {% hint style="warning" %} **📔 Observação**: `devicePixelRatio` não participa no layout de UI. É uma pista de densidade do ecrã — útil para escolher entre uma versão 1x, 2x ou 3x de uma texture — e mais nada. Se a sua scene foi dimensionada numa versão anterior do SDK, espere que a UI dimensionada em pixels seja renderizada até 2–3 vezes maior em ecrãs de alta densidade (retina e mobile) e volte a verificar tudo o que tenha sido ajustado manualmente. {% endhint %} {% hint style="danger" %} **📔 Remova o seu próprio fator de escala.** Se a sua scene multiplicar os seus tamanhos por um fator que calcula a partir de `UiCanvasInformation` — normalmente `Math.min(width / 1920, height / 1080)` — remova esse multiplicador. É o mesmo fator que o SDK agora aplica por defeito, pelo que manter ambos faz com que a sua UI cresça quadraticamente com o tamanho do ecrã. Se preferir manter o seu próprio fator como o único, desative o ecrã virtual com `setUiRenderer(ui, { virtualWidth: 0, virtualHeight: 0 })`. {% endhint %} `UiCanvasInformation`, adicionado por defeito à root entity da scene, continua a ser a ferramenta certa para as decisões de layout que a escala não consegue expressar — um arranjo de diálogo diferente num ecrã estreito, escolher uma resolução de texture a partir de `devicePixelRatio`, ou ler você próprio as áreas insetadas. Não é a ferramenta certa para dimensionamento. O `UiCanvasInformation` component contém a seguinte informação: * `height`: Altura do Canvas em pixels * `width`: Largura do Canvas em pixels * `devicePixelRatio`: A razão entre a resolução em pixels físicos no dispositivo e os pixels no Canvas. Útil como pista de densidade do ecrã, por exemplo para escolher entre uma versão 1x, 2x ou 3x de uma texture. * `interactableArea`: Um `BorderRect` objeto, que detalha a área designada para elementos de UI da scene. Este objeto contém valores para `top`, `bottom`, `left` e `right`, cada um deles é o número de pixels dessa margem do ecrã ocupados pela UI do Explorer. * `screenInsetArea`: Um `BorderRect` objeto, que detalha a área insetada do ecrã (safe margins) reservada pela UI do dispositivo ou da plataforma, por exemplo o notch, a barra de estado, o indicador home ou os cantos arredondados no mobile. Este objeto contém valores para `top`, `bottom`, `left` e `right`, cada um deles é o número de pixels reservados nessa margem do ecrã. No desktop, isto é normalmente `0` em todos os lados. {% hint style="warning" %} **📔 Observação** : Diferentes explorers da Decentraland terão valores diferentes para estes, já que as UIs globais da plataforma podem diferir, e os valores podem mudar dinamicamente à medida que o utilizador expande ou oculta diferentes menus globais de UI. {% endhint %} ```ts import { engine, UiCanvasInformation } from "@dcl/sdk/ecs" export function Main() { const canvas = UiCanvasInformation.getOrNull(engine.RootEntity) if (!canvas) return console.log("DIMENSÕES DO CANVAS: ", canvas.width, canvas.height) } ``` Algumas outras boas práticas relativamente aos tamanhos de UI: * Se a largura ou a altura de qualquer elemento de UI for dinâmica, é bom também usar os `, que se ajusta para caber em todo o texto. Pode definir um`, `minWidth`, `maxHeight`, e `minHeight` parâmetros para garantir que permanecem dentro de valores razoáveis. * Um tamanho de fonte numérico é um valor de pixel virtual, escalado como qualquer outro. Se quiser um tamanho medido em relação ao Canvas, para que se mantenha independentemente do ecrã virtual, passe uma `vw`/`vh` string — veja [Tamanho de texto responsivo](/creator/content-creator-pt/scenes-sdk7/ui-2d/ui_text.md#responsive-text-size) {% hint style="info" %} **💡 Dica**: Para exemplos funcionais de dimensionamento de UI, veja a [`81,-2-ui-screen-inset-area`](https://github.com/decentraland/sdk7-test-scenes/tree/main/scenes/81,-2-ui-screen-inset-area) scene de teste, que executa os três `screenInset` modos (`'none'`, `'device'`, `'interactable'`) como três renderers coexistentes e imprime os valores em tempo real de `screenInsetArea` e `interactableArea` e [`76,-10-UiCanvasInformation`](https://github.com/decentraland/sdk7-test-scenes/tree/main/scenes/76,-10-UiCanvasInformation), que lê `UiCanvasInformation` a cada frame para dimensionar a UI de forma responsiva. {% endhint %} --- # 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/scenes-sdk7/ui-2d/ui-positioning.md?ask=&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.