Posicionamiento de UI

Configura la posición, escala, padding y otras propiedades de las entidades UI.

Para todo tipo de contenido de UI, use el uiTransform componente para establecer el tamaño, la posición y otras propiedades relacionadas con la alineación de la entidad.

El uiTransform El componente funciona en el espacio 2D de la pantalla de forma muy parecida a como el Transform componente funciona en el espacio 3D de la escena.

archivo 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() }}
	/>
)

archivo index.ts:

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

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

📔 Nota: Todos los fragmentos siguientes en esta página asumen que tienes un .ts similar al anterior, ejecutando la ReactEcsRenderer.setUiRenderer() función.

Propiedades de posicionamiento

La alineación de las entidades de UI se basa en el modelo de alineación Flexbox. Este es un modelo muy potente para organizar dinámicamente entidades anidadas dentro de modales que pueden variar en tamaño.

💡 Consejo: La implementación de UI de Decentraland se basa en la de Yoga. Lea este artículo para una cobertura muy accesible y en profundidad de las propiedades disponibles en Flexbox.

Tamaño de la entidad

Usa width y height para establecer el tamaño de la entidad. Se admiten los siguientes tipos de valores:

• auto: El tamaño se adapta para ajustarse al contenido interior. Esto es muy conveniente para texto que puede variar en longitud. Escriba el valor como "auto".

• Porcentaje: Como porcentaje de las medidas del padre. Escriba el valor como una cadena que termine en "%", por ejemplo 10 %.

• Píxeles: Escriba el valor como un número.

• Ancho o alto de la pantalla: Se pueden usar vw (view width) y vh (view height) para indicar una fracción del tamaño completo de la ventana que ejecuta Decentraland. Por ejemplo 10vw se refiere al 10% del ancho de la ventana, 25vh al 25% de la altura de la ventana.

Tenga en cuenta que estas propiedades afectan al default tamaño de ese elemento, el tamaño del elemento antes de que se realicen los cálculos de flex grow y flex shrink. El tamaño final puede interpretarse de manera diferente según el tamaño de la entidad padre y las propiedades de Flexbox que estén configuradas.

📔 Nota: En propiedades que admiten tanto números como cadenas, para establecer el valor en píxeles escriba un número. Para establecer estos campos como un porcentaje de las medidas del padre, escriba el valor como una cadena que termine en "%", por ejemplo 10 %. También puede establecer un valor en píxeles como cadena terminando la cadena en px, por ejemplo 200px.

• Cuando los valores se expresan como porcentaje, siempre están en relación con el contenedor padre. Si la entidad no tiene padres, entonces el valor es un porcentaje de toda la pantalla.

• Si los valores se expresan en píxeles, son absolutos y no se ven afectados por la escala del padre.

• Si los valores se expresan en vh u vw, son un porcentaje de la ventana completa, no afectados por la escala del padre.

Para el auto para que width/height funcione, se aplican las siguientes reglas:

• El UiTransform que usa width/height como “auto” debería tener alignSelf: “center”/“flex-start”/“flex-end” O positionType: “absolute”

• Si el UiTransform de un hijo usa positionType: “absolute”, el padre no se adaptará a su tamaño/posición

• Si el UiTransform de un hijo usa cualquier sobrescritura de posición, el padre no se adaptará a su tamaño/posición

Estas otras propiedades también están disponibles para ajustar el tamaño de manera más avanzada:

• maxWidth y maxHeight: maxDistance o cadena (como height y width). El tamaño máximo que la entidad puede tener.

• minWidth y minHeight: maxDistance o cadena (como height y width). El tamaño mínimo que la entidad puede tener. Si el padre es demasiado pequeño para ajustar el tamaño mínimo de las entidades, estas desbordarán su padre.

• flexBasis: Esta es una forma independiente del eje de proporcionar el tamaño por defecto de un elemento a lo largo del eje principal. Establecer el flex basis de un hijo es similar a establecer el width de ese hijo si su padre es un contenedor con flex direction: row, o establecer la height de un hijo si su padre es un contenedor con flex direction: column.

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

export const uiMenu = () => (
	<UiEntity
		uiTransform={{
			alignSelf: 'center',
			alignContent: 'center',
			width: '80%',
			height: '30%',
			minWidth: 300,
			maxWidth: 2500,
			margin: { left: '10%', right: '10%' },
		}}
		uiBackground={{ color: Color4.Green() }}
	/>
)

Organizar entidades hijas

Por defecto, las entidades hijas se posicionan en relación con la esquina superior izquierda de su padre. Puede usar propiedades como justifyContent y alignItems para cambiar este comportamiento.

