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

Posicionamiento de UI

Establece la posición, escala, relleno y otras propiedades de las Entities de UI.

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

La uiTransform component funciona en el espacio 2D de la pantalla muy parecido al Transform component funciona en el espacio 3D de la scene.

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 siguientes snippets de esta página asumen que tiene una .ts similar a la anterior, ejecutando la ReactEcsRenderer.setUiRenderer() function.

Propiedades de posicionamiento

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

💡 Consejo: La implementación de la 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 entity

Usa width y height para establecer el tamaño de la entity. 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".

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

  • Pixels: 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 el predeterminado tamaño de ese item, el tamaño del item antes de que se realicen los cálculos de flex grow y flex shrink. El tamaño final puede interpretarse de forma diferente según el tamaño de la entity padre y las propiedades Flexbox que se hayan establecido.

📔 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 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 una cadena terminándola en px, por ejemplo 200px.

  • Cuando los valores se expresan como porcentaje, siempre se relacionan con el contenedor padre. La entity de nivel raíz de su UI también tiene un padre: el renderer la coloca dentro del área seleccionada por screenInset, que por defecto es el área segura del dispositivo. Así que una 100% de nivel raíz es el 100% de esa área — en un teléfono que es más estrecho que la pantalla, en desktop ambos coinciden. Pase screenInset: 'none' si necesita porcentajes medidos contra la pantalla completa.

  • Si los valores se expresan en píxeles, no se ven afectados por la escala del padre, pero tampoco son píxeles crudos de pantalla: se multiplican por el factor de escala de la UI derivado de la se refiere pantalla virtual , que está activa por defecto. Unwidth: 200 significa "200 px en una pantalla del tamaño de la pantalla virtual", y crece o se reduce proporcionalmente en cualquier otra. Si los valores se expresan en

  • vh vw o , son un porcentaje de la ventana completa, no afectados por la escala del padre, por la pantalla virtual ni por. Para que funcione screenInset.

width/height auto , se aplican las siguientes reglas:

  • El UiTransform que usa width/height como “auto” debe 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 una forma más avanzada:

  • maxWidth y maxHeight: number o string (como height y width). El tamaño máximo que puede tener la entity.

  • minWidth y minHeight: number o string (como height y width). El tamaño mínimo que puede tener la entity. Si el padre es demasiado pequeño para acomodar el tamaño mínimo de las entities, estas desbordarán de su padre.

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

Organización de entities hijas

De forma predeterminada, las entities 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 entities 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 node. Esto también se conoce como el 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 envueltas. Toma su valor del FlexDirectionType type. Las siguientes opciones están disponibles:

    • row (DEFAULT)

    • row-reverse

    • column

    • column-reverse

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

    • flex-start (DEFAULT): Alinea los hijos de un container al inicio del eje principal del container.

    • flex-end: Alinea los hijos de un container al final del eje principal del container.

    • center: Alinea los hijos de un container en el centro del eje principal del container.

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

    • space-around: Espacia uniformemente a los hijos a lo largo del eje principal del container, distribuyendo el espacio restante alrededor de los hijos. En comparación con space-between, usar space-around hará que el espacio se distribuya al inicio del primer hijo y al final del último hijo.

    • space-evenly: Espacia uniformemente a los hijos a lo largo del eje principal del container, distribuyendo el espacio restante para que los espacios entre los hijos y entre los hijos y los bordes del container sean todos iguales.

  • alignItems: Describe cómo alinear los hijos a lo largo del eje cruzado de su container. 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 del AlignType type. Las siguientes opciones están disponibles:

    • stretch: (DEFAULT) Estira los hijos de un container para que coincidan con la altura del eje cruzado del container.

    • flex-start: Alinea los hijos de un container al inicio del eje cruzado del container.

    • flex-end: Alinea los hijos de un container al final del eje cruzado del container.

    • center: Alinea los hijos de un container en el centro del eje cruzado del container.

    • baseline: Alinea los hijos de un container 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 el mismo efecto que alignItems pero, en lugar de afectar a los hijos dentro de un container, puede aplicar esta propiedad a un solo hijo para cambiar su alineación dentro de su padre. align self sobrescribe cualquier opción establecida por el padre con align items. Toma su valor de AlignType, consulta alignItems arriba para obtener detalles sobre estas opciones.

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

    • flex-start: (DEFAULT) Alinea las líneas envueltas al inicio del eje cruzado del container.

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

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

    • center: Alinea las líneas envueltas en el centro del eje cruzado del container.

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

    • space-around: Espacia uniformemente las líneas envueltas a lo largo del eje principal del container, distribuyendo el espacio restante alrededor de las líneas. En comparación con space-between, usar space-around hará que el espacio se distribuya al inicio de las primeras líneas y al final de la última línea.

  • flexGrow: Esto describe cómo debe distribuirse cualquier espacio dentro de un container entre sus hijos a lo largo del eje principal. Después de disponer a sus hijos, un container distribuirá cualquier espacio restante según los valores de flex grow especificados por sus hijos. Flex grow acepta cualquier valor de punto flotante >= 0, siendo 0 el valor predeterminado. Un container distribuirá cualquier espacio restante entre sus hijos ponderado por el valor de flex grow del hijo.

  • flexShrink: Describe cómo reducir 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 container en el eje principal. flex shrink es muy similar a flex grow y puede entenderse de la misma manera si se considera que cualquier tamaño desbordado es 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 predeterminado. Un container reducirá sus hijos ponderado por el valor de flex shrink del hijo.

  • overflow: Determina qué ocurre si el tamaño de los hijos de una entity desborda a su padre. Usa valores del OverflowType tipo.

    • hidden: Las entities que desbordan se hacen invisibles.

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

    • scroll: El área se vuelve desplazable, lo que permite al player desplazarse por el contenido que desborda. Consulte contenedores desplazables para más detalles.

  • flexWrap: La propiedad flex wrap se establece en los containers y controla lo que ocurre cuando los hijos desbordan el tamaño del container a lo largo del eje principal. De forma predeterminada, los hijos se envuelven en varias líneas a lo largo del eje principal si es necesario. Si el ajuste se deshabilita con nowrap, los hijos se fuerzan a una sola línea (lo que puede reducir entities). wrap-reverse se comporta igual que wrap, pero el orden de las líneas se invierte. Esta propiedad toma su valor del FlexWrapType tipo.

    • wrap

    • nowrap

    • wrap-reverse

