photokit

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

PhotoKit

Modern patterns for photo picking, camera capture, image loading, and media permissions targeting iOS 26+ with Swift 6.3. Patterns are backward-compatible to iOS 16 unless noted. See references/photokit-patterns.md for complete picker recipes and references/camera-capture.md for AVCaptureSession patterns.

针对iOS 26+和Swift 6.3的照片选择、相机拍摄、图片加载及媒体权限处理的现代方案。除非特别说明，这些方案向后兼容至iOS 16。完整的选择器方案请查看references/photokit-patterns.md，AVCaptureSession相关方案请查看references/camera-capture.md。

PhotosPicker (SwiftUI, iOS 16+)

PhotosPicker（SwiftUI，iOS 16+）

PhotosPicker

is the native SwiftUI replacement for

UIImagePickerController

. It runs out-of-process, requires no photo library permission for browsing, and supports single or multi-selection with media type filtering.

PhotosPicker

是

UIImagePickerController

的原生SwiftUI替代方案。它在进程外运行，浏览照片时无需相册权限，支持单选或多选，并可按媒体类型过滤。

Single Selection

单选择

swift

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)
                }
            }
        }
    }
}

swift

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)
                }
            }
        }
    }
}

Multi-Selection

多选择

swift

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(RoundedRectangle(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))
                    }
                }
            }
        }
    }
}

swift

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(RoundedRectangle(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))
                    }
                }
            }
        }
    }
}

Media Type Filtering

媒体类型过滤

Filter with

PHPickerFilter

composites to restrict selectable media:

swift

// 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)]))

使用

PHPickerFilter

组合来限制可选择的媒体类型：

swift

// 仅图片
PhotosPicker(selection: $items, matching: .images)

// 仅视频
PhotosPicker(selection: $items, matching: .videos)

// 仅实况照片
PhotosPicker(selection: $items, matching: .livePhotos)

// 仅截图
PhotosPicker(selection: $items, matching: .screenshots)

// 图片和视频
PhotosPicker(selection: $items, matching: .any(of: [.images, .videos]))

// 图片（排除截图）
PhotosPicker(selection: $items, matching: .all(of: [.images, .not(.screenshots)]))

Loading Selected Items with Transferable

使用Transferable加载选中项

PhotosPickerItem

loads content asynchronously via

loadTransferable(type:)

. Define a

Transferable

type for automatic decoding:

swift

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
}

Always load in a

Task

to avoid blocking the main thread. Handle

nil

returns and thrown errors -- the user may select a format that cannot be decoded.

PhotosPickerItem

通过

loadTransferable(type:)

异步加载内容。定义一个

Transferable

类型以实现自动解码：

swift

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
}

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

务必在

Task

中加载内容，避免阻塞主线程。处理

nil

返回值和抛出的错误——用户可能选择了无法解码的格式。

Privacy and Permissions

隐私与权限

Photo Library Access Levels

相册访问级别

iOS provides two access levels for the photo library. The system automatically presents the limited-library picker when an app requests

.readWrite

access -- users choose which photos to share.

Access Level	Description	Info.plist Key
Add-only	Write photos to the library without reading	`NSPhotoLibraryAddUsageDescription`
Read-write	Full or limited read access plus write	`NSPhotoLibraryUsageDescription`

PhotosPicker

requires no permission to browse -- it runs out-of-process and only grants access to selected items. Request explicit permission only when you need to read the full library (e.g., a custom gallery) or save photos.

iOS为相册提供两种访问级别。当应用请求

.readWrite

权限时，系统会自动弹出受限相册选择器，用户可选择要共享的照片。

访问级别	描述	Info.plist键
仅添加	仅向相册写入照片，无需读取权限	`NSPhotoLibraryAddUsageDescription`
读写	完整或受限读取权限，加上写入权限	`NSPhotoLibraryUsageDescription`

PhotosPicker

浏览照片时无需权限——它在进程外运行，仅会授予对选中项的访问权限。仅当需要读取整个相册（如自定义图库）或保存照片时，才需请求显式权限。

Checking and Requesting Photo Library Permission

检查并请求相册权限

swift

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
    }
}

swift

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
    }
}

Camera Permission

相机权限

Add

NSCameraUsageDescription

to Info.plist. Check and request access before configuring a capture session:

swift

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
    }
}

在Info.plist中添加

NSCameraUsageDescription

。在配置拍摄会话前检查并请求权限：

swift

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
    }
}

Handling Denied Permissions

处理权限被拒绝的情况

When the user denies access, guide them to Settings. Never repeatedly prompt or hide functionality silently.

