FoxReader：从零构建 SwiftUI iOS 阅读 App 完整教程

发布于 · 2026-08-14 · # 默认分类

# FoxReader：从零构建 SwiftUI iOS 阅读 App 完整教程

```
教程由 AI 生成，仅搭建一个样子货
功能欠缺而且有 BUG ，仅用于学习记录
```

## 目录

- **开篇：认识 FoxReader** —— 项目概览，了解我们将要构建什么样的阅读 App
- **第一章：项目搭建与 MVVM 架构** —— 创建 Xcode 项目，添加依赖，理解 MVVM 设计模式
- **第二章：数据模型与 SwiftData** —— 使用 SwiftData 框架定义数据模型，实现本地持久化
- **第三章：阅读设置与主题系统** —— 构建统一的阅读设置管理器，实现多主题切换
- **第四章：HTML 模板引擎——统一渲染的秘密** —— 用一套 HTML 模板渲染 EPUB、Markdown、RSS 三种格式
- **第五章：WKWebView 封装与统一阅读器** —— 用 UIViewRepresentable 封装 WKWebView，构建统一阅读体验
- **第六章：书架与图书管理** —— 构建书架界面，实现导入、删除、进度跟踪
- **第七章：Markdown 解析与阅读** —— 纯 Foundation 实现 Markdown 转 HTML 转换器
- **第八章：EPUB 解析与阅读** —— 使用 ZIPFoundation 解压 EPUB，解析 OPF 目录与章节内容
- **第九章：RSS 订阅功能** —— 解析 RSS/Atom Feed，构建订阅管理与文章列表
- **第十章：WebKit for SwiftUI 新特性展望** —— 了解 WWDC25 引入的新 WebView/WebPage API
- **第十一章：项目完善与扩展指南** —— 测试建议、性能优化、未来功能展望

---

## 开篇：认识 FoxReader

你好！欢迎来到 FoxReader 的世界。

你是否曾经想过，手机上的阅读 App 是怎么做出来的？那些精美的排版、流畅的翻页、护眼的夜间模式——背后到底藏着怎样的技术？这个教程就是为你准备的。

FoxReader 是一个**统一的阅读 App**，它支持三种内容格式：RSS 订阅源、Markdown 文档、EPUB 电子书。你可能会觉得，这三种格式差别很大，要分别写三套渲染引擎吗？答案是——不需要。FoxReader 的核心设计理念就是：**把所有格式统一转换为 HTML，然后用一个 WebView 渲染**。这样，无论用户在读什么，都能获得一致的阅读体验。

在架构上，FoxReader 采用了 **MVVM 模式**（Model-View-ViewModel），配合 Apple 最新的 **SwiftData** 框架进行数据持久化。UI 全部用 **SwiftUI** 声明式构建。整个项目是纯 Swift 的，没有一行 Objective-C。

通过这个教程，你将学到：

- 如何用 SwiftUI 搭建一个完整的 iOS App
- 如何用 SwiftData 实现数据持久化（替代 Core Data）
- 如何用 MVVM 模式组织代码
- 如何将 EPUB、Markdown、RSS 统一渲染为 HTML
- 如何用 WKWebView 在 SwiftUI 中实现翻页阅读
- 如何实现多主题、多字体的阅读设置系统

