photokit

PhotoKit

Swift 6.3 を使用し、iOS 26 以降を対象とした、写真の選択、カメラ撮影、画像の読み込み、メディア権限に関する最新のパターンです。特に記載がない限り、iOS 16 まで後方互換性があります。ピッカーのレシピ全般については references/photokit-patterns.md、AVCaptureSession のパターンについては references/camera-capture.md を参照してください。

目次

• PhotosPicker（SwiftUI、iOS 16 以降）
• プライバシーと権限
• カメラ撮影の基本
• 画像の読み込みと表示
• よくある間違い
• レビュー用チェックリスト
• 参考資料

PhotosPicker（SwiftUI、iOS 16 以降）

PhotosPicker は、UIImagePickerController に代わる SwiftUI ネイティブの仕組みです。プロセス外で動作するため、写真ライブラリの閲覧に権限は不要で、メディアタイプで絞り込みながら、単一または複数の項目を選択できます。

単一選択

import SwiftUI
import PhotosUI

struct SinglePhotoPicker: View {
    @State private var selectedItem: PhotosPickerItem?
    @State private var selectedImage: Image?

    var body: some View {
        VStack {
            if let selectedImage {
                selectedImage
                    .resizable()
                    .scaledToFit()
                    .frame(maxHeight: 300)
            }

            PhotosPicker("Select Photo", selection: $selectedItem, matching: .images)
        }
        .onChange(of: selectedItem) { _, newItem in
            Task {
                if let data = try? await newItem?.loadTransferable(type: Data.self),
                   let uiImage = UIImage(data: data) {
                    selectedImage = Image(uiImage: uiImage)
                }
            }
        }
    }
}

複数選択

struct MultiPhotoPicker: View {
    @State private var selectedItems: [PhotosPickerItem] = []
    @State private var selectedImages: [Image] = []

    var body: some View {
        VStack {
            ScrollView(.horizontal) {
                HStack {
                    ForEach(selectedImages.indices, id: \.self) { index in
                        selectedImages[index]
                            .resizable()
                            .scaledToFill()
                            .frame(width: 100, height: 100)
                            .clipShape(.rect(cornerRadius: 8))
                    }
                }
            }

            PhotosPicker(
                "Select Photos",
                selection: $selectedItems,
                maxSelectionCount: 5,
                matching: .images
            )
        }
        .onChange(of: selectedItems) { _, newItems in
            Task {
                selectedImages = []
                for item in newItems {
                    if let data = try? await item.loadTransferable(type: Data.self),
                       let uiImage = UIImage(data: data) {
                        selectedImages.append(Image(uiImage: uiImage))
                    }
                }
            }
        }
    }
}

メディアタイプによる絞り込み

PHPickerFilter の複合条件で、選択できるメディアを制限します。

// Images only
PhotosPicker(selection: $items, matching: .images)

// Videos only
PhotosPicker(selection: $items, matching: .videos)

// Live Photos only
PhotosPicker(selection: $items, matching: .livePhotos)

// Screenshots only
PhotosPicker(selection: $items, matching: .screenshots)

// Images and videos combined
PhotosPicker(selection: $items, matching: .any(of: [.images, .videos]))

// Images excluding screenshots
PhotosPicker(selection: $items, matching: .all(of: [.images, .not(.screenshots)]))

Transferable を使った選択項目の読み込み

PhotosPickerItem は、loadTransferable(type:) を使ってコンテンツを非同期に読み込みます。自動デコードを行うには、Transferable 型を定義します。

struct PickedImage: Transferable {
    let data: Data
    let image: Image

    static var transferRepresentation: some TransferRepresentation {
        DataRepresentation(importedContentType: .image) { data in
            guard let uiImage = UIImage(data: data) else {
                throw TransferError.importFailed
            }
            return PickedImage(data: data, image: Image(uiImage: uiImage))
        }
    }
}

enum TransferError: Error {
    case importFailed
}

