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

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