Buka file dan folder dengan pemilih berkas

Important

Membangun aplikasi WinUI 3? Gunakan Microsoft.Windows. Storage.Pickers namespace, bukan API Windows.Storage.Pickers yang dijelaskan dalam artikel ini. Fitur pemilih di SDK Aplikasi Windows (tersedia di SDK Aplikasi Windows 1.8 dan yang lebih baru) dirancang untuk aplikasi WinUI 3 — tidak memerlukan inisialisasi handle jendela dan mengembalikan hasil berbasis jalur yang ringan. Lihat Membuka file dan folder dengan pemilih di WinUI dan Menyimpan file dengan pemilih di WinUI.

API Windows.Storage.Pickers di halaman ini berlaku untuk aplikasi UWP dan ke aplikasi desktop yang memerlukan elevasi (di mana pemilih SDK Aplikasi Windows tidak dapat digunakan).

API penting

• FileOpenPicker
• FolderPicker
• StorageFile

Akses file dan folder dengan memungkinkan pengguna berinteraksi dengan pemilih berkas. Anda dapat menggunakan kelas FileOpenPicker dan FileSavePicker untuk mengakses file, dan FolderPicker untuk mengakses folder.

Catatan

 Untuk contoh lengkap, lihat File picker sample.

Prasyarat

• Memahami pemrograman asinkron untuk aplikasi Platform Windows Universal (UWP)

  Anda dapat mempelajari cara menulis aplikasi asinkron di C# atau Visual Basic, lihat Memanggil API asinkron di C# atau Visual Basic. Untuk mempelajari cara menulis aplikasi asinkron di C++, lihat Pemrograman asinkron di C++.

• Izin akses ke lokasi

  Lihat Izin akses file.

UI pemilih file

Pemilih file menampilkan informasi untuk mengorientasi pengguna dan memberikan pengalaman yang konsisten saat membuka atau menyimpan file.

Informasi tersebut meliputi:

• Lokasi saat ini
• Item atau barang yang telah dipilih pengguna
• Pohon lokasi yang dapat dijelajahi pengguna. Lokasi ini mencakup lokasi sistem file—seperti folder Musik atau Unduhan—serta aplikasi yang mengimplementasikan kontrak pemilih file (seperti Kamera, Foto, dan Microsoft OneDrive).

Aplikasi email mungkin menampilkan pemilih file bagi pengguna untuk memilih lampiran.

Cara kerja alat pengambil

Dengan pemilih, aplikasi Anda dapat mengakses, menelusuri, dan menyimpan file dan folder di sistem pengguna. Aplikasi Anda menerima pilihan tersebut sebagai objek StorageFile dan StorageFolder, yang kemudian dapat Anda operasikan.

Pemilih menggunakan satu antarmuka terpadu untuk memungkinkan pengguna memilih file dan folder dari sistem file atau dari aplikasi lain. File yang dipilih dari aplikasi lain mirip dengan file dari sistem file: file tersebut dikembalikan sebagai objek StorageFile. Secara umum, aplikasi Anda dapat beroperasi dengan cara yang sama seperti objek lain. Aplikasi lain membuat file tersedia dengan berpartisipasi dalam kontrak penyeleksi file. Jika Anda ingin aplikasi Anda menyediakan file, lokasi penyimpanan, atau pembaruan file ke aplikasi lain, lihat Mengintegrasikan dengan kontrak pemilih file.

Misalnya, Anda dapat memanggil pemilih file di aplikasi sehingga pengguna dapat membuka file. Ini menjadikan aplikasi Anda sebagai aplikasi panggilan. Pemilih file berinteraksi dengan sistem dan/atau aplikasi lain untuk memungkinkan pengguna menavigasi dan memilih file. Saat pengguna Anda memilih file, pemilih file mengembalikan file tersebut ke aplikasi Anda. Berikut adalah proses untuk kasus pengguna memilih file dari aplikasi yang menyediakan, seperti OneDrive.

Pilih satu file: daftar kode lengkap

var picker = new Windows.Storage.Pickers.FileOpenPicker();
picker.ViewMode = Windows.Storage.Pickers.PickerViewMode.Thumbnail;
picker.SuggestedStartLocation = Windows.Storage.Pickers.PickerLocationId.PicturesLibrary;
picker.FileTypeFilter.Add(".jpg");
picker.FileTypeFilter.Add(".jpeg");
picker.FileTypeFilter.Add(".png");

Windows.Storage.StorageFile file = await picker.PickSingleFileAsync();
if (file != null)
{
    // Application now has read/write access to the picked file
    this.textBlock.Text = "Picked photo: " + file.Name;
}
else
{
    this.textBlock.Text = "Operation cancelled.";
}

