如何用AGCircularPicker构建多环时间选择器：时、分、秒联动一次搞定

如何用AGCircularPicker构建多环时间选择器：时、分、秒联动一次搞定

【免费下载链接】AGCircularPicker AGCircularPicker is helpful component for creating a controller aimed to manage any calculated parameter 项目地址: https://gitcode.com/gh_mirrors/ag/AGCircularPicker

AGCircularPicker 是一款轻量级 iOS 圆形时间选择器组件，专为管理"计算型参数"而生。借助它内置的多环容器，你可以快速搭出一个时、分、秒联动的多环时间选择器——横向滑动切换环，旋转圆环改数值，顶部标签实时汇总，非常适合倒计时、游戏计分等场景。本文带你从安装到联动实现一次搞定。

30秒认识AGCircularPicker：圆形时间选择器能做什么？

组件由两个核心类组成：

典型使用场景：

• ⏱️ 倒计时 / 时间设置（时、分、秒）
• 🎮 游戏界面的分数控制
• 🎚️ 音量等单参数调节

一键安装步骤：CocoaPods 最快配置方法

在 Podfile 中添加一行即可引入 AGCircularPicker：

pod "AGCircularPicker"

执行 pod install 后，import AGCircularPicker 就能开始使用了。想直接跑完整示例工程，可先克隆仓库：

git clone https://gitcode.com/gh_mirrors/ag/AGCircularPicker

进入 Example 目录执行 pod install，即可看到单环与多环两个演示页面。

第一步：用配置项描述"时、分、秒"

每个环都由一个 AGCircularPickerOption 描述，包含三组配置：

• valueOption（必填）：最小值、最大值、旋转圈数、初始值
• titleOption（可选）：环标题、字体、颜色
• colorOption（可选）：渐变色、渐变位置、渐变角度

多环时间选择器中三个环的设置如下（摘自 MultiPickerViewController.swift）：

// 时环：0~23，转 2 圈，初始 15
let hourValueOption = AGCircularPickerValueOption(minValue: 0, maxValue: 23,
                                                 rounds: 2, initialValue: 15)
let hourOption = AGCircularPickerOption(
    valueOption: hourValueOption,
    titleOption: AGCircularPickerTitleOption(title: "hours"),
    colorOption: AGCircularPickerColorOption(gradientColors: hourColors, gradientAngle: 20))

// 分环 / 秒环：0~59
let minuteValueOption = AGCircularPickerValueOption(minValue: 0, maxValue: 59)
let minuteOption = AGCircularPickerOption(valueOption: minuteValueOption,
    titleOption: AGCircularPickerTitleOption(title: "minutes"),
    colorOption: minuteColorOption)

💡 小技巧：给每个环设置不同的 gradientAngle（如 20 / -20），三环视觉区分度立刻拉满。

第二步：三行代码挂上多环容器，实现时、分、秒联动

把选项数组赋给容器并设置 delegate，联动逻辑就完成了：

circularPicker.options = [hourOption, minuteOption, secondOption]
circularPicker.delegate = self

联动的核心是 AGCircularPickerDelegate 的回调——任意一环数值变化时，都会收到全部三个环的最新值：

func didChangeValues(_ values: [AGColorValue], selectedIndex: Int) {
    // values: [时, 分, 秒]；selectedIndex: 当前正在操作的环
    let text = values.map { String(format: "%02d", $0.value) }
                    .joined(separator: ":")        // 例如 15:00:00
    titleLabel.text = text
    // 再用 values[selectedIndex].color 可高亮当前环
}

联动原理：滑动切环 + 实时汇总

看 AGCircularPicker.swift 就能理解实现机制：

1. 容器内部是一个横向 UICollectionView，每个选项对应一个旋钮 cell；
2. AGCenteredFlowLayout 负责"居中吸附"：松手时自动对齐到最近的环，两侧环自动降低透明度并禁用交互；
3. 当前环数值一变，立即通过 delegate 汇总回传，实现时、分、秒三值实时联动。

自定义清单：换个风格只要改配置

不设置颜色时，组件会使用默认的青-蓝-紫渐变，开箱即用。

常见问题 FAQ

Q1：分钟环能超过 60 吗？ 能。maxValue 想设多少就设多少，rounds 决定转几圈回到起点。

Q2：如何定位到初始时间？ 在 valueOption 中传 initialValue 即可，例如 initialValue: 15 表示初始 15 时。

Q3：单环和多环怎么选？ 只做音量这类单参数，用 AGCircularPickerView + setupPicker（参考 SinglePickerViewController.swift）；需要时、分、秒联动，就用 AGCircularPicker 多环容器。

总结

AGCircularPicker 用"选项配置 + 代理回调"的极简设计，把多环时间选择器拆成了三步：描述配置、挂载容器、实现联动。接下来只需把默认渐变换成项目的品牌色，一个专属的圆形时间选择器就完成了 🎉

【免费下载链接】AGCircularPicker AGCircularPicker is helpful component for creating a controller aimed to manage any calculated parameter 项目地址: https://gitcode.com/gh_mirrors/ag/AGCircularPicker