Up to date

This page is up to date for Godot 4.2. If you still find outdated information, please open an issue.

BBCode in RichTextLabel

Einführung

Label-Nodes eignen sich hervorragend für die Anzeige von einfachem Text, aber sie haben ihre Grenzen. Wenn Sie die Farbe des Textes oder seine Ausrichtung ändern wollen, können Sie das nur für das gesamte Label tun. Es ist nicht möglich, einem Teil des Textes eine andere Farbe zu geben oder einen Teil des Textes zu zentrieren. Um diese Einschränkungen zu umgehen, würden Sie ein RichTextLabel verwenden.

RichTextLabel ermöglicht die komplexe Formatierung von Text mit Hilfe einer Markup-Syntax oder der eingebauten API. Es verwendet BBCodes für die Markup-Syntax, ein System von Tags, die Formatierungsregeln für einen Teil des Textes bezeichnen. Vielleicht sind Sie damit vertraut, wenn Sie schon einmal Foren benutzt haben (auch bekannt als Bulletin Boards, daher das "BB" in "BBCode").

Im Gegensatz zu Label verfügt RichTextLabel auch über eine eigene vertikale Scrollbar. Diese Scrollbar wird automatisch angezeigt, wenn der Text nicht in die Größe des Controls passt. Die Scrollbar kann durch Deaktivieren der Property Scroll Active im RichTextLabel-Inspektor deaktiviert werden.

Beachten Sie, dass die BBCode-Tags bis zu einem gewissen Grad auch in der XML-Quelle der Klassenreferenz verwendet werden können. Für weitere Informationen, siehe Einführung in die Klassenreferenz.

Siehe auch

Sie können sehen, wie BBCode in RichTextLabel in Aktion funktioniert, indem Sie das Rich Text Label with BBCode Demoprojekt verwenden.

Verwendung von BBCode

Standardmäßig funktioniert RichTextLabel wie ein normales Label. Es hat die Property property_text, die Sie bearbeiten können, um einheitlich formatierten Text zu erhalten. Um BBCode für die Rich-Text-Formatierung verwenden zu können, müssen Sie den BBCode-Modus einschalten, indem Sie bbcode_enabled setzen. Danach können Sie die Property text mit den verfügbaren Tags bearbeiten. Beide Properties befinden sich im oberen Bereich des Inspektors, nachdem ein RichTextLabel-Node ausgewählt wurde.

../../_images/bbcode_in_richtextlabel_inspector.webp

Zum Beispiel würde BBCode [color=green]test[/color] das Wort "test" mit einer grünen Farbe darstellen.

../../_images/bbcode_in_richtextlabel_basic_example.webp

Die meisten BBCodes bestehen aus drei Teilen: dem öffnenden Tag, dem Inhalt und dem schließenden Tag. Der öffnende Tag grenzt den Beginn des formatierten Teils ab und kann auch einige Konfigurationsoptionen enthalten. Einige öffnende Tags, wie der oben gezeigte color, benötigen auch einen Wert, um zu funktionieren. Andere öffnende Tags können mehrere Optionen akzeptieren (getrennt durch Leerzeichen innerhalb des öffnenden Tags). Der schließende Tag begrenzt das Ende des formatierten Teils. In einigen Fällen können sowohl das schließende Tag als auch der Inhalt weggelassen werden.

Im Gegensatz zu BBCode in HTML werden führende/abschließende Leerzeichen bei der Anzeige eines RichTextLabels nicht entfernt. Auch doppelte Leerzeichen werden in der endgültigen Ausgabe unverändert angezeigt. Das bedeutet, dass Sie bei der Anzeige eines Codeblocks in einem RichTextLabel kein vorformatiertes Text-Tag verwenden müssen.

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

Bemerkung

RichTextLabel unterstützt keine verschränkten BBCode-Tags. Zum Beispiel, statt der Verwendung von:

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

Verwenden Sie:

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

Sichere Handhabung von Benutzereingaben

In einem Szenario, in dem Benutzer frei Text eingeben können (z.B. Chat in einem Multiplayer-Spiel), sollten Sie sicherstellen, dass Benutzer keine beliebigen BBCode-Tags verwenden können, die von RichTextLabel geparst werden. Dies dient dazu, eine unangemessene Verwendung von Formatierungen zu vermeiden, was problematisch sein kann, wenn [url]-Tags von Ihrem RichTextLabel verarbeitet werden (da Spieler in der Lage sein könnten, anklickbare Links zu Phishing-Seiten oder ähnlichem zu erstellen).

