UIDocumentPickerViewController — bekerja dengan dokumen di iOS

Apa itu UIDocumentPickerViewController?

UIDocumentPickerViewController — adalah kontroler UIKit yang menyediakan antarmuka sistem untuk memilih dokumen. Ini adalah bagian dari framework UIKit dan tersedia sejak iOS 8. Kontroler menampilkan browser file yang mencakup penyimpanan lokal, iCloud Drive, dan layanan cloud pihak ketiga yang terdaftar.

Kontroler bekerja secara asinkron: setelah memanggil present, pengguna melihat dialog sistem, memilih file, dan hasilnya dikembalikan melalui delegasi. Aplikasi tidak memerlukan izin khusus untuk mengakses file yang dipilih — pemilih sistem secara otomatis memberikan akses sementara ke URI.

UIDocumentPickerViewController mendukung iPad melalui UIPopoverPresentationController dan antarmuka adaptif untuk iPhone. Mulai iOS 14, kontroler menerima desain yang diperbarui dan dukungan navigasi sidebar di iPadOS.

Mode kerja: import dan export

UIDocumentPickerViewController bekerja dalam dua mode utama, yang masing-masing menentukan bagaimana aplikasi mengakses file. Mode diatur melalui parameter forOpeningContentTypes atau forExporting tergantung pada tugas.

Mode Import (forOpeningContentTypes) menyalin file yang dipilih ke sandbox aplikasi. Aplikasi menerima URL salinan file miliknya sendiri, yang hanya dapat diakses olehnya. Ini adalah mode aman: file aplikasi lain tidak dimodifikasi, dan salinan sepenuhnya dikendalikan oleh aplikasi saat ini.

Mode Export (forExporting) menyediakan URL ke file asli tanpa menyalin. Aplikasi dapat membaca file melalui tautan, tetapi perubahan tidak disimpan kembali. Mode ini digunakan saat perlu mentransfer file ke aplikasi lain atau mengirimkannya melalui email. Untuk menulis perubahan, digunakan mode open dengan URL security-scoped.

Mengonfigurasi picker dan memfilter berdasarkan UTI

UTI (Uniform Type Identifier) — adalah sistem identifikasi jenis konten di ekosistem Apple. UIDocumentPickerViewController memfilter file yang ditampilkan berdasarkan array UTI yang dikirim melalui forOpeningContentTypes. Jika UTI tidak ditentukan, picker menampilkan semua jenis file.

• PDF — com.adobe.pdf. Picker hanya menampilkan dokumen PDF.
• Gambar — public.image. Mencakup JPEG, PNG, HEIC, dan format lainnya.
• Teks — public.plain-text. Menampilkan file .txt, .csv, dan file teks lainnya.
• Audio — public.audio. Mencakup MP3, AAC, WAV, dan format Lossless.
• Video — public.movie. Menampilkan MP4, MOV, AVI, dan format video lainnya.

Untuk memilih beberapa jenis, array [UTType.pdf, UTType.image] dikirimkan. Mulai iOS 14, Apple merekomendasikan penggunaan UTType sebagai pengganti konstanta string. UIDocumentPickerViewController secara otomatis memperbarui daftar jenis yang ditampilkan saat penyedia yang dipilih berubah.

Contoh kode: memilih dokumen di Swift

Implementasi UIDocumentPickerViewController di Swift minimal: buat instance kontroler dengan tipe UTI, atur delegasi, dan panggil present. Setelah memilih file, delegasi menerima array URL dalam metode didPickDocumentsAt. Setiap URL adalah tautan security-scoped yang memerlukan panggilan startAccessingSecurityScopedResource.

let picker = UIDocumentPickerViewController(
    forOpeningContentTypes: [.pdf, .image],
    asCopy: true
)
picker.delegate = self
picker.allowsMultipleSelection = false
present(picker, animated: true)

// MARK: - UIDocumentPickerDelegate
func documentPicker(
    _ controller: UIDocumentPickerViewController,
    didPickDocumentsAt urls: [URL]
) {
    guard let url = urls.first else { return }
    url.startAccessingSecurityScopedResource()
    defer { url.stopAccessingSecurityScopedResource() }
    // baca file dari url
}

Sumber daya security-scoped

URL security-scoped memerlukan panggilan startAccessingSecurityScopedResource sebelum membaca. Metode ini memberi tahu sistem bahwa aplikasi mendapatkan akses sementara ke file di luar sandbox. Setelah selesai, pastikan untuk memanggil stopAccessingSecurityScopedResource, jika tidak, sistem dapat memblokir akses.

UIDocumentPickerDelegate dan menangani hasil

UIDocumentPickerDelegate menerima hasil pemilihan file melalui dua metode: didPickDocumentsAt saat berhasil dan didPickDocumentsAt saat dibatalkan. iOS secara otomatis memanggil metode pembatalan jika pengguna menutup picker tanpa memilih.

Penanganan kesalahan mencakup pemeriksaan ketersediaan URL. Jika pengguna memilih file dari iCloud Drive tetapi perangkat offline, URL mungkin tidak tersedia. Disarankan untuk memeriksa FileManager.default.isReadableFile sebelum membaca dan menampilkan pesan kesalahan yang dapat dipahami kepada pengguna.

Untuk iOS 14+, metode baru documentPicker:didPickDocumentsAt dengan array URL tersedia. Metode lama didPickDocumentAt (tunggal) sudah tidak digunakan lagi. Selalu tangani array, bahkan jika allowsMultipleSelection dinonaktifkan — Apple merekomendasikan penggunaan satu handler terpadu.

UIDocumentPickerViewController di iPad

iPad memerlukan konfigurasi khusus UIDocumentPickerViewController. Di iPad, picker ditampilkan sebagai popover dan perlu menentukan sourceView untuk posisi yang benar. Tanpa sourceView, kontroler dapat crash dengan exception di iPadOS.

Untuk popover, properti popoverPresentationController digunakan. Tentukan sourceView dan sourceRect untuk menambatkan ke tombol atau sel tabel. Di iPhone, kode ini tidak berpengaruh — iOS secara otomatis menampilkan picker dalam layar penuh. Mulai iPadOS 16, kontroler mendukung sidebar dan split view untuk navigasi yang lebih baik.

Desain adaptif UIDocumentPickerViewController secara otomatis beralih antara full-screen (iPhone) dan popover (iPad). Pengembang tidak perlu mengimplementasikan kontroler terpisah untuk perangkat yang berbeda — cukup mengonfigurasi popoverPresentationController dengan benar untuk iPad.