swift

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)
                }
            }
        }
    }
}

当用户拒绝权限时，引导他们前往设置。切勿反复弹出提示或隐藏功能而不告知用户。

swift

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)
                }
            }
        }
    }
}

Required Info.plist Keys

必填的Info.plist键

Key	When Required
`NSPhotoLibraryUsageDescription`	Reading photos from the library
`NSPhotoLibraryAddUsageDescription`	Saving photos/videos to the library
`NSCameraUsageDescription`	Accessing the camera
`NSMicrophoneUsageDescription`	Recording audio (video with sound)

Omitting a required key causes a runtime crash when the permission dialog would appear.

键	必填场景
`NSPhotoLibraryUsageDescription`	从相册读取照片时
`NSPhotoLibraryAddUsageDescription`	向相册保存照片/视频时
`NSCameraUsageDescription`	访问相机时
`NSMicrophoneUsageDescription`	录制音频（带声音的视频）时

如果遗漏必填键，当系统要弹出权限对话框时会导致运行时崩溃。

Camera Capture Basics

相机拍摄基础

Manage camera sessions in a dedicated

@Observable

model. The representable view only displays the preview. See references/camera-capture.md for complete patterns.

在专门的

@Observable

模型中管理相机会话，可表示视图仅用于显示预览。完整方案请查看references/camera-capture.md。

Minimal Camera Manager

极简相机管理器

swift

import AVFoundation

@available(iOS 17.0, *)
@Observable
@MainActor
final class CameraManager {
    let session = AVCaptureSession()
    private let photoOutput = AVCapturePhotoOutput()
    private var currentDevice: AVCaptureDevice?

    var isRunning = false
    var capturedImage: Data?

    func configure() async {
        guard await requestCameraAccess() else { return }

        session.beginConfiguration()
        session.sessionPreset = .photo

        // Add camera input
        guard let device = AVCaptureDevice.default(.builtInWideAngleCamera,
                                                    for: .video,
                                                    position: .back) else { return }
        currentDevice = device

        guard let input = try? AVCaptureDeviceInput(device: device),
              session.canAddInput(input) else { return }
        session.addInput(input)

        // Add photo output
        guard session.canAddOutput(photoOutput) else { return }
        session.addOutput(photoOutput)

        session.commitConfiguration()
    }

    func start() {
        guard !session.isRunning else { return }
        Task.detached { [session] in
            session.startRunning()
        }
        isRunning = true
    }

    func stop() {
        guard session.isRunning else { return }
        Task.detached { [session] in
            session.stopRunning()
        }
        isRunning = false
    }

    private func requestCameraAccess() async -> Bool {
        let status = AVCaptureDevice.authorizationStatus(for: .video)
        if status == .notDetermined {
            return await AVCaptureDevice.requestAccess(for: .video)
        }
        return status == .authorized
    }
}

Start and stop

AVCaptureSession

on a background queue. The

startRunning()

and

stopRunning()

methods are synchronous and block the calling thread.

swift

import AVFoundation

@available(iOS 17.0, *)
@Observable
@MainActor
final class CameraManager {
    let session = AVCaptureSession()
    private let photoOutput = AVCapturePhotoOutput()
    private var currentDevice: AVCaptureDevice?

    var isRunning = false
    var capturedImage: Data?

    func configure() async {
        guard await requestCameraAccess() else { return }

        session.beginConfiguration()
        session.sessionPreset = .photo

        // 添加相机输入
        guard let device = AVCaptureDevice.default(.builtInWideAngleCamera,
                                                    for: .video,
                                                    position: .back) else { return }
        currentDevice = device

        guard let input = try? AVCaptureDeviceInput(device: device),
              session.canAddInput(input) else { return }
        session.addInput(input)

        // 添加照片输出
        guard session.canAddOutput(photoOutput) else { return }
        session.addOutput(photoOutput)

        session.commitConfiguration()
    }

    func start() {
        guard !session.isRunning else { return }
        Task.detached { [session] in
            session.startRunning()
        }
        isRunning = true
    }

    func stop() {
        guard session.isRunning else { return }
        Task.detached { [session] in
            session.stopRunning()
        }
        isRunning = false
    }

    private func requestCameraAccess() async -> Bool {
        let status = AVCaptureDevice.authorizationStatus(for: .video)
        if status == .notDetermined {
            return await AVCaptureDevice.requestAccess(for: .video)
        }
        return status == .authorized
    }
}

在后台队列中启动和停止

AVCaptureSession

。

startRunning()

和

stopRunning()

方法是同步的，会阻塞调用线程。

Camera Preview in SwiftUI

