> 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-es/scenes-sdk7/ui-2d/ui-positioning.md). # Posicionamiento de UI Establece la posición, escala, padding y otras propiedades de las entidades de UI. Para todo tipo de contenido de UI, usa 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 al `Transform` El componente funciona en el espacio 3D de la escena. ***Archivo ui.tsx:*** ```ts import { UiEntity, ReactEcs } from '@dcl/sdk/react-ecs' import { Color4 } from '@dcl/sdk/math' export const uiMenu = () => ( ) ``` ***Archivo 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 los siguientes fragmentos de esta página asumen que tienes un `.ts` similar al anterior, ejecutando la `ReactEcsRenderer.setUiRenderer()` función. {% endhint %} ## Propiedades de posicionamiento La alineación de las entidades de UI se basa en el modelo de alineación de Flexbox. Este es un modelo muy potente para organizar dinámicamente entidades anidadas dentro de modales que pueden variar de tamaño. {% hint style="info" %} **💡 Consejo**: La implementación de UI de Decentraland está basada en la de [Yoga](https://yogalayout.com/docs/). Lee [este artículo](https://www.joshwcomeau.com/css/interactive-guide-to-flexbox/) para una cobertura muy accesible y detallada de las propiedades disponibles en Flexbox. {% endhint %} ### 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 ajustar el contenido interior. Esto es muy conveniente para texto que puede variar en longitud. Escribe el valor como "auto". * **Porcentaje**: Como porcentaje de las medidas del padre. Escribe el valor como una cadena que termine en "%", por ejemplo `10 %`. * **Píxeles**: Escribe 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% del alto de la ventana. Ten 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 forma diferente según el tamaño de la entidad padre y las propiedades de Flexbox que se establezcan. {% hint style="warning" %} **📔 Nota**: En las propiedades que admiten tanto números como cadenas, para establecer el valor en píxeles, escribe un número. Para establecer estos campos como un porcentaje de las medidas del padre, escribe el valor como una cadena que termine en "%", por ejemplo `10 %`. También puedes establecer un valor en píxeles como una 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. La entidad de nivel superior de tu UI también tiene un padre: el renderer la coloca dentro del área seleccionada por [`screenInset`](/creator/content-creator-es/scenes-sdk7/ui-2d/onscreen-ui.md#screen-inset-area), que por defecto es el área segura del dispositivo. Así que una entidad de nivel raíz `100%` es el 100% de esa área — en un teléfono eso es más estrecho que la pantalla, en escritorio ambos coinciden. Pasa `screenInset: 'none'` si necesitas porcentajes medidos con respecto a la pantalla completa. * Si los valores se expresan en píxeles, no se ven afectados por la escala del padre, pero tampoco son **no** píxeles en crudo de pantalla tampoco: se multiplican por el factor de escala de la UI derivado de [pantalla virtual](/creator/content-creator-es/scenes-sdk7/ui-2d/onscreen-ui.md#screen-virtual-scale)la pantalla virtual, que está activa de forma predeterminada. Un `width: 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` o `vw`, son un porcentaje de la ventana completa, no afectados por la escala del padre, por la pantalla virtual ni por `screenInset`. Para el `auto` para que width/height funcionen, 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 {% endhint %} Estas otras propiedades también están disponibles para ajustar el tamaño de una forma más avanzada: * `maxWidth` y `maxHeight`: *number* o cadena (como height y width). El tamaño máximo que puede tener la entidad. * `minWidth` y `minHeight`: *number* o cadena (como height y width). El tamaño mínimo que puede tener la entidad. Si el padre es demasiado pequeño para ajustarse al tamaño mínimo de las entidades, estas desbordarán de su padre. * `flexBasis`: Esta es una forma independiente del eje de proporcionar el tamaño predeterminado 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 a establecer la height de un hijo si su padre es un contenedor con flex direction: column. ```ts import { UiEntity, ReactEcs } from '@dcl/sdk/react-ecs' import { Color4 } from '@dcl/sdk/math' export const uiMenu = () => ( ) ``` ### Organizar entidades hijas Por defecto, las entidades hijas se posicionan con relación a la esquina superior izquierda de su padre. Puedes usar propiedades como `justifyContent` y `alignItems` para cambiar este comportamiento. {% hint style="info" %} **💡 Consejo**: Cualquier propiedad que se refiera a *content* se refiere a entidades a lo largo del eje principal (determinado por `flexDirection`). Cualquier propiedad que se refiera {% endhint %} * `flexDirection`: Flex direction controla la dirección en la que se distribuyen los hijos de un nodo. Esto también se conoce como eje principal. El eje principal es la dirección en la que se distribuyen los hijos. El eje transversal es el eje perpendicular al eje principal, o el eje en el que se distribuyen las líneas de ajuste. Toma su valor de `FlexDirectionType` type. Las siguientes opciones están disponibles: * `row` (POR DEFECTO) * `row-reverse` * `column` * `column-reverse` * `justifyContent`: Esta propiedad describe cómo alinear los hijos dentro del eje principal de su contenedor. Por ejemplo, puedes 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 provenir de `JustifyType` type. Los valores posibles son: * `flex-start` (POR DEFECTO): Alinea los hijos de un contenedor al inicio del eje principal del contenedor. * `flex-end`: Alinea los hijos de un contenedor al final del eje principal del contenedor. * `center`: Alinea los hijos de un contenedor en el centro del eje principal del contenedor. * `space-between`: Distribuye uniformemente los hijos a lo largo del eje principal del contenedor, distribuyendo el espacio restante entre los hijos. * `space-around`: Distribuye uniformemente 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 hará que el espacio se distribuya al inicio del primer hijo y al final del último hijo. * `space-evenly`: Distribuye uniformemente los hijos a lo largo del eje principal del contenedor, distribuyendo el espacio restante de modo que los espacios entre los hijos, y entre los hijos y los bordes del contenedor, sean todos iguales. * `alignItems`: Describe cómo alinear los hijos a lo largo del eje transversal 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 transversal. Esta propiedad requiere un valor de `AlignType` type. Las siguientes opciones están disponibles: * `stretch`: (POR DEFECTO) Estira los hijos de un contenedor para que coincidan con la altura del eje transversal del contenedor. * `flex-start`: Alinea los hijos de un contenedor al inicio del eje transversal del contenedor. * `flex-end`: Alinea los hijos de un contenedor al final del eje transversal del contenedor. * `center`: Alinea los hijos de un contenedor en el centro del eje transversal del contenedor. * `baseline`: Alinea los hijos de un contenedor a lo largo de una línea de base común. Los hijos individuales pueden configurarse para ser la línea de base de referencia de 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 contenedor, puedes 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`, 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 transversal. Esto solo tiene efecto cuando los elementos se ajustan a varias líneas usando `flexWrap`. Toma su valor de `AlignType` type. Las siguientes opciones están disponibles: * `flex-start`(POR DEFECTO) Alinea las líneas ajustadas al inicio del eje transversal del contenedor. * `flex-end`: Alinea las líneas ajustadas al final del eje transversal del contenedor. * `stretch`: Estira las líneas ajustadas para que coincidan con la altura del eje transversal del contenedor. * `center`: Alinea las líneas ajustadas en el centro del eje transversal del contenedor. * `space-between`: Distribuye uniformemente las líneas ajustadas a lo largo del eje principal del contenedor, distribuyendo el espacio restante entre las líneas. * `space-around`: Distribuye uniformemente las líneas ajustadas 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 hará que el espacio se distribuya al inicio de la primera línea y al final de la última línea. * `flexGrow`: Esto describe cómo debe distribuirse cualquier espacio dentro de un contenedor entre sus hijos a lo largo del eje principal. Después de distribuir a sus hijos, un contenedor repartirá 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 contenedor distribuirá cualquier espacio restante entre sus hijos ponderado por el valor de flex grow del hijo. * `flexShrink`: Describe cómo reducir a los hijos a lo largo del eje principal en 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 cualquier tamaño que desborde se considera 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 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 a su padre. Usa valores de `OverflowType` . * `hidden`: Las entidades desbordadas se vuelven invisibles. * `visible`: Las entidades desbordadas salen de los márgenes del padre. * `scroll`: El área se vuelve desplazable, lo que permite al jugador desplazarse por el contenido desbordado. Ver [Contenedores desplazables](#scrollable-containers) para más detalles. * `flexWrap`: La propiedad flex wrap se establece en los 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 ajustan 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 las entidades). wrap-reverse se comporta igual que wrap, pero el orden de las líneas se invierte. Esta propiedad toma su valor de `FlexWrapType` . * `wrap` * `nowrap` * `wrap-reverse` ### Márgenes y padding * `margin`: Esta propiedad afecta al espaciado alrededor del exterior de un nodo. Un nodo con margin se separará de 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. Establece el espacio entre la entidad 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 nodo al que se aplica. Padding en Yoga actúa como si se hubiera establecido box-sizing: border-box;. Es decir, padding no se añadirá al tamaño total de una entidad si tiene un tamaño explícito establecido. Para nodos de tamaño automático, padding aumentará el tamaño del nodo 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`. ### Ajustar la posición con precisión En Flexbox, las posiciones de las entidades se determinan principalmente por cómo están vinculadas como padre e hijo y por las propiedades de disposición establecidas en el padre y el hijo. A menudo no tienes que establecer la `posición` propiedad en absoluto. Pero si quieres ajustarlo o anular por completo 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 de forma relativa a esa posición según los valores de `top`, `right`, `bottom`, y `left`. El desplazamiento no afecta a la posición de ninguna entidad hermana o padre. * `absolute`: Cuando se posiciona absolutamente, una entidad no participa en el flujo normal del layout. En su lugar, se distribuye de forma independiente de sus hermanos. La posición se determina en función de `top`, `right`, `bottom`, y `left` valores. * `posición`: Los valores de posición `top`, `right`, `bottom`, y `left` se comportan de manera diferente según `positionType`. Para una entidad relativa, desplazan la posición de la entidad en la dirección especificada. Sin embargo, para una entidad absoluta, estas propiedades especifican el desplazamiento del lado de la entidad con respecto al mismo lado del padre. El valor esperado es un objeto que contiene las propiedades `top`, `left`, `bottom`, y `right`. {% hint style="warning" %} **📔 Nota** : Un valor positivo para `top` o `left` mide la distancia hacia adentro desde ese mismo borde del padre. Ejemplo: para posicionar un componente dejando un margen de 20 píxeles con respecto al padre en los lados superior e izquierdo, establece `posición` en `{ top: 20, left: 20 }`. {% endhint %} ### Visibility * `display`: Determina si una entidad es visible o no. Para hacer una entidad invisible, establece `display` en `none`. ### Z Index El `zIndex` propiedad de un `UiEntity` determina el orden en que se renderizan las entidades. Las entidades con un valor más alto de `zIndex` se renderizan por encima de las entidades con un valor más bajo de `zIndex`. El valor predeterminado `zIndex` es 0. ```ts import { UiEntity, ReactEcs } from '@dcl/sdk/react-ecs' import { Color4 } from '@dcl/sdk/math' export const uiMenu = () => ( ) ``` {% hint style="warning" %} **📔 Nota** : La `zIndex` propiedad solo ordenará elementos con respecto a hermanos directos; no puede usarse para renderizar una entidad por encima de otras partes del árbol de layout. En términos de HTML/CSS, cada elemento de UI de DCL crea un nuevo [contexto de apilamiento](https://web.dev/learn/css/z-index#stacking_context). Para ordenar módulos independientes de UI añadidos con `addUiRenderer()` entre sí, usa las `zIndex` de la [opciones del renderer](/creator/content-creator-es/scenes-sdk7/ui-2d/onscreen-ui.md#stacking-order-between-ui-modules) en su lugar. La UI predeterminada de Decentraland, incluido el mapa, el chat, etc., siempre se renderiza por encima de todos los demás elementos de UI. {% endhint %} ## Contenedores desplazables Cuando una entidad de UI tiene más contenido del que cabe en su tamaño asignado, puedes hacer que el área sea desplazable configurando `overflow` en `scroll` overflow en el `uiTransform`. Luego, el jugador puede desplazarse por el contenido arrastrando o usando la rueda del mouse. Para crear un contenedor desplazable, la entidad padre debe tener un tamaño fijo (usando `width` y `height`), y los hijos deben superar ese tamaño. ```ts import { UiEntity, Label, ReactEcs } from '@dcl/sdk/react-ecs' import { Color4 } from '@dcl/sdk/math' export const scrollableMenu = () => ( {/* Estos hijos superan la altura de 400px del padre, haciendo que el área sea desplazable */} ) ``` Esto es útil para crear 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 puedes anidar contenedores desplazables dentro de otros layouts de UI. Por ejemplo, un modal de diálogo con un encabezado fijo y un cuerpo desplazable: ```ts import { UiEntity, Label, ReactEcs } from '@dcl/sdk/react-ecs' import { Color4 } from '@dcl/sdk/math' export const dialogWithScroll = () => ( {/* Encabezado fijo */} ) ``` {% hint style="info" %} **💡 Consejo**: Usa `flexGrow: 1` en la entidad desplazable para que llene el espacio restante en el padre, de modo que se adapte si otros hermanos (como un encabezado o un pie de página) cambian de tamaño. {% endhint %} ## Tamaño de UI responsive Los jugadores con tamaños de pantalla diferentes pueden ver tu layout de UI de manera distinta. Los valores de píxeles se escalan con respecto a la [pantalla virtual](/creator/content-creator-es/scenes-sdk7/ui-2d/onscreen-ui.md#screen-virtual-scale) por ti, por lo que la misma UI mantiene sus proporciones entre resoluciones — **no necesitas calcular un factor de escala tú mismo**, y hacerlo aplica la escala dos veces. {% hint style="warning" %} **📔 Nota**: `devicePixelRatio` no participa en el layout de 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ó en una versión anterior del SDK, espera 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 móviles), y vuelve a comprobar cualquier cosa que haya sido ajustada manualmente. {% endhint %} {% hint style="danger" %} **📔 Elimina tu propio factor de escala.** Si tu scene multiplica sus tamaños por un factor que calcula a partir de `UiCanvasInformation` — normalmente `Math.min(width / 1920, height / 1080)` — elimina ese multiplicador. Es el mismo factor que ahora aplica el SDK por defecto, así que mantener ambos hace que tu UI crezca cuadráticamente con el tamaño de la pantalla. Si prefieres mantener tu propio factor como el único, desactiva la pantalla virtual con `setUiRenderer(ui, { virtualWidth: 0, virtualHeight: 0 })`. {% endhint %} `UiCanvasInformation`, añadida por defecto a la entidad raíz de la scene, sigue siendo la herramienta adecuada para las decisiones de layout que la escala no puede expresar — una disposición diferente de diálogo en una pantalla estrecha, elegir una resolución de textura a partir de `devicePixelRatio`, o leer tú mismo las áreas de inset. No es la herramienta adecuada para dimensionar. 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 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 inset de la pantalla (márgenes seguros) reservada por la UI del dispositivo o de la plataforma, por ejemplo la muesca, la barra de estado, el indicador de inicio o las esquinas redondeadas en móviles. 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 escritorio esto suele ser `0` en todos los lados. {% hint style="warning" %} **📔 Nota** : Distintos Explorers de Decentraland tendrán valores diferentes para estos, ya que las UIs globales de la plataforma pueden diferir y los valores pueden cambiar dinámicamente a medida que el usuario expande u oculta distintos menús globales 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("CANVAS DIMENSIONS: ", canvas.width, canvas.height) } ``` Otras buenas prácticas sobre los tamaños de UI: * Si el ancho o el alto de cualquier elemento de UI es dinámico, también conviene usar los `maxWidth`, `minWidth`, `maxHeight`, y `minHeight` parámetros para asegurarte 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 en cambio quieres un tamaño medido con respecto al Canvas, para que se mantenga independientemente de la pantalla virtual, pasa una `vw`/`vh` cadena — consulta [Tamaño de texto responsive](/creator/content-creator-es/scenes-sdk7/ui-2d/ui_text.md#responsive-text-size) {% hint style="info" %} **💡 Consejo**: Para ver ejemplos funcionales de dimensionamiento de UI, consulta la [`81,-2-ui-screen-inset-area`](https://github.com/decentraland/sdk7-test-scenes/tree/main/scenes/81,-2-ui-screen-inset-area) scene de prueba, que ejecuta los tres `screenInset` modos (`'none'`, `'device'`, `'interactable'`) como tres renderers coexistentes e imprime los valores en vivo de `screenInsetArea` y `interactableArea` los valores, y [`76,-10-UiCanvasInformation`](https://github.com/decentraland/sdk7-test-scenes/tree/main/scenes/76,-10-UiCanvasInformation), que lee `UiCanvasInformation` cada frame para dimensionar la 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-es/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.