名称： PagerKit
描述： '提供关于 PagerKit 的专家指导，这是一个用于高级、可定制页面导航的 SwiftUI 库。当开发者提及以下内容时使用：(1) PagerKit、PKPagesView、PKPage，(2) 自定义页面控件、指示器或分页行为，(3) 跨平台 SwiftUI 分页，(4) 动态页面生成，(5) 将页面视图集成到自定义布局中，(6) 特定的 PagerKit 修饰符或枚举，(7) 页面视图控制器选项，(8) 页面更改的事件处理。'

PagerKit 技能

概述

本技能提供关于 PagerKit 的专家指导，这是一个功能强大的 SwiftUI 库，用于创建高度可定制且跨平台的基于页面的导航。内容涵盖从基本用法、动态页面生成到页面指示器高级定制、事件处理以及最佳实践等各个方面。使用本技能可帮助开发者在所有 Apple 平台的 SwiftUI 应用中有效实现灵活且视觉丰富的分页体验。

助手行为准则 (遵循以下规则)

1. 明确分页需求： 在提供解决方案之前，务必先了解用户关于页面内容、指示器样式、导航流程和平台目标的具体需求。
2. 优先使用地道的 SwiftUI： 推荐使用 PagerKit 的 PKPageBuilder 和 ForEach 进行声明式页面构建，以符合 SwiftUI 的设计原则。
3. 提供平台特定建议： 当讨论指示器图像、进度或 UIPageViewController 选项时，务必说明平台可用性和正确的类型（UIImage 与 Image，UIPageControlProgress）。
4. 强调修饰符： 引导用户使用相关的 PKPagesView 或 PKPage 修饰符进行定制，并使用完整的修饰符签名（例如 .pkPageNavigationOrientation(_:)）。
5. 提供上下文相关的代码示例： 提供简洁的代码片段，展示在 PKPagesView 或 PKPage 上下文中的推荐用法。
6. 突出跨平台特性： 在可能的情况下，提醒用户 PagerKit 的跨平台一致性，以及如何使用 #if os(...) 指令处理平台特定差异。

项目设置

PagerKit 的行为受项目部署目标和 Swift 版本影响。

• 部署目标： PagerKit 支持 iOS 14.0+、iPadOS 14.0+、macOS 14.0+、tvOS 14.0+、visionOS 1.0+ 和 watchOS 10.0+。某些功能（例如 UIPageControlProgress）仅在特定平台和操作系统版本上可用。
• Swift 版本： 需要 Swift 5.9+。

如果这些信息未知，请要求开发者确认，尤其是在讨论平台特定功能时。

快速决策树

当开发者需要 PagerKit 指导时，请遵循此决策树：

1. 设置新的分页器？

   • 基本安装和概念 → references/PagerKit.md
   • 定义整体分页器结构 → references/PKPagesView.md
   • 创建单个页面内容 → references/PKPage.md

2. 从数据动态生成页面？

   • 使用项目集合 → references/ForEach.md

3. 控制页面流或结构？

   • 添加条件页面 (if/else) → references/PKPageBuilder.md
   • 设置水平或垂直导航 → references/PKPagesView.md (.pkPageNavigationOrientation)

4. 自定义页面指示器（点）？

   • 更改颜色（活动/非活动） → references/PKPagesView.md (.pkPageControlIndicatorTintColor, .pkPageControlIndicatorCurrentIndicatorTintColor)
   • 更改背景样式（简约、突出、自动） → references/PKPageControlBackgroundStyle.md
   • 调整位置或间距 → references/PKPagesView.md (.pkPageControlIndicatorAlignment, .pkPageControlPadding)
   • 设置布局方向（例如垂直对齐） → references/PKPageControlDirection.md
   • 使用自定义图像（全局或每页） → references/PKPagesView.md, references/PKPage.md
   • 隐藏指示器（始终隐藏或单页时隐藏） → references/PKPagesView.md

5. 处理页面更改事件或状态？

   • 绑定到当前页面索引 → references/PKPagesView.md (.pkCurrentPageIndex)
   • 响应用户手动页面更改 → references/PKPagesView.md (.pkOnManualPageChange)
   • 响应自动页面更改 → references/PKPagesView.md (.pkOnAutoPageChange)
   • 识别页面过渡方向 → references/PKPageDirection.md
   • 在过渡开始/结束时执行操作 → references/PKPagesView.md

6. 自定义单个页面行为？

   • 设置自动过渡持续时间 → references/PKPage.md (.pkPageDuration)
   • 为页面添加自定义页脚 → references/PKPage.md (.pkPageFooter)

问题排查优先指南

• "我的页面没有显示或显示不正确。"
  • 验证 PKPagesView 是否包含有效的 PKPage 实例。参考 references/PKPagesView.md, references/PKPage.md。
  • 如果使用动态内容，检查 ForEach 实现。参考 references/ForEach.md。
• "页面指示器位置或样式不正确。"
  • 检查 PKPagesView 上的 .pkPageControlIndicatorAlignment、.pkPageControlIndicatorBackgroundStyle、.pkPageControlIndicatorDirection 修饰符。参考 references/PKPagesView.md、references/PKPageControlBackgroundStyle.md、references/PKPageControlDirection.md。
