Up to date

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

String

字符串内置类型。

描述

这是内置的字符串 Variant 类型（GDScript 使用的就是这个类型）。字符串中可以包含任意数量的 Unicode 字符，暴露的方法可用于字符串的操作和生成。字符串有引用计数，使用写时复制技术（每次对字符串的修改都会返回新的 String），所以传递字符串的资源损耗很小。

部分字符串方法有对应的变体。后缀 n 的变体（countn、findn、replacen 等）大小写不敏感（不区分大写字符和小写字符）。前缀 r 的方法变体（rfind、rsplit 等）是逆序的，会从字符串末尾开始，而不是从开头开始。

注意：在布尔语境下，空字符串（""）的求值结果为 false。否则字符串的求值结果始终为 true。无法使用 not 运算符。检查空字符串请使用 is_empty。

备注

通过 C# 使用这个 API 时有显著的不同。详见 C# API 与 GDScript 的差异。

教程

• GDScript 格式字符串

构造函数

String	String ( )
String	String ( String from )
String	String ( NodePath from )
String	String ( StringName from )

方法

bool	begins_with ( String text ) const
PackedStringArray	bigrams ( ) const
int	bin_to_int ( ) const
String	c_escape ( ) const
String	c_unescape ( ) const
String	capitalize ( ) const
int	casecmp_to ( String to ) const
String	chr ( int char ) static
bool	contains ( String what ) const
int	count ( String what, int from=0, int to=0 ) const
int	countn ( String what, int from=0, int to=0 ) const
String	dedent ( ) const
bool	ends_with ( String text ) const
String	erase ( int position, int chars=1 ) const
int	find ( String what, int from=0 ) const
int	findn ( String what, int from=0 ) const
String	format ( Variant values, String placeholder="{_}" ) const
String	get_base_dir ( ) const
String	get_basename ( ) const
String	get_extension ( ) const
String	get_file ( ) const
String	get_slice ( String delimiter, int slice ) const
int	get_slice_count ( String delimiter ) const
String	get_slicec ( int delimiter, int slice ) const
int	hash ( ) const
PackedByteArray	hex_decode ( ) const
int	hex_to_int ( ) const
String	humanize_size ( int size ) static
String	indent ( String prefix ) const
String	insert ( int position, String what ) const
bool	is_absolute_path ( ) const
bool	is_empty ( ) const
bool	is_relative_path ( ) const
bool	is_subsequence_of ( String text ) const
bool	is_subsequence_ofn ( String text ) const
bool	is_valid_filename ( ) const
bool	is_valid_float ( ) const
bool	is_valid_hex_number ( bool with_prefix=false ) const
bool	is_valid_html_color ( ) const
bool	is_valid_identifier ( ) const
bool	is_valid_int ( ) const
bool	is_valid_ip_address ( ) const
String	join ( PackedStringArray parts ) const
String	json_escape ( ) const
String	left ( int length ) const
int	length ( ) const
String	lpad ( int min_length, String character=" " ) const
String	lstrip ( String chars ) const
bool	match ( String expr ) const
bool	matchn ( String expr ) const
PackedByteArray	md5_buffer ( ) const
String	md5_text ( ) const
int	naturalcasecmp_to ( String to ) const
int	naturalnocasecmp_to ( String to ) const
int	nocasecmp_to ( String to ) const
String	num ( float number, int decimals=-1 ) static
String	num_int64 ( int number, int base=10, bool capitalize_hex=false ) static
String	num_scientific ( float number ) static
String	num_uint64 ( int number, int base=10, bool capitalize_hex=false ) static
String	pad_decimals ( int digits ) const
String	pad_zeros ( int digits ) const
String	path_join ( String file ) const
String	repeat ( int count ) const
String	replace ( String what, String forwhat ) const
String	replacen ( String what, String forwhat ) const
String	reverse ( ) const
int	rfind ( String what, int from=-1 ) const
int	rfindn ( String what, int from=-1 ) const
String	right ( int length ) const
String	rpad ( int min_length, String character=" " ) const
PackedStringArray	rsplit ( String delimiter="", bool allow_empty=true, int maxsplit=0 ) const
String	rstrip ( String chars ) const
PackedByteArray	sha1_buffer ( ) const
String	sha1_text ( ) const
PackedByteArray	sha256_buffer ( ) const
String	sha256_text ( ) const
float	similarity ( String text ) const
String	simplify_path ( ) const
PackedStringArray	split ( String delimiter="", bool allow_empty=true, int maxsplit=0 ) const
PackedFloat64Array	split_floats ( String delimiter, bool allow_empty=true ) const
String	strip_edges ( bool left=true, bool right=true ) const
String	strip_escapes ( ) const
String	substr ( int from, int len=-1 ) const
PackedByteArray	to_ascii_buffer ( ) const
String	to_camel_case ( ) const
float	to_float ( ) const
int	to_int ( ) const
String	to_lower ( ) const
String	to_pascal_case ( ) const
String	to_snake_case ( ) const
String	to_upper ( ) const
PackedByteArray	to_utf8_buffer ( ) const
PackedByteArray	to_utf16_buffer ( ) const
PackedByteArray	to_utf32_buffer ( ) const
PackedByteArray	to_wchar_buffer ( ) const
String	trim_prefix ( String prefix ) const
String	trim_suffix ( String suffix ) const
int	unicode_at ( int at ) const
String	uri_decode ( ) const
String	uri_encode ( ) const
String	validate_filename ( ) const
String	validate_node_name ( ) const
String	xml_escape ( bool escape_quotes=false ) const
String	xml_unescape ( ) const