💡 Consejo: Cualquier propiedad que se refiera a content se refiere a las entidades a lo largo del eje principal (determinado por flexDirection). Cualquier propiedad que se refiera

• flexDirection: Flex direction controla la dirección en la que se disponen los hijos de un nodo. Esto también se denomina eje principal. El eje principal es la dirección en la que se disponen los hijos. El eje cruzado es el eje perpendicular al eje principal, o el eje en el que se disponen las líneas de ajuste. Toma su valor del FlexDirectionType tipo. Las siguientes opciones están disponibles:

  • row (POR DEFECTO)

  • row-reverse

  • column

  • column-reverse

• justifyContent: Esta propiedad describe cómo alinear a los hijos dentro del eje principal de su contenedor. Por ejemplo, puede usar esta propiedad para centrar un hijo horizontalmente dentro de un contenedor con flexDirection establecido en row o verticalmente dentro de un contenedor con flexDirection establecido en column. El valor de esta propiedad debe pertenecer al AlignType tipo. Los valores posibles son:

  • flex-start (POR DEFECTO): Alinear los hijos de un contenedor al inicio del eje principal del contenedor.

  • flex-end: Alinear los hijos de un contenedor al final del eje principal del contenedor.

  • center: Alinear los hijos de un contenedor en el centro del eje principal del contenedor.

  • space-between: Espaciar uniformemente a los hijos a lo largo del eje principal del contenedor, distribuyendo el espacio restante entre los hijos.

  • space-around: Espaciar uniformemente a los hijos a lo largo del eje principal del contenedor, distribuyendo el espacio restante alrededor de los hijos. En comparación con space-between, usar space-around resultará en espacio distribuido al comienzo del primer hijo y al final del último hijo.

• alignItems: Describe cómo alinear a los hijos a lo largo del eje cruzado de su contenedor. Align items es muy similar a justify content pero en lugar de aplicarse al eje principal, align items se aplica al eje cruzado. Esta propiedad requiere un valor de AlignType tipo. Las siguientes opciones están disponibles:

  • stretch: (POR DEFECTO) Estirar a los hijos de un contenedor para que coincidan con la altura del eje cruzado del contenedor.

  • flex-start: Alinear los hijos de un contenedor al inicio del eje cruzado del contenedor.

  • flex-end: Alinear los hijos de un contenedor al final del eje cruzado del contenedor.

  • center: Alinear los hijos de un contenedor en el centro del eje cruzado del contenedor.

  • baseline: Alinear los hijos de un contenedor a lo largo de una línea base común. Los hijos individuales pueden configurarse para ser la línea base de referencia para sus padres.

• alignSelf: Align self tiene las mismas opciones y efecto que alignItems pero en lugar de afectar a los hijos dentro de un contenedor, puede aplicar esta propiedad a un solo hijo para cambiar su alineación dentro de su padre. align self anula cualquier opción establecida por el padre con align items. Toma su valor de AlignType, ver alignItems arriba para detalles sobre estas opciones.

• alignContent: Align content define la distribución de líneas a lo largo del eje cruzado. Esto solo tiene efecto cuando los items se envuelven en múltiples líneas usando flexWrap. Toma su valor de AlignType tipo. Las siguientes opciones están disponibles:

  • flex-start: (POR DEFECTO) Alinear las líneas envueltas al inicio del eje cruzado del contenedor.

  • flex-end: Alinear las líneas envueltas al final del eje cruzado del contenedor.

  • stretch: Estirar las líneas envueltas para que coincidan con la altura del eje cruzado del contenedor.

  • center: Alinear las líneas envueltas en el centro del eje cruzado del contenedor.

  • space-between: Espaciar uniformemente las líneas envueltas a lo largo del eje principal del contenedor, distribuyendo el espacio restante entre las líneas.

  • space-around: Espaciar uniformemente las líneas envueltas a lo largo del eje principal del contenedor, distribuyendo el espacio restante alrededor de las líneas. En comparación con space-between, usar space-around resultará en espacio distribuido al inicio de las primeras líneas y al final de la última línea.

• flexGrow: Esto describe cómo se debe distribuir cualquier espacio dentro de un contenedor entre sus hijos a lo largo del eje principal. Después de colocar a sus hijos, un contenedor distribuirá cualquier espacio restante de acuerdo con los valores de flex grow especificados por sus hijos. Flex grow acepta cualquier valor de punto flotante >= 0, siendo 0 el valor por defecto. Un contenedor distribuirá cualquier espacio restante entre sus hijos ponderado por el valor de flex grow del hijo.

