Image Playground API：SwiftUI Sheet、编程式 Image Creator 与样式控制

更新（2026 年 6 月 11 日）： Apple 正在停用本文所介绍的编程式路径 ImageCreator。它在 iOS 27、iPadOS 27、macOS 27 和 visionOS 27 中将停止工作。本文其余部分介绍的基于 sheet 的 API 仍是受支持的路径。完整的时间线和迁移说明请阅读完整的弃用文章。

Apple Intelligence 的 Image Playground 向应用提供了两条集成路径。SwiftUI 的 imagePlaygroundSheet() 修饰符会呈现系统面向用户的图像生成 UI；开发者交付一个起始概念（文本或图像），用户在 sheet 内部迭代，结果随后返回应用。ImageCreator API 则以编程方式运行同一套生成流水线：开发者提供一个 ImagePlaygroundConcept 对象数组加上一种样式，框架便返回生成的图像，全程不展示任何 UI¹。这两条路径面向不同的使用场景。当用户应当进行迭代时，sheet 集成更合适；当应用已有明确的生成请求并直接呈现结果时，编程式集成更合适。

本文将依据 Apple 的文档逐一梳理这套 API。讨论的核心是”哪条集成路径与用户的心智模型相匹配”，因为选错路径会产生这样的 UX：要么从用户手中夺走过多控制权（用户本想迭代，却用了编程式），要么给得太少（用户本期待一次性结果，却用了 sheet）。

太长不看

• imagePlaygroundSheet(isPresented:concept:sourceImage:onCompletion:onCancellation:) 是用于呈现系统 Image Playground sheet 的 SwiftUI 修饰符。用户进行迭代；应用通过 onCompletion 接收所选图像的 URL（非可选 URL）；取消操作会触发 onCancellation²。
• ImageCreator().images(for: [ImagePlaygroundConcept], style: ImagePlaygroundStyle, limit: Int) 是编程式路径（iOS 18.4+）。该方法返回一个 ImageCreator.CreatedImage 结果的 AsyncSequence³。
• ImagePlaygroundConcept 承载模型所使用的输入：文本描述（.text("a watercolor of a cat")）、源图像（.image(...)）、绘图（.drawing(...)），或从参考素材中提取的概念（.extracted(from:title:)）。
• ImagePlaygroundStyle 用于选择视觉风格。应用通过查询 ImageCreator().availableStyles 来发现设备支持哪些 case。
• .imagePlaygroundPersonalizationPolicy(_:) 接受 .automatic、.enabled 或 .disabled。.imagePlaygroundGenerationStyle(_:in:) 接受一个首选样式和一组允许的样式。在涉及隐私敏感或需锁定美学风格的场景中使用它们。

两条路径：Sheet 与编程式

在两条集成路径之间做选择，关键在于由谁掌控迭代。

Sheet 集成把系统完整的图像生成 UI 交给用户。用户输入提示词、挑选变体并选定最终图像。应用的职责是带着一个起始概念启动 sheet，并接收用户选定的结果。在以下情况使用它：

• 用户拥有应用无法完全预测的创作意图。
• 该交互是某个创作流程的一部分（消息类应用、笔记类应用、个人资料定制流程）。
• 用户预期在确定之前会进行迭代。

编程式集成则把模型直接交给应用。应用提供概念并取回图像，不展示系统 UI。在以下情况使用它：

• 该生成是某个非交互流程的一部分（系统生成的头像、菜谱卡片的确定性素材、一次性插图）。
• 应用有特定的美学要求（始终采用插画风格、始终只生成一张图像）。
• 用户不应看到迭代过程；他们在意的只是结果。

这两条路径共享底层模型，并遵循相同的用户级 Apple Intelligence 配置。选择纯粹是 UX 层面的考量。

SwiftUI Sheet

imagePlaygroundSheet 在 View 上提供了多个重载变体。规范的 5 参数形式接受一个起始概念、一个可选的源图像引用，以及完成与取消处理闭包²：

import ImagePlayground
import SwiftUI

struct ProfileEditor: View {
    @State private var showPlayground = false
    @State private var avatarURL: URL?

    var body: some View {
        VStack {
            if let avatarURL {
                AsyncImage(url: avatarURL) { image in
                    image.resizable().scaledToFit()
                } placeholder: {
                    ProgressView()
                }
            }

            Button("Generate Avatar") {
                showPlayground = true
            }
        }
        .imagePlaygroundSheet(
            isPresented: $showPlayground,
            concept: "a friendly cartoon avatar",
            sourceImage: nil,
            onCompletion: { url in
                avatarURL = url
            },
            onCancellation: {
                // user dismissed without choosing
            }
        )
    }
}

sheet 的 UX 由系统掌控。用户看到的是 Apple 标准的 Image Playground 界面（提示词、样式选择器、变体网格、”完成”按钮）。应用的角色是提供起始提示词并接收结果。取消操作会触发专门的 onCancellation 闭包，而非在完成时传回一个 nil URL；传给 onCompletion 的 URL 是非可选的。