Márgenes y padding

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

  • padding: Esta propiedad afecta al tamaño del node al que se aplica. El padding en Yoga actúa como si se hubiera establecido box-sizing: border-box;. Es decir, el padding no se sumará al tamaño total de una entity si tiene un tamaño explícito establecido. Para nodes con tamaño auto, el padding aumentará el tamaño del node y también desplazará la ubicación de cualquier hijo. El valor esperado es un objeto que contiene las propiedades top, left, bottom, y right.

Ajuste fino de la posición

En Flexbox, las posiciones de las entities se determinan en su mayor parte por cómo están parentadas y qué propiedades de organización están establecidas en el padre y el hijo. A menudo no tiene que establecer la position propiedad en absoluto. Pero si desea ajustarla, o sobrescribir por completo el flujo normal de Flexbox y establecer una posición absoluta, estas son las propiedades relevantes:

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

    • relative: (DEFAULT) De forma predeterminada, una entity se posiciona de forma relativa. Esto significa que una entity se posiciona según el flujo normal del layout y luego se desplaza de forma relativa a esa posición en función de los valores de top, right, bottom, y left. El desplazamiento no afecta a la posición de ningún sibling ni entity padre.

    • absolute: Cuando se posiciona de forma absoluta, una entity no participa en el flujo normal del layout. En su lugar, se dispone de forma independiente de sus siblings. La posición se determina en función de top, right, bottom, y left valores.

  • position: Los valores de posición top, right, bottom, y left se comportan de forma diferente según positionType. Para una entity relativa, desplazan la posición de la entity en la dirección especificada. Pero para una entity absoluta, estas propiedades especifican el desplazamiento del lado de la entity desde el mismo lado del padre. El valor esperado es un objeto que contiene las propiedades top, left, bottom, y right.

📔 Nota : Un valor positivo para top o left mide la distancia hacia dentro desde ese mismo borde del padre. Ejemplo: para posicionar un component dejando un margen de 20 píxeles con respecto al padre en los lados superior e izquierdo, establezca position a { top: 20, left: 20 }.

Visibilidad

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

Z Index

La zIndex property de un UiEntity determina el orden en que se renderizan las entities. Las entities con un zIndex más alto se renderizan encima de las entities con un zIndexmás bajo. El zIndex predeterminado es 0.

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

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

contenedores desplazables

Cuando una entity de UI tiene más contenido del que cabe en el tamaño asignado, puede hacer que el área sea desplazable estableciendo overflow a scroll en la uiTransformde la entity. Entonces el player puede desplazarse por el contenido arrastrando o usando la rueda del mouse.

