Attention: Here be dragons

This is the latest (unstable) version of this documentation, which may document features not available in or compatible with released stable versions of Godot.

Checking the stable version of the documentation...

BBCode em RichTextLabel

Introdução

Nós de Label são ótimos para exibir texto básico, mas possuem limitações. Se você quiser alterar a cor do texto ou seu alinhamento, só pode fazer isso para o rótulo inteiro. Você não pode fazer com que parte do texto tenha outra cor, ou que parte do texto seja centralizada. Para contornar essas limitações, você deve usar um RichTextLabel.

RichTextLabel allows for complex formatting of text using a markup syntax or the built-in API. It uses BBCodes for the markup syntax, a system of tags that designate formatting rules for a part of the text. You may be familiar with them if you ever used forums (also known as bulletin boards, hence the "BB" in "BBCode").

Ao contrário do Label, o RichTextLabel também vem com sua própria barra de rolagem vertical. Essa barra de rolagem é exibida automaticamente se o texto não couber no tamanho do controle. A barra de rolagem pode ser desativada desmarcando a propriedade Scroll Active no inspetor do RichTextLabel.

Observe que as tags BBCode também podem ser usadas, até certo ponto, para outros casos de uso:

• BBCode pode ser usado para formatar comentários na fonte XML da referência de classe.

• O BBCode pode ser usado em comentários de documentação do GDScript.

• O BBCode pode ser usado ao imprimir texto rico no painel inferior Output.

Ver também

Você pode ver como o BBCode no RichTextLabel funciona na prática usando o projeto de demonstração Rich Text Label com BBCode.

Usando BBCode

Por padrão, o RichTextLabel funciona como um Label normal. Ele possui a propriedade text, que você pode editar para ter um texto formatado uniformemente. Para poder usar BBCode para formatação de texto rico, você precisa ativar o modo BBCode definindo bbcode_enabled. Depois disso, você pode editar a propriedade text usando as tags disponíveis. Ambas as propriedades estão localizadas no topo do inspetor após selecionar um nó RichTextLabel.

Por exemplo, BBCode [color=green]teste[/color] renderizaria a palavra "teste" com uma cor verde.

A maioria dos BBCodes consiste em 3 partes: a tag de abertura, o conteúdo e a tag de fechamento. A tag de abertura delimita o início da parte formatada e também pode conter algumas opções de configuração. Algumas tags de abertura, como a de color mostrada acima, também exigem um valor para funcionar. Outras tags de abertura podem aceitar múltiplas opções (separadas por espaços dentro da tag de abertura). A tag de fechamento delimita o fim da parte formatada. Em alguns casos, tanto a tag de fechamento quanto o conteúdo podem ser omitidos.

Ao contrário do BBCode em HTML, os espaços em branco no início/fim não são removidos por um RichTextLabel ao serem exibidos. Espaços duplicados também são exibidos como estão na saída final. Isso significa que, ao exibir um bloco de código em um RichTextLabel, você não precisa usar uma tag de texto pré-formatado.

[tag]content[/tag]
[tag=value]content[/tag]
[tag option1=value1 option2=value2]content[/tag]
[tag][/tag]
[tag]

Nota

O RichTextLabel não suporta tags BBCode entrelaçadas. Por exemplo, em vez de usar:

[b]bold[i]bold italic[/b]italic[/i]

Use:

[b]bold[i]bold italic[/i][/b][i]italic[/i]

Tratamento seguro de entrada do usuário

Em um cenário onde os usuários podem inserir texto livremente (como um chat em um jogo multiplayer), você deve garantir que os usuários não possam usar tags BBCode arbitrárias que serão processadas pelo RichTextLabel. Isso serve para evitar o uso inadequado de formatação, o que pode ser problemático se as tags [url] forem tratadas pelo seu RichTextLabel (já que os jogadores poderiam criar links clicáveis para sites de phishing ou similares).

Using RichTextLabel's [lb] and/or [rb] tags, we can replace the opening and/or closing brackets of any BBCode tag in a message with those escaped tags. This prevents users from using BBCode that will be parsed as tags – instead, the BBCode will be displayed as text.

Exemplo de entrada de usuário não escapada resultando em injeção de BBCode (2ª linha) e entrada de usuário escapada (3ª linha)

A imagem acima foi criada utilizando o seguinte script:

extends RichTextLabel

func _ready():
    append_chat_line("Player 1", "Hello world!")
    append_chat_line("Player 2", "Hello [color=red]BBCode injection[/color] (no escaping)!")
    append_chat_line_escaped("Player 2", "Hello [color=red]BBCode injection[/color] (with escaping)!")


# Returns escaped BBCode that won't be parsed by RichTextLabel as tags.
func escape_bbcode(bbcode_text):
    # We only need to replace opening brackets to prevent tags from being parsed.
    return bbcode_text.replace("[", "[lb]")


# Appends the user's message as-is, without escaping. This is dangerous!
func append_chat_line(username, message):
    append_text("%s: [color=green]%s[/color]\n" % [username, message])