操作符

bool	operator != ( String right )
bool	operator != ( StringName right )
String	operator % ( Variant right )
String	operator + ( String right )
String	operator + ( StringName right )
bool	operator < ( String right )
bool	operator <= ( String right )
bool	operator == ( String right )
bool	operator == ( StringName right )
bool	operator > ( String right )
bool	operator >= ( String right )
String	operator [] ( int index )

---

构造函数说明

String String ( )

构造空的 String（""）。

---

String String ( String from )

构造给定 String 的副本。

---

String String ( NodePath from )

从给定的 NodePath 构造新的 String。

---

String String ( StringName from )

从给定的 StringName 构造新 String。

---

方法说明

bool begins_with ( String text ) const

如果该字符串以给定的 text 开始，则返回 true。另见 ends_with。

---

PackedStringArray bigrams ( ) const

返回包含该字符串的双字母组（连续字母的组合）的数组。

print("Get up!".bigrams()) # 输出 ["Ge", "et", "t ", " u", "up", "p!"]

---

int bin_to_int ( ) const

将表示二进制数的字符串转换为 int。该字符串可以前缀 "0b"，负数可以前缀 -。

GDScriptC#

print("101".bin_to_int())   # 输出 5
print("0b101".bin_to_int()) # 输出 5
print("-0b10".bin_to_int()) # 输出 -2

---

String c_escape ( ) const

返回该字符串的副本，按照 C 语言标准对特殊字符进行转义。

---

String c_unescape ( ) const

返回该字符串的副本，转义字符均使用本义代替。支持的转义序列有 \'、\"、\\、\a、\b、\f、\n、\r、\t、\v。

注意：与 GDScript 解析器不同，这个方法不支持 \uXXXX 转义序列。

---

String capitalize ( ) const

改变字符串的外观：用空格代替下划线（_），在单词中间的大写字母前添加空格，将所有字母转换为小写，然后将第一个字母和空格后的每个字母转换为大写。

GDScriptC#

"move_local_x".capitalize()   # 返回 "Move Local X"
"sceneFile_path".capitalize() # 返回 "Scene File Path"

注意：这个方法与检查器面板中属性的默认外观不一样，不会像你期望的那样将首字母缩写大写（"2D"、"FPS"、"PNG" 等）。

---

int casecmp_to ( String to ) const

与另一个字符串进行比较，区分大小写。小于时返回 -1、大于时返回 1、等于时返回 0。“小于”和“大于”比较的是字符串中的 Unicode 码位，大致与字母表顺序一致。

如果字符串长度不同，这个字符串比 to 字符串长时返回 1，短时返回 -1。请注意空字符串的长度始终为 0。

如果想在比较字符串时获得 bool 返回值，请改用 == 运算符。另见 nocasecmp_to、naturalcasecmp_to 和 naturalnocasecmp_to。

---

String chr ( int char ) static

根据十进制数 char 返回单一 Unicode 字符。你可以用 unicodelookup.com 和 unicode.org 作为参考。

print(String.chr(65))     # 输出 "A"
print(String.chr(129302)) # 输出 "🤖"（机器人脸 Emoji）

---

bool contains ( String what ) const

如果该字符串包含 what，则返回 true。在 GDScript 中对应 in 运算符。

GDScriptC#

