Flet 中 CupertinoTimerPickerMode 枚举全解析：iOS 风格倒计时选择器的三种显示模式-平芜编程栈

前端
跨平台
桌面应用
移动开发

【免费下载链接】flet

Build realtime web, mobile and desktop apps in Python only. No frontend experience required.

项目地址：https://gitcode.com/gh_mirrors/fl/flet

flet.CupertinoTimerPickerMode是 Flet 框架（sdk/python/packages/flet/src/flet/controls/cupertino/cupertino_timer_picker.py）中用于控制 iOS 风格倒计时选择器（CupertinoTimerPicker）显示粒度的枚举类型。本文以该类型文档为主体，结合其对应的 Flutter 实现与 Python 控件源码，完整讲解三种模式的取值、显示效果、默认行为，以及它们在真实应用（倒计时设置、底部弹层、事件回调）中的组合用法。读完本文，你将能够根据自己的业务场景，精确选择最合适的计时显示模式，并写出可复现、可运行的 Flet 代码。

什么是 CupertinoTimerPickerMode

CupertinoTimerPickerMode是CupertinoTimerPicker控件的mode属性的取值类型，它决定倒计时选择器以「小时-分钟」「小时-分钟-秒」「分钟-秒」中的哪一种粒度来展示时间。在 Flet 中，它是一个标准的Enum类型，每个成员都有一个对应的字符串序列化值，用于在 Python 侧与 Flutter 渲染端之间传递：

枚举成员	字符串值	显示粒度	显示示例
`HOUR_MINUTE`	`"hm"`	小时、分钟	`16 hours \\| 14 min`
`HOUR_MINUTE_SECONDS`	`"hms"`	小时、分钟、秒	`16 hours \\| 14 min \\| 43 sec`
`MINUTE_SECONDS`	`"ms"`	分钟、秒	`14 min \\| 43 sec`

从源码看，这三个成员定义在CupertinoTimerPickerMode枚举中（cupertino_timer_picker.py），其 docstring 分别给出了上述显示示例，帮助开发者直观理解每种模式的视觉效果。

底层字符串值的传递

Python 侧枚举成员的字符串值（"hm"、"hms"、"ms"）并非随意设定，它们与 Flutter 端CupertinoTimerPickerMode枚举（hm、hms、ms）一一对应。在 Flutter 渲染端，控件通过解析属性字符串来还原枚举：

cupertino_timer_picker.dart 中调用getCupertinoTimerPickerMode("mode", CupertinoTimerPickerMode.hms)读取mode属性，未设置时默认回退到hms；
解析逻辑实现在 utils/time.dart 的parseCupertinoTimerPickerMode，内部通过parseEnum将字符串映射为 Flutter 枚举。

这意味着三种模式在 Python 与 Flutter 两端是完全对齐的，开发者只需关心业务语义，无需处理序列化细节。

CupertinoTimerPicker 与 mode 的配合

CupertinoTimerPickerMode本身只是一个枚举，它的实际价值体现在作为CupertinoTimerPicker.mode属性的取值。该控件在 Flet 中对应 iOS 风格（Cupertino 设计语言）的倒计时选择器，可以显示小时、分钟、秒三组滚轮，取值范围被严格限制在0到23小时59分钟59秒之间。

一个最小可运行的示例：