# Appends the user's message with escaping.
# Remember to escape both the player name and message contents.
func append_chat_line_escaped(username, message):
    append_text("%s: [color=green]%s[/color]\n" % [escape_bbcode(username), escape_bbcode(message)])

Removendo tags BBCode

Para certos casos de uso, pode ser desejável remover as tags BBCode da string. Isso é útil ao exibir o texto do RichTextLabel em outro Control que não suporta BBCode (como um tooltip):

extends RichTextLabel

func _ready():
    var regex = RegEx.new()
    regex.compile("\\[.*?\\]")
    var text_without_tags = regex.sub(text, "", true)
    # `text_without_tags` contains the text with all BBCode tags removed.

Nota

Remover as tags BBCode completamente não é recomendado para entradas de usuário, pois isso pode modificar o texto exibido sem que os usuários entendam o motivo de parte de sua mensagem ter sido removida. O método de escapar a entrada do usuário deve ser preferido.

Desempenho

Na maioria dos casos, você pode usar o BBCode diretamente como está, já que a formatação de texto raramente é uma tarefa pesada. No entanto, com RichTextLabels particularmente grandes (como logs de console que abrangem milhares de linhas), você pode encontrar travamentos (stuttering) durante o jogo quando o texto do RichTextLabel é atualizado.

Existem várias maneiras de aliviar isso:

• Use a função append_text() em vez de concatenar diretamente na propriedade text. Essa função processará o BBCode apenas para o texto adicionado, em vez de reprocessar o BBCode de toda a propriedade text.

• Use as funções push_[tag]() e pop() para adicionar tags ao RichTextLabel em vez de usar BBCode por texto.

• Ative a propriedade Threading > Threaded no RichTextLabel. Isso não acelerará o processamento, mas evitará o bloqueio da thread principal, o que elimina os travamentos durante o jogo. Ative o threading apenas se for realmente necessário no seu projeto, pois ele possui uma sobrecarga (overhead).

Usando as funções push_[tag]() e pop() em vez de BBCode

Se você não quiser usar BBCode por motivos de desempenho, pode utilizar as funções fornecidas pelo RichTextLabel para criar tags de formatação sem escrever BBCode no texto.

Cada tag BBCode (incluindo efeitos) possui uma função push_[tag]() (onde [tag] é o nome da tag). Também existem algumas funções de conveniência disponíveis, como push_bold_italics(), que combina tanto push_bold() quanto push_italics() em uma única tag. Consulte a referência da classe RichTextLabel para uma lista completa das funções push_[tag]().

A função pop() é usada para encerrar qualquer tag. Como o BBCode funciona como uma pilha (stack) de tags, o uso de pop() fechará as tags iniciadas mais recentemente primeiro.

O script a seguir resultará na mesma saída visual que usar BBCode [color=green]test [i]example[/i][/color]:

extends RichTextLabel

func _ready():
    append_text("BBCode ")  # Trailing space separates words from each other.
    push_color(Color.GREEN)
    append_text("test ")  # Trailing space separates words from each other.
    push_italics()
    append_text("example")
    pop()  # Ends the tag opened by `push_italics()`.
    pop()  # Ends the tag opened by `push_color()`.

Aviso

Não defina a propriedade text diretamente ao usar funções de formatação. Concatenar strings diretamente na propriedade text apagará todas as modificações feitas no RichTextLabel usando as funções append_text(), push_[tag]() e pop().

Referência

Ver também

Algumas dessas tags BBCode podem ser usadas em dicas de ferramentas (tooltips) para variáveis de script @export, bem como na fonte XML da referência de classe. Para mais informações, veja Referência de classe BBCode.

