Ctrlk
For the complete documentation index, see llms.txt. This page is also available as Markdown.

Posicionamento da UI

Defina a position, scale, padding e outras propriedades de entities de UI.

Para todos os tipos de conteúdo de UI, use o uiTransform componente para definir o tamanho, a posição e outras propriedades relacionadas ao alinhamento da entidade.

A uiTransform componente funciona no espaço 2D da tela de forma muito semelhante ao Transform componente funciona no espaço 3D da cena.

arquivo ui.tsx:

import { UiEntity, ReactEcs } from '@dcl/sdk/react-ecs'
import { Color4 } from '@dcl/sdk/math'

export const uiMenu = () => (
	<UiEntity
		uiTransform={{
			width: '200px',
			height: '100px',
			justifyContent: 'center',
			alignItems: 'center',
		}}
		uiBackground={{ color: Color4.Green() }}
	/>
)

arquivo index.ts:

import { ReactEcsRenderer } from '@dcl/sdk/react-ecs'
import { uiMenu } from './ui'

export function main() {
    ReactEcsRenderer.setUiRenderer(uiMenu)
}

📔 Nota: Todos os snippets a seguir nesta página pressupõem que você tenha um .ts semelhante ao acima, executando a ReactEcsRenderer.setUiRenderer() função.

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.

💡 Dica: A implementação de UI do Decentraland baseia-se na de Yoga. Leia este artigo para uma cobertura muito acessível e detalhada das propriedades disponíveis no Flexbox.

Tamanho da entidade

Use width e height para definir o tamanho da entidade. Os seguintes tipos de valores são suportados:

  • auto: O tamanho se adapta para caber no conteúdo interno. Isso é muito conveniente para texto que pode variar de comprimento. Escreva o valor como “auto”.

  • Percentual: Como uma porcentagem das medidas do pai. Escreva o valor como uma string que termina em “%”, por exemplo 10 %.

  • Pixels: Escreva o valor como um número.

  • Largura ou altura da tela: Use vw (largura da janela) e vh (altura da janela) para indicar uma fração do tamanho total da janela que executa o Decentraland. Por exemplo 10vw refere-se a 10% da largura da janela, 25vh a 25% da altura da janela.

Observe que essas propriedades afetam o default tamanho padrão desse item, o tamanho do item antes que quaisquer cálculos de flex grow e flex shrink sejam realizados. O tamanho final pode ser interpretado de forma diferente com base no tamanho da entidade pai e nas propriedades Flexbox definidas.

📔 Nota: Em propriedades que aceitam números e strings, para definir o valor em pixels, escreva um número. Para definir esses campos como uma porcentagem das medidas do pai, escreva o valor como uma string que termina em “%”, por exemplo 10 %. Você também pode definir um valor em pixels como uma string, terminando a string em px, por exemplo 200px.

  • Quando os valores são expressos como uma porcentagem, eles estão sempre em relação ao contêiner pai. A entidade de nível superior da sua UI também tem um pai: o renderer a coloca dentro da área selecionada por screenInset, que por padrão é a área segura do dispositivo. Portanto, uma 100% é 100% dessa área — em um telefone que é mais estreito que a tela, no desktop os dois coincidem. Passe screenInset: 'none' se você precisar que as porcentagens sejam medidas em relação à tela inteira.

  • Se os valores forem expressos em pixels, eles não são afetados pela escala do pai, mas também não são pixels crus da tela: eles são multiplicados pelo fator de escala da UI derivado da não tela virtual , que fica ativa por padrão. Umawidth: 200 significa “200 px em uma tela do tamanho da tela virtual” e cresce ou encolhe proporcionalmente em qualquer outra. significa “200 px em uma tela do tamanho da tela virtual” e cresce ou encolhe proporcionalmente em qualquer outra.

  • Se os valores forem expressos em vh ou vw, eles são uma porcentagem da janela inteira, não são afetados pela escala do pai, pela tela virtual, nem por screenInset.

Para o auto width/height funcionarem, as regras a seguir se aplicam:

  • 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 sobrescrita de posição, o pai não se adaptará ao seu tamanho/posição

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 pequeno demais para caber no tamanho mínimo das entidades, elas transbordarão para fora do pai.

  • 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 filho é semelhante a definir a largura desse filho se o pai for um contêiner com flex direction: row ou a definir a altura de um filho se o pai for um contêiner com flex direction: column.

