企业官网建设流程全解析

Flet DatePickerEntryMode 完全指南：掌握日期选择器的四种输入模式

【免费下载链接】fletBuild realtime web, mobile and desktop apps in Python only. No frontend experience required.项目地址: https://gitcode.com/gh_mirrors/fl/flet

DatePickerEntryMode是 Flet 中定义日期选择器（DatePicker/DateRangePicker）日期录入方式的枚举类型，它决定了用户在对话框中选择日期时看到的是日历网格（Calendar）还是可输入文本的输入框（Input）。通过本指南，你将完整掌握该枚举的四个取值及其适用场景、如何在DatePicker与DateRangePicker中配置entry_mode、如何在运行时动态切换模式、如何通过on_entry_mode_change事件感知用户的操作，以及模式切换图标的定制方法。

认识 DatePickerEntryMode

DatePickerEntryMode定义于 date_picker.py 中，是标准 Python 的Enum类型，被DatePicker与DateRangePicker两个控件共同引用。它的文档注释（docstring）明确说明其职责：决定日期选择器对话框的日期录入方式（Mode of date entry method for the date picker dialog）。

该枚举共包含四个取值：

从源码结构看，前两个值（CALENDAR、INPUT）是可互相切换的“软”模式，后两个值（CALENDAR_ONLY、INPUT_ONLY）是锁定单一录入方式的“硬”模式。这一设计与 Flutter Material 的DatePickerEntryMode一一对应，Flet 通过 Dart 侧的解析函数将其映射到 Flutter 原生实现。

四种模式的适用场景

• CALENDAR（默认）：最通用的模式，适合大多数触屏与桌面场景，用户通过直观的点选完成日期选择；同时保留输入框入口，方便习惯键盘输入的用户。
• INPUT：适合日期格式对用户来说非常明确的场景（例如输入出生日期），减少日历翻页操作；也适合移动端需要快速调出系统键盘录入的场景。
• CALENDAR_ONLY：当业务规则强制要求用户“看着日历选”，不希望出现自由文本输入导致格式错误或歧义时使用，例如订票系统的出发日期选择。
• INPUT_ONLY：当希望最大化录入效率、且日期格式有严格校验兜底时使用，例如表单中的到期日字段。

在代码中配置 entry_mode

entry_mode是DatePicker的一个公开属性，默认值为DatePickerEntryMode.CALENDAR（见 date_picker.py）。直接在构造时指定即可：

