> 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-pt/scenes-sdk7/ui-2d/ui_text.md).
# Texto da UI
Escreva texto em UI entities.
Adicione texto à sua UI criando uma `Label` entity.
Uma `Label` entity tem os seguintes campos que podem ser configurados:
* `value`: A string a exibir
* `fontSize`: O tamanho do texto, como um número.
> OBS.: O `fontSize` não é afetado pelo tamanho da sua entity nem das parent entities.
* `color`: A cor do texto, como um [Color4](/creator/content-creator-pt/scenes-sdk7/fundamentos-de-conteudo-3d/color-types.md).
* `font`: A fonte a usar. Os valores suportados são:
* `'serif'`
* `'sans-serif'` *(padrão)*
* `'monospace'`
* `fontSrc`: Caminho para um `.ttf` arquivo de fonte na sua Scene, para renderizar o texto com uma fonte personalizada. `font` é usado como fallback. Veja [Fontes personalizadas](#custom-fonts).
* `textAlign`: Como o texto se alinhará com seu parent. 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. Vem ativado por padrão (`'wrap'`), para desativá-lo passe o valor `'nowrap'`.
{% hint style="warning" %}
**📔 Observação**: A `fontSize` não é afetado pelo tamanho da sua entity nem das parent entities.
{% endhint %}
Uma `Label` entity também pode ter outros componentes comuns encontrados em outros tipos de entities de UI, como `uiTransform` e `uiBackground`.
***arquivo ui.tsx:***
```ts
import { UiEntity, Label, ReactEcs } from '@dcl/sdk/react-ecs'
import { Color4 } from '@dcl/sdk/math'
export const uiMenu = () => (
)
```
***arquivo index.ts:***
```ts
import { ReactEcsRenderer } from '@dcl/sdk/react-ecs'
import { uiMenu } from './ui'
export function main() {
ReactEcsRenderer.setUiRenderer(uiMenu, { virtualWidth: 1920, virtualHeight: 1080 })
}
```
{% hint style="warning" %}
**📔 Observação**: Todos os snippets a seguir nesta página assumem que você tem um `.ts` semelhante ao acima, executando a `ReactEcsRenderer.setUiRenderer()` função.
{% endhint %}
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.
```ts
import { UiEntity, Label, ReactEcs } from '@dcl/sdk/react-ecs'
export const uiMenu = () => (
)
```
Se nenhuma `height` ou `width` estiver definida em `uiTransform` do container, o container usará o valor `auto`, que se ajusta para caber em todo o texto. Você pode definir uma `maxWidth` e uma `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 cresça demais, mesmo que o texto seja mais curto.
{% hint style="warning" %}
**📔 Observação**: Não dependa desse ajuste automático para texto. Quanto espaço uma `Label` ocupa quando você deixa seu tamanho indefinido difere entre Explorers. O Explorer baseado em Bevy mede o texto renderizado e o organiza de acordo. O Explorer da Unity quase não lhe dá altura, mas ainda desenha as letras, então labels empilhados acabam um sobre o outro e um parent dimensionado a partir do texto colapsa para nada.
Dê a cada `Label` uma altura explícita `width` **e** `height` na sua `uiTransform`, e dê uma altura explícita a qualquer container que empilhe labels. Para texto com quebra de linha, ajuste a altura para o número de linhas: duas linhas com `fontSize: 20` precisa de cerca de `height: 60`.
Como isso difere por Explorer, um preview que parece correto em um client não prova que o layout está correto em outro.
{% endhint %}
## Fontes personalizadas
Para renderizar um `Label` com sua própria fonte, adicione um arquivo de fonte TrueType (`.ttf`) à pasta da sua Scene e defina a `fontSrc` propriedade para o caminho dele, relativo à pasta raiz da Scene. Mantenha `font` definido também: ele é o fallback usado sempre que a fonte personalizada não puder ser carregada.
{% hint style="warning" %}
**📔 Observação**: `fontSrc` requer uma versão do SDK mais חדשה que 7.30.1. Na 7.30.1 e anteriores, a propriedade não existe.
{% endhint %}
```tsx
```
O `Button` entity, o `uiText` de uma `UiEntity` e as [`Input` e `Dropdown`](/creator/content-creator-pt/scenes-sdk7/ui-2d/ui_special_types.md) entities também aceitam `fontSrc` também, e o mesmo acontece com o [`TextShape`](/creator/content-creator-pt/scenes-sdk7/fundamentos-de-conteudo-3d/text.md#custom-fonts) componente para texto no espaço 3D.
Tenha o seguinte em mente ao usar fontes personalizadas:
* **Apenas `.ttf` arquivos são suportados**. Fontes OpenType com contornos CFF (geralmente `.otf`), coleções de fontes e web fonts são rejeitadas, e o texto é renderizado com o fallback `font`.
* **A fonte deve ser um arquivo na sua Scene**. `fontSrc` não pode apontar para uma URL externa, e nomes de família de fonte (por exemplo, do Google Fonts) também não são suportados. Faça download do `.ttf` arquivo e inclua-o na pasta da sua Scene. Certifique-se de que sua licença permite a redistribuição.
* **No Desktop Client, as fontes personalizadas só aparecem quando os assets da Scene são otimizados**. Quando você publica uma Scene, suas fontes são convertidas em pacotes de assets otimizados junto com seus modelos 3D, e a fonte personalizada aparece assim que essa conversão é concluída. Até lá, o texto usa o fallback `font`. O mesmo se aplica a previews locais: a fonte personalizada só aparece ao fazer preview com assets otimizados (a **Compress Assets** opção no Creator Hub, ou `npm run start -- --asset-bundles` da CLI). Veja [pré-visualização com assets otimizados](/creator/content-creator-pt/scenes-sdk7/primeiros-passos/preview-scene.md#preview-with-optimized-assets). O client web da Bevy carrega o `.ttf` arquivo diretamente, então ali a fonte personalizada aparece na hora, inclusive em previews locais.
* **Não suportado em mobile**. O app mobile da Decentraland ignora `fontSrc` e renderiza o fallback `font`. Escolha um fallback que ainda fique bom e não dependa da fonte personalizada para fazer o texto caber em um espaço fixo. Veja [Recursos ausentes no mobile](/creator/content-creator-pt/criar-para-mobile/cliente-movel/missing-features.md).
* **Caracteres que a fonte não inclui** são desenhados com a fonte sans-serif integrada. Caracteres não latinos que a fonte inclui são renderizados na primeira vez em que aparecem, o que pode causar uma pequena travada.
Para a lista completa de limites, como o tamanho máximo do arquivo, veja [Fontes personalizadas](/creator/content-creator-pt/scenes-sdk7/fundamentos-de-conteudo-3d/text.md#custom-fonts) na página Text.
## Não use emoji no texto da UI
Não inclua emoji em nenhuma `Label` ou `Button` `value`, `uiText.value`, `Input` `opção de placeholder`, e `Dropdown` .
O SDK não inclui glifos de emoji. Se um emoji aparece ou não depende das fontes que cada Explorer inclui, e o Explorer da Unity não tem nenhuma, então o caractere sai como uma caixa vazia ou desaparece por completo. A mesma cautela se aplica a outros Unicode decorativos, como setas e caracteres de desenho de caixas.
Para um rótulo pictórico, envie a arte em vez disso: coloque uma imagem em um pequeno `UiEntity` ao lado do texto, usando uma `uiBackground` com uma `textura`. Veja [Fundos de UI](/creator/content-creator-pt/scenes-sdk7/ui-2d/ui_background.md).
```ts
import { UiEntity, ReactEcs } from '@dcl/sdk/react-ecs'
import { Color4 } from '@dcl/sdk/math'
export const uiMenu = () => (
)
```
## 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 essa função em vez de um único número.
```ts
import { scaleFontSize } from '@dcl/sdk/react-ecs'
import { UiEntity, ReactEcs } from '@dcl/sdk/react-ecs'
import { Color4 } from '@dcl/sdk/math'
export const uiMenu = () => (
)
```
O `scaleFontSize()` função requer dois parâmetros:
* `fontSize`: O tamanho base da fonte a usar.
* `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 de quanto adaptar. Padrão: `0.39` (um número, então ele é interpretado como relativo a *width*). Os valores podem ser:
* *Número*: Um número simples, neste caso ele é interpretado como relativo a *width*
* *String que termina em **vw***: Isso torna o número relativo à largura da visualização. Por exemplo `"0.8vw"`
* *String que termina em **vh***: Isso torna o número relativo à altura da visualização. Por exemplo `"0.8vh"`
{% hint style="info" %}
**💡 Dica**: Esta função funciona de forma semelhante ao CSS `calc()` função.
{% endhint %}
O valor de `scaleUnit` é uma porcentagem da largura ou altura da janela. Então 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 pelo `scaleUnit`, e soma a isso o `fontSize` passado no primeiro parâmetro.
```ts
final font = fontSize + (screen width * scaleUnit / 100)
```
Por exemplo, no snippet abaixo é usado um `scaleUnit` valor de 0,8. Se a largura da tela for *1280px*, isso resultará em texto com tamanho de **25.24**, seguindo a equação `15 + (1280 * 0.8 / 100)`.
{% hint style="warning" %}
**📔 Observação**: `scaleFontSize()` retorna um **número**, então o resultado é um tamanho em *pixels virtuais* — ainda é multiplicado pelo [fator de escala da UI](/creator/content-creator-pt/scenes-sdk7/ui-2d/onscreen-ui.md#screen-virtual-scale) antes de ser desenhado. `1920x1080` virtual screen e uma canvas de 1280px, o fator de escala é `1280 / 1920 = 0.667`, então o texto é renderizado com cerca de 16,8px. Se você quiser um tamanho de fonte medido diretamente em relação ao canvas, ignorando a tela virtual, passe uma `vw`/`vh` **string** diretamente para `fontSize` em vez disso — por exemplo `fontSize: '1.8vh'`.
{% endhint %}
```ts
import { scaleFontSize } from '@dcl/sdk/react-ecs'
import { UiEntity, ReactEcs } from '@dcl/sdk/react-ecs'
export const uiMenu = () => (
)
```
{% hint style="info" %}
**💡 Dica**: Se você não tiver diferentes tamanhos de tela para testar, pode tentar usar o Web Explorer e redimensionar a janela onde você executa o preview. O texto se ajustará instantaneamente toda vez que você alterar a janela.
{% endhint %}
Como alternativa a `scaleFontSize()`, passe uma `vw`/`vh` string diretamente como o `fontSize` — por exemplo `fontSize: '1.8vh'` — o que dimensiona o texto em relação ao canvas e ignora completamente o fator de escala da UI. Não **não** multiplique os tamanhos da fonte por um fator calculado por você a partir de `UiCanvasInformation`: o SDK já aplica um, veja [Tamanho responsivo da UI](/creator/content-creator-pt/scenes-sdk7/ui-2d/ui-positioning.md#responsive-ui-size).
---
# 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-pt/scenes-sdk7/ui-2d/ui_text.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.