UIDocumentPickerViewController — มันคืออะไร, การทำงานกับเอกสาร iOS

UIDocumentPickerViewController คืออะไร?

UIDocumentPickerViewController เป็นตัวควบคุม UIKit ที่ให้อินเทอร์เฟียสระบบสำหรับเลือกเอกสาร มันเป็นส่วนหนึ่งของเฟรมเวิร์ค UIKit และใช้ได้ตั้งแต่ iOS 8 ตัวควบคุมจะแสดงตัวเฟิล์บราว์เซอร์ที่รวมหน่วยความจำท้องถิ่น, iCloud Drive และบริการเมฆของบุคคลที่สามที่ลงทะเบียนแล้ว

ตัวควบคุมทำงานแบบไม่พร้อมกัน: หลังจากเรียก present, ผู้ใช้จะเห็นกล่องโต้ตอบระบบ, เลือกไฟล์ และผลลัพธ์จะถูกส่งคืนผ่านตัวแทน แอปไม่ต้องการอนุญาตพิเศษในการเข้าถึงไฟล์ที่เลือก — ตัวเลือกระบบจะให้การเข้าถึง URI แบบชั่วคราวโดยอัตโนมัติ

UIDocumentPickerViewController รองรับ iPad ผ่าน UIPopoverPresentationController และอินเทอร์เฟียสแบบปรับตัวสำหรับ iPhone ตั้งแต่ iOS 14, ตัวควบคุมได้รับการออกแบบที่อัพเดต และการรองรับแถบนำทางแบบ sidebar ใน iPadOS

โหมดการทำงาน: import และ export

UIDocumentPickerViewController ทำงานในสองโหมดหลัก, แต่ละโหมดจะกำหนดว่าแอปเข้าถึงไฟล์อย่างไร โหมดจะถูกตั้งผ่านพารามิเตอร์ forOpeningContentTypes หรือ forExporting ขึ้นอยู่กับงาน

Import mode (forOpeningContentTypes) คัดลอกไฟล์ที่เลือกไปยังกล่องทรายของแอป แอปจะได้รับ URL ไปยังสำเนาของตัวเองของไฟล์, เพื่อใช้เฉพาะแอปนั้น นี่เป็นโหมดที่ปลอดภัย: ไฟล์ของแอปอื่นจะไม่ถูกแก้ไข และสำเนาจะถูกควบคุมโดยแอปปัจจุบันอย่างสมบูรณ์

Export mode (forExporting) ให้ URL ไปยังไฟล์ต้นฉบับโดยไม่ต้องคัดลอก แอปสามารถอ่านไฟล์ผ่านลิงก์, แต่การเปลี่ยนแปลงจะไม่ถูกบันทึก โหมดนี้ใช้เมื่อต้องการโอนเวนไฟล์ไปยังแอปอื่นหรือส่งทางอีเมล สำหรับการเขียนการเปลี่ยนแปลง, โหมด open กับ scoped security-scoped URL ถูกใช้

การตั้งค่า picker และการกรองโดย UTI

UTI (Uniform Type Identifier) เป็นระบบการระบุประเภทเนื้อหาในระบนนิเวศ Apple UIDocumentPickerViewController กรองไฟล์ที่แสดงตามอาร์เรย์ UTI ที่ส่งผ่าน forOpeningContentTypes หากไม่ได้ระบุ UTI, ตัวเลือกจะแสดงไฟล์ทุกประเภท

• PDF — com.adobe.pdf. ตัวเลือกแสดงเฉพาะเอกสาร PDF
• รูปภาพ — public.image. รวม JPEG, PNG, HEIC และรูปแบบอื่นๆ
• ข้อความ — public.plain-text. แสดงไฟล์ .txt, .csv และไฟล์ข้อความอื่นๆ
• เสียง — public.audio. รวม MP3, AAC, WAV และรูปแบบ Lossless
• วิดีโอ — public.movie. แสดง MP4, MOV, AVI และรูปแบบวิดีโออื่นๆ