SwiftUI中的相机预览

Wrap

AVCaptureVideoPreviewLayer

in a

UIViewRepresentable

. Override

layerClass

for automatic resizing:

swift

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 }
}

将

AVCaptureVideoPreviewLayer

包装在

UIViewRepresentable

中。重写

layerClass

以实现自动调整大小：

swift

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 }
}

Using the Camera in a View

在视图中使用相机

swift

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, 32)
        }
        .task {
            await cameraManager.configure()
            cameraManager.start()
        }
        .onDisappear {
            cameraManager.stop()
        }
    }
}

Always call

stop()

onDisappear

. A running capture session holds the camera exclusively and drains battery.

swift

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

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

            Button {
                // 拍摄照片——请查看references/camera-capture.md
            } label: {
                Circle()
                    .fill(.white)
                    .frame(width: 72, height: 72)
                    .overlay(Circle().stroke(.gray, lineWidth: 3))
            }
            .padding(.bottom, 32)
        }
        .task {
            await cameraManager.configure()
            cameraManager.start()
        }
        .onDisappear {
            cameraManager.stop()
        }
    }
}

务必在

onDisappear

中调用

stop()

。运行中的拍摄会话会独占相机，并且消耗电量。

Image Loading and Display

图片加载与显示

AsyncImage for Remote Images

远程图片使用AsyncImage

swift

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(RoundedRectangle(cornerRadius: 12))

AsyncImage

does not cache images across view redraws. For production apps with many images, use a dedicated image loading library or

URLCache

-based caching.

swift

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(RoundedRectangle(cornerRadius: 12))

AsyncImage

不会在视图重绘时缓存图片。对于包含大量图片的生产应用，请使用专门的图片加载库或基于

URLCache

的缓存方案。

Downsampling Large Images

大图片降采样

Load full-resolution photos from the library into a display-sized

CGImage

to avoid memory spikes. A 48MP photo can consume over 200 MB uncompressed.

swift

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)
}

Use this whenever displaying user-selected photos in lists, grids, or thumbnails. Pass the raw

Data

from

PhotosPickerItem

directly to the downsampler before creating a

UIImage

将相册中的全分辨率照片加载为适合显示的

CGImage

，避免内存峰值。一张4800万像素的照片未压缩时会占用超过200MB内存。

swift

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)
}

在列表、网格或缩略图中显示用户选择的照片时，请使用此方法。直接将

PhotosPickerItem

的原始

Data

传入降采样器，再创建

UIImage

。

Image Rendering Modes

图片渲染模式

swift

// 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)

Use

.original

for photos and artwork. Use

.template

for icons that should adopt the current tint color.

swift

// 原始模式：按图片原样显示，保留原始颜色
Image("photo")
    .renderingMode(.original)

// 模板模式：将图片视为遮罩，使用前景色填充
Image(systemName: "heart.fill")
    .renderingMode(.template)
    .foregroundStyle(.red)

照片和艺术作品使用

.original

模式。需要适配当前色调颜色的图标使用

.template

模式。

Common Mistakes

常见误区

DON'T: Use

UIImagePickerController

for photo picking. DO: Use

PhotosPicker

(SwiftUI) or

PHPickerViewController

(UIKit). Why:

UIImagePickerController

is legacy API with limited functionality.

PhotosPicker

runs out-of-process, supports multi-selection, and requires no library permission for browsing.

DON'T: Request full photo library access when you only need the user to pick photos. DO: Use

PhotosPicker

which requires no permission, or request

.readWrite

and let the system handle limited access. Why: Full access is unnecessary for most pick-and-use workflows. The system's limited-library picker respects user privacy and still grants access to selected items.

DON'T: Load full-resolution images into memory for thumbnails. DO: Use

CGImageSource

with

kCGImageSourceThumbnailMaxPixelSize

to downsample. A 48MP image is over 200 MB uncompressed.

DON'T: Block the main thread loading

PhotosPickerItem

data. DO: Use

async loadTransferable(type:)

in a

Task

DON'T: Forget to stop

AVCaptureSession

when the view disappears. DO: Call

session.stopRunning()

onDisappear

dismantleUIView

DON'T: Assume camera access is granted without checking. DO: Check

AVCaptureDevice.authorizationStatus(for: .video)

and handle

.denied

.restricted

DON'T: Call

session.startRunning()

on the main thread. DO: Dispatch to a background thread with

Task.detached

or a dedicated serial queue. Why:

startRunning()

is a synchronous blocking call that can take hundreds of milliseconds while the hardware initializes.

DON'T: Create

AVCaptureSession

inside a

