> 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, usa o `uiTransform` componente para definir o tamanho, a posição e outras propriedades relacionadas com o alinhamento da entidade. O `uiTransform` componente funciona no espaço 2D do ecrã de forma muito semelhante a como o `Transform` componente funciona no espaço 3D da cena. ***ficheiro ui.tsx:*** ```ts import { UiEntity, ReactEcs } from '@dcl/sdk/react-ecs' import { Color4 } from '@dcl/sdk/math' export const uiMenu = () => ( ) ``` ***ficheiro index.ts:*** ```ts import { ReactEcsRenderer } from '@dcl/sdk/react-ecs' import { uiMenu } from './ui' export function main() { ReactEcsRenderer.setUiRenderer(uiMenu) } ``` {% hint style="warning" %} **📔 Nota**: Todos os snippets seguintes nesta página assumem que tens um `.ts` semelhante ao acima, a executar a `ReactEcsRenderer.setUiRenderer()` função. {% endhint %} ## Propriedades de posicionamento O alinhamento das entidades de UI baseia-se no modelo de alinhamento Flexbox. Este é um modelo muito poderoso para organizar dinamicamente entidades aninhadas dentro de modais que podem variar de tamanho. {% hint style="info" %} **💡 Dica**: A implementação de UI do Decentraland baseia-se na do [Yoga](https://yogalayout.com/docs/). Lê [este artigo](https://www.joshwcomeau.com/css/interactive-guide-to-flexbox/) para uma cobertura muito acessível e detalhada das propriedades disponíveis no Flexbox. {% endhint %} ### Tamanho da entidade Usa `width` e `height` para definir o tamanho da entidade. São suportados os seguintes tipos de valores: * `auto`: O tamanho adapta-se para caber no conteúdo no interior. Isto é muito conveniente para texto que pode variar de comprimento. Escreve o valor como "auto". * **Percentagem**: Como percentagem das medidas do pai. Escreve o valor como uma string que termina em "%", por exemplo `10 %`. * **Píxeis**: Escreve o valor como um número. * **Largura ou altura do ecrã**: Podem ser usados vw (view width) e vh (view height) para indicar uma fração do tamanho total da janela onde o Decentraland está a correr. Por exemplo `10vw` refere-se a 10% da largura da janela, `25vh` a 25% da altura da janela. Tem em conta que estas propriedades afetam o **valor predefinido** do tamanho desse item, o tamanho do item antes de quaisquer cálculos de flex grow e flex shrink serem efetuados. O tamanho final pode ser interpretado de forma diferente com base no tamanho da entidade pai e nas propriedades Flexbox que estiverem definidas. {% hint style="warning" %} **📔 Nota**: Em propriedades que suportam números e strings, para definir o valor em píxeis, escreve um número. Para definir estes campos como uma percentagem das medidas do pai, escreve o valor como uma string que termina em "%", por exemplo `10 %`. Também podes definir um valor em píxeis como string terminando a string em `px`, por exemplo `200px`. * Quando os valores são expressos como percentagem, estão sempre relacionados com o contentor pai. A entidade de nível superior da tua UI também tem um pai: 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 predefinição é a área segura do dispositivo. Por isso, uma entidade de nível raiz é 100% dessa área — num telemóvel que é mais estreito do que o ecrã, no desktop os dois coincidem. Passa `100%` é 100% dessa área — num telemóvel que é mais estreito do que o ecrã, no desktop os dois coincidem. Passa `screenInset: 'none'` se precisares de percentagens medidas em relação ao ecrã inteiro. * Se os valores forem expressos em píxeis, não são afetados pela escala do pai, mas também **não** são píxeis brutos do ecrã: são multiplicados pelo fator de escala da UI derivado do [ecrã virtual](/creator/content-creator-pt/scenes-sdk7/ui-2d/onscreen-ui.md#screen-virtual-scale), que está ativo por predefinição. 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 afetada pela escala do pai, pelo ecrã virtual ou por `screenInset`. Para que o `auto` width/height funcione, 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 filho usar `positionType: “absolute”`, o pai não se adaptará ao seu tamanho/posição * Se o UiTransform de um filho usar qualquer sobreposição de posição, o pai 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: * `maxWidth` e `maxHeight`: *number* ou string (como height e width). O tamanho máximo que a entidade pode ter. * `minWidth` e `minHeight`: *number* ou string (como height e width). O tamanho mínimo que a entidade pode ter. Se o pai for demasiado pequeno para caber o tamanho mínimo das entidades, estas ultrapassarão os limites do pai. * `flexBasis`: Esta é uma forma independente do eixo de fornecer o tamanho predefinido de um item ao longo do eixo principal. Definir o flex basis de um filho é semelhante a definir a width desse filho se o seu pai for um contentor com flex direction: row, ou a definir a height de um filho se o seu pai for um contentor com flex direction: column. ```ts import { UiEntity, ReactEcs } from '@dcl/sdk/react-ecs' import { Color4 } from '@dcl/sdk/math' export const uiMenu = () => ( ) ``` ### Organizar entidades filhas Por predefinição, as entidades filhas são posicionadas em relação ao canto superior esquerdo do respetivo pai. Podes usar propriedades como `justifyContent` e `alignItems` para alterar este comportamento. {% hint style="info" %} **💡 Dica**: Quaisquer propriedades que se refiram a *conteúdo* referem-se a entidades ao longo do eixo principal (determinado por `flexDirection`). Quaisquer propriedades que se refiram {% endhint %} * `flexDirection`: A direção de flex define a direção em que os filhos de um nó são dispostos. Isto também é referido como o eixo principal. O eixo principal é a direção em que os filhos são dispostos. O eixo cruzado é o eixo perpendicular ao eixo principal, ou o eixo em que são dispostas as linhas de quebra. O seu valor vem do `FlexDirectionType` tipo. Estão disponíveis as seguintes opções: * `row` (PADRÃO) * `row-reverse` * `column` * `column-reverse` * `justifyContent`: Esta propriedade descreve como alinhar os filhos ao longo do eixo principal do respetivo contentor. Por exemplo, podes usar esta propriedade para centrar um filho horizontalmente dentro de um contentor com `flexDirection` definido para row ou verticalmente dentro de um contentor com `flexDirection` definido para column. O valor desta propriedade tem de vir do `JustifyType` tipo. Os valores possíveis são: * `flex-start` (PADRÃO): Alinha os filhos de um contentor no início do eixo principal do contentor. * `flex-end`: Alinha os filhos de um contentor no fim do eixo principal do contentor. * `center`: Alinha os filhos de um contentor no centro do eixo principal do contentor. * `space-between`: Espaça uniformemente os filhos ao longo do eixo principal do contentor, distribuindo o espaço restante entre os filhos. * `space-around`: Espaça uniformemente os filhos ao longo do eixo principal do contentor, distribuindo o espaço restante à volta dos filhos. Comparado com space-between, usar space-around fará com que o espaço seja distribuído no início do primeiro filho e no fim do último filho. * `space-evenly`: Espaça uniformemente os filhos ao longo do eixo principal do contentor, distribuindo o espaço restante para que os espaços entre os filhos, e entre os filhos e as margens do contentor, sejam todos iguais. * `alignItems`: Descreve como alinhar os filhos ao longo do eixo cruzado do respetivo contentor. Align items é muito semelhante a justify content, mas em vez de se aplicar ao eixo principal, align items aplica-se ao eixo cruzado. Esta propriedade requer um valor do `AlignType` tipo. Estão disponíveis as seguintes opções: * `stretch`: (PADRÃO) Estica os filhos de um contentor para corresponder à altura do eixo cruzado do contentor. * `flex-start`: Alinha os filhos de um contentor no início do eixo cruzado do contentor. * `flex-end`: Alinha os filhos de um contentor no fim do eixo cruzado do contentor. * `center`: Alinha os filhos de um contentor no centro do eixo cruzado do contentor. * `baseline`: Alinha os filhos de um contentor ao longo de uma linha de base comum. Filhos individuais podem ser definidos como a linha de base de referência para os respetivos pais. * `alignSelf`: Align self tem as mesmas opções e o mesmo efeito que `alignItems` mas, em vez de afetar os filhos dentro de um contentor, podes aplicar esta propriedade a um único filho para alterar o respetivo alinhamento dentro do pai. align self substitui qualquer opção definida pelo pai com align items. O seu valor vem de `AlignType`, vê `alignItems` acima para detalhes sobre estas opções. * `alignContent`: Align content define a distribuição das linhas ao longo do eixo cruzado. Isto só tem efeito quando os itens são distribuídos por várias linhas usando `flexWrap`. O seu valor vem do `AlignType` tipo. Estão disponíveis as seguintes opções: * `flex-start`: (PADRÃO) Alinha as linhas quebradas no início do eixo cruzado do contentor. * `flex-end`: Alinha as linhas quebradas no fim do eixo cruzado do contentor. * `stretch`: Estica as linhas quebradas para corresponder à altura do eixo cruzado do contentor. * `center`: Alinha as linhas quebradas no centro do eixo cruzado do contentor. * `space-between`: Espaça uniformemente as linhas quebradas ao longo do eixo principal do contentor, distribuindo o espaço restante entre as linhas. * `space-around`: Espaça uniformemente as linhas quebradas ao longo do eixo principal do contentor, distribuindo o espaço restante à volta das linhas. Comparado com space-between, usar space-around fará com que o espaço seja distribuído no início da primeira linha e no fim da última linha. * `flexGrow`: Isto descreve como qualquer espaço dentro de um contentor deve ser distribuído pelos respetivos filhos ao longo do eixo principal. Depois de dispor os seus filhos, um contentor distribui qualquer espaço restante de acordo com os valores flex grow especificados pelos seus filhos. Flex grow aceita qualquer valor de ponto flutuante >= 0, sendo 0 o valor predefinido. Um contentor distribui qualquer espaço restante pelos seus filhos ponderado pelo valor de flex grow do filho. * `flexShrink`: Descreve como reduzir os filhos ao longo do eixo principal no caso de o tamanho total dos filhos ultrapassar o tamanho do contentor 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 filhos cresçam e encolham conforme necessário. Flex shrink aceita qualquer valor de ponto flutuante >= 0, sendo 1 o valor predefinido. Um contentor reduz os seus filhos ponderado pelo valor de flex shrink do filho. * `overflow`: Determina o que acontece se o tamanho dos filhos de uma entidade ultrapassar o do respetivo pai. Usa valores do `OverflowType` tipo. * `hidden`: As entidades em excesso tornam-se invisíveis. * `visible`: As entidades em excesso saem dos limites do pai. * `scroll`: A área torna-se rolável, permitindo ao jogador percorrer o conteúdo em excesso. Vê [Contentores roláveis](#scrollable-containers) para detalhes. * `flexWrap`: A propriedade flex wrap é definida nos contentores e controla o que acontece quando os filhos ultrapassam o tamanho do contentor ao longo do eixo principal. Por predefinição, os filhos são distribuídos por várias linhas ao longo do eixo principal, se necessário. Se a quebra estiver desativada com `nowrap`, os filhos são forçados para uma única linha (o que pode encolher entidades). wrap reverse comporta-se da mesma forma que wrap, mas a ordem das linhas é invertida. Esta propriedade recebe o seu valor do `FlexWrapType` tipo. * `wrap` * `nowrap` * `wrap-reverse` ### Margens e padding * `margin`: Esta propriedade afeta o espaçamento à volta do exterior de um nó. Um nó com margin desloca-se dos limites do respetivo pai, mas também desloca a localização de quaisquer irmãos. A margin de um nó contribui para o tamanho total do respetivo pai se o pai tiver tamanho automático. Define o espaço entre a entidade e as margens do respetivo pai. O valor esperado é um objeto que contém as propriedades `top`, `left`, `bottom`, e `right`. * `padding`: Esta propriedade afeta o tamanho do nó a que é aplicada. O padding no Yoga funciona como se box-sizing: border-box; estivesse definido. Isto significa que o padding não é adicionado ao tamanho total de uma entidade se esta tiver um tamanho explícito definido. Para nós com tamanho automático, o padding aumenta o tamanho do nó, bem como desloca a localização de quaisquer filhos. O valor esperado é um objeto que contém as propriedades `top`, `left`, `bottom`, e `right`. ### Ajustar a posição No Flexbox, as posições das entidades são maioritariamente determinadas pela forma como estão parentadas e pelas propriedades de disposição definidas no pai e no filho. Muitas vezes não tens de definir a propriedade `position` de todo. Mas se quiseres 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 entidades são posicionadas. Usa um valor do `PositionType` enum. * `relative`: (PADRÃO) Por predefinição, uma entidade é posicionada relativamente. Isto significa que uma entidade é posicionada de acordo com o fluxo normal da disposição 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 entidades irmãs ou pai. * `absolute`: Quando posicionada absolutamente, uma entidade não participa no fluxo normal da disposição. Em vez disso, é disposta de forma independente dos seus irmãos. A posição é determinada com base nos `top`, `right`, `bottom`, e `left` valores. * `position`: Os valores de posição `top`, `right`, `bottom`, e `left` comportam-se de forma diferente consoante o `positionType`. Para uma entidade relativa, deslocam a posição da entidade na direção especificada. Para uma entidade absoluta, estes atributos especificam porém o deslocamento do lado da entidade a partir do mesmo lado no pai. O valor esperado é um objeto que contém as propriedades `top`, `left`, `bottom`, e `right`. {% hint style="warning" %} **📔 Nota** : Um valor positivo para `top` ou `left` mede a distância para dentro a partir dessa mesma margem do pai. Exemplo: para posicionar um componente deixando uma margem de 20 píxeis em relação ao pai nos lados superior e esquerdo, define `position` a `{ top: 20, left: 20 }`. {% endhint %} ### Visibilidade * `display`: Determina se uma entidade está visível ou não. Para tornar uma entidade invisível, define `display` a `none`. ### Índice Z O `zIndex` propriedade de um `UiEntity` determina a ordem em que as entidades são renderizadas. As entidades com um `zIndex` mais alto são renderizadas por cima das entidades com um `zIndex`mais baixo. O `zIndex` predefinido é 0. ```ts import { UiEntity, ReactEcs } from '@dcl/sdk/react-ecs' import { Color4 } from '@dcl/sdk/math' export const uiMenu = () => ( ) ``` {% hint style="warning" %} **📔 Nota** : A `zIndex` propriedade apenas ordena elementos em relação a irmãos diretos, não podendo ser usada para renderizar uma entidade por cima de outras partes da árvore de disposição. Em termos de html/CSS, cada elemento de UI do DCL 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, usa o `zIndex` das [opções do renderer](/creator/content-creator-pt/scenes-sdk7/ui-2d/onscreen-ui.md#stacking-order-between-ui-modules) em vez disso. A UI predefinida do Decentraland, incluindo o mapa, o chat, etc., é sempre renderizada por cima de todos os outros elementos de UI. {% endhint %} ## Contentores roláveis Quando uma entidade de UI tem mais conteúdo do que cabe no tamanho atribuído, podes tornar a área rolável definindo `overflow` a `scroll` na `uiTransform`da entidade. O jogador pode então percorrer o conteúdo arrastando ou usando a roda do rato. `width` e `height`Para criar um contentor rolável, a entidade pai deve ter um tamanho fixo (usando ```ts import { UiEntity, Label, ReactEcs } from '@dcl/sdk/react-ecs' import { Color4 } from '@dcl/sdk/math' export const scrollableMenu = () => ( {/* Estes filhos ultrapassam a altura de 400px do pai, 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 podes aninhar contentores 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**: Usa `flexGrow: 1` na entidade rolável para a fazer preencher o espaço restante no pai, para que se adapte caso outros irmãos (como um cabeçalho ou rodapé) mudem de tamanho. {% endhint %} ## Tamanho da UI responsivo Jogadores com tamanhos de ecrã diferentes podem ver a tua disposição de UI de forma diferente. Os valores em píxeis são escalados em relação ao [ecrã virtual](/creator/content-creator-pt/scenes-sdk7/ui-2d/onscreen-ui.md#screen-virtual-scale) por ti, para que a mesma UI mantenha as suas proporções entre resoluções — **não precisas de calcular um fator de escala manualmente**, e fazê-lo aplicaria a escala duas vezes. {% hint style="warning" %} **📔 Nota**: `devicePixelRatio` não participa na disposição da UI. É uma dica de densidade de ecrã — útil para escolher entre uma versão 1x, 2x ou 3x de uma textura — e nada mais. Se a tua cena tiver sido dimensionada numa versão anterior do SDK, espera que a UI dimensionada em píxeis seja renderizada até 2–3 vezes maior em ecrãs de alta densidade (retina e mobile), e volta a verificar tudo o que tenha sido afinado manualmente. {% endhint %} {% hint style="danger" %} **📔 Remove o teu próprio fator de escala.** Se a sua scene multiplica 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 padrão, então manter os dois faz a sua UI crescer quadraticamente com o tamanho da tela. Se você preferir manter o seu próprio fator como o único, desative a tela virtual com `setUiRenderer(ui, { virtualWidth: 0, virtualHeight: 0 })`. {% endhint %} `UiCanvasInformation`, adicionado por padrão à root entity da scene, ainda é a ferramenta certa para as decisões de layout que o dimensionamento não consegue expressar — uma disposição diferente de diálogo em uma tela estreita, escolher uma resolução de Texture a partir de `devicePixelRatio`, ou ler as áreas de margem interna você mesmo. Não é a ferramenta certa para dimensionamento. O `UiCanvasInformation` o componente contém as seguintes informações: * `height`: Altura do Canvas em pixels * `width`: Largura do Canvas em pixels * `devicePixelRatio`: A relação entre a resolução em pixels físicos no dispositivo e os pixels no Canvas. Útil como dica de densidade de exibição, por exemplo para escolher entre uma versão 1x, 2x ou 3x de uma Texture. * `interactableArea`: Um `BorderRect` objeto, detalhando 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 nessa margem da tela ocupados pela UI do Explorer. * `screenInsetArea`: Um `BorderRect` objeto, detalhando a área de margem interna da tela (margens seguras) reservada pela UI do dispositivo ou da plataforma, por exemplo o notch, a status bar, o home indicator ou cantos arredondados em dispositivos móveis. Este objeto contém valores para `top`, `bottom`, `left` e `right`, cada um deles é o número de pixels reservados nessa borda da tela. No desktop, isso normalmente é `0` em todos os lados. {% hint style="warning" %} **📔 Nota** : Different explorers da Decentraland terão valores diferentes para esses itens, já que as UIs globais da plataforma podem diferir, e os valores podem mudar dinamicamente à medida que o usuário expande ou oculta diferentes menus globais da UI. {% endhint %} ```ts import { engine, UiCanvasInformation } from "@dcl/sdk/ecs" export function Main() { const canvas = UiCanvasInformation.getOrNull(engine.RootEntity) if (!canvas) return console.log("CANVAS DIMENSIONS: ", canvas.width, canvas.height) } ``` Algumas outras boas práticas em relação aos tamanhos da UI: * Se a largura ou a altura de qualquer elemento de UI for dinâmica, também é bom usar os `maxWidth`, `minWidth`, `maxHeight`, e `minHeight` parâmetros para garantir que permaneçam dentro de valores razoáveis. * Um tamanho de fonte numérico é um valor de pixel virtual, escalado como qualquer outro. Se você quiser um tamanho medido em relação ao canvas em vez disso, para que se mantenha independentemente da tela 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 práticos de dimensionamento da 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 todos os três `screenInset` modos (`'none'`, `'device'`, `'interactable'`) como três renderers coexistentes e imprime os valores em tempo real, e `screenInsetArea` e `interactableArea` valores, 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 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-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 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.