• flexShrink: Describe cómo reducir el tamaño de los hijos a lo largo del eje principal en el caso de que el tamaño total de los hijos desborde el tamaño del contenedor en el eje principal. flex shrink es muy similar a flex grow y puede pensarse de la misma manera si se considera cualquier tamaño desbordado como espacio restante negativo. Estas dos propiedades también funcionan bien juntas al permitir que los hijos crezcan y se reduzcan según sea necesario. Flex shrink acepta cualquier valor de punto flotante >= 0, siendo 1 el valor por defecto. Un contenedor reducirá a sus hijos ponderado por el valor de flex shrink del hijo.

• overflow: Determina qué sucede si el tamaño de los hijos de una entidad desborda su padre. Usa valores de OverflowType Entity

  • hidden: Las entidades que desbordan se vuelven invisibles.

  • visible: Las entidades que desbordan salen de los márgenes del padre.

• flexWrap: La propiedad flex wrap se establece en contenedores y controla qué sucede cuando los hijos desbordan el tamaño del contenedor a lo largo del eje principal. Por defecto, los hijos se fuerzan en una sola línea (lo que puede reducir el tamaño de las entidades). Si se permite el ajuste, los elementos se envuelven en múltiples líneas a lo largo del eje principal si es necesario. wrap-reverse se comporta igual, pero el orden de las líneas se invierte. Esta propiedad toma su valor de FlexWrapType Entity

  • wrap

  • no-wrap

  • wrap-reverse

Márgenes y relleno

• margin: Esta propiedad afecta el espaciado alrededor del exterior de un nodo. Un nodo con margin se desplazará respecto a los límites de su padre, pero también desplazará la ubicación de cualquier hermano. El margin de un nodo contribuye al tamaño total de su padre si el padre tiene tamaño automático. Establezca espacio entre la entidad y los márgenes de su padre. El valor esperado es un objeto que contiene las propiedades arriba, left, abajo, y right.

• padding: Esta propiedad afecta el tamaño del nodo al que se aplica. El padding en Yoga actúa como si box-sizing: border-box; estuviera establecido. Es decir, el padding no se sumará al tamaño total de una entidad si tiene un tamaño explícito establecido. Para nodos de tamaño automático, el padding aumentará el tamaño del nodo y desplazará la ubicación de cualquier hijo. El valor esperado es un objeto que contiene las propiedades arriba, left, abajo, y right.

Ajustar la posición

En Flexbox, las posiciones de las entidades se determinan principalmente por cómo están parentadas y qué propiedades de distribución se establecen en el padre y el hijo. A menudo no es necesario establecer la propiedad posición propiedad en absoluto. Pero si desea ajustarla, o anular completamente el flujo normal de Flexbox y establecer una posición absoluta, aquí están las propiedades relevantes:

• positionType: Define cómo se posicionan las entidades. Usa un valor de PositionType enum.

  • relative: (POR DEFECTO) Por defecto, una entidad se posiciona de forma relativa. Esto significa que una entidad se posiciona según el flujo normal del layout y luego se desplaza con respecto a esa posición según los valores de arriba, right, abajo, y left. El desplazamiento no afecta la posición de ningún hermano o entidad padre.

  • absolute: Cuando se posiciona de forma absoluta, una entidad no participa en el flujo normal del layout. En su lugar, se dispone de manera independiente de sus hermanos. La posición se determina en función de la arriba, right, abajo, y left valores más bajos.

• posición: Los valores de posición arriba, right, abajo, y left se comportan de forma diferente dependiendo del positionType. Para una entidad relativa, desplazan la posición de la entidad en la dirección especificada. Para una entidad absoluta, sin embargo, estas propiedades especifican el desplazamiento del lado de la entidad desde el mismo lado en el padre. El valor esperado es un objeto que contiene las propiedades arriba, left, abajo, y right.

📔 Nota : Al medir desde la parte superior, los números para posición deberían ser negativos. Ejemplo: para posicionar un componente dejando un margen de 20 píxeles con respecto al padre en los lados superior e izquierdo, establezca posición a 20, -20.

Visibility

• display: Determina si una entidad es visible o no. Para hacer una entidad invisible, establezca display a none.

Z Index

El zIndex propiedad de un UiEntity determina el orden en que se renderizan las entidades. Las entidades con un zIndex más alto se renderizan encima de las entidades con un zIndex. El valor por defecto zIndex es 0.

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

export const uiMenu = () => (
	<UiEntity
		uiTransform={{
			zIndex: 4
		}}
		uiBackground={{ color: Color4.Green() }}
	/>
)

