BBCode in RichTextLabel

Introduzione

I nodi Label sono ottimi per visualizzare testo semplice, ma sono limitati. Se desideri modificare il colore del testo o il suo allineamento, è possibile farlo solo sull'intera etichetta. Non è possibile assegnare un colore diverso a una parte del testo, né centrarla. Per aggirare queste limitazioni, puoi utilizzare un RichTextLabel.

RichTextLabel consente di formattare il testo attraverso una sintassi di markup o l'API integrata. Esso utilizza i BBCode per la sintassi di markup, un sistema di tag che determinano le regole di formattazione per una parte del testo. Potresti averli familiarità con questi tag se hai mai usato i forum, noti anche come bulletin boards (bacheche elettroniche), da cui il "BB" di "BBCode").

A differenza di Label, RichTextLabel è dotato anche di una propria barra di scorrimento verticale. Questa barra di scorrimento viene visualizzata automaticamente se il testo non rientra nelle dimensioni del controllo. La barra di scorrimento può essere disattivata disabilitando la proprietà Attiva scorrimento nell'ispettore del RichTextLabel.

Nota che i tag BBCode si possono utilizzare fino a un certo punto anche per altri casi d'uso:

• Il BBCode può essere utilizzato per formattare i commenti nel codice sorgente XML del riferimento classi.

• Il BBCode può essere utilizzato nei commenti nella documentazione GDScript.

• Il BBCode può essere utilizzato quando si stampa testo formattato nel pannello inferiore di Output.

Vedi anche

Puoi vedere come funziona il BBCode in RichTextLabel attraverso il progetto demo Rich Text Label con BBCode.

Utilizzo di BBCode

By default, RichTextLabel functions like a normal Label. It has the property_text property, which you can edit to have uniformly formatted text. To be able to use BBCode for rich text formatting, you need to turn on the BBCode mode by setting bbcode_enabled. After that, you can edit the text property using available tags. Both properties are located at the top of the inspector after selecting a RichTextLabel node.

For example, BBCode [color=green]test[/color] would render the word "test" with a green color.

Most BBCodes consist of 3 parts: the opening tag, the content and the closing tag. The opening tag delimits the start of the formatted part, and can also carry some configuration options. Some opening tags, like the color one shown above, also require a value to work. Other opening tags may accept multiple options (separated by spaces within the opening tag). The closing tag delimits the end of the formatted part. In some cases, both the closing tag and the content can be omitted.

A differenza del BBCode in HTML, gli spazi vuoti iniziali/finali non vengono rimossi da un RichTextLabel al momento della visualizzazione. Anche gli spazi duplicati vengono visualizzati così come sono nel risultato finale. Ciò significa che quando si visualizza un blocco di codice in un RichTextLabel, non è necessario utilizzare un tag di testo preformattato.

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

Nota

RichTextLabel non supporta tag BBCode intrecciati. Ad esempio, invece di usare:

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

Usa:

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

Gestione in modo sicuro dell'input utente

In a scenario where users may freely input text (such as chat in a multiplayer game), you should make sure users cannot use arbitrary BBCode tags that will be parsed by RichTextLabel. This is to avoid inappropriate use of formatting, which can be problematic if [url] tags are handled by your RichTextLabel (as players may be able to create clickable links to phishing sites or similar).

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.

Esempio di input utente senza escape, risultante nell'iniettamento di BBCode (2ª riga), e input utente con escape (3ª riga)

L'immagine precedente è stata creata attraverso il seguente 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)])

Rimozione dei tag BBCode

