Up to date

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

GDScript Format-Strings

GDScript bietet ein Funktion namens Format-Strings, die es ermöglicht, Textvorlagen wieder zu verwenden, um schnell unterschiedliche, aber ähnliche Strings zu erzeugen.

Format-Strings sind wie normale Strings, mit der Ausnahme, dass sie bestimmte Platzhalter für Zeichensequenzen enthalten. Diese Platzhalter können einfach durch Parameter im Format-String ersetzt werden.

Mit %s als Platzhalter kann zum Beispiel der Format-String "Hallo %s, wie geht es dir?" leicht in "Hallo Welt, wie geht es dir?" geändert werden. Beachten Sie, dass der Platzhalter in der Mitte des Strings steht; ohne Format-Strings wäre es umständlich, ihn zu ändern.

Verwendung in GDScript

Versuchen Sie, das folgende GDScript-Beispiel zu verstehen:

# Define a format string with placeholder '%s'
var format_string = "We're waiting for %s."

# Using the '%' operator, the placeholder is replaced with the desired value
var actual_string = format_string % "Godot"

print(actual_string)
# Output: "We're waiting for Godot."

Platzhalter starten immer mit einem %, aber das nächste oder die nächsten Zeichen, der Formatkennzeichner, legt fest, wie der gegebene Wert zu einem String konvertiert wird.

Das %s im Beispiel oben ist der einfachste Platzhalter und funktioniert in den meisten Fällen: er konvertiert den Wert mit der gleichen Methode, von der eine implizierte String-Konvertierung oder str() es konvertieren würde. Strings bleiben unverändert. Booleans schalten entweder in "True" oder "False", eine ganze oder reelle Zahl wird eine Dezimalzahl, andere Typen geben meist ihre Daten in einem lesbaren String zurück.

Es gibt auch einen anderen Weg, um Text in GDScript zu formatieren, nämlich die String.format()-Methode. Sie ersetzt alle Keys im String mit dem entsprechenden Wert. Die Methode kommt mit Arrays oder Dictionarys für die Key/Value-Paare klar.

Arrays können als Key, Index oder in gemischtem Stil (siehe Beispiele unten) vorkommen. Die Reihenfolge ist nur wichtig, wenn der Index oder der gemischte Stil des Arrays benutzt wird.

Ein kurzes Beispiel in GDScript:

# Define a format string
var format_string = "We're waiting for {str}"

# Using the 'format' method, replace the 'str' placeholder
var actual_string = format_string.format({"str": "Godot"})

print(actual_string)
# Output: "We're waiting for Godot"

Es gibt auch andere Formatbezeichner, aber diese sind nur anwendbar beim Benutzen des %-Operators.

Mehrere Platzhalter

Format-Strings können mehrere Platzhalter enthalten. In diesem Fall werden die Werte in der Form eines Arrays gehandhabt, ein Wert pro Platzhalter (außer es wird ein Formatbezeichner mit * genutzt, siehe dynamisches Padding):

var format_string = "%s was reluctant to learn %s, but now he enjoys it."
var actual_string = format_string % ["Estragon", "GDScript"]

print(actual_string)
# Output: "Estragon was reluctant to learn GDScript, but now he enjoys it."

Beachten Sie, dass die Werte der Reihe nach eingefügt werden. Denken Sie daran, dass alle Platzhalter auf einmal ersetzt werden müssen, es muss also eine angemessene Anzahl von Werten vorhanden sein.

Formatbezeichner

Es gibt weitere Formatbezeichner außer s, die in Platzhaltern genutzt werden können. Diese bestehen aus einem oder mehreren Zeichen. Manche funktionieren für sich alleine, wie s, manche stehen vor anderen Zeichen, wieder andere funktionieren in Verbindung mit bestimmten Werten oder Zeichen.

Platzhalter-Typen

Einer – und nur einer – dieser Platzhalter-Typen muss immer als letztes Zeichen in einem Formatbezeichner auftreten. Abgesehen von s werden bestimmte Parametertypen benötigt.

s

Einfache Konvertierung von einem String mit der selben Methode, die bei der impliziten String-Konvertierung verwendet wird.

c

Ein einzelnes Unicode-Zeichen. Erwartet ein unsigned 8-bit Integer (0-255) für einen Codepunkt oder einen String, der aus einem einzelnen Zeichen besteht.

d

Eine dezimale ganze Zahl. Erwartet eine ganze oder reelle Zahl (wird abgerundet).

o

Eine oktale ganze Zahl. Erwartet eine ganze oder reelle Zahl (wird abgerundet).

x

Eine hexadezimale ganze Zahl mit Kleinbuchstaben. Erwartet eine ganze oder reelle Zahl (wird abgerundet).

X

Eine hexadezimale ganz Zahl mit Großbuchstaben. Erwartet eine ganze oder reelle Zahl (wird abgerundet).

f

Eine reelle Dezimalzahl. Erwartet eine ganze oder reelle Zahl.

v

Ein Vektor. Erwartet ein beliebiges float- oder int-basiertes Vektorobjekt ( Vector2, Vector3, Vector4, Vector2i, Vector3i oder Vector4i). Zeigt die Vektorkoordinaten in Klammern an, wobei jede Koordinate so formatiert wird, als ob sie ein %f wäre, und die gleichen Modifikatoren verwendet werden.

Platzhalter-Modifikatoren

Diese Zeichen erscheinen vor den oben angegebenen. Einige davon funktionieren nur unter bestimmten Bedingungen.

+

