Texto de UI

Escribe texto en Entities de UI.

Agrega texto a tu UI creando un Label entity.

Un Label entity tiene los siguientes campos que se pueden configurar:

• value: La cadena a mostrar

• fontSize: El tamaño del texto, como número.

  NOTA: El fontSize no se ve afectado por el tamaño de su entity o de sus parent entities.

• color: El color del texto, como un Color4.

• font: La fuente a usar. Los valores admitidos son:

  • 'serif'

  • 'sans-serif' (predeterminado)

  • 'monospace'

• textAlign: Cómo se alineará el texto con su padre. Toma un valor del TextAlignType tipo. TextAlignType = 'top-left' | 'top-center' | 'top-right' | 'middle-left' | 'middle-center' | 'middle-right' | 'bottom-left' | 'bottom-center' | 'bottom-right';

• textWrap: Establece si el texto usa saltos de línea para evitar exceder el ancho máximo. Está activado de forma predeterminada ('wrap'), para desactivarlo pasa el valor 'nowrap'.

📔 Nota: El fontSize no se ve afectado por el tamaño de su entity o de sus parent entities.

Un Label entity también puede tener otros componentes comunes presentes en otros tipos de UI entities, como uiTransform y uiBackground.

archivo ui.tsx:

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

export const uiMenu = () => (
	<UiEntity uiTransform={{ width: 'auto', height: 'auto' }}>
		<Label
			value="Esto es una etiqueta"
			color={Color4.Red()}
			fontSize={29}
			font="sans-serif"
			textAlign="top-left"
		/>
	</UiEntity>
)

archivo index.ts:

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

export function main() {
    ReactEcsRenderer.setUiRenderer(uiMenu, { virtualWidth: 1920, virtualHeight: 1080 })
}

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

Si una línea de texto es demasiado larga para caber en el ancho asignado, o en el ancho máximo de su contenedor, el texto continuará en la siguiente línea. Puedes desactivar esto cambiando el valor de la textWrap propiedad a 'nowrap'.

También puedes forzar un salto de línea agregando explícitamente \n a la cadena.

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

export const uiMenu = () => (
	<UiEntity uiTransform={{ width: 700, height: 400 }}>
		<Label 
			value="¡Hola mundo!\nEsta otra parte es bastante larga. Probablemente no quepa en una sola línea, así que incluirá un salto de línea en algún punto.\nCuarta línea"
			textWrap= {`nowrap`} 
		/>
	</UiEntity>
)

Si no se establece explícitamente height o width se establece en el uiTransform del contenedor, el contenedor usará el valor auto, que se ajusta para encajar todo el texto. Puedes establecer un maxWidth y un maxHeight para asegurarte de que no exceda ciertos límites. También puedes usar minWidth y minHeight para asegurarte de que el contenedor no se haga demasiado pequeño, incluso si el texto es más corto.

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

export const uiMenu = () => (
	<UiEntity
		uiTransform={{
			minWidth: 100,
			maxWidth: 300,
			height: 'auto',
			alignSelf: 'center',
			padding: 10,
		}}
		uiBackground={{
			color: Color4.Red(),
		}}
		uiText={{
			value: '¡Hola mundo!',
			fontSize: 18,
		}}
	/>
)

Tamaño de texto adaptable

Usa la scaleFontSize() función para proporcionar valores de fuente que se ajusten al tamaño de la pantalla del jugador. Al establecer la fontSize propiedad de una UI entity de texto, pasa esta función en lugar de un solo número.

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

export const uiMenu = () => (
  <UiEntity
    uiTransform={{
      width: 'auto',
      height: 'auto',
      alignSelf: 'center',
      padding: 10,
    }}
    uiText={{
      value: '¡Hola mundo!',
      fontSize: scaleFontSize(15)
    }}
  />
)

La scaleFontSize() función requiere dos parámetros:

• fontSize: El tamaño base de fuente a usar.

• scaleUnit (opcional): El factor de escala. Esto determina si el texto debe ajustarse en función del ancho o la altura de la pantalla, y un multiplicador de cuánto adaptar. Predeterminado: 0.39 (un número, por lo que se interpreta como relativo a width). Los valores pueden ser:

  • Number: Un número simple; en este caso se interpreta como relativo a width

  • Cadena que termina en vw: Esto hace que el número sea relativo al ancho de la vista. Por ejemplo "0.8vw"

  • Cadena que termina en vh: Esto hace que el número sea relativo a la altura de la vista. Por ejemplo "0.8vh"

💡 Consejo: Esta función funciona de manera similar a CSS calc() función.

El valor de scaleUnit es un porcentaje del ancho o la altura de la ventana. Así que un scaleUnit de "100vw" es el 100% del ancho de la pantalla, un valor de "0.5vw" es el 0.5% del ancho de la pantalla.

La fórmula que scaleFontSize() sigue multiplica el ancho o la altura de la pantalla por el scaleUnit, y le suma el fontSize pasado en el primer parámetro.

final font = fontSize + (screen width * scaleUnit / 100)

Por ejemplo, en el fragmento de abajo se usa un scaleUnit valor de 0.8. Si el ancho de la pantalla es 1280px, eso dará como resultado un texto de tamaño 25.24, siguiendo la ecuación 15 + (1280 * 0.8 / 100).

📔 Nota: scaleFontSize() devuelve un number, por lo que su resultado es un tamaño en virtual píxeles virtuales — todavía se multiplica por el UI scale factor antes de dibujarse. En el ejemplo anterior, con la 1920x1080 pantalla virtual y un canvas de 1280px de ancho, el factor de escala es 1280 / 1920 = 0.667, por lo que el texto se renderiza en aproximadamente 16.8px. Si quieres un tamaño de fuente medido directamente contra el canvas, que ignore la pantalla virtual, pasa una vw/vh string directamente a fontSize en su lugar — por ejemplo fontSize: '1.8vh'.

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

export const uiMenu = () => (
  <UiEntity
    uiTransform={{
      width: 'auto',
      height: 'auto',
      alignSelf: 'center',
      padding: 10,
    }}
    uiText={{
      value: '¡Hola mundo!',
      fontSize: scaleFontSize(15, 0.8)
    }}
  />
)

💡 Consejo: Si no tienes diferentes tamaños de pantalla para probar, puedes intentar usar el Web Explorer y redimensionar la ventana donde ejecutas el preview. El texto se ajustará al instante cada vez que cambies la ventana.

Como alternativa a scaleFontSize(), pasa una vw/vh string directamente como el fontSize — por ejemplo fontSize: '1.8vh' — que dimensiona el texto contra el canvas e ignora por completo el factor de escala de la UI. No no multipliques los tamaños de fuente por un factor que calcules tú mismo a partir de UiCanvasInformation: el SDK ya aplica uno, ver Tamaño de UI adaptable.