最后同步日期：2026-04-15 | Godot 官方原文 — format

format

定义

format 用来把一个带有占位符的"模板字符串"填充上具体的值。你可以把它想象成填空题：模板里留着一些"空位"（用 {} 或 {键名} 表示），format 会帮你把这些空位替换成真实的数据。

比如模板 "你好，{name}！"，配上 {"name": "小明"}，就变成了 "你好，小明！"。

函数签名

C#

// Godot.StringExtensions 方法
public static string Format(this string instance, Variant values)

GDScript

func format(values: Variant, placeholder: String = "{_}") -> String

参数说明

参数	类型	必需	默认值	说明
values	Variant	是	—	要填入占位符的值。可以是字典（Dictionary）、数组（Array）等
placeholder	String	否	"{_}"	仅 GDScript：自定义占位符的格式，默认用 {_} 表示

返回值

类型： string / String

返回把占位符替换成实际值之后的新字符串。原字符串不会被修改。

代码示例

基础用法

C#

using Godot;

public partial class FormatExample : Node
{
    public override void _Ready()
    {
        // 用数组按顺序填充占位符
        string template = "欢迎来到 {0}，当前版本是 {1}！";
        string result = template.Format(new Godot.Collections.Array { "Godot", "4.6" });
        GD.Print(result);
        // 运行结果: 欢迎来到 Godot，当前版本是 4.6！
    }
}

GDScript

extends Node

func _ready():
    # 用数组按顺序填充占位符
    var template := "欢迎来到 {0}，当前版本是 {1}！"
    var result := template.format(["Godot", "4.6"])
    print(result)
    # 运行结果: 欢迎来到 Godot，当前版本是 4.6！

实际场景：游戏中的提示信息

C#

using Godot;

public partial class GameHUD : Node
{
    public override void _Ready()
    {
        // 用字典按键名填充占位符（更清晰的写法）
        string template = "玩家 {name} 击败了 {enemy}，获得 {score} 分！";
        var data = new Godot.Collections.Dictionary
        {
            { "name", "勇者" },
            { "enemy", "巨龙" },
            { "score", 500 }
        };
        string result = template.Format(data);
        GD.Print(result);
        // 运行结果: 玩家 勇者 击败了 巨龙，获得 500 分！
    }
}

GDScript

extends Node

func _ready():
    # 用字典按键名填充占位符（更清晰的写法）
    var template := "玩家 {name} 击败了 {enemy}，获得 {score} 分！"
    var data := {
        "name": "勇者",
        "enemy": "巨龙",
        "score": 500
    }
    var result := template.format(data)
    print(result)
    # 运行结果: 玩家 勇者 击败了 巨龙，获得 500 分！

进阶用法：自定义占位符格式（仅 GDScript）与嵌套数组

C#

using Godot;

public partial class FormatAdvanced : Node
{
    public override void _Ready()
    {
        // 嵌套数组填充：每个子数组对应一组键值对
        // 格式为 [[key1, value1], [key2, value2], ...]
        string template = "你 picked up {item}！效果：{effect}";
        var data = new Godot.Collections.Array
        {
            new Godot.Collections.Array { "item", "治疗药水" },
            new Godot.Collections.Array { "effect", "恢复 50 HP" }
        };
        string result = template.Format(data);
        GD.Print(result);
        // 运行结果: 你 picked up 治疗药水！效果：恢复 50 HP

        // C# 中更推荐使用字符串插值
        string item = "治疗药水";
        string effect = "恢复 50 HP";
        string better = $"你 picked up {item}！效果：{effect}";
        GD.Print(better);
        // 运行结果: 你 picked up 治疗药水！效果：恢复 50 HP
    }
}

GDScript

extends Node

func _ready():
    # 嵌套数组填充：每个子数组对应一组键值对
    var template := "你 picked up {item}！效果：{effect}"
    var data := [["item", "治疗药水"], ["effect", "恢复 50 HP"]]
    var result := template.format(data)
    print(result)
    # 运行结果: 你 picked up 治疗药水！效果：恢复 50 HP

    # 自定义占位符：使用 $ 代替 {}
    var tpl2 := "你好 $name$，你的等级是 $level$"
    var result2 := tpl2.format({"name": "战士", "level": 10}, "$_$")
    print(result2)
    # 运行结果: 你好 战士，你的等级是 10

注意事项

1. C# 更推荐字符串插值：在 C# 中，通常使用 $"{变量名}" 的字符串插值语法更方便直观，Format 主要用于需要和 Godot 的 Variant 类型交互的场景。
2. 占位符中的键名必须匹配：模板中的占位符名称（如 {name}）必须和传入的字典键名完全一致，否则占位符会原样保留在结果中。
3. 数组从 0 开始编号：使用数组填充时，占位符写成 {0}、{1}、{2} 等，从 0 开始编号。
4. GDScript 的 placeholder 参数：默认占位符格式是 "{_}"，其中 _ 会被替换为实际的键名。你可以自定义为 "$_" 或其他格式，但必须包含 _ 来代表键名的位置。
5. 不修改原字符串：format 返回一个全新的字符串，不会改变原始的模板字符串。