如需查看完整的文档索引,请参阅 llms.txt。在文档页面的 URL 末尾加上 .md 即可查看该页面的 Markdown 版本。
主导航
主题
Codex

Codex 使用场景

搭建 Mac 应用界面框架

使用 Codex 搭建带有侧边栏、详情面板、检查器、命令和设置的 Mac 原生 SwiftUI 应用界面框架。

难度 Advanced
时间跨度 1h

使用 Codex 和 Build macOS Apps 插件,将您的应用构想实现为基于 NavigationSplitView 的原生桌面应用。保持侧边栏选中项稳定,添加菜单、工具栏和键盘快捷键,并将偏好设置移到专用的 Settings 场景中。

最适合

  • 需要常驻导航、菜单、工具栏和键盘快捷键等桌面功能的新 Mac 应用构想,或最初面向 iPad 或网页、现在需要这些桌面功能的应用设计
  • 编辑器、资源库工具、管理工具或审阅工具,详情面板随侧边栏选中项更新,检查器则显示辅助元数据或提供相关操作
  • 需要在独立窗口中管理偏好设置的 Mac 应用,这样就无需在主内容区的导航栈中再加入一层设置页面

目录

    ← 所有使用场景

    搭建 Mac 应用界面框架

    使用 Codex 搭建带有侧边栏、详情面板、检查器、命令和设置的 Mac 原生 SwiftUI 应用界面框架。

    使用 Codex 和 Build macOS Apps 插件,将您的应用构想实现为基于 NavigationSplitView 的原生桌面应用。保持侧边栏选中项稳定,添加菜单、工具栏和键盘快捷键,并将偏好设置移到专用的 Settings 场景中。

    Advanced
    1h

    使用 Codex 和 Build macOS Apps 插件,将您的应用构想实现为基于 NavigationSplitView 的原生桌面应用。保持侧边栏选中项稳定,添加菜单、工具栏和键盘快捷键,并将偏好设置移到专用的 Settings 场景中。

    Advanced
    1h

    最适合

    • 需要常驻导航、菜单、工具栏和键盘快捷键等桌面功能的新 Mac 应用构想,或最初面向 iPad 或网页、现在需要这些桌面功能的应用设计
    • 编辑器、资源库工具、管理工具或审阅工具,详情面板随侧边栏选中项更新,检查器则显示辅助元数据或提供相关操作
    • 需要在独立窗口中管理偏好设置的 Mac 应用,这样就无需在主内容区的导航栈中再加入一层设置页面

    技能与插件

    • 运用 macOS SwiftUI 设计模式、窗口管理、AppKit 互操作以及构建和运行等技能,搭建由侧边栏、详情面板和检查器组成的布局,并为菜单和设置接入相应功能。从界面框架开始,在每轮迭代中构建、运行并验证应用。
    技能 使用理由
    Build macOS Apps 运用 macOS SwiftUI 设计模式、窗口管理、AppKit 互操作以及构建和运行等技能,搭建由侧边栏、详情面板和检查器组成的布局,并为菜单和设置接入相应功能。从界面框架开始,在每轮迭代中构建、运行并验证应用。

    起始提示词

    使用 Build macOS Apps 插件,将 [describe your app idea] 实现为 Mac 原生 SwiftUI 应用界面框架,包含侧边栏、详情面板、检查器、命令和设置。 约束条件: - 先选择场景模型。主窗口优先使用 `WindowGroup`,并为偏好设置添加专用的 `Settings` 场景。 - 围绕 `NavigationSplitView` 构建主界面,显式管理选中状态,使用原生 `.sidebar` 列表和详情视图,并在 `inspector(isPresented:)` 面板中显示辅助元数据或提供控件。 - 侧边栏列表项应简洁,沿用原生样式。每项包含一个图标和一行标题,最多再加一行简短说明。除非产品确有需要,否则不要把每一项都做成大型自定义卡片。 - 通过场景级 `commands`、`CommandMenu`、工具栏按钮和键盘快捷键提供重要操作。不要让手势成为执行关键操作的唯一途径。 - 使用 `@SceneStorage` 保存各窗口的界面状态,使用 `@AppStorage` 保存偏好设置。由父视图管理选中项,并通过显式绑定让详情视图与侧边栏选中项保持同步。 - 优先使用系统材质、语义颜色和标准侧边栏背景。仅在需要时为详情面板或检查器中的内容卡片添加自定义样式。 - 仅当 SwiftUI 无法简洁地实现某项具体的桌面行为时,才针对该行为桥接 AppKit。 - 创建或更新 `script/build_and_run.sh`,执行足以验证构建和运行的最小检查,并告诉我实际使用的完整命令。 请提供: - 场景结构,以及侧边栏、详情面板和检查器的主要视图 - 将菜单、工具栏和键盘快捷键绑定到相应操作的代码 - 设置场景和偏好设置的状态模型 - 新增的 AppKit 桥接代码(如有),并说明为何需要桥接 - 构建和运行的验证步骤,以及对桌面用户体验的后续改进建议
    使用 Build macOS Apps 插件,将 [describe your app idea] 实现为 Mac 原生 SwiftUI 应用界面框架,包含侧边栏、详情面板、检查器、命令和设置。 约束条件: - 先选择场景模型。主窗口优先使用 `WindowGroup`,并为偏好设置添加专用的 `Settings` 场景。 - 围绕 `NavigationSplitView` 构建主界面,显式管理选中状态,使用原生 `.sidebar` 列表和详情视图,并在 `inspector(isPresented:)` 面板中显示辅助元数据或提供控件。 - 侧边栏列表项应简洁,沿用原生样式。每项包含一个图标和一行标题,最多再加一行简短说明。除非产品确有需要,否则不要把每一项都做成大型自定义卡片。 - 通过场景级 `commands`、`CommandMenu`、工具栏按钮和键盘快捷键提供重要操作。不要让手势成为执行关键操作的唯一途径。 - 使用 `@SceneStorage` 保存各窗口的界面状态,使用 `@AppStorage` 保存偏好设置。由父视图管理选中项,并通过显式绑定让详情视图与侧边栏选中项保持同步。 - 优先使用系统材质、语义颜色和标准侧边栏背景。仅在需要时为详情面板或检查器中的内容卡片添加自定义样式。 - 仅当 SwiftUI 无法简洁地实现某项具体的桌面行为时,才针对该行为桥接 AppKit。 - 创建或更新 `script/build_and_run.sh`,执行足以验证构建和运行的最小检查,并告诉我实际使用的完整命令。 请提供: - 场景结构,以及侧边栏、详情面板和检查器的主要视图 - 将菜单、工具栏和键盘快捷键绑定到相应操作的代码 - 设置场景和偏好设置的状态模型 - 新增的 AppKit 桥接代码(如有),并说明为何需要桥接 - 构建和运行的验证步骤,以及对桌面用户体验的后续改进建议

    从 Mac 场景模型入手

    如果您想把应用构想做成 Mac 应用,可以按本用例搭建界面框架,让它符合桌面使用习惯,避免把以触控为主的导航布局简单拉宽。请先让 Codex 选择场景模型,再设计主窗口:侧边栏保留当前选中的项目,详情面板展示该项目的内容,检查器提供辅助控件或显示元数据。

    采用 Mac 原生布局的应用界面,侧边栏中有一个选中的项目,详情面板显示该项目的内容

    如果您希望 Codex 采用这种桌面布局,并主要通过命令行反复构建和运行应用,可以使用 Build macOS Apps 插件。插件中的 macOS SwiftUI 模式技能适合设计场景、侧边栏、检查器、命令和设置。如果 SwiftUI 恰好无法实现某项 Mac 特有的行为,也可以用这项技能编写少量 AppKit 桥接代码。

    构建侧边栏、详情面板和检查器

    如果某项功能适合使用常驻导航并保留当前选中的项目,请优先使用 NavigationSplitView。侧边栏中的列表行应采用简洁的原生样式,侧边栏背景使用系统样式。将自定义卡片或较为密集的元数据放在详情面板或检查器中。

    import SwiftUI
    
    struct Item: Identifiable, Hashable {
      let id: String
      let title: String
      let systemImage: String
    }
    let items = [Item(id: "notes", title: "Notes", systemImage: "note.text"), Item(id: "photos", title: "Photos", systemImage: "photo")]
    
    struct ItemDetailView: View {
      let selection: String?
      var body: some View { Text(selection ?? "Select an item").frame(maxWidth: .infinity, maxHeight: .infinity) }
    }
    struct ItemInspectorView: View {
      let selection: String?
      var body: some View { Text("Metadata: \(selection ?? "No selection")").padding().frame(minWidth: 220) }
    }
    @MainActor final class LibraryStore: ObservableObject {
      @Published var entries = items
      @Published var selection: String?
      @Published var showInspector = true
      func addItem() {
        let item = Item(id: UUID().uuidString, title: "New Item", systemImage: "doc")
        entries.append(item)
        selection = item.id
      }
    }
    
    struct LibraryRootView: View {
      @StateObject private var store = LibraryStore()
      @SceneStorage("LibraryRootView.selection") private var savedSelection: Item.ID?
      @SceneStorage("LibraryRootView.showInspector") private var savedShowInspector = true
    
      var body: some View {
        NavigationSplitView {
          List(selection: $store.selection) {
            ForEach(store.entries) { item in
              Label(item.title, systemImage: item.systemImage)
                .tag(item.id)
            }
          }
          .listStyle(.sidebar)
          .navigationTitle("Library")
        } detail: {
          ItemDetailView(selection: store.selection)
            .inspector(isPresented: $store.showInspector) {
              ItemInspectorView(selection: store.selection)
            }
        }
        .focusedSceneObject(store)
        .onAppear {
          store.selection = savedSelection
          store.showInspector = savedShowInspector
        }
        .onChange(of: store.selection) { _, selection in
          savedSelection = selection
        }
        .onChange(of: store.showInspector) { _, showInspector in
          savedShowInspector = showInspector
        }
      }
    }

    如果应用对分栏尺寸有特殊要求,需要在底层协调窗口,或需要自定义响应者链的行为,请让 Codex 保留完整的 SwiftUI 界面框架,只为这项需求添加必要的 AppKit 桥接代码。

    在桌面界面中提供命令、工具栏和快捷键

    Mac 用户应该能在菜单栏和工具栏中找到重要操作,也能看到可用的键盘快捷键。请让 Codex 将场景级 commands、随当前上下文变化的菜单项和工具栏按钮绑定到同一组应用操作,这样桌面用户就不必四处寻找只能通过手势触发的控件。

    @main
    struct LibraryApp: App {
      @FocusedObject private var store: LibraryStore?
      var body: some Scene {
        WindowGroup {
          LibraryRootView()
        }
        .commands {
          CommandMenu("Library") {
            Button("New Item") {
              store?.addItem()
            }
            .keyboardShortcut("n")
            .disabled(store == nil)
    
            Button("Toggle Inspector") {
              store?.showInspector.toggle()
            }
            .keyboardShortcut("i", modifiers: [.command, .option])
            .disabled(store == nil)
          }
        }
    
        Settings {
          LibrarySettingsView()
        }
      }
    }

    如果命令应作用于详情面板当前显示的项目,请使用 FocusedValue、场景状态或显式维护的选中状态。如果同一快捷键会在多处注册,请让 Codex 将它交由一处统一管理,让应用通过一条明确的路径分发命令。

    在 Settings 中管理偏好设置

    为应用的偏好设置创建专用的 Settings 场景,并使用 @AppStorage 保存需要长期保留的用户选项。相比在主内容窗口内逐级导航到设置页面,这种做法通常更符合 Mac 的使用习惯。

    struct LibrarySettingsView: View {
      @AppStorage("showItemMetadata") private var showItemMetadata = true
    
      var body: some View {
        TabView {
          Form {
            Toggle("Show Item Metadata", isOn: $showItemMetadata)
          }
          .tabItem { Label("General", systemImage: "gearshape") }
        }
        .frame(width: 460, height: 260)
        .scenePadding()
      }
    }

    在提示词中描述应用构想,再验证界面框架

    使用本用例时,最好在提示词中说明您的应用构想、应用要处理的主要内容对象,以及用户会执行的主要操作。然后让 Codex 先围绕这套工作流程搭建桌面界面框架。请让智能体构建并运行一次应用,做个简单检查,再概述场景如何组织、命令如何绑定、各项状态由谁管理,以及哪些功能需要通过 AppKit 桥接来实现。

    实用技巧

    保留侧边栏的原生样式

    侧边栏的每一行使用一个图标和一行标题,最多再加一行简短的辅助说明。将内容更丰富的卡片、计数器和元数据移到详情面板或检查器中,让用户能快速浏览侧边栏列表。

    避免将设置藏在主导航栈中

    如果某项用户偏好会影响整个应用,请让 Codex 将对应的控件放在 Settings 中,用 @AppStorage 保存该选项,并在应用菜单中提供设置入口,避免再向主导航栈推入一个设置页面。

    仅在个别桌面功能需要时使用 AppKit

    如果某项功能需要打开或保存文件的面板、需要控制第一响应者,或需要自定义 NSView,请继续由 SwiftUI 管理状态模型,只在实现这些功能时接入少量 AppKit 代码,无需用 AppKit 重写整个窗口。

    技术栈

    需求

    分栏式应用界面框架

    默认选项

    NavigationSplitView、.sidebar 列表和 inspector(isPresented:)

    为什么需要

    与面向触控的逐层导航相比,常驻侧边栏配合详情面板和检查器,更符合 Mac 应用的常见布局。

    需求

    桌面操作和设置

    默认选项

    commands、CommandMenu、键盘快捷键和 Settings 场景

    为什么需要

    菜单栏操作、快捷键和独立设置窗口让用户能按熟悉的 Mac 方式使用这项功能,避免了简单拉宽 iOS 界面带来的生硬感。

    需求

    状态归属

    默认选项

    @State、@SceneStorage、@AppStorage 和显式选中项绑定

    为什么需要

    Codex 可以让侧边栏选中项、检查器的显示状态和用户偏好设置都按预期更新,无需为此一律添加视图模型。

    需求

    用原生 API 补充 SwiftUI 的能力

    默认选项

    通过仅负责特定功能的 NSViewRepresentable 或 NSWindow 桥接层接入 AppKit

    为什么需要

    仅在 SwiftUI 无法简洁地实现某项平台行为时使用 AppKit。场景状态和选中状态仍由 SwiftUI 统一管理。

    需求 默认选项 为什么需要
    分栏式应用界面框架 NavigationSplitView 、 .sidebar 列表和 inspector(isPresented:) 与面向触控的逐层导航相比,常驻侧边栏配合详情面板和检查器,更符合 Mac 应用的常见布局。
    桌面操作和设置 commands 、 CommandMenu 、键盘快捷键和 Settings 场景 菜单栏操作、快捷键和独立设置窗口让用户能按熟悉的 Mac 方式使用这项功能,避免了简单拉宽 iOS 界面带来的生硬感。
    状态归属 @State 、 @SceneStorage 、 @AppStorage 和显式选中项绑定 Codex 可以让侧边栏选中项、检查器的显示状态和用户偏好设置都按预期更新,无需为此一律添加视图模型。
    用原生 API 补充 SwiftUI 的能力 通过仅负责特定功能的 NSViewRepresentable 或 NSWindow 桥接层接入 AppKit 仅在 SwiftUI 无法简洁地实现某项平台行为时使用 AppKit。场景状态和选中状态仍由 SwiftUI 统一管理。

    相关使用场景