对于希望使用比单个字符串更丰富的起始概念的应用，同级重载可直接接受 [ImagePlaygroundConcept]。多个概念会组合在一起：模型将每个概念用作约束或信号。顺序很重要：文本概念确立提示词；图像概念确立视觉参考；绘图概念确立轮廓。

ImagePlaygroundConcept 的各种变体

Apple 提供了多个 ImagePlaygroundConcept 构造方法⁴：

.text(_:)。 一段简短的文本描述。最常见的起始概念。

.image(_:)。 一张源图像（通常是 URL 或 UIImage/NSImage）。模型将其用作风格或构图的视觉参考。

.drawing(_:)。 一幅绘图，通常来自 PencilKit 或自定义的绘图界面。模型将这些笔触解读为结构性提示。

.extracted(from:title:)。 从被分析图像中提取出的概念。这种双参数形式接受一个源 URL（或图像类型）和一个描述提取内容的 title。框架利用设备端分析，从参考素材中推导出适合生成的概念。

概念可以组合：向 sheet 或 ImageCreator 传入 [text, image, extracted]，可让模型同时满足多个约束。恰当的做法是”足够具体以产出有用的输出，又足够宽松以给模型留出空间”：一两个具体概念，再加上可选的参考图像。

ImageCreator：编程式路径

[更新：Apple 已于 2026 年 6 月 11 日停用 ImageCreator；iOS 27 的时间线及迁移方法请参阅弃用文章。下文作为该 API 的历史文档保留。]

ImageCreator 是面向那些希望在没有 UI 的情况下进行生成的应用的编程式 API³：

import ImagePlayground

do {
    let creator = try ImageCreator()

    // Discover the styles the device supports
    guard let style = creator.availableStyles.first else {
        // Apple Intelligence unavailable on this device
        return
    }

    let stream = creator.images(
        for: [.text("a friendly cartoon avatar")],
        style: style,
        limit: 1
    )

    for try await result in stream {
        // result is an ImageCreator.CreatedImage
        await self.save(result)
    }
} catch {
    // ImageCreator() initializer can throw on unsupported devices
    print("Generation failed: \(error)")
}

images(for:style:limit:) 方法返回一个 ImageCreator.CreatedImage 结果的 AsyncSequence。这种异步流式模型让应用既可以呈现部分结果（模型逐步细化的过程），也可以等待最终图像。limit: 参数限定请求的图像数量上限；Apple 可能基于策略或设备状态返回更少的图像。

编程式路径需要 iOS 18.4+，并要求设备具备 Apple Intelligence 能力且已启用该功能。可用性检查的模式是：在 try 内部构造 ImageCreator，然后读取 availableStyles。一个空的 availableStyles 集合（或初始化方法抛出异常）表明当前设备上无法进行生成；此时应用应回退到非生成式路径（素材库、用户上传的图像等）。

ImagePlaygroundStyle 的各种变体

style 参数用于约束视觉风格⁵：

• .animation。 Apple 的动画角色风格（圆润的造型、粗重的轮廓、简化的特征）。适合头像、吉祥物以及亲和力强的 UI 插图。
• .illustration。 具有矢量感的扁平插画风格。适合信息图、菜谱卡片和概念性图像。
• .sketch。 铅笔素描风格（在后续版本中加入）。适合笔记类应用、日志记录以及手绘美学。

希望在生成图像中保持一致美学的应用（每个头像都用 .animation 风格，每张菜谱卡片都用 .illustration 风格）会在生成调用中锁定样式；希望把选择权交给用户的应用，则呈现一个映射到可用 case 的样式选择器。

个性化与策略修饰符

两个 SwiftUI 修饰符可让应用在自身上下文中约束 Image Playground 的行为⁶：

.imagePlaygroundPersonalizationPolicy(_:)。 接受一个 ImagePlaygroundPersonalizationPolicy 值：.automatic（系统默认）、.enabled（明确允许）或 .disabled（禁止系统引用联系人/照片等个人内容）。在隐私敏感场景中的应用（医疗、金融、匿名通信）应使用 .disabled。

.imagePlaygroundGenerationStyle(_:in:)。 接受一个首选样式和一组允许的样式。用户的样式选择器（如果可见）会被限制在允许的列表内，而首选样式即为默认值。当应用的美学要求约束或锁定可用样式时使用它。

这两个修饰符都以系统级 Apple Intelligence 配置为下限来遵循。应用无法覆盖系统已禁用的功能；它们只能在此基础上进一步约束。

常见错误

来自 Image Playground 集成日志的三种模式：

调用 ImageCreator() 时未捕获初始化方法的错误。 在不具备 Apple Intelligence 的设备上，creator 会在初始化时抛出异常。未使用 try 并捕获异常的应用会向用户暴露一个令人困惑的错误。修复方法：将 ImageCreator() 包裹在 try 中，检查 availableStyles，并在失败时提供回退路径（显示占位图、提示用户在”设置”中启用 Apple Intelligence，或干脆隐藏该功能）。