UIViewRepresentable

. DO: Own the session in a separate

@Observable

model.

不要： 使用

UIImagePickerController

进行照片选择。要：使用

PhotosPicker

（SwiftUI）或

PHPickerViewController

（UIKit）。 原因：

UIImagePickerController

是遗留API，功能有限。

PhotosPicker

在进程外运行，支持多选，浏览时无需相册权限。

不要： 仅需用户选择照片时请求完整相册访问权限。要：使用无需权限的

PhotosPicker

，或请求

.readWrite

权限并让系统处理受限访问。 原因： 大多数选择即用的工作流无需完整访问权限。系统的受限相册选择器尊重用户隐私，同时仍会授予对选中项的访问权限。

不要： 将全分辨率图片加载到内存中用作缩略图。要：使用

CGImageSource

并设置

kCGImageSourceThumbnailMaxPixelSize

进行降采样。一张4800万像素的图片未压缩时超过200MB。

不要： 加载

PhotosPickerItem

数据时阻塞主线程。要：在

Task

中使用

async loadTransferable(type:)

。

不要： 视图消失时忘记停止

AVCaptureSession

。要：在

onDisappear

或

dismantleUIView

中调用

session.stopRunning()

。

不要： 未检查权限就假设相机访问已被授予。要：检查

AVCaptureDevice.authorizationStatus(for: .video)

并处理

.denied

.restricted

状态。

不要： 在主线程调用

session.startRunning()

。要：使用

Task.detached

或专用串行队列调度到后台线程。 原因：

startRunning()

是同步阻塞调用，硬件初始化时可能需要数百毫秒。

不要： 在

UIViewRepresentable

内部创建

AVCaptureSession

。要：在单独的

@Observable

模型中管理会话。

Review Checklist

评审检查清单

```
PhotosPicker
```
used instead of deprecated
```
UIImagePickerController
```
Privacy descriptions in Info.plist for camera/photo library
Loading states handled for async image/video loading
Large images downsampled with
```
CGImageSource
```
before display
Camera session started on background thread; stopped in
```
onDisappear
```
Permission denial handled with Settings deep link
```
AVCaptureSession
```
owned by model, not created inside
```
UIViewRepresentable
```
Media asset types and picker results are
```
Sendable
```
across concurrency boundaries

使用
```
PhotosPicker
```
替代已废弃的
```
UIImagePickerController
```
Info.plist中包含相机/相册的隐私描述
异步加载图片/视频时处理加载状态
大图片在显示前使用
```
CGImageSource
```
进行降采样
相机会话在后台线程启动，在
```
onDisappear
```
中停止
权限被拒绝时提供设置跳转链接
```
AVCaptureSession
```
由模型管理，而非在
```
UIViewRepresentable
```
内部创建
媒体资源类型和选择器结果在并发边界上是
```
Sendable
```
类型

References

参考资料

references/photokit-patterns.md — Picker patterns, media loading, HEIC handling
references/camera-capture.md — AVCaptureSession, photo/video capture, QR scanning
references/image-loading-caching.md — AsyncImage, caching, downsampling
references/av-playback.md — AVPlayer, streaming, audio

references/photokit-patterns.md — 选择器方案、媒体加载、HEIC格式处理
references/camera-capture.md — AVCaptureSession、照片/视频拍摄、二维码扫描
references/image-loading-caching.md — AsyncImage、缓存、降采样
references/av-playback.md — AVPlayer、流媒体、音频

photokit

Original

Translation

PhotoKit

PhotoKit

Contents

目录

PhotosPicker (SwiftUI, iOS 16+)

PhotosPicker（SwiftUI，iOS 16+）

Single Selection

单选择

Multi-Selection

多选择

Media Type Filtering

媒体类型过滤

Loading Selected Items with Transferable

使用Transferable加载选中项

Privacy and Permissions

隐私与权限

Photo Library Access Levels

相册访问级别

Checking and Requesting Photo Library Permission

检查并请求相册权限

Camera Permission

相机权限

Handling Denied Permissions

处理权限被拒绝的情况

Required Info.plist Keys

必填的Info.plist键

Camera Capture Basics

相机拍摄基础

Minimal Camera Manager

极简相机管理器

Camera Preview in SwiftUI

SwiftUI中的相机预览

Using the Camera in a View

在视图中使用相机

Image Loading and Display

图片加载与显示

AsyncImage for Remote Images

远程图片使用AsyncImage

Downsampling Large Images

大图片降采样

Image Rendering Modes

图片渲染模式

Common Mistakes

常见误区

Review Checklist

评审检查清单

References

参考资料