Up to date

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

GDScript 格式字串

GDScript 提供了 格式化字串 功能,通過格式化字串能重複使用一個文字樣板,並尷尬地建立類似但不同的字串。

格式化字串就像普通的字串,但格式化字串包含了特定的預留位置字元順序。這些預留位置能夠通過將參數傳遞給格式化字串來替換掉。

例如,若使用 %s 作為預留位置,格式化字串 "你好 %s,你吃飽沒?" 就能簡單地換成 "你好 世界,你吃飽沒?" 。可以注意到,預留位置在字串的中間,若不使用格式化字串來處理就會變得很麻煩。

在 GDScript 中使用

來看看這個實際的 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 是最簡單的預留位置,適用於大部分的情況。 %s 會以與 str() 轉換字串相同的方法將數值轉換為字串。若數值為字串則會保持相同,布林會轉為 "True""False" ,整數或實數則會轉為十進位值,其餘型別則通常會將資料轉換為人類看得懂的字串。

GDScript 中還有另一個格式化文字的方法,即 String.format() 方法。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"

還有其他的 格式規範 ,但其他格式規範只有 % 運算元才可以用。

多預留位置

格式化字串可以包含多個預留位置。這時,數值必須以陣列形式來傳遞,一個數值一個預留位置 (除非使用 * 格式規範,請參見 動態填充 ):

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

使用與字串轉換方式相同的方法, 單純 將數值轉為字串。

c

單一 Unicode 字元 。需要輸入無號 8 位元整數 (0-255) 作為字碼指標或單一字元字串。

d

十進位整數 數字。需要輸入一個整數或實數 (實數將無條件捨去)。

o

八進位整數 數字。需要輸入一個整數或實數 (實數將無條件捨去)。

x

使用 小寫字母十六進位整數 數字。需要輸入一個整數或實數 (實數將無條件捨去)。

X

使用 大寫字母十進位整數 數字。需要輸入一個整數或實數 (實數將無條件捨去)。

f

十進位實數 。需要輸入一個整數或實數。

v

A vector. Expects any float or int-based vector object ( Vector2, Vector3, Vector4, Vector2i, Vector3i or Vector4i). Will display the vector coordinates in parentheses, formatting each coordinate as if it was an %f, and using the same modifiers.

預留位置修飾元

這些字元放置於上表中字串的前面。有部分修飾元只能在特定情況下使用。

+

在數字格式規範中,若為正數則 顯示 + 號

整數

設定 填充。若該整數以 0 開頭則以 0 填充,否則以空白填充。若在 . 後使用,請參見 .

.

Before f or v, set precision to 0 decimal places. Can be followed up with numbers to change. Padded with zeroes.

-

向右填充 ,而非向左。

*

動態填充 ,需要配合額外的整數參數來設定 . 後的填充或精度,請參見 動態填充

填充

. (), * (星號), - (減號) 與數字 (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%"

格式化方法範例

下列為各種呼叫 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