文件选取器

  • 项目

Browse sample. 浏览示例

本文介绍如何使用 .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.Images、FilePickerFileType.Png 和 FilePickerFilerType.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 类型。