NativeFileDialog 1.0.0

NativeFileDialog

一个跨平台的文件对话框库，为.NET应用程序提供原生的文件选择、保存和文件夹选择功能。

项目概述

NativeFileDialog是一个C#库，提供了统一的API来访问各个操作系统的原生文件对话框。支持Windows、Linux和macOS平台，让开发者可以编写一次代码，在多个平台上获得原生的用户体验。

主要特性

• 跨平台支持（Windows、Linux、macOS）
• 打开文件对话框（支持单选和多选）
• 保存文件对话框
• 打开文件夹对话框
• 可自定义文件过滤器
• 原生UI体验
• 简洁的API设计

平台支持

快速开始

基本使用

using NativeFileDialog;

// 获取当前平台的文件对话框实现
IFileDialog? dialog = NativeFileDialog.GetFileDialog();

if (dialog == null)
{
    Console.WriteLine("不支持的平台");
    return;
}

// 打开文件选择对话框（单选）
string[]? selectedFiles = dialog.OpenFile(
    title: "选择文件",
    basePath: Environment.GetFolderPath(Environment.SpecialFolder.UserProfile),
    filter: new OpenFileFilter
    {
        Filter = new Dictionary<string, List<string>>
        {
            { "文本文件", ["txt", "log"] },
            { "Markdown文件", ["md"] },
            { "C#文件", ["cs"] }
        },
        IncludeAllFiles = true
    }
);

if (selectedFiles != null && selectedFiles.Length > 0)
{
    Console.WriteLine($"选择的文件: {selectedFiles[0]}");
}

多选文件

// 打开文件选择对话框（多选）
string[]? selectedFiles = dialog.OpenFile(
    title: "选择多个文件",
    basePath: Environment.GetFolderPath(Environment.SpecialFolder.UserProfile),
    filter: new OpenFileFilter
    {
        Filter = new Dictionary<string, List<string>>
        {
            { "图片文件", ["jpg", "png", "gif"] }
        },
        IncludeAllFiles = false
    },
    multiSelect: true  // 启用多选
);

if (selectedFiles != null)
{
    foreach (var file in selectedFiles)
    {
        Console.WriteLine($"选择的文件: {file}");
    }
}

保存文件

string? savedPath = dialog.SaveFile(
    title: "保存文件",
    basePath: Environment.GetFolderPath(Environment.SpecialFolder.UserProfile),
    defaultName: "untitled",
    filter: new SaveFileFilter
    {
        Filter = new Dictionary<string, string>
        {
            { "文本文件", "txt" },
            { "Markdown文件", "md" },
            { "JSON文件", "json" }
        },
        IncludeAllFiles = false
    }
);

if (!string.IsNullOrEmpty(savedPath))
{
    Console.WriteLine($"保存路径: {savedPath}");
}

选择文件夹

string? selectedFolder = dialog.OpenFolder(
    title: "选择文件夹",
    basePath: Environment.GetFolderPath(Environment.SpecialFolder.UserProfile)
);

if (!string.IsNullOrEmpty(selectedFolder))
{
    Console.WriteLine($"选择的文件夹: {selectedFolder}");
}

API文档

IFileDialog 接口

// 打开文件选择对话框
string[]? OpenFile(string title, string basePath, OpenFileFilter filter, bool multiSelect = false);

// 打开保存文件对话框
string? SaveFile(string title, string basePath, string defaultName, SaveFileFilter filter);

// 打开文件夹选择对话框
string? OpenFolder(string title, string basePath);

OpenFileFilter 结构

public struct OpenFileFilter
{
    // 文件过滤器字典，键为显示名称，值为扩展名列表
    public Dictionary<string, List<string>> Filter;
    
    // 是否包含"所有文件"选项
    public bool IncludeAllFiles;
}

SaveFileFilter 结构

public struct SaveFileFilter
{
    // 文件过滤器字典，键为显示名称，值为单个扩展名
    public Dictionary<string, string> Filter;
    
    // 是否包含"所有文件"选项
    public bool IncludeAllFiles;
}

依赖项

运行时库

Windows

• comdlg32.dll (系统内置)
• shell32.dll (系统内置)

Linux

• libgtk-3.so.0 (GTK3库)
• libgdk-3.so.0 (GDK3库)
• libglib-2.0.so.0 (GLib库)

安装GTK3库（Ubuntu/Debian）:

sudo apt-get install libgtk-3-0

macOS

• libobjc.dylib (系统内置)
• AppKit框架 (系统内置)

开发工具

• .NET 10.0 或更高版本
• .NET Framework 4.8.1 (仅Windows)

构建项目

# 恢复NuGet包
dotnet restore

# 构建项目
dotnet build

# 发布项目
dotnet publish -c Release

运行测试

# 运行所有测试
dotnet test

注意事项

• 返回值变更: OpenFile 方法现在返回 string[]? 数组，即使单选模式也返回数组
• 多选支持: Windows和macOS完全支持多选，Linux部分支持（待完善）
• 工作目录保护: 所有方法都会保护当前工作目录
• 自动扩展名: 保存文件时会自动附加选中的文件扩展名

常见问题

Q: 如何处理用户取消操作？
A: 方法返回null表示用户取消了对话框。

Q: 单选模式下返回值是什么？
A: 返回包含一个元素的数组，例如 new[] { "path/to/file.txt" }

Q: Linux上遇到"DISPLAY environment variable is not set"错误怎么办？
A: 确保在图形界面环境下运行程序，或手动设置DISPLAY变量。

export DISPLAY=:0
./program

许可证

本项目采用MIT许可证。

更新日志

v1.1.0 (2026-05-14)

• 添加多选文件支持
• 更改 OpenFile 返回值为 string[]?
• 添加双语注释（中英文）
• 修复项目引用问题

v1.0.0 (2026-05-14)

• 初始版本发布
• 支持Windows、Linux、macOS三个平台
• 实现文件选择、保存和文件夹选择功能

部分代码由AI生成