前端跨平台桌面应用移动开发【免费下载链接】fletBuild 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 代码。什么是 CupertinoTimerPickerModeCupertinoTimerPickerMode是CupertinoTimerPicker控件的mode属性的取值类型它决定倒计时选择器以「小时-分钟」「小时-分钟-秒」「分钟-秒」中的哪一种粒度来展示时间。在 Flet 中它是一个标准的Enum类型每个成员都有一个对应的字符串序列化值用于在 Python 侧与 Flutter 渲染端之间传递枚举成员字符串值显示粒度显示示例HOUR_MINUTEhm小时、分钟16 hours \| 14 minHOUR_MINUTE_SECONDShms小时、分钟、秒16 hours \| 14 min \| 43 secMINUTE_SECONDSms分钟、秒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( valueft.Duration(seconds754), # 初始倒计时时长 modeft.CupertinoTimerPickerMode.HOUR_MINUTE_SECONDS, # 显示粒度 )当value以整数传入时会被视为秒数例如value300等价于 5 分钟。mode 的默认值mode属性的默认值是CupertinoTimerPickerMode.HOUR_MINUTE_SECONDScupertino_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( width340, padding12, borderft.Border.all(1, ft.Colors.RED), border_radius10, bgcolorft.Colors.SURFACE_CONTAINER_LOW, contentft.Column( spacing8, controls[ ft.Text(mode.name, weightft.FontWeight.BOLD), ft.CupertinoTimerPicker( modemode, valueft.Duration(seconds754), ), ], ), ) def main(page: ft.Page): page.horizontal_alignment ft.CrossAxisAlignment.CENTER page.appbar ft.AppBar(titleCupertinoTimerPickerMode Showcase) page.add( ft.SafeArea( expandTrue, contentft.Column( controls[ ft.Text(Compare timer picker layouts.), ft.Row( wrapTrue, spacing12, expandTrue, scrollft.ScrollMode.AUTO, alignmentft.MainAxisAlignment.CENTER, controls[ showcase_card(mode) for mode in ft.CupertinoTimerPickerMode ], ), ], ), ) ) if __name__ __main__: ft.run(main)运行这段代码页面上会并排展示三种模式的选择器可以直观对比同一时长ft.Duration(seconds754)即 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( value00:01:10, size23, colorft.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( value300, second_interval10, minute_interval1, modeft.CupertinoTimerPickerMode.HOUR_MINUTE_SECONDS, on_changehandle_timer_picker_change, ) page.add( ft.SafeArea( contentft.Row( tightTrue, controls[ ft.Text(TimerPicker Value:, size23), ft.CupertinoButton( on_clicklambda _: page.show_dialog( ft.CupertinoBottomSheet( height216, paddingft.Padding.only(top6), contenttimer_picker, ) ), contenttimer_value_text, ), ], ), ) ) if __name__ __main__: ft.run(main)该示例展示了与模式选择配套的完整属性组合value300以整数秒形式设置初始值这里表示 5 分钟second_interval10秒滚轮的粒度此处意味着滚轮只能选中 0、10、20、30、40、50 秒minute_interval1分钟滚轮的粒度按整分钟递增on_change用户滚动滚轮改变时长时触发回调e.data中携带新的时长值。关于 on_change 返回值的类型on_change事件回调的数据类型与value属性保持严格一致cupertino_timer_picker.py如果value是Duration那么e.data也是Duration如果value是整数秒则e.data也是整数秒。上述示例中value300是整数因此回调里直接用time.gmtime(e.data)格式化即可。这一「保留原始类型」的行为在 Flutter 端也有对应实现onTimerDurationChanged回调中会判断控件原始value是否为int是则把事件数据转换为秒数否则保留完整的Durationcupertino_timer_picker.dart。模式与间隔参数的校验规则使用不同的mode时还需要注意value、minute_interval、second_interval之间的约束关系。从CupertinoTimerPicker.before_update的实现cupertino_timer_picker.py可以看出控件在每次更新前会执行一系列校验不满足条件会抛出ValueErrorvalue必须是非负时长即不能小于0value必须严格小于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_interval10那么value的秒数必须是 10 的倍数否则控件会拒绝更新并抛出异常。设计倒计时功能时应确保初始值与滚轮粒度对齐。其他常用属性速查除mode外CupertinoTimerPicker还提供以下属性用于定制外观与行为定义于 cupertino_timer_picker.py属性默认值说明valueDuration()0 时长初始倒计时时长传整数则视为秒alignmentAlignment.CENTER选择器在其父级中的对齐方式second_interval1秒滚轮的粒度必须为 60 的因子minute_interval1分钟滚轮的粒度必须为 60 的因子bgcolorNone选择器背景色item_extent32.0所有滚轮子项的统一高度on_changeNone时长变化时的回调事件Flutter 端对这些属性的解析同样可以在 cupertino_timer_picker.dart 中找到一一对应关系包括默认值minute_interval1、second_interval1、item_extent32.0、alignmentAlignment.center。测试验证仓库的集成测试test_cupertino_timer_picker.py对上述用法给出了可验证的样例测试将value300、second_interval10、minute_interval1、modeHOUR_MINUTE_SECONDS的选择器放入CupertinoBottomSheet弹层中展示并开启截图断言。这从侧面确认了「模式 间隔 弹层」组合是官方推荐且经过验证的用法也是你调试自己页面时可以参考的对照基准。总结CupertinoTimerPickerMode用三个成员覆盖了 iOS 倒计时选择器的全部显示粒度需要小时级时长用HOUR_MINUTE需要精确到秒用HOUR_MINUTE_SECONDS默认模式时长较短且无需小时用MINUTE_SECONDS。实际使用时结合value、minute_interval、second_interval、on_change等属性即可快速构建出符合 iOS 交互习惯的倒计时设置界面同时注意值域与间隔的校验规则避免更新时抛出ValueError。相关源码与示例均可直接在仓库中查阅Python 控件定义、模式对比演示、完整业务示例、Flutter 渲染实现。赞分享前端跨平台桌面应用移动开发【免费下载链接】fletBuild realtime web, mobile and desktop apps in Python only. No frontend experience required.项目地址https://gitcode.com/gh_mirrors/fl/flet点击查看免费下载相关推荐Flet CupertinoTimerPicker 完全指南用 Python 构建 iOS 风格倒计时选择器的属性、事件与底层实现Flet CupertinoTimerPicker 完全指南用 Python 构建 iOS 风格倒计时选择器的属性、事件与底层实现 CupertinoTime前端跨平台桌面应用移动开发Flet CardVariant 枚举详解为 Card 控件选择 elevated、filled、outlined 三种 Material 视觉变体Flet CardVariant 枚举详解为 Card 控件选择 elevated、filled、outlined 三种 Material 视觉变体 Flet前端跨平台桌面应用移动开发Flet CupertinoDatePicker 控件完全指南iOS 风格日期与时间选择器Flet CupertinoDatePicker 控件完全指南iOS 风格日期与时间选择器 CupertinoDatePicker 是 Flet 中复刻 iO前端跨平台桌面应用移动开发创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考