// Usage
if let picked = try? await item.loadTransferable(type: PickedImage.self) {
    selectedImage = picked.image
}

メインスレッドをブロックしないよう、必ず Task 内で読み込んでください。nil が返された場合やエラーがスローされた場合にも対処してください。ユーザーがデコードできない形式を選択する可能性があります。

プライバシーと権限

写真ライブラリのアクセスレベル

iOS では、写真ライブラリに対して 2 つのアクセスレベルが用意されています。アプリが .readWrite アクセスを要求すると、システムは限定ライブラリのピッカーを自動的に表示し、ユーザーは共有する写真を選択します。

アクセスレベル	説明	Info.plist キー
追加のみ	写真ライブラリへの書き込みは可能、読み取りは不可	NSPhotoLibraryAddUsageDescription
読み書き	全体または限定的な読み取りアクセスに加え、書き込みも可能	NSPhotoLibraryUsageDescription

PhotosPicker での閲覧に権限は不要です。プロセス外で動作し、選択された項目へのアクセスのみを許可します。写真ライブラリ全体の読み取り（カスタムギャラリーなど）や写真の保存が必要な場合に限り、明示的に権限を要求してください。

写真ライブラリの権限を確認および要求する

import Photos

func requestPhotoLibraryAccess() async -> PHAuthorizationStatus {
    let status = PHPhotoLibrary.authorizationStatus(for: .readWrite)

    switch status {
    case .notDetermined:
        return await PHPhotoLibrary.requestAuthorization(for: .readWrite)
    case .authorized, .limited:
        return status
    case .denied, .restricted:
        return status
    @unknown default:
        return status
    }
}

カメラの権限

Info.plist に NSCameraUsageDescription を追加してください。キャプチャセッションを構成する前に、アクセスを確認して要求します。

import AVFoundation

func requestCameraAccess() async -> Bool {
    let status = AVCaptureDevice.authorizationStatus(for: .video)

    switch status {
    case .notDetermined:
        return await AVCaptureDevice.requestAccess(for: .video)
    case .authorized:
        return true
    case .denied, .restricted:
        return false
    @unknown default:
        return false
    }
}

拒否された権限への対応

ユーザーがアクセスを拒否した場合は、設定アプリへ誘導してください。繰り返し許可を求めたり、機能を黙って非表示にしたりしないでください。

struct PermissionDeniedView: View {
    let message: String
    @Environment(\.openURL) private var openURL

    var body: some View {
        ContentUnavailableView {
            Label("Access Denied", systemImage: "lock.shield")
        } description: {
            Text(message)
        } actions: {
            Button("Open Settings") {
                if let url = URL(string: UIApplication.openSettingsURLString) {
                    openURL(url)
                }
            }
        }
    }
}

必須の Info.plist キー

キー	必要な場合
NSPhotoLibraryUsageDescription	ライブラリから写真を読み取る場合
NSPhotoLibraryAddUsageDescription	写真やビデオをライブラリに保存する場合
NSCameraUsageDescription	カメラにアクセスする場合
NSMicrophoneUsageDescription	音声を録音する場合（音声付きビデオ）

必須キーがないと、権限ダイアログが表示されるタイミングで実行時クラッシュが発生します。

カメラ撮影の基本

専用のコントローラーで各キャプチャセッションを管理し、構成、startRunning()、stopRunning() は同じ非メインの実行コンテキスト上で直列化してください。メインアクターでの構成と、切り離された開始／停止タスクを混在させないでください。beginConfiguration()／commitConfiguration() とセッション状態の変更が競合するおそれがあります。Representable ビューはプレビューの表示のみを担当します。

最小限のカメラマネージャー

シリアル化されたコントローラーパターン、写真／動画デリゲート、フォーカス、フラッシュ、向き、スキャンについては、Camera Capture を読み込んでください。重要なライフサイクルは次のとおりです。

