UIDocumentPickerViewController — 개요, iOS에서 문서 작업

UIDocumentPickerViewController란?

UIDocumentPickerViewController는 문서 선택을 위한 시스템 인터페이스를 제공하는 UIKit 컨트롤러입니다. UIKit 프레임워크의 일부이며 iOS 8부터 사용할 수 있습니다. 이 컨트롤러는 로컬 저장소, iCloud Drive 및 등록된 타사 클라우드 서비스를 포함하는 파일 브라우저를 표시합니다.

컨트롤러는 비동기적으로 작동합니다: present를 호출하면 사용자가 시스템 대화상자를 보고 파일을 선택하며 결과가 델리게이트를 통해 반환됩니다. 앱은 선택한 파일에 접근하기 위해 특별한 권한이 필요하지 않습니다 — 시스템 피커가 자동으로 URI에 대한 임시 접근을 제공합니다.

UIDocumentPickerViewController는 UIPopoverPresentationController를 통해 iPad를 지원하며 iPhone용 적응형 인터페이스를 제공합니다. iOS 14부터 컨트롤러는 업데이트된 디자인과 iPadOS의 사이드바 탐색 지원을 받았습니다.

작동 모드: import 및 export

UIDocumentPickerViewController는 두 가지 주요 모드로 작동하며, 각 모드는 앱이 파일에 접근하는 방식을 결정합니다. 모드는 작업에 따라 forOpeningContentTypes 또는 forExporting 매개변수를 통해 설정됩니다.

Import mode(forOpeningContentTypes)는 선택한 파일을 앱 샌드박스에 복사합니다. 앱은 파일의 자체 복사본에 대한 URL을 받으며, 해당 복사본은 앱만 접근할 수 있습니다. 이것은 안전한 모드입니다: 다른 앱의 파일은 수정되지 않으며 복사본은 현재 앱에 의해 완전히 제어됩니다.

Export mode(forExporting)는 복사 없이 원본 파일에 대한 URL을 제공합니다. 앱은 링크를 통해 파일을 읽을 수 있지만 변경 사항은 저장되지 않습니다. 이 모드는 파일을 다른 앱으로 전송하거나 이메일로 보내야 할 때 사용됩니다. 변경 사항을 쓰려면 scoped security-scoped URL과 함께 open 모드가 사용됩니다.

피커 설정 및 UTI 필터링

UTI(Uniform Type Identifier)는 Apple 생태계의 콘텐츠 유형 식별 시스템입니다. UIDocumentPickerViewController는 forOpeningContentTypes를 통해 전달된 UTI 배열에 따라 표시되는 파일을 필터링합니다. 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에서 문서 선택

구현 Swift에서 UIDocumentPickerViewController는 최소한입니다: UTI 유형으로 컨트롤러 인스턴스를 생성하고 델리게이트를 설정한 후 present를 호출합니다. 파일이 선택되면 델리게이트는 didPickDocumentsAt 메서드에서 URL 배열을 받습니다. 각 URL은 startAccessingSecurityScopedResource를 호출해야 하는 security-scoped 참조입니다.

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 리소스

Security-scoped URL은 읽기 전에 startAccessingSecurityScopedResource를 호출해야 합니다. 이 메서드는 앱이 샌드박스 외부의 파일에 임시 접근을 얻고 있음을 시스템에 알립니다. 완료 후에는 항상 stopAccessingSecurityScopedResource를 호출하세요. 그렇지 않으면 시스템이 접근을 차단할 수 있습니다.

UIDocumentPickerDelegate 및 결과 처리

UIDocumentPickerDelegate는 두 가지 메서드를 통해 파일 선택 결과를 받습니다: 성공 시 didPickDocumentsAt과 취소 시 didPickDocumentsAt입니다. 사용자가 선택 없이 피커를 닫으면 iOS가 자동으로 취소 메서드를 호출합니다.

오류 처리에는 URL 가용성 확인이 포함됩니다. 사용자가 iCloud Drive에서 파일을 선택했지만 장치가 오프라인인 경우 URL을 사용할 수 없을 수 있습니다. 읽기 전에 FileManager.default.isReadableFile을 확인하고 사용자에게 명확한 오류 메시지를 표시하는 것이 좋습니다.

iOS 14+의 경우 URL 배열과 함께 새로운 메서드 documentPicker:didPickDocumentsAt을 사용할 수 있습니다. 이전 메서드 didPickDocumentAt(단일)은 더 이상 사용되지 않습니다. allowsMultipleSelection이 비활성화되어 있어도 항상 배열을 처리하세요 — Apple은 단일 핸들러 사용을 권장합니다.

iPad에서 UIDocumentPickerViewController

iPad에서는 UIDocumentPickerViewController의 특별한 구성이 필요합니다. iPad에서 피커는 팝오버로 표시되며 올바른 위치 지정을 위해 sourceView를 지정해야 합니다. sourceView가 없으면 컨트롤러가 iPadOS에서 예외와 함께 충돌할 수 있습니다.

팝오버의 경우 popoverPresentationController 속성이 사용됩니다. sourceView와 sourceRect를 지정하여 버튼이나 테이블 셀에 고정합니다. iPhone에서는 이 코드가 효과가 없습니다 — iOS가 자동으로 피커를 전체 화면으로 표시합니다. iPadOS 16부터 컨트롤러는 향상된 탐색을 위해 사이드바 및 분할 보기를 지원합니다.

UIDocumentPickerViewController의 적응형 디자인은 전체 화면(iPhone)과 팝오버(iPad) 사이를 자동으로 전환합니다. 개발자는 다른 장치에 대해 별도의 컨트롤러를 구현할 필요가 없습니다 — iPad용 popoverPresentationController를 올바르게 구성하는 것으로 충분합니다.