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.

Note that the BBCode tags can also be used to some extent for other use cases:

• BBCode can be used to format comments in the XML source of the class reference.

• BBCode can be used in GDScript documentation comments.

• BBCode can be used when printing rich text to the Output bottom panel.

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.

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

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)

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

Siehe auch

Einige dieser BBCode-Tags können in Tooltips für @export-Skriptvariablen sowie in der XML-Quelle der Klassenreferenz verwendet werden. Weitere Informationen finden Sie unter Klassenreferenz BBCode.

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]
char Fügt Unicode-Zeichen mit hexadezimalem UTF-32 {codepoint} hinzu.	[char={codepoint}]
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. Fügen Sie % am Ende des {width}- oder {height}-Wertes hinzu, um ihn als Prozentsatz der Breite des Steuerelements anstelle von Pixeln anzugeben. Wenn die Konfiguration {valign} angegeben ist, wird das Bild versuchen, sich an dem umgebenden Text auszurichten, siehe Vertikale Ausrichtung von Bildern und Tabellen. 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. 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={size} color={color} outline_size={size} outline_color={color} margins={left},{top},{right},{bottom}]{text}[/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={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 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={code/name}]{text}[/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={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. Wenn die Konfiguration {valign} angegeben ist, wird das Bild versuchen, sich an dem umgebenden Text auszurichten, siehe Vertikale Ausrichtung von Bildern und Tabellen. Wenn die Grundlinienausrichtung verwendet wird, wird die Tabelle an der Grundlinie der Zeile mit dem Index {alignment_row} (nullbasiert) ausgerichtet.	[table={number}]{cells}[/table] [table={number},{valign}]{cells}[/table] [table={number},{valign},{alignment_row}]{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 (oder l), center (oder c), right (oder r), fill (oder f)
  Default	left

  Horizontale Ausrichtung des Textes.

• bidi_override, st

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

  Überschreiben von strukturiertem Text.

• justification_flags, jst

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

  Ausrichtungsoption (Füllungsausrichtung). Siehe TextServer für weitere Details.

• direction, dir

  Values	ltr (oder l), rtl (oder r), auto (oder a)
  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 runtime.
    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	Integer-Zahl
  Default	Vererben

  Zielhöhe des Bildes in Pixeln, fügen Sie % am Ende des Wertes hinzu, um sie als Prozentsatz der Kontrollbreite statt in Pixeln anzugeben.

• width

  Values	Integer-Zahl
  Default	Vererben

  Zielbreite des Bildes, fügen Sie % am Ende des Wertes hinzu, um sie als Prozentsatz der Kontrollbreite statt als Pixel anzugeben.

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

• pad

  Values	false, true
  Default	false

  Wenn diese Option auf true gesetzt ist und das Bild kleiner als die durch width und height angegebene Größe ist, wird Bild-Padding hinzugefügt, um die Größe anzupassen, anstatt es hochzuskalieren.

• tooltip

  Values	String
  Default

  Bild-Tooltip.

Vertikale Ausrichtung von Bildern und Tabellen

When a vertical alignment value is provided with the [img] or [table] tag the image/table will try to align itself against the surrounding text. Alignment is performed using a vertical point of the image and a vertical point of the text. There are 3 possible points on the image (top, center, and bottom) and 4 possible points on the text and table (top, center, baseline, and bottom), which can be used in any combination.

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

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.

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.

• glyph_spacing, gl

  Values	Anzahl in Pixeln.
  Default	Vererben

  Zusätzliche Abstände für jede Glyphe.

• space_spacing, sp

  Values	Anzahl in Pixeln.
  Default	Vererben

  Zusätzlicher Abstand für das Leerzeichen.

• top_spacing, top

  Values	Anzahl in Pixeln.
  Default	Vererben

  Zusätzlicher Abstand am Anfang der Zeile.

• bottom_spacing, bt

  Values	Anzahl in Pixeln.
  Default	Vererben

  Zusätzlicher Abstand am unteren Ende der Zeile.

• embolden, emb

  Values	Float-Zahl.
  Default	0.0

  Die Stärke des Fettdrucks der Schrift, wenn sie ungleich Null ist, werden die Konturen der Schrift fett gedruckt. Negative Werte verringern die Konturstärke.

• face_index, fi

  Values	Integer-Zahl.
  Default	0

  Ein aktiver Flächenindex in der TrueType/OpenType-Sammlung.

• slant, sln

  Values	Float-Zahl.
  Default	0.0

  Neigungsstärke der Schrift, bei positiven Werten werden die Glyphen nach rechts geneigt. Negative Werte nach links.

• opentype_variation, otv

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

  OpenType-Variationskoordinaten der Schriftart. Siehe OpenType Variations-Tags.

  Anmerkung: Der Wert sollte in " eingeschlossen werden, um die Verwendung von = darin zu ermöglichen:

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

• opentype_features, otf

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

  OpenType-Features der Schriftart. Siehe OpenType Features-Tags.

  Anmerkung: Der Wert sollte in " eingeschlossen werden, um die Verwendung von = darin zu ermöglichen:

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

Benannte Farben

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

See this image for a list of color constants:

View at full size

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.

• padding

  Values	4 comma-separated floating-point numbers (no space after each comma)
  Default	0,0,0,0

  Linkes, oberes, rechtes und unteres Zellen-Padding.

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

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

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

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

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

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

Rainbow gives the text a rainbow color that changes over time. Its tag format is [rainbow freq=1.0 sat=0.8 val=0.8 speed=1.0]{text}[/rainbow].

freq determines how many letters the rainbow extends over before it repeats itself, sat is the saturation of the rainbow, val is the value of the rainbow. speed is the number of full rainbow cycles per second. A positive speed value will play the animation forwards, a value of 0 will pause the animation, and a negative speed value will play the animation backwards.

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

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.

There is only one function that you need to extend: _process_custom_fx(char_fx). Optionally, you can also provide a custom BBCode identifier by adding a member name bbcode. The code will check the bbcode property automatically or will use the name of the file to determine what the BBCode tag should be.

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