如需完整的文件索引,請參閱 llms.txt。在文件頁面的網址末尾加上 .md ,即可取得該頁面的 Markdown 版本。
主要導覽
主題
Codex

Codex 應用案例

建立 Mac 應用程式骨架

使用 Codex 建立 Mac 原生 SwiftUI 應用程式骨架,包含側邊欄、詳細資料面板、檢閱器、指令和設定。

難度 Advanced
任務時間跨度 1h

使用 Codex 和 Build macOS Apps 外掛程式,以 NavigationSplitView 將你的構想做成 Mac 原生應用程式。讓側邊欄保留所選項目,加入選單、工具列和鍵盤快速鍵,並將偏好設定移至專屬的 Settings 場景。

最適合的對象

  • 全新的 Mac 應用程式構想,或原本以 iPad 或網頁為主、現在需要完整桌面介面的構想,包括常駐導覽、選單、工具列和鍵盤快速鍵
  • 編輯、館藏管理、系統管理或審查工具,透過詳細資料面板顯示側邊欄所選項目的內容,並在檢閱器中提供次要的中繼資料或操作
  • 需要獨立偏好設定視窗的 Mac 應用程式,讓使用者無須從主要內容再進入一層設定畫面

目錄

    ← 所有應用案例

    建立 Mac 應用程式骨架

    使用 Codex 建立 Mac 原生 SwiftUI 應用程式骨架,包含側邊欄、詳細資料面板、檢閱器、指令和設定。

    使用 Codex 和 Build macOS Apps 外掛程式,以 NavigationSplitView 將你的構想做成 Mac 原生應用程式。讓側邊欄保留所選項目,加入選單、工具列和鍵盤快速鍵,並將偏好設定移至專屬的 Settings 場景。

    Advanced
    1h

    使用 Codex 和 Build macOS Apps 外掛程式,以 NavigationSplitView 將你的構想做成 Mac 原生應用程式。讓側邊欄保留所選項目,加入選單、工具列和鍵盤快速鍵,並將偏好設定移至專屬的 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 採用這種桌面介面結構,並以 shell 為主要工具反覆建置和執行應用程式,請使用 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

    預設選項

    透過專供特定行為使用的 NSViewRepresentable 或 NSWindow 橋接整合 AppKit

    為何需要

    只有在 SwiftUI 難以妥善實作特定平台行為時,才使用 AppKit。場景狀態和選取狀態仍以 SwiftUI 為準。

    需求 預設選項 為何需要
    分割檢視應用程式骨架 NavigationSplitView 、 .sidebar 列表和 inspector(isPresented:) 相較於以觸控為主、逐層進入新畫面的導覽方式,常駐側邊欄搭配詳細資料面板和檢閱器更符合 Mac 應用程式的常見配置。
    桌面操作與設定 commands 、 CommandMenu 、鍵盤快速鍵和 Settings 場景 使用者可以透過選單列或快速鍵執行操作,並在獨立視窗調整設定。這些互動符合 Mac 的使用習慣,避免介面用起來像放大版的 iOS 畫面。
    狀態由誰管理 @State 、 @SceneStorage 、 @AppStorage 和明確的選取狀態繫結 Codex 可以讓側邊欄的選取狀態、檢閱器的顯示狀態和使用者偏好設定都符合預期,無須一律加入檢視模型。
    需要時使用原生 API 透過專供特定行為使用的 NSViewRepresentable 或 NSWindow 橋接整合 AppKit 只有在 SwiftUI 難以妥善實作特定平台行為時,才使用 AppKit。場景狀態和選取狀態仍以 SwiftUI 為準。

    相關應用案例