Otwieranie plików i folderów przy użyciu selektorów w usłudze WinUI

Użyj selektorów plików i folderów zestawu SDK aplikacji systemu Windows, aby umożliwić użytkownikom przeglądanie i wybieranie plików lub folderów w aplikacji WinUI. Interfejsy API selektora zapewniają znajome środowisko systemu Windows, które ułatwia użytkownikom nawigowanie po ich urządzeniach i lokalizacjach przechowywania w chmurze. W tym artykule pokazano, jak zaimplementować selektory otwierania plików i selektory folderów, dostosować ich zachowanie i obsłużyć wybrane wyniki w aplikacji.

Klasy FileOpenPicker i FileSavePicker zestawu SDK aplikacji systemu Windows tworzą okno dialogowe selektora, które umożliwia użytkownikom określenie nazwy i lokalizacji pliku do otwarcia lub zapisania. Klasa FolderPicker umożliwia wybranie folderu.

Aby dowiedzieć się więcej o korzystaniu z selektora do zapisywania plików, zobacz Zapisywanie pliku przy użyciu selektora zestawu SDK aplikacji systemu Windows.

Ważne interfejsy API

W tym artykule są używane następujące interfejsy API:

• FileOpenPicker
• FolderPicker
• StorageFile

Interfejs użytkownika selektora plików

Selektor plików wyświetla informacje dotyczące orientowania użytkowników i zapewnienia spójnego środowiska podczas otwierania lub zapisywania plików.

Te informacje obejmują:

• Bieżąca lokalizacja
• Element lub elementy wybrane przez użytkownika
• Drzewo lokalizacji, do których użytkownik może przejść. Te lokalizacje obejmują lokalizacje systemu plików , takie jak folder Muzyka lub Pliki do pobrania, a także aplikacje implementujące kontrakt selektora plików (takie jak Aparat, Zdjęcia i Microsoft OneDrive).

Być może masz aplikację, która umożliwia użytkownikom otwieranie lub zapisywanie plików. Gdy użytkownik inicjuje akcję, aplikacja wywołuje selektor plików, który wyświetla interfejs selektora plików.

Jak selektory współpracują z aplikacją

Za pomocą selektora aplikacja może uzyskiwać dostęp do plików i folderów oraz przeglądać je oraz zapisywać w systemie użytkownika. Aplikacja odbiera te opcje jako lekkie obiekty PickFileResult i PickFolderResult , które zapewniają ścieżkę do wybranego pliku lub folderu.

Selektor używa jednego, ujednoliconego interfejsu, aby umożliwić użytkownikowi wybieranie plików i folderów z systemu plików lub innych aplikacji. Pliki wybrane z innych aplikacji są podobne do plików z systemu plików. Ogólnie rzecz biorąc, aplikacja może działać na nich w taki sam sposób jak inne obiekty. Inne aplikacje udostępniają pliki, uczestnicząc w kontraktach selekcji plików.

Możesz na przykład wywołać selektor plików w aplikacji, aby użytkownik mógł otworzyć plik. Twoja aplikacja staje się aplikacją wywołującą dzięki tej akcji. Selektor plików współdziała z systemem i innymi aplikacjami, aby umożliwić użytkownikowi nawigowanie i wybieranie pliku. Gdy użytkownik wybierze plik, selektor plików zwraca ścieżkę tego pliku do aplikacji.

Wybierz plik, aby otworzyć przykład

Poniższy kod pokazuje, jak użyć klasy FileOpenPicker , aby umożliwić użytkownikowi wybranie pojedynczego pliku, takiego jak zdjęcie. Kod ustawia właściwości selektora, aby dostosować jego wygląd i zachowanie, a następnie wyświetla selektor do użytkownika przy użyciu metody PickSingleFileAsync . Jeśli użytkownik wybierze plik, aplikacja odczytuje zawartość pliku i zapisuje ją w zmiennej.

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.
}

Jest to ten sam przykład w języku 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.
}

Wybierz wiele plików, aby otworzyć przykład

Możesz również zezwolić użytkownikowi na wybranie wielu plików. Poniższy kod pokazuje, jak użyć klasy FileOpenPicker , aby umożliwić użytkownikowi wybranie wielu plików, takich jak zdjęcia. Proces jest taki sam, ale metoda PickMultipleFilesAsync zwraca kolekcję ścieżek plików zamiast pojedynczej ścieżki.

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.
}

Aby wykonać tę samą operację w języku C++, użyj następującego kodu:

#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.
}

Wybierz przykład folderu

Aby wybrać folder przy użyciu klasy FolderPicker , użyj następującego kodu. Ten kod tworzy selektor folderów, wyświetla go użytkownikowi przy użyciu metody PickSingleFolderAsync i pobiera ścieżkę wybranego folderu w obiekcie PickFolderResult . Jeśli użytkownik wybierze folder, aplikacja pobierze ścieżkę folderu i zapisze ją w zmiennej do późniejszego użycia.

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.
}

Aby wykonać tę samą operację w języku C++, użyj następującego kodu:

#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.
}

Wskazówka

Za każdym razem, gdy aplikacja uzyskuje dostęp do pliku lub folderu za pomocą selektora, dodaj go do aplikacji FutureAccessList lub MostRecentlyUsedList , aby śledzić go za pomocą interfejsów API środowiska uruchomieniowego systemu Windows (WinRT). Aby uzyskać więcej informacji, zobacz Jak śledzić ostatnio używane pliki i foldery.

Interfejs użytkownika selektora folderów wygląda następująco:

Treści powiązane

Windows.Storage.Pickers

Pliki, foldery i biblioteki z zestawem SDK aplikacji systemu Windows

Przestrzeń nazw Microsoft.Windows.Storage.Pickers