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

FileDialog

节点继承关系

继承链：Node → CanvasItem → Control → AcceptDialog → FileDialog

定义

弹出一个系统级的文件选择/保存对话框。就像 Word 里点"文件 > 打开"时弹出的那个窗口。你不需要自己做文件浏览器，FileDialog 已经帮你做好了。

使用频率：★★ 偶尔使用（需要加载/保存文件时使用）

节点用途

• 让用户选择要打开的文件
• 让用户选择保存位置
• 让用户选择文件夹

使用场景

• 游戏的"加载存档"功能
• 地图编辑器的"导入/导出"
• 截图保存功能

常用节点搭配

• 搭配 Button 触发弹出
• 搭配 Label 显示已选择的文件路径

生效必备素材/资源

无需特殊资源。

节点属性与信号

自有属性

属性	类型	默认值	继承自	说明
file_mode	枚举	OpenFile	—	模式：OpenFile（打开文件）、OpenFiles（打开多个）、OpenDir（打开文件夹）、SaveFile（保存文件）
access	枚举	Resources	—	可访问范围：Resources（资源目录）、UserData（用户目录）、Filesystem（文件系统）
filters	string[]	null	—	文件类型过滤器，如 new string[] { "*.png ; 图片文件" }
current_dir	string	""	—	当前目录
current_file	string	""	—	当前文件名
title	string	"Save a File"	—	对话框标题

继承自 AcceptDialog

属性	类型	默认值	继承自	说明
dialog_hide_on_ok	bool	true	AcceptDialog	点击确认后是否自动关闭

信号

信号	触发时机	参数
file_selected	选择了一个文件时	string 文件路径
files_selected	选择了多个文件时	string[] 文件路径数组
dir_selected	选择了一个文件夹时	string 文件夹路径

常用方法

方法	说明
PopupCentered(Vector2I)	在屏幕中央弹出对话框
PopupCenteredClamped()	弹出并限制最大尺寸
Show()	显示对话框
Hide()	隐藏对话框

代码示例

C

using Godot;

public partial class SaveLoader : Control
{
    private FileDialog _fileDialog;

    public override void _Ready()
    {
        var btn = new Button();
        btn.Text = "选择存档文件";
        btn.Position = new Vector2(100, 100);
        btn.Pressed += ShowFileDialog;
        AddChild(btn);

        _fileDialog = new FileDialog();
        _fileDialog.FileMode = FileDialog.FileModeEnum.OpenFile;
        _fileDialog.Access = FileDialog.AccessEnum.Filesystem;
        _fileDialog.Filters = new string[] { "*.sav ; 存档文件" };
        _fileDialog.FileSelected += (path) =>
        {
            GD.Print($"选择了文件: {path}");
        };
        AddChild(_fileDialog);
    }

    private void ShowFileDialog()
    {
        _fileDialog.PopupCentered(new Vector2I(600, 400));
    }
}

GDScript

extends Control

var file_dialog: FileDialog

func _ready():
    var btn = Button.new()
    btn.text = "选择存档文件"
    btn.position = Vector2(100, 100)
    btn.pressed.connect(_show_file_dialog)
    add_child(btn)

    file_dialog = FileDialog.new()
    file_dialog.file_mode = FileDialog.FileModeEnum.FILE_MODE_OPEN_FILE
    file_dialog.access = FileDialog.AccessEnum.ACCESS_FILESYSTEM
    file_dialog.filters = PackedStringArray(["*.sav ; 存档文件"])
    file_dialog.file_selected.connect(func(path: String):
        print("选择了文件: " + path)
    )
    add_child(file_dialog)

func _show_file_dialog():
    file_dialog.popup_centered(Vector2i(600, 400))