Flet CupertinoDatePickerMode 完全指南：四种 iOS 日期选择模式详解

前端跨平台桌面应用移动开发【免费下载链接】fletBuild realtime web, mobile and desktop apps in Python only. No frontend experience required.项目地址https://gitcode.com/gh_mirrors/fl/flet点击查看免费下载本指南深入解析 Flet 中CupertinoDatePickerMode枚举类型的四种取值——TIME、DATE、DATE_AND_TIME与MONTH_YEAR。你将掌握每种模式的实际展示效果、与CupertinoDatePicker相关属性如use_24h_format、date_order、show_day_of_week的配合方式以及如何在真实应用中基于模式搭建完整的日期选择交互。CupertinoDatePickerMode 是什么CupertinoDatePickerMode是定义CupertinoDatePickeriOS 风格日期选择器展示模式的枚举类型在 Python SDK 中定义于 cupertino_date_picker.py。它直接对应 Flutter 原生控件CupertinoDatePicker.mode属性由 Dart 端在 cupertino_date_picker.dart 中解析映射。Flet 的日期选择器底层即 Flutter 的CupertinoDatePicker控件其mode参数决定选择器以何种滚轮组合呈现日期与时间。CupertinoDatePickerMode枚举共包含四个值枚举值字符串值展示内容示例TIMEtime时、分以及可选AM/PM 标识4 \| 14 \| PMDATEdate月份全称、日期、年份July \| 13 \| 2012DATE_AND_TIMEdateAndTime星期、月份、日期、时、分以及可选AM/PM 标识Fri Jul 13 \| 4 \| 14 \| PMMONTH_YEARmonthYear月份全称与年份July \| 2012在 Flet 中可通过ft.CupertinoDatePickerMode访问该枚举并通过CupertinoDatePicker.date_picker_mode属性指定模式其默认值为DATE_AND_TIME见 cupertino_date_picker.py。四种模式的详细行为TIME时间模式仅展示时、分滚轮。AM/PM 标识仅在选择器未使用 24 小时制时出现即use_24h_formatFalse默认值时显示若设置为True则直接以 24 小时制显示无 AM/PM 列。滚轮列顺序受国际化locale影响。DATE日期模式展示完整的月、日、年三列月份名以全称拼写如 July 而非 7。列顺序同样受 locale 影响同时受date_order属性与show_day_of_week属性影响。DATE_AND_TIME日期与时间模式同时展示日期与时间日期部分为星期、月份、日如Fri Jul 13时间部分为时、分及可选的 AM/PM。这是最常用、信息量最大的模式也是date_picker_mode属性的默认值。MONTH_YEAR年月模式仅展示月份与年份两列适合选择某年某月的场景如选择账单月份、信用卡有效期等。月份名以全称显示。关于 AM/PM 与 24 小时制的细节文档注释明确指出AM/PM 仅在CupertinoDatePicker不使用 24 小时格式时显示源码见 cupertino_date_picker.py。模式与相关属性的配合CupertinoDatePickerMode并非孤立存在它与选择器的多个属性深度联动理解这些联动是正确使用模式的前提。与 use_24h_format 的联动use_24h_format默认False决定时间类模式TIME、DATE_AND_TIME是否显示 AM/PM 列。设置为True时选择器以 24 小时制呈现如16:14而非4:14 PM。该属性的定义见 cupertino_date_picker.py。与 date_order 的联动date_order类型为CupertinoDatePickerDateOrder控制日期列日/月/年的排列顺序取值包括DAY_MONTH_YEARdmy、MONTH_DAY_YEARmdy、YEAR_MONTH_DAYymd、YEAR_DAY_MONTHydm源码见 cupertino_date_picker.py。文档明确指出最终的列顺序同时受date_picker_mode影响。例如在MONTH_YEAR模式下无论设置DAY_MONTH_YEAR还是MONTH_DAY_YEAR最终呈现的都是month | year顺序见 cupertino_date_picker.py。这与 iOS 原生行为一致——年月模式只关心月份与年份的相对位置。与 show_day_of_week 的联动show_day_of_week默认False用于在日期旁边同时显示星期几。它仅支持DATE模式若在其他模式下设置为Truebefore_update校验会抛出ValueErrorshow_day_of_week is only supported when date_picker_mode is CupertinoDatePickerMode.DATE校验逻辑见 cupertino_date_picker.py。与 first_date / last_date / minute_interval 的联动模式不同日期范围校验的粒度也不同在DATE_AND_TIME模式下value必须同时满足first_date value last_datecupertino_date_picker.py在DATE/MONTH_YEAR模式下除范围校验外还额外校验minimum_year与maximum_yearcupertino_date_picker.py文档特别提示在TIME模式下若某时间与value的日期部分组合后早于first_date或晚于last_date该时间将不可选因此通常建议将first_date/last_date设置为与value同一天的日期时间见 cupertino_date_picker.py。此外minute_interval默认1必须为 60 的因数且大于 0控制分钟滚轮的粒度若value.minute不是其倍数会触发ValueErrorcupertino_date_picker.py。实战模式展示 Demo官方为CupertinoDatePickerMode提供了可直接运行的演示程序路径为 showcase/main.py。该程序在一个页面中为四种模式各生成一张卡片点击卡片上的 Open picker 按钮即弹出对应的选择器方便对比不同模式的展示差异。from datetime import datetime import flet as ft def main(page: ft.Page): page.horizontal_alignment ft.CrossAxisAlignment.CENTER def showcase_card(mode: ft.CupertinoDatePickerMode) - ft.Container: def open_picker(_): picker ft.CupertinoDatePicker( date_picker_modemode, valuedatetime(2024, 7, 13, 16, 14), use_24h_formatTrue, ) page.show_dialog( ft.CupertinoBottomSheet( contentpicker, height216, paddingft.Padding.only(top6), ) ) return ft.Container( width320, 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.Button( Open picker, iconft.CupertinoIcons.CALENDAR, on_clickopen_picker, ), ], ), ) page.appbar ft.AppBar(titleCupertinoDatePickerMode Showcase) page.add( ft.SafeArea( expandTrue, contentft.Column( controls[ ft.Text( Open each mode in CupertinoBottomSheet to compare behavior. ), ft.Row( wrapTrue, spacing12, expandTrue, scrollft.ScrollMode.AUTO, alignmentft.MainAxisAlignment.CENTER, controls[ showcase_card(mode) for mode in ft.CupertinoDatePickerMode ], ), ], ), ) ) if __name__ __main__: ft.run(main)代码要点解读遍历全部枚举通过for mode in ft.CupertinoDatePickerMode一次性为四种模式生成展示卡片mode.name直接输出枚举名TIME、DATE、DATE_AND_TIME、MONTH_YEAR作为卡片标题统一初始值valuedatetime(2024, 7, 13, 16, 14)使四种模式在同一基准时间上对比展示效果配合 24 小时制use_24h_formatTrue关闭 AM/PM 列让示例在不同模式下更聚焦于列结构本身底部弹层容器选择器通过page.show_dialog搭配CupertinoBottomSheet高度216、顶部留白6以 iOS 底部弹层的形式呈现。运行方式在安装了flet的 Python 环境中执行python main.py即可启动应用需桌面或移动端运行环境支持。模式的选择建议场景推荐模式理由仅选择具体时间闹钟、提醒TIME聚焦时与分界面最简洁选择完整日期生日、活动日DATE月/日/年三列清晰可配合show_day_of_week显示星期日期与时间同时选择预约、排程DATE_AND_TIME信息最全为默认模式仅选择月份与年份账单周期、信用卡有效期MONTH_YEAR精简为两列避免无关粒度干扰源码视角模式如何从 Python 传递到 FlutterFlet 采用Python 描述属性 → JSON 协议传输 → Flutter 渲染的架构。CupertinoDatePickerMode的传递链路如下Python 端date_picker_mode属性保存枚举实例序列化时取其字符串值time/date/dateAndTime/monthYearDart 端解析CupertinoDatePickerControl的build方法调用widget.control.getCupertinoDatePickerMode(date_picker_mode, CupertinoDatePickerMode.dateAndTime)获取模式cupertino_date_picker.dart底层解析getCupertinoDatePickerMode经parseCupertinoDatePickerMode调用parseEnum将字符串值映射回 Flutter 的CupertinoDatePickerMode枚举time.dartFlutter 渲染解析得到的CupertinoDatePickerMode直接传给原生CupertinoDatePicker.mode完成滚轮布局渲染。该链路中parseEnum为通用枚举解析器传入未知字符串时返回默认值因此即使 Python 端传入非法值Dart 端也会安全回退到DATE_AND_TIME默认模式不会导致崩溃。另外值得注意的是Flutter 端的CupertinoDatePicker还支持通过Localizations.override针对单个选择器覆盖 localecupertino_date_picker.dart这正是 Flet 中CupertinoDatePicker.locale属性的实现基础。官方示例 custom_locale/main.py 展示了如何用ft.Locale(zh, Hans)让选择器以简体中文zh_Hans呈现——在中文 locale 下各模式的月份、星期名称会本地化显示进一步印证了列顺序与名称受国际化影响的文档说明。测试验证Flet 为CupertinoDatePicker提供了集成测试 test_cupertino_date_picker.py其中test_basic以DATE_AND_TIME模式渲染选择器并断言截图test_locale验证了localeft.Locale(zh, Hans)时的本地化渲染。这些测试一方面印证了DATE_AND_TIME作为默认模式的地位另一方面也验证了模式与 locale 的组合在实际渲染链路中稳定可用可作为你集成CupertinoDatePickerMode时编写自身测试的参考范本。赞分享前端跨平台桌面应用移动开发【免费下载链接】fletBuild realtime web, mobile and desktop apps in Python only. No frontend experience required.项目地址https://gitcode.com/gh_mirrors/fl/flet点击查看免费下载相关推荐Flet DatePickerEntryMode 完全指南掌握日期选择器的四种输入模式Flet DatePickerEntryMode 完全指南掌握日期选择器的四种输入模式 DatePickerEntryMode 是 Flet 中定义日期选择器前端跨平台桌面应用移动开发Flet TimePickerEntryMode 完全指南掌控时间选择器的四种输入模式Flet TimePickerEntryMode 完全指南掌控时间选择器的四种输入模式 flet.TimePickerEntryMode 是 Flet 中 M前端跨平台桌面应用移动开发Flet CupertinoDatePicker 控件完全指南iOS 风格日期与时间选择器Flet CupertinoDatePicker 控件完全指南iOS 风格日期与时间选择器 CupertinoDatePicker 是 Flet 中复刻 iO前端跨平台桌面应用移动开发创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考