介绍
# PagerKit Skill
## 概述
该技能提供有关 `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(_:)` 且持续时间非零。请参阅 `references/PKPage.md`。 - **“我在 `PKPagesView` 内部的条件逻辑（`if` 语句）出现编译器错误。”** - 查看 `PKPageBuilder` 概念，确保所有分支都返回有效的 `PKPage` 组件。请参阅 `references/PKPageBuilder.md`。 - **“如何判断用户是向前滑动还是向后滑动？”** - 在 `.pkOnManualPageChange` 中使用 `PKPageDirection` 参数。请参阅 `references/PKPagesView.md`，`references/PKPageDirection.md`。
## 核心模式参考
### 基本分页器设置
```swift PKPagesView { PKPage { Text("Page A").font(.title) } PKPage { Text("Page B").font(.title) } PKPage { Text("Page C").font(.title) } } .pkCurrentPageIndex(index: $currentPage) // Bind to @State .pkPageNavigationOrientation(.horizontal) ```
### 使用 ForEach 进行动态分页
```swift struct Item: Identifiable { let id = UUID() let title: String }
// ... inside a View let items = [Item(title: "Item 1"), Item(title: "Item 2")]
PKPagesView { ForEach(items) { item in PKPage { Text(item.title) } .pkPageFooter { Text("Footer for \(item.title)") } } } ```
### 自定义页面指示器样式
```swift .pkPageControlIndicatorAlignment(spacing: 10, alignment: .bottomTrailing) .pkPageControlIndicatorBackgroundStyle(.prominent) .pkPageControlIndicatorDirection(.topToBottom) // Vertical dots .pkPageControlIndicatorTintColor(.gray) .pkPageControlIndicatorCurrentIndicatorTintColor(.blue) // Custom images #if os(iOS) .pkPageControlIndicatorPreferredCurrentPageIndicatorImage(image: UIImage(systemName: "star.fill")) #else .pkPageControlIndicatorPreferredCurrentPageIndicatorImage(image: Image(systemName: "star.fill")) #endif ```
### 处理页面更改事件
```swift .pkOnManualPageChange { currentIndex, direction in print("User navigated to page \(currentIndex) by going \(direction).") } .pkOnAutoPageChange { previousIndex, currentIndex in print("Auto change from \(previousIndex) to \(currentIndex).") } .pkOnTransitionEnd { previous, current in print("Transition ended. Was on \(previous), now on \(current).") } ```
## 集成快速指南
PagerKit 通过 Swift Package Manager 集成。
1. **添加包依赖：** 在 Xcode 中，转到 **File > Add Package Dependency** 并输入 `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/](https://documentation.kamilszpak.com/documentation/pagerkit/) 上的官方文档或项目网站 [kamilszpak.com/pl/pagerkit](https://kamilszpak.com/pl/pagerkit)。