UIDocumentPickerViewController — iOS-da sənədlərlə iş

UIDocumentPickerViewController nədir?

UIDocumentPickerViewController — sənəd seçimi üçün sistem interfeysi təmin edən UIKit nəzarətçisidir. UIKit framework-ünə daxildir və iOS 8-dən etibarən mövcuddur. Nəzarətçi yerli yaddaş, iCloud Drive və qeydiyyatdan keçmiş üçüncü tərəf bulud xidmətlərini əhatə edən fayl brauzerini göstərir.

Nəzarətçi asinxron işləyir: present çağırışından sonra istifadəçi sistem dialoqunu görür, faylı seçir və nəticə delegat vasitəsilə qaytarılır. Tətbiq seçilmiş fayla giriş üçün xüsusi icazə tələb etmir — sistem pickeri avtomatik olaraq URI-yə müvəqqəti giriş təmin edir.

UIDocumentPickerViewController iPad-ı UIPopoverPresentationController və iPhone üçün adaptiv interfeys vasitəsilə dəstəkləyir. iOS 14-dən etibarən nəzarətçi yenilənmiş dizayn və iPadOS-da sidebar naviqasiya dəstəyi almışdır.

İş rejimləri: import və export

UIDocumentPickerViewController iki əsas rejimdə işləyir, hər biri tətbiqin fayla necə daxil olacağını müəyyən edir. Rejim tapşırıqdan asılı olaraq forOpeningContentTypes və ya forExporting parametri ilə təyin edilir.

Import rejimi (forOpeningContentTypes) seçilmiş faylı tətbiqin sandboxuna kopyalayır. Tətbiq faylın yalnız özünə məxsus surətinə URL alır. Bu təhlükəsiz rejimdir: başqa tətbiqin faylı dəyişdirilmir və surət cari tətbiq tərəfindən tam idarə olunur.

Export rejimi (forExporting) kopyalamadan orijinal fayla URL təqdim edir. Tətbiq faylı link vasitəsilə oxuya bilər, lakin dəyişikliklər geri yazılmır. Bu rejim faylı başqa tətbiqə ötürmək və ya poçtla göndərmək lazım olduqda istifadə olunur. Dəyişiklikləri yazmaq üçün security-scoped URL ilə open rejimi istifadə olunur.

Pickerin qurulması və UTI-ə görə filtrləmə

UTI (Uniform Type Identifier) — Apple ekosistemində məzmun tiplərinin identifikasiya sistemidir. UIDocumentPickerViewController göstərilən faylları forOpeningContentTypes vasitəsilə ötürülən UTI massivinə görə filtrləyir. UTI göstərilməzsə, picker bütün fayl tiplərini göstərir.

• PDF — com.adobe.pdf. Picker yalnız PDF sənədlərini göstərir.
• Şəkillər — public.image. JPEG, PNG, HEIC və digər formatları əhatə edir.
• Mətn — public.plain-text. .txt, .csv və digər mətn fayllarını göstərir.
• Audio — public.audio. MP3, AAC, WAV və Lossless formatlarını əhatə edir.
• Video — public.movie. MP4, MOV, AVI və digər video formatlarını göstərir.

Çox tip seçmək üçün [UTType.pdf, UTType.image] massivi ötürülür. iOS 14-dən etibarən Apple sətir sabitləri əvəzinə UTType istifadəsini tövsiyə edir. UIDocumentPickerViewController seçilmiş provayder dəyişdikdə göstərilən tiplərin siyahısını avtomatik yeniləyir.

Kod nümunəsi: Swift-də sənəd seçimi

Implementasiya Swift-də UIDocumentPickerViewController minimaldır: UTI tipləri ilə nəzarətçi nümunəsi yaradın, delegat təyin edin və present çağırın. Fayl seçimindən sonra delegat didPickDocumentsAt metodunda URL massivi alır. Hər URL startAccessingSecurityScopedResource çağırışı tələb edən security-scoped linkdir.

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() }
    // faylı url-dən oxu
}

Security-scoped resurslar

Security-scoped URL oxumadan əvvəl startAccessingSecurityScopedResource çağırışı tələb edir. Bu metod sistemə tətbiqin sandbox xaricindəki fayla müvəqqəti giriş əldə etdiyini bildirir. İş bitdikdən sonra mütləq stopAccessingSecurityScopedResource çağırın, əks halda sistem girişi bloklaya bilər.

UIDocumentPickerDelegate və nəticələrin idarə edilməsi

UIDocumentPickerDelegate fayl seçiminin nəticələrini iki metod vasitəsilə alır: didPickDocumentsAt uğur halında və didPickDocumentsAt ləğv edildikdə. iOS istifadəçi pickeri seçim etmədən bağladıqda avtomatik olaraq ləğv metodunu çağırır.

Xəta idarəetməsi URL-in əlçatanlığının yoxlanılmasını əhatə edir. İstifadəçi iCloud Drive-dan fayl seçibsə, lakin cihaz oflayndırsa, URL əlçatan olmaya bilər. Oxumadan əvvəl FileManager.default.isReadableFile yoxlamaq və istifadəçiyə anlaşılan xəta mesajı göstərmək tövsiyə olunur.

iOS 14+ üçün URL massivi ilə yeni documentPicker:didPickDocumentsAt metodu mövcuddur. Köhnə didPickDocumentAt (tək) metodu deprecated-dir. allowsMultipleSelection söndürülsə belə həmişə massivi idarə edin — Apple vahid handler istifadəsini tövsiyə edir.

iPad-da UIDocumentPickerViewController

iPad UIDocumentPickerViewController üçün xüsusi konfiqurasiya tələb edir. iPad-də picker popover kimi göstərilir və düzgün yerləşdirmə üçün sourceView təyin edilməlidir. SourceView olmadan nəzarətçi iPadOS-da exception ilə çökə bilər.

Popover üçün popoverPresentationController xassəsindən istifadə olunur. Düyməyə və ya cədvəl xanasına bağlamaq üçün sourceView və sourceRect təyin edin. iPhone-da bu kod təsir etmir — iOS avtomatik pickeri tam ekranda göstərir. iPadOS 16-dan etibarən nəzarətçi təkmilləşdirilmiş naviqasiya üçün sidebar və split view dəstəkləyir.

UIDocumentPickerViewController-ın adaptiv dizaynı avtomatik olaraq full-screen (iPhone) və popover (iPad) arasında keçid edir. Tərtibatçı müxtəlif cihazlar üçün ayrıca nəzarətçilər tətbiq etməlidir — iPad üçün popoverPresentationController-ı düzgün konfiqurasiya etmək kifayətdir.