📔 Nota : El zIndex la propiedad solo ordenará elementos en relación con hermanos directos, no puede usarse para renderizar una entidad encima de otras partes del árbol de layout. En términos de html/CSS, cada elemento UI de DCL crea un nuevo contexto de apilamiento.

La UI predeterminada de Decentraland, incluido el mapa, chat, etc., siempre se renderiza por encima de todos los demás elementos de UI.

Tamaño de UI responsivo

Los jugadores con diferentes tamaños de pantalla pueden ver su diseño de UI de manera distinta. Si establece el tamaño de cualquier elemento de UI a un número fijo de píxeles, esta UI puede verse demasiado pequeña para leer en pantallas retina, que tienen una densidad de píxeles mucho mayor.

En lugar de posicionar y escalar elementos de UI en términos de porcentajes de pantalla, también puede obtener las dimensiones del canvas y luego calcular las posiciones y tamaños absolutos siguiendo su propia lógica personalizada. Por ejemplo, podría elegir diferentes disposiciones de diálogos según el tamaño de la pantalla.

Para obtener información sobre la dimensión de la pantalla, puede comprobar el UiCanvasInformation, que se añade por defecto a la entidad raíz de la escena.

El UiCanvasInformation el componente contiene la siguiente información:

• height: Altura del canvas en píxeles

• width: Ancho del canvas en píxeles

• devicePixelRatio: La proporción de la resolución en píxeles físicos del dispositivo respecto a los píxeles en el canvas

• interactableArea: Un BorderRect objeto, detallando el área designada para los elementos de UI de la escena. Este objeto contiene valores para arriba, abajo, left y right, cada uno de estos es el número de píxeles en ese margen de la pantalla que ocupan las UIs del explorer.

📔 Nota : Diferentes Explorer de Decentraland tendrán valores distintos para estos, ya que las UIs globales de la plataforma pueden diferir, y los valores podrían cambiar dinámicamente a medida que el usuario expande u oculta diferentes menús de UI globales.

export function Main(){
  let canvas = UiCanvasInformation.get(engine.RootEntity)
	console.log("DIMENSIONES DEL CANVAS: ", canvas.width, canvas.height)
})

El siguiente fragmento calcula continuamente un valor multiplicador basado en el tamaño de la pantalla:

import { engine, UiCanvasInformation } from "@dcl/sdk/ecs"

let timer = 0
let canvasInfoTimer = 0.5
export let scaleFactor = 1

export function UIScaleUpdate() {

  // comprobar rayos
    timer += dt

    if (timer <= canvasInfoTimer) return
    timer = 0

    const uiCanvasInfo = UiCanvasInformation.getOrNull(engine.RootEntity)

    if (!uiCanvasInfo) return

    const newScaleFactor = Math.min(uiCanvasInfo.width / 1920, uiCanvasInfo.height / 1080)

    if (newScaleFactor !== scaleFactor) {
      scaleFactor = newScaleFactor
      console.log('NUEVO scaleFactor de UI: ', scaleFactor)
    }
  })
}

El valor de la scaleFactor variable, que esta función actualiza, puede usarse luego como multiplicador en cualquier elemento de UI de la escena, incluyendo heigh, width y fontSize valores más bajos.

import { UiEntity, Label, ReactEcs } from '@dcl/sdk/react-ecs'
import { scaleFactor } from './calculate-scale-factor'
import { Color4 } from '@dcl/sdk/math'

export const uiMenu = () => (
	<UiEntity
		uiTransform={{
			width: 200 * scaleFactor,
			height: 100 * scaleFactor,
			justifyContent: 'center',
			alignItems: 'center',
			padding: 4 * scaleFactor
		}}
		uiBackground={{ color: Color4.Green() }}
	>
	  	<Label
		        value={description}
		        fontSize={18 * scaleFactor}
		        textAlign="middle-center"
		        uiTransform={{
		          width: "auto",
		          height: "auto",
		          alignSelf: "center",
		          margin: { top: 10 * scaleFactor, bottom: 10 * scaleFactor },
		        }}
	      />
	</UiEntity>
)

Algunas otras buenas prácticas con respecto a los tamaños de UI:

• Si el ancho o alto de cualquier elemento de UI es dinámico, es bueno también usar los maxWidth, minWidth, maxHeight, y minHeight parámetros para asegurarse de que se mantengan dentro de valores razonables.

• El tamaño de fuente del texto es relativo a un número fijo de píxeles; debe hacerlo dinámico para que siga siendo legible en pantallas retina. Véase Tamaño de texto responsivo