共用方式為

檔案選擇器

  • 發行項

流覽範例。 流覽範例

本文說明如何使用 .NET 多平臺應用程式 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

這些權限可以透過下列方式新增：

  • 新增元件型權限：

    開啟 Platform/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 指令清單：

    開啟 [平臺/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 中，按兩下 [平臺/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.Png和FilePickerFilerType.Videos一起FilePickerFileType.Images提供。 您可以藉由建立 類別的 FilePickerFileType 實例，為每個平臺指定自定義文件類型。 這個類別的建構函式會採用型別索引 DevicePlatform 鍵的字典，以識別平臺。 字典索引鍵的值是代表檔類型的字串集合。 例如，以下說明如何指定特定的漫畫檔類型：

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 - Common MIME 類型。