Organizando entidades filhas

Por padrão, as entidades filhas são posicionadas em relação ao canto superior esquerdo do seu pai. Você pode usar propriedades como justifyContent e alignItems para alterar esse comportamento.

💡 Dica: Quaisquer propriedades que se refiram a conteúdo se referem a entidades ao longo do eixo principal (determinado por flexDirection). Quaisquer propriedades que se refiram

  • flexDirection: A direção flex controla a direção em que os filhos de um nó são dispostos. Isso também é chamado de 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 as linhas de quebra são dispostas. Ele obtém seu valor de FlexDirectionType tipo. As opções a seguir estão disponíveis:

    • row (PADRÃO)

    • row-reverse

    • column

    • column-reverse

  • justifyContent: Esta propriedade descreve como alinhar os filhos dentro do eixo principal do seu contêiner. Por exemplo, você pode usar esta propriedade para centralizar um filho horizontalmente dentro de um contêiner com flexDirection definido como row ou verticalmente dentro de um contêiner com flexDirection definido como column. O valor desta propriedade deve ser do JustifyType tipo. Os valores possíveis são:

    • flex-start (PADRÃO): Alinha os filhos de um contêiner ao início do eixo principal do contêiner.

    • flex-end: Alinha os filhos de um contêiner ao final do eixo principal do contêiner.

    • center: Alinha os filhos de um contêiner no centro do eixo principal do contêiner.

    • space-between: Distribui uniformemente os filhos ao longo do eixo principal do contêiner, distribuindo o espaço restante entre os filhos.

    • space-around: Distribui uniformemente os filhos ao longo do eixo principal do contêiner, distribuindo o espaço restante ao redor dos filhos. Em comparação com space-between, usar space-around resultará em espaço distribuído no início do primeiro filho e no fim do último filho.

    • space-evenly: Distribui uniformemente os filhos ao longo do eixo principal do contêiner, distribuindo o espaço restante para que os espaços entre os filhos e entre os filhos e as bordas do contêiner sejam todos iguais.

  • alignItems: Descreve como alinhar os filhos ao longo do eixo cruzado do seu contêiner. Align items é muito semelhante a justify content, mas em vez de se aplicar ao eixo principal, align items se aplica ao eixo cruzado. Esta propriedade requer um valor do AlignType tipo. As opções a seguir estão disponíveis:

    • stretch: (PADRÃO) Estica os filhos de um contêiner para corresponder à altura do eixo cruzado do contêiner.

    • flex-start: Alinha os filhos de um contêiner ao início do eixo cruzado do contêiner.

    • flex-end: Alinha os filhos de um contêiner ao fim do eixo cruzado do contêiner.

    • center: Alinha os filhos de um contêiner no centro do eixo cruzado do contêiner.

    • baseline: Alinha os filhos de um contêiner ao longo de uma linha de base comum. Filhos individuais podem ser definidos como a linha de base de referência para seus pais.

  • alignSelf: Align self tem as mesmas opções e efeito que alignItems mas, em vez de afetar os filhos dentro de um contêiner, você pode aplicar esta propriedade a um único filho para alterar seu alinhamento dentro do seu pai. align self substitui qualquer opção definida pelo pai com align items. Ele obtém seu valor de AlignType, veja alignItems acima para detalhes sobre essas opções.

  • alignContent: Align content define a distribuição das linhas ao longo do eixo cruzado. Isso só tem efeito quando os itens são quebrados em várias linhas usando flexWrap. Ele obtém seu valor do AlignType tipo. As opções a seguir estão disponíveis:

    • flex-start: (PADRÃO) Alinha as linhas quebradas ao início do eixo cruzado do contêiner.

    • flex-end: Alinha as linhas quebradas ao fim do eixo cruzado do contêiner.

    • stretch: Estica as linhas quebradas para corresponder à altura do eixo cruzado do contêiner.

    • center: Alinha as linhas quebradas no centro do eixo cruzado do contêiner.

    • space-between: Distribui uniformemente as linhas quebradas ao longo do eixo principal do contêiner, distribuindo o espaço restante entre as linhas.

    • space-around: Distribui uniformemente as linhas quebradas ao longo do eixo principal do contêiner, distribuindo o espaço restante ao redor das linhas. Em comparação com space-between, usar space-around resultará em espaço distribuído no início da primeira linha e no fim da última linha.

  • flexGrow: Isto descreve como o espaço dentro de um contêiner deve ser distribuído entre seus filhos ao longo do eixo principal. Depois de organizar seus filhos, um contêiner distribuirá qualquer espaço restante de acordo com os valores de flex grow especificados por seus filhos. Flex grow aceita qualquer valor de ponto flutuante >= 0, sendo 0 o valor padrão. Um contêiner distribuirá qualquer espaço restante entre seus filhos ponderado pelo valor de flex grow de cada filho.

  • flexShrink: Descreve como encolher os filhos ao longo do eixo principal no caso de o tamanho total dos filhos exceder o tamanho do contêiner no eixo principal. flex shrink é muito semelhante a flex grow e pode ser pensado da mesma forma se qualquer tamanho excedente for considerado espaço restante negativo. Essas duas propriedades também funcionam bem juntas, permitindo que os filhos cresçam e encolham conforme necessário. Flex shrink aceita qualquer valor de ponto flutuante >= 0, sendo 1 o valor padrão. Um contêiner encolherá seus filhos ponderado pelo valor de flex shrink de cada filho.

  • overflow: Determina o que acontece se o tamanho dos filhos de uma entidade exceder o tamanho do seu pai. Usa valores do OverflowType tipo.

    • hidden: Entidades que excedem os limites são tornadas invisíveis.

    • visible: Entidades que excedem os limites ultrapassam as margens do pai.

    • scroll: A área torna-se rolável, permitindo que o jogador percorra o conteúdo excedente. Veja contêineres roláveis para detalhes.

  • flexWrap: A propriedade flex wrap é definida em contêineres e controla o que acontece quando os filhos excedem o tamanho do contêiner ao longo do eixo principal. Por padrão, os filhos são quebrados em várias linhas ao longo do eixo principal, se necessário. Se a quebra for desativada com nowrap, os filhos são forçados a ficar em uma única linha (o que pode encolher entidades). wrap reverse funciona da mesma maneira que wrap, mas a ordem das linhas é invertida. Esta propriedade obtém seu valor do FlexWrapType tipo.

    • wrap

    • nowrap

    • wrap-reverse