在 WebView 与 SwiftUI 的集成方面，我们参考了 Apple 官方的 [WebKit for SwiftUI 文档](https://developer.apple.com/documentation/webkit/wkwebview)，使用 `UIViewRepresentable` 协议将 WKWebView 包装为 SwiftUI 视图。

准备好了吗？让我们开始吧。

---

## 第一章：项目搭建与 MVVM 架构

### 1.1 创建 Xcode 项目

打开 Xcode，点击 **File > New > Project**，在弹出的窗口中选择 **iOS > App** 模板，然后点击 Next。按照以下信息填写：

- **Product Name**：`FoxReader`
- **Interface**：选择 `SwiftUI`
- **Language**：选择 `Swift`
- **Storage**：选择 `SwiftData`（这一步很重要，Xcode 会自动帮你配置 SwiftData 容器）
- **Include Tests**：勾选（养成写测试的好习惯）

点击 Next，选择一个文件夹保存项目，点击 Create。项目就创建好了。

### 1.2 添加 ZIPFoundation 依赖

EPUB 文件本质上是一个 ZIP 压缩包，我们需要一个库来解压。这里使用 [ZIPFoundation](https://github.com/weichsel/ZIPFoundation.git)，它是 Swift 社区最受欢迎的 ZIP 处理库。

添加步骤：点击 **File > Add Package Dependencies**，在搜索框中粘贴以下 URL：

```
https://github.com/weichsel/ZIPFoundation.git
```

点击 Add Package，选择 `ZIPFoundation` 库，点击 Add Package。等待 Xcode 下载并集成完成即可。

### 1.3 项目文件夹结构

一个清晰的项目结构能让代码更容易维护。建议按以下方式组织文件夹：

```
FoxReader/
├── FoxReaderApp.swift          # App 入口
├── ContentView.swift           # 根视图（TabView）
├── Stubs.swift                 # 临时占位文件（后续章节逐步删除）
├── Models/                     # 数据模型
│   ├── Book.swift              # 图书模型
│   ├── RSSFeedSource.swift     # RSS 订阅源模型
│   └── Bookmark.swift          # 书签模型
├── Utilities/                  # 工具类
│   ├── Extensions.swift        # 通用扩展
│   ├── ReaderSettings.swift    # 阅读设置管理器
│   └── HTMLTemplates.swift     # HTML 模板引擎
├── Services/                   # 服务层
│   ├── EPUBService.swift       # EPUB 解析服务
│   ├── MarkdownService.swift   # Markdown 解析服务
│   ├── RSSService.swift        # RSS 解析服务
│   └── BookImportService.swift # 图书导入服务
├── ViewModels/                 # 视图模型
│   ├── LibraryViewModel.swift  # 书架视图模型
│   ├── ReaderViewModel.swift   # 阅读器视图模型
│   └── RSSViewModel.swift      # RSS 视图模型
└── Views/                      # 视图层
    ├── Components/             # 通用 UI 组件
    ├── Library/                # 书架相关视图
    ├── RSS/                    # RSS 相关视图
    ├── Reader/                 # 阅读器视图
    └── Settings/               # 设置视图
```

### 1.4 MVVM 架构解析

在写代码之前，我们先来理解 MVVM 架构。这里用一个**餐厅的比喻**来解释：

想象你去一家餐厅吃饭。你坐在桌前看**菜单**（这就是 **View**——用户界面），你点了一份宫保鸡丁。**服务员**（这就是 **ViewModel**）记下你的订单，送到后厨。**后厨**里有大厨和各种食材（这就是 **Model**——数据和业务逻辑），大厨做好菜后，服务员再把菜端给你。

在 MVVM 中：

- **Model**（模型）：负责数据和业务逻辑。在我们的 App 里，就是 `Book`、`RSSFeedSource` 这些数据模型，以及 EPUB 解析、RSS 抓取等服务。
- **View**（视图）：负责 UI 展示。就是用户看到的界面——书架列表、阅读器、设置页面。View 只管"怎么展示"，不管"数据从哪来"。
- **ViewModel**（视图模型）：连接 Model 和 View 的桥梁。它从 Model 获取数据，处理成 View 需要的格式，然后通过数据绑定通知 View 更新。

这样做的好处是：UI 代码和业务逻辑完全分离。改 UI 不影响逻辑，改逻辑不影响 UI。测试也更容易——你可以单独测试 ViewModel，不需要启动整个 UI。

### 1.5 App 入口与根视图

现在来看代码。首先是 App 的入口文件，它配置了 SwiftData 数据容器，注册了所有数据模型。

? 项目文件：`FoxReader/FoxReaderApp.swift`

```swift
import SwiftUI
import SwiftData

/// FoxReader App 入口
/// 配置 SwiftData 数据容器，注册所有 @Model 类型
@main
struct FoxReaderApp: App {
    var body: some Scene {
        WindowGroup {
            ContentView()
        }
        .modelContainer(for: [
            Book.self,
            RSSFeedSource.self,
            Bookmark.self
        ])
    }
}
```

几个关键点：

- `@main` 标记告诉 Swift 这是程序的入口点，App 启动时从这里开始执行。
- `.modelContainer(for:)` 是 SwiftData 的核心配置。它告诉系统："请帮我创建一个数据库，用来存储 `Book`、`RSSFeedSource` 和 `Bookmark` 这三种数据。" 有了这一行，SwiftData 就会自动创建 SQLite 数据库，你不需要手写任何 SQL。
- `WindowGroup` 定义了 App 的主窗口场景，里面放入了 `ContentView`。

接下来是根视图 `ContentView`，它用 `TabView` 组织了三个主要功能模块。

? 项目文件：`FoxReader/ContentView.swift`

```swift
import SwiftUI
import SwiftData

/// 根视图，使用 TabView 组织三个主要功能模块
/// 通过 @EnvironmentObject 将 ReaderSettings 注入整个视图层级
struct ContentView: View {
    @State private var selectedTab = 0
    @StateObject private var readerSettings = ReaderSettings()

var body: some View {
        TabView(selection: $selectedTab) {
            LibraryView()
                .tabItem {
                    Label("书架", systemImage: "books.vertical.fill")
                }
                .tag(0)

RSSListView()
                .tabItem {
                    Label("订阅", systemImage: "antenna.radiowaves.left.and.right")
                }
                .tag(1)

SettingsView()
                .tabItem {
                    Label("设置", systemImage: "gearshape.fill")
                }
                .tag(2)
        }
        .environmentObject(readerSettings)
    }
}

#Preview {
    ContentView()
        .modelContainer(for: [Book.self, RSSFeedSource.self, Bookmark.self], inMemory: true)
}
```

几个关键点：

- `TabView` 创建了底部标签栏，用户可以在"书架"、"订阅"、"设置"三个页面之间切换。`selection: $selectedTab` 用 `$` 前缀创建双向绑定，既可读取当前选中的标签，也可在代码中修改它来切换页面。
- `@StateObject private var readerSettings` 创建了阅读设置的实例。`@StateObject` 的意思是"这个视图拥有并管理这个对象的生命周期"。然后用 `.environmentObject(readerSettings)` 把它注入到整个视图层级中，所有子视图都可以通过 `@EnvironmentObject` 读取它。
- `#Preview` 块中的 `inMemory: true` 表示在预览时使用内存数据库，不会写入磁盘，这样在 Xcode Canvas 中预览时不会污染真实数据。

### 1.6 创建占位文件（确保项目可编译）

上面的代码引用了 `Book`、`RSSFeedSource`、`Bookmark`（第二章）、`ReaderSettings`（第三章）、`LibraryView`（第六章）、`RSSListView`、`SettingsView`（第九章）等类型。这些类型将在后续章节中逐步实现，但为了让你在第一章结束时就能编译运行项目，我们先创建一个占位文件。

> ? 项目文件：`FoxReader/Stubs.swift`（新建）

```swift
import Foundation
import SwiftData
import SwiftUI

// MARK: - 临时占位类型
// 以下类型为占位定义，将在后续章节中被完整实现替换
// 完成对应章节后，请从本文件中删除对应的占位代码

// ─── 第二章将替换 ───
@Model
final class Book {
    var id: UUID = UUID()
    var title: String = ""
    var bookType: String = ""
}

@Model
final class RSSFeedSource {
    var id: UUID = UUID()
    var title: String = ""
    var feedURL: String = ""
    var feedDescription: String = ""
}

@Model
final class Bookmark {
    var id: UUID = UUID()
}

// ─── 第三章将替换 ───
final class ReaderSettings: ObservableObject {
    @Published var fontSize: Double = 18
}

// ─── 第六章将替换 ───
struct LibraryView: View {
    var body: some View {
        Text("书架功能将在第六章实现")
            .navigationTitle("书架")
    }
}

// ─── 第九章将替换 ───
struct RSSListView: View {
    @EnvironmentObject var readerSettings: ReaderSettings

var body: some View {
        Text("订阅功能将在第九章实现")
            .navigationTitle("订阅")
    }
}

struct SettingsView: View {
    @EnvironmentObject var readerSettings: ReaderSettings

var body: some View {
        Text("设置功能将在第九章实现")
            .navigationTitle("设置")
    }
}
```

> **重要提示**：这个文件中的所有类型都是临时占位。在后续章节中，当你创建了真正的类型定义文件后，请回到这个文件，删除对应的占位代码。当所有章节完成后，这个文件应该为空，可以删除。

现在，点击 Xcode 的 **Cmd+B** 编译项目，应该能成功编译通过。你会看到一个带有三个标签的 App 界面，虽然每个页面只显示一行占位文字，但这意味着你的项目结构和 MVVM 架构已经搭建好了。

---

## 第二章：数据模型与 SwiftData

> **替换占位代码**：在开始本章之前，请打开 `Stubs.swift` 文件，删除 `Book`、`RSSFeedSource`、`Bookmark` 三个占位类型。本章将创建它们的完整实现。

### 2.1 什么是 SwiftData

SwiftData 是 Apple 在 2023 年 WWDC 上推出的全新数据持久化框架，可以看作 Core Data 的"继任者"。它用 Swift 宏来定义数据模型，写法极其简洁——你几乎感觉不到自己在操作数据库。

打个比方：SwiftData 就像一个**智能档案柜**。你只需要定义"文件夹的结构"（用 `@Model` 标记你的类），它就会自动帮你处理存储、读取、更新、删除这些繁琐的工作。你不需要写 SQL 语句，不需要配置 `.xcdatamodeld` 文件，甚至不需要关心底层的 SQLite 细节。

在 SwiftData 中，你只需要做两件事：

1. 用 `@Model` 宏标记你的数据类
2. 在 App 入口用 `.modelContainer(for:)` 注册这些类

就这么简单。SwiftData 会自动为你的类生成数据库表，处理对象关系映射（ORM），提供查询和保存的 API。

### 2.2 Book 模型——图书数据

`Book` 是最核心的数据模型，它存储了用户导入的所有书籍和文章信息。

? 项目文件：`FoxReader/Models/Book.swift`

```swift
import Foundation
import SwiftData

/// 图书类型枚举，支持 EPUB、Markdown、RSS 三种格式
enum BookType: String, Codable {
    case epub
    case markdown
    case rss

var displayName: String {
        switch self {
        case .epub: return "EPUB"
        case .markdown: return "Markdown"
        case .rss: return "RSS"
        }
    }

var iconName: String {
        switch self {
        case .epub: return "book.fill"
        case .markdown: return "doc.richtext"
        case .rss: return "antenna.radiowaves.left.and.right"
        }
    }
}

/// 图书数据模型，使用 SwiftData 持久化
/// 存储用户导入的所有书籍/文章信息
@Model
final class Book {
    var id: UUID
    var title: String
    var author: String
    /// SwiftData 不直接支持枚举存储，使用 String 原始值
    var bookTypeRaw: String
    /// 本地文件路径或 RSS 文章 URL
    var fileURL: String
    var coverImageData: Data?
    var addedDate: Date
    var lastReadDate: Date?
    /// 阅读进度 0.0 ~ 1.0
    var readProgress: Double
    var totalChapters: Int
    var currentChapterIndex: Int

/// 计算属性：将 String 转换为枚举
    var bookType: BookType {
        get { BookType(rawValue: bookTypeRaw) ?? .epub }
        set { bookTypeRaw = newValue.rawValue }
    }

init(
        id: UUID = UUID(),
        title: String,
        author: String = "未知作者",
        bookType: BookType,
        fileURL: String,
        coverImageData: Data? = nil,
        addedDate: Date = .now,
        lastReadDate: Date? = nil,
        readProgress: Double = 0,
        totalChapters: Int = 0,
        currentChapterIndex: Int = 0
    ) {
        self.id = id
        self.title = title
        self.author = author
        self.bookTypeRaw = bookType.rawValue
        self.fileURL = fileURL
        self.coverImageData = coverImageData
        self.addedDate = addedDate
        self.lastReadDate = lastReadDate
        self.readProgress = readProgress
        self.totalChapters = totalChapters
        self.currentChapterIndex = currentChapterIndex
    }
}
```

几个关键点：

- `@Model` 宏是 SwiftData 的魔法所在。标记之后，SwiftData 会自动为这个类生成持久化代码。`final class` 是必须的——SwiftData 需要继承自一个隐藏的基类，`final` 确保不被进一步继承。
- SwiftData **不直接支持枚举存储**，所以 `BookType` 枚举的值通过 `bookTypeRaw: String` 来保存。然后我们用一个**计算属性** `bookType` 来做转换：`get` 时把 String 转回枚举，`set` 时把枚举的 `rawValue` 存进 String。这是 SwiftData 中处理枚举的标准模式。
- `coverImageData: Data?` 和 `lastReadDate: Date?` 用了可选类型（`?`），因为新书可能还没有封面图片，也可能还没读过。SwiftData 完美支持可选属性的存储。

### 2.3 RSSFeedSource 模型——订阅源

这个模型存储用户订阅的 RSS/Atom Feed 信息。

? 项目文件：`FoxReader/Models/RSSFeedSource.swift`

```swift
import Foundation
import SwiftData

/// RSS 订阅源数据模型
/// 存储用户订阅的 RSS/Atom Feed 信息
@Model
final class RSSFeedSource {
    var id: UUID
    var title: String
    var feedURL: String
    var feedDescription: String
    var lastUpdated: Date?

init(
        id: UUID = UUID(),
        title: String,
        feedURL: String,
        feedDescription: String = "",
        lastUpdated: Date? = nil
    ) {
        self.id = id
        self.title = title
        self.feedURL = feedURL
        self.feedDescription = feedDescription
        self.lastUpdated = lastUpdated
    }
}
```

几个关键点：

- 每个 `RSSFeedSource` 代表一个订阅源，比如某个博客的 RSS 链接。`feedURL` 存储的是 RSS feed 的地址，`title` 是用户可读的名称（比如"阮一峰的网络日志"）。
- `lastUpdated` 是可选的 `Date?`，用来记录上次更新时间。用户打开订阅页面时，我们可以根据这个时间判断是否需要重新抓取最新文章。
- `id: UUID = UUID()` 使用了默认参数。创建对象时不需要手动传 id，Swift 会自动生成一个唯一的 UUID。

### 2.4 Bookmark 模型——书签

书签模型记录用户在阅读过程中标记的位置和笔记。

? 项目文件：`FoxReader/Models/Bookmark.swift`

```swift
import Foundation
import SwiftData

/// 书签数据模型
/// 记录用户在阅读过程中添加的书签
@Model
final class Bookmark {
    var id: UUID
    /// 关联的书籍 ID
    var bookID: UUID
    var chapterIndex: Int
    var note: String
    var createdDate: Date

init(
        id: UUID = UUID(),
        bookID: UUID,
        chapterIndex: Int = 0,
        note: String = "",
        createdDate: Date = .now
    ) {
        self.id = id
        self.bookID = bookID
        self.chapterIndex = chapterIndex
        self.note = note
        self.createdDate = createdDate
    }
}
```

几个关键点：

- `bookID: UUID` 通过存储关联书籍的 UUID 来建立"软关联"——它不是数据库外键，而是在应用层通过代码查询关联的 Book 对象。这种方式在 SwiftData 中很常见，比正式的关系映射更灵活。
- `chapterIndex` 记录书签在哪一章，`note` 存储用户添加的笔记内容。这样用户不仅能回到之前的阅读位置，还能看到当时写下的心得。
- 三个模型都用 `UUID` 作为主键，而不是自增整数。UUID 的好处是：即使在没有网络的情况下（比如离线创建对象），也能保证 id 全局唯一，将来同步到云端时不会冲突。

---

## 第三章：阅读设置与主题系统

> **替换占位代码**：在开始本章之前，请打开 `Stubs.swift` 文件，删除 `ReaderSettings` 占位类型。本章将创建它的完整实现。

### 3.1 为什么需要统一的设置系统

阅读 App 的核心体验是什么？是让用户**舒服地阅读**。每个人对"舒服"的定义不同：有人喜欢白底黑字，有人喜欢暗黑模式；有人喜欢大字体，有人喜欢小字体；有人习惯滚动浏览，有人习惯翻页阅读。

如果我们的 App 支持三种格式（EPUB、Markdown、RSS），每种格式各写一套设置系统，那太痛苦了。FoxReader 的做法是：**创建一个全局的 `ReaderSettings` 管理器，所有格式共用同一套设置**。无论你在读什么，主题、字体、字号、翻页方式都保持一致。

打个比方：这就像在图书馆里选座位。你挑选**灯光亮度**（对应主题——白天、护眼、深色、夜间）、**椅子高度**（对应字号——从 12px 到 24px）、**老花镜还是近视镜**（对应字体——系统体、衬线体、圆体），以及**阅读姿势**（对应翻页方式——滚动还是翻页）。选好之后，无论你从书架上拿什么书来读，这个座位环境都是一样的。

### 3.2 阅读设置管理器

先来看设置管理器和主题枚举的完整代码。

? 项目文件：`FoxReader/Utilities/ReaderSettings.swift`

```swift
import SwiftUI
import Combine

// MARK: - 阅读主题
/// 定义四种阅读主题：白天、护眼、深色、夜间
enum ReaderTheme: String, CaseIterable {
    case light = "light"
    case sepia = "sepia"
    case dark = "dark"
    case night = "night"

var displayName: String {
        switch self {
        case .light: return "白天"
        case .sepia: return "护眼"
        case .dark: return "深色"
        case .night: return "夜间"
        }
    }

var iconName: String {
        switch self {
        case .light: return "sun.max.fill"
        case .sepia: return "leaf.fill"
        case .dark: return "moon.fill"
        case .night: return "moon.stars.fill"
        }
    }

/// SwiftUI 背景色（用于原生 UI）
    var backgroundColor: Color {
        switch self {
        case .light: return Color(hex: "FFFFFF")
        case .sepia: return Color(hex: "F5DEB3")
        case .dark: return Color(hex: "2C2C2C")
        case .night: return Color(hex: "1A1A1A")
        }
    }

/// SwiftUI 文字色（用于原生 UI）
    var textColor: Color {
        switch self {
        case .light: return Color(hex: "333333")
        case .sepia: return Color(hex: "5B4636")
        case .dark: return Color(hex: "CCCCCC")
        case .night: return Color(hex: "808080")
        }
    }

/// CSS 背景色（用于 WebView 内容）
    var cssBackgroundColor: String {
        switch self {
        case .light: return "#FFFFFF"
        case .sepia: return "#F5DEB3"
        case .dark: return "#2C2C2C"
        case .night: return "#1A1A1A"
        }
    }

/// CSS 文字色（用于 WebView 内容）
    var cssTextColor: String {
        switch self {
        case .light: return "#333333"
        case .sepia: return "#5B4636"
        case .dark: return "#CCCCCC"
        case .night: return "#808080"
        }
    }
}

// MARK: - 阅读字体
enum ReaderFont: String, CaseIterable {
    case system = "system"
    case serif = "serif"
    case rounded = "rounded"

var displayName: String {
        switch self {
        case .system: return "系统"
        case .serif: return "衬线"
        case .rounded: return "圆体"
        }
    }

var iconName: String {
        switch self {
        case .system: return "textformat"
        case .serif: return "textformat.size"
        case .rounded: return "textformat.alt"
        }
    }

/// CSS font-family 值
    var cssFontFamily: String {
        switch self {
        case .system: return "-apple-system, 'Helvetica Neue', sans-serif"
        case .serif: return "'Georgia', 'Times New Roman', serif"
        case .rounded: return "'SF Pro Rounded', 'Avenir Next Rounded', sans-serif"
        }
    }
}

// MARK: - 翻页方式
enum PageMode: String, CaseIterable {
    case scroll = "scroll"
    case paginated = "paginated"

var displayName: String {
        switch self {
        case .scroll: return "滚动"
        case .paginated: return "翻页"
        }
    }

var iconName: String {
        switch self {
        case .scroll: return "scroll"
        case .paginated: return "book"
        }
    }
}

// MARK: - 阅读设置管理器
/// 全局阅读设置管理器，使用 ObservableObject + @AppStorage 持久化
/// 通过 @EnvironmentObject 在视图层级中共享
final class ReaderSettings: ObservableObject {
    // 1. 集中管理 Keys 和默认值，消除硬编码
    private enum Keys {
        static let theme = "reader.theme"
        static let fontSize = "reader.fontSize"
        static let fontFamily = "reader.fontFamily"
        static let pageMode = "reader.pageMode"
    }

private enum Default {
        static let theme = ReaderTheme.light
        static let fontSize: Double = 17
        static let fontFamily = ReaderFont.system
        static let pageMode = PageMode.scroll
    }

// 2. 使用 @AppStorage 替代手写 UserDefaults 存取
    @AppStorage(Keys.theme) private var themeStorage: String = Default.theme.rawValue
    @AppStorage(Keys.fontSize) private var fontSizeStorage: Double = Default.fontSize
    @AppStorage(Keys.fontFamily) private var fontFamilyStorage: String = Default.fontFamily.rawValue
    @AppStorage(Keys.pageMode) private var pageModeStorage: String = Default.pageMode.rawValue

// 3. 对外暴露计算属性，变更时触发 UI 刷新
    var theme: ReaderTheme {
        get { ReaderTheme(rawValue: themeStorage) ?? Default.theme }
        set {
            guard theme != newValue else { return }
            themeStorage = newValue.rawValue
            objectWillChange.send()
        }
    }

var fontSize: Double {
        get { fontSizeStorage }
        set {
            guard fontSize != newValue else { return }
            fontSizeStorage = newValue
            objectWillChange.send()
        }
    }

var fontFamily: ReaderFont {
        get { ReaderFont(rawValue: fontFamilyStorage) ?? Default.fontFamily }
        set {
            guard fontFamily != newValue else { return }
            fontFamilyStorage = newValue.rawValue
            objectWillChange.send()
        }
    }

var pageMode: PageMode {
        get { PageMode(rawValue: pageModeStorage) ?? Default.pageMode }
        set {
            guard pageMode != newValue else { return }
            pageModeStorage = newValue.rawValue
            objectWillChange.send()
        }
    }
}
```

几个关键点：

- `ReaderTheme`、`ReaderFont`、`PageMode` 三个枚举都遵循 `CaseIterable`，这样在设置界面中可以用 `for theme in ReaderTheme.allCases` 来遍历所有选项，自动生成选择按钮。每个枚举都提供了 `displayName`（中文显示名）、`iconName`（SF Symbols 图标名），以及 CSS 相关的值——因为我们的阅读器是基于 WebView 渲染的，颜色和字体最终要转换成 CSS 属性。
- `ReaderSettings` 用了 `ObservableObject` + `@AppStorage` 的模式。`@AppStorage` 是 SwiftUI 提供的属性包装器，它会自动读写 `UserDefaults`——你不需要手写 `didSet` 来持久化，也不需要在 `init()` 中手动读取。每个设置项用私有的 `@AppStorage` 存储属性（如 `themeStorage`）做底层持久化，对外则暴露计算属性（如 `theme`），在 `set` 中通过 `objectWillChange.send()` 手动触发 UI 刷新。这样，用户改了设置，UI 实时更新，同时数据也自动持久化到磁盘——下次打开 App 时设置依然保留。
- `Keys` 和 `Default` 两个私有枚举集中管理了所有的 `UserDefaults` 键名和默认值，消除了硬编码字符串散落各处的问题。首次安装 App 时，`@AppStorage` 会自动使用声明的默认值（主题=白天、字号=17、字体=系统、翻页=滚动）。`set` 中的 `guard` 检查防止重复写入相同值，避免不必要的 UI 刷新。

### 3.3 通用扩展工具

下面是项目中的通用扩展，包括 Color 的 hex 初始化、Date 格式化、String 处理等。

? 项目文件：`FoxReader/Utilities/Extensions.swift`

```swift
import SwiftUI

// MARK: - Color 扩展
/// 支持通过 Hex 字符串创建 SwiftUI Color
/// 用法: Color(hex: "FF5733")
extension Color {
    init(hex: String) {
        let hex = hex.trimmingCharacters(in: CharacterSet.alphanumerics.inverted)
        var int: UInt64 = 0
        Scanner(string: hex).scanHexInt64(&int)
        let a, r, g, b: UInt64
        switch hex.count {
        case 3:
            (a, r, g, b) = (255, (int >> 8) * 17, (int >> 4 & 0xF) * 17, (int & 0xF) * 17)
        case 6:
            (a, r, g, b) = (255, int >> 16, int >> 8 & 0xFF, int & 0xFF)
        case 8:
            (a, r, g, b) = (int >> 24, int >> 16 & 0xFF, int >> 8 & 0xFF, int & 0xFF)
        default:
            (a, r, g, b) = (255, 0, 0, 0)
        }
        self.init(
            .sRGB,
            red: Double(r) / 255,
            green: Double(g) / 255,
            blue: Double(b) / 255,
            opacity: Double(a) / 255
        )
    }
}

// MARK: - Date 扩展
extension Date {
    /// 格式化为简短日期字符串，如 "3月15日"
    var shortDisplayString: String {
        let formatter = DateFormatter()
        formatter.dateFormat = "M月d日"
        formatter.locale = Locale(identifier: "zh_CN")
        return formatter.string(from: self)
    }

/// 相对时间描述，如 "刚刚"、"3分钟前"
    var relativeDisplayString: String {
        let interval = Date().timeIntervalSince(self)
        if interval < 60 {
            return "刚刚"
        } else if interval < 3600 {
            return "\(Int(interval / 60))分钟前"
        } else if interval < 86400 {
            return "\(Int(interval / 3600))小时前"
        } else if interval < 604800 {
            return "\(Int(interval / 86400))天前"
        } else {
            return shortDisplayString
        }
    }
}

// MARK: - String 扩展
extension String {
    /// 截取指定长度的字符串
    func truncated(to maxLength: Int) -> String {
        if self.count <= maxLength {
            return self
        }
        return String(self.prefix(maxLength)) + "..."
    }

/// 清理 HTML 标签，返回纯文本
    var strippedHTML: String {
        self.replacingOccurrences(of: "<[^>]+>", with: "", options: .regularExpression)
    }
}

// MARK: - URL 扩展
extension URL {
    /// 判断是否为有效的 HTTP/HTTPS URL
    var isHTTPURL: Bool {
        return self.scheme == "http" || self.scheme == "https"
    }
}
```

几个关键点：

- `Color(hex:)` 扩展是整个项目中使用频率最高的工具之一。SwiftUI 的 `Color` 没有内置 hex 初始化器，但设计师通常给我们的是 hex 色值（如 `#F5DEB3`）。这个扩展支持 3 位（`FFF`）、6 位（`FFFFFF`）、8 位（`FFFFFFFF`）三种 hex 格式，用 `Scanner` 将十六进制字符串解析为数值，再转换为 RGB 分量。
- `Date.relativeDisplayString` 提供了"刚刚"、"3分钟前"、"2小时前"这类相对时间描述，在 RSS 文章列表中特别有用——用户一眼就能看出这篇文章是多久前发布的。
- `String.strippedHTML` 用正则表达式去掉所有 HTML 标签，返回纯文本。在 RSS 文章摘要展示中会用到，因为很多 RSS feed 的 description 字段包含 HTML 标签，但在列表中我们只想显示纯文字。

---

## 第四章：HTML 模板引擎——统一渲染的秘密

### 4.1 核心设计理念：万物皆 HTML

这一章是整个 FoxReader 项目的**灵魂所在**。

回想一下我们的 App 支持三种格式：EPUB、Markdown、RSS。如果为每种格式分别写一套渲染引擎，那工作量会非常大，而且很难保证三种格式的阅读体验一致。

FoxReader 的核心洞察是：**EPUB 的内容本身就是 HTML，Markdown 可以转换为 HTML，RSS 文章的正文也是 HTML**。也就是说，这三种格式都可以统一到 HTML。那么，我们只需要一个 WebView，一套 CSS 样式，一套 JavaScript 分页逻辑，就能渲染所有内容。

这就像一个**万能翻译器**。不管原文是英文、法文还是日文，翻译器都先把它翻译成中文，然后你只需要用中文阅读。在 FoxReader 中，EPUB 解析器、Markdown 解析器、RSS 解析器各自负责把内容"翻译"成 HTML 片段，然后交给 HTML 模板引擎统一包装成完整的网页。

这样做的好处是巨大的：

- **一套样式管所有**：改一处 CSS，三种格式的显示效果同时更新
- **一套翻页逻辑管所有**：JavaScript 分页代码只写一次，EPUB/Markdown/RSS 都能用
- **主题切换即时生效**：修改阅读设置后，重新生成 HTML 即可应用新样式
- **开发效率高**：新增一种格式只需要写一个"翻译器"（转成 HTML），不需要写渲染逻辑

### 4.2 模板结构详解

HTML 模板由三部分组成：

1. **CSS 样式**：定义文字颜色、背景色、字体、字号、行高、标题样式、代码块样式等。所有样式值都从 `ReaderSettings` 动态注入。
2. **正文容器**：一个 `<div class="content">` 包裹传入的 HTML 内容。
3. **JavaScript 分页逻辑**：计算总页数，提供翻页函数（上一页、下一页、跳转到指定页）。

当用户在设置中切换主题或调整字号时，我们会用新的设置重新生成 HTML 并加载到 WebView 中。CSS 的 `column-width` 属性是实现翻页模式的关键——它把内容分成等宽的列，每一列就是一"页"。

### 4.3 HTML 模板引擎完整代码

? 项目文件：`FoxReader/Utilities/HTMLTemplates.swift`

```swift
import Foundation

/// HTML 模板生成器
/// 将阅读内容包装为完整的 HTML 文档，注入 CSS 样式和 JavaScript 分页逻辑
/// 这是实现「统一阅读样式」的核心组件
struct HTMLTemplates {

// MARK: - 主模板

/// 将内容包装为完整 HTML 文档
    /// - Parameters:
    ///   - content: HTML 格式的正文内容
    ///   - settings: 阅读设置
    /// - Returns: 完整的 HTML 字符串
    static func wrapContent(_ content: String, settings: ReaderSettings) -> String {
        let theme = settings.theme
        let paginationCSS = settings.pageMode == .paginated ? paginatedCSS : scrollCSS

return """
        <!DOCTYPE html>
        <html lang="zh-CN">
        <head>
            <meta charset="utf-8">
            <meta name="viewport" content="width=device-width, initial-scale=1.0, \
        maximum-scale=1.0, user-scalable=no">
            <style>
                * { margin: 0; padding: 0; box-sizing: border-box; }

html, body {
                    background-color: \(theme.cssBackgroundColor);
                    color: \(theme.cssTextColor);
                    font-family: \(settings.fontFamily.cssFontFamily);
                    font-size: \(Int(settings.fontSize))px;
                    line-height: 1.8;
                    -webkit-text-size-adjust: none;
                    word-wrap: break-word;
                    -webkit-user-select: text;
                }

\(paginationCSS)

.content { padding: 20px 16px 60px 16px; }

h1 { font-size: 1.8em; margin-top: 1.5em; margin-bottom: 0.5em; font-weight: 700; }
                h2 { font-size: 1.5em; margin-top: 1.3em; margin-bottom: 0.4em; font-weight: 700; }
                h3 { font-size: 1.3em; margin-top: 1.1em; margin-bottom: 0.3em; font-weight: 600; }
                h4 { font-size: 1.1em; margin-top: 1em; margin-bottom: 0.3em; font-weight: 600; }
                h5, h6 { font-size: 1em; margin-top: 0.8em; margin-bottom: 0.2em; font-weight: 600; }

p { margin: 0.8em 0; text-align: justify; }

img { max-width: 100%; height: auto; border-radius: 8px; margin: 1em 0; }

a { color: \(accentColor(for: theme)); text-decoration: none; }

blockquote {
                    border-left: 3px solid \(accentColor(for: theme));
                    padding-left: 15px;
                    margin: 1em 0;
                    opacity: 0.85;
                }

code {
                    background-color: \(codeBgColor(for: theme));
                    padding: 2px 6px;
                    border-radius: 4px;
                    font-size: 0.9em;
                    font-family: 'SF Mono', 'Menlo', monospace;
                }

pre {
                    background-color: \(codeBgColor(for: theme));
                    padding: 15px;
                    border-radius: 8px;
                    overflow-x: auto;
                    margin: 1em 0;
                }

pre code {
                    background-color: transparent;
                    padding: 0;
                    border-radius: 0;
                }

ul, ol { padding-left: 1.5em; margin: 0.8em 0; }
                li { margin: 0.3em 0; }

table {
                    width: 100%;
                    border-collapse: collapse;
                    margin: 1em 0;
                }
                th, td {
                    border: 1px solid \(borderColor(for: theme));
                    padding: 8px 12px;
                    text-align: left;
                }
                th { font-weight: 600; }

hr {
                    border: none;
                    border-top: 1px solid \(borderColor(for: theme));
                    margin: 1.5em 0;
                }
            </style>
        </head>
        <body>
            <div class="content">
                \(content)
            </div>
            <script>
                // 分页相关 JavaScript
                var totalPages = 1;
                var currentPage = 0;

function updatePageCount() {
                    var body = document.body;
                    var scrollWidth = body.scrollWidth;
                    var clientWidth = document.documentElement.clientWidth;
                    totalPages = Math.max(1, Math.ceil(scrollWidth / clientWidth));
                }

function goToPage(page) {
                    var clientWidth = document.documentElement.clientWidth;
                    window.scrollTo(page * clientWidth, 0);
                    currentPage = page;
                }

function nextPage() {
                    if (currentPage < totalPages - 1) {
                        goToPage(currentPage + 1);
                    }
                }

function previousPage() {
                    if (currentPage > 0) {
                        goToPage(currentPage - 1);
                    }
                }

// 页面加载完成后计算页数
                window.addEventListener('load', function() {
                    updatePageCount();
                });
            </script>
        </body>
        </html>
        """
    }

// MARK: - CSS 片段

/// 滚动模式 CSS
    private static var scrollCSS: String {
        """
        body {
            overflow-y: auto;
            overflow-x: hidden;
        }
        """
    }

/// 翻页模式 CSS（使用 CSS 多列布局）
    private static var paginatedCSS: String {
        """
        html, body {
            height: 100vh;
            overflow: hidden;
        }
        .content {
            column-width: 100vw;
            column-gap: 0;
            height: calc(100vh - 40px);
            padding: 20px 16px;
        }
        """
    }

// MARK: - 辅助方法

/// 根据主题获取强调色
    private static func accentColor(for theme: ReaderTheme) -> String {
        switch theme {
        case .light: return "#007AFF"
        case .sepia: return "#8B6914"
        case .dark: return "#5AC8FA"
        case .night: return "#4A90A4"
        }
    }

/// 根据主题获取代码块背景色
    private static func codeBgColor(for theme: ReaderTheme) -> String {
        switch theme {
        case .light: return "#F5F5F5"
        case .sepia: return "#E8D9B0"
        case .dark: return "#3A3A3A"
        case .night: return "#2A2A2A"
        }
    }

/// 根据主题获取边框色
    private static func borderColor(for theme: ReaderTheme) -> String {
        switch theme {
        case .light: return "#E0E0E0"
        case .sepia: return "#D4C4A0"
        case .dark: return "#555555"
        case .night: return "#3A3A3A"
        }
    }
}
```

几个关键点：

- **CSS 多列分页**：翻页模式的核心是 `column-width: 100vw`。它让 `.content` 容器把内容分成多个列，每列宽度正好是一个屏幕宽度（`100vw`）。这样内容会自动横向溢出，用户左右滑动就是在"翻页"。配合 JavaScript 的 `window.scrollTo(page * clientWidth, 0)`，就能精确跳转到某一页。而滚动模式则简单地用 `overflow-y: auto` 让内容纵向滚动。
- **设置动态注入**：注意 CSS 中大量使用了 Swift 的字符串插值 `\(...)`。`background-color: \(theme.cssBackgroundColor)` 会把当前主题的背景色直接写入 CSS。`font-size: \(Int(settings.fontSize))px` 把用户选择的字号注入。这意味着每次设置改变，我们只需要重新调用 `wrapContent()` 生成新 HTML，WebView 重新加载后样式就会立刻更新。
- **主题感知的辅助色**：`accentColor(for:)`、`codeBgColor(for:)`、`borderColor(for:)` 这三个辅助方法根据当前主题返回不同的颜色值。比如白天模式的链接是蓝色（`#007AFF`），深色模式则是亮蓝色（`#5AC8FA`），确保在暗色背景下依然清晰可见。这种"同一套模板、不同主题色"的设计让每种主题都有精心调配的配色方案，而不是简单地反转颜色。

---

## 第五章：WKWebView 封装与统一阅读器

在前几章中，我们搭建好了数据模型和设置系统。现在是时候把内容真正展示出来了。FoxReader 支持两种主要格式：EPUB 和 Markdown。它们最终都会被转换成 HTML，然后渲染到屏幕上。那么问题来了——SwiftUI 怎么显示 HTML？

### 为什么要封装 WKWebView

SwiftUI 本身没有原生的网页视图组件。在 iOS 18 之前，如果你想显示一段 HTML 内容，唯一的办法就是借助 UIKit 里久经考验的 `WKWebView`。这就像你的新房子（SwiftUI）还没有装好窗户，但你手头有一扇旧房子（UIKit）拆下来的好窗户（WKWebView），直接装上就能用。

值得一提的是，WWDC25 上苹果终于为 SwiftUI 原生引入了 `WebView` 组件。这意味着未来我们可以像用 `Text`、`Image` 一样简单地嵌入网页视图。但作为学习项目，理解 `UIViewRepresentable` 这套桥接机制依然非常重要——它不仅是 WebView，所有 UIKit 组件迁移到 SwiftUI 都靠这个模式。

### UIViewRepresentable：UIKit 与 SwiftUI 的翻译官

`UIViewRepresentable` 是一座桥梁。想象一个场景：一位只会说中文的工程师（SwiftUI）和一位只会说英文的工人（UIKit）要合作。`UIViewRepresentable` 就是中间的翻译官，它定义了两个核心任务：

- `makeUIView`：告诉 UIKit 工人"创建一个什么东西"
- `updateUIView`：当 SwiftUI 的状态变化时，告诉 UIKit 工人"更新成什么样子"

还有第三个角色叫 `Coordinator`，它像工人的助手，专门负责监听 UIKit 那边发生的事件（比如页面加载完成），然后汇报给 SwiftUI。

? 项目文件：`FoxReader/Views/Reader/WebViewContainer.swift`

```swift
import SwiftUI
import WebKit
import Combine

// MARK: - WebView 状态管理器

/// 持有 WKWebView 的弱引用，提供 JavaScript 调用接口
/// 用于在 SwiftUI 视图中控制 WebView 的行为（如翻页）
final class WebViewState: ObservableObject {
    weak var webView: WKWebView?

/// 执行 JavaScript 脚本
    func evaluate(_ script: String) {
        webView?.evaluateJavaScript(script)
    }

/// 下一页（翻页模式）
    func nextPage() {
        evaluate("nextPage()")
    }

/// 上一页（翻页模式）
    func previousPage() {
        evaluate("previousPage()")
    }
}

// MARK: - UIColor Hex 扩展

private extension UIColor {
    convenience init(hexString: String) {
        let hex = hexString.replacingOccurrences(of: "#", with: "")
        var int: UInt64 = 0
        Scanner(string: hex).scanHexInt64(&int)
        self.init(
            red: CGFloat((int >> 16) & 0xFF) / 255,
            green: CGFloat((int >> 8) & 0xFF) / 255,
            blue: CGFloat(int & 0xFF) / 255,
            alpha: 1.0
        )
    }
}

// MARK: - WebView 容器

/// WKWebView 的 SwiftUI 封装
/// 负责加载 HTML 内容、管理背景色、处理滚动
/// 当 htmlContent 变化时自动重新加载（如切换主题/字体后）
struct WebViewContainer: UIViewRepresentable {
    let htmlContent: String
    @ObservedObject var state: WebViewState
    /// 主题背景色（CSS 格式，如 "#FFFFFF"）
    let backgroundColor: String

func makeUIView(context: Context) -> WKWebView {
        let configuration = WKWebViewConfiguration()
        configuration.preferences.javaScriptEnabled = true

let webView = WKWebView(frame: .zero, configuration: configuration)
        webView.navigationDelegate = context.coordinator
        webView.scrollView.delegate = context.coordinator

// 设置透明背景，由 CSS 控制实际背景色
        webView.isOpaque = false
        let bgColor = UIColor(hexString: backgroundColor)
        webView.backgroundColor = bgColor
        webView.scrollView.backgroundColor = bgColor

// 禁用 WebView 的默认弹性效果
        webView.scrollView.bounces = false

// 保存引用
        state.webView = webView

// 加载初始内容
        webView.loadHTMLString(htmlContent, baseURL: nil)
        context.coordinator.lastHTML = htmlContent

return webView
    }

func updateUIView(_ webView: WKWebView, context: Context) {
        // 更新背景色
        let bgColor = UIColor(hexString: backgroundColor)
        webView.backgroundColor = bgColor
        webView.scrollView.backgroundColor = bgColor

// 只在内容变化时重新加载（避免不必要的刷新）
        if htmlContent != context.coordinator.lastHTML {
            webView.loadHTMLString(htmlContent, baseURL: nil)
            context.coordinator.lastHTML = htmlContent
        }
    }

func makeCoordinator() -> Coordinator {
        Coordinator()
    }

// MARK: - Coordinator

/// WKWebView 的代理对象
    /// 管理 HTML 内容的跟踪和页面加载完成后的回调
    final class Coordinator: NSObject, WKNavigationDelegate, UIScrollViewDelegate {
        /// 记录最后加载的 HTML，用于判断是否需要重新加载
        var lastHTML: String = ""

func webView(_ webView: WKWebView, didFinish navigation: WKNavigation!) {
            // 页面加载完成后更新分页信息
            webView.evaluateJavaScript("updatePageCount()")
        }

// MARK: - UIScrollViewDelegate

func scrollViewDidScroll(_ scrollView: UIScrollView) {
            // 可在此处处理滚动进度（未来扩展用）
        }
    }
}
```

上面这段代码有三个要点值得你注意：

第一，`WebViewState` 用 `weak` 弱引用持有 `WKWebView`。这是为了避免循环引用——SwiftUI 的视图持有 State，State 又持有 WebView，如果不用弱引用，内存就永远释放不了。

第二，`updateUIView` 里有一个关键的判断：`if htmlContent != context.coordinator.lastHTML`。SwiftUI 的特点是状态一变就会重新调用 `updateUIView`，但我们不想每次都重新加载整个网页（那样会闪一下）。所以我们用 `Coordinator` 记住上次加载的内容，只有真正变化时才重新加载。

第三，`Coordinator` 实现了 `WKNavigationDelegate`，在页面加载完成后立刻执行 JavaScript 函数 `updatePageCount()`。这是翻页模式的核心——JavaScript 负责计算总页数，Swift 负责触发翻页命令。

### ReaderViewModel：阅读器的大脑

有了渲染引擎，还需要一个"大脑"来管理状态：当前读的是哪本书？第几章？加载到哪了？这些逻辑都由 `ReaderViewModel` 统一管理。它被标记为 `@MainActor`，因为所有 UI 状态更新都必须在主线程完成。

? 项目文件：`FoxReader/ViewModels/ReaderViewModel.swift`

```swift
import Foundation
import SwiftUI
import Combine

/// 阅读器 ViewModel
/// 管理阅读状态：加载内容、章节导航、阅读进度
/// 支持 EPUB、Markdown、RSS 三种内容来源
@MainActor
final class ReaderViewModel: ObservableObject {
    /// 当前显示的原始 HTML 内容（未经 HTMLTemplates 包装）
    @Published var rawContent: String = ""
    @Published var title: String = ""
    @Published var chapters: [EPUBChapter] = []
    @Published var currentChapter: Int = 0
    @Published var totalChapters: Int = 0
    @Published var isLoading: Bool = false
    @Published var errorMessage: String?
    @Published var readProgress: Double = 0

private var currentBook: Book?

// MARK: - 加载内容

/// 加载图书
    /// 根据图书类型调用不同的解析逻辑
    func loadBook(_ book: Book) {
        currentBook = book
        title = book.title
        currentChapter = book.currentChapterIndex
        errorMessage = nil

switch book.bookType {
        case .epub:
            Task { await loadEPUB(book) }
        case .markdown:
            loadMarkdown(book)
        case .rss:
            break
        }
    }

/// 加载 RSS 文章
    func loadArticle(_ article: RSSArticle) {
        currentBook = nil
        title = article.title
        rawContent = article.displayContent
        totalChapters = 0
        currentChapter = 0
    }

// MARK: - EPUB 加载

private func loadEPUB(_ book: Book) async {
        isLoading = true

let url = URL(fileURLWithPath: book.fileURL)

// 在后台线程解析 EPUB，避免阻塞 UI
        let epubBook = await Task.detached(priority: .userInitiated) {
            await EPUBService.parseEPUB(at: url)
        }.value

isLoading = false

if let epubBook = epubBook {
            chapters = epubBook.chapters
            totalChapters = epubBook.chapters.count

// 加载当前章节内容
            if currentChapter < chapters.count {
                rawContent = chapters[currentChapter].htmlContent
            } else if !chapters.isEmpty {
                currentChapter = 0
                rawContent = chapters[0].htmlContent
            }
        } else {
            errorMessage = "无法解析 EPUB 文件，请确保已通过 SPM 添加 ZIPFoundation 依赖"
        }
    }

// MARK: - Markdown 加载

private func loadMarkdown(_ book: Book) {
        let url = URL(fileURLWithPath: book.fileURL)
        do {
            let content = try String(contentsOf: url, encoding: .utf8)
            rawContent = MarkdownService.convertToHTML(content)
            totalChapters = 1
        } catch {
            errorMessage = "无法读取文件：\(error.localizedDescription)"
        }
    }

// MARK: - 章节导航

/// 加载指定章节
    func loadChapter(at index: Int) {
        guard index >= 0 && index < chapters.count else { return }
        currentChapter = index
        rawContent = chapters[index].htmlContent
        updateProgress()
    }

/// 下一章
    func nextChapter() {
        guard currentChapter < chapters.count - 1 else { return }
        loadChapter(at: currentChapter + 1)
    }

/// 上一章
    func previousChapter() {
        guard currentChapter > 0 else { return }
        loadChapter(at: currentChapter - 1)
    }

/// 是否有下一章
    var hasNextChapter: Bool {
        currentChapter < chapters.count - 1
    }

/// 是否有上一章
    var hasPreviousChapter: Bool {
        currentChapter > 0
    }

// MARK: - 阅读进度

/// 更新阅读进度
    private func updateProgress() {
        guard totalChapters > 0 else {
            readProgress = 0
            return
        }
        readProgress = Double(currentChapter + 1) / Double(totalChapters)
    }

/// 保存阅读进度到 Book 对象
    func saveProgress(to book: Book) {
        book.lastReadDate = Date()
        book.currentChapterIndex = currentChapter
        book.readProgress = readProgress
    }
}
```

注意 `loadEPUB` 方法中用到了 `Task.detached`。EPUB 解压和 XML 解析是 CPU 密集型操作，如果在主线程执行会卡住 UI。`Task.detached` 把它扔到后台线程，解析完再回到主线程更新 `@Published` 属性。

而 `saveProgress` 方法则体现了 SwiftData 的便利——直接修改 `Book` 对象的属性即可，不用写 SQL，不用手动持久化，上下文会处理一切。

### ReaderView：把一切组合在一起

现在我们有了渲染引擎（WebViewContainer）和大脑（ReaderViewModel），还需要一个"身体"把它们组合起来。`ReaderView` 就是这个身体，它同时支持 `Book`（本地图书）和 `RSSArticle`（网络文章）两种内容来源。

? 项目文件：`FoxReader/Views/Reader/ReaderView.swift`

```swift
import SwiftUI
import SwiftData

/// 统一阅读器视图
/// 支持显示 Book（EPUB/Markdown）和 RSSArticle 内容
/// 通过 WebViewContainer 渲染 HTML 内容，通过 HTMLTemplates 应用阅读样式
struct ReaderView: View {
    var book: Book? = nil
    var article: RSSArticle? = nil

@EnvironmentObject var readerSettings: ReaderSettings
    @Environment(\.modelContext) var modelContext
    @Environment(\.dismiss) var dismiss

@StateObject private var viewModel = ReaderViewModel()
    @StateObject private var webViewState = WebViewState()

@State private var showSettings = false

var body: some View {
        ZStack {
            // 主题背景色
            readerSettings.theme.backgroundColor
                .ignoresSafeArea()

// 主内容区
            VStack(spacing: 0) {
                contentArea

// EPUB 章节导航栏
                if viewModel.totalChapters > 1 {
                    chapterNavigationBar
                }
            }
        }
        .navigationTitle(viewModel.title)
        .navigationBarTitleDisplayMode(.inline)
        .toolbar {
            // 章节列表（仅 EPUB）
            if viewModel.totalChapters > 1 {
                ToolbarItem(placement: .topBarLeading) {
                    Menu {
                        ForEach(0..<viewModel.totalChapters, id: \.self) { index in
                            Button("第 \(index + 1) 章") {
                                viewModel.loadChapter(at: index)
                            }
                        }
                    } label: {
                        Image(systemName: "list.bullet")
                    }
                }
            }

// 阅读设置按钮
            ToolbarItem(placement: .topBarTrailing) {
                Button {
                    showSettings = true
                } label: {
                    Image(systemName: "textformat.size")
                }
            }
        }
        .toolbarBackground(readerSettings.theme.backgroundColor, for: .navigationBar)
        .toolbarBackground(.visible, for: .navigationBar)
        .toolbarColorScheme(
            readerSettings.theme == .dark || readerSettings.theme == .night ? .dark : .light,
            for: .navigationBar
        )
        .onAppear {
            loadContent()
        }
        .onDisappear {
            saveProgress()
        }
        .sheet(isPresented: $showSettings) {
            ReaderSettingsBar()
                .environmentObject(readerSettings)
                .presentationDetents([.medium, .large])
        }
    }

// MARK: - 内容区域

@ViewBuilder
    private var contentArea: some View {
        if viewModel.isLoading {
            // 加载中
            ProgressView("加载中...")
                .frame(maxWidth: .infinity, maxHeight: .infinity)
        } else if let error = viewModel.errorMessage {
            // 错误状态
            VStack(spacing: 16) {
                Image(systemName: "exclamationmark.triangle.fill")
                    .font(.system(size: 48))
                    .foregroundStyle(.orange)
                Text(error)
                    .multilineTextAlignment(.center)
                    .foregroundStyle(.secondary)
                if error.contains("ZIPFoundation") {
                    Text("请在 Xcode 中通过 SPM 添加 ZIPFoundation 依赖")
                        .font(.caption)
                        .foregroundStyle(.tertiary)
                }
            }
            .padding()
            .frame(maxWidth: .infinity, maxHeight: .infinity)
        } else if !viewModel.rawContent.isEmpty {
            // 正常显示内容
            let wrappedHTML = HTMLTemplates.wrapContent(viewModel.rawContent, settings: readerSettings)

WebViewContainer(
                htmlContent: wrappedHTML,
                state: webViewState,
                backgroundColor: readerSettings.theme.cssBackgroundColor
            )
            .overlay {
                // 翻页模式下的点击翻页区域
                if readerSettings.pageMode == .paginated {
                    paginatedTapZones
                }
            }
        } else {
            // 空内容
            Text("暂无内容")
                .foregroundStyle(.secondary)
                .frame(maxWidth: .infinity, maxHeight: .infinity)
        }
    }

// MARK: - 翻页点击区域

/// 翻页模式下，点击屏幕左右两侧进行翻页
    private var paginatedTapZones: some View {
        HStack(spacing: 0) {
            // 左侧点击区域：上一页
            Color.clear
                .contentShape(Rectangle())
                .onTapGesture { webViewState.previousPage() }
                .frame(maxWidth: .infinity)

// 中间区域（不响应点击，避免误触）
            Color.clear
                .frame(width: 100)

// 右侧点击区域：下一页
            Color.clear
                .contentShape(Rectangle())
                .onTapGesture { webViewState.nextPage() }
                .frame(maxWidth: .infinity)
        }
    }

// MARK: - 章节导航栏

private var chapterNavigationBar: some View {
        HStack {
            Button {
                viewModel.previousChapter()
            } label: {
                Image(systemName: "chevron.left")
                    .font(.title3)
            }
            .disabled(!viewModel.hasPreviousChapter)
            .foregroundStyle(viewModel.hasPreviousChapter ? readerSettings.theme.textColor : .gray.opacity(0.3))

Spacer()

Text("\(viewModel.currentChapter + 1) / \(viewModel.totalChapters)")
                .font(.caption)
                .foregroundStyle(readerSettings.theme.textColor.opacity(0.6))

Spacer()

Button {
                viewModel.nextChapter()
            } label: {
                Image(systemName: "chevron.right")
                    .font(.title3)
            }
            .disabled(!viewModel.hasNextChapter)
            .foregroundStyle(viewModel.hasNextChapter ? readerSettings.theme.textColor : .gray.opacity(0.3))
        }
        .padding(.horizontal, 24)
        .padding(.vertical, 10)
        .background(readerSettings.theme.backgroundColor.opacity(0.95))
    }

// MARK: - 数据加载

private func loadContent() {
        if let book = book {
            viewModel.loadBook(book)
        } else if let article = article {
            viewModel.loadArticle(article)
        }
    }

// MARK: - 进度保存

private func saveProgress() {
        if let book = book {
            viewModel.saveProgress(to: book)
            try? modelContext.save()
        }
    }
}
```

这段代码展示了三个重要的设计思路：

第一是**翻页点击区域**。在翻页模式下，屏幕被分成三部分：左侧点击翻到上一页，右侧点击翻到下一页，中间 100 点宽度留空（避免误触）。这些区域用 `Color.clear` + `contentShape` 实现——透明的颜色本来不接收点击事件，但加上 `contentShape(Rectangle())` 后就变成了一个隐形的可点击矩形。

第二是**环境对象的传递**。`readerSettings` 通过 `@EnvironmentObject` 注入，当用户在设置面板修改主题或字体后，整个阅读器界面会自动刷新。注意 `.sheet` 弹出的 `ReaderSettingsBar` 也调用了 `.environmentObject(readerSettings)`，确保设置面板内部能访问到同一个设置实例。

第三是**工具栏自适应**。当有多章节时（EPUB），左侧显示章节目录菜单；单章节时（Markdown）则不显示。导航栏背景色和配色方案会根据当前主题动态调整，保证暗色主题下标题依然清晰可见。

### ReaderSettingsBar：阅读设置面板

最后来看设置面板。它以底部 Sheet 的形式弹出，让用户在阅读时随时调整主题、字体大小、字体类型和翻页方式。

? 项目文件：`FoxReader/Views/Reader/ReaderSettingsBar.swift`

```swift
import SwiftUI

/// 阅读设置面板
/// 以底部 Sheet 形式弹出，提供主题切换、字体大小、字体类型、翻页方式设置
/// 通过 @EnvironmentObject 访问 ReaderSettings，修改后自动持久化到 UserDefaults
struct ReaderSettingsBar: View {
    @EnvironmentObject var readerSettings: ReaderSettings
    @Environment(\.dismiss) var dismiss

var body: some View {
        NavigationStack {
            ScrollView {
                VStack(spacing: 28) {
                    // 主题选择
                    settingsSection("阅读主题") {
                        HStack(spacing: 20) {
                            ForEach(ReaderTheme.allCases, id: \.self) { theme in
                                themeButton(theme)
                            }
                        }
                    }

// 字体大小
                    settingsSection("字体大小") {
                        HStack(spacing: 20) {
                            Button {
                                decreaseFontSize()
                            } label: {
                                Image(systemName: "minus.circle.fill")
                                    .font(.title2)
                            }

Text("\(Int(readerSettings.fontSize)) pt")
                                .font(.body.monospacedDigit())
                                .frame(width: 70)

Button {
                                increaseFontSize()
                            } label: {
                                Image(systemName: "plus.circle.fill")
                                    .font(.title2)
                            }
                        }
                    }

// 字体类型
                    settingsSection("字体类型") {
                        HStack(spacing: 12) {
                            ForEach(ReaderFont.allCases, id: \.self) { font in
                                fontButton(font)
                            }
                        }
                    }

// 翻页方式
                    settingsSection("翻页方式") {
                        HStack(spacing: 12) {
                            ForEach(PageMode.allCases, id: \.self) { mode in
                                pageModeButton(mode)
                            }
                        }
                    }
                }
                .padding()
            }
            .navigationTitle("阅读设置")
            .navigationBarTitleDisplayMode(.inline)
            .toolbar {
                ToolbarItem(placement: .topBarTrailing) {
                    Button("完成") { dismiss() }
                }
            }
        }
        .presentationDetents([.medium, .large])
        .presentationDragIndicator(.visible)
    }

// MARK: - 设置区块

@ViewBuilder
    private func settingsSection<Content: View>(
        _ title: String,
        @ViewBuilder content: () -> Content
    ) -> some View {
        VStack(alignment: .leading, spacing: 12) {
            Text(title)
                .font(.headline)
            HStack {
                Spacer()
                content()
                Spacer()
            }
        }
    }

// MARK: - 主题按钮

private func themeButton(_ theme: ReaderTheme) -> some View {
        let isSelected = readerSettings.theme == theme
        return Button {
            readerSettings.theme = theme
        } label: {
            VStack(spacing: 6) {
                Circle()
                    .fill(theme.backgroundColor)
                    .frame(width: 44, height: 44)
                    .overlay {
                        Circle()
                            .stroke(
                                isSelected ? Color.accentColor : Color.gray.opacity(0.3),
                                lineWidth: isSelected ? 3 : 1
                            )
                    }
                    .overlay {
                        Image(systemName: theme.iconName)
                            .font(.caption)
                            .foregroundStyle(theme.textColor)
                    }
                Text(theme.displayName)
                    .font(.caption)
                    .foregroundStyle(isSelected ? Color.accentColor : .primary)
            }
        }
    }

// MARK: - 字体按钮

private func fontButton(_ font: ReaderFont) -> some View {
        let isSelected = readerSettings.fontFamily == font
        return Button {
            readerSettings.fontFamily = font
        } label: {
            HStack(spacing: 6) {
                Image(systemName: font.iconName)
                Text(font.displayName)
            }
            .font(.subheadline)
            .padding(.horizontal, 16)
            .padding(.vertical, 10)
            .background {
                if isSelected {
                    Capsule().fill(Color.accentColor.opacity(0.15))
                } else {
                    Capsule().fill(Color.gray.opacity(0.1))
                }
            }
            .foregroundStyle(isSelected ? Color.accentColor : .primary)
        }
    }

// MARK: - 翻页模式按钮

private func pageModeButton(_ mode: PageMode) -> some View {
        let isSelected = readerSettings.pageMode == mode
        return Button {
            readerSettings.pageMode = mode
        } label: {
            HStack(spacing: 6) {
                Image(systemName: mode.iconName)
                Text(mode.displayName)
            }
            .font(.subheadline)
            .padding(.horizontal, 16)
            .padding(.vertical, 10)
            .background {
                if isSelected {
                    Capsule().fill(Color.accentColor.opacity(0.15))
                } else {
                    Capsule().fill(Color.gray.opacity(0.1))
                }
            }
            .foregroundStyle(isSelected ? Color.accentColor : .primary)
        }
    }

// MARK: - 字体大小调整

private func increaseFontSize() {
        readerSettings.fontSize = min(readerSettings.fontSize + 1, 28)
    }

private func decreaseFontSize() {
        readerSettings.fontSize = max(readerSettings.fontSize - 1, 12)
    }
}
```

这个面板有两个设计亮点：

第一是 `settingsSection` 泛型辅助方法。它接受一个标题字符串和一个 `@ViewBuilder` 闭包，统一了每个设置区块的布局（标题在左，内容居中）。这种模式在 SwiftUI 中非常常见——把重复的布局逻辑提取成一个方法，既减少代码量又保证视觉一致性。

第二是 `.presentationDetents([.medium, .large])`。这让 Sheet 可以停留在半屏或全屏两个位置，用户可以向上拖动展开更多内容。配合 `.presentationDragIndicator(.visible)`，顶部会显示一个小横条作为拖动手柄的视觉提示。

### 临时占位代码（确保项目可编译）

本章的 `ReaderViewModel` 和 `ReaderView` 引用了几个后续章节才定义的类型：`EPUBChapter`、`EPUBBook`、`EPUBService`（第八章）、`MarkdownService`（第七章）、`RSSArticle`（第九章）。为了让你在本章结束时就能编译运行阅读器，请将以下占位代码**追加到** `Stubs.swift` 文件中：

> ? 项目文件：`FoxReader/Stubs.swift`（追加以下代码）

```swift
// ─── 第七章将替换 ───
struct MarkdownService {
    /// 简单占位：直接返回段落标签包裹的文本
    static func convertToHTML(_ markdown: String) -> String {
        "<p>\(markdown)</p>"
    }
}

// ─── 第八章将替换 ───
struct EPUBChapter {
    let htmlContent: String
}

struct EPUBBook {
    let title: String
    let author: String
    let coverImageData: Data?
    let chapters: [EPUBChapter]
}

struct EPUBService {
    /// 占位：返回 nil，第八章实现完整解析
    static func parseEPUB(at url: URL) -> EPUBBook? {
        nil
    }
}

// ─── 第九章将替换 ───
struct RSSArticle: Identifiable, Hashable {
    let id: UUID
    let title: String
    let link: String
    let summary: String
    let content: String
    let publishDate: Date?
    let author: String?

/// 获取用于显示的 HTML 内容
    var displayContent: String {
        content.isEmpty ? summary : content
    }

init(id: UUID = UUID(), title: String = "", link: String = "",
         summary: String = "", content: String = "",
         publishDate: Date? = nil, author: String? = nil) {
        self.id = id
        self.title = title
        self.link = link
        self.summary = summary
        self.content = content
        self.publishDate = publishDate
        self.author = author
    }
}
```

> **提示**：这些占位类型提供了阅读器编译所需的最小接口。`MarkdownService` 会简单地把文本包裹在 `<p>` 标签中，`EPUBService.parseEPUB` 会返回 `nil`（即 EPUB 解析不可用），`RSSArticle` 提供了 `displayContent` 计算属性。在后续章节中，这些占位将被完整实现替换。

现在编译项目（**Cmd+B**），应该能成功通过。你可以尝试导入一个 Markdown 文件，阅读器会以基础格式显示其内容。

---

## 第六章：书架与图书管理

> **替换占位代码**：在开始本章之前，请打开 `Stubs.swift` 文件，删除 `LibraryView` 占位类型。本章将创建它的完整实现。注意：`EPUBService` 和 `EPUBBook` 仍为占位状态（在第五章添加），将在第八章替换。

每本好书都需要一个好书架。在 FoxReader 中，书架是用户打开 App 后看到的第一个界面——就像你走进家里的书房，一眼看到整齐排列的书本。这一章我们来看看书架是如何构建的，以及图书是如何从用户的文件系统"搬"到 App 里的。

### @Query：SwiftData 的智能搜索

SwiftData 提供了一个非常强大的宏 `@Query`。它就像一个不知疲倦的图书管理员——你告诉他"按添加日期倒序排列所有书"，他就会一直守在那里，每当书架有变化（添加新书、删除旧书），他都会自动刷新列表，你完全不用手动管理。

? 项目文件：`FoxReader/Views/Library/LibraryView.swift`

```swift
import SwiftUI
import SwiftData

struct LibraryView: View {
    @Query(sort: \Book.addedDate, order: .reverse) var books: [Book]
    @Environment(\.modelContext) var modelContext
    @EnvironmentObject var readerSettings: ReaderSettings
    @StateObject private var viewModel = LibraryViewModel()
    @State private var showImportPicker = false

var body: some View {
        NavigationStack {
            Group {
                if books.isEmpty {
                    EmptyStateView(
                        icon: "books.vertical",
                        title: "书架空空如也",
                        subtitle: "点击右上角导入按钮添加图书",
                        actionTitle: "导入图书",
                        action: { showImportPicker = true }
                    )
                } else {
                    ScrollView {
                        LazyVGrid(columns: gridColumns, spacing: 20) {
                            ForEach(books) { book in
                                NavigationLink(value: book) {
                                    BookCardView(book: book)
                                }
                                .contextMenu {
                                    Button("删除", role: .destructive) {
                                        viewModel.deleteBook(book, context: modelContext)
                                    }
                                }
                            }
                        }
                        .padding()
                    }
                }
            }
            .navigationTitle("书架")
            .toolbar {
                ToolbarItem(placement: .topBarTrailing) {
                    Button { showImportPicker = true } label: {
                        Image(systemName: "plus")
                    }
                }
            }
            .navigationDestination(for: Book.self) { book in
                ReaderView(book: book)
                    .environmentObject(readerSettings)
            }
            .sheet(isPresented: $showImportPicker) {
                DocumentPickerView { url in
                    viewModel.importBook(at: url, context: modelContext)
                }
            }
            .alert("提示", isPresented: $viewModel.showError) {
                Button("确定", role: .cancel) {}
            } message: {
                Text(viewModel.errorMessage ?? "")
            }
        }
    }

private var gridColumns: [GridItem] {
        [GridItem(.adaptive(minimum: 160), spacing: 16)]
    }
}
```

注意 `@Query(sort: \Book.addedDate, order: .reverse)` 这一行。`@Query` 会自动监听数据库变化——当你通过 `modelContext.insert()` 添加新书后，`books` 数组会自动更新，UI 也会自动刷新。这比传统的 Core Data + NSFetchedResultsController 简洁太多了。

另一个细节是 `NavigationLink(value: book)` 配合 `.navigationDestination(for: Book.self)`。这是 SwiftUI 4.0 引入的类型安全导航方式——你把 `Book` 作为导航值传递，SwiftUI 会根据类型自动找到对应的目标视图，避免了旧版 `NavigationLink(destination:)` 那种紧耦合的写法。

### BookCardView：书的封面

每本书在书架上以卡片形式展示。如果有封面图片就显示图片，没有则用渐变背景和图标代替。

? 项目文件：`FoxReader/Views/Library/BookCardView.swift`

```swift
import SwiftUI
import UIKit

struct BookCardView: View {
    let book: Book

var body: some View {
        VStack(alignment: .leading, spacing: 8) {
            coverView
                .frame(width: 160, height: 220)
                .clipShape(RoundedRectangle(cornerRadius: 12))
                .shadow(color: .black.opacity(0.15), radius: 5, y: 3)

Text(book.title)
                .font(.subheadline)
                .lineLimit(2)
                .foregroundStyle(.primary)

Text(book.author)
                .font(.caption)
                .foregroundStyle(.secondary)
                .lineLimit(1)

if book.readProgress > 0 {
                ProgressView(value: book.readProgress)
                    .tint(.accentColor)
            }
        }
        .frame(width: 160)
    }

@ViewBuilder
    private var coverView: some View {
        if let coverData = book.coverImageData,
           let uiImage = UIImage(data: coverData) {
            Image(uiImage: uiImage)
                .resizable()
                .aspectRatio(contentMode: .fill)
        } else {
            ZStack {
                LinearGradient(
                    colors: [Color(hex: "667eea"), Color(hex: "764ba2")],
                    startPoint: .topLeading,
                    endPoint: .bottomTrailing
                )
                VStack(spacing: 8) {
                    Image(systemName: book.bookType.iconName)
                        .font(.system(size: 32))
                        .foregroundStyle(.white.opacity(0.9))
                    Text(book.bookType.displayName)
                        .font(.caption)
                        .foregroundStyle(.white.opacity(0.7))
                    Text(book.title.prefix(6))
                        .font(.caption2)
                        .foregroundStyle(.white.opacity(0.5))
                        .lineLimit(1)
                }
            }
        }
    }
}
```

封面卡片底部有一个阅读进度条 `ProgressView(value: book.readProgress)`。只有当 `readProgress > 0` 时才显示，这样还没读过的书不会显示一个空的进度条。这是个很小的细节，但对用户体验很重要——清晰的视觉反馈远比一堆空状态元素要舒服。

### DocumentPickerView：文件选择器

SwiftUI 同样没有原生的文件选择器。我们需要用 `UIViewControllerRepresentable` 来桥接 UIKit 的 `UIDocumentPickerViewController`。这个模式和上一章的 `UIViewRepresentable` 几乎一样，只是把 `UIView` 换成了 `UIViewController`。

? 项目文件：`FoxReader/Views/Components/DocumentPickerView.swift`

```swift
import SwiftUI
import UniformTypeIdentifiers

struct DocumentPickerView: UIViewControllerRepresentable {
    var onPick: (URL) -> Void

func makeUIViewController(context: Context) -> UIDocumentPickerViewController {
        let epubType = UTType(importedAs: "org.idpf.epub-container")
        let markdownType = UTType(importedAs: "net.daringfireball.markdown")
        let types: [UTType] = [epubType, markdownType, .plainText, .text]
        let picker = UIDocumentPickerViewController(forOpeningContentTypes: types)
        picker.allowsMultipleSelection = false
        picker.delegate = context.coordinator
        return picker
    }

func updateUIViewController(_ uiViewController: UIDocumentPickerViewController, context: Context) {}

func makeCoordinator() -> Coordinator {
        Coordinator(self)
    }

final class Coordinator: NSObject, UIDocumentPickerDelegate {
        let parent: DocumentPickerView

init(_ parent: DocumentPickerView) {
            self.parent = parent
        }

func documentPicker(_ controller: UIDocumentPickerViewController, didPickDocumentsAt urls: [URL]) {
            if let url = urls.first {
                parent.onPick(url)
            }
        }

func documentPickerWasCancelled(_ controller: UIDocumentPickerViewController) {}
    }
}
```

这里用到了 `UTType`（Uniform Type Identifiers）来指定可选择的文件类型。EPUB 的类型标识符是 `org.idpf.epub-container`，这是国际数字出版论坛（IDPF）定义的标准。`plainText` 和 `text` 则覆盖了 `.txt` 和 `.md` 文件。

`Coordinator` 持有一个对 `parent`（即 SwiftUI 视图本身）的引用，当用户选好文件后，通过闭包 `onPick(url)` 把结果传回 SwiftUI 世界。

### EmptyStateView：空状态提示

当书架还没有任何书时，一个友好的空状态视图比一片空白要好得多。

? 项目文件：`FoxReader/Views/Components/EmptyStateView.swift`

```swift
import SwiftUI

struct EmptyStateView: View {
    let icon: String
    let title: String
    let subtitle: String
    var actionTitle: String? = nil
    var action: (() -> Void)? = nil

var body: some View {
        VStack(spacing: 16) {
            Image(systemName: icon)
                .font(.system(size: 56))
                .foregroundStyle(.secondary.opacity(0.4))

Text(title)
                .font(.title3)
                .foregroundStyle(.secondary)

Text(subtitle)
                .font(.subheadline)
                .foregroundStyle(.tertiary)
                .multilineTextAlignment(.center)

if let actionTitle = actionTitle, let action = action {
                Button(actionTitle, action: action)
                    .buttonStyle(.borderedProminent)
                    .padding(.top, 8)
            }
        }
        .padding(40)
        .frame(maxWidth: .infinity, maxHeight: .infinity)
    }
}
```

这个组件是通用的——`icon`、`title`、`subtitle` 都是外部传入的参数，`actionTitle` 和 `action` 是可选的。这意味着你可以在 App 的任何地方复用它：书架为空、搜索无结果、网络错误等场景，都能用同一个组件展示不同的内容。

### LibraryViewModel：书架的业务逻辑

书架的 UI 是 `LibraryView`，但导入和删除的具体逻辑被抽到了 `LibraryViewModel` 里。这种分离让代码更清晰，也让 ViewModel 更容易测试。

? 项目文件：`FoxReader/ViewModels/LibraryViewModel.swift`

```swift
import Foundation
import SwiftData
import SwiftUI
import Combine

/// 书架 ViewModel
/// 管理图书导入、删除等业务逻辑
/// 通过 ModelContext 参数与 SwiftData 交互，保持 ViewModel 的可测试性
@MainActor
final class LibraryViewModel: ObservableObject {
    @Published var showImportPicker = false
    @Published var errorMessage: String?
    @Published var showError = false

/// 导入图书文件
    /// - Parameters:
    ///   - url: 用户选择的文件 URL
    ///   - context: SwiftData ModelContext（由视图注入）
    func importBook(at url: URL, context: ModelContext) {
        if let book = BookImportService.importFile(at: url) {
            context.insert(book)
            do {
                try context.save()
            } catch {
                showError(message: "保存失败：\(error.localizedDescription)")
            }
        } else {
            showError(message: "不支持的文件格式，仅支持 EPUB 和 Markdown 文件")
        }
    }

/// 删除图书
    /// - Parameters:
    ///   - book: 要删除的 Book 对象
    ///   - context: SwiftData ModelContext
    func deleteBook(_ book: Book, context: ModelContext) {
        // 同时删除本地文件
        let fileURL = URL(fileURLWithPath: book.fileURL)
        try? FileManager.default.removeItem(at: fileURL)

context.delete(book)
        do {
            try context.save()
        } catch {
            showError(message: "删除失败：\(error.localizedDescription)")
        }
    }

private func showError(message: String) {
        errorMessage = message
        showError = true
    }
}
```

注意 `importBook` 和 `deleteBook` 方法都接收 `ModelContext` 作为参数，而不是在 ViewModel 内部获取。这是一种依赖注入的设计——ViewModel 不关心数据从哪来，它只负责处理逻辑。这样在写单元测试时，你可以传入一个内存数据库的 context 来测试，完全不用碰真实文件系统。

### BookImportService：文件搬运工

当用户选择了一个文件后，这个文件并不属于 App——它在 iOS 的安全沙盒之外。`BookImportService` 的职责就是把文件"搬"进 App 自己的 Documents 目录，然后创建对应的 `Book` 对象。

? 项目文件：`FoxReader/Services/BookImportService.swift`

```swift
import Foundation

/// 图书导入服务
/// 协调不同格式的图书导入流程，将文件复制到 App 沙盒目录并创建 Book 对象
struct BookImportService {

/// 导入文件，根据扩展名自动判断类型
    /// - Parameter sourceURL: 用户选择的文件 URL（通常来自 Document Picker）
    /// - Returns: 创建好的 Book 对象，如果格式不支持则返回 nil
    static func importFile(at sourceURL: URL) -> Book? {
        let ext = sourceURL.pathExtension.lowercased()

switch ext {
        case "epub":
            return importEPUB(at: sourceURL)
        case "md", "markdown", "txt":
            return importMarkdown(at: sourceURL)
        default:
            return nil
        }
    }

/// 导入 EPUB 文件
    private static func importEPUB(at sourceURL: URL) -> Book? {
        // 复制文件到沙盒
        guard let destURL = copyToDocuments(from: sourceURL) else { return nil }

// 解析 EPUB 获取元数据
        if let epubBook = EPUBService.parseEPUB(at: destURL) {
            return Book(
                title: epubBook.title,
                author: epubBook.author,
                bookType: .epub,
                fileURL: destURL.path,
                coverImageData: epubBook.coverImageData,
                totalChapters: epubBook.chapters.count
            )
        }

// 解析失败时仍然创建 Book（可能未安装 ZIPFoundation）
        let title = sourceURL.deletingPathExtension().lastPathComponent
        return Book(
            title: title,
            bookType: .epub,
            fileURL: destURL.path
        )
    }

/// 导入 Markdown 文件
    private static func importMarkdown(at sourceURL: URL) -> Book? {
        guard let destURL = copyToDocuments(from: sourceURL) else { return nil }

let title = sourceURL.deletingPathExtension().lastPathComponent

return Book(
            title: title,
            bookType: .markdown,
            fileURL: destURL.path,
            totalChapters: 1
        )
    }

/// 将文件复制到 App 的 Documents 目录
    /// 返回复制后的目标 URL，如果失败返回 nil
    private static func copyToDocuments(from sourceURL: URL) -> URL? {
        let fileManager = FileManager.default

guard let documentsDir = fileManager.urls(for: .documentDirectory, in: .userDomainMask).first else {
            return nil
        }

// 生成唯一文件名避免冲突
        let fileName = "\(UUID().uuidString)_\(sourceURL.lastPathComponent)"
        let destURL = documentsDir.appendingPathComponent(fileName)

// 访问安全域资源（iOS Document Picker 返回的 URL 需要安全域访问权限）
        let didAccess = sourceURL.startAccessingSecurityScopedResource()
        defer {
            if didAccess {
                sourceURL.stopAccessingSecurityScopedResource()
            }
        }

// 如果目标文件已存在则先删除
        if fileManager.fileExists(atPath: destURL.path) {
            try? fileManager.removeItem(at: destURL)
        }

do {
            try fileManager.copyItem(at: sourceURL, to: destURL)
            return destURL
        } catch {
            return nil
        }
    }

/// 获取 App Documents 目录路径
    static var documentsDirectory: URL? {
        FileManager.default.urls(for: .documentDirectory, in: .userDomainMask).first
    }
}
```

这段代码里有一个非常关键的概念：**安全域资源访问**（Security-Scoped Resource）。iOS 的文件系统是严格沙盒化的，用户通过 Document Picker 选择的文件返回的 URL 是一个"安全域" URL——你必须调用 `startAccessingSecurityScopedResource()` 才能读取它，用完之后必须调用 `stopAccessingSecurityScopedResource()` 释放权限。代码中用 `defer` 确保无论如何都会释放，这是一个好习惯。

另一个要点是文件名的生成：`\(UUID().uuidString)_\(sourceURL.lastPathComponent)`。UUID 前缀确保即使导入两个同名文件也不会冲突。文件复制到 Documents 目录后，App 就拥有了完全的读写权限，后续读取不再需要安全域访问。

---

## 第七章：Markdown 解析与阅读

> **替换占位代码**：在开始本章之前，请打开 `Stubs.swift` 文件，删除 `MarkdownService` 占位类型。本章将创建它的完整实现。

Markdown 是一种轻量级标记语言，用简单的符号就能写出格式丰富的文本。比如 `**粗体**` 变成粗体，`# 标题` 变成一级标题。它在技术文档、博客、笔记领域非常流行。FoxReader 支持直接导入 `.md` 文件并渲染成漂亮的阅读界面。

### 自己动手写解析器

市面上有很多成熟的 Markdown 解析库，但我们选择自己实现一个。这不仅仅是为了减少依赖，更重要的是——理解一个解析器是怎么工作的，本身就是非常好的编程练习。

打个比方，这就像教一个人把英文翻译成中文。你不需要翻译每一句话，你只需要告诉它规则：看到 "Hello" 就翻译成"你好"，看到 "Thank you" 就翻译成"谢谢"。Markdown 解析器也是一样的思路：看到 `#` 就变成 `<h1>`，看到 `**` 就变成 `<strong>`。

我们的解析策略分两个层次：

- **块级元素**：逐行扫描，识别标题、列表、引用、代码块等。这些元素独占一行或多行。
- **行内元素**：在一行文字内部，用正则表达式替换粗体、斜体、链接、图片等。

? 项目文件：`FoxReader/Services/MarkdownService.swift`

```swift
import Foundation

/// Markdown 转 HTML 转换器
/// 实现一个轻量级的 Markdown 解析器，支持常用语法
/// 无需第三方依赖，纯 Foundation 实现
struct MarkdownService {

// MARK: - 公开方法

/// 将 Markdown 文本转换为 HTML
    /// - Parameter markdown: Markdown 原始文本
    /// - Returns: HTML 字符串（不含 html/head/body 标签，仅正文）
    static func convertToHTML(_ markdown: String) -> String {
        var result = ""
        var inCodeBlock = false
        var codeBlockContent = ""
        var inUnorderedList = false
        var inOrderedList = false
        var inBlockquote = false
        var paragraphBuffer = ""

let lines = markdown.components(separatedBy: .newlines)

for line in lines {
            // 代码块处理
            if line.trimmingCharacters(in: .whitespaces).hasPrefix("```") {
                if inCodeBlock {
                    // 结束代码块
                    result += "<pre><code>\(escapeHTML(codeBlockContent.trimmingCharacters(in: .newlines)))</code></pre>\n"
                    codeBlockContent = ""
                    inCodeBlock = false
                } else {
                    // 开始代码块 - 先关闭其他元素
                    flushParagraph(¶graphBuffer, &result)
                    closeLists(&inUnorderedList, &inOrderedList, &result)
                    closeBlockquote(&inBlockquote, &result)
                    inCodeBlock = true
                }
                continue
            }

if inCodeBlock {
                codeBlockContent += line + "\n"
                continue
            }

let trimmed = line.trimmingCharacters(in: .whitespaces)

// 空行 - 段落分隔
            if trimmed.isEmpty {
                flushParagraph(¶graphBuffer, &result)
                closeLists(&inUnorderedList, &inOrderedList, &result)
                closeBlockquote(&inBlockquote, &result)
                continue
            }

// 标题处理
            if let headingHTML = parseHeading(trimmed) {
                flushParagraph(¶graphBuffer, &result)
                closeLists(&inUnorderedList, &inOrderedList, &result)
                closeBlockquote(&inBlockquote, &result)
                result += headingHTML + "\n"
                continue
            }

// 水平分割线
            if isHorizontalRule(trimmed) {
                flushParagraph(¶graphBuffer, &result)
                closeLists(&inUnorderedList, &inOrderedList, &result)
                closeBlockquote(&inBlockquote, &result)
                result += "<hr>\n"
                continue
            }

// 引用块
            if trimmed.hasPrefix(">") {
                flushParagraph(¶graphBuffer, &result)
                closeLists(&inUnorderedList, &inOrderedList, &result)
                if !inBlockquote {
                    result += "<blockquote>\n"
                    inBlockquote = true
                }
                let quoteContent = String(trimmed.dropFirst()).trimmingCharacters(in: .whitespaces)
                result += "<p>\(processInline(quoteContent))</p>\n"
                continue
            } else {
                closeBlockquote(&inBlockquote, &result)
            }

// 无序列表
            if trimmed.hasPrefix("- ") || trimmed.hasPrefix("* ") || trimmed.hasPrefix("+ ") {
                flushParagraph(¶graphBuffer, &result)
                closeOrderedList(&inOrderedList, &result)
                if !inUnorderedList {
                    result += "<ul>\n"
                    inUnorderedList = true
                }
                let itemContent = String(trimmed.dropFirst(2))
                result += "<li>\(processInline(itemContent))</li>\n"
                continue
            }

// 有序列表
            if let match = trimmed.range(of: #"^\d+\.\s"#, options: .regularExpression) {
                flushParagraph(¶graphBuffer, &result)
                closeUnorderedList(&inUnorderedList, &result)
                if !inOrderedList {
                    result += "<ol>\n"
                    inOrderedList = true
                }
                let itemContent = String(trimmed[match.upperBound...])
                result += "<li>\(processInline(itemContent))</li>\n"
                continue
            }

// 关闭列表（如果当前行不是列表项）
            closeLists(&inUnorderedList, &inOrderedList, &result)

// 普通段落
            if paragraphBuffer.isEmpty {
                paragraphBuffer = processInline(trimmed)
            } else {
                paragraphBuffer += " " + processInline(trimmed)
            }
        }

