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

Normalmente, RichTextLabel funziona come una comune Label. Ha la proprietà text, che si può modificare per ottenere un testo formattato in maniera uniforme. Per poter utilizzare il BBCode per la formattazione rich text, bisogna attivare la modalità BBCode impostando bbcode_enabled. Successivamente, è possibile modificare la proprietà text utilizzando i tag disponibili. Entrambe le proprietà si trovano in alto all'ispettore dopo aver selezionato un nodo RichTextLabel.

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

La maggioranza dei BBCode è composta da tre parti: il tag di apertura, il contenuto e il tag di chiusura. Il tag di apertura delimita l'inizio della parte formattata e può anche includere alcune opzioni di configurazione. Alcuni tag di apertura, come quello color mostrato sopra, richiedono anche un valore per funzionare. Altri tag di apertura possono accettare più opzioni (separate da spazi all'interno del tag di apertura). Il tag di chiusura delimita la fine della parte formattata. In alcuni casi, è possibile omettere entrambi il tag di chiusura e il contenuto.

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 uno scenario in cui gli utenti possono inserire liberamente testo (ad esempio, nella chat di un gioco multigiocatore), è necessario assicurarsi che non possano utilizzare tag BBCode arbitrari che saranno interpretati da un RichTextLabel. Questo per evitare un uso improprio della formattazione, che può essere problematico se i tag [url] sono gestiti dal proprio RichTextLabel (poiché i giocatori potrebbero essere in grado di creare collegamenti cliccabili a siti di phishing o simili).

Utilizzando i tag [lb] e/o [rb] di RichTextLabel, possiamo sostituire le parentesi di apertura e/o chiusura di qualsiasi tag BBCode in un messaggio con tali tag di escape. Ciò impedisce agli utenti di usare BBCode che sarà analizzato come tag; il BBCode sarà invece visualizzato come testo.

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.