สำหรับการเลือกหลายประเภท, อาร์เรย์ [UTType.pdf, UTType.image] จะถูกส่ง ตั้งแต่ iOS 14, Apple แนะนำให้ใช้ UTType แทนค่าคงที่เป็นสตริง UIDocumentPickerViewController จะอัพเดตรายการประเภทที่แสดงโดยอัตโนมัติเมื่อผู้ให้บริการที่เลือกเปลี่ยนไป

ตัวอย่างโค้ด: การเลือกเอกสารใน Swift

การนำไปใช้ UIDocumentPickerViewController ใน Swift เป็นไปอย่างน้อยที่สุด: สร้างอินสแตนซ์ของตัวควบคุมด้วยประเภท UTI, ตั้งตัวแทน และเรียก present หลังจากเลือกไฟล์แล้ว, ตัวแทนจะได้รับอาร์เรย์ของ URL ในมเธอดอ์ didPickDocumentsAt แต่ละ URL เป็นการอ้างอิงแบบ security-scoped ที่ต้องการเรียก 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() }
    // อ่านไฟล์จาก url
}

แหล่งทรัพยากร Security-Scoped

URL แบบ security-scoped ต้องการเรียก startAccessingSecurityScopedResource ก่อนอ่าน มเธอดอ์นี้จะแจ้งให้ระบบทราบว่าแอปกำลังเข้าถึงไฟล์นอกกล่องทรายแบบชั่วคราว หลังเสร็จเรียบร้อย, ให้เรียก stopAccessingSecurityScopedResource ทุกครั้ง, มิฉะนั้นระบบอาจบล็อกการเข้าถึง

UIDocumentPickerDelegate และการจัดการผลลัพธ์

UIDocumentPickerDelegate ได้รับผลลัพธ์การเลือกไฟล์ผ่านสองมเธอดอ์: didPickDocumentsAt เมื่อสำเร็จ และ didPickDocumentsAt เมื่อยกเลิก iOS จะเรียกมเธอดอ์การยกเลิกโดยอัตโนมัติหากผู้ใช้ปิดตัวเลือกโดยไม่ได้เลือก

การจัดการข้อผิดพลาดรวมถึงการตรวจสอบความพร้อมของ URL หากผู้ใช้เลือกไฟล์จาก iCloud Drive แต่อุปกรณ์ออฟไลน์, URL อาจไม่พร้อมใช้งาน แนะนำให้ตรวจสอบ FileManager.default.isReadableFile ก่อนอ่าน และแสดงข้อความผิดพลาดที่ชัดเจนแก่ผู้ใช้

สำหรับ iOS 14+, มีมเธอดอ์ใหม่ documentPicker:didPickDocumentsAt กับอาร์เรย์ของ URL มเธอดอ์เก่า didPickDocumentAt (เดียว) ถูกแตงว่าเป็น deprecated จัดการอาร์เรย์ตลอด, แม้ว่า allowsMultipleSelection จะถูกปิดก็ตาม — Apple แนะนำให้ใช้ตัวจัดการตัวเดียว

UIDocumentPickerViewController บน iPad

iPad ต้องการการกำหนดค่าพิเศษของ UIDocumentPickerViewController บน iPad, ตัวเลือกจะแสดงเป็น popover และต้องระบุ sourceView สำหรับการวางตำแหน่งที่ถูกต้อง หากไม่มี sourceView, ตัวควบคุมอาจตกโดยมี exception บน iPadOS

สำหรับ popover, ใช้คุณสมบัติ popoverPresentationController ระบุ sourceView และ sourceRect เพื่อยึดกับปุ่มหรือเซลล์ตาราง บน iPhone, โค้ดนี้ไม่มีผล — iOS จะแสดงตัวเลือกเต็มจอโดยอัตโนมัติ ตั้งแต่ iPadOS 16, ตัวควบคุมรองรับ sidebar และ split view สำหรับการนำทางที่ดีขึ้น

การออกแบบแบบปรับตัวของ UIDocumentPickerViewController จะสลับระหว่างเต็มจอ (iPhone) และ popover (iPad) โดยอัตโนมัติ นักพัฒนาไม่จำเป็นต้องทำงานตัวควบคุมแยกสำหรับอุปกรณ์ต่างๆ — แค่ต้องกำหนดค่า popoverPresentationController อย่างถูกต้องสำหรับ iPad