Ouvrir des fichiers et des dossiers avec des sélecteurs dans WinUI

Utilisez les sélecteurs de fichiers et de dossiers du Kit de développement logiciel (SDK) d’application Windows pour permettre aux utilisateurs de parcourir et de sélectionner des fichiers ou dossiers dans votre application WinUI. Les API du sélecteur fournissent une expérience Windows familière qui aide les utilisateurs à naviguer dans les emplacements de stockage de leurs appareils et dans le cloud. Cet article explique comment implémenter des sélecteurs d’ouverture de fichiers et des sélecteurs de dossiers, personnaliser leur comportement et gérer les résultats sélectionnés dans votre application.

Les classes FileOpenPicker et FileSavePicker du SDK d’application Windows créent une boîte de dialogue sélecteur qui permet aux utilisateurs de spécifier le nom et l’emplacement d’un fichier à ouvrir ou à enregistrer. La classe FolderPicker vous permet de sélectionner un dossier.

Pour en savoir plus sur l’utilisation d’un sélecteur pour enregistrer des fichiers, consultez Enregistrer un fichier avec un sélecteur de SDK d’application Windows.

API importantes

Cet article utilise les API suivantes :

• FileOpenPicker
• FolderPicker
• StorageFile

Interface utilisateur du sélecteur de fichiers

Un sélecteur de fichiers affiche des informations pour orienter les utilisateurs et fournir une expérience cohérente lors de l’ouverture ou de l’enregistrement de fichiers.

Ces informations incluent :

• Emplacement actuel
• Élément ou éléments sélectionnés par l’utilisateur
• Arborescence des emplacements auxquels l’utilisateur peut accéder. Ces emplacements incluent des emplacements de système de fichiers, tels que le dossier Musique ou Téléchargements, ainsi que des applications qui implémentent le contrat du sélecteur de fichiers (par exemple, Caméra, Photos et Microsoft OneDrive).

Vous disposez peut-être d’une application qui permet aux utilisateurs d’ouvrir ou d’enregistrer des fichiers. Lorsque l’utilisateur lance cette action, votre application appelle le sélecteur de fichiers, qui affiche l’interface utilisateur du sélecteur de fichiers :

Comment les sélecteurs fonctionnent avec votre application

Avec un sélecteur, votre application peut accéder, parcourir et enregistrer des fichiers et des dossiers sur le système de l’utilisateur. Votre application reçoit ces sélections en tant qu’objets PickFileResult et PickFolderResult légers, qui fournissent le chemin d’accès au fichier ou dossier sélectionné.

Le sélecteur utilise une interface unique et unifiée pour permettre à l’utilisateur de choisir des fichiers et des dossiers à partir du système de fichiers ou d’autres applications. Les fichiers sélectionnés à partir d’autres applications sont similaires aux fichiers du système de fichiers. En règle générale, votre application peut les utiliser de la même manière que d’autres objets. D'autres applications mettent les fichiers à disposition en participant aux contrats de sélecteur de fichiers.

Par exemple, vous pouvez appeler le sélecteur de fichiers dans votre application afin que votre utilisateur puisse ouvrir un fichier. Cette action fait de votre application l'application de téléphonie. Le sélecteur de fichiers interagit avec le système et d’autres applications pour permettre à l’utilisateur de naviguer et de sélectionner le fichier. Lorsque votre utilisateur choisit un fichier, le sélecteur de fichiers retourne le chemin d’accès de ce fichier à votre application.

Choisir un fichier pour ouvrir un exemple

Le code suivant montre comment utiliser la classe FileOpenPicker pour permettre à l’utilisateur de choisir un fichier unique, tel qu’une photo. Le code définit les propriétés du sélecteur pour personnaliser son apparence et son comportement, puis affiche le sélecteur à l’utilisateur à l’aide de la méthode PickSingleFileAsync . Si l’utilisateur sélectionne un fichier, l’application lit le contenu du fichier et le stocke dans une variable.

using Microsoft.Windows.Storage.Pickers;

var openPicker = new FileOpenPicker(this.AppWindow.Id)
{
    // (Optional) Specify the initial location for the picker. 
    //     If the specified location doesn't exist on the user's machine, it falls back to the DocumentsLibrary.
    //     If not set, it defaults to PickerLocationId.Unspecified, and the system will use its default location.
    SuggestedStartLocation = PickerLocationId.DocumentsLibrary,
    
    // (Optional) specify the text displayed on the commit button. 
    //     If not specified, the system uses a default label of "Open" (suitably translated).
    CommitButtonText = "Choose selected files",

    // (Optional) specify file extension filters. If not specified, defaults to all files (*.*).
    FileTypeFilter = { ".txt", ".pdf", ".doc", ".docx" },

    // (Optional) specify the view mode of the picker dialog. If not specified, defaults to List.
    ViewMode = PickerViewMode.List,
};

var result = await openPicker.PickSingleFileAsync();
if (result is not null)
{
    var content = System.IO.File.ReadAllText(result.Path);
}
else
{
    // Add your error handling here.
}

Il s’agit du même exemple en C++ :

#include <winrt/Microsoft.Windows.Storage.Pickers.h>
#include <fstream>
#include <string>

using namespace winrt::Microsoft::Windows::Storage::Pickers;

FileOpenPicker openPicker(this->AppWindow().Id());

// (Optional) Specify the initial location for the picker. 
//     If the specified location doesn't exist on the user's machine, it falls back to the DocumentsLibrary.
//     If not set, it defaults to PickerLocationId.Unspecified, and the system will use its default location.
openPicker.SuggestedStartLocation(PickerLocationId::DocumentsLibrary);

