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

GDScript 格式化字串

Godot 提供多種方式可動態變更字串內容：

• 格式化字串： var string = "I have %s cats." % "3"

• String.format() 方法： var string = "I have {0} cats.".format([3])

• 字串串接： var string = "I have " + str(3) + " cats."

本頁將說明如何使用格式化字串，並簡單介紹 format() 方法與字串串接。

格式化字串

格式化字串 是用來重複利用文字樣板，簡潔地產生不同但類似字串的方法。

格式化字串和一般字串類似，只是它們包含像 %s 這樣的預留位置符號。這些預留位置可由傳入的參數取代。

來看看這個實際的 GDScript 範例：

# 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."

預留位置總是以 % 開頭，接下來的字元稱為 格式規範，決定該值如何被轉換為字串。

上方範例中的 %s 是最簡單的預留位置，適用於大多數情境：它會以隱式 String 轉型或 str() 相同的方式轉換值。字串會保持不變，布林值會變成 "True" 或 "False"，整數或浮點數會轉為十進位，其他類型則會轉為人類可讀的字串。

還有其他 格式規範 可用。

多重預留位置

格式化字串可以包含多個預留位置。此時，參數需以陣列方式傳入，每個預留位置對應一個值（除非使用 * 格式規範，請見 動態填充）：

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

注意值會依序插入。請記得所有預留位置必須一次填滿，因此需要有正確數量的值。

格式規範

除了 s 之外，預留位置還可以使用其他格式規範。格式規範可以是一個或多個字元。有些像 s 一樣獨立使用，有些要搭配其他字元，有些則只適用於特定數值或字元。

預留位置類型

格式規範最後一定要有下表其中一個（且僅能有一個）。除了 s 之外，其他規範都需要特定型別的參數。

s	單純 以隱式 String 轉型的方式轉換為字串。
c	單一的 Unicode 字元。接受 Unicode 碼位（整數）或單一字元的字串。支援超過 255 的值。
d	十進位整數。需傳入整數或浮點數（小數部分會被無條件捨去）。
o	八進位整數。需傳入整數或浮點數（小數部分會被無條件捨去）。
x	小寫 字母的 十六進位整數。需傳入整數或浮點數（小數部分會被無條件捨去）。
X	大寫 字母的 十六進位整數。需傳入整數或浮點數（小數部分會被無條件捨去）。
f	十進位實數。需傳入整數或浮點數。
v	向量。需傳入任一以整數或浮點數為基礎的向量物件（如 Vector2、Vector3、Vector4、Vector2i、Vector3i 或 Vector4i）。會以括號顯示向量座標，每個座標會以 %f 方式格式化，且可套用相同修飾元。

預留位置修飾元

這些字元要放在格式規範前面。有些只在特定情況下有效。

+	在數字格式規範中，若為正數則 顯示 + 號。
整數	設定 填充。若在整數或實數預留位置中以 0 開頭，則以 0 填充，否則以空白填充。若同時有 -，則忽略前導 0。若用於 . 之後，請見 . 說明。
.	在 f 或 v 前面時，將 精度 設為 0 小數位。可以在後面加數字更改小數位數。以 0 進行填充。
-	向右填充，而非向左填充。
*	動態填充，會預期額外的整數參數來設定填充或 . 後的精度，請見 動態填充。

填充

.``（點）、``*``（星號）、-（減號）及數字（``0-9）可用於填充。若搭配等寬字型，可讓多個值垂直對齊，像表格一樣。

若要將字串填充至最小長度，可在格式規範中加整數：

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

若整數以 0 開頭，則會以 0 填充整數值，而非空白：

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

對於實數，可在格式規範中加上 .``（點）及整數來指定精度。若 ``. 後未加數字，則精度為 0（四捨五入為整數）。用來填充的整數必須寫在點之前。

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

- 字元會讓填充改為向右（右對齊），方便右側對齊字串：

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

動態填充

使用 * （星號）可讓你不用修改格式化字串本身，就能動態設定填充或精度。它會取代格式規範中的整數，並於格式化時傳入填充或精度的數值：

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

若要在整數預留位置用 0 填充，則可在 * 前加上 0：

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

跳脫字元

若要將字面上的 % 字元插入格式化字串，必須跳脫它，避免被解析為預留位置。這可透過連續輸入兩個 % 達成：

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

字串格式化方法

GDScript 也支援另一種格式化字串的方式，就是 String.format() 方法。它會將字串中出現的所有索引鍵，替換為對應的值。這個方法可以處理陣列或字典型態的索引鍵／值組。

陣列可以作為索引鍵、索引，或混合樣式使用（請見下方範例）。只有在用索引或混合樣式時才需注意順序。

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"

格式化方法範例

以下展示各種方式呼叫 String.format() 方法的範例。

型別	樣式	範例	結果
字典	索引鍵	"你好，{name} v{version}！".format({"name":"Godette", "version":"3.0"})	你好，Godette v3.0！
字典	索引	"你好，{0} v{1}！".format({"0":"Godette", "1":"3.0"})	你好，Godette v3.0！
字典	混合	"你好，{0} v{version}！".format({"0":"Godette", "version":"3.0"})	你好，Godette v3.0！
陣列	索引鍵	"你好，{name} v{version}！".format([["version","3.0"], ["name","Godette"]])	你好，Godette v3.0！
陣列	索引	"你好，{0} v{1}！".format(["Godette","3.0"])	你好，Godette v3.0！
陣列	混合	"你好，{name} v{0}！".format(["3.0", ["name","Godette"]])	你好，Godette v3.0！
陣列	無索引	"你好，{} v{}！".format(["Godette", "3.0"], "{}")	你好，Godette v3.0！

在使用 String.format 時也能自訂預留位置，下列為相關功能範例。

型別	範例	結果
中置（預設）	"你好，{0} v{1}".format(["Godette", "3.0"], "{_}")	你好，Godette v3.0
後置	"你好，0% v1%".format(["Godette", "3.0"], "_%")	你好，Godette v3.0
前置	"你好，%0 v%1".format(["Godette", "3.0"], "%_")	你好，Godette v3.0

有時可以同時使用 String.format 方法與 % 運算子，因為 String.format 無法直接調整數字格式。

範例	結果
"你好，{0} v{version}".format({0:"Godette", "version":"%0.2f" % 3.114})	你好，Godette v3.11

字串串接

你也可以用 + 運算子來將字串 串接 在一起。

# Define a base string
var base_string = "We're waiting for "

# Concatenate the string
var actual_string = base_string + "Godot"

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

在使用字串串接時，非字串的值必須先用 str() 函式轉換。這種方式無法指定轉換後數值的格式。

var name_string = "Godette"
var version = 3.0
var actual_string = "Hi, " + name_string + " v" + str(version) + "!"

print(actual_string)
# Output: "Hi, Godette v3!"

由於上述限制，格式化字串或 format() 方法通常會是更好的選擇。很多時候，字串串接也較難閱讀。

備註

在 Godot 的 C++ 程式碼中，可以透過 Variant 標頭裡的 vformat() 輔助函式來存取 GDScript 格式化字串。