集成路径与使用场景不匹配。 一个使用 ImageCreator 的个人资料头像生成器，会产出用户无法调整的一次性头像；而一个使用 sheet 的一次性头像生成器，则会增加摩擦。让路径与用户的预期相匹配：若用户想迭代，用 sheet；若用户只想要结果，用编程式。

忽视系统的策略下限。 试图绕过系统 Apple Intelligence 设置的应用（例如在用户已全局禁用的上下文中生成图像）会遇到策略错误。修复方法：遵循系统配置；当 Apple Intelligence 被禁用时，呈现有意义的错误信息，而非默默失败。

这套模式对 Apple Intelligence 应用意味着什么

三点要义。

1. 按用户心智模型选择集成路径。 创作式迭代用 sheet；非交互流程中的一次性生成用编程式。选错的代价是实实在在的 UX 摩擦。

2. 有意识地约束样式与个性化。 一个希望头像风格一致的消息类应用，会向 .imagePlaygroundGenerationStyle(_:in:) 传入单一的允许样式。一个注重隐私的日志类应用会设置 .imagePlaygroundPersonalizationPolicy(.disabled)。默认值是宽松的（.automatic）；有意识的约束会让这项功能显得更有目的性。

3. 始终检查 ImageCreator() 的 availableStyles（或捕获初始化方法的错误）并准备回退方案。 Apple Intelligence 需要特定硬件（iPhone 15 Pro 及更新机型、M 系列 Mac）外加用户主动开启。不做可用性检查就依赖 Image Playground 的应用，在较旧设备上以及在 Apple Intelligence 被禁用的设备上会出现令人困惑的失败。

完整的 Apple Ecosystem 系列：带类型的 App Intents；MCP 服务器；路由问题；Foundation Models；运行时与工具链 LLM 之分；三种界面；单一可信源模式；两个 MCP 服务器；面向 Apple 开发的 hooks；Live Activities；watchOS 运行时；SwiftUI 内部机制；RealityKit 的空间心智模型；SwiftData schema 纪律；Liquid Glass 模式；多平台发布；平台矩阵；Vision 框架；Symbol Effects；Core ML 推理；Writing Tools API；Swift Testing；隐私清单；作为平台的无障碍能力；SF Pro 排版；visionOS 空间模式；Speech 框架；SwiftData 迁移；tvOS 焦点引擎；@Observable 内部机制；SwiftUI Layout 协议；自定义 SF Symbols；AVFoundation HDR；watchOS 锻炼生命周期；iOS 26 中的 App Intents 2.0；我拒绝写的内容。系列主页在 Apple Ecosystem 系列。如需了解更宏观的”iOS 与 AI 智能体”背景，请参阅 iOS 智能体开发指南。

常见问题

我需要处理 Apple Intelligence 不可用的情况吗？

需要。Image Playground 要求设备具备 Apple Intelligence 能力（iPhone 15 Pro 及更新机型、M 系列 Mac）且已启用该功能。在不受支持的设备上，sheet 不会呈现，ImageCreator() 也会在初始化时抛出异常。检查模式是：将 ImageCreator() 包裹在 try 中并检查 availableStyles；空集合或初始化方法抛出异常都表明无法进行生成。请为不受支持的用户提供一个非生成式的回退方案。

我可以自定义 sheet 的 UI 吗？

不可以。sheet 由系统掌控。应用提供起始概念并接收结果；中间的一切都是 Apple 的 UI。如果您需要自定义 UI，请使用 ImageCreator 编程式 API，并围绕它构建自己的迭代界面。

当用户关闭 sheet 时，已生成的图像会怎样？

5 参数的 imagePlaygroundSheet 重载提供了相互独立的 onCompletion 和 onCancellation 闭包。当用户选定一张图像时，onCompletion 会带着一个非可选的 URL 触发；当用户未做选择就关闭时，onCancellation 会触发。临时图像数据由系统清理；希望保留图像的应用必须在完成处理闭包中将其保存到自己的存储中。

Image Playground 如何与照片权限交互？

sheet 本身不需要照片库访问权限。如果用户在 sheet 内部引用了自己的照片库（浏览要用作概念的图像），sheet 会在内部处理权限提示。应用无需为 Image Playground 集成预先请求照片权限。

我可以在后台生成图像吗？

ImageCreator 在前台运行；框架负责管理生成所需的系统资源。希望在后台生成图像的应用，需要让自己的应用保持在前台（或处于允许持续执行的会话类型中，例如 watchOS 锻炼生命周期所介绍的锻炼会话）。

这与 Foundation Models LLM 有何关系？

Image Playground 的模型与 Foundation Models 的设备端 LLM（详见 Foundation Models 设备端 LLM）是相互独立的。两者共享 Apple Intelligence 框架的基础设施，但使用不同的专用模型。将二者结合的应用（用 LLM 生成的提示词馈入图像生成）会按顺序组合这两套 API。

参考资料