Etiqueta	Exemplo
b Faz com que {text} use a fonte em negrito (ou negrito itálico) do RichTextLabel.	[b]{text}[/b]
i Faz com que {text} use a fonte em itálico (ou negrito itálico) do RichTextLabel.	[i]{text}[/i]
u Faz com que {text} fique sublinhado.	[u]{text}[/u] [u color={color}]{text}[/u]
s Faz com que {text} fique tachado.	[s]{text}[/s] [s color={color}]{text}[/s]
código Faz com que {text} use a fonte mono do RichTextLabel.	[code]{text}[/code]
char Adiciona um caractere Unicode com o codepoint UTF-32 hexadecimal {codepoint}.	[char={codepoint}]
p Adiciona um novo parágrafo com {text}. Suporta opções de configuração, veja Opções de parágrafo.	[p]{text}[/p] [p {options}]{text}[/p]
br Adiciona uma quebra de linha no texto, sem criar un novo parágrafo. Se usado dentro de uma lista, isso não criará um novo item de lista, mas adicionará uma quebra de linha dentro do item atual.	[br]
hr Adiciona uma nova linha horizontal para separar o conteúdo. Suporta opções de configuração, veja Opções de regra horizontal.	[hr] [hr {options}]
centralizado Faz com que {text} fique centralizado horizontalmente. O mesmo que [p align=center].	[center]{text}[/center]
left Faz com que {text} fique alinhado à esquerda horizontalmente. O mesmo que [p align=left].	[left]{text}[/left]
direita Faz com que {text} fique alinhado à direita horizontalmente. O mesmo que [p align=right].	[right]{text}[/right]
preencher Faz com que {text} preencha toda a largura do RichTextLabel. O mesmo que [p align=fill].	[fill]{text}[/fill]
recuo Aplica recuo (indentação) ao {text} uma vez. A largura do recuo é a mesma que em [ul] ou [ol], mas sem o marcador de ponto.	[indent]{text}[/indent]
url Cria um hyperlink (texto sublinhado e clicável). Pode conter um {text} opcional ou exibir o {link} como está. Suporta opções de configuração, veja Opções de URL. Deve ser tratado com o sinal "meta_clicked" para ter efeito, veja Lidando com cliques de tags [url].	[url]{link}[/url] [url={link}]{text}[/url] [url {options}]{text}[/url]
hint Cria uma dica (tooltip hint) que é exibida ao passar o mouse sobre o texto. Embora não seja obrigatório, recomenda-se colocar o texto da dica entre aspas duplas ou simples. Note que não é possível escapar aspas usando \" ou \'. Para usar aspas simples como apóstrofos na string da dica, você deve usar aspas duplas para envolver a string inteira.	[hint='{texto da dica exibido ao passar o mouse}']{text}[/hint]
img Insere uma imagem a partir do caminho {path} (pode ser qualquer recurso Texture2D válido). Se {width} for fornecido, a imagem tentará se ajustar a essa largura mantendo a proporção de aspecto. Se ambos {width} e {height} forem fornecidos, a imagem será redimensionada para esse tamanho. Adicione % ao final do valor de {width} ou {height} para especificá-lo como uma porcentagem da largura do controle em vez de pixels. Adicione em ao final do valor de {width} ou {height} para especificá-lo como uma proporção do tamanho atual da fonte. Por exemplo, height=1em tornará a imagem tão alta quanto o texto ao redor. Se a configuração {valign} for fornecida, a imagem tentará se alinhar ao texto ao redor, veja Alinhamento vertical de imagem e tabela. Suporta opções de configuração, veja Opções de imagem.	[img]{caminho}[/img] [img={width}]{path}[/img] [img={width}x{height}]{path}[/img] [img={valign}]{path}[/img] [img {options}]{path}[/img]
fonte Faz com que {text} use um recurso de fonte do caminho {path}. Suporta opções de configuração, veja Opções de fonte.	[font={path}]{text}[/font] [font {options}]{text}[/font]
font_size Use tamanho de fonte personalizado para {text}.	[font_size={size}]{text}[/font_size]
dropcap Usa um tamanho de fonte e cor diferentes para {text}, fazendo com que o conteúdo da tag ocupe várias linhas se for grande o suficiente. Uma capitular (drop cap) é tipicamente um único caractere maiúsculo, mas a tag [dropcap] suporta conter múltiplos caracteres. Os valores de margins são separados por vírgulas e podem ser positivos, zero ou negativos. Os valores não devem ser separados por espaços; caso contrário, não serão processados corretamente. Margens superiores e inferiores negativas são particularmente úteis para permitir que o restante do parágrafo seja exibido abaixo da capitular.	[dropcap font={font} font_size={size} color={color} outline_size={size} outline_color={color} margins={left},{top},{right},{bottom}]{text}[/dropcap]
opentype_features Ativa recursos de fonte OpenType personalizados para {text}. Os recursos devem ser fornecidos como uma lista {list} separada por vírgulas. Os valores não devem ser separados por espaços; caso contrário, a lista não será processada corretamente.	[opentype_features={list}] {text} [/opentype_features]
lang Substitui o idioma do {text} que foi definido pela propriedade BiDi > Language no RichTextLabel. {code} deve ser um código de idioma ISO. Isso pode ser usado para forçar o uso de uma escrita específica para um idioma sem iniciar um novo parágrafo. Alguns arquivos de fonte podem conter substitutos específicos para a escrita e, nesses casos, eles serão utilizados.	[lang={code}]{text}[/lang]
cor Altera a cor do {text}. A cor deve ser fornecida por um nome comum (veja Cores nomeadas) ou usando o formato HEX (ex: #ff00ff, veja Códigos de cores hexadecimais).	[color={code/name}]{text}[/color]
bgcolor Desenha a cor atrás do {text}. Isso pode ser usado para destacar o texto. Aceita os mesmos valores que a tag color. Por padrão, há um pequeno preenchimento (padding) que é controlado pelos itens de tema text_highlight_h_padding e text_highlight_v_padding no nó RichTextLabel. Defina o preenchimento para 0 para evitar potenciais problemas de sobreposição quando houver cores de fundo em linhas/colunas vizinhas.	[bgcolor={code/name}]{text}[/bgcolor]
fgcolor Desenha a cor à frente do {text}. Isso pode ser usado para "censurar" ou ocultar o texto usando uma cor de primeiro plano opaca. Aceita os mesmos valores que a tag color. Por padrão, há um pequeno preenchimento que é controlado pelos itens de tema text_highlight_h_padding e text_highlight_v_padding no nó RichTextLabel. Defina o preenchimento para 0 para evitar potenciais problemas de sobreposição quando houver cores de primeiro plano em linhas/colunas vizinhas.	[fgcolor={code/name}]{text}[/fgcolor]
outline_size Use tamanho de contorno de fonte personalizado para {text}.	[outline_size={size}] {text} [/outline_size]
outline_color Usa uma cor de contorno personalizada para {text}. Aceita os mesmos valores que a tag color.	[outline_color={code/name}] {text} [/outline_color]
tabela Cria uma tabela com o número {number} de colunas. Use a tag cell para definir as células da tabela. Se a configuração {valign} for fornecida, a tabela tentará se alinhar ao texto ao redor, veja Alinhamento vertical de imagem e tabela. Se o alinhamento pela linha de base (baseline) for usado, a tabela será alinhada à linha de base da linha com o índice {alignment_row} (baseado em zero). {name} é o nome da tabela para aplicativos de acessibilidade (leitores de tela).	[table={number}]{cells}[/table] [table={number},{valign}]{cells}[/table] [table={number},{valign},{alignment_row}]{cells}[/table] [table={number},{valign},{alignment_row} name={name}]{cells}[/table]
célula Adiciona uma célula com {text} à tabela. Se {ratio} for fornecido, a célula tentará se expandir para esse valor proporcionalmente às outras células e seus valores de proporção. Suporta opções de configuração, veja Opções de célula.	[cell]{texto}[/cell] [cell={ratio}]{text}[/cell] [cell {options}]{text}[/cell]
ul Adiciona uma lista não ordenada. Os itens da lista {items} devem ser fornecidos colocando um item por linha de texto. O marcador de ponto pode ser personalizado usando o parâmetro {bullet}, veja Marcador de lista não ordenada.	[ul]{items}[/ul] [ul bullet={bullet}]{items}[/ul]
ol Adiciona uma lista ordenada (numerada) do tipo {type} fornecido (veja Tipos de lista ordenada). Os itens da lista {items} devem ser fornecidos colocando um item por linha de texto.	[ol type={type}]{items}[/ol]
lb, rb Adiciona [ e ] respectivamente. Permite escapar a marcação BBCode. Estas são tags de fechamento automático (self-closing), o que significa que você não precisa fechá-las (e não existe uma tag de fechamento [/lb] ou [/rb]).	[lb]b[rb]text[lb]/b[rb] será exibido como [b]text[/b].
Vários caracteres de controle Unicode podem ser adicionados usando suas próprias tags de fechamento automático. Isso pode resultar em uma manutenção mais fácil em comparação com colar esses caracteres de controle diretamente no texto.	[lrm] (marcação esquerda para direita), [rlm] (marcação direita para esquerda), [lre] (incorporação esquerda para direita), [rle] (incorporação direita para esquerda), [lro] (sobreposição esquerda para direita), [rlo] (sobreposição direita para esquerda), [pdf] (encerrar formatação direcional), [alm] (marcação de letra árabe), [lri] (isolamento esquerda para direita), [rli] (isolamento direita para esquerda), [fsi] (isolamento de primeira forte), [pdi] (encerrar isolamento direcional), [zwj] (conector de largura zero), [zwnj] (não-conector de largura zero), [wj] (conector de palavra), [shy] (hífen suave)

Nota

As tags para formatação em negrito ([b]) e itálico ([i]) funcionam melhor se as fontes personalizadas apropriadas forem configuradas nas sobreposições de tema do nó RichTextLabel. Se nenhuma fonte personalizada em negrito ou itálico for definida, fontes falsas em negrito e itálico (faux bold and italic fonts) serão geradas pelo Godot. Essas fontes raramente têm uma boa aparência em comparação com variantes de fontes em negrito/itálico feitas à mão.

A tag monoespaçada ([code]) apenas funciona se uma fonte personalizada estiver configurada nas sobreposições de tema do nó RichTextLabel. Caso contrário, o texto monoespaçado usará a fonte padrão.

Ainda não há tags BBCode para controlar a centralização vertical do texto.

As opções podem ser omitidas para todas as tags.

Opções de parágrafo

• align

  Values	left (ou l), center (or c), right (or r), fill (or f)
  Default	left

  Alinhamento horizontal do texto.

• bidi_override, st

  Values	default (ou d), uri (ou u), file (ou f), email (ou e), list (ou l), none (ou n), custom (ou c)
  Default	default

  Substituição de texto estruturado.

• justification_flags, jst

  Values	Comma-separated list of the following values (no space after each comma): kashida (or k), word (or w), trim (or tr), after_last_tab (or lt), skip_last (or sl), skip_last_with_chars (or sv), do_not_skip_single (or ns).
  Default	word,kashida,skip_last,do_not_skip_single

  Opção de justificativa (alinhamento preenchido). Veja TextServer para mais detalhes.

• direction, dir

  Values	ltr (ou l), rtl (ou r), auto (ou a)
  Default	Herdar

  Direção base BiDi.

• language, lang

  Values	Códigos de idioma ISO. Veja Códigos de localidade
  Default	Herdar

  Substituição de localidade (locale). Alguns arquivos de fonte podem conter substitutos específicos para a escrita e, nesses casos, eles serão utilizados.

• tab_stops

  Values	Lista de números de ponto flutuante, ex: 10.0,30.0
  Default	Largura do caractere de espaço na fonte

  Substitui os deslocamentos horizontais para cada caractere de tabulação. Quando o fim da lista é alcançado, as paradas de tabulação se repetem em loop. Por exemplo, se você definir tab_stops para 10.0,30.0, a primeira tabulação estará a 10 pixels, a segunda estará a 10 + 30 = 40 pixels e a terceira estará a 10 + 30 + 10 = 50 pixels a partir da origem do RichTextLabel.

Lidando com cliques de tags [url]

Por padrão, as tags [url] não fazem nada quando clicadas. Isso é para permitir o uso flexível de tags [url] em vez de limitá-los a abrir URLs em um navegador da web.

Para lidar com tags [url] clicadas, conecte o sinal meta_clicked do nó RichTextLabel a uma função de script.

Por exemplo, o seguinte método pode ser conectado a meta_clicked para abrir URLs clicadas usando o navegador da web padrão do usuário:

# This assumes RichTextLabel's `meta_clicked` signal was connected to
# the function below using the signal connection dialog.
func _richtextlabel_on_meta_clicked(meta):
    # `meta` is not guaranteed to be a String, so convert it to a String
    # to avoid script errors at runtime.
    OS.shell_open(str(meta))

Para casos de uso mais avançados, também é possível armazenar JSON na opção de uma tag [url] e analisá-lo na função que trata o sinal meta_clicked. Por exemplo:

[url={"example": "value"}]JSON[/url]

Opções de regra horizontal

• cor

  Values	Nome da cor ou cor no formato HEX
  Default	Color(1, 1, 1, 1)

  Tonalidade de cor da linha (modulação).

• height

  Values	Número inteiro
  Default	2

  Altura alvo da linha em pixels, adicione % ao final do valor para especificá-la como porcentagem da largura do controle no lugar de pixels.

• width

  Values	Número inteiro
  Default	90%

  Largura alvo da linha em pixels, adicione % ao final do valor para especificá-la como porcentagem da largura do controle no lugar de pixels.

• align

  Values	left (ou l), center (ou c), right (ou r)
  Default	center

  Alinhamento horizontal.

Opções de URL

• underline

  Values	always, never, hover
  Default	always

  Modo de sublinhado de URL.

• tooltip

  Values	String (linha).
  Default

  Dica de ferramenta (tooltip) de URL.

• href

  Values	String (linha).
  Default

  Endereço de destino da URL.

Opções de imagem

• cor

  Values	Nome da cor ou cor no formato HEX
  Default	Herdar

  Tonalidade de cor da imagem (modulação).

• height

  Values	Número de ponto flutuante
  Default	Herdar

  Altura alvo da imagem em pixels.

  Unidades alternativas aos pixels podem ser especificadas:

  • Adicione % ao final do valor para especificá-lo como uma porcentagem da largura do controle em vez de pixels. Por exemplo, height=50% tornará a imagem metade da altura em relação à largura do controle.

  • Adicione em ao final do valor para especificá-lo como uma proporção do tamanho da fonte ao redor no lugar de pixels. Por exemplo, height=1em tornará a imagem tão alta quanto o texto ao redor.

• width

  Values	Número de ponto flutuante
  Default	Herdar

  Largura alvo da imagem in pixels.

  Unidades alternativas aos pixels podem ser especificadas:

  • Adicione % ao final do valor para especificá-lo como uma porcentagem da largura do controle em vez de pixels. Por exemplo, width=50% fará com que a imagem ocupe metade da largura do controle.

  • Adicione em ao final do valor para especificá-lo como uma proporção do tamanho da fonte ao redor no lugar de pixels. Por exemplo, width=1em tornará a imagem tão larga quanto a altura do texto ao redor.

• region

  Values	x,y,width,height em pixels
  Default	Herdar

  Retângulo de região (region rect) da imagem. Isso pode ser usado para exibir uma única imagem de um spritesheet.

• pad

  Values	false, true
  Default	false

  Se definido como true, e a imagem for menor que o tamanho especificado por width e height, o preenchimento da imagem é adicionai para corresponder ao tamanho em vez de realizar o redimensionamento (upscale).

• tooltip

  Values	String
  Default

  Dica de ferramenta (tooltip) de imagem.

• align

  Values	veja Alinhamento vertical de imagem e tabela
  Default	center,center

  Alinhamento da imagem em relação ao texto ao redor.

• alt

  Values	String
  Default

  Descrição da imagem para aplicativos de acessibilidade (leitor de tela).

Alinhamento vertical de imagem e tabela

Quando um valor de alinhamento vertical é fornecido com a tag [img] ou [table], a imagem/tabela tentará se alinhar com o texto ao redor. O alinhamento é realizado usando um ponto vertical da imagem e um ponto vertical do texto. Existem 3 pontos possíveis na imagem (top, center e bottom) e 4 pontos possíveis no texto e na tabela (top, center, baseline e bottom), que podem ser usados em qualquer combinação.

Para especificar ambos os pontos, use seus nomes completos ou curtos como o valor da tag de imagem/tabela:

text [img=top,bottom]...[/img] text
text [img=center,center]...[/img] text

text [table=3,center]...[/table] text  # Center to center.
text [table=3,top,bottom]...[/table] text # Top of the table to the bottom of text.
text [table=3,baseline,baseline,1]...[/table] text # Baseline of the second row (rows use zero-based indexing) to the baseline of text.

Você também pode especificar apenas um valor (top, center ou bottom) para utilizar um preset correspondente (top-top, center-center e bottom-bottom respectivamente).

Os nomes curtos para os valores são t (top), c (center), l (baseline) e b (bottom).

Opções de fonte

• name, n

  Values	Um caminho de recurso de Fonte válido.
  Default	Herdar

  Caminho do recurso de fonte.

• size, s

  Values	Número em pixels.
  Default	Herdar

  Tamanho de fonte personalizado.

• glyph_spacing, gl

  Values	Número em pixels.
  Default	Herdar

  Espaçamento extra para cada glifo.

• space_spacing, sp

  Values	Número em pixels.
  Default	Herdar

  Espaçamento extra para o caractere de espaço.

• top_spacing, top

  Values	Número em pixels.
  Default	Herdar

  Espaçamento extra no topo da linha.

• bottom_spacing, bt

  Values	Número em pixels.
  Default	Herdar

  Espaçamento extra na parte inferior da linha.

• embolden, emb

  Values	Número de ponto flutuante.
  Default	0.0

  Intensidade do efeito de negrito na fonte; se não for igual a zero, torna os contornos da fonte mais espessos. Valores negativos reduzem a espessura do contorno.

• face_index, fi

  Values	Número inteiro.
  Default	0

  Um índice de face ativo na coleção TrueType / OpenType.

• slant, sln

  Values	Número de ponto flutuante.
  Default	0.0

  Intensidade da inclinação da fonte; valores positivos inclinam os glifos para a direita. Valores negativos inclinam para a esquerda.

• opentype_variation, otv

  Values	Lista de tags de variação OpenType separadas por vírgulas (sem espaço após cada vírgula).
  Default

  Coordenadas de variação OpenType da fonte. Veja OpenType variation tags.

  Nota: O valor deve ser envolvido por " para permitir o uso de = dentro dele:

[font otv="wght=200,wdth=400"] # Sets variable font weight and width.

• opentype_features, otf

  Values	Lista de tags de recursos OpenType separadas por vírgulas (sem espaço após cada vírgula).
  Default

  Recursos OpenType da fonte. Veja OpenType features tags.

  Nota: O valor deve ser envolvido por " para permitir o uso de = dentro dele:

[font otf="calt=0,zero=1"] # Disable contextual alternates, enable slashed zero.

Cores nomeadas

For tags that allow specifying a color by name, you can use names of the constants from the built-in Color class. Named colors can be specified in a number of styles using different casings: DARK_RED, DarkRed, and darkred will give the same exact result.

Veja esta imagem para uma lista de constantes de cores:

Ver em tamanho completo

Códigos de cores hexadecimais

Para cores RGB opacas, qualquer código hexadecimal de 6 dígitos válido é suportado, por exemplo, [color=#ffffff]white[/color]. Códigos de cores RGB abreviados, como #6f2 (equivalente a #66ff22), também são suportados.

Para cores RGB transparentes, qualquer código hexadecimal RGBA de 8 dígitos pode ser usado, por exemplo, [color=#ffffff88]translucent white[/color]. Observe que o canal alfa é o último componente do código de cor, não o primeiro. Códigos de cores RGBA curtos, como #6f28 (equivalente a #66ff2288), também são suportados.

Opções de célula

• shrink

  Values	false, true
  Default	true

  Se definido como true, a célula pode encolher para se ajustar ao seu conteúdo.

• expand

  Values	Número inteiro
  Default	1

  Proporção de expansão da célula. Isso define quais células tentarão se expandir proporcionalmente às outras células e suas respectivas proporções de expansão.

• border

  Values	Nome da cor ou cor no formato HEX
  Default	Herdar

  Cor da borda da célula.

• bg

  Values	Nome da cor ou cor no formato HEX
  Default	Herdar

  Cor de fundo da célula. For alternating odd/even row backgrounds, você pode usar bg=odd_color,even_color.

• padding

  Values	4 números de ponto flutuante separados por vírgula (sem espaço após cada vírgula)
  Default	0,0,0,0

  Preenchimento (padding) esquerdo, superior, direito e inferior da célula.

Marcador de lista não ordenada

Por padrão, a tag [ul] usa o glifo Unicode "Bullet" U+2022 como o caractere de marcador. Esse comportamento é semelhante ao dos navegadores web. O caractere de marcador pode ser personalizado usando [ul bullet={bullet}]. Se fornecido, este parâmetro {bullet} deve ser uma string sem aspas envolventes (por exemplo, [bullet=*]). Você pode adicionar espaços adicionais após o caractere de marcador para aumentar o espaçamento entre o marcador e o texto do item da lista.

Veja Bullet (typography) na Wikipedia para uma lista de caracteres de marcadores comuns que você pode colar diretamente no parâmetro bullet.

Tipos de lista ordenada

As listas ordenadas podem ser usadas para marcar itens automaticamente com números ou letras em ordem crescente. Esta tag suporta as seguintes opções de tipo:

• 1 - Números, utilizando o sistema de numeração específico do idioma, se possível.

• a, A - Letras latinas minúsculas e maiúsculas.

• i, I - Algarismos romanos minúsculos e maiúsculos.

Efeitos de texto

O BBCode também pode ser usado para criar diferentes efeitos de texto que opcionalmente podem ser animados. Vários efeitos customizáveis são fornecidos nativamente, e você pode criar facilmente os seus próprios. Por padrão, os efeitos animados serão pausados quando o SceneTree estiver pausado. Você pode alterar esse comportamento ajustando a propriedade Process > Mode do RichTextLabel.

Todos os exemplos abaixo mencionam os valores padrão para as opções no formato de tag listado.

Nota

Efeitos de texto que movem as posições dos caracteres podem fazer com que eles sejam cortados pelos limites do nó RichTextLabel.

Você pode resolver isso desativando a opção Control > Layout > Clip Contents no inspetor após selecionar o nó RichTextLabel, ou garantindo que haja margem suficiente adicionada ao redor do texto usando quebras de linha acima e abaixo da linha que utiliza o efeito.

Pulso

Pulse cria um efeito de pulsação animada que multiplica a opacidade e a cor de cada caractere. Pode ser usado para chamar a atenção para um texto específico. Seu formato de tag é [pulse freq=1.0 color=#ffffff40 ease=-2.0]{text}[/pulse].

freq controla a frequência do ciclo de meio-pulso (valores maiores são mais rápidos). Um ciclo completo de pulsação leva 2 * (1.0 / freq) segundos. color é o multiplicador de cor alvo para a oscilação. O padrão esmaece a maior parte do texto, mas não totalmente. ease é o expoente da função de atenuação (easing) a ser usado. Valores negativos fornecem atenuação de entrada e saída (in-out easing), razão pela qual o padrão é -2.0.

Onda

Wave faz o texto subir e descer. O formato da sua tag é [wave amp=50.0 freq=5.0 connected=1]{text}[/wave].

amp controla o quão alto e baixo o efeito vai, e freq controla a velocidade com que o texto sobe e desce. Um valor de freq igual a 0 resultará em nenhuma onda visível, e valores negativos de freq também não exibirão ondas. Se connected for 1 (padrão), os glifos com ligaturas serão movidos juntos. Se connected for 0, cada glifo será movido individualmente, mesmo que estejam unidos por ligaturas. Isso pode contornar certos problemas de renderização com ligaturas de fontes.

Tornado

Tornado faz o texto girar em círculo. O formato da sua tag é [tornado radius=10.0 freq=1.0 connected=1]{text}[/tornado].

radius é o raio do círculo que controla o deslocamento, freq é a velocidade com que o texto se move em círculos. Um valor de freq igual a 0 pausará a animação, enquanto um freq negativo reproduzirá a animação de trás para frente. Se connected for 1 (padrão), os glifos com ligaturas serão movidos juntos. Se connected for 0, cada glifo será movido individualmente, mesmo que estejam unidos por ligaturas. Isso pode contornar certos problemas de renderização com ligaturas de fontes.

Tremendo

O efeito Shake faz o texto tremer. O formato da sua tag é [shake rate=20.0 level=5 connected=1]{text}[/shake].

rate controla a velocidade com que o texto treme, e level controla o quão longe o texto se desloca em relação à origem. Se connected for 1 (padrão), os glifos com ligaturas serão movidos juntos. Se connected for 0, cada glifo será movido individualmente, mesmo que estejam unidos por ligaturas. Isso pode contornar certos problemas de renderização com ligaturas de fontes.

Desaparecer

O efeito Fade cria um desbotamento estático que multiplica a opacidade de cada caractere. O formato da sua tag é [fade start=4 length=14]{text}[/fade].

start controla a posição inicial do esmaecimento em relação a onde o comando de fade é inserido, length controla sobre quantos caracteres o esmaecimento deve ocorrer.

Arco-íris

Rainbow dá ao texto uma cor de arco-íris que muda ao longo do tempo. O formato da sua tag é [rainbow freq=1.0 sat=0.8 val=0.8 speed=1.0]{text}[/rainbow].

freq determina por quantas letras o arco-íris se estende antes de se repetir, sat é a saturação do arco-íris e val é o valor (brilho) do arco-íris. speed é o número de ciclos completos do arco-íris por segundo. Um valor positivo de speed reproduzirá a animação para a frente, um valor de 0 pausará a animação e um valor negativo de speed reproduzirá a animação de trás para frente.

Os contornos da fonte não são afetados pelo efeito arco-íris (eles mantêm sua cor original). As cores de fonte existentes são substituídas pelo efeito arco-íris. No entanto, as propriedades Modulate e Self Modulate do CanvasItem afetarão a aparência final do efeito arco-íris, já que a modulação multiplica suas cores finais.

Tags BBCode personalizadas e efeitos de texto

Você pode estender o tipo de recurso RichTextEffect para criar suas próprias tags BBCode personalizadas. Crie um novo arquivo de script que estenda o tipo de recurso RichTextEffect e dê ao script um class_name para que o efeito possa ser selecionado no inspetor. Adicione a anotação @tool ao seu arquivo GDScript se desejar que esses efeitos personalizados funcionem dentro do próprio editor. O RichTextLabel não precisa ter um script anexado, nem precisa estar sendo executado no modo tool. O novo efeito pode ser registrado no Inspetor adicionando-o à array Markup > Custom Effects, ou em código com o método install_effect():

Selecionando um RichTextEffect personalizado após salvar um script que estende RichTextEffect com um class_name

Aviso

Se o efeito personalizado não estiver registrado na propriedade Markup > Custom Effects do RichTextLabel, nenhum efeito ficará visível e a tag original será mantida como está.

Existe apenas uma função que você precisa estender: _process_custom_fx(char_fx). Opcionalmente, você também pode fornecer um identificador BBCode personalizado adicionando uma variável membro chamada bbcode. O código verificará a propriedade bbcode automaticamente ou usará o nome do arquivo para determinar qual deve ser a tag BBCode.

_process_custom_fx

É aqui que a lógica de cada efeito acontece, sendo chamada uma vez por glifo durante a fase de desenho (draw phase) da renderização do texto. Isso passa um objeto CharFXTransform, que contém algumas variáveis para controlar como o glifo associado é renderizado:

• outline é true se o efeito for chamado para desenhar o contorno do texto.

• range indica a que distância você está dentro de um determinado bloco de efeito personalizado, funcionando como um índice.

• elapsed_time é a quantidade total de tempo que o efeito de texto está em execução.

• visible informará se o glifo está visível ou não e também permitirá ocultar uma determinada parte do texto.

• offset é uma posição de deslocamento relativa a onde o glifo específico deveria ser renderizado em circunstâncias normais.

• color é a cor de um determinado glifo.

• glyph_index e font representam o glifo que está sendo desenhado e o recurso de dados de fonte usado para desenhá-lo.

• Por fim, env é um Dictionary de parâmetros atribuídos a um determinado efeito customizado. Você pode usar get() com um valor padrão opcional para recuperar cada parâmetro, se especificado pelo usuário. Por exemplo, [custom_fx spread=0.5 color=#FFFF00]test[/custom_fx] teria parâmetros float spread e Color color em seu dicionário env. Veja abaixo mais exemplos de uso.

A última coisa a notar sobre esta função é que é necessário retornar um valor booleano true para verificar se o efeito foi processado corretamente. Dessa forma, se houver um problema com a renderização de um determinado glifo, a renderização de efeitos customizados será totalmente interrompida até que o usuário corrija qualquer erro que tenha surgido na lógica do seu efeito customizado.

Aqui estão alguns exemplos de efeitos personalizados:

Fantasma

@tool
extends RichTextEffect
class_name RichTextGhost

# Syntax: [ghost freq=5.0 span=10.0][/ghost]

# Define the tag name.
var bbcode = "ghost"

func _process_custom_fx(char_fx):
    # Get parameters, or use the provided default value if missing.
    var speed = char_fx.env.get("freq", 5.0)
    var span = char_fx.env.get("span", 10.0)

    var alpha = sin(char_fx.elapsed_time * speed + (char_fx.range.x / span)) * 0.5 + 0.5
    char_fx.color.a = alpha
    return true

Matriz

@tool
extends RichTextEffect
class_name RichTextMatrix

# Syntax: [matrix clean=2.0 dirty=1.0 span=50][/matrix]

# Define the tag name.
var bbcode = "matrix"

# Gets TextServer for retrieving font information.
func get_text_server():
    return TextServerManager.get_primary_interface()

func _process_custom_fx(char_fx):
    # Get parameters, or use the provided default value if missing.
    var clear_time = char_fx.env.get("clean", 2.0)
    var dirty_time = char_fx.env.get("dirty", 1.0)
    var text_span = char_fx.env.get("span", 50)

    var value = get_text_server().font_get_char_from_glyph_index(char_fx.font, 1, char_fx.glyph_index)

    var matrix_time = fmod(char_fx.elapsed_time + (char_fx.range.x / float(text_span)), \
                           clear_time + dirty_time)

    matrix_time = 0.0 if matrix_time < clear_time else \
                  (matrix_time - clear_time) / dirty_time

    if matrix_time > 0.0:
        value = int(1 * matrix_time * (126 - 65))
        value %= (126 - 65)
        value += 65
    char_fx.glyph_index = get_text_server().font_get_glyph_index(char_fx.font, 1, value, 0)
    return true

Isso adicionará alguns novos comandos BBCode, que podem ser usados assim:

[center][ghost]This is a custom [matrix]effect[/matrix][/ghost] made in
[pulse freq=5.0 height=2.0][pulse color=#00FFAA freq=2.0]GDScript[/pulse][/pulse].[/center]