第1章：項目概述與環境搭建

學習目標

了解YunChangAction靈感記錄應用的整體架構和功能
掌握SwiftUI開發環境的配置方法
創建項目基礎結構并理解文件組織方式
實現應用的啟動屏幕和基本主題設置

理論知識講解

靈感記錄應用概述

靈感記錄應用是一種專門設計用來幫助用戶隨時捕捉、整理和管理各種想法的工具。在日常生活和工作中，靈感往往稍縱即逝，一個好的靈感記錄應用能夠幫助用戶快速記錄這些珍貴的想法，并通過分類、標簽等方式進行有效管理。

YunChangAction是一款功能豐富的靈感記錄應用，它不僅提供基本的筆記功能，還集成了AI輔助分類、多種視圖模式、數據導出等高級特性，幫助用戶更高效地管理創意和想法。

靈感記錄應用概念圖

SwiftUI框架介紹

SwiftUI是Apple在2019年WWDC上推出的聲明式UI框架，它徹底改變了iOS應用開發的方式。與傳統的UIKit相比，SwiftUI具有以下優勢：

聲明式語法：使用簡潔的聲明式語法描述UI的外觀和行為
實時預覽：通過Canvas實時預覽UI變化，加速開發過程
自動適配：自動支持動態類型、深色模式和各種設備尺寸
組合式設計：通過組合小型、獨立的視圖構建復雜界面
數據驅動：內置狀態管理機制，UI會自動響應數據變化

MVVM架構模式

YunChangAction采用MVVM（Model-View-ViewModel）架構模式，這是SwiftUI應用中常用的架構模式：

Model（模型）：表示應用的數據和業務邏輯，如InspirationNote類
View（視圖）：負責UI的展示，如ContentView、SplashScreen等
ViewModel（視圖模型）：連接Model和View，處理UI邏輯和狀態管理，如InspirationManager

MVVM架構的優勢在于實現了關注點分離，提高了代碼的可測試性和可維護性。在SwiftUI中，通過@ObservedObject、@StateObject和@EnvironmentObject等屬性包裝器，可以輕松實現視圖與視圖模型之間的數據綁定。

實踐步驟

1. 配置開發環境

所需工具和版本

macOS 12.0或更高版本
Xcode 14.0或更高版本
iOS 15.0+模擬器或實機

安裝步驟

從Mac App Store下載并安裝最新版Xcode
1. (如果沒有安裝，這里按鈕會有下載字樣，如果有安裝按鈕就是獲取)

安裝前

安裝后：

在終端配置Xcode命令行工具

在終端執行以下命令，配置Xcode command-line tools

sudo xcode-select --switch /Applications/Xcode.app/Contents/Developer
sudo xcodebuild -runFirstLaunch

執行sudo命令時，需要下輸入macOS登錄用戶名的密碼，且用戶名具有管理員權限。
執行xcodebuild -runFirstLaunch命令時，會要求先確認Xcode license。

這里輸入密碼

打開Xcode并接受許可協議，點擊Agree

安裝必要的組件（模擬器、命令行工具等）

在這里插入圖片描述

2. 創建新項目

打開Xcode，選擇"Create a new Xcode project"
選擇"App"模板，點擊"Next"
填寫項目信息：
- Product Name: YunChangAction
- Organization Identifier: com.example
- Interface: SwiftUI
- Language: Swift
- 確保"Use Core Data"未選中
選擇項目保存位置，點擊"Create"

在這里插入圖片描述

3. 配置項目基本信息

在這里插入圖片描述

在項目導航器中選擇項目文件
在"General"標簽頁中設置：
- Display Name: 靈感記錄
- Deployment Info: iOS 15.0+
- Device Orientation: Portrait
創建InfoCustom.plist文件，添加以下內容：

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict><key>CFBundleURLTypes</key><array><dict><key>CFBundleTypeRole</key><string>Editor</string><key>CFBundleURLName</key><string>com.yunchangaction</string><key>CFBundleURLSchemes</key><array><string>yunchangaction</string></array></dict></array><key>UIApplicationShortcutItems</key><array><dict><key>UIApplicationShortcutItemIconType</key><string>UIApplicationShortcutIconTypeCompose</string><key>UIApplicationShortcutItemTitle</key><string>快速記錄</string><key>UIApplicationShortcutItemType</key><string>com.yunchangaction.quicknote</string></dict></array></dict></plist>

在這里插入圖片描述

4. 創建項目文件結構

為了保持代碼的組織性和可維護性，我們將按照以下結構組織項目文件：

