SwiftUI DocumentGroup应用：如何跳过iOS文件选择器并添加引导页

我之前也遇到过一模一样的问题：用Xcode的Document App模板做SwiftUI应用，macOS启动直接开新文档能放引导UI，但iOS一启动就跳系统文档选择器，完全没机会展示自定义引导。后来摸索出一个简单优雅的方案，用SwiftUI的场景切换结合持久化状态就能搞定，不需要折腾复杂的UIKit代理。

核心思路 #

用@AppStorage持久化记录用户是否看过引导页，启动时根据这个状态决定先显示引导页（WindowGroup）还是直接进入DocumentGroup。当用户完成引导后，切换回DocumentGroup，系统会自动处理iOS上的文档选择器展示，完全符合原生行为。

完整修改代码 #

1. 更新App结构体，添加状态判断和引导页场景 #

import SwiftUI
import UniformTypeIdentifiers
import UIKit // 用于平台判断（可选）

@main
struct DocumentTestApp: App {
    // 持久化存储用户是否已完成引导，默认未完成
    @AppStorage("hasSeenOnboarding") private var hasSeenOnboarding = false
    
    var body: some Scene {
        // 可选：仅在iOS/iPadOS显示引导页，macOS保持原行为
        if !hasSeenOnboarding && (UIDevice.current.userInterfaceIdiom == .phone || UIDevice.current.userInterfaceIdiom == .pad) {
            WindowGroup {
                OnboardingView()
            }
        } else {
            // 原有的DocumentGroup逻辑
            DocumentGroup(newDocument: DocumentTestDocument()) { file in
                ContentView(document: file.$document)
            }
        }
    }
}

2. 创建引导页视图 #

struct OnboardingView: View {
    @AppStorage("hasSeenOnboarding") private var hasSeenOnboarding = false
    
    var body: some View {
        ZStack {
            // 自定义引导页背景和内容，这里随便写了个示例
            Color.indigo.ignoresSafeArea()
            VStack(spacing: 32) {
                Text("欢迎使用文档助手")
                    .font(.largeTitle)
                    .fontWeight(.heavy)
                    .foregroundColor(.white)
                
                Text("在这里你可以创建、编辑和管理你的纯文本文档，支持iCloud同步哦～")
                    .foregroundColor(.white.opacity(0.9))
                    .multilineTextAlignment(.center)
                    .padding(.horizontal, 24)
                
                Button("开始使用") {
                    // 标记引导已完成，App会自动切换到DocumentGroup场景
                    hasSeenOnboarding = true
                }
                .buttonStyle(.borderedProminent)
                .tint(.white)
                .foregroundColor(.indigo)
                .font(.headline)
            
                // 可选：添加跳过引导按钮
                Button("跳过") {
                    hasSeenOnboarding = true
                }
                .foregroundColor(.white)
                .font(.subheadline)
            }
        }
    }
}

3. 保留原有的ContentView和Document逻辑 #

你原代码里的ContentView、DocumentTestDocument和UTType扩展不需要修改，直接保留即可：

struct ContentView: View {
    @Binding var document: DocumentTestDocument
    var body: some View {
        TextEditor(text: $document.text)
    }
}

struct ContentView_Previews: PreviewProvider {
    static var previews: some View {
        ContentView(document: .constant(DocumentTestDocument()))
    }
}

extension UTType {
    static var exampleText: UTType {
        UTType(importedAs: "com.example.plain-text")
    }
}

struct DocumentTestDocument: FileDocument {
    var text: String
    
    init(text: String = "Hello, world!") {
        self.text = text
    }
    
    static var readableContentTypes: [UTType] {
        [.exampleText]
    }
    
    init(configuration: ReadConfiguration) throws {
        guard let data = configuration.file.regularFileContents,
              let string = String(data: data, encoding: .utf8)
        else {
            throw CocoaError(.fileReadCorruptFile)
        }
        text = string
    }
    
    func fileWrapper(configuration: WriteConfiguration) throws -> FileWrapper {
        let data = text.data(using: .utf8)!
        return .init(regularFileWithContents: data)
    }
}

为什么这个方案可行？ #

• 持久化状态：@AppStorage会把状态存在系统的UserDefaults里，重启App也不会丢失，用户只会看一次引导页。
• 原生场景切换：当hasSeenOnboarding变为true时，SwiftUI会自动重新计算App的body，从WindowGroup切换到DocumentGroup，iOS系统会自动展示文档选择器，macOS则会直接创建新文档进入编辑界面，完美匹配两个平台的原生行为。
• 无额外UIKit代码：不需要自定义SceneDelegate或者处理文档浏览器的代理，完全用SwiftUI的原生能力实现，代码简洁易维护。

内容的提问来源于stack exchange，提问作者MScottWaller