Margens e padding

  • margin: Esta propriedade afeta o espaçamento ao redor da parte externa de um nó. Um nó com margin se deslocará em relação aos limites do seu pai, mas também deslocará a posição de quaisquer irmãos. A margin de um nó contribui para o tamanho total do seu pai se o pai tiver tamanho automático. Defina o espaço entre a entidade e as margens do seu pai. O valor esperado é um objeto que contém as propriedades top, left, bottom, e right.

  • padding: Esta propriedade afeta o tamanho do nó ao qual é aplicada. 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 entidade se ela tiver um tamanho explícito definido. Para nós com tamanho automático, o padding aumentará o tamanho do nó, bem como deslocará a posição de quaisquer filhos. O valor esperado é um objeto que contém as propriedades top, left, bottom, e right.

Ajuste fino da posição

No Flexbox, as posições das entidades são determinadas principalmente por como elas são parentadas e quais propriedades de arranjo estão definidas no pai e no filho. Muitas vezes você não precisa definir a posição propriedade alguma. 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 entidades são posicionadas. Usa um valor do PositionType enum.

    • relative: (PADRÃO) Por padrão, uma entidade é posicionada relativamente. Isso significa que a entidade é posicionada de acordo com o fluxo normal do layout e depois deslocada em relação 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 do fluxo normal do layout. Em vez disso, ela é disposta independentemente de seus irmãos. A posição é determinada com base em top, right, bottom, e left valores.

  • posição: Os valores de posição top, right, bottom, e left comportam-se de maneira diferente dependendo de positionType. Para uma entidade relativa, eles deslocam a posição da entidade na direção especificada. Porém, para uma entidade absoluta, essas propriedades especificam o deslocamento do lado da entidade em relação ao mesmo lado no pai. O valor esperado é um objeto que contém as propriedades top, left, bottom, e right.

📔 Nota : Um valor positivo para top ou left mede a distância para dentro a partir da mesma borda do pai. Exemplo: para posicionar um componente deixando uma margem de 20 pixels em relação ao pai nas partes superior e esquerda, defina posição quando você define { top: 20, left: 20 }.