// (Optional) specify the text displayed on the commit button. 
//     If not specified, the system uses a default label of "Open" (suitably translated).
openPicker.CommitButtonText(L"Choose selected files");

// (Optional) specify file extension filters. If not specified, defaults to all files (*.*).
openPicker.FileTypeFilter().ReplaceAll({ L".txt", L".pdf", L".doc", L".docx" });

// (Optional) specify the view mode of the picker dialog. If not specified, defaults to List.
openPicker.ViewMode(PickerViewMode::List);

auto result{ co_await openPicker.PickSingleFileAsync() };
if (result)
{
    std::ifstream fileReader(result.Path().c_str());
    std::string text((std::istreambuf_iterator<char>(fileReader)), std::istreambuf_iterator<char>());
    winrt::hstring hText = winrt::to_hstring(text);
}
else
{
    // Add your error handling here.
}

Choisir plusieurs fichiers pour ouvrir l’exemple

Vous pouvez également laisser l’utilisateur choisir plusieurs fichiers. Le code suivant montre comment utiliser la classe FileOpenPicker pour permettre à l’utilisateur de choisir plusieurs fichiers, tels que des photos. Le processus est le même, mais la méthode PickMultipleFilesAsync retourne une collection de chemins de fichier au lieu d’un seul chemin d’accès.

using Microsoft.Windows.Storage.Pickers;

var openPicker = new FileOpenPicker(this.AppWindow.Id);

var results = await openPicker.PickMultipleFilesAsync();
if (results.Count > 0)
{
    var pickedFilePaths = results.Select(f => f.Path);
    foreach (var path in pickedFilePaths)
    {
        var content = System.IO.File.ReadAllText(path);
    }
}
else
{
    // Add your error handling here.
}

Pour effectuer la même opération en C++, utilisez le code suivant :

#include <winrt/Microsoft.Windows.Storage.Pickers.h>
#include <fstream>
#include <string>

using namespace winrt::Microsoft::Windows::Storage::Pickers;

FileOpenPicker openPicker(this->AppWindow().Id());
auto results{ co_await openPicker.PickMultipleFilesAsync() };
if (results.Size() > 0)
{
    for (auto const& result : results)
    {
        std::ifstream fileReader(result.Path().c_str());
        std::string text((std::istreambuf_iterator<char>(fileReader)), std::istreambuf_iterator<char>());
        winrt::hstring hText = winrt::to_hstring(text);
    }
}
else
{
    // Add your error handling here.
}

Choisir un exemple de dossier

Pour choisir un dossier à l’aide de la classe FolderPicker , utilisez le code suivant. Ce code crée un sélecteur de dossiers, l’affiche à l’utilisateur à l’aide de la méthode PickSingleFolderAsync et récupère le chemin d’accès du dossier sélectionné dans un objet PickFolderResult . Si l’utilisateur sélectionne un dossier, l’application récupère le chemin d’accès du dossier et la stocke dans une variable pour une utilisation ultérieure.

using Microsoft.Windows.Storage.Pickers;

var folderPicker = new FolderPicker(this.AppWindow.Id)
{
    // (Optional) Specify the initial location for the picker. 
    //     If the specified location doesn't exist on the user's machine, it falls back to the DocumentsLibrary.
    //     If not set, it defaults to PickerLocationId.Unspecified, and the system will use its default location.
    SuggestedStartLocation = PickerLocationId.DocumentsLibrary,

    // (Optional) specify the text displayed on the commit button. 
    //     If not specified, the system uses a default label of "Open" (suitably translated).
    CommitButtonText = "Select Folder",

    // (Optional) specify the view mode of the picker dialog. If not specified, default to List.
    ViewMode = PickerViewMode.List,
};

var result = await folderPicker.PickSingleFolderAsync();

if (result is not null)
{
    var path = result.Path;
}
else
{
    // Add your error handling here.
}

Pour effectuer la même opération en C++, utilisez le code suivant :

#include <winrt/Microsoft.Windows.Storage.Pickers.h>

using namespace winrt::Microsoft::Windows::Storage::Pickers;

FolderPicker folderPicker(this->AppWindow().Id());

// (Optional) Specify the initial location for the picker. 
//     If the specified location doesn't exist on the user's machine, it falls back to the DocumentsLibrary.
//     If not set, it defaults to PickerLocationId.Unspecified, and the system will use its default location.
folderPicker.SuggestedStartLocation(PickerLocationId::DocumentsLibrary);

// (Optional) specify the text displayed on the commit button. 
//     If not specified, the system uses a default label of "Open" (suitably translated).
folderPicker.CommitButtonText(L"Select Folder");

// (Optional) specify the view mode of the picker dialog. If not specified, default to List.
folderPicker.ViewMode(PickerViewMode::List);

auto result{ co_await folderPicker.PickSingleFolderAsync() };
if (result)
{
    auto path{ result.Path() };
}
else
{
    // Add your error handling here.
}

Conseil / Astuce

Chaque fois que votre application accède à un fichier ou un dossier via un sélecteur, ajoutez-la aux API FutureAccessList ou MostRecentlyUsedList de votre application pour effectuer le suivi à l’aide des API Windows Runtime (WinRT). Pour plus d’informations, consultez Comment suivre les fichiers et dossiers récemment utilisés.

L’interface utilisateur du sélecteur de dossiers ressemble à ceci :

Contenu connexe

Windows.Storage.Pickers

Fichiers, dossiers et bibliothèques avec le Kit de développement logiciel (SDK) d’application Windows

Espace de noms Microsoft.Windows.Storage.Pickers