// 处理最后的未关闭元素
        flushParagraph(¶graphBuffer, &result)
        closeLists(&inUnorderedList, &inOrderedList, &result)
        closeBlockquote(&inBlockquote, &result)
        if inCodeBlock {
            result += "<pre><code>\(escapeHTML(codeBlockContent))</code></pre>\n"
        }

return result
    }

// MARK: - 内部方法

/// 解析标题行
    private static func parseHeading(_ line: String) -> String? {
        let headings: [(String, Int)] = [
            ("###### ", 6), ("##### ", 5), ("#### ", 4),
            ("### ", 3), ("## ", 2), ("# ", 1)
        ]

for (prefix, level) in headings {
            if line.hasPrefix(prefix) {
                let content = String(line.dropFirst(prefix.count))
                return "<h\(level)>\(processInline(content))</h\(level)>"
            }
        }
        return nil
    }

/// 判断是否为水平分割线
    private static func isHorizontalRule(_ line: String) -> Bool {
        let trimmed = line.trimmingCharacters(in: .whitespaces)
        if trimmed.count < 3 { return false }

let firstChar = trimmed.first!
        guard firstChar == "-" || firstChar == "*" || firstChar == "_" else { return false }

// 仅由同一种字符（可含空格）组成
        return trimmed.allSatisfy { $0 == firstChar || $0.isWhitespace }
    }