• Abilitare la proprietà Threading > Threaded in RichTextLabel. Questo non velocizzerà l'elaborazione, ma impedirà il blocco del thread principale, evitando così scatti durante il gioco. Abilitare il threading solo se effettivamente necessario nel proprio progetto, poiché il threading ha un certo impatto iniziale.

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] [u color={colore}]{testo}[/u]
s Rende {testo} barrato.	[s]{testo}[/s] [s color={colore}]{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 opzioni di configurazione, consultare Opzioni di paragrafo.	[p]{testo}[/p] [p {opzioni}]{testo}[/p]
br Aggiunge un'interruzione di riga in un testo, senza creare un nuovo paragrafo. Se utilizzato all'interno di una lista, non crea un nuovo elemento di lista, ma aggiunge un'interruzione di riga all'interno dell'elemento attuale.	[br]
hr Aggiunge un nuova linea orizzontale per separare i contenuti. Supporta opzioni di configurazione, consulta Opzioni di linea orizzontale.	[hr] [hr {opzioni}]
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 un {link} così com'è. Supporta opzioni di configurazione, consultare Opzioni di URL. 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] [url {opzioni}]{testo}[/url]
hint Crea un tooltip che è visualizzato al passaggio del mouse sul testo. Sebbene non sia obbligatorio, si consiglia di racchiudere il testo del tooltip tra virgolette doppie o singole. Si noti che non è possibile usare \" o \' come escape per le virgolette. Per utilizzare le virgolette singole per gli apostrofi nella stringa del suggerimento, è necessario utilizzare le virgolette doppie per racchiudere la stringa.	[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. Aggiungi em alla fine del valore di {larghezza} o {altezza} per specificarlo come rapporto rispetto alla dimensione del font attuale. Ad esempio, height=1em renderà l'immagine alta quanto il testo circostante. Se una configurazione {valign} è specificata, l'immagine tenterà di allinearsi al testo circostante, vedi Allineamento verticale di immagini e tabelle. Supporta opzioni di configurazione, consultare 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 opzioni di configurazione, consultare 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. Un capolettera è in genere costituito da un solo carattere maiuscolo, ma [dropcap] supporta più di un carattere. I valori di margins sono separati da virgole e possono essere positivi, zero o negativi. I valori non si devono separare da spazi; altrimenti, i valori non saranno analizzati correttamente. I margini superiori e inferiori negativi sono particolarmente utili per permettere di visualizzare il resto del paragrafo sotto il capolettera.	[dropcap font={font} font_size={dimensione} color={colore} outline_size={dimensione} outline_color={colore} margins={sinistra},{superiore},{destro},{inferiore}]{testo}[/dropcap]
opentype_features Abilita funzionalità OpenType personalizzate di font per {testo}. Bisogna specificare le funzionalità sotto forma di {lista} separata da virgole. I valori non si devono separare da spazi; altrimenti, la lista non sarà analizzata correttamente.	[opentype_features={lista}] {testo} [/opentype_features]
lang Sostituisce la lingua per {testo} impostata dalla proprietà BiDi > Lingua in RichTextLabel. {codice} deve essere un codice lingua ISO. Questo può servire per imporre l'uso di un'alfabeto specifico per una lingua senza iniziare un nuovo paragrafo. Alcuni file di font potrebbero contenere sostituti specifici per un alfabeto, nel qual caso saranno utilizzati essi.	[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 Disegna il colore dietro {testo}. Può essere usato per evidenziare il testo. Accetta gli stessi valori del tag color. Come predefinito, è presente una leggera spaziatura interna, controllata dagli elementi del tema text_highlight_h_padding e text_highlight_v_padding nel nodo RichTextLabel. Impostare la spaziatura interna su 0 per evitare eventuali problemi di sovrapposizione quando ci sono colori di sfondo su righe/colonne adiacenti.	[bgcolor={codice/nome}]{testo}[/bgcolor]
fgcolor Disegna il colore davanti a {text}. Può essere usato per "oscurare" il testo tramite un colore di primo piano opaco. Accetta gli stessi valori del tag color. Come predefinito, è presente una leggera spaziatura interna, controllata dagli elementi del tema text_highlight_h_padding e text_highlight_v_padding nel nodo RichTextLabel. Impostare la spaziatura interna su 0 per evitare eventuali problemi di sovrapposizione quando ci sono colori in primo piano su righe/colonne adiacenti.	[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). {name} è un nome della tabella per le applicazioni assistive (lettore di schermo).	[table={numero}]{celle}[/table] [table={numero},{valign}]{celle}[/table] [table={numero},{valign},{riga_allineamento}]{celle}[/table] [table={number},{valign},{alignment_row} name={name}]{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 opzioni di configurazione, consultare 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	Elenco separato da virgole dei seguenti valori (senza spazi dopo ogni virgola): kashida (o k), word (o w), trim (o tr), after_last_tab (o lt), skip_last (o sl), skip_last_with_chars (o sv), do_not_skip_single (o 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 si può connettere a meta_clicked per aprire gli URL cliccati tramite il 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 un 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 linea orizzontale

• color

  Valori	Nome del colore o colore in formato HEX
  Predefinito	Color(1, 1, 1, 1)

  Tinta di colore della linea (modulazione).

• height

  Valori	Numero intero
  Predefinito	2

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

• width

  Valori	Numero intero
  Predefinito	90%

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

• align

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

  Allineamento orizzontale.

Opzioni di URL

• underline

  Valori	always, never, hover
  Predefinito	always

  Metodo di sottolineatura dell'URL.

• tooltip

  Valori	Stringa.
  Predefinito

  Suggerimento dell'URL.

• href

  Valori	Stringa.
  Predefinito

  Indirizzo URL di destinazione.

Opzioni di immagine

• color

  Valori	Nome del colore o colore in formato HEX
  Predefinito	Eredita

  Tinta di colore dell'immagine (modulazione).

• height

  Valori	Numero a virgola mobile
  Predefinito	Eredita

  Altezza di destinazione dell'immagine, in pixel.

  È possibile specificare unità di misura alternative ai pixel:

  • Aggiungi % alla fine del valore per specificarlo come percentuale della larghezza del controllo anziché in pixel. Ad esempio, height=50% renderà l'immagine alta la metà della larghezza del controllo.

  • Aggiungere em alla fine del valore per specificarlo come rapporto rispetto alla dimensione del font circostante anziché in pixel. Ad esempio, height=1em renderà l'immagine alta quanto il testo circostante.

• width

  Valori	Numero a virgola mobile
  Predefinito	Eredita

  Larghezza di destinazione dell'immagine, in pixel.

  È possibile specificare unità di misura alternative ai pixel:

  • Aggiungi % alla fine del valore per specificarlo come percentuale della larghezza del controllo anziché in pixel. Ad esempio, width=50% renderà l'immagine larga la metà della larghezza del controllo.

  • Aggiungere em alla fine del valore per specificarlo come rapporto rispetto alla dimensione del font circostante anziché in pixel. Ad esempio, width=1em renderà l'immagine larga quanto l'altezza del testo circostante.

• 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.

• align

  Valori	Vedi Allineamento verticale di immagini e tabelle
  Predefinito	center,center

  Allineamento dell'immagine al testo circostante.

• alt

  Valori	Stringa
  Predefinito

  Descrizione dell'immagine per le applicazioni assistive (lettore di schermo).

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	Elenco separato da virgole dei tag di variazione OpenType (senza spazi dopo ogni virgola).
  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	Elenco separato da virgole dei tag delle funzionalità OpenType (senza spazi dopo ogni virgola).
  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

• shrink

  Valori	false, true
  Predefinito	true

  Se true, la cella può ridursi al suo contenuto.

• 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 numeri in virgola mobile separati da virgole (senza spazi dopo ogni virgola)
  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 di 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 una stringa senza virgolette (ad esempio, [bullet=*]). È possibile aggiungere spazi finali dopo il carattere di punto elenco per aumentare la spaziatura tra il punto elenco e il testo dell'elemento 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 usare per creare diversi effetti di testo che è possibile opzionalmente animare. Sono già inclusi diversi 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:

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

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]