Mit Hilfe der RichTextLabel-Tags [lb] und/oder [rb] können wir die öffnenden und/oder schließenden Klammern jedes BBCode-Tags in einer Nachricht durch diese maskierten Tags ersetzen. Dadurch wird verhindert, dass Benutzer BBCode verwenden, der als Tags geparst wird - stattdessen wird der BBCode als Text angezeigt.

Beispiel für eine Benutzereingabe ohne Maskierung, die zu einer BBCode-Injection führt (2. Zeile) und eine Benutzereingabe mit Maskierung (3. Zeile)

Beispiel für eine Benutzereingabe ohne Maskierung, die zu einer BBCode-Injection führt (2. Zeile) und eine Benutzereingabe mit Maskierung (3. Zeile)

Das obige Bild wurde mit folgendem Skript erstellt:

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

Entfernen von BBCode-Tags

Für bestimmte Anwendungsfälle kann es erwünscht sein, BBCode-Tags aus dem String zu entfernen. Dies ist nützlich, wenn der Text des RichTextLabels in einem anderen Control angezeigt wird, das BBCode nicht unterstützt (z.B. ein 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.

Bemerkung

Das vollständige Entfernen von BBCode-Tags ist für Benutzereingaben nicht ratsam, da es den angezeigten Text verändern kann, ohne dass die Benutzer verstehen, warum ein Teil ihrer Nachricht entfernt wurde. Maskieren von Benutzereingaben sollte stattdessen bevorzugt werden.

Performance

In den meisten Fällen können Sie BBCode direkt verwenden, da die Textformatierung selten eine schwere Aufgabe ist. Bei besonders großen RichTextLabels (z. B. Konsolenprotokollen, die Tausende von Zeilen umfassen) kann es jedoch während des Spiels zu Stuttering kommen, wenn der Text des RichTextLabels aktualisiert wird.

Es gibt mehrere Möglichkeiten, dieses Problem zu lösen:

  • Verwenden Sie die Funktion append_text() anstelle des Anhängens an die text-Property. Diese Funktion analysiert nur den BBCode für den hinzugefügten Text, anstatt den BBCode der gesamten text-Property zu analysieren.

  • Verwenden Sie die Funktionen push_[tag]() und pop(), um Tags zu RichTextLabel hinzuzufügen, anstatt BBCode zu verwenden.

  • Aktivieren Sie die Property Threading > Threaded in RichTextLabel. Dies wird die Verarbeitung nicht beschleunigen, aber es wird verhindern, dass der Hauptthread blockiert, was Stuttering während des Spiels verhindert. Aktivieren Sie Threading nur, wenn es in Ihrem Projekt tatsächlich benötigt wird, da Threading einen gewissen Overhead verursacht.

Verwendung der Funktionen push_[tag]() und pop() anstelle von BBCode

Wenn Sie aus Performance-Gründen keinen BBCode verwenden möchten, können Sie die von RichTextLabel bereitgestellten Funktionen verwenden, um Formatierungs-Tags zu erstellen, ohne BBCode in den Text zu schreiben.

Jedes BBCode Tag (einschließlich der Effekte) hat eine push_[tag]() Funktion (wobei [tag] der Name des Tags ist). Es gibt auch einige Komfortfunktionen, wie push_bold_italics(), die sowohl push_bold() als auch push_italics() in einem einzigen Tag kombiniert. Siehe die RichTextLabel Klassenreferenz für eine komplette Liste der push_[tag]() Funktionen.

Die Funktion pop() wird benutzt, um jedes Tag zu beenden. Da BBCode ein Tag-Stack ist, werden mit pop() die zuletzt gestarteten Tags zuerst geschlossen.

Das folgende Skript ergibt die gleiche visuelle Ausgabe wie die Verwendung von 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()`.

Warnung

Setzen Sie nicht die text-Property direkt, wenn Sie Formatierungsfunktionen verwenden. Das Anhängen an die text-Property löscht alle Änderungen, die mit den Funktionen append_text(), push_[tag]() und pop() am RichTextLabel vorgenommen wurden.

Referenz

Tag

Beispiel

b
Verwendet die fette (oder fett-kursive) Schriftart von RichTextLabel für {text}.

[b]{text}[/b]

i
Macht {text} zur kursiven (oder fett-kursiven) Schriftart von RichTextLabel.

[i]{text}[/i]

u
Stellt {text} unterstrichen dar.

[u]{text}[/u]

s
Stellt {Text} durchgestrichen dar.

[s]{text}[/s]

code
Verwendet die Mono-Schriftart von RichTextLabel für {text}.

[code]{text}[/code]

p
Fügt einen neuen Absatz mit {text} hinzu. Unterstützt Konfigurationsoptionen, siehe Absatz-Optionen.
[p]{text}[/p]
[p {options}]{text}[/p]
center
Stellt {text} horizontal zentriert dar.
Dasselbe wie [p align=center].

[center]{text}[/center]

left
Stellt {text} horizontal linksbündig dar.
Dasselbe wie [p align=left].

[left]{text}[/left]

right
Stellt {text} horizontal rechtsbündig dar.
Dasselbe wie [p align=right].

[right]{text}[/right]

fill
Stellt {text} in voller Breite von RichTextLabel dar.
Dasselbe wie [p align=fill].

[fill]{text}[/fill]

indent
Rückt {text} einmal ein. Die Einrückungsbreite ist die gleiche wie bei [ul] oder [ol], aber ohne Zeichen für punktierte Listen.

[indent]{text}[/indent]

url
Erzeugt einen Hyperlink (unterstrichener und anklickbarer Text). Kann optionalen {text} enthalten oder {link} so anzeigen, wie er ist.
Muss mit dem Signal "meta_clicked" behandelt werden, um eine Wirkung zu haben, siehe Umgang mit [url]-Tag-Klicks.
[url]{link}[/url]
[url={link}]{text}[/url]
hint
Erzeugt einen Tooltip-Hint, der angezeigt wird, wenn man mit der Maus über den Text fährt. Der Tooltip-Text sollte nicht in Anführungszeichen gesetzt werden (Anführungszeichen erscheinen sonst unverändert im Tooltip).
[hint={Tooltip-Text, der beim Maus-Überfahren angezeigt wird}]{text}[/hint]
img
Fügt ein Bild aus dem {path} ein (kann jede gültige Texture2D-Ressource sein).
Wenn {width} angegeben ist, wird das Bild versuchen, sich dieser Breite anzupassen, wobei das Seitenverhältnis beibehalten wird.
Wenn sowohl {width} als auch {height} angegeben werden, wird das Bild auf diese Größe skaliert.
Wenn die Konfiguration {valign} angegeben ist, wird das Bild versuchen, sich an dem umgebenden Text auszurichten, siehe Vertikale Ausrichtung des Bildes.
Unterstützt Konfigurationsoptionen, siehe Bild-Optionen.
[img]{path}[/img]
[img={width}]{path}[/img]
[img={width}x{height}]{path}[/img]
[img={valign}]{path}[/img]
[img {options}]{path}[/img]
font
Bringt {text} dazu, eine Schriftart-Ressource aus dem {path} zu verwenden.
Unterstützt Konfigurationsoptionen, siehe Schriftart-Optionen.
[font={path}]{text}[/font]
[font {options}]{text}[/font]
font_size
Eigene Schriftart für {text} verwenden.

[font_size={size}]{text}[/font_size]

dropcap
Verwenden einer anderen Schriftart und Farbe für {text}, wobei der Inhalt des Tags sich über mehrere Zeilen erstreckt, wenn er groß genug ist.
Ein Dropcap ist normalerweise ein Großbuchstabe, aber [dropcap] kann auch mehrere Zeichen enthalten. Die Werte von margins sind durch Kommas getrennt und können positiv, null oder negativ sein. Negative obere und untere Seitenränder sind besonders nützlich, um den Rest des Absatzes unterhalb des Dropcaps anzeigen zu lassen.

[dropcap font_size={size} color={color} margins={left},{top},{right},{bottom}]{text}[/dropcap]

opentype_features
Aktiviert benutzerdefinierte OpenType Schriftart-Features für {text}. Die Features müssen als kommagetrennte Liste in {list} angegeben werden.
[opentype_features={list}]
{text}
[/opentype_features]
lang
Überschreibt die Sprache für {text}, die durch die BiDi > Sprache-Property in RichTextLabel festgelegt ist. {code} muss ein ISO Sprachcode sein. Dies kann verwendet werden, um die Verwendung einer bestimmten Schrift für eine Sprache zu erzwingen, ohne einen neuen Absatz zu beginnen. Einige Schriftarten können skript-spezifische Ersetzungen enthalten, die dann verwendet werden.

[lang={code}]{text}[/lang]

color
Ändert die Farbe von {text}. Die Farbe muss durch einen allgemeinen Namen (siehe Benannte Farben) oder durch das HEX-Format (z.B. #ff00ff, siehe Hexadezimale Farbcodes) angegeben werden.

[color={code/name}]{text}[/color]

bgcolor
Zeichnet die Farbe hinter {text}. Dies kann verwendet werden, um Text hervorzuheben. Akzeptiert dieselben Werte wie der color-Tag.

[bgcolor={code/name}]{text}[/bgcolor]

fgcolor
Zeichnet die Farbe vor dem {text}. Dies kann verwendet werden, um Text mit einer undurchsichtigen Vordergrundfarbe zu "schwärzen". Akzeptiert dieselben Werte wie der Tag color.

[fgcolor={code/name}]{text}[/fgcolor]

outline_size
Verwenden einer benutzerdefinierten Schriftart für {text}.
[outline_size={size}]
{text}
[/outline_size]
outline_color
Verwenden einer benutzerdefinierten Umrissfarbe für {text}. Akzeptiert dieselben Werte wie der color-Tag.
[outline_color={code/name}]
{text}
[/outline_color]
table
Erzeugt eine Tabelle mit der {number} von Spalten. Verwenden Sie den cell-Tag, um Tabellenzellen zu definieren.

[table={number}]{cells}[/table]

cell
Fügt eine Zelle mit {text} in die Tabelle ein.
Wenn {ratio} angegeben ist, wird die Zelle versuchen, sich proportional zu anderen Zellen und deren Verhältniswerten auf diesen Wert auszudehnen.
Unterstützt Konfigurationsoptionen, siehe Zellenoptionen.
[cell]{text}[/cell]
[cell={ratio}]{text}[/cell]
[cell {options}]{text}[/cell]
ul
Fügt eine ungeordnete Liste hinzu. Die Liste {items} muss mit einem Element pro Textzeile angegeben werden.
Der Aufzählungspunkt kann mit dem Parameter {bullet} angepasst werden, siehe Aufzählungszeichen für ungeordnete Listen.
[ul]{items}[/ul]
[ul bullet={bullet}]{items}[/ul]
ol
Fügt eine geordnete (nummerierte) Liste des angegebenen {type} hinzu (siehe Geordnete Listenarten). Die Liste {items} muss mit einem Element pro Textzeile angegeben werden.

[ol type={type}]{items}[/ol]

lb, rb
Fügt [ bzw. ] hinzu. Ermöglicht das Maskieren von BBCode Markup.
Dies sind selbstschließende Tags, was bedeutet, dass Sie sie nicht schließen müssen (und es gibt keinen [/lb] oder [/rb]-schließenden Tag).
[lb]b[rb]text[lb]/b[rb] wird als [b]text[/b] angezeigt.
Mehrere Unicode-Steuerzeichen können mit eigenen selbstschließenden Tags hinzugefügt werden.
Dies kann zu einer einfacheren Verwaltung führen als das Einfügen per Copy&Paste
Steuerzeichen direkt im Text.
[lrm] (Links-nach-Rechts-Markierung), [rlm] (Rechts-nach-Links-Markierung), [lre] (Links-nach-Rechts-Einbettung),
[rle] (Rechts-nach-Links-Einbettung), [lro] (Links-nach-Rechts-Überschreibung), [rlo] (Rechts-nach-Links-Überschreibung),
[pdf] (POP-Directional Formatting), [alm] (Arabic Letter Mark), [lri] (Left-to-Right Isolate),
[rli] (Right to Left-Isolate), [fsi] (First Strong Isolate), [pdi] (POP-Directional Isolate),
[zwj] (Zero-Width Joiner), [zwnj] (Zero-Width Non-Joiner), [wj] (Word Joiner),
[shy] (weicher Bindestrich)

Bemerkung

Tags für fette ([b]) und kursive ([i]) Formatierung funktionieren am besten, wenn die entsprechenden benutzerdefinierten Schriftarten in den Theme-Overrides des RichTextLabelNode eingerichtet sind. Wenn keine benutzerdefinierten fetten oder kursiven Schriftarten definiert sind, werden von Godot pseudo-fette und kursive Schriftarten erzeugt. Diese Schriftarten sehen im Vergleich zu handgefertigten fetten/kursiven Schriftarten selten gut aus.

Der Monospaced-([code])-Tag funktioniert nur, wenn eine benutzerdefinierte Schriftart in das Theme-Overrides des RichTextLabel-Nodes eingestellt ist. Andernfalls wird für einzeiligen Text die normale Schriftart verwendet.

Es gibt noch keine BBCode-Tags zur Steuerung der vertikalen Zentrierung von Text.

Die Optionen können für alle Tags übersprungen werden.

Absatz-Optionen

  • align

    Values

    left, center, right, fill

    Default

    left

    Horizontale Ausrichtung des Textes.

  • bidi_override, st

    Values

    default, uri, file, email, list, none, custom

    Default

    default

    Überschreiben von strukturiertem Text.

  • direction, dir

    Values

    ltr, rtl, auto

    Default

    Vererben

    Basis-BiDi-Richtung.

  • language, lang

    Values

    ISO-Sprachcodes. Siehe Gebietsschema-Codes

    Default

    Vererben

    Gebietsschema überschreiben. Einige Schriftarten können skriptspezifische Ersetzungen enthalten, die dann verwendet werden.

  • tab_stops

    Values

    Liste von Float-Zahlen, z.B. 10.0,30.0

    Default

    Breite des Leerzeichens in der Schriftart

    Überschreibt die horizontalen Offsets für jedes Tab-Zeichen. Wenn das Ende der Liste erreicht ist, werden die Tabstopps in einer Schleife durchlaufen. Wenn Sie zum Beispiel tab_stops auf 10.0,30.0 setzen, ist der erste Tab bei 10 Pixeln, der zweite Tab bei 10 + 30 = 40 Pixeln und der dritte Tab bei 10 + 30 + 10 = 50 Pixeln vom Ursprung des RichTextLabels.

Umgang mit [url]-Tag-Klicks

Standardmäßig bewirken [url]-Tags nichts, wenn sie angeklickt werden. Dies soll eine flexible Verwendung von [url]-Tags ermöglichen, anstatt sie auf das Öffnen von URLs in einem Webbrowser zu beschränken.

Um angeklickte [url]-Tags zu behandeln, verbinden Sie das meta_clicked-Signal des RichTextLabel-Nodes mit einer Skriptfunktion.

Zum Beispiel kann die folgende Methode mit meta_clicked verbunden werden, um angeklickte URLs mit dem Default-Webbrowser des Benutzers zu öffnen:

# 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 run-time.
    OS.shell_open(str(meta))

Für fortgeschrittene Anwendungsfälle ist es auch möglich, JSON in der Option eines [url]-Tags zu speichern und es in der Funktion zu analysieren, die das meta_clicked-Signal verarbeitet. Zum Beispiel:

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

Bild-Optionen

  • color

    Values

    Farbname oder Farbe im HEX-Format

    Default

    Vererben

    Farbtönung des Bildes (Modulation).

  • height

    Values

    Anzahl in Pixeln

    Default

    Vererben

    Zielhöhe des Bildes.

  • width

    Values

    Anzahl in Pixeln

    Default

    Vererben

    Zielbreite des Bildes.

  • region

    Values

    x, y, Breite, Höhe in Pixeln

    Default

    Vererben

    Bereichs-Rechteck des Bildes. Dies kann verwendet werden, um ein einzelnes Bild aus einem Spritesheet anzuzeigen.

Vertikale Ausrichtung des Bildes

Wenn ein Wert für die vertikale Ausrichtung mit dem [img]-Tag angegeben wird, versucht das Bild, sich an dem umgebenden Text auszurichten. Die Ausrichtung erfolgt anhand eines vertikalen Punktes des Bildes und eines vertikalen Punktes des Textes. Es gibt 3 mögliche Punkte auf dem Bild (top, center und bottom) und 4 mögliche Punkte auf dem Text (top, center, baseline und bottom), die in jeder Kombination verwendet werden können.

Um beide Punkte anzugeben, verwenden Sie ihre vollständigen oder kurzen Namen als Wert des Bild-Tags:

[img=top,bottom]
[img=center,center]

Sie können auch nur einen Wert angeben (top, center oder bottom), um eine entsprechende Vorgabe zu verwenden (top-top, center-center bzw. bottom-bottom).

Kurznamen für die Werte sind t (top), c (center), l (baseline) und b (bottom).

Schriftart-Optionen

  • name, n

    Values

    Ein gültiger Schriftart-Ressourcenpfad.

    Default

    Vererben

    Pfad der Schriftart-Ressourcen.

  • size, s

    Values

    Anzahl in Pixeln.

    Default

    Vererben

    Benutzerdefinierte Schriftgröße.

Benannte Farben

Für Tags, die es erlauben, eine Farbe durch einen Namen zu spezifizieren, können Sie die Namen der Konstanten der Built-in-Klasse Color verwenden. Benannte Klassen können in einer Reihe von Stilen mit verschiedenen Schreibstilen angegeben werden: DARK_RED, DarkRed und darkred ergeben genau das gleiche Ergebnis.

Hexadezimale Farbcodes

Für undurchsichtige RGB-Farben wird jeder gültige 6-stellige Hexadezimalcode unterstützt, z.B. [color=#ffffff]white[/color]. Kurzschrift-RGB-Farbcodes wie #6f2 (entspricht #66ff22) werden ebenfalls unterstützt.

Für transparente RGB-Farben kann ein beliebiger 8-stelliger RGBA-Hexadezimalcode verwendet werden, z.B. [color=#ffffff88]durchsichtiges Weiß[/color]. Beachten Sie, dass der Alphakanal die letzte Komponente des Farbcodes ist, nicht die erste. Kurze RGBA-Farbcodes wie #6f28 (entspricht #66ff2288) werden ebenfalls unterstützt.

Zellenoptionen

  • expand

    Values

    Integer-Zahl

    Default

    1

    Verhältnis der Zellenexpansion. Damit wird festgelegt, welche Zellen versuchen werden, proportional zu anderen Zellen und deren Expansionsverhältnis zu expandieren.

  • border

    Values

    Farbname oder Farbe im HEX-Format

    Default

    Vererben

    Farbe der Zellenränder.

  • bg

    Values

    Farbname oder Farbe im HEX-Format

    Default

    Vererben

    Hintergrundfarbe der Zelle. Für abwechselnde ungerade/gerade Zeilenhintergründe können Sie bg=odd_color,even_color verwenden.

Aufzählungszeichen für ungeordnete Listen

Standardmäßig verwendet der [ul]-Tag die Unicode-Glyphe U+2022 "Bullet" als Aufzählungszeichen. Dieses Verhalten ist ähnlich wie bei Webbrowsern. Das Aufzählungszeichen kann mit [ul bullet={bullet}] angepasst werden. Falls angegeben, muss der Parameter {bullet} ein einzelnes Zeichen ohne einschließende Anführungszeichen sein (zum Beispiel [bullet=*]). Zusätzliche Zeichen werden ignoriert. Die Breite des Aufzählungszeichens hat keinen Einfluss auf die Formatierung der Liste.

Siehe Aufzählungszeichen (Typografie) auf Wikipedia für eine Liste der üblichen Aufzählungszeichen, die Sie direkt in den Parameter Aufzählungszeichen einfügen können.

Geordnete Listenarten

Geordnete Listen können verwendet werden, um Elemente automatisch mit Zahlen oder Buchstaben in aufsteigender Reihenfolge zu markieren. Dieses Tag unterstützt die folgenden Typoptionen:

  • 1 - Zahlen, wenn möglich unter Verwendung eines sprachspezifischen Nummerierungssystems.

  • a, A - Lateinische Klein- und Großbuchstaben.

  • i, I - Römische Ziffern in Klein- und Großbuchstaben.

Text-Effekte

BBCode kann auch verwendet werden, um verschiedene Texteffekte zu erstellen, die optional animiert werden können. Fünf anpassbare Effekte sind standardmäßig vorhanden, und Sie können leicht Ihre eigenen erstellen. Standardmäßig pausieren animierte Effekte wenn der SceneTree angehalten wird. Sie können dieses Verhalten ändern, indem Sie die Property Prozess > Modus des RichTextLabel anpassen.

In allen folgenden Beispielen werden die Default-Werte für Optionen im aufgeführten Tag-Format angegeben.

Bemerkung

Texteffekte, von denen die Position der Zeichen verschoben werden, können dazu führen, dass die Zeichen von den Begrenzungen des RichTextLabel-Nodes abgeschnitten werden.

Sie können dieses Problem lösen, indem Sie Steuerung > Layout > Clip-Inhalt im Inspektor deaktivieren, nachdem Sie den RichTextLabel-Node ausgewählt haben, oder indem Sie sicherstellen, dass um den Text herum genügend Seitenrand hinzugefügt wird, indem Sie Zeilenumbrüche oberhalb und unterhalb der Zeile verwenden, die den Effekt nutzen.

Pulsieren

../../_images/bbcode_in_richtextlabel_effect_pulse.webp

Pulsieren erzeugt einen animierten, pulsierenden Effekt, der die Deckkraft und Farbe jedes Zeichens vervielfacht. Er kann verwendet werden, um die Aufmerksamkeit auf einen bestimmten Text zu lenken. Sein Tag-Format ist [pulse freq=1.0 color=#ffffff40 ease=-2.0]{text}[/pulse].

freq steuert die Frequenz des halben Pulszyklus (höher ist schneller). Ein voller Pulszyklus dauert 2 * (1.0 / freq) Sekunden. color ist der Zielfarben-Multiplikator für das Blinken. Der Default lässt den Text meist per Fading verblassen, aber nicht vollständig. ease ist der Exponent der Easing-Funktion, der verwendet werden soll. Negative Werte sorgen für ein In-Out-Easing, deshalb ist der Default -2.0.

Welle

../../_images/bbcode_in_richtextlabel_effect_wave.webp

Welle lässt den Text auf und ab wandern. Sein Tag-Format ist [wave amp=50.0 freq=5.0 connected=1]{text}[/wave].

amp bestimmt, wie hoch und tief der Effekt geht, und freq bestimmt, wie schnell sich der Text auf und ab bewegt. Ein freq Wert von 0 führt zu keinen sichtbaren Wellen, und negative freq Werte zeigen auch keine Wellen an. Ist connected gleich 1 (Default), werden Glyphen mit Ligaturen zusammengeschoben. Wenn connected den Wert 0 hat, wird jede Glyphe einzeln verschoben, auch wenn sie durch Ligaturen verbunden sind. Dies kann bestimmte Darstellungsprobleme bei Schriftarten mit Ligaturen umgehen.

Tornado

../../_images/bbcode_in_richtextlabel_effect_tornado.webp

Tornado lässt den Text in einem Kreis herumlaufen. Sein Tag-Format ist [tornado radius=10.0 freq=1.0 connected=1]{text}[/tornado].

radius ist der Radius des Kreises, der den Offset steuert, freq gibt an, wie schnell sich der Text im Kreis bewegt. Ein freq-Wert von 0 hält die Animation an, während ein negativer freq die Animation rückwärts abspielt. Wenn connected den Wert 1 hat (Default), werden Glyphen mit Ligaturen zusammen bewegt. Wenn connected gleich 0 ist, wird jede Glyphe einzeln bewegt, auch wenn sie durch Ligaturen verbunden sind. Dies kann bestimmte Darstellungsprobleme bei Schriftarten mit Ligaturen umgehen.

Schütteln

../../_images/bbcode_in_richtextlabel_effect_shake.webp

Schütteln lässt den Text wackeln. Sein Tag-Format ist [shake rate=20.0 level=5 connected=1]{text}[/shake].

rate bestimmt, wie schnell der Text wackelt, level bestimmt, wie weit der Text vom Ursprung entfernt ist. Ist connected gleich 1 (Default), werden Glyphen mit Ligaturen zusammen verschoben. Wenn connected den Wert 0 hat, wird jede Glyphe einzeln verschoben, auch wenn sie durch Ligaturen verbunden sind. Dies kann bestimmte Darstellungsprobleme bei Schriftarten mit Ligaturen umgehen.

Fading

../../_images/bbcode_in_richtextlabel_effect_fade.webp

Fading erzeugt einen statischen Fading-Effekt, der die Deckkraft jedes Zeichens vervielfacht. Sein Tag-Format ist [fade start=4 length=14]{text}[/fade].

start steuert die Startposition des Fadings relativ zu der Stelle, wo der Fade-Befehl eingefügt wird, Länge steuert, über wie viele Zeichen das Fading erfolgen soll.

Regenbogen

../../_images/bbcode_in_richtextlabel_effect_rainbow.webp

Regenbogen verleiht dem Text eine Regenbogenfarbe, die sich mit der Zeit ändert. Sein Tag-Format ist [rainbow freq=1.0 sat=0.8 val=0.8]{text}[/rainbow].

freq ist die Anzahl der vollen Regenbogenzyklen pro Sekunde, sat ist die Sättigung des Regenbogens, val ist der Wert des Regenbogens. Ein freq-Wert von 0 hält die Animation an, während ein negativer freq die Animation rückwärts abspielt.

Die Konturen der Schriftarten werden vom Regenbogeneffekt nicht beeinflusst (sie behalten ihre ursprüngliche Farbe). Vorhandene Schriftarten werden durch den Regenbogeneffekt außer Kraft gesetzt. Die Propertys Modulieren und Selbstmodulieren von CanvasItem beeinflussen jedoch das Aussehen des Regenbogeneffekts, da die Modulation die endgültigen Farben vervielfacht.

Eigene BBCode-Tags und -Texteffekte

Sie können den Ressourcentyp RichTextEffect erweitern, um Ihre eigenen BBCode-Tags zu erstellen. Erstellen Sie eine neue Skriptdatei, die den Ressourcentyp RichTextEffect erweitert und geben Sie dem Skript einen class_name, damit der Effekt im Inspektor ausgewählt werden kann. Fügen Sie die Annotation @tool zu Ihrer GDScript-Datei hinzu, wenn Sie diese benutzerdefinierten Effekte im Editor selbst laufen lassen wollen. Das RichTextLabel muss nicht mit einem Skript verbunden sein, noch muss es im tool-Modus laufen. Der neue Effekt kann im Inspektor registriert werden, indem man ihn dem Array Markup > Benutzerdefinierte Effekte hinzufügt, oder im Code mit der Methode install_effect():

Auswählen eines benutzerdefinierten RichTextEffects nach dem Speichern eines Skripts, das RichTextEffect mit einem ``class_name`` erweitert

Auswählen eines benutzerdefinierten RichTextEffects nach dem Speichern eines Skripts, das RichTextEffect mit einem class_name erweitert

Warnung

Wenn der benutzerdefinierte Effekt nicht in der Property Markup > Benutzerdefinierte Effekte des RichTextLabels registriert ist, ist kein Effekt sichtbar und der ursprüngliche Tag wird unverändert belassen.

Es gibt nur eine einzige Funktion, die Sie erweitern müssen: _process_custom_fx(char_fx). Optional können Sie auch einen benutzerdefinierten BBCode-Bezeichner bereitstellen, indem Sie einfach einen Membernamen bbcode hinzufügen. Der Code wird die Property bbcode automatisch überprüfen oder den Namen der Datei verwenden, um zu bestimmen, wie der BBCode-Tag lauten soll.

_process_custom_fx

Hier findet die Logik jedes Effekts statt und wird einmal pro Glyphe während der Zeichenphase der Textdarstellung aufgerufen. Dabei wird ein CharFXTransform-Objekt übergeben, das einige Variablen enthält, die steuern, wie die zugehörige Glyphe gerendert wird:

  • identity gibt an, welcher benutzerdefinierte Effekt verarbeitet wird. Sie sollten das für die Code-Flusskontrolle verwenden.

  • outline ist true , wenn der Effekt zum Zeichnen des Textumrisses aufgerufen wird.

  • range sagt Ihnen, wie weit Sie sich als Index in einem gegebenen benutzerdefinierten Effektblock befinden.

  • elapsed_time ist die Gesamtzeit, die der Texteffekt ausgeführt wurde.

  • Mit visible können Sie feststellen, ob die Glyphe sichtbar ist oder nicht, und Sie können einen bestimmten Teil des Textes ausblenden.

  • offset ist eine Offset-Position relativ zu der Stelle, an der die angegebene Glyphe unter normalen Umständen dargestellt werden sollte.

  • color ist die Farbe einer bestimmten Glyphe.

  • glyph_index und font ist die Glyphe, die gezeichnet wird und die Schriftdaten-Ressource, die zum Zeichnen verwendet wird.

  • Schließlich ist env ein Dictionary mit Parametern, die einem bestimmten benutzerdefinierten Effekt zugeordnet sind. Sie können get() mit einem optionalen Defaultwert verwenden, um jeden Parameter abzurufen, falls vom Benutzer angegeben. Zum Beispiel würde [custom_fx spread=0.5 color=#FFFF00]test[/custom_fx] einen float spread und Color color-Parameter in seinem env-Dictionary haben. Siehe unten für weitere Anwendungsbeispiele.

Der letzte Punkt, der bei dieser Funktion zu beachten ist: Ein boolescher true-Wert muss zurückgegeben werden, um zu überprüfen, ob der Effekt korrekt verarbeitet wurde. Wenn es also ein Problem mit der Darstellung einer bestimmten Glyphe gibt, wird die Funktion die Darstellung von benutzerdefinierten Effekten komplett abbrechen, bis der Benutzer den Fehler in seiner benutzerdefinierten Effektlogik behoben hat.

Hier sind einige Beispiele benutzedefinierter Effekte:

Geist

@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

Matrix

@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

Dadurch werden einige neue BBCode-Befehle hinzugefügt, die wie folgt verwendet werden können:

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