1. セッションの構成トランザクションの外でアクセスを要求します。
2. キャプチャエグゼキューターで beginConfiguration() を呼び出し、すべての早期終了でトランザクションが確実に完了するよう、直ちに defer { commitConfiguration() } を設定します。
3. canAddInput／canAddOutput を確認してから、入力と出力を追加します。
4. 同じエグゼキューターで開始または停止し、同期呼び出しが戻った後にのみ、メインアクターで UI の状態を公開します。
5. 失敗した場合は、停止して新しいセッションフィクスチャを復元し、構成を修正してから、認証、バックグラウンド／フォアグラウンド、中断、キャプチャの各チェックを再実行します。

SwiftUI でのカメラプレビュー

AVCaptureVideoPreviewLayer を UIViewRepresentable でラップします。自動リサイズのために layerClass をオーバーライドします。

import SwiftUI
import AVFoundation

struct CameraPreview: UIViewRepresentable {
    let session: AVCaptureSession

    func makeUIView(context: Context) -> PreviewView {
        let view = PreviewView()
        view.previewLayer.session = session
        view.previewLayer.videoGravity = .resizeAspectFill
        return view
    }

    func updateUIView(_ uiView: PreviewView, context: Context) {
        if uiView.previewLayer.session !== session {
            uiView.previewLayer.session = session
        }
    }
}

final class PreviewView: UIView {
    override class var layerClass: AnyClass { AVCaptureVideoPreviewLayer.self }
    var previewLayer: AVCaptureVideoPreviewLayer { layer as! AVCaptureVideoPreviewLayer }
}

ビューでのカメラの使用

struct CameraScreen: View {
    @State private var cameraManager = CameraManager()

    var body: some View {
        ZStack(alignment: .bottom) {
            CameraPreview(session: cameraManager.session)
                .ignoresSafeArea()

            Button {
                // Capture photo -- see references/camera-capture.md
            } label: {
                Circle()
                    .fill(.white)
                    .frame(width: 72, height: 72)
                    .overlay(Circle().stroke(.gray, lineWidth: 3))
            }
            .padding(.bottom)
        }
        .task {
            await cameraManager.configure()
            cameraManager.start()
        }
        .onDisappear {
            cameraManager.stop()
        }
    }
}

onDisappear では必ず stop() を呼び出してください。実行中のキャプチャセッションはカメラを排他的に使用し、バッテリーを消耗します。

画像の読み込みと表示

リモート画像に AsyncImage を使用する

AsyncImage(url: imageURL) { phase in
    switch phase {
    case .empty:
        ProgressView()
    case .success(let image):
        image
            .resizable()
            .scaledToFill()
    case .failure:
        Image(systemName: "photo")
            .foregroundStyle(.secondary)
    @unknown default:
        EmptyView()
    }
}
.frame(width: 200, height: 200)
.clipShape(.rect(cornerRadius: 12))

AsyncImage はビューの再描画をまたいで画像をキャッシュしません。画像を多数扱う本番アプリでは、専用の画像読み込みライブラリか、URLCache ベースのキャッシュを使用してください。

大きな画像のダウンサンプリング

メモリの急増を避けるため、フォトライブラリからフル解像度の写真を、表示サイズの CGImage に読み込みます。48MP の写真は、非圧縮状態で 200 MB を超えることがあります。

import ImageIO
import UIKit

func downsample(data: Data, to pointSize: CGSize, scale: CGFloat = UITraitCollection.current.displayScale) -> UIImage? {
    let maxDimensionInPixels = max(pointSize.width, pointSize.height) * scale

    let options: [CFString: Any] = [
        kCGImageSourceCreateThumbnailFromImageAlways: true,
        kCGImageSourceShouldCacheImmediately: true,
        kCGImageSourceCreateThumbnailWithTransform: true,
        kCGImageSourceThumbnailMaxPixelSize: maxDimensionInPixels
    ]

    guard let source = CGImageSourceCreateWithData(data as CFData, nil),
          let cgImage = CGImageSourceCreateThumbnailAtIndex(source, 0, options as CFDictionary) else {
        return nil
    }

    return UIImage(cgImage: cgImage)
}