• "我想更改活动点的颜色，但不起作用。"
  • 确保在 PKPagesView 上使用了 .pkPageControlIndicatorCurrentIndicatorTintColor(_:)。参考 references/PKPagesView.md。
• "页面没有自动过渡。"
  • 检查是否在单个 PKPage 上应用了 .pkPageDuration(_:) 并设置了非 nil 的持续时间。参考 references/PKPage.md。
• "PKPagesView 内部的条件逻辑（if 语句）导致编译器错误。"
  • 复习 PKPageBuilder 概念，确保所有分支都返回有效的 PKPage 组件。参考 references/PKPageBuilder.md。
• "如何判断用户是向前滑动还是向后滑动？"
  • 在 .pkOnManualPageChange 中使用 PKPageDirection 参数。参考 references/PKPagesView.md、references/PKPageDirection.md。

核心模式参考

基本分页器设置

PKPagesView {
    PKPage { Text("页面 A").font(.title) }
    PKPage { Text("页面 B").font(.title) }
    PKPage { Text("页面 C").font(.title) }
}
.pkCurrentPageIndex(index: $currentPage) // 绑定到 @State
.pkPageNavigationOrientation(.horizontal)

使用 ForEach 动态生成页面

struct Item: Identifiable {
    let id = UUID()
    let title: String
}

// ... 在某个 View 内部
let items = [Item(title: "项目 1"), Item(title: "项目 2")]

PKPagesView {
    ForEach(items) { item in
        PKPage { Text(item.title) }
            .pkPageFooter { Text("\(item.title) 的页脚") }
    }
}

自定义页面指示器样式

.pkPageControlIndicatorAlignment(spacing: 10, alignment: .bottomTrailing)
.pkPageControlIndicatorBackgroundStyle(.prominent)
.pkPageControlIndicatorDirection(.topToBottom) // 垂直排列的点
.pkPageControlIndicatorTintColor(.gray)
.pkPageControlIndicatorCurrentIndicatorTintColor(.blue)
// 自定义图像
#if os(iOS)
.pkPageControlIndicatorPreferredCurrentPageIndicatorImage(image: UIImage(systemName: "star.fill"))
#else
.pkPageControlIndicatorPreferredCurrentPageIndicatorImage(image: Image(systemName: "star.fill"))
#endif

处理页面更改事件

.pkOnManualPageChange { currentIndex, direction in
    print("用户导航到页面 \(currentIndex)，方向是 \(direction)。")
}
.pkOnAutoPageChange { previousIndex, currentIndex in
    print("自动从页面 \(previousIndex) 切换到 \(currentIndex)。")
}
.pkOnTransitionEnd { previous, current in
    print("过渡结束。之前是 \(previous)，现在是 \(current)。")
}

集成快速指南

PagerKit 通过 Swift Package Manager 集成。

1. 添加包依赖： 在 Xcode 中，转到 文件 > 添加包依赖项，输入 https://github.com/SzpakKamil/PagerKit.git。
2. 导入： 在 Swift 文件中使用 import PagerKit。
3. 部署目标： 确保项目目标为 iOS 14.0+、iPadOS 14.0+、macOS 14.0+、tvOS 14.0+、visionOS 1.0+ 或 watchOS 10.0+（Swift 5.9+）。

详细设置请参见 references/PagerKit.md。

参考文件

根据需要加载这些文件以获取特定主题信息：

• PagerKit.md - 概述、设置和核心优势。
• PKPagesView.md - 主分页器容器及其全局修饰符的详细信息。
• PKPage.md - 单个页面创建和页面特定修饰符的信息。
• ForEach.md - 如何从数据集合生成页面。
• PKPageBuilder.md - 理解 PKPagesView 的声明式内容构建。
• PKPageControlBackgroundStyle.md - 页面指示器背景样式的选项。
• PKPageControlDirection.md - 页面指示器点布局方向的选项。
• PKPageDirection.md - 理解页面过渡的方向。
• _index.md - 所有 PagerKit 参考文档的综合索引。

最佳实践总结

1. 拥抱声明式 UI： 使用 PKPageBuilder 配合 ForEach 进行灵活且可维护的页面构建。
2. 审慎定制： 利用丰富的修饰符 API 来匹配原生平台美学和应用程序品牌，避免过度定制影响可用性。
3. 管理分页器状态： 始终将 pkCurrentPageIndex 绑定到外部状态（@State 或 @Binding），以便进行程序化控制和观察。
4. 实现事件处理： 利用回调（例如 .pkOnManualPageChange、.pkOnTransitionEnd）来处理分析、触觉反馈或响应导航的自定义逻辑。
5. 注意平台差异： 了解在不同 Apple 平台和操作系统版本上行为不同或仅限特定平台可用的修饰符和功能。
6. 优先考虑可访问性： 确保自定义指示器和页脚保持可访问性（例如，支持 VoiceOver）。

注意： 本技能基于 PagerKit 的完整文档。更多详细信息，请访问官方文档 documentation.kamilszpak.com/documentation/pagerkit/ 或项目网站 kamilszpak.com/pl/pagerkit。