/// 处理行内元素（粗体、斜体、代码、链接、图片）
    /// 先对原始文本进行 HTML 转义，再处理 Markdown 语法
    private static func processInline(_ text: String) -> String {
        var result = escapeHTML(text)

// 图片 ![alt](url) - 必须在链接之前处理
        result = replacePattern(result, pattern: #"!\[([^\]]*)\]$([^)]+)$"#) { match in
            let alt = match[1]
            let url = match[2]
            return "<img src="https://cdn.jsdelivr.net/gh/yanranxiaoxi/Simplecho@0.1.21/images/lazyload.jpg" alt="" data-src="" /><head>...</head><body>...</body></html>` 结构，但我们只需要 body 里的内容。`extractBodyContent` 方法通过字符串查找定位 `<body>` 和 `</body>`，截取中间部分。同时还调用了 `removeScriptTags` 清除 JavaScript 代码——安全第一，不能让 EPUB 里的脚本在 WebView 里执行。

**封面图片的双重查找**。EPUB 2 和 EPUB 3 标记封面的方式不同：EPUB 3 在 manifest item 的 `properties` 属性里写 `cover-image`，EPUB 2 则在 metadata 里用 `<meta name="cover" content="item-id"/>` 引用。代码先尝试 EPUB 3 方式，找不到再尝试 EPUB 2 方式，确保两种版本的 EPUB 都能正确提取封面。

---

## 第九章：RSS 订阅功能

> **替换占位代码**：在开始本章之前，请打开 `Stubs.swift` 文件，删除 `RSSListView`、`SettingsView`、`RSSArticle` 占位类型。本章将创建它们的完整实现。如果 `Stubs.swift` 此时已无任何占位代码，可以直接删除整个文件。

### 什么是 RSS

RSS 的全称是 Really Simple Syndication（真正简单的聚合），它的作用就像报社的送报服务。你不需要每天打开十几个网站检查有没有新文章，只要订阅了 RSS 源，新内容就会自动"送上门来"。

打个比方：RSS 就像你订了一份报纸，每天报社会把当天的报纸投递到你家门口的报箱里。你只需要打开报箱，就能看到所有最新内容。在技术层面，RSS 源本质上是一个 XML 文件，里面按时间倒序列出了网站最近发布的文章，每篇文章包含标题、链接、摘要和发布时间等信息。

### RSS 与 Atom 格式

目前主流的订阅源格式有两种：RSS 2.0 和 Atom。RSS 2.0 历史更悠久，使用 `<item>` 标签包裹每篇文章；Atom 是后来设计的更规范的格式，使用 `<entry>` 标签。我们的解析器同时支持这两种格式，用户不需要关心订阅源到底是哪种。

### XMLParser 的代理模式

Foundation 框架提供了 `XMLParser` 类来解析 XML 数据。它采用的是**代理模式（Delegate Pattern）**：解析器像一位逐行读报的读者，从头到尾扫描 XML 文档，每遇到一个重要的节点就"喊一声"通知代理对象。

打个比方：XMLParser 就像一个播音员在朗读报纸。他读到"下一篇报道开始"时，你就准备好记录新文章的信息；他读到标题，你就把标题记下来；他读到正文，你就把正文记下来；他读到"这篇报道结束"，你就把收集好的信息整理成一张完整的文章卡片。这个过程是事件驱动的，解析器会在三个关键时刻回调代理方法：

- `didStartElement`：遇到开始标签时触发（如 `<item>`），可以读取标签属性
- `foundCharacters`：遇到标签内的文本内容时触发，可能被多次调用
- `didEndElement`：遇到结束标签时触发（如 `</item>`），在这里完成一篇文章的组装

下面是我们完整的 RSS 服务实现，包含了数据模型、错误处理和 XML 解析逻辑。

? 项目文件：`FoxReader/Services/RSSService.swift`

```swift
import Foundation

// MARK: - RSS 文章数据结构

/// RSS 文章数据模型（非持久化，按需获取）
struct RSSArticle: Identifiable, Hashable {
    let id: UUID
    let title: String
    let link: String
    let summary: String
    let content: String
    let publishDate: Date?
    let author: String?

init(
        id: UUID = UUID(),
        title: String,
        link: String,
        summary: String = "",
        content: String = "",
        publishDate: Date? = nil,
        author: String? = nil
    ) {
        self.id = id
        self.title = title
        self.link = link
        self.summary = summary
        self.content = content
        self.publishDate = publishDate
        self.author = author
    }

/// 获取用于显示的 HTML 内容（优先使用 content，其次 summary）
    var displayContent: String {
        if !content.isEmpty {
            return content
        }
        return summary
    }
}

// MARK: - RSS 错误类型

enum RSSError: LocalizedError {
    case invalidURL
    case fetchFailed(String)
    case parseFailed(String)

var errorDescription: String? {
        switch self {
        case .invalidURL:
            return "无效的订阅地址"
        case .fetchFailed(let message):
            return "获取订阅失败：\(message)"
        case .parseFailed(let message):
            return "解析订阅失败：\(message)"
        }
    }
}

// MARK: - RSS 服务

/// RSS/Atom 订阅源解析服务
/// 使用 Foundation 的 XMLParser 解析 RSS 2.0 和 Atom 格式
struct RSSService {

/// 获取并解析订阅源
    /// - Parameter feedURL: 订阅源 URL 字符串
    /// - Returns: 文章数组
    static func fetchArticles(from feedURL: String) async throws -> [RSSArticle] {
        guard let url = URL(string: feedURL) else {
            throw RSSError.invalidURL
        }

let (data, response) = try await URLSession.shared.data(from: url)

if let httpResponse = response as? HTTPURLResponse,
           !(200...299).contains(httpResponse.statusCode) {
            throw RSSError.fetchFailed("HTTP \(httpResponse.statusCode)")
        }

return try parseFeed(data: data)
    }

/// 解析订阅源数据
    static func parseFeed(data: Data) throws -> [RSSArticle] {
        let parser = RSSFeedParser(data: data)
        return try parser.parse()
    }

/// 获取订阅源的标题和描述
    static func fetchFeedInfo(from feedURL: String) async throws -> (title: String, description: String) {
        guard let url = URL(string: feedURL) else {
            throw RSSError.invalidURL
        }

let (data, _) = try await URLSession.shared.data(from: url)
        let parser = RSSFeedParser(data: data)
        let info = try parser.parseFeedInfo()
        return info
    }
}

// MARK: - RSS 解析器

/// RSS/Atom XML 解析器
/// 同时支持 RSS 2.0 (item) 和 Atom (entry) 格式
private final class RSSFeedParser: NSObject, XMLParserDelegate {

private let parser: XMLParser
    private var articles: [RSSArticle] = []
    private var feedTitle = ""
    private var feedDescription = ""

// 当前解析状态
    private var currentElement = ""
    private var currentTitle = ""
    private var currentLink = ""
    private var currentDescription = ""
    private var currentContent = ""
    private var currentPubDate = ""
    private var currentAuthor = ""
    private var isInItem = false
    private var linkHref = ""

private var parseError: Error?

init(data: Data) {
        self.parser = XMLParser(data: data)
        super.init()
        self.parser.delegate = self
        self.parser.shouldProcessNamespaces = false
    }

// MARK: - 解析入口

func parse() throws -> [RSSArticle] {
        parser.parse()
        if let error = parseError {
            throw error
        }
        return articles
    }

func parseFeedInfo() throws -> (title: String, description: String) {
        parser.parse()
        if let error = parseError {
            throw error
        }
        return (feedTitle, feedDescription)
    }

// MARK: - XMLParserDelegate

func parser(_ parser: XMLParser, didStartElement elementName: String,
                namespaceURI: String?, qualifiedName qName: String?,
                attributes attributeDict: [String : String]) {
        currentElement = elementName

if elementName == "item" || elementName == "entry" {
            isInItem = true
            currentTitle = ""
            currentLink = ""
            currentDescription = ""
            currentContent = ""
            currentPubDate = ""
            currentAuthor = ""
            linkHref = ""
        }

// Atom 链接处理
        if elementName == "link" && isInItem {
            linkHref = attributeDict["href"] ?? ""
        }
    }

func parser(_ parser: XMLParser, foundCharacters string: String) {
        let trimmed = string.trimmingCharacters(in: .whitespacesAndNewlines)

if isInItem {
            switch currentElement {
            case "title":
                if !trimmed.isEmpty { currentTitle += trimmed }
            case "link":
                // RSS 2.0: link 标签内包含 URL 文本
                if !trimmed.isEmpty {
                    if linkHref.isEmpty {
                        currentLink += trimmed
                    } else {
                        currentLink = linkHref
                    }
                }
            case "description", "summary":
                currentDescription += string // 保留原始内容（可能含 HTML）
            case "content", "content:encoded":
                currentContent += string
            case "pubDate", "published", "updated":
                if !trimmed.isEmpty { currentPubDate += trimmed }
            case "author", "dc:creator":
                if !trimmed.isEmpty { currentAuthor += trimmed }
            default:
                break
            }
        } else {
            // 频道信息
            if !trimmed.isEmpty {
                switch currentElement {
                case "title":
                    if feedTitle.isEmpty { feedTitle += trimmed }
                case "description", "subtitle":
                    if feedDescription.isEmpty { feedDescription += trimmed }
                default:
                    break
                }
            }
        }
    }

func parser(_ parser: XMLParser, didEndElement elementName: String,
                namespaceURI: String?, qualifiedName qName: String?) {
        if elementName == "item" || elementName == "entry" {
            // 构建 RSSArticle
            let link = currentLink.isEmpty ? linkHref : currentLink
            let date = parseDate(currentPubDate)

let article = RSSArticle(
                title: decodeHTML(currentTitle),
                link: link,
                summary: decodeHTML(currentDescription),
                content: currentContent.isEmpty ? decodeHTML(currentDescription) : currentContent,
                publishDate: date,
                author: currentAuthor.isEmpty ? nil : currentAuthor
            )
            articles.append(article)

isInItem = false
        }

// 处理 Atom 的 link 标签结束
        if elementName == "link" && isInItem && !linkHref.isEmpty && currentLink.isEmpty {
            currentLink = linkHref
        }

currentElement = ""
    }

func parser(_ parser: XMLParser, parseErrorOccurred parseError: Error) {
        self.parseError = RSSError.parseFailed(parseError.localizedDescription)
    }

// MARK: - 日期解析

/// 解析多种日期格式
    private func parseDate(_ dateString: String) -> Date? {
        let formats = [
            "EEE, dd MMM yyyy HH:mm:ss zzz",
            "EEE, dd MMM yyyy HH:mm:ss Z",
            "yyyy-MM-dd'T'HH:mm:ssZZZZZ",
            "yyyy-MM-dd'T'HH:mm:ss.SSSZZZZZ",
            "yyyy-MM-dd'T'HH:mm:ss'Z'",
            "yyyy-MM-dd HH:mm:ss",
            "yyyy-MM-dd"
        ]

let formatter = DateFormatter()
        formatter.locale = Locale(identifier: "en_US_POSIX")

for format in formats {
            formatter.dateFormat = format
            if let date = formatter.date(from: dateString) {
                return date
            }
        }
        return nil
    }

// MARK: - HTML 实体解码

/// 简单的 HTML 实体解码
    private func decodeHTML(_ string: String) -> String {
        string
            .replacingOccurrences(of: "&", with: "&")
            .replacingOccurrences(of: "<", with: "<")
            .replacingOccurrences(of: ">", with: ">")
            .replacingOccurrences(of: """, with: "\"")
            .replacingOccurrences(of: "'", with: "'")
            .replacingOccurrences(of: "'", with: "'")
    }
}
```

上面的代码有几个关键点值得注意：

- **async/await 网络请求**：`fetchArticles` 方法使用了 Swift 的 async/await 语法，配合 `URLSession.shared.data(from:)` 进行异步网络请求，代码比传统的闭包回调更简洁直观。
- **多格式日期解析**：`parseDate` 方法尝试了 7 种不同的日期格式，因为不同 RSS 源使用的日期格式千差万别。注意 `locale` 设为 `en_US_POSIX` 是解析英文日期名称（如 Mon, Jan）的必要条件。
- **HTML 实体解码**：很多 RSS 源的标题和摘要中包含 HTML 实体（如 `&`、`<`），`decodeHTML` 方法负责把它们还原成可读字符。

### RSSViewModel：订阅管理的状态中枢

有了 RSSService 处理数据获取和解析，我们还需要一个 ViewModel 来管理 UI 状态。它负责在加载时显示进度，出错时展示错误信息，成功时更新文章列表。

? 项目文件：`FoxReader/ViewModels/RSSViewModel.swift`

```swift
import Foundation
import SwiftUI
import Combine

/// RSS 订阅 ViewModel
/// 管理文章获取、刷新和错误状态
@MainActor
final class RSSViewModel: ObservableObject {
    /// 当前获取到的文章列表
    @Published var articles: [RSSArticle] = []
    @Published var isLoading = false
    @Published var errorMessage: String?

/// 获取 RSS 订阅源的文章
    /// - Parameter feedURL: 订阅源 URL
    func fetchArticles(from feedURL: String) async {
        isLoading = true
        errorMessage = nil

do {
            articles = try await RSSService.fetchArticles(from: feedURL)
        } catch {
            errorMessage = error.localizedDescription
            articles = []
        }

isLoading = false
    }

/// 清空文章列表
    func clear() {
        articles = []
        errorMessage = nil
    }
}
```

这个 ViewModel 的设计很简洁：

- **`@MainActor` 标注**：确保所有属性更新都在主线程执行，因为 `@Published` 属性的变更会触发 SwiftUI 视图刷新，而 UI 更新必须在主线程进行。
- **三态管理**：`isLoading`、`errorMessage` 和 `articles` 三个属性覆盖了加载中、错误和正常三种状态，视图根据它们显示不同界面。

### RSSListView：订阅列表与文章列表

RSS 功能涉及两个列表视图：订阅源列表（`RSSListView`）和某订阅源下的文章列表（`RSSArticleListView`）。它们被定义在同一个文件中，前者负责展示用户已订阅的源，后者负责拉取并展示该源下的文章。

? 项目文件：`FoxReader/Views/RSS/RSSListView.swift`

```swift
import SwiftUI
import SwiftData

struct RSSListView: View {
    @Query(sort: \RSSFeedSource.title) var feeds: [RSSFeedSource]
    @Environment(\.modelContext) var modelContext
    @EnvironmentObject var readerSettings: ReaderSettings
    @State private var showAddFeed = false

var body: some View {
        NavigationStack {
            Group {
                if feeds.isEmpty {
                    EmptyStateView(
                        icon: "antenna.radiowaves.left.and.right",
                        title: "还没有订阅源",
                        subtitle: "点击右上角按钮添加 RSS 订阅",
                        actionTitle: "添加订阅",
                        action: { showAddFeed = true }
                    )
                } else {
                    List {
                        ForEach(feeds) { feed in
                            NavigationLink(value: feed) {
                                feedRow(feed)
                            }
                        }
                        .onDelete(perform: deleteFeed)
                    }
                }
            }
            .navigationTitle("订阅")
            .toolbar {
                ToolbarItem(placement: .topBarTrailing) {
                    Button { showAddFeed = true } label: {
                        Image(systemName: "plus")
                    }
                }
            }
            .navigationDestination(for: RSSFeedSource.self) { feed in
                RSSArticleListView(feed: feed)
                    .environmentObject(readerSettings)
            }
            .sheet(isPresented: $showAddFeed) {
                AddFeedView()
            }
        }
    }

private func feedRow(_ feed: RSSFeedSource) -> some View {
        VStack(alignment: .leading, spacing: 4) {
            Text(feed.title)
                .font(.body)
                .lineLimit(1)
            if !feed.feedDescription.isEmpty {
                Text(feed.feedDescription)
                    .font(.caption)
                    .foregroundStyle(.secondary)
                    .lineLimit(2)
            }
        }
    }

private func deleteFeed(at offsets: IndexSet) {
        for index in offsets {
            modelContext.delete(feeds[index])
        }
        try? modelContext.save()
    }
}

struct RSSArticleListView: View {
    let feed: RSSFeedSource
    @StateObject private var viewModel = RSSViewModel()
    @EnvironmentObject var readerSettings: ReaderSettings

var body: some View {
        Group {
            if viewModel.isLoading {
                ProgressView("加载中...")
                    .frame(maxWidth: .infinity, maxHeight: .infinity)
            } else if let error = viewModel.errorMessage {
                VStack(spacing: 16) {
                    Image(systemName: "wifi.exclamationmark")
                        .font(.system(size: 48))
                        .foregroundStyle(.orange)
                    Text(error)
                        .multilineTextAlignment(.center)
                        .foregroundStyle(.secondary)
                    Button("重试") {
                        Task { await viewModel.fetchArticles(from: feed.feedURL) }
                    }
                    .buttonStyle(.borderedProminent)
                }
                .padding()
                .frame(maxWidth: .infinity, maxHeight: .infinity)
            } else if viewModel.articles.isEmpty {
                Text("暂无文章")
                    .foregroundStyle(.secondary)
                    .frame(maxWidth: .infinity, maxHeight: .infinity)
            } else {
                List(viewModel.articles) { article in
                    NavigationLink(value: article) {
                        articleRow(article)
                    }
                }
                .listStyle(.plain)
            }
        }
        .navigationTitle(feed.title)
        .navigationBarTitleDisplayMode(.inline)
        .toolbar {
            ToolbarItem(placement: .topBarTrailing) {
                Button {
                    Task { await viewModel.fetchArticles(from: feed.feedURL) }
                } label: {
                    Image(systemName: "arrow.clockwise")
                }
            }
        }
        .task {
            await viewModel.fetchArticles(from: feed.feedURL)
        }
        .navigationDestination(for: RSSArticle.self) { article in
            ReaderView(article: article)
                .environmentObject(readerSettings)
        }
    }

private func articleRow(_ article: RSSArticle) -> some View {
        VStack(alignment: .leading, spacing: 6) {
            Text(article.title)
                .font(.body)
                .lineLimit(2)

if !article.summary.isEmpty {
                Text(article.summary.strippedHTML)
                    .font(.caption)
                    .foregroundStyle(.secondary)
                    .lineLimit(2)
            }

HStack {
                if let date = article.publishDate {
                    Text(date.relativeDisplayString)
                }
                if let author = article.author {
                    Text("· \(author)")
                }
            }
            .font(.caption2)
            .foregroundStyle(.tertiary)
        }
        .padding(.vertical, 4)
    }
}
```

这两个视图的设计要点：

- **SwiftData 查询**：`RSSListView` 使用 `@Query` 直接从数据库获取订阅源列表，SwiftUI 会自动在数据变化时刷新视图。`onDelete` 修饰符让用户可以左滑删除订阅。
- **`.task` 修饰符**：`RSSArticleListView` 在视图出现时通过 `.task` 自动触发文章拉取，它会在视图销毁时自动取消任务。点击右上角刷新按钮可以重新拉取。
- **统一阅读器**：点击文章后跳转到 `ReaderView(article: article)`，RSS 文章也会用统一的阅读器渲染，实现了"一处阅读，多源接入"的设计目标。

### AddFeedView：添加订阅的预览功能

添加订阅时，用户可能不确定一个链接是否有效。我们提供了"预览订阅信息"功能：先拉取 RSS 源的标题和描述，让用户确认后再保存。

? 项目文件：`FoxReader/Views/RSS/AddFeedView.swift`

```swift
import SwiftUI
import SwiftData

struct AddFeedView: View {
    @Environment(\.modelContext) var modelContext
    @Environment(\.dismiss) var dismiss

@State private var feedURL = ""
    @State private var feedTitle = ""
    @State private var feedDescription = ""
    @State private var isLoading = false
    @State private var errorMessage: String?
    @State private var hasPreview = false

var body: some View {
        NavigationStack {
            Form {
                Section("订阅地址") {
                    TextField("输入 RSS/Atom 链接", text: $feedURL)
                        .keyboardType(.URL)
                        .autocorrectionDisabled()
                        .textInputAutocapitalization(.never)

Button {
                        Task { await previewFeed() }
                    } label: {
                        if isLoading {
                            HStack {
                                ProgressView()
                                Text("获取中...")
                            }
                        } else {
                            Label("预览订阅信息", systemImage: "magnifyingglass")
                        }
                    }
                    .disabled(feedURL.isEmpty || isLoading)
                }

if hasPreview {
                    Section("订阅信息") {
                        TextField("名称", text: $feedTitle)
                        TextField("描述", text: $feedDescription, axis: .vertical)
                            .lineLimit(2...4)
                    }
                }

if let error = errorMessage {
                    Section {
                        Label(error, systemImage: "exclamationmark.triangle.fill")
                            .foregroundStyle(.red)
                    }
                }

Section {
                    Text("提示：输入完整的订阅链接，如 https://example.com/feed.xml")
                        .font(.caption)
                        .foregroundStyle(.secondary)
                }
            }
            .navigationTitle("添加订阅")
            .navigationBarTitleDisplayMode(.inline)
            .toolbar {
                ToolbarItem(placement: .cancellationAction) {
                    Button("取消") { dismiss() }
                }
                ToolbarItem(placement: .confirmationAction) {
                    Button("添加") { saveFeed() }
                        .disabled(feedURL.isEmpty)
                }
            }
        }
    }

private func previewFeed() async {
        isLoading = true
        errorMessage = nil

do {
            let info = try await RSSService.fetchFeedInfo(from: feedURL)
            feedTitle = info.title
            feedDescription = info.description
            hasPreview = true
        } catch {
            errorMessage = error.localizedDescription
            hasPreview = false
        }

isLoading = false
    }

private func saveFeed() {
        let feed = RSSFeedSource(
            title: feedTitle.isEmpty ? feedURL : feedTitle,
            feedURL: feedURL,
            feedDescription: feedDescription
        )
        modelContext.insert(feed)
        try? modelContext.save()
        dismiss()
    }
}
```

这个视图的预览功能是亮点：

- **预览机制**：`previewFeed` 方法调用 `RSSService.fetchFeedInfo` 只获取标题和描述，不拉取全部文章。这样用户可以先验证链接有效性，再决定是否保存。
- **可编辑的预览信息**：拉取到的标题和描述填入可编辑的文本框，用户可以自行修改后再保存。如果用户没有点预览就直接保存，标题默认使用 URL 地址。

---

### SettingsView：设置页面

我们的设置页面不需要复杂的交互——它主要是一个信息展示页面，让用户了解当前阅读设置的状态，以及 App 支持的文件格式。真正的阅读设置修改入口在阅读器内部。

> ? 项目文件：`FoxReader/Views/Settings/SettingsView.swift`

```swift
import SwiftUI

struct SettingsView: View {
    @EnvironmentObject var readerSettings: ReaderSettings

var body: some View {
        NavigationStack {
            List {
                Section {
                    settingRow(
                        icon: readerSettings.theme.iconName,
                        title: "当前主题",
                        value: readerSettings.theme.displayName
                    )

settingRow(
                        icon: "textformat.size",
                        title: "字体大小",
                        value: "\(Int(readerSettings.fontSize)) pt"
                    )

settingRow(
                        icon: readerSettings.fontFamily.iconName,
                        title: "字体类型",
                        value: readerSettings.fontFamily.displayName
                    )

settingRow(
                        icon: readerSettings.pageMode.iconName,
                        title: "翻页方式",
                        value: readerSettings.pageMode.displayName
                    )
                } header: {
                    Text("阅读设置")
                } footer: {
                    Text("阅读时点击右上角按钮可修改这些设置")
                }

Section("支持格式") {
                    formatRow(icon: "book.fill", title: "EPUB", desc: "电子书格式")
                    formatRow(icon: "doc.richtext", title: "Markdown", desc: "标记语言格式")
                    formatRow(icon: "antenna.radiowaves.left.and.right", title: "RSS/Atom", desc: "订阅源格式")
                }

Section("关于") {
                    settingRow(
                        icon: "info.circle",
                        title: "版本",
                        value: "1.0.0"
                    )

Link(destination: URL(string: "https://developer.apple.com/documentation/webkit/webkit-for-swiftui")!) {
                        HStack {
                            Label("WebKit for SwiftUI", systemImage: "safari")
                            Spacer()
                            Image(systemName: "chevron.right")
                                .font(.caption)
                                .foregroundStyle(.tertiary)
                        }
                    }
                }
            }
            .navigationTitle("设置")
        }
    }

private func settingRow(icon: String, title: String, value: String) -> some View {
        HStack {
            Label(title, systemImage: icon)
            Spacer()
            Text(value)
                .foregroundStyle(.secondary)
        }
    }

private func formatRow(icon: String, title: String, desc: String) -> some View {
        HStack {
            Image(systemName: icon)
                .frame(width: 24)
                .foregroundStyle(.tint)
            VStack(alignment: .leading, spacing: 2) {
                Text(title)
                Text(desc)
                    .font(.caption)
                    .foregroundStyle(.secondary)
            }
        }
    }
}
```

这个设置页面设计简洁明了：

- **阅读设置展示**：通过 `@EnvironmentObject` 读取 `ReaderSettings`，展示当前主题、字体大小、字体类型和翻页方式。用户如果想要修改，需要进入阅读器点击右上角的设置按钮。
- **支持格式说明**：清晰列出 EPUB、Markdown、RSS/Atom 三种支持的格式，方便用户了解 App 功能范围。
- **关于页面**：包含版本号和 WebKit for SwiftUI 的官方文档链接，方便开发者参考。

---

## 第十章：WebKit for SwiftUI 新特性展望

### WWDC25 带来的全新 WebKit API

在 WWDC25 上，Apple 发布了一个令人期待的新框架——WebKit for SwiftUI。在此之前的 SwiftUI 应用中，如果需要显示网页内容，我们必须通过 `UIViewRepresentable` 手动包装 UIKit 的 `WKWebView`，就像我们在 `WebViewContainer` 中做的那样。这种方式虽然能用，但代码较为繁琐，而且无法充分利用 SwiftUI 的声明式特性。

新的 WebKit for SwiftUI API 提供了两个核心类型：`WebView` 和 `WebPage`。你可以参考官方文档了解更多细节：[WebKit for SwiftUI](https://developer.apple.com/documentation/webkit/webkit-for-swiftui)。

### WebView：原生 SwiftUI 网页视图

`WebView` 是一个全新的 SwiftUI 原生视图结构体（struct），它可以直接在 SwiftUI 视图层级中使用，无需任何 `UIViewRepresentable` 包装。你只需要给它一个 URL 或 HTML 字符串，它就能自动加载和显示内容。

### WebPage：网页行为管理器

`WebPage` 是一个类（class），负责管理网页内容的行为。它可以执行 JavaScript、观察导航进度、处理导航事件等。你可以把它理解为 `WKWebView` 配置和行为的 SwiftUI 封装。多个 `WebView` 可以共享同一个 `WebPage`，实现状态同步。

### 与当前方案的对比

我们在项目中使用的 `WebViewContainer` 是通过 `UIViewRepresentable` 包装 `WKWebView` 实现的。来看看如果使用新的 WebView API，我们的 `ReaderView` 会变成什么样：

? 示例代码

```swift
import WebKit

// 使用新的 WebView（需要 iOS 26+）
struct ReaderViewModern: View {
    let htmlContent: String
    @State private var webPage = WebPage()

var body: some View {
        WebView(htmlContent)
            .webPage(webPage)
    }
}
```

对比我们当前的实现，新 API 的优势非常明显：

- **声明式 API**：`WebView` 是一个纯 SwiftUI 视图，不需要手动实现 `makeUIView` 和 `updateUIView` 方法。
- **`WebPage` 替代 `WebViewState`**：我们目前在 `WebViewContainer.swift` 中定义的 `WebViewState` 类用于持有 `WKWebView` 弱引用并执行 JavaScript 翻页。新的 `WebPage` 类天然提供了这些能力，不需要我们手动管理弱引用。
- **原生导航控制**：通过 `NavigationDeciding` 协议，你可以声明式地处理网页导航事件，比如决定是否允许跳转到某个链接。这比我们当前通过 `WKNavigationDelegate` 回调的方式更符合 SwiftUI 风格。

### NavigationDeciding 协议

`NavigationDeciding` 协议允许你为 `WebPage` 提供自定义的导航决策逻辑。当网页尝试跳转到新链接时，你可以检查目标 URL 并决定是允许、取消还是在外部浏览器打开。这在阅读器场景中特别有用，比如阻止广告跳转、拦截特定域名等。

### 迁移路径

好消息是，我们当前的 `WKWebView` 方案是完全生产可用的，支持 iOS 14+。新的 `WebView` API 需要 iOS 26+，目前很多用户的设备还未升级。因此，推荐的迁移策略是：

1. **当前保持不变**：`WebViewContainer` 已经经过充分测试，继续使用没有任何问题。
2. **渐进式迁移**：当你的应用最低部署目标提升到 iOS 26 后，可以逐步将 `WebViewContainer` 替换为 `WebView` + `WebPage`。
3. **条件编译过渡**：在过渡期可以使用 `if #available(iOS 26, *)` 来同时支持新旧两种实现。

我们的项目已经为未来的迁移做好了准备——`WebViewState` 封装了所有 JavaScript 调用逻辑，替换为 `WebPage` 时只需要修改这一层，上层视图代码几乎不用改动。

---

## 第十一章：项目完善与扩展指南

### 回顾：我们构建了什么

恭喜你一路走到了这里！让我们回顾一下 FoxReader 的完整旅程。我们从一个空项目开始，逐步构建了一个功能完整的阅读应用：

- **三种格式支持**：EPUB 电子书、Markdown 文档、RSS/Atom 订阅源，三种内容统一在同一个阅读器中呈现。
- **统一阅读体验**：通过 `HTMLTemplates` 将所有内容转换为 HTML，再用 `WKWebView` 渲染，实现了主题、字体、翻页方式的统一控制。
- **MVVM 架构**：Model（SwiftData）、View（SwiftUI）、ViewModel（ObservableObject）三层清晰分离，代码可维护性高。
- **SwiftData 持久化**：书籍、订阅源、书签全部使用 SwiftData 存储，无需手动管理数据库。

### 项目文件结构

整个项目包含 25 个 Swift 文件，组织结构如下：

```
FoxReader/
├── FoxReaderApp.swift                    # App 入口，配置 SwiftData 容器
├── ContentView.swift                     # 根视图，TabView 组织三大模块
├── Models/
│   ├── Book.swift                        # 图书数据模型（SwiftData）
│   ├── RSSFeedSource.swift               # RSS 订阅源模型（SwiftData）
│   └── Bookmark.swift                    # 书签模型（SwiftData）
├── Services/
│   ├── EPUBService.swift                 # EPUB 文件解析服务
│   ├── MarkdownService.swift             # Markdown 转 HTML 服务
│   ├── RSSService.swift                  # RSS/Atom 订阅源解析服务
│   └── BookImportService.swift           # 图书导入协调服务
├── ViewModels/
│   ├── LibraryViewModel.swift            # 书架管理 ViewModel
│   ├── ReaderViewModel.swift             # 阅读器 ViewModel
│   └── RSSViewModel.swift                # RSS 订阅 ViewModel
├── Views/
│   ├── Library/
│   │   ├── LibraryView.swift             # 书架主视图
│   │   └── BookCardView.swift             # 图书卡片视图
│   ├── Reader/
│   │   ├── ReaderView.swift              # 统一阅读器视图
│   │   ├── ReaderSettingsBar.swift        # 阅读设置面板
│   │   └── WebViewContainer.swift         # WKWebView 的 SwiftUI 封装
│   ├── RSS/
│   │   ├── RSSListView.swift             # 订阅列表与文章列表
│   │   └── AddFeedView.swift             # 添加订阅视图
│   ├── Settings/
│   │   └── SettingsView.swift            # 设置页面
│   └── Components/
│       ├── EmptyStateView.swift           # 空状态占位组件
│       └── DocumentPickerView.swift       # 文件选择器封装
└── Utilities/
    ├── ReaderSettings.swift               # 阅读设置管理器与主题枚举
    ├── HTMLTemplates.swift                # HTML 模板与 CSS 样式生成
    └── Extensions.swift                  # Color/Date/String 扩展
```

### 测试建议

一个成熟的应用离不开测试。以下是一些建议的单元测试方向：

- **MarkdownService 测试**：验证各种 Markdown 语法（标题、列表、代码块、粗体、链接等）是否正确转换为 HTML。准备一组输入输出对照的测试用例，覆盖边界情况如空字符串、嵌套格式等。
- **RSSService 测试**：准备几段真实的 RSS 2.0 和 Atom XML 数据作为测试 fixture，验证解析后的文章标题、链接、日期是否正确。特别注意多格式日期解析和 HTML 实体解码。
- **EPUBService 测试**：准备一个最小化的 EPUB 测试文件，验证章节提取、封面获取和 body 内容清理逻辑是否正常。

### 性能优化方向

当书籍体积增大或订阅源文章变多时，以下优化可以提升体验：

- **EPUB 解析缓存**：当前每次打开 EPUB 都会重新解压和解析。可以将解析结果缓存到本地文件或内存中，第二次打开时直接加载缓存。
- **章节懒加载**：对于章节众多的 EPUB，可以只在需要时解析当前章节的 HTML，而不是一次性解析所有章节。
- **设置变更的局部更新**：当前修改主题或字体会重新生成整个 HTML 并重新加载 WebView。可以考虑只通过 JavaScript 动态修改 CSS 变量，避免整页重新渲染。

### 未来功能展望

FoxReader 还有很大的扩展空间：

- **书签与高亮**：我们已经定义了 `Bookmark` 模型，可以进一步实现阅读过程中添加书签和高亮功能。
- **全文搜索**：在所有已导入的书籍和文章中搜索关键词，跳转到对应位置。
- **云同步**：通过 iCloud 或自定义后端同步阅读进度、订阅列表和书签数据。
- **OPDS 目录支持**：OPDS（Open Publication Distribution System）是一种电子书目录格式，支持后可以直接浏览和下载在线书库。
- **TTS 语音朗读**：利用系统 Text-to-Speech 框架，将文章内容转为语音播放。

### 写在最后

从零开始构建一个完整的阅读应用并不容易，但你已经做到了。在这个过程中，你学习了 SwiftUI 的视图组合、SwiftData 的数据持久化、MVVM 架构的实践、XML 解析技术、WKWebView 的集成以及模块化的设计思维。这些技能不只适用于 FoxReader，它们是你开发任何 iOS 应用的基础。

编程就像写作——第一稿永远不会完美，重要的是先把功能跑通，然后再不断打磨。希望 FoxReader 能成为你继续探索 iOS 开发的起点。去创造你自己的应用吧！

---

## 附录：完整项目文件清单

以下是项目中全部 25 个 Swift 文件的路径和功能说明：

| 序号 | 文件路径 | 功能说明 |
|------|----------|----------|
| 1 | `FoxReader/FoxReaderApp.swift` | App 入口，配置 SwiftData 数据容器并注册所有 @Model 类型 |
| 2 | `FoxReader/ContentView.swift` | 根视图，使用 TabView 组织书架、订阅、设置三个模块 |
| 3 | `FoxReader/Models/Book.swift` | 图书数据模型，使用 SwiftData 持久化，支持 EPUB/Markdown/RSS 三种类型 |
| 4 | `FoxReader/Models/RSSFeedSource.swift` | RSS 订阅源数据模型，存储用户订阅的 Feed 信息 |
| 5 | `FoxReader/Models/Bookmark.swift` | 书签数据模型，记录用户在阅读过程中添加的书签 |
| 6 | `FoxReader/Services/EPUBService.swift` | EPUB 文件解析服务，使用 ZIPFoundation 解压并解析 OPF 结构 |
| 7 | `FoxReader/Services/MarkdownService.swift` | Markdown 转 HTML 转换器，纯 Foundation 实现无需第三方依赖 |
| 8 | `FoxReader/Services/RSSService.swift` | RSS/Atom 订阅源解析服务，使用 XMLParser 解析两种格式 |
| 9 | `FoxReader/Services/BookImportService.swift` | 图书导入协调服务，根据文件扩展名分发给对应解析器 |
| 10 | `FoxReader/ViewModels/LibraryViewModel.swift` | 书架管理 ViewModel，处理图书导入和删除逻辑 |
| 11 | `FoxReader/ViewModels/ReaderViewModel.swift` | 阅读器 ViewModel，管理内容加载、章节导航和阅读进度 |
| 12 | `FoxReader/ViewModels/RSSViewModel.swift` | RSS 订阅 ViewModel，管理文章获取和错误状态 |
| 13 | `FoxReader/Views/Library/LibraryView.swift` | 书架主视图，LazyVGrid 展示图书卡片并支持导入 |
| 14 | `FoxReader/Views/Library/BookCardView.swift` | 图书卡片视图，显示封面、标题、作者和阅读进度 |
| 15 | `FoxReader/Views/Reader/ReaderView.swift` | 统一阅读器视图，支持 Book 和 RSSArticle 两种内容来源 |
| 16 | `FoxReader/Views/Reader/ReaderSettingsBar.swift` | 阅读设置面板，以底部 Sheet 形式提供主题/字体/翻页设置 |
| 17 | `FoxReader/Views/Reader/WebViewContainer.swift` | WKWebView 的 SwiftUI 封装，包含 WebViewState 状态管理器 |
| 18 | `FoxReader/Views/RSS/RSSListView.swift` | 订阅列表视图与文章列表视图，支持刷新和删除 |
| 19 | `FoxReader/Views/RSS/AddFeedView.swift` | 添加订阅视图，提供订阅预览功能后保存到 SwiftData |
| 20 | `FoxReader/Views/Settings/SettingsView.swift` | 设置页面，展示阅读设置状态、支持格式和版本信息 |
| 21 | `FoxReader/Views/Components/EmptyStateView.swift` | 空状态占位组件，可复用于书架和订阅列表 |
| 22 | `FoxReader/Views/Components/DocumentPickerView.swift` | UIDocumentPickerViewController 的 SwiftUI 封装 |
| 23 | `FoxReader/Utilities/ReaderSettings.swift` | 阅读设置管理器，定义主题/字体/翻页枚举并使用 @AppStorage 持久化 |
| 24 | `FoxReader/Utilities/HTMLTemplates.swift` | HTML 模板生成器，将内容包装为完整 HTML 文档并注入 CSS 和 JS |
| 25 | `FoxReader/Utilities/Extensions.swift` | Color/Date/String/URL 扩展方法集合 |

FoxReader：从零构建 SwiftUI iOS 阅读 App 完整教程

添加新评论 取消回复

添加新评论取消回复