YunChangAction/
├── App/
│   ├── YunChangActionApp.swift  // 應用入口點
│   └── AppTheme.swift           // 應用主題定義
├── Views/
│   ├── SplashScreen.swift       // 啟動屏幕
│   ├── ContentView.swift        // 主內容視圖
│   ├── NoteViews/               // 筆記相關視圖
│   └── SettingsViews/           // 設置相關視圖
├── Models/
│   ├── InspirationNote.swift    // 靈感筆記模型
│   └── CategoryRecommendation.swift // AI推薦模型
├── ViewModels/
│   └── InspirationManager.swift // 靈感管理器
├── Services/
│   └── AIService.swift          // AI服務
├── Utilities/
│   └── Extensions.swift         // 擴展方法
└── Resources/
│   └── Assets.xcassets          // 資源文件

在Xcode中創建這些文件夾和文件：

在項目導航器中右鍵點擊YunChangAction文件夾
選擇"New Group"創建新文件夾
為每個文件夾創建相應的文件

5. 實現應用主題

創建AppTheme.swift文件，定義應用的主題色系：

import SwiftUI// 定義應用的主題色
struct AppTheme {static let primaryColor = Color(red: 0.2, green: 0.7, blue: 0.3)static let secondaryColor = Color(red: 0.5, green: 0.8, blue: 0.5)static let accentColor = Color(red: 0.4, green: 0.8, blue: 0.7)static let backgroundColor = Color(red: 0.95, green: 0.98, blue: 0.95)
}

6. 實現啟動屏幕

創建SplashScreen.swift文件，實現應用的啟動屏幕：

import SwiftUI// 啟動屏幕
struct SplashScreen: View {@State private var isAnimating = falsevar body: some View {ZStack {AppTheme.backgroundColor.ignoresSafeArea()VStack(spacing: 20) {Image(systemName: "lightbulb.fill").font(.system(size: 80)).foregroundColor(AppTheme.primaryColor).scaleEffect(isAnimating ? 1.2 : 1.0).animation(Animation.easeInOut(duration: 1.0).repeatForever(autoreverses: true),value: isAnimating)Text("靈感記錄").font(.largeTitle).fontWeight(.bold).foregroundColor(AppTheme.primaryColor)Text("捕捉每一個閃光的想法").font(.subheadline).foregroundColor(.gray).padding(.top, 4)}}.onAppear {isAnimating = true}}
}#Preview {SplashScreen()
}

在這里插入圖片描述

7. 修改應用入口點

修改YunChangActionApp.swift文件，集成啟動屏幕：

