最后更新日期：2026-04-16

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

@export_placeholder

定义

@export_placeholder 是 GDScript 中的一个注解（annotation），用来在 Godot 编辑器的检查器面板中，为字符串变量添加一个占位提示文本（placeholder）。当变量的值为空时，输入框中会以灰色文字显示提示信息，告诉使用者应该在这里填什么。

简单说，就像网页上的登录框，在你还没输入内容时，框里会显示灰色的"请输入用户名"。@export_placeholder 就是给你的导出变量加一个这样的"提示文字"，帮助其他开发者或策划理解这个字段应该填什么。

在 C# 中，对应的写法是 [Export(PropertyHint.PlaceholderText, "提示文字")]。

语法

C#

// 导出带占位提示的字符串
[Export(PropertyHint.PlaceholderText, "请输入角色名字")]
public string ExPlayerName = "";

GDScript

# 导出带占位提示的字符串
@export_placeholder("请输入角色名字") var ex_player_name: String = ""

参数说明

参数	类型	必需	说明
placeholder	String	是	占位提示文本，当变量值为空时以灰色文字显示在输入框中

返回值

@export_placeholder 是一个注解，没有返回值。变量的值仍然是普通的字符串，占位文本只是编辑器中的视觉提示。

代码示例

C#

using Godot;

public partial class CharacterConfig : Node
{
    // ===== 基础用法：带提示的字符串导出 =====
    [Export(PropertyHint.PlaceholderText, "例如：勇者小明")]
    public string ExCharacterName = "";

    public override void _Ready()
    {
        string name = string.IsNullOrEmpty(ExCharacterName) ? "未命名角色" : ExCharacterName;
        GD.Print($"角色名称: {name}");
    }
    // 运行结果: 角色名称: 未命名角色


    // ===== 实际场景：配置表单提示 =====
    [Export(PropertyHint.PlaceholderText, "例如：res://data/config.json")]
    public string ExConfigPath = "";

    [Export(PropertyHint.PlaceholderText, "例如：127.0.0.1")]
    public string ExServerAddress = "";

    [Export(PropertyHint.PlaceholderText, "例如：这是一个勇敢的战士")]
    public string ExDescription = "";

    [Export(PropertyHint.PlaceholderText, "例如：Hello, {player}!")]
    public string ExGreetingTemplate = "";

    public void PrintConfig()
    {
        GD.Print($"配置路径: {(string.IsNullOrEmpty(ExConfigPath) ? "未设置" : ExConfigPath)}");
        GD.Print($"服务器地址: {(string.IsNullOrEmpty(ExServerAddress) ? "未设置" : ExServerAddress)}");
        GD.Print($"描述: {(string.IsNullOrEmpty(ExDescription) ? "无" : ExDescription)}");
    }
    // 运行结果: 配置路径: 未设置
    // 运行结果: 服务器地址: 未设置
    // 运行结果: 描述: 无


    // ===== 进阶用法：格式化提示与验证 =====
    [Export(PropertyHint.PlaceholderText, "格式：#RRGGBB，例如 #FF5733")]
    public string ExHexColor = "#FFFFFF";

    [Export(PropertyHint.PlaceholderText, "格式：key=value，每行一个")]
    public string ExCustomTags = "";

    public bool ValidateHexColor()
    {
        if (ExHexColor.Length() != 7 || !ExHexColor.StartsWith("#"))
        {
            GD.PrintErr($"无效的颜色格式: {ExHexColor}，请使用 #RRGGBB 格式");
            return false;
        }
        GD.Print($"颜色格式正确: {ExHexColor}");
        return true;
    }
    // 运行结果: 颜色格式正确: #FFFFFF
}

GDScript

extends Node

# ===== 基础用法：带提示的字符串导出 =====
@export_placeholder("例如：勇者小明") var ex_character_name: String = ""

func _ready():
    var name := "未命名角色" if ex_character_name.is_empty() else ex_character_name
    print("角色名称: %s" % name)
# 运行结果: 角色名称: 未命名角色


# ===== 实际场景：配置表单提示 =====
@export_placeholder("例如：res://data/config.json") var ex_config_path: String = ""
@export_placeholder("例如：127.0.0.1") var ex_server_address: String = ""
@export_placeholder("例如：这是一个勇敢的战士") var ex_description: String = ""
@export_placeholder("例如：Hello, {player}!") var ex_greeting_template: String = ""

func print_config():
    print("配置路径: %s" % ("未设置" if ex_config_path.is_empty() else ex_config_path))
    print("服务器地址: %s" % ("未设置" if ex_server_address.is_empty() else ex_server_address))
    print("描述: %s" % ("无" if ex_description.is_empty() else ex_description))
# 运行结果: 配置路径: 未设置
# 运行结果: 服务器地址: 未设置
# 运行结果: 描述: 无


# ===== 进阶用法：格式化提示与验证 =====
@export_placeholder("格式：#RRGGBB，例如 #FF5733") var ex_hex_color: String = "#FFFFFF"
@export_placeholder("格式：key=value，每行一个") var ex_custom_tags: String = ""

func validate_hex_color() -> bool:
    if ex_hex_color.length() != 7 or not ex_hex_color.begins_with("#"):
        push_error("无效的颜色格式: %s，请使用 #RRGGBB 格式" % ex_hex_color)
        return false
    print("颜色格式正确: %s" % ex_hex_color)
    return true
# 运行结果: 颜色格式正确: #FFFFFF

注意事项

• @export_placeholder 只能用于 String 类型的变量。
• 占位提示文本只在变量值为空时显示，一旦用户输入了内容，提示就会消失。
• 占位文本不会成为变量的值——它纯粹是编辑器中的视觉辅助。
• 提示文字应该简洁明了，告诉使用者"应该填什么"或"格式是什么"。
• C# 中使用 [Export(PropertyHint.PlaceholderText, "提示文字")] 的形式，提示文字写在第二个参数中。
• 如果你需要多行文本的占位提示，可以配合 @export_multiline 使用，但 @export_placeholder 本身不支持多行占位文本。