import flet as ft ft.CupertinoTimerPicker( value=ft.Duration(seconds=754), # 初始倒计时时长 mode=ft.CupertinoTimerPickerMode.HOUR_MINUTE_SECONDS, # 显示粒度 )

当value以整数传入时，会被视为秒数，例如value=300等价于 5 分钟。

mode 的默认值

mode属性的默认值是CupertinoTimerPickerMode.HOUR_MINUTE_SECONDS（cupertino_timer_picker.py），也就是说，即使你不显式设置mode，选择器也会展示「小时 | 分钟 | 秒」三列滚轮。这一默认行为与 Flutter 端getCupertinoTimerPickerMode("mode", CupertinoTimerPickerMode.hms)的回退值保持一致。

三种模式的实际演示

官方示例仓库中提供了一个专门用于对比三种模式的演示程序（showcase/main.py），它遍历枚举的全部成员，为每种模式生成一张独立的卡片：

import flet as ft def showcase_card(mode: ft.CupertinoTimerPickerMode) -> ft.Container: return ft.Container( width=340, padding=12, border=ft.Border.all(1, ft.Colors.RED), border_radius=10, bgcolor=ft.Colors.SURFACE_CONTAINER_LOW, content=ft.Column( spacing=8, controls=[ ft.Text(mode.name, weight=ft.FontWeight.BOLD), ft.CupertinoTimerPicker( mode=mode, value=ft.Duration(seconds=754), ), ], ), ) def main(page: ft.Page): page.horizontal_alignment = ft.CrossAxisAlignment.CENTER page.appbar = ft.AppBar(title="CupertinoTimerPickerMode Showcase") page.add( ft.SafeArea( expand=True, content=ft.Column( controls=[ ft.Text("Compare timer picker layouts."), ft.Row( wrap=True, spacing=12, expand=True, scroll=ft.ScrollMode.AUTO, alignment=ft.MainAxisAlignment.CENTER, controls=[ showcase_card(mode) for mode in ft.CupertinoTimerPickerMode ], ), ], ), ) ) if __name__ == "__main__": ft.run(main)

运行这段代码，页面上会并排展示三种模式的选择器，可以直观对比同一时长（ft.Duration(seconds=754)，即 12 分 34 秒）在不同模式下的列数与显示粒度：

HOUR_MINUTE：只显示小时和分钟两列，适合「精确到分钟」的场景；
HOUR_MINUTE_SECONDS：显示小时、分钟、秒三列，信息最完整；
MINUTE_SECONDS：只显示分钟和秒两列，适合时长较短、无需小时的场景（如 1 分钟内的高精度倒计时）。

注意示例中通过for mode in ft.CupertinoTimerPickerMode遍历枚举成员，这与 Python 标准库Enum的迭代行为一致，说明CupertinoTimerPickerMode可以直接参与枚举的遍历、比较等常规操作。

在真实应用中使用三种模式

除了模式对比演示，仓库还提供了一个更贴近真实业务的完整示例（cupertino_timer_picker/main.py）：把选择器放进CupertinoBottomSheet底部弹层，用户点击按钮后弹出设置倒计时，并通过on_change事件实时回显选择结果：

import time import flet as ft def main(page: ft.Page): page.horizontal_alignment = ft.CrossAxisAlignment.CENTER timer_value_text = ft.Text( value="00:01:10", size=23, color=ft.CupertinoColors.DESTRUCTIVE_RED, ) def handle_timer_picker_change(e: ft.Event[ft.CupertinoTimerPicker]): timer_value_text.value = time.strftime("%H:%M:%S", time.gmtime(e.data)) timer_picker = ft.CupertinoTimerPicker( value=300, second_interval=10, minute_interval=1, mode=ft.CupertinoTimerPickerMode.HOUR_MINUTE_SECONDS, on_change=handle_timer_picker_change, ) page.add( ft.SafeArea( content=ft.Row( tight=True, controls=[ ft.Text("TimerPicker Value:", size=23), ft.CupertinoButton( on_click=lambda _: page.show_dialog( ft.CupertinoBottomSheet( height=216, padding=ft.Padding.only(top=6), content=timer_picker, ) ), content=timer_value_text, ), ], ), ) ) if __name__ == "__main__": ft.run(main)

该示例展示了与模式选择配套的完整属性组合：

value=300：以整数（秒）形式设置初始值，这里表示 5 分钟；
second_interval=10：秒滚轮的粒度，此处意味着滚轮只能选中 0、10、20、30、40、50 秒；
minute_interval=1：分钟滚轮的粒度，按整分钟递增；
on_change：用户滚动滚轮改变时长时触发回调，e.data中携带新的时长值。

关于 on_change 返回值的类型

on_change事件回调的数据类型与value属性保持严格一致（cupertino_timer_picker.py）：如果value是Duration，那么e.data也是Duration；如果value是整数（秒），则e.data也是整数秒。上述示例中value=300是整数，因此回调里直接用time.gmtime(e.data)格式化即可。

这一「保留原始类型」的行为在 Flutter 端也有对应实现：onTimerDurationChanged回调中，会判断控件原始value是否为int，是则把事件数据转换为秒数，否则保留完整的Duration（cupertino_timer_picker.dart）。

模式与间隔参数的校验规则

使用不同的mode时，还需要注意value、minute_interval、second_interval之间的约束关系。从CupertinoTimerPicker.before_update的实现（cupertino_timer_picker.py）可以看出，控件在每次更新前会执行一系列校验，不满足条件会抛出ValueError：

value必须是非负时长，即不能小于0；
value必须严格小于24小时（与前面提到的取值范围上限一致）；
当minute_interval > 0时，value的分钟数必须是minute_interval的整数倍；
当second_interval > 0时，value的秒数必须是second_interval的整数倍；
item_extent（滚轮子项的统一高度）必须严格大于0。

此外，minute_interval与second_interval自身也有约束：必须严格大于0且是60的因子（见属性定义处的V.gt(0)与V.factor_of(60)校验注解，cupertino_timer_picker.py）。

这些规则对实际开发有直接影响：例如在使用MINUTE_SECONDS模式时，若同时设置了second_interval=10，那么value的秒数必须是 10 的倍数，否则控件会拒绝更新并抛出异常。设计倒计时功能时，应确保初始值与滚轮粒度对齐。

其他常用属性速查

除mode外，CupertinoTimerPicker还提供以下属性用于定制外观与行为（定义于 cupertino_timer_picker.py）：

属性	默认值	说明
`value`	`Duration()`（0 时长）	初始倒计时时长；传整数则视为秒
`alignment`	`Alignment.CENTER`	选择器在其父级中的对齐方式
`second_interval`	`1`	秒滚轮的粒度，必须为 60 的因子
`minute_interval`	`1`	分钟滚轮的粒度，必须为 60 的因子
`bgcolor`	`None`	选择器背景色
`item_extent`	`32.0`	所有滚轮子项的统一高度
`on_change`	`None`	时长变化时的回调事件

Flutter 端对这些属性的解析同样可以在 cupertino_timer_picker.dart 中找到一一对应关系，包括默认值（minute_interval=1、second_interval=1、item_extent=32.0、alignment=Alignment.center）。

测试验证

仓库的集成测试（test_cupertino_timer_picker.py）对上述用法给出了可验证的样例：测试将value=300、second_interval=10、minute_interval=1、mode=HOUR_MINUTE_SECONDS的选择器放入CupertinoBottomSheet弹层中展示，并开启截图断言。这从侧面确认了「模式 + 间隔 + 弹层」组合是官方推荐且经过验证的用法，也是你调试自己页面时可以参考的对照基准。

总结

CupertinoTimerPickerMode用三个成员覆盖了 iOS 倒计时选择器的全部显示粒度：需要小时级时长用HOUR_MINUTE，需要精确到秒用HOUR_MINUTE_SECONDS（默认模式），时长较短且无需小时用MINUTE_SECONDS。实际使用时，结合value、minute_interval、second_interval、on_change等属性即可快速构建出符合 iOS 交互习惯的倒计时设置界面；同时注意值域与间隔的校验规则，避免更新时抛出ValueError。相关源码与示例均可直接在仓库中查阅：Python 控件定义、模式对比演示、完整业务示例、Flutter 渲染实现。