UIDocumentPickerViewController — paggawa gamit ang mga dokumento sa iOS

Ano ang UIDocumentPickerViewController?

UIDocumentPickerViewController — ay isang UIKit controller na nagbibigay ng system interface para sa pagpili ng mga dokumento. Ito ay bahagi ng UIKit framework at available mula noong iOS 8. Ang controller ay nagpapakita ng file browser na kinabibilangan ng lokal na storage, iCloud Drive, at mga rehistradong third-party na cloud services.

Ang controller ay gumagana nang asynchronous: pagkatapos tawagin ang present, nakikita ng user ang system dialog, pumipili ng file, at ang resulta ay ibinabalik sa pamamagitan ng delegate. Ang app ay hindi nangangailangan ng mga espesyal na pahintulot para ma-access ang napiling file — ang system picker ay awtomatikong nagbibigay ng pansamantalang access sa URI.

Sinusuportahan ng UIDocumentPickerViewController ang iPad sa pamamagitan ng UIPopoverPresentationController at adaptive interface para sa iPhone. Mula noong iOS 14, nakatanggap ang controller ng updated na disenyo at suporta para sa sidebar navigation sa iPadOS.

Mga mode ng trabaho: import at export

UIDocumentPickerViewController ay gumagana sa dalawang pangunahing mode, na ang bawat isa ay tumutukoy kung paano ina-access ng app ang file. Ang mode ay itinakda sa pamamagitan ng parameter na forOpeningContentTypes o forExporting depende sa gawain.

Import mode (forOpeningContentTypes) kinokopya ang napiling file sa sandbox ng app. Ang app ay tumatanggap ng URL ng sarili nitong kopya ng file, na tanging ito lamang ang makaka-access. Ito ay isang ligtas na mode: ang file ng ibang app ay hindi binabago, at ang kopya ay ganap na kinokontrol ng kasalukuyang app.

Export mode (forExporting) ay nagbibigay ng URL sa orihinal na file nang walang pagkopya. Maaaring basahin ng app ang file sa pamamagitan ng link, ngunit ang mga pagbabago ay hindi nai-save pabalik. Ang mode na ito ay ginagamit kapag kailangan ilipat ang file sa ibang app o ipadala ito sa pamamagitan ng email. Para sa pagsulat ng mga pagbabago, ginagamit ang open mode na may security-scoped URL.

Pag-configure ng picker at pag-filter ayon sa UTI

UTI (Uniform Type Identifier) — ay isang sistema ng pagkilala sa mga uri ng nilalaman sa Apple ecosystem. Ang UIDocumentPickerViewController ay nag-filter ng mga ipinapakitang file batay sa UTI array na ipinadala sa pamamagitan ng forOpeningContentTypes. Kung walang tinukoy na UTI, ipinapakita ng picker ang lahat ng uri ng file.

• PDF — com.adobe.pdf. Ang picker ay nagpapakita lamang ng mga PDF na dokumento.
• Mga Larawan — public.image. Kasama ang JPEG, PNG, HEIC at iba pang format.
• Teksto — public.plain-text. Nagpapakita ng .txt, .csv at iba pang text file.
• Audio — public.audio. Kasama ang MP3, AAC, WAV at Lossless na format.
• Video — public.movie. Nagpapakita ng MP4, MOV, AVI at iba pang video format.

Para sa pagpili ng maraming uri, ang array na [UTType.pdf, UTType.image] ay ipinapadala. Mula noong iOS 14, inirerekomenda ng Apple ang paggamit ng UTType sa halip na mga string constant. Awtomatikong ina-update ng UIDocumentPickerViewController ang listahan ng mga ipinapakitang uri kapag nagbago ang napiling provider.

Halimbawa ng code: pagpili ng dokumento sa Swift

Implementasyon ng UIDocumentPickerViewController sa Swift ay minimal: gumawa ng instance ng controller na may mga uri ng UTI, itakda ang delegate, at tawagin ang present. Pagkatapos pumili ng file, ang delegate ay tumatanggap ng array ng mga URL sa pamamaraang didPickDocumentsAt. Bawat URL ay isang security-scoped link na nangangailangan ng pagtawag sa 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() }
    // basahin ang file mula sa url
}

Mga security-scoped na resource

Ang security-scoped URL ay nangangailangan ng pagtawag sa startAccessingSecurityScopedResource bago magbasa. Ang pamamaraang ito ay nagpapaalam sa system na ang app ay nakakakuha ng pansamantalang access sa isang file sa labas ng sandbox. Pagkatapos ng trabaho, siguraduhing tawagin ang stopAccessingSecurityScopedResource, kung hindi ay maaaring i-block ng system ang access.

UIDocumentPickerDelegate at paghawak ng mga resulta

UIDocumentPickerDelegate ay tumatanggap ng mga resulta ng pagpili ng file sa pamamagitan ng dalawang pamamaraan: didPickDocumentsAt sa tagumpay at didPickDocumentsAt sa pagkansela. Awtomatikong tinatawag ng iOS ang pagkansela kung isinara ng user ang picker nang walang pinili.

Ang paghawak ng error ay kasama ang pagsusuri ng availability ng URL. Kung ang user ay pumili ng file mula sa iCloud Drive ngunit ang device ay offline, ang URL ay maaaring hindi available. Inirerekomenda na suriin ang FileManager.default.isReadableFile bago magbasa at magpakita ng naiintindihang mensahe ng error sa user.

Para sa iOS 14+, ang bagong pamamaraang documentPicker:didPickDocumentsAt na may array ng mga URL ay available. Ang lumang pamamaraang didPickDocumentAt (iisa) ay deprecated. Palaging hawakan ang array, kahit na naka-disable ang allowsMultipleSelection — inirerekomenda ng Apple ang paggamit ng iisang handler.

UIDocumentPickerViewController sa iPad

iPad ay nangangailangan ng espesyal na configuration ng UIDocumentPickerViewController. Sa iPad, ang picker ay ipinapakita bilang popover at kailangang tukuyin ang sourceView para sa tamang pagpoposisyon. Kung walang sourceView, ang controller ay maaaring mag-crash na may exception sa iPadOS.

Para sa popover, ginagamit ang property na popoverPresentationController. Tukuyin ang sourceView at sourceRect para sa pag-angkla sa isang button o table cell. Sa iPhone, ang code na ito ay walang epekto — awtomatikong ipinapakita ng iOS ang picker sa full screen. Mula noong iPadOS 16, sinusuportahan ng controller ang sidebar at split view para sa pinahusay na navigation.

Ang adaptive na disenyo ng UIDocumentPickerViewController ay awtomatikong lumilipat sa pagitan ng full-screen (iPhone) at popover (iPad). Ang developer ay hindi kailangang mag-implement ng magkakahiwalay na controller para sa iba't ibang device — sapat na ang tamang pag-configure ng popoverPresentationController para sa iPad.