Visibilidade

  • display: Determina se uma entidade está visível ou não. Para tornar uma entidade invisível, defina display quando você define none.

Índice Z

A zIndex propriedade de um UiEntity determina a ordem em que as entidades são renderizadas. Entidades com um zIndex mais alto zIndexsão renderizadas acima de entidades com um zIndex mais baixo

📔 Nota : O zIndex A propriedade só ordenará elementos em relação a irmãos diretos; ela não pode ser usada para renderizar uma entidade acima de outras partes da árvore de layout. Em termos de html/CSS, cada elemento de UI do DCL cria um novo contexto de empilhamento.

A UI padrão do Decentraland, incluindo o mapa, o chat etc., é sempre renderizada acima de todos os outros elementos de UI.

contêineres roláveis

Quando uma entidade de UI tem mais conteúdo do que cabe no tamanho atribuído, você pode tornar a área rolável definindo overflow quando você define scroll na entidade uiTransform. O jogador pode então percorrer o conteúdo arrastando ou usando a roda do mouse.

Para criar um contêiner rolável, a entidade pai deve ter um tamanho fixo (usando width e height), e os filhos devem exceder esse tamanho.

Isso é útil para criar listas longas, inventários, logs de chat, placares ou qualquer painel em que o conteúdo possa crescer além do que cabe na tela.

Você também pode aninhar contêineres roláveis dentro de outros layouts de UI. Por exemplo, um modal de diálogo com um cabeçalho fixo e um corpo rolável:

💡 Dica: Use flexGrow: 1 na entidade rolável para fazê-la preencher o espaço restante no pai, assim ela se adapta se outros irmãos (como um cabeçalho ou rodapé) mudarem de tamanho.

Tamanho responsivo da UI

Jogadores com tamanhos de tela diferentes podem ver o layout da sua UI de forma diferente. Os valores em pixels são escalados em relação ao , que fica ativa por padrão. Uma para você, então a mesma UI mantém suas proporções entre resoluções — você não precisa calcular um fator de escala por conta própria, e fazer isso aplica a escala duas vezes.

📔 Nota: devicePixelRatio não participa do layout da UI. É uma dica de densidade de exibição — útil para escolher entre uma versão 1x, 2x ou 3x de uma textura — e nada mais. Se sua cena foi dimensionada em uma versão anterior do SDK, espere que a UI com tamanho em pixels seja renderizada até 2–3 vezes maior em telas de alta densidade (retina e mobile), e revise qualquer coisa que tenha sido ajustada manualmente.

📔 Remova seu próprio fator de escala. Se sua cena multiplica seus tamanhos por um fator que ela 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 sua UI crescer quadraticamente com o tamanho da tela. Se preferir manter seu próprio fator como o único, desative a tela virtual com setUiRenderer(ui, { virtualWidth: 0, virtualHeight: 0 }).

UiCanvasInformation, adicionado por padrão à entidade raiz da cena, ainda é a ferramenta certa para as decisões de layout que a escala não consegue expressar — um arranjo de diálogo diferente em uma tela estreita, escolher uma resolução de textura a partir de devicePixelRatio, ou ler você mesmo as áreas de recuo. Não é a ferramenta certa para dimensionamento.

A 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 textura.

  • interactableArea: Um BorderRect objeto, detalhando a área designada para os elementos de UI da cena. 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 recuo da tela (margens seguras) reservada pela UI do dispositivo ou da plataforma, por exemplo o notch, a barra de status, o indicador inicial ou os 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 naquela borda da tela. No desktop, isso normalmente é 0 em todos os lados.

📔 Nota : Explorers diferentes do Decentraland terão valores diferentes para isso, pois as UIs globais da plataforma podem diferir, e os valores podem mudar dinamicamente à medida que o usuário expande ou oculta diferentes menus globais de UI.

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, para que ele se mantenha independentemente da tela virtual, passe uma vw/vh string — veja Tamanho de texto responsivo

💡 Dica: Para exemplos funcionais de dimensionamento de UI, veja o 81,-2-ui-screen-inset-area cena de teste, que executa os três screenInset modos ('none', 'device', 'interactable') como três renderers coexistentes e imprime os screenInsetArea e interactableArea valores, e 76,-10-UiCanvasInformation, que lê UiCanvasInformation a cada frame para dimensionar a UI de forma responsiva.

AnteriorUI na tela
PróximoFundo da UI

Atualizado