print("Node".contains("de")) # 输出 true
print("team".contains("I"))  # 输出 false
print("I" in "team")         # 输出 false

如果想要知道 what 在该字符串中的位置，请使用 find。

---

int count ( String what, int from=0, int to=0 ) const

返回子串 what 在 from 和 to 位置之间出现的次数。如果 to 为 0，会在剩余字符串中继续搜索。

---

int countn ( String what, int from=0, int to=0 ) const

返回子串 what 在 from 和 to 位置之间出现的次数，忽略大小写。如果 to 为 0，会在剩余字符串中继续搜索。

---

String dedent ( ) const

返回删除了缩进（前导制表符和空格）的字符串副本。添加缩进请参阅 indent。

---

bool ends_with ( String text ) const

如果该字符串以给定的 text 结束，则返回 true。另见 begins_with。

---

String erase ( int position, int chars=1 ) const

返回从 position 开始擦除 chars 个字符后的字符串。如果在指定 position 的基础上 chars 超过字符串的长度，返回的字符串中擦除的字符数会少于请求的数量。如果 position 或 chars 为负数，则返回空字符串。如果 chars 为 0 则返回原字符串，不进行修改。

---

int find ( String what, int from=0 ) const

返回 what 在该字符串中第一次出现的索引，如果不存在则返回 -1。搜索的起点可以用 from 指定，持续到字符串结尾。

GDScriptC#

print("Team".find("I")) # 输出 -1

print("Potato".find("t"))    # 输出 2
print("Potato".find("t", 3)) # 输出 4
print("Potato".find("t", 5)) # 输出 -1

注意：如果你只是想要知道该字符串中是否包含 what，请使用 contains。在 GDScript 中，你还可以使用 in 运算符。

---

int findn ( String what, int from=0 ) const

返回这个字符串中 what 首次出现的索引，不区分大小写，不存在时则为 -1。搜索的起点可以用 from 指定，终点为该字符串的末尾。

---

String format ( Variant values, String placeholder="{_}" ) const

通过将所有出现的 placeholder 替换为 values 的元素来格式化字符串。

values 可以是 Dictionary 或 Array。placeholder 中的任何下划线将被预先被替换为对应的键。数组元素使用它们的索引作为键。

# 输出：Waiting for Godot 是 Samuel Beckett 的戏剧，Godot 引擎由此得名。
var use_array_values = "Waiting for {0} 是 {1} 的戏剧，{0} 引擎由此得名。"
print(use_array_values.format(["Godot", "Samuel Beckett"]))

# 输出：第 42 号用户是 Godot。
print("第 {id} 号用户是 {name}。".format({"id": 42, "name": "Godot"}))

当 values 是 Array 时还会执行一些额外的处理。 如果 placeholder 不包含下划线，则 values 数组的元素将用于按顺序替换出现的占位符；如果 values 的元素是另一个 2 元素数组，则它将被解释为键值对。

# 输出：第 42 号用户是 Godot。
print("第 {} 号用户是 {}。".format([42, "Godot"], "{}"))
print("第 {id} 号用户是 {name}。".format([["id", 42], ["name", "Godot"]]))

另请参阅 GDScript 格式化字符串教程。

注意：在 C# 中推荐改为使用“$”插入字符串。

---

String get_base_dir ( ) const

如果该字符串是有效的文件路径，则返回基础目录名称。

var dir_path = "/path/to/file.txt".get_base_dir() # dir_path 为 "/path/to"

---

String get_basename ( ) const

如果该字符串是有效的文件路径，则返回完整文件路径，不包括扩展名。

var base = "/path/to/file.txt".get_basename() # base 为 "/path/to/file"

---

String get_extension ( ) const

如果该字符串是有效的文件名或路径，则返回该文件的扩展名，不含开头的点号（.）。否则返回空字符串。

var a = "/path/to/file.txt".get_extension() # a 为 "txt"
var b = "cool.txt".get_extension()          # b 为 "txt"
var c = "cool.font.tres".get_extension()    # c 为 "tres"
var d = ".pack1".get_extension()            # d 为 "pack1"

var e = "file.txt.".get_extension()  # e 为 ""
var f = "file.txt..".get_extension() # f 为 ""
var g = "txt".get_extension()        # g 为 ""
var h = "".get_extension()           # h 为 ""

---

String get_file ( ) const

如果该字符串是有效的文件路径，则返回文件名，包括扩展名。

var file = "/path/to/icon.png".get_file() # file 为 "icon.png"