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 是最简单的占位符, 并且适用于大多数用例: 它使用与隐式 String 转换相同的方法或 str() 转换值. 字符串保持不变, 布尔值变成 "True""False", 整数或实数变为小数, 其他类型通常以人类可读的字符串形式返回其数据.

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

还有其他 格式说明符, 但是它们仅在使用 % 操作符时适用.

多个占位符

格式字符串可能包含多个占位符. 在这种情况下, 这些值以数组的形式处理, 每个占位符一个值(除非使用带 * 的格式说明符, 请参见 动态填充):

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 转换的相同方法 简单 转换为 String.

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 方法的各种调用的一些示例.

类型

样式

示例

结果

字典

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

Hi, Godette v3.0!

字典

索引

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

Hi, Godette v3.0!

字典

混合

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

Hi, Godette v3.0!

数组

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

Hi, Godette v3.0!

数组

索引

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

Hi, Godette v3.0!

数组

混合

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

Hi, Godette v3.0!

数组

没有索引

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

Hi, Godette v3.0!

使用 String.format 时, 也可以自定义占位符, 这是该功能的一些示例.

类型

示例

结果

中缀(默认)

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

Hi, Godette v3.0

后缀

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

Hi, Godette v3.0

前缀

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

Hi, Godette v3.0

结合 String.format 方法和 运算符可能很有用, 因为 String.format 没有办法操纵数字的表示.

示例

结果

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

Hi, Godette v3.11