> 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/escenas-sdk7/ui-2d/ui-positioning.md). # Posicionamiento 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:*** ```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 snippets de esta página asumen que tiene una `.ts` similar a la anterior, ejecutando la `ReactEcsRenderer.setUiRenderer()` function. {% endhint %} ## 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. {% hint style="info" %} **💡 Consejo**: La implementación de la UI de Decentraland se basa en la de [Yoga](https://yogalayout.com/docs/). Lea [este artículo](https://www.joshwcomeau.com/css/interactive-guide-to-flexbox/) para una cobertura muy accesible y en profundidad de las propiedades disponibles en Flexbox. {% endhint %} ### 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. {% hint style="warning" %} **📔 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`](/creator/content-creator-es/escenas-sdk7/ui-2d/onscreen-ui.md#screen-inset-area), 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. Un](/creator/content-creator-es/escenas-sdk7/ui-2d/onscreen-ui.md#screen-virtual-scale)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 `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 {% 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 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. ```ts import { UiEntity, ReactEcs } from '@dcl/sdk/react-ecs' import { Color4 } from '@dcl/sdk/math' export const uiMenu = () => ( ) ``` ### 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. {% hint style="info" %} **💡 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 {% endhint %} * `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](#scrollable-containers) 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`. {% hint style="warning" %} **📔 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 }`. {% endhint %} ### 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 `zIndex`más bajo. El `zIndex` predeterminado es 0. ```ts import { UiEntity, ReactEcs } from '@dcl/sdk/react-ecs' import { Color4 } from '@dcl/sdk/math' export const uiMenu = () => ( ) ``` {% hint style="warning" %} **📔 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](https://web.dev/learn/css/z-index#stacking_context). 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 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 `uiTransform`de 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. ```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 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: ```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 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. {% endhint %} ## 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](/creator/content-creator-es/escenas-sdk7/ui-2d/onscreen-ui.md#screen-virtual-scale) 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. {% hint style="warning" %} **📔 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. {% endhint %} {% hint style="danger" %} **📔 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 })`. {% endhint %} `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. {% hint style="warning" %} **📔 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. {% 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) } ``` 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](/creator/content-creator-es/escenas-sdk7/ui-2d/ui_text.md#responsive-text-size) {% hint style="info" %} **💡 Consejo**: Para ejemplos prácticos 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) 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`](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 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-es/escenas-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.