Texto da UI

Escreva texto em entities de UI.

Adicione texto à sua UI criando um Label entity.

Um Label entity tem os seguintes campos que podem ser configurados:

• value: A string a ser exibida

• fontSize: O tamanho do texto, como um número.

  NOTA: O fontSize não é afetado pelo tamanho da sua entity ou das parent entities.

• color: A cor do texto, como um Color4.

• font: A fonte a ser usada. Os valores suportados são:

  • 'serif'

  • 'sans-serif' (padrão)

  • 'monospace'

• textAlign: Como o texto se alinhará com o seu pai. Ele recebe um valor do TextAlignType type. TextAlignType = 'top-left' | 'top-center' | 'top-right' | 'middle-left' | 'middle-center' | 'middle-right' | 'bottom-left' | 'bottom-center' | 'bottom-right';

• textWrap: Define se o texto usa quebras de linha para evitar exceder a largura máxima. Ele vem ativado por padrão ('wrap'), para desativá-lo, passe o valor 'nowrap'.

📔 Nota: O fontSize não é afetado pelo tamanho da sua entity ou das parent entities.

Um Label entity também pode ter outros componentes comuns encontrados em outros tipos de UI entities, como uiTransform e uiBackground.

arquivo 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="This is a label"
			color={Color4.Red()}
			fontSize={29}
			font="sans-serif"
			textAlign="top-left"
		/>
	</UiEntity>
)

arquivo 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 os snippets a seguir nesta página pressupõem que você tenha um .ts semelhante ao acima, executando o ReactEcsRenderer.setUiRenderer() função.

Se uma linha de texto for longa demais para caber na largura atribuída, ou na largura máxima do seu container, o texto continuará na linha seguinte. Você pode desativar isso alterando o valor da textWrap propriedade para 'nowrap'.

Você também pode forçar uma quebra de linha adicionando explicitamente \n à string.

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

export const uiMenu = () => (
	<UiEntity uiTransform={{ width: 700, height: 400 }}>
		<Label 
			value="Hello World!\nThis other bit is quite long. It probably won't fit in a single line, so it will include a line break somewhere.\nFourth line"
			textWrap= {`nowrap`} 
		/>
	</UiEntity>
)

Se nenhuma height ou width estiver definida no uiTransform container, o container usará o valor auto, que se ajusta para caber em todo o texto. Você pode definir um maxWidth e um maxHeight para garantir que ele não exceda certos limites. Você também pode usar minWidth e minHeight para garantir que o container não fique pequeno demais, mesmo se o texto for mais curto.

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: 'Hello world!',
			fontSize: 18,
		}}
	/>
)

Tamanho responsivo do texto

Use a scaleFontSize() função para fornecer valores de fonte que se ajustam ao tamanho da tela do jogador. Ao definir a fontSize propriedade de uma entity de UI de texto, passe esta função em vez de um único 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: 'Hello world!',
      fontSize: scaleFontSize(15)
    }}
  />
)

A scaleFontSize() função requer dois parâmetros:

• fontSize: O tamanho base da fonte a ser usado.

• scaleUnit (opcional): O fator de escala. Isso determina se o texto deve ser ajustado com base na largura ou na altura da tela, e um multiplicador para o quanto adaptar. Padrão: 0.39 (um número, então ele é interpretado como relativo a width). Os valores podem ser:

  • Number: Um número simples; neste caso, ele é interpretado como relativo a width

  • String terminando em vw: Isso torna o número relativo à largura da view. Por exemplo "0.8vw"

  • String terminando em vh: Isso torna o número relativo à altura da view. Por exemplo "0.8vh"

💡 Dica: Esta função funciona de forma semelhante à CSS calc() função.

O valor de scaleUnit é uma porcentagem da largura ou altura da janela. Portanto, um scaleUnit de "100vw" é 100% da largura da tela, um valor de "0.5vw" é 0,5% da largura da tela.

A fórmula que scaleFontSize() segue multiplica a largura ou altura da tela por scaleUnit, e adiciona a isso o fontSize passado no primeiro parâmetro.

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

Por exemplo, no snippet abaixo usa um scaleUnit valor de 0,8. Se a largura da tela for 1280px, isso resultará em um texto com tamanho de 25.24, seguindo a equação 15 + (1280 * 0.8 / 100).

📔 Nota: scaleFontSize() retorna um number, então o seu resultado é um tamanho em virtual pixels virtuais — ele ainda é multiplicado pelo UI scale factor antes de ser desenhado. No exemplo acima, com a 1920x1080 tela virtual padrão e um canvas de 1280px de largura, o fator de escala é 1280 / 1920 = 0.667, então o texto é renderizado em cerca de 16,8px. Se você quiser um tamanho de fonte medido diretamente em relação ao canvas, que ignore a tela virtual, passe uma vw/vh string diretamente para fontSize em vez disso — por exemplo 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: 'Hello world!',
      fontSize: scaleFontSize(15, 0.8)
    }}
  />
)

💡 Dica: Se você não tiver diferentes tamanhos de tela para testar, pode tentar usar o Web Explorer e redimensionar a janela em que você executa o preview. O texto se ajustará instantaneamente toda vez que você alterar a janela.

Como alternativa a scaleFontSize(), passe uma vw/vh string diretamente como o fontSize — por exemplo fontSize: '1.8vh' — que dimensiona o texto em relação ao canvas e ignora completamente o fator de escala da UI. Não não multiplique tamanhos de fonte por um fator que você calcula por conta própria a partir de UiCanvasInformation: o SDK já aplica um, veja Tamanho responsivo da UI.