import SwiftUI
import WidgetKit@main
struct YunChangActionApp: App {@StateObject private var inspirationManager = InspirationManager()@State private var isQuickNoteActive = false@Environment(\.scenePhase) private var scenePhase@State private var showSplash = truevar body: some Scene {WindowGroup {ZStack {ContentView().environmentObject(inspirationManager).preferredColorScheme(.light).accentColor(AppTheme.primaryColor).onOpenURL { url in// 處理URL Scheme，用于快速啟動記錄功能if url.scheme == "yunchangaction" && url.host == "quicknote" {isQuickNoteActive = true}}// 條件性顯示啟動屏幕if showSplash {SplashScreen().transition(.opacity).zIndex(1).onAppear {// 2秒后隱藏啟動屏幕DispatchQueue.main.asyncAfter(deadline: .now() + 2) {withAnimation {showSplash = false}}}}}}}
}

8. 創建基本數據模型

創建InspirationNote.swift文件，定義靈感筆記的數據模型：

import SwiftUI// 靈感筆記模型
struct InspirationNote: Identifiable, Codable {var id = UUID()var content: Stringvar createdAt: Datevar isFavorite: Bool = falsevar category: NoteCategory = .generalvar color: NoteColor = .greenvar tags: Set<String> = []
}// 筆記分類
enum NoteCategory: String, Codable, CaseIterable, Identifiable {case general = "通用"case work = "工作"case personal = "個人"case idea = "創意"case todo = "待辦"case study = "學習"case travel = "旅行"case health = "健康"var id: String { self.rawValue }var icon: String {switch self {case .general: return "doc.text"case .work: return "briefcase"case .personal: return "person"case .idea: return "lightbulb"case .todo: return "checklist"case .study: return "book"case .travel: return "airplane"case .health: return "heart"}}
}// 筆記顏色
enum NoteColor: String, Codable, CaseIterable, Identifiable {case green = "綠色"case lightGreen = "淡綠色"case mint = "薄荷色"case teal = "青色"case lime = "青檸色"var id: String { self.rawValue }var color: Color {switch self {case .green: return Color(red: 0.2, green: 0.7, blue: 0.3)case .lightGreen: return Color(red: 0.5, green: 0.8, blue: 0.5)case .mint: return Color(red: 0.4, green: 0.8, blue: 0.7)case .teal: return Color(red: 0.2, green: 0.6, blue: 0.6)case .lime: return Color(red: 0.6, green: 0.8, blue: 0.3)}}
}

代碼解釋

SplashScreen.swift

// @State屬性包裝器用于管理視圖的本地狀態
// 當isAnimating變化時，SwiftUI會自動重新渲染視圖
@State private var isAnimating = false// ZStack用于在z軸方向疊加視圖元素
ZStack {// 設置背景色并忽略安全區域，使背景色填滿整個屏幕AppTheme.backgroundColor.ignoresSafeArea()// VStack用于垂直排列視圖元素VStack(spacing: 20) {// 使用SF Symbols圖標作為燈泡圖標Image(systemName: "lightbulb.fill").font(.system(size: 80)).foregroundColor(AppTheme.primaryColor)// scaleEffect修飾符用于縮放視圖// 根據isAnimating狀態在1.0和1.2之間變化.scaleEffect(isAnimating ? 1.2 : 1.0)// animation修飾符定義動畫效果// easeInOut表示動畫曲線，duration表示動畫持續時間// repeatForever使動畫無限重復，autoreverses使動畫來回播放.animation(Animation.easeInOut(duration: 1.0).repeatForever(autoreverses: true),value: isAnimating  // 監聽這個值的變化來觸發動畫)// 應用標題Text("靈感記錄").font(.largeTitle).fontWeight(.bold).foregroundColor(AppTheme.primaryColor)// 應用副標題Text("捕捉每一個閃光的想法").font(.subheadline).foregroundColor(.gray).padding(.top, 4)}
}
// onAppear在視圖出現時執行閉包
// 這里用于啟動動畫
.onAppear {isAnimating = true
}

YunChangActionApp.swift

// @main標記應用的入口點
@main
struct YunChangActionApp: App {// @StateObject用于創建和管理應用級別的狀態對象// inspirationManager將在整個應用生命周期內保持存在@StateObject private var inspirationManager = InspirationManager()// @State用于管理視圖的本地狀態@State private var isQuickNoteActive = false// @Environment用于訪問環境值// scenePhase表示應用的當前狀態（活躍、非活躍、后臺）@Environment(\.scenePhase) private var scenePhase// 控制是否顯示啟動屏幕@State private var showSplash = truevar body: some Scene {WindowGroup {// ZStack用于疊加ContentView和SplashScreenZStack {ContentView()// 將inspirationManager注入環境，使其在視圖層次結構中可用.environmentObject(inspirationManager)// 設置淺色模式.preferredColorScheme(.light)// 設置強調色.accentColor(AppTheme.primaryColor)// 處理URL Scheme.onOpenURL { url inif url.scheme == "yunchangaction" && url.host == "quicknote" {isQuickNoteActive = true}}// 條件性顯示啟動屏幕if showSplash {SplashScreen()// 設置過渡動畫為淡入淡出.transition(.opacity)// 確保啟動屏幕在最上層.zIndex(1).onAppear {// 延遲2秒后隱藏啟動屏幕DispatchQueue.main.asyncAfter(deadline: .now() + 2) {// 使用動畫效果隱藏啟動屏幕withAnimation {showSplash = false}}}}}}}
}

常見問題和解決方案

1. Xcode版本兼容性問題

問題：使用較舊版本的Xcode可能無法支持最新的SwiftUI功能。

解決方案：

升級到最新版本的Xcode
如果無法升級，可以修改代碼以兼容舊版本的SwiftUI
使用條件編譯來處理不同版本的API差異

// 條件編譯示例
#if compiler(>=5.5)
// 使用iOS 15+的API
if #available(iOS 15.0, *) {Text("新API").listRowSeparator(.hidden)
} else {// 兼容iOS 14及更早版本Text("舊API")
}
#else
// 兼容舊版本Swift編譯器
Text("舊API")
#endif

2. 預覽功能不工作

問題：SwiftUI預覽有時會停止工作或顯示錯誤。

解決方案：

重啟Xcode預覽（點擊預覽窗口中的刷新按鈕）
確保預覽代碼正確（檢查#Preview宏的使用）
清理項目（Product > Clean Build Folder）
重啟Xcode
檢查是否有編譯錯誤

3. 環境對象注入問題

問題：在視圖中無法訪問通過environmentObject注入的對象。

解決方案：

確保在視圖層次結構的頂層正確注入了環境對象
檢查是否正確使用了@EnvironmentObject屬性包裝器
確保環境對象類型匹配

// 正確注入環境對象
ContentView().environmentObject(inspirationManager)// 在子視圖中正確訪問環境對象
struct ChildView: View {@EnvironmentObject var inspirationManager: InspirationManagervar body: some View {Text("共有\(inspirationManager.notes.count)條筆記")}
}

4. 啟動屏幕閃爍問題

問題：啟動屏幕可能會在顯示后立即消失或閃爍。

解決方案：

確保延遲足夠長的時間再隱藏啟動屏幕
使用withAnimation包裝狀態變化，使過渡更平滑
添加適當的過渡動畫

// 平滑過渡的示例
.onAppear {// 立即開始動畫isAnimating = true// 延遲2秒后隱藏啟動屏幕DispatchQueue.main.asyncAfter(deadline: .now() + 2) {withAnimation(.easeOut(duration: 0.5)) {showSplash = false}}
}