In alcuni casi, può essere opportuno rimuovere i tag BBCode dalla stringa. Ciò è utile quando si visualizza il testo di un RichTextLabel in un altro Control che non supporta BBCode (ad esempio, un 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

Non si consiglia di rimuovere completamente i tag BBCode per l'input utente, poiché ciò potrebbe modificare il testo visualizzato senza che l'utente capisca perché parte del messaggio è stata rimossa. Invece, si dovrebbe preferire l'escape dell'input utente.

Prestazioni

Nella maggior parte dei casi, è possibile utilizzare il BBCode direttamente così com'è, poiché la formattazione del testo raramente è un compito pesante. Tuttavia, con RichTextLabel particolarmente grandi (come i log da console che si estendono per migliaia di righe), si potrebbero verificare scatti durante il gioco quando il testo della RichTextLabel viene aggiornato.

Esistono diversi modi per alleviare questo problema:

• Utilizzare la funzione append_text() invece di aggiungere testo alla proprietà text. Questa funzione analizzerà il BBCode solo per il testo aggiunto, invece di analizzare il BBCode dall'intera proprietà text.

• Usare le funzioni push_[tag]() e pop() per aggiungere tag a RichTextLabel invece di usare BBCode.

• Enable the Threading > Threaded property in RichTextLabel. This won't speed up processing, but it will prevent the main thread from blocking, which avoids stuttering during gameplay. Only enable threading if it's actually needed in your project, as threading has some overhead.

Utilizzo delle funzioni push_[tag]() e pop() al posto del BBCode

Se per motivi di prestazioni non si desidera utilizzare il BBCode, è possibile utilizzare le funzioni fornite da RichTextLabel per creare tag di formattazione senza scrivere il BBCode nel testo.

Ogni tag BBCode (inclusi gli effetti) ha una funzione push_[tag]() (dove [tag] è il nome del tag). Sono disponibili anche alcune funzioni utili, come push_bold_italics() che combina push_bold() e push_italics() in un unico tag. Consulta la classe RichTextLabel class reference per un elenco completo delle funzioni push_[tag]().

La funzione pop() è utilizzata per terminare qualsiasi tag. Poiché il BBCode è una pila di tag, l'uso di pop() chiuderà i tag iniziati più recentemente per primi.

Lo script seguente produrrà lo stesso risultato visivo ottenuto tramite 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()`.

Avvertimento

Non impostare direttamente la proprietà text quando si utilizzano le funzioni di formattazione. Aggiungendo alla proprietà text verranno cancellate tutte le modifiche apportate al RichTextLabel tramite le funzioni append_text(), push_[tag]() e pop().

Riferimento

Vedi anche

Alcuni di questi tag BBCode si possono utilizzare nei tooltip per le variabili di script con @export e nel codice sorgente XML del riferimento classi. Per ulteriori informazioni, consulta BBCode del riferimento classi.

Tag	Esempio
b Fa in modo che {testo} utilizzi il font grassetto (o grassetto corsivo) di RichTextLabel.	[b]{testo}[/b]
i Fa in modo che {testo} utilizzi il font corsivo (o grassetto corsivo) di RichTextLabel.	[i]{testo}[/i]
u Rende {testo} sottolineato.	[u]{testo}[/u]
s Rende {testo} barrato.	[s]{testo}[/s]
code Fa in modo che {testo} utilizzi il font a spaziatura fissa di RichTextLabel.	[code]{testo}[/code]
char Aggiunge il carattere Unicode con il {codepoint} UTF-32 esadecimale.	[char={codepoint}]
p Aggiunge un nuovo paragrafo con {testo}. Supporta le opzioni di configurazione, consulta Opzioni di paragrafo.	[p]{testo}[/p] [p {opzioni}]{testo}[/p]
center Rende {testo} centrato orizzontalmente. Uguale a [p align=center].	[center]{testo}[/center]
left Rende {testo} orizzontalmente allineato a sinistra. Uguale a [p align=left].	[left]{testo}[/left]
right Rende {testo} orizzontalmente allineato a destra. Uguale a [p align=right].	[right]{testo}[/right]
fill Fa in modo che {testo} riempia l'intera larghezza di RichTextLabel. Uguale a [p align=fill].	[fill]{testo}[/fill]
indent Rientra {testo} una volta. La larghezza del rientro è la stessa di [ul] o [ol], ma senza un punto elenco.	[indent]{testo}[/indent]
url Crea un collegamento ipertestuale (testo sottolineato e cliccabile). Può contenere {testo} facoltativo o visualizzare {link} così com'è. Deve essere gestito con il segnale "meta_clicked" per avere effetto, consulta Gestione dei clic sul tag [url].	[url]{link}[/url] [url=<link>]{testo}[/url]
hint Crea un suggerimento che viene visualizzato quando si passa il mouse sul testo. Il testo del suggerimento non deve essere racchiuso tra virgolette (altrimenti, le virgolette appariranno così come sono nel tooltip).	[hint={suggerimento visualizzato al passaggio del mouse}]{testo}[/hint]
img Inserisce un'immagine dal {percorso} (può essere qualsiasi risorsa Texture2D valida). Se la {larghezza} è specificata, l'immagine cercherà di adattarsi a quella larghezza mantenendo le proporzioni. Se sia {larghezza} sia {altezza} sono specificati, l'immagine sarà ridimensionata a tali dimensioni. Aggiungi % alla fine del valore di {larghezza} o {altezza} per specificarlo come percentuale delle dimensioni del controllo anziché in pixel. Se una configurazione {valign} è specificata, l'immagine tenterà di allinearsi al testo circostante, vedi Allineamento verticale di immagini e tabelle. Supporta le opzioni di configurazione, consulta Opzioni di immagine.	[img]{percorso}[/img] [img=<larghezza>]{percorso}[/img] [img=<larghezza>x<altezza>]{percorso}[/img] [img={valign}]{percorso}[/img] [img {opzioni}]{percorso}[/img]
font Fa in modo che {testo} utilizzi una risorsa font da {percorso}. Supporta le opzioni di configurazione, consulta Opzioni di font.	[font={percorso}]{testo}[/font] [font {opzioni}]{testo}[/font]
font_size Utilizza una dimensione di font personalizzata per {testo}.	[font_size={dimensione}]{testo}[/font_size]
dropcap Utilizza una dimensione di font e un colore diversi per {text}, estendendo il contenuto del tag su più righe se è grande abbastanza. A drop cap is typically one uppercase character, but [dropcap] supports containing multiple characters. margins values are comma-separated and can be positive, zero or negative. Values must not be separated by spaces; otherwise, the values won't be parsed correctly. Negative top and bottom margins are particularly useful to allow the rest of the paragraph to display below the dropcap.	[dropcap font={font} font_size={dimensione} color={colore} outline_size={dimensione} outline_color={colore} margins={sinistra},{superiore},{destro},{inferiore}]{testo}[/dropcap]
opentype_features Enables custom OpenType font features for {text}. Features must be provided as a comma-separated {list}. Values must not be separated by spaces; otherwise, the list won't be parsed correctly.	[opentype_features={lista}] {testo} [/opentype_features]
lang Overrides the language for {text} that is set by the BiDi > Language property in RichTextLabel. {code} must be an ISO language code. This can be used to enforce the use of a specific script for a language without starting a new paragraph. Some font files may contain script-specific substitutes, in which case they will be used.	[lang={codice}]{testo}[/lang]
color Cambia il colore di {testo}. Il colore deve essere specificato con un nome comune (consulta Colori con nome) o in formato HEX (ad esempio #ff00ff, consulta Codici colori esadecimali).	[color={codice/nome}]{testo}[/color]
bgcolor Draws the color behind {text}. This can be used to highlight text. Accepts same values as the color tag. By default, there is a slight padding which is controlled by the text_highlight_h_padding and text_highlight_v_padding theme items in the RichTextLabel node. Set padding to 0 to avoid potential overlapping issues when there are background colors on neighboring lines/columns.	[bgcolor={codice/nome}]{testo}[/bgcolor]
fgcolor Draws the color in front of {text}. This can be used to "redact" text by using an opaque foreground color. Accepts same values as the color tag. By default, there is a slight padding which is controlled by the text_highlight_h_padding and text_highlight_v_padding theme items in the RichTextLabel node. Set padding to 0 to avoid potential overlapping issues when there are foreground colors on neighboring lines/columns.	[fgcolor={codice/nome}]{testo}[/fgcolor]
outline_size Utilizza una dimensione personalizzata per il contorno del font di {text}.	[outline_size={dimensione}] {testo} [/outline_size]
outline_color Utilizza un colore personalizzato per il contorno del font di {text}. Accetta gli stessi valori del tag color.	[outline_color={codice/nome}] {testo} [/outline_color]
table Crea una tabella con {numero} di colonne. Utilizza il tag cell per definire le celle di una tabella. Se la configurazione {valign} è specificata, la tabella tenterà di allinearsi al testo circostante, consulta Allineamento verticale di immagini e tabelle. Se si utilizza l'allineamento della linea di base, la tabella è allineata alla linea di base della riga con indice {riga_allineamento} (a base zero).	[table={numero}]{celle}[/table] [table={numero},{valign}]{celle}[/table] [table={numero},{valign},{riga_allineamento}]{celle}[/table]
cell Aggiunge una cella con {testo} alla tabella. Se {rapporto} è specificato, la cella tenterà di espandersi fino a raggiungere quel valore in modo proporzionale rispetto alle altre celle e ai loro valori di rapporto. Supporta le opzioni di configurazione, consulta Opzioni di cella.	[cell]{testo}[/cell] [cell={rapporto}]{testo}[/cell] [cell {opzioni}]{testo}[/cell]
ul Aggiunge un elenco non ordinato. Gli {elementi} dell'elenco devono essere specificati inserendo un elemento per riga di testo. È possibile personalizzare il punto elenco attraverso il parametro {punto}, consulta Punto di elenco non ordinato.	[ul]{elementi}[/ul] [ul bullet={punto}]{elementi}[/ul]
ol Aggiunge un elenco ordinato (numerato) del {tipo} specificato (consulta Tipi di elenchi ordinati). Gli {elementi} dell'elenco devono essere specificati inserendo un elemento per riga di testo.	[ol type={tipo}]{elementi}[/ol]
lb, rb Aggiunge [ e ] rispettivamente. Permette di evitare il markup BBCode. Questi sono tag a chiusura automatica, il che significa che non è necessario chiuderli (e non esiste alcun tag di chiusura [/lb] o [/rb]).	[lb]b[rb]testo[lb]/b[rb] verrà visualizzato come [b]testo[/b].
È possibile aggiungere diversi caratteri di controllo Unicode attraverso i propri tag a chiusura automatica. Ciò può facilitare la manutenzione rispetto a incollare i caratteri di controllo direttamente nel testo.	[lrm] (segno da sinistra a destra), [rlm] (segno da destra a sinistra), [lre] (integrazione da sinistra a destra), [rle] (integrazione da destra a sinistra), [lro] (sovrascrittura da sinistra a destra), [rlo] (sovrascrittura da destra a sinistra), [pdf] (pop di formattazione direzionale), [alm] (segno di lettera araba), [lri] (isolamento da sinistra a destra), [rli] (isolamento da destra a sinistra), [fsi] (primo isolamento forte), [pdi] (pop di isolamento direzionale), [zwj] (joiner di larghezza zero), [zwnj] (non-joiner di larghezza zero), [wj] (joiner di parole), [shy] (trattino dolce)

Nota

I tag per la formattazione in grassetto ([b]) e corsivo ([i]) funzionano meglio se i font personalizzati appropriati sono impostati nelle sostituzione del tema del nodo RichTextLabel. Se non sono definiti font personalizzati in grassetto o corsivo, Godot genererà font fittizi in grassetto e corsivo. Questi font raramente hanno un aspetto gradevole rispetto alle varianti in grassetto/corsivo create a mano.

Il tag monospaziato ([code]) funziona solo se è impostato un font personalizzato nelle sostituzioni del tema del nodo RichTextLabel. Altrimenti, il testo monospaziato utilizzerà il font regolare.

Non ci sono ancora tag BBCode per controllare la centratura verticale del testo.

È possibile saltare le opzioni per tutti i tag.

Opzioni di paragrafo

• align

  Valori	left (o l), center (o c), right (o r), fill (o f)
  Predefinito	left

  Allineamento orizzontale del testo.

• bidi_override, st

  Valori	default (o d), uri (o u), file (o f), email (o e), list (o l), none (o n), custom (o c)
  Predefinito	default

  Sostituzione del testo strutturato.

• justification_flags, jst

  Valori	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).
  Predefinito	word,kashida,skip_last,do_not_skip_single

  Opzione di giustificazione (allineamento del riempimento). Consulta TextServer per maggiori dettagli.

• direction, dir

  Valori	ltr (o l), rtl (o r), auto (o a)
  Predefinito	Eredita

  Direzione BiDi di base.

• language, lang

  Valori	Codici di lingua ISO. Vedi Codici di localizzazione
  Predefinito	Eredita

  Sostituzione della localizzazione. Alcuni file di font potrebbero contenere sostituti specifici all'alfabeto, nel qual caso saranno utilizzati essi.

• tab_stops

  Valori	Elenco di numeri in virgola mobile, ad esempio 10.0,30.0
  Predefinito	Larghezza del carattere spazio nel font

  Sostituisce gli offset orizzontali per ogni carattere di tabulazione. Quando si raggiunge la fine dell'elenco, le tabulazioni vengono ripetute ciclicamente. Ad esempio, se si imposta tab_stops a 10.0,30.0, la prima tabulazione sarà a 10 pixel, la seconda a 10 + 30 = 40 pixel e la terza a 10 + 30 + 10 = 50 pixel dall'origine del RichTextLabel.

Gestione dei clic sul tag [url]

Come predefinito, i tag [url] non fanno nulla quando vengono cliccati. Ciò rende flessibile l'uso dei tag [url] anziché limitarli all'apertura di URL in un browser web.

Per gestire i tag [url] cliccati, collega il segnale meta_clicked del nodo RichTextLabel a una funzione di script.

Ad esempio, il seguente metodo può essere collegato a meta_clicked per aprire gli URL cliccati usando browser web predefinito dell'utente:

# 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))

Per casi d'uso più avanzati, è anche possibile memorizzare JSON nell'opzione di un tag [url] e analizzarlo nella funzione che gestisce il segnale meta_clicked. Ad esempio:

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

Opzioni di immagine

• color

  Valori	Nome del colore o colore in formato HEX
  Predefinito	Eredita

  Tinta di colore dell'immagine (modulazione).

• height

  Valori	Numero intero
  Predefinito	Eredita

  Altezza di destinazione dell'immagine in pixel, aggiungi % alla fine del valore per specificarlo come percentuale della larghezza del controllo anziché in pixel.

• width

  Valori	Numero intero
  Predefinito	Eredita

  Larghezza di destinazione dell'immagine in pixel, aggiungi % alla fine del valore per specificarlo come percentuale della larghezza del controllo anziché in pixel.

• region

  Valori	x,y,larghezza,altezza in pixel
  Predefinito	Eredita

  Rettangolo della regione dell'immagine. Può essere utilizzato per visualizzare una singola immagine da uno spritesheet.

• pad

  Valori	false, true
  Predefinito	false

  Se impostato su true e l'immagine è più piccola delle dimensioni specificate da width e height, viene aggiunta una spaziatura all'immagine per adattarla alle dimensioni anziché ridimensionarla.

• tooltip

  Valori	Stringa
  Predefinito

  Suggerimento dell'immagine.

Allineamento verticale di immagini e tabelle

Quando si specifica un valore di allineamento verticale con il tag [img] o [table], l'immagine/tabella tenterà di allinearsi al testo circostante. L'allineamento viene effettuato tramite un punto verticale dell'immagine e un punto verticale del testo. Sono disponibili 3 punti sull'immagine (top, center e bottom) e 4 punti sul testo e sulla tabella (top, center, baseline e bottom), che si possono usare in qualsiasi combinazione.

Per specificare entrambi i punti, utilizza i loro nomi completi o abbreviati come valore del tag di immagine/tabella:

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.

È anche possibile specificare un solo valore (top, center o bottom) per utilizzare una preimpostazione corrispondente (rispettivamente top-top, center-center e bottom-bottom).

I nomi abbreviati per i valori sono t (top), c (center), l (baseline) e b (bottom).

Opzioni di font

• name, n

  Valori	Un percorso valido a una risorsa Font.
  Predefinito	Eredita

  Percorso a una risorsa Font.

• size, s

  Valori	Numero in pixel.
  Predefinito	Eredita

  Dimensione personalizzata di font.

• glyph_spacing, gl

  Valori	Numero in pixel.
  Predefinito	Eredita

  Spaziatura aggiuntiva per ogni glifo.

• space_spacing, sp

  Valori	Numero in pixel.
  Predefinito	Eredita

  Spaziatura aggiuntiva per il carattere spazio.

• top_spacing, top

  Valori	Numero in pixel.
  Predefinito	Eredita

  Spaziatura aggiuntiva nella parte superiore della riga.

• bottom_spacing, bt

  Valori	Numero in pixel.
  Predefinito	Eredita

  Spaziatura aggiuntiva nella parte inferiore della riga.

• embolden, emb

  Valori	Numero in virgola mobile.
  Predefinito	0.0

  Intensità grassetto del font: se diversa da zero, grassetta i contorni del font. Valori negativi riducono lo spessore del contorno.

• face_index, fi

  Valori	Numero intero.
  Predefinito	0

  Un indice di faccia attivo nella raccolta TrueType/OpenType.

• slant, sln

  Valori	Numero in virgola mobile.
  Predefinito	0.0

  Intensità dell'inclinazione del font: valori positivi inclinano i glifi verso destra. Valori negativi li inclinano verso sinistra.

• opentype_variation, otv

  Valori	Comma-separated list of the OpenType variation tags (no space after each comma).
  Predefinito

  Coordinate delle varianti OpenType del font. Vedi tag delle variazioni OpenType.

  Nota: il valore dovrebbe essere racchiuso tra " per consentire l'utilizzo di = al suo interno:

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

• opentype_features, otf

  Valori	Comma-separated list of the OpenType feature tags (no space after each comma).
  Predefinito

  Funzionalità OpenType del font. Vedi tag delle funzionalità OpenType.

  Nota: il valore dovrebbe essere racchiuso tra " per consentire l'utilizzo di = al suo interno:

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

Colori con nome

Per i tag che consentono di specificare un colore per nome, è possibile utilizzare i nomi delle costanti della classe integrata Color. Le classi con nome possono essere specificate in diversi stili, utilizzando sia maiuscole sia minuscole: DARK_RED, DarkRed e darkred daranno esattamente lo stesso risultato.

Consulta questa immagine per una lista di costanti di colore:

Visualizza a dimensioni originali

Codici colori esadecimali

Per i colori RGB opachi, è supportato qualsiasi codice esadecimale valido a 6 cifre, ad esempio [color=#ffffff]bianco[/color]. Sono supportati anche i codici colore RGB abbreviati come #6f2 (equivalente a #66ff22).

Per i colori RGB trasparenti, è possibile usare qualsiasi codice esadecimale RGBA a 8 cifre, ad esempio [color=#ffffff88]bianco traslucido[/color]. Si noti che il canale alfa è l'ultimo componente del codice colore, non il primo. Sono supportati anche codici colore RGBA brevi come #6f28 (equivalente a #66ff2288).

Opzioni di cella

• expand

  Valori	Numero intero
  Predefinito	1

  Rapporto di espansione della cella. Definisce quali celle cercheranno di espandersi in modo proporzionale rispetto ad altre celle e al loro rapporto di espansione.

• border

  Valori	Nome del colore o colore in formato HEX
  Predefinito	Eredita

  Colore del bordo della cella.

• bg

  Valori	Nome del colore o colore in formato HEX
  Predefinito	Eredita

  Colore di sfondo della cella. Per alternare gli sfondi delle righe pari/dispari, puoi usare bg=odd_color,even_color.

• padding

  Valori	4 comma-separated floating-point numbers (no space after each comma)
  Predefinito	0,0,0,0

  Spaziatura sinistra, superiore, destra e inferiore della cella.

Punto di elenco non ordinato

Come predefinito, il tag [ul] utilizza il glifo Unicode U+2022 "Bullet" come carattere punto elenco. Questo comportamento è simile a quello dei browser web. È possibile personalizzare il punto utilizzando [ul bullet={bullet}]. Se specificato, il parametro {bullet} deve essere un singolo carattere senza virgolette (ad esempio, [bullet=*]). Ulteriori caratteri sono ignorati. La larghezza del punto non influisce sulla formattazione dell'elenco.

Consulta Punto elenco su Wikipedia per un elenco dei caratteri punto elenco più comuni che è possibile incollare direttamente nel parametro bullet.

Tipi di elenchi ordinati

Gli elenchi ordinati si possono utilizzare per segnare automaticamente gli elementi con numeri o lettere in ordine crescente. Questo tag supporta le seguenti opzioni per il tipo:

• 1 - Numeri, utilizzando, se possibile, il sistema di numerazione specifico per la lingua.

• a, A - Lettere latine minuscole e maiuscole.

• i, I - Numeri romani minuscoli e maiuscoli.

Effetti di testo

Il BBCode si può anche utilizzare per creare diversi effetti di testo che si possono opzionalmente animare. Sono inclusi cinque effetti personalizzabili, ed è possibile crearne facilmente di propri. Come predefinito, gli effetti animati si mettono in pausa quando lo SceneTree è in pausa. È possibile cambiare questo comportamento regolando la proprietà Processo > Modalità del RichTextLabel.

Tutti gli esempi riportati di seguito menzionano i valori predefiniti per le loro opzioni nel formato dei tag elencati.

Nota

Gli effetti di testo che spostano la posizione dei caratteri potrebbero risultare in caratteri ritagliati dai limiti del nodo RichTextLabel.

È possibile risolvere ciò disattivando Control > Layout > Ritaglia contenuto nell'Ispettore dopo aver selezionato il nodo RichTextLabel, oppure assicurandosi che vi sia margine sufficiente attorno al testo, inserendo interruzioni di riga sopra e sotto la riga che sta usando l'effetto.

Pulsazione

Crea un effetto pulsante animato che moltiplica l'opacità e il colore di ogni carattere. Si può utilizzare per attirare l'attenzione su un testo specifico. Il formato del tag è [pulse freq=1.0 color=#ffffff40 ease=-2.0]{text}[/pulse].

freq controlla la frequenza del ciclo di semi-pulsazione (più alta è la frequenza, più veloce è). Un ciclo di pulsazione completo impiega 2 * (1.0 / freq) secondi. color è il moltiplicatore del colore di destinazione per il lampeggio. Il valore predefinito dissolve maggiormente il testo, ma non completamente. ease è l'esponente della funzione di easing da utilizzare. Valori negativi forniscono un easing in-out, motivo per cui il valore predefinito è -2.0.

Onda

Fa muovere il testo su e giù. Il suo formato del tag è [wave amp=50.0 freq=5.0 connected=1]{text}[/wave].

amp controlla quanto alto e basso va l'effetto, mentre freq controlla la frequenza con cui il testo va su e giù. Un valore di freq pari a 0 non produrrà onde visibili, mentre valori di freq negativi non mostreranno alcuna onda. Se connected è impostato su 1 (predefinito), i glifi con legature verranno spostati insieme. Se connected è impostato su 0, ogni glifo verrà spostato individualmente, anche se sono uniti da legature. Ciò può risolvere alcuni problemi di rendering con le legature dei font.

Tornado

Fa muovere il testo in modo circolare. Il formato del tag è [tornado radius=10.0 freq=1.0 connected=1]{text}[/tornado].

radius è il raggio del cerchio che controlla l'offset, freq indica la frequenza con cui il testo si muove in modo circolare. Un valore di freq pari a 0 metterà in pausa l'animazione, mentre un valore negativo di freq la riprodurrà all'indietro. Se connected è 1 (predefinito), i glifi con legature verranno spostati insieme. Se connected è 0, ogni glifo verrà spostato individualmente anche se sono uniti da legature. Ciò può risolvere alcuni problemi di rendering con le legature dei font.

Scuoti

Fa tremare il testo. Il formato del tag è [shake rate=20.0 level=5 connected=1]{text}[/shake].

rate controlla la frequenza di vibrazione del testo, level controlla lo scostamento del testo dall'origine. Se connected è 1 (predefinito), i glifi con legature verranno spostati insieme. Se connected è 0, ogni glifo viene spostato individualmente, anche se sono uniti da legature. Ciò può risolvere alcuni problemi di rendering con le legature dei font.

Dissolvi

Crea un effetto di dissolvenza statico che moltiplica l'opacità di ogni carattere. Il formato del tag è [fade start=4 length=14]{text}[/fade].

start controlla la posizione iniziale del decadimento rispetto al punto in cui è inserito il tag, length controlla per quanti caratteri bisogna effettuare la dissolvenza.

Arcobaleno

Assegna al testo un colore arcobaleno che cambia nel tempo. Il formato del tag è [rainbow freq=1.0 sat=0.8 val=0.8 speed=1.0]{text}[/rainbow].

freq determina il numero di lettere su cui si estende l'arcobaleno prima di ripetersi, sat è la saturazione dell'arcobaleno, val è il valore dell'arcobaleno. speed è il numero di cicli completi dell'arcobaleno al secondo. Un valore positivo di speed riproduce l'animazione in avanti, un valore di 0 la mette in pausa e un valore negativo di speed la riproduce all'indietro.

I contorni del font non sono influenzati dall'effetto arcobaleno (mantengono il loro colore originale). I colori esistenti del font sono sovrascritti dall'effetto arcobaleno. Tuttavia, le proprietà Modulate e Self Modulate di CanvasItem influenzeranno l'aspetto dell'effetto arcobaleno, poiché la modulazione ne moltiplica i colori finali.

Tag BBCode ed effetti di testo personalizzati

È possibile estendere il tipo di risorsa RichTextEffect per creare tag BBCode personalizzati. Crea un nuovo file di script che estende il tipo di risorsa RichTextEffect e assegna allo script un class_name in modo che sia possibile selezionare l'effetto nell'ispettore. Aggiungi l'annotazione @tool al file GDScript se desideri che questi effetti personalizzati siano eseguiti all'interno dell'editor. Il RichTextLabel non ha bisogno di uno script associato, né di essere in esecuzione in modalità tool. Il nuovo effetto può essere registrato nell'ispettore aggiungendolo all'array Markup > Effetti personalizzati, oppure tramite codice con il metodo install_effect():

Selezione di un RichTextEffect personalizzato dopo aver salvato uno script che estende RichTextEffect con un class_name

Avvertimento

Se l'effetto personalizzato non è registrato nella proprietà Markup > Effetti personalizzati del RichTextLabel, nessun effetto sarà visibile e il tag originale rimarrà cosi com'è.

C'è solo una funzione da estendere: _process_custom_fx(char_fx). Facoltativamente, è possibile anche fornire un identificatore BBCode personalizzato aggiungendo un membro con il nome bbcode. Il codice controllerà automaticamente la proprietà bbcode o userà il nome del file per determinare quale tag BBCode utilizzare.

_process_custom_fx

È qui che si svolge la logica di ogni effetto, che viene chiamata una volta per glifo durante la fase di disegno per renderizzare il testo. Questo passa un oggetto CharFXTransform, che contiene alcune variabili per controllare come viene renderizzato il glifo associato:

• identity specifica quale effetto personalizzato è in elaborazione. È consigliabile utilizzarlo per il controllo del flusso del codice.

• outline è true se l'effetto viene chiamato per disegnare il contorno del testo.

• range Determina, sotto forma di indice, a che punto ci si trova in un determinato blocco di effetti personalizzati.

• elapsed_time è il tempo totale d'esecuzione per l'effetto di testo.

• visible determinerà se il glifo è visibile o meno e consentirà anche di nascondere una determinata porzione di testo.

• offset è una posizione di offset relativa a dove un determinato glifo si dovrebbe renderizzare in circostanze normali.

• color è il colore di un determinato glifo.

• glyph_index e font sono il glifo che viene disegnato e la risorsa font utilizzata per disegnarlo.

• Infine, env è un Dictionary di parametri assegnati a un determinato effetto personalizzato. È possibile usare get() con un valore predefinito facoltativo per recuperare ciascun parametro, se specificato dall'utente. Ad esempio, [custom_fx spread=0.5 color=#FFFF00]test[/custom_fx] avrebbe i parametri float spread e Color color nel suo dizionario env. Vedere in seguito per ulteriori esempi di utilizzo.

L'ultima cosa da notare su questa funzione è che è necessario restituire un valore booleano true per verificare che l'effetto sia stato elaborato correttamente. In questo modo, se si verifica un problema con il rendering di un determinato glifo, il rendering degli effetti personalizzati verrà interrotto completamente finché l'utente non correggerà qualsiasi errore riscontrato nella logica dell'effetto personalizzato.

Ecco alcuni esempi di effetti personalizzati:

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

Matrice

@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 = 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

Questo aggiungerà alcuni nuovi comandi BBCode, che si possono utilizzare in questo modo:

[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]