Para crear un contenedor desplazable, la entity padre debe tener un tamaño fijo (usando width y height), y los hijos deben superar ese tamaño.

Esto es útil para construir listas largas, inventarios, registros de chat, tablas de clasificación o cualquier panel en el que el contenido pueda crecer más allá de lo que cabe en pantalla.

También puede anidar contenedores desplazables dentro de otros layouts de UI. Por ejemplo, un modal de diálogo con un encabezado fijo y un cuerpo desplazable:

💡 Consejo: Usa flexGrow: 1 en la entity desplazable para que llene el espacio restante en el padre, de modo que se adapte si otras entidades hermanas (como un header o footer) cambian de tamaño.

Tamaño responsivo de la UI

Jugadores con distintos tamaños de pantalla pueden ver el layout de su UI de forma diferente. Los valores en píxeles se escalan en función de la , que está activa por defecto. Un para ti, así que la misma UI mantiene sus proporciones en distintas resoluciones — no necesitas calcular tú mismo un factor de escala, y hacerlo aplica el escalado dos veces.

📔 Nota: devicePixelRatio no participa en el layout de la UI. Es una pista de densidad de pantalla — útil para elegir entre una versión 1x, 2x o 3x de una Texture — y nada más. Si tu scene se dimensionó con una versión anterior del SDK, espere que la UI de tamaño en píxeles se renderice hasta 2–3 veces más grande en pantallas de alta densidad (retina y mobile), y vuelva a revisar cualquier ajuste hecho a mano.

📔 Elimine su propio factor de escala. Si su scene multiplica sus tamaños por un factor que calcula a partir de UiCanvasInformation — normalmente Math.min(width / 1920, height / 1080) — elimine ese multiplicador. Es el mismo factor que ahora aplica el SDK por defecto, así que mantener ambos hace que su UI crezca de forma cuadrática con el tamaño de la pantalla. Si prefiere conservar su propio factor como el único, desactive la pantalla virtual con setUiRenderer(ui, { virtualWidth: 0, virtualHeight: 0 }).

UiCanvasInformation, añadida por defecto a la RootEntity de la scene, sigue siendo la herramienta adecuada para las decisiones de layout que el escalado no puede expresar — un arreglo de diálogo diferente en una pantalla estrecha, elegir una resolución de textura a partir de devicePixelRatio, o leer por su cuenta las áreas inset. No es la herramienta adecuada para el dimensionamiento.

La UiCanvasInformation component contiene la siguiente información:

  • height: Altura del canvas en píxeles

  • width: Anchura del canvas en píxeles

  • devicePixelRatio: La relación entre la resolución en píxeles físicos del dispositivo y los píxeles del canvas. Útil como pista de densidad de pantalla, por ejemplo para elegir entre una versión 1x, 2x o 3x de una Texture.

  • interactableArea: Un BorderRect objeto, que detalla el área designada para los elementos de UI de la scene. Este objeto contiene valores para top, bottom, left y right, cada uno de ellos es el número de píxeles de ese margen de la pantalla que ocupa la UI del explorer.

  • screenInsetArea: Un BorderRect objeto, que detalla el área de screen inset (márgenes seguros) reservada por la UI del dispositivo o de la plataforma, por ejemplo el notch, la barra de estado, el indicador de inicio o las esquinas redondeadas en mobile. Este objeto contiene valores para top, bottom, left y right, cada uno de ellos es el número de píxeles reservados en ese borde de la pantalla. En desktop esto suele ser 0 en todos los lados.

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

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

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

  • Un tamaño de fuente numérico es un valor de píxel virtual, escalado como cualquier otro. Si quieres un tamaño medido en relación con el canvas, para que se mantenga independientemente de la pantalla virtual, pasa una , son un porcentaje de la ventana completa, no afectados por la escala del padre, por la pantalla virtual ni por/vw string — consulta Tamaño de texto responsivo

💡 Consejo: Para ejemplos prácticos de dimensionamiento de UI, consulta la 81,-2-ui-screen-inset-area escena de prueba, que ejecuta los tres screenInset modos ('none', 'device', 'interactable') como tres renderizadores coexistentes e imprime los valores en vivo, y screenInsetArea y interactableArea valores, y 76,-10-UiCanvasInformation, que lee UiCanvasInformation cada frame para dimensionar la UI de forma responsiva.

AnteriorUI en pantalla
SiguienteFondo de UI

Última actualización