import datetime import flet as ft def main(page: ft.Page): picker = ft.DatePicker( entry_mode=ft.DatePickerEntryMode.INPUT, # 以输入框模式打开 first_date=datetime.datetime(year=2024, month=1, day=1), last_date=datetime.datetime(year=2025, month=12, day=31), ) page.add( ft.Button( "Pick date", icon=ft.Icons.CALENDAR_MONTH, on_click=lambda _: page.show_dialog(picker), ) ) ft.run(main)

DateRangePicker同样接收entry_mode属性，默认值同样是CALENDAR（见 date_range_picker.py），因此上述设置方式对范围日期选择器同样生效。

运行时动态切换模式

entry_mode是一个可写属性，可以在对话框打开前动态修改。官方示例 showcase/main.py 展示了这一典型用法：为每一种模式生成一张卡片，点击按钮后先设置entry_mode，再通过page.show_dialog(picker)打开选择器。

import datetime import flet as ft def main(page: ft.Page): page.horizontal_alignment = ft.CrossAxisAlignment.CENTER today = datetime.datetime.now() picker = ft.DatePicker( first_date=datetime.datetime(year=today.year - 1, month=1, day=1), last_date=datetime.datetime(year=today.year + 1, month=12, day=31), ) def open_picker(entry_mode: ft.DatePickerEntryMode): picker.entry_mode = entry_mode # 动态指定录入模式 picker.date_picker_mode = ft.DatePickerMode.DAY page.show_dialog(picker) def showcase_card(entry_mode: ft.DatePickerEntryMode) -> ft.Container: return ft.Container( width=320, 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(entry_mode.name, weight=ft.FontWeight.BOLD), ft.Button( "Open DatePicker", icon=ft.Icons.CALENDAR_MONTH, on_click=lambda _, m=entry_mode: open_picker(m), ), ], ), ) page.add( ft.SafeArea( expand=True, content=ft.Column( controls=[ ft.Row( wrap=True, spacing=12, expand=True, scroll=ft.ScrollMode.AUTO, alignment=ft.MainAxisAlignment.CENTER, controls=[showcase_card(m) for m in ft.DatePickerEntryMode], ), ], ), ) ) if __name__ == "__main__": ft.run(main)

这段代码有两个值得注意的细节：

1. 通过for m in ft.DatePickerEntryMode直接遍历枚举，自动生成四张展示卡片，卡片标题即枚举成员名（entry_mode.name），便于直观对比四种模式的交互差异；
2. 使用lambda _, m=entry_mode: open_picker(m)以默认参数绑定当前枚举值，避免闭包捕获循环变量的经典陷阱。

监听模式切换事件

当用户通过对话框内部的模式按钮在CALENDAR与INPUT之间手动切换时，Flet 会触发on_entry_mode_change事件。该事件携带DatePickerEntryModeChangeEvent事件对象，其entry_mode字段保存切换后的新模式（见 date_picker.py 与 date_picker.py）。

import flet as ft def on_entry_mode_change(e: ft.DatePickerEntryModeChangeEvent): print("Entry mode changed to:", e.entry_mode) # 例如 DatePickerEntryMode.INPUT picker = ft.DatePicker( entry_mode=ft.DatePickerEntryMode.CALENDAR, on_entry_mode_change=on_entry_mode_change, )

在 Dart 侧，事件回调实现于 date_picker.dart：当 Flutter 的DatePickerDialog.onDatePickerModeChange被触发时，Flet 先将新的模式名回写为控件属性（updateProperties({"entry_mode": mode.name})），再通过triggerEvent("entry_mode_change", ...)通知 Python 端。这意味着事件发生后，Python 侧picker.entry_mode的值也会同步更新，你可以据此在事件处理器中读取最新模式而无需手动回写。

模式切换图标定制

在可切换的模式（CALENDAR↔INPUT）下，对话框角落会出现一个模式切换图标，这两个图标均可通过属性定制（见 date_picker.py）：

• switch_to_calendar_icon：当entry_mode为INPUT时显示，点击后将模式切换为CALENDAR。默认值为Icons.CALENDAR_TODAY。
• switch_to_input_icon：当entry_mode为CALENDAR时显示，点击后将模式切换为INPUT。默认值为Icons.EDIT_OUTLINED。

import flet as ft picker = ft.DatePicker( entry_mode=ft.DatePickerEntryMode.CALENDAR, switch_to_calendar_icon=ft.Icons.CALENDAR_MONTH, # 自定义“切到日历”图标 switch_to_input_icon=ft.Icons.KEYBOARD_OUTLINED, # 自定义“切到输入”图标 )

在 date_picker.dart 中，这两个图标通过control.getIconData(...)读取，随后包装为Icon传给 Flutter 的DatePickerDialog。需要说明的是：当entry_mode为CALENDAR_ONLY或INPUT_ONLY时，这两种模式“没有用户界面可切换到另一种模式”，因此对话框不会渲染上述切换图标。

与 entry_mode 联动的其他属性

在实际使用时，INPUT相关模式通常会与以下属性配合，以获得更好的录入体验（完整属性清单见 date_picker.py）：

例如，为INPUT模式定制中文提示与校验文案：

import datetime import flet as ft picker = ft.DatePicker( entry_mode=ft.DatePickerEntryMode.INPUT_ONLY, first_date=datetime.datetime(2024, 1, 1), last_date=datetime.datetime(2025, 12, 31), keyboard_type=ft.KeyboardType.NUMBER, field_hint_text="YYYY-MM-DD", field_label_text="请选择日期", error_format_text="日期格式不正确", error_invalid_text="日期超出可选范围", )

底层实现解析：从 Python 属性到 Flutter 对话框

DatePickerEntryMode的完整调用链清晰地展现了 Flet 的属性传递机制：

1. Python 端：DatePicker.entry_mode属性接收DatePickerEntryMode枚举，序列化时以其字符串值（如"inputOnly"）通过@control("DatePicker")装饰器生成控件协议；
2. Dart 端解析：time.dart 中的parseDatePickerEntryMode使用parseEnum将字符串解析为 Flutter 的DatePickerEntryMode，供 date_picker.dart 构造DatePickerDialog时作为initialEntryMode传入；
3. 双向同步：用户在对话框中切换模式后，Dart 端通过updateProperties把新模式回写到控件属性，并触发entry_mode_change事件返回 Python 端（见 date_picker.dart）。

小结

DatePickerEntryMode是 Flet 日期选择体系中的一个轻量但关键的枚举：四个取值分别对应“日历可切换”“输入可切换”“仅日历”“仅输入”四种交互策略，默认CALENDAR兼顾了绝大多数场景。搭配entry_mode动态赋值、on_entry_mode_change事件、切换图标定制以及field_*/error_*系列文案属性，可以在DatePicker与DateRangePicker中构建出符合业务要求的完整日期录入体验。如需动手验证，可直接运行官方示例 showcase/main.py，对比四种模式的交互差异。

【免费下载链接】fletBuild realtime web, mobile and desktop apps in Python only. No frontend experience required.项目地址: https://gitcode.com/gh_mirrors/fl/flet