Gibt bei Zahlen-Bezeichnern das ** "+"-Vorzeichen mit an**, falls die Zahl positiv ist.

Integer

Padding einstellen. Füllt bei einem Platzhalter für ganze oder reelle Zahlen den String mit Leerzeichen oder Nullen auf, wenn die ganze Zahl mit 0 beginnt. Die führende 0 wird ignoriert, wenn - vorhanden ist. Für die Verwendung nach . siehe ..

.

Vor f oder v, wird die Präzision auf 0 Dezimalstellen gesetzt. Zum Ändern können Zahlen angegeben werden. Wird aufgefüllt mit Nullen.

-

Rechts-Padding statt Links-Padding.

*

Dynamisches Padding, erwartet einen zusätzlichen ganzzahligen Parameter. Um das Padding oder die Genauigkeit nach . festzulegen, siehe dynamisches Padding.

Padding

Die Zeichen . (Punkt), * (Stern), - (Minuszeichen) und Ziffer (0-9) werden zum Padding verwendet. Auf diese Weise können mehrere Werte vertikal angeordnet werden, als wären sie in einer Spalte, sofern eine Schriftart mit fester Breite verwendet wird.

Um einen String auf eine Minimallänge zu padden, fügen Sie eine Ganzzahl zum Bezeichner hinzu:

print("%10d" % 12345)
# output: "     12345"
# 5 leading spaces for a total length of 10

Falls die Ganzzahl mit 0 beginnt, werden die Ganzzahlwerte mit Nullen aufgefüllt anstatt mit Leerzeichen:

print("%010d" % 12345)
# output: "0000012345"

Die Genauigkeit für reelle Zahlen kann durch das Hinzufügen von . (Punkt) und einer darauffolgenden Ganzzahl festgelegt werden. Ohne Ganzzahl nach . wird eine Genauigkeit von 0 genutzt, wobei auf einen ganzzahligen Wert gerundet wird. Die Anzahl der Füllzeichen muss vor dem Punkt angegeben werden.

# Pad to minimum length of 10, round to 3 decimal places
print("%10.3f" % 10000.5555)
# Output: " 10000.556"
# 1 leading space

Das Zeichen - führt zu einem Rechts-Padding statt einem Links-Padding, was nützlich ist für rechts ausgerichteten Text:

print("%-10d" % 12345678)
# Output: "12345678  "
# 2 trailing spaces

Dynamisches Padding

Mit dem Zeichen * (Stern) kann der Abstand oder die Genauigkeit festgelegt werden, ohne den Formatstring zu ändern. Es wird anstelle einer Ganzzahl im Formatbezeichner verwendet. Die Werte für Padding und Genauigkeit werden dann beim Formatieren übergeben:

var format_string = "%*.*f"
# Pad to length of 7, round to 3 decimal places:
print(format_string % [7, 3, 8.8888])
# Output: "  8.889"
# 2 leading spaces

Es ist weiterhin möglich, Ganzzahl-Platzhalter mit Nullen aufzufüllen, indem 0 vor * eingefügt wird:

print("%0*d" % [2, 3])
# Output: "03"

Escape-Sequenz

Um ein Zeichen % selbst in einen Format-String einzubauen, muss dieses „escaped“ werden, damit es nicht als Platzhalter aufgefasst wird. Dies schafft man durch das Verdoppeln des Zeichens:

var health = 56
print("Remaining health: %d%%" % health)
# Output: "Remaining health: 56%"

Beispiele für Formatierungsmethoden

Im Folgenden finden Sie einige Beispiele für die verschiedenen Aufrufarten der String.format-Methode.

Typ

Stil

Beispiel

Ergebnis

Dictionary

Key

"Hallo, {name} v{version}!".format({"name":"Godette", "version":"3.0"})

Hallo, Godette v3.0!

Dictionary

Index

"Hallo, {0} v{1}!".format({"0":"Godette", "1":"3.0"})

Hallo, Godette v3.0!

Dictionary

gemischt

"Hallo, {0} v{version}!".format({"0":"Godette", "version":"3.0"})

Hallo, Godette v3.0!

Array

Key

"Hallo, {name} v{version}!".format([["version":"3.0"], ["name":"Godette"]])

Hallo, Godette v3.0!

Array

Index

"Hallo, {0} v{1}!".format(["Godette","3.0"])

Hallo, Godette v3.0!

Array

gemischt

"Hallo, {name} v{0}!".format([3.0, ["name":"Godette"]])

Hallo, Godette v3.0!

Array

kein Index

"Hallo, {} v{}".format(["Godette", "3.0"], "{}")

Hallo, Godette v3.0!

Platzhalter können auch bei Verwendung von String.format angepasst werden, hier einige Beispiele zu dieser Funktionalität.

Typ

Beispiel

Ergebnis

Infix (Default)

"Hallo, {0} v{1}".format(["Godette", "3.0"], "{_}")

Hallo, Godette v3.0

Postfix

"Hallo, 0% v1%".format(["Godette", "3.0"], "_%")

Hallo, Godette v3.0

Präfix

"Hallo, %0 v%1".format(["Godette", "3.0"], "%_")

Hallo, Godette v3.0

Es kann sinnvoll sein, die String.format-Methode mit dem %-Operator zu kombinieren, da mit String.format keine Möglichkeit besteht, die Repräsentation von Zahlen zu beeinflussen.

Beispiel

Ergebnis

"Hallo, {0} v{version}".format({0:"Godette", "version":"%0.2f" % 3.114})

Hallo, Godette v3.11