Pilih satu file: langkah demi langkah

Menggunakan pemilih file melibatkan pembuatan dan penyesuaian objek pemilih file, lalu memperlihatkan pemilih file sehingga pengguna dapat memilih satu atau beberapa item.

1. Membuat dan menyesuaikan FileOpenPicker

   var picker = new Windows.Storage.Pickers.FileOpenPicker();
   picker.ViewMode = Windows.Storage.Pickers.PickerViewMode.Thumbnail;
   picker.SuggestedStartLocation = Windows.Storage.Pickers.PickerLocationId.PicturesLibrary;
   picker.FileTypeFilter.Add(".jpg");
   picker.FileTypeFilter.Add(".jpeg");
   picker.FileTypeFilter.Add(".png");
   

   Atur properti pada objek pemilih file yang relevan dengan pengguna dan aplikasi Anda.

   Contoh ini membuat tampilan gambar yang kaya dan visual di lokasi yang nyaman yang dapat dipilih pengguna dengan mengatur tiga properti: ViewMode, SuggestedStartLocation, dan FileTypeFilter.

   • Mengatur ViewMode ke nilai enum PickerViewMode Thumbnail membuat tampilan visual yang kaya dengan menggunakan gambar mini gambar untuk mewakili file dalam pemilih file. Lakukan ini untuk memilih file visual seperti gambar atau video. Jika tidak, gunakan PickerViewMode.List. Aplikasi email hipotetis dengan fitur Lampirkan Gambar atau Video dan Lampirkan Dokumen akan mengatur ViewMode yang sesuai dengan fitur sebelum menampilkan pemilih file.

   • Mengatur SuggestedStartLocation ke Gambar menggunakan PickerLocationId.PicturesLibrary memulai pengguna di lokasi di mana mereka cenderung menemukan gambar. Atur SuggestedStartLocation ke lokasi yang sesuai untuk jenis file yang dipilih, misalnya Musik, Gambar, Video, atau Dokumen. Dari lokasi awal, pengguna dapat menavigasi ke lokasi lain.

   • Menggunakan FileTypeFilter untuk menentukan jenis file membuat pengguna tetap fokus pada memilih file yang relevan. Untuk mengganti tipe file sebelumnya di FileTypeFilter dengan entri baru, gunakan ReplaceAll alih-alih Tambahkan.

2. Perlihatkan FileOpenPicker

   • Untuk memilih satu file

     Windows.Storage.StorageFile file = await picker.PickSingleFileAsync();
     if (file != null)
     {
         // Application now has read/write access to the picked file
         this.textBlock.Text = "Picked photo: " + file.Name;
     }
     else
     {
         this.textBlock.Text = "Operation cancelled.";
     }
     

   • Untuk memilih beberapa file

     var files = await picker.PickMultipleFilesAsync();
     if (files.Count > 0)
     {
         StringBuilder output = new StringBuilder("Picked files:\n");
     
         // Application now has read/write access to the picked file(s)
         foreach (Windows.Storage.StorageFile file in files)
         {
             output.Append(file.Name + "\n");
         }
         this.textBlock.Text = output.ToString();
     }
     else
     {
         this.textBlock.Text = "Operation cancelled.";
     }
     

Pilih folder: daftar lengkap kode

var folderPicker = new Windows.Storage.Pickers.FolderPicker();
folderPicker.SuggestedStartLocation = Windows.Storage.Pickers.PickerLocationId.Desktop;
folderPicker.FileTypeFilter.Add("*");

Windows.Storage.StorageFolder folder = await folderPicker.PickSingleFolderAsync();
if (folder != null)
{
    // Application now has read/write access to all contents in the picked folder
    // (including other sub-folder contents)
    Windows.Storage.AccessCache.StorageApplicationPermissions.
    FutureAccessList.AddOrReplace("PickedFolderToken", folder);
    this.textBlock.Text = "Picked folder: " + folder.Name;
}
else
{
    this.textBlock.Text = "Operation cancelled.";
}

Petunjuk / Saran

Setiap kali aplikasi Anda mengakses file atau folder melalui pemilih file, tambahkan ke FutureAccessList atau MostRecentlyUsedList aplikasi Anda untuk melacaknya. Anda dapat mempelajari selengkapnya tentang menggunakan daftar ini di Cara melacak file dan folder yang baru digunakan.

Lihat juga

Windows.Storage.Pickers

File, folder, dan perpustakaan

Mengintegrasikan dengan antarmuka pemilih berkas