リスト、グリッド、サムネイルでユーザーが選択した写真を表示する場合は、必ずこれを使用してください。UIImage を作成する前に、PhotosPickerItem の生の Data をダウンサンプラーに直接渡します。

画像のレンダリングモード

// Original: display the image as-is with its original colors
Image("photo")
    .renderingMode(.original)

// Template: treat the image as a mask, colored by foregroundStyle
Image(systemName: "heart.fill")
    .renderingMode(.template)
    .foregroundStyle(.red)

写真やアートワークには .original を使用します。現在のティントカラーを適用するアイコンには .template を使用します。

よくある間違い

禁止： 写真の選択に UIImagePickerController を使用する。 推奨： PhotosPicker（SwiftUI）または PHPickerViewController（UIKit）を使用する。 理由： UIImagePickerController は機能が限られたレガシー API です。PhotosPicker はプロセス外で実行され、複数選択に対応し、ブラウズにライブラリの権限を必要としません。

禁止： ユーザーに写真を選ばせるだけなのに、フォトライブラリへのフルアクセスを要求する。 推奨： 権限を必要としない PhotosPicker を使用するか、.readWrite を要求して、制限付きアクセスの処理をシステムに任せる。 理由： 選択して使用する多くのワークフローでは、フルアクセスは不要です。システムの制限付きライブラリピッカーはユーザーのプライバシーを尊重しながら、選択した項目へのアクセスを許可します。

禁止： サムネイル用のフル解像度画像をメモリに読み込む。 推奨： CGImageSource と kCGImageSourceThumbnailMaxPixelSize を使ってダウンサンプリングする。48MP の画像は非圧縮状態で 200 MB を超えます。

禁止： PhotosPickerItem のデータ読み込みでメインスレッドをブロックする。 推奨： Task 内で async loadTransferable(type:) を使用する。

禁止： ビューが表示されなくなるときに AVCaptureSession を停止し忘れる。 推奨： onDisappear または dismantleUIView で session.stopRunning() を呼び出す。

禁止： 確認せずにカメラへのアクセスが許可されていると想定する。 推奨： AVCaptureDevice.authorizationStatus(for: .video) を確認し、.denied／.restricted に対処する。

禁止： メインスレッドで session.startRunning() を呼び出す。 推奨： 構成および停止の操作を管理する、同じ専用シリアルエグゼキューターで実行する。 理由： startRunning() は同期的なブロッキング呼び出しであり、ハードウェアの初期化中に数百ミリ秒かかることがあります。

禁止： UIViewRepresentable 内で AVCaptureSession を作成する。 推奨： セッションは別の @Observable モデルで管理する。

レビューチェックリスト

• 非推奨の UIImagePickerController ではなく PhotosPicker を使用する
• カメラ／フォトライブラリのプライバシー説明を Info.plist に記載する
• 非同期の画像／動画読み込み時にローディング状態を処理する
• 表示前に CGImageSource を使って大きな画像をダウンサンプリングする
• カメラセッションをバックグラウンドスレッドで開始し、onDisappear で停止する
• 権限が拒否された場合に、設定画面へのディープリンクを処理する
• AVCaptureSession はモデルが所有し、UIViewRepresentable 内で作成しない
• メディアアセットの型とピッカーの結果が、並行処理の境界を越えて Sendable であることを確認する

参考資料

• references/photokit-patterns.md — ピッカーのパターン、メディアの読み込み、HEIC の処理
• references/camera-capture.md — AVCaptureSession、写真／動画の撮影、QR スキャン
• references/image-loading-caching.md — AsyncImage、キャッシュ、ダウンサンプリング
• references/av-playback.md — AVPlayer、ストリーミング、オーディオ