UIDocumentPickerViewController — nó là gì, làm việc với tài liệu iOS

UIDocumentPickerViewController là gì?

UIDocumentPickerViewController là một bộ điều khiển UIKit cung cấp giao diện hệ thống để chọn tài liệu. Nó là một phần của framework UIKit và có sẵn từ iOS 8. Bộ điều khiển hiển thị trình duyệt tệp bao gồm bộ nhớ cục bộ, iCloud Drive và các dịch vụ đám mây của bên thứ ba đã đăng ký.

Bộ điều khiển hoạt động không đồng bộ: sau khi gọi present, người dùng thấy một hộp thoại hệ thống, chọn một tệp và kết quả được trả về thông qua ủy quyền. Ứng dụng không yêu cầu quyền đặc biệt để truy cập tệp đã chọn — trình chọn hệ thống tự động cung cấp quyền truy cập tạm thời vào URI.

UIDocumentPickerViewController hỗ trợ iPad thông qua UIPopoverPresentationController và giao diện thích ứng cho iPhone. Từ iOS 14, bộ điều khiển đã nhận được thiết kế cập nhật và hỗ trợ điều hướng thanh bên trong iPadOS.

Chế độ hoạt động: import và export

UIDocumentPickerViewController hoạt động ở hai chế độ chính, mỗi chế độ xác định cách ứng dụng truy cập tệp. Chế độ được thiết lập thông qua tham số forOpeningContentTypes hoặc forExporting tùy theo nhiệm vụ.

Import mode (forOpeningContentTypes) sao chép tệp đã chọn vào hộp cát của ứng dụng. Ứng dụng nhận được URL đến bản sao của riêng mình, chỉ có ứng dụng mới truy cập được. Đây là chế độ an toàn: tệp của ứng dụng khác không bị sửa đổi và bản sao hoàn toàn do ứng dụng hiện tại kiểm soát.

Export mode (forExporting) cung cấp URL đến tệp gốc mà không sao chép. Ứng dụng có thể đọc tệp qua liên kết, nhưng các thay đổi không được lưu lại. Chế độ này được sử dụng khi cần chuyển tệp sang ứng dụng khác hoặc gửi qua email. Để ghi các thay đổi, chế độ open với scoped security-scoped URL được sử dụng.

Thiết lập picker và lọc theo UTI

UTI (Uniform Type Identifier) là hệ thống nhận dạng loại nội dung trong hệ sinh thái Apple. UIDocumentPickerViewController lọc các tệp hiển thị theo mảng UTI được truyền qua forOpeningContentTypes. Nếu không có UTI nào được chỉ định, trình chọn hiển thị tất cả các loại tệp.

• PDF — com.adobe.pdf. Trình chọn chỉ hiển thị tài liệu PDF.
• Hình ảnh — public.image. Bao gồm JPEG, PNG, HEIC và các định dạng khác.
• Văn bản — public.plain-text. Hiển thị tệp .txt, .csv và các tệp văn bản khác.
• Âm thanh — public.audio. Bao gồm MP3, AAC, WAV và các định dạng Lossless.
• Video — public.movie. Hiển thị MP4, MOV, AVI và các định dạng video khác.

Để chọn nhiều loại, hãy truyền mảng [UTType.pdf, UTType.image]. Từ iOS 14, Apple khuyên dùng UTType thay vì hằng chuỗi. UIDocumentPickerViewController tự động cập nhật danh sách các loại hiển thị khi nhà cung cấp được chọn thay đổi.

Ví dụ mã: chọn tài liệu trong Swift

Triển khai UIDocumentPickerViewController trong Swift rất tối thiểu: tạo một thể hiện bộ điều khiển với các loại UTI, đặt ủy quyền và gọi present. Sau khi tệp được chọn, ủy quyền nhận được mảng URL trong phương thức didPickDocumentsAt. Mỗi URL là một tham chiếu security-scoped yêu cầu gọi 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() }
    // đọc tệp từ url
}

Tài nguyên Security-Scoped

URL security-scoped yêu cầu gọi startAccessingSecurityScopedResource trước khi đọc. Phương thức này thông báo cho hệ thống rằng ứng dụng đang truy cập tạm thời vào một tệp bên ngoài hộp cát. Sau khi hoàn thành, luôn gọi stopAccessingSecurityScopedResource, nếu không hệ thống có thể chặn quyền truy cập.

UIDocumentPickerDelegate và xử lý kết quả

UIDocumentPickerDelegate nhận kết quả chọn tệp qua hai phương thức: didPickDocumentsAt khi thành công và didPickDocumentsAt khi hủy. iOS tự động gọi phương thức hủy nếu người dùng đóng trình chọn mà không chọn.

Xử lý lỗi bao gồm kiểm tra tính khả dụng của URL. Nếu người dùng chọn tệp từ iCloud Drive nhưng thiết bị ngoại tuyến, URL có thể không khả dụng. Nên kiểm tra FileManager.default.isReadableFile trước khi đọc và hiển thị thông báo lỗi rõ ràng cho người dùng.

Đối với iOS 14+, phương thức mới documentPicker:didPickDocumentsAt với mảng URL có sẵn. Phương thức cũ didPickDocumentAt (đơn lẻ) đã lỗi thời. Luôn xử lý mảng, ngay cả khi allowsMultipleSelection bị tắt — Apple khuyên dùng một trình xử lý duy nhất.

UIDocumentPickerViewController trên iPad

iPad yêu cầu cấu hình đặc biệt cho UIDocumentPickerViewController. Trên iPad, trình chọn được hiển thị dưới dạng popover và cần chỉ định sourceView để định vị chính xác. Nếu không có sourceView, bộ điều khiển có thể bị lỗi với ngoại lệ trên iPadOS.

Đối với popover, thuộc tính popoverPresentationController được sử dụng. Chỉ định sourceView và sourceRect để neo vào một nút hoặc ô bảng. Trên iPhone, mã này không có tác dụng — iOS tự động hiển thị trình chọn toàn màn hình. Từ iPadOS 16, bộ điều khiển hỗ trợ thanh bên và chế độ chia đôi để điều hướng tốt hơn.

Thiết kế thích ứng của UIDocumentPickerViewController tự động chuyển đổi giữa toàn màn hình (iPhone) và popover (iPad). Nhà phát triển không cần triển khai các bộ điều khiển riêng cho các thiết bị khác nhau — chỉ cần cấu hình đúng popoverPresentationController cho iPad là đủ.