文件选取器

浏览示例。 浏览示例

本文介绍如何使用 .NET Multi-platform App UI (.NET MAUI) IFilePicker 接口。 IFilePicker使用界面,可以提示用户从设备中选择一个或多个文件。

IFilePicker 接口的默认实现通过 FilePicker.Default 属性提供。 IFilePicker 接口和 FilePicker 类都包含在 Microsoft.Maui.Storage 命名空间中。

开始使用

要访问 FilePicker 功能,需执行以下特定于平台的设置。

如果应用面向 Android 12 或更低版本,则必须请求 READ_EXTERNAL_STORAGE 权限。 如果你的应用面向 Android 13 或更高版本,并且需要访问其他应用创建的文件,则必须请求以下一个或多个精细权限,而不是 READ_EXTERNAL_STORAGE 权限:

  • READ_MEDIA_IMAGES
  • READ_MEDIA_VIDEO
  • READ_MEDIA_AUDIO

可通过以下方式添加这些权限:

  • 添加基于程序集的权限:

    打开 Platforms/Android/MainApplication.cs 文件,并在 using 指令后面添加以下程序集属性:

    [assembly: UsesPermission(Android.Manifest.Permission.ReadExternalStorage, MaxSdkVersion = 32)]
    [assembly: UsesPermission(Android.Manifest.Permission.ReadMediaAudio)]
    [assembly: UsesPermission(Android.Manifest.Permission.ReadMediaImages)]
    [assembly: UsesPermission(Android.Manifest.Permission.ReadMediaVideo)]
    

    - 或 -

  • 更新 Android 清单:

    打开 Platforms/Android/AndroidManifest.xml 文件并在 manifest 节点中添加以下内容:

    <uses-permission android:name="android.permission.READ_EXTERNAL_STORAGE" android:maxSdkVersion="32" />
    <!-- Required only if your app needs to access images or photos that other apps created -->
    <uses-permission android:name="android.permission.READ_MEDIA_IMAGES" />
    <!-- Required only if your app needs to access videos that other apps created -->
    <uses-permission android:name="android.permission.READ_MEDIA_VIDEO" />
    <!-- Required only if your app needs to access audio files that other apps created -->
    <uses-permission android:name="android.permission.READ_MEDIA_AUDIO" />    
    

    - 或 -

  • 在清单编辑器中更新 Android 清单:

    在 Visual Studio 中,双击 Platforms/Android/AndroidManifest.xml 文件以打开 Android 清单编辑器。 然后在“所需权限”下方检查上方所列权限。 这样会自动更新 AndroidManifest.xml 文件。

重要说明

必须在 UI 线程上调用所有方法,因为 .NET MAUI 会自动处理权限检查和请求。

选取一个文件

该方法 PickAsync 提示用户从设备中选取文件。 使用 PickOptions 类型指定选取器允许的标题和文件类型。 以下示例演示如何打开选取器并处理所选图像:

public async Task<FileResult> PickAndShow(PickOptions options)
{
    try
    {
        var result = await FilePicker.Default.PickAsync(options);
        if (result != null)
        {
            if (result.FileName.EndsWith("jpg", StringComparison.OrdinalIgnoreCase) ||
                result.FileName.EndsWith("png", StringComparison.OrdinalIgnoreCase))
            {
                using var stream = await result.OpenReadAsync();
                var image = ImageSource.FromStream(() => stream);
            }
        }

        return result;
    }
    catch (Exception ex)
    {
        // The user canceled or something went wrong
    }

    return null;
}

提供的默认文件类型包括 FilePickerFileType.ImagesFilePickerFileType.PngFilePickerFilerType.Videos。 可以通过创建类的实例来指定每个平台的 FilePickerFileType 自定义文件类型。 此类构造函数接受一个以DevicePlatform类型为键来识别平台的字典。 字典键的值是表示文件类型的字符串集合。 下面的示例说明了如何指定特定 comic 文件类型:

var customFileType = new FilePickerFileType(
                new Dictionary<DevicePlatform, IEnumerable<string>>
                {
                    { DevicePlatform.iOS, new[] { "public.my.comic.extension" } }, // UTType values
                    { DevicePlatform.Android, new[] { "application/comics" } }, // MIME type
                    { DevicePlatform.WinUI, new[] { ".cbr", ".cbz" } }, // file extension
                    { DevicePlatform.Tizen, new[] { "*/*" } },
                    { DevicePlatform.macOS, new[] { "cbr", "cbz" } }, // UTType values
                });

PickOptions options = new()
{
    PickerTitle = "Please select a comic file",
    FileTypes = customFileType,
};

根据文件类型来搜索文件,可能不同平台有不同的实现方式。 有关详细信息,请参阅功能差异

选取多个文件

如果希望用户可以选择多个文件,则可以调用 FilePicker.PickMultipleAsync 方法。 该方法也采用 PickOptions 作为参数,来指定其他信息。 结果与PickAsync相同,但返回的类型不是FileResult,而是带有所有选定文件的IEnumerable<FileResult>类型。

提示

FullPath 属性并不总是返回文件的物理路径。 若要获取文件,请使用 OpenReadAsync 方法。

平台差异

本节描述了文件选择器在不同平台间的差异。

PickOptions.PickerTitle会显示在初始提示中,但不会显示在选择对话框本身。

按类型筛选文件时,请使用文件的 MIME 类型。 有关 MIME 类型的列表,请参阅 Mozilla - 常见 MIME 类型