UIDocumentPickerViewController — nedir, iOS belgeleriyle çalışma

UIDocumentPickerViewController nedir?

UIDocumentPickerViewController, belge seçmek için bir sistem arayüzü sağlayan bir UIKit denetleyicisidir. UIKit çerçevesinin bir parçasıdır ve iOS 8’den beri kullanılabilir. Denetleyici, yerel depolama, iCloud Drive ve kayıtlı üçüncü taraf bulut hizmetlerini içeren bir dosya tarayıcısı görüntüler.

Denetleyici asenkron çalışır: present çağrıldıktan sonra, kullanıcı bir sistem iletişim kutusu görür, bir dosya seçer ve sonuç temsilci aracılığıyla döndürülür. Uygulama, seçilen dosyaya erişmek için özel izinler gerektirmez — sistem seçicisi otomatik olarak URI’ye geçici erişim sağlar.

UIDocumentPickerViewController, UIPopoverPresentationController aracılığıyla iPad’i ve iPhone için uyarlanabilir bir arayüzü destekler. iOS 14’ten itibaren denetleyici, güncellenmiş bir tasarım ve iPadOS’te kenar çubuğu gezintisi desteği aldı.

Çalışma modları: import ve export

UIDocumentPickerViewController iki ana modda çalışır ve her biri uygulamanın dosyaya nasıl eriştiğini belirler. Mod, göreve bağlı olarak forOpeningContentTypes veya forExporting parametresi aracılığıyla ayarlanır.

Import mode (forOpeningContentTypes), seçilen dosyayı uygulama sanal alanına kopyalar. Uygulama, dosyanın yalnızca kendisinin erişebileceği kendi kopyasına bir URL alır. Bu güvenli bir moddur: başka bir uygulamanın dosyası değiştirilmez ve kopya tamamen mevcut uygulama tarafından kontrol edilir.

Export mode (forExporting), kopyalamadan orijinal dosyaya bir URL sağlar. Uygulama bağlantı aracılığıyla dosyayı okuyabilir, ancak değişiklikler kaydedilmez. Bu mod, bir dosyayı başka bir uygulamaya aktarmak veya e-posta ile göndermek gerektiğinde kullanılır. Değişiklikleri yazmak için, scoped security-scoped URL ile birlikte open modu kullanılır.

Seçici kurulumu ve UTI filtreleme

UTI (Uniform Type Identifier), Apple ekosisteminde içerik türü tanımlama sistemidir. UIDocumentPickerViewController, forOpeningContentTypes aracılığıyla iletilen UTI dizisine göre görüntülenen dosyaları filtreler. Hiçbir UTI belirtilmezse, seçici tüm dosya türlerini gösterir.

• PDF — com.adobe.pdf. Seçici yalnızca PDF belgelerini gösterir.
• Görüntüler — public.image. JPEG, PNG, HEIC ve diğer formatları içerir.
• Metin — public.plain-text. .txt, .csv ve diğer metin dosyalarını gösterir.
• Ses — public.audio. MP3, AAC, WAV ve Lossless formatlarını içerir.
• Video — public.movie. MP4, MOV, AVI ve diğer video formatlarını gösterir.

Birden çok tür seçmek için bir dizi [UTType.pdf, UTType.image] iletilir. iOS 14’ten itibaren Apple, dize sabitleri yerine UTType kullanılmasını önerir. UIDocumentPickerViewController, seçilen sağlayıcı değiştiğinde görüntülenen türlerin listesini otomatik olarak günceller.

Kod örneği: Swift’te belge seçimi

Uygulama Swift’te UIDocumentPickerViewController minimaldir: UTI türleriyle bir denetleyici örneği oluşturun, temsilciyi ayarlayın ve present çağrısı yapın. Dosya seçildikten sonra, temsilci didPickDocumentsAt yönteminde bir URL dizisi alır. Her URL, startAccessingSecurityScopedResource çağrısı gerektiren bir security-scoped referanstır.

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() }
    // dosyayı url’den oku
}

Security-Scoped Kaynaklar

Bir security-scoped URL, okumadan önce startAccessingSecurityScopedResource çağrısı gerektirir. Bu yöntem, uygulamanın sanal alan dışındaki bir dosyaya geçici erişim elde ettiğini sisteme bildirir. İşlem tamamlandıktan sonra her zaman stopAccessingSecurityScopedResource çağrısı yapın, aksi takdirde sistem erişimi engelleyebilir.

UIDocumentPickerDelegate ve sonuç işleme

UIDocumentPickerDelegate, dosya seçim sonuçlarını iki yöntem aracılığıyla alır: başarı durumunda didPickDocumentsAt ve iptal durumunda didPickDocumentsAt. Kullanıcı seçim yapmadan seçiciyi kapatırsa, iOS otomatik olarak iptal yöntemini çağrır.

Hata işleme, URL kullanılabilirliğini kontrol etmeyi içerir. Kullanıcı iCloud Drive’dan bir dosya seçtiyse ancak cihaz çevrimdışıysa, URL kullanılamayabilir. Okumadan önce FileManager.default.isReadableFile kontrolü yapılması ve kullanıcıya net bir hata mesajı gösterilmesi önerilir.

iOS 14+ için, URL dizisiyle birlikte yeni bir yöntem documentPicker:didPickDocumentsAt kullanılabilir. Eski yöntem didPickDocumentAt (tek) kullanımdan kaldırılmıştır. allowsMultipleSelection devre dışı olsa bile her zaman diziyi işleyin — Apple tek bir işleyici kullanılmasını önerir.

iPad’de UIDocumentPickerViewController

iPad, UIDocumentPickerViewController’ın özel yapılandırmasını gerektirir. iPad’de seçici bir popover olarak görüntülenir ve doğru konumlandırma için bir sourceView belirtmelidir. sourceView olmadan, denetleyici iPadOS’te bir istisna ile çökebilir.

Popover için popoverPresentationController özelliği kullanılır. Bir düğmeye veya tablo hücresine sabitlemek için sourceView ve sourceRect belirtin. iPhone’da bu kodun hiçbir etkisi yoktur — iOS seçiciyi otomatik olarak tam ekranda gösterir. iPadOS 16’dan itibaren denetleyici, gelişmiş gezinme için kenar çubuğu ve bölünmüş görünümü destekler.

UIDocumentPickerViewController’ın uyarlanabilir tasarımı, tam ekran (iPhone) ve popover (iPad) arasında otomatik olarak geçiş yapar. Geliştiricinin farklı cihazlar için ayrı denetleyiciler uygulaması gerekmez — iPad için popoverPresentationController’ı doğru şekilde yapılandırmak yeterlidir.