TimePicker 继承自：DialogControl, AdaptiveControl, Control, BaseControl

Material 风格的时间选择器对话框。

可以通过调用 show_dialog 方法打开。

根据 entry_mode 的不同，它会显示表盘或输入框（小时和分钟文本字段）来选择时间。

示例：

ft.TimePicker(
    open=True,
    value=time(1, 2),
    entry_mode=ft.TimePickerEntryMode.INPUT_ONLY,
)

示例

from datetime import time

import flet as ft


def main(page: ft.Page):
    page.horizontal_alignment = ft.CrossAxisAlignment.CENTER

    def handle_change(e: ft.Event[ft.TimePicker]):
        selection.value = f"Selection: {time_picker.value}"
        page.show_dialog(ft.SnackBar(f"TimePicker change: {time_picker.value}"))

    def handle_dismissal(e: ft.Event[ft.DialogControl]):
        page.show_dialog(ft.SnackBar("TimePicker dismissed!"))

    def handle_entry_mode_change(e: ft.TimePickerEntryModeChangeEvent):
        page.show_dialog(ft.SnackBar(f"Entry mode changed: {time_picker.entry_mode}"))

    time_picker = ft.TimePicker(
        value=time(hour=19, minute=30),
        confirm_text="Confirm",
        error_invalid_text="Time out of range",
        help_text="Pick your time slot",
        entry_mode=ft.TimePickerEntryMode.DIAL,
        on_change=handle_change,
        on_dismiss=handle_dismissal,
        on_entry_mode_change=handle_entry_mode_change,
    )

    page.add(
        ft.SafeArea(
            content=ft.Column(
                horizontal_alignment=ft.CrossAxisAlignment.CENTER,
                controls=[
                    ft.Button(
                        key="pick_time_button",
                        content="Pick time",
                        icon=ft.Icons.TIME_TO_LEAVE,
                        on_click=lambda: page.show_dialog(time_picker),
                    ),
                    selection := ft.Text(weight=ft.FontWeight.BOLD),
                ],
            ),
        ),
    )


if __name__ == "__main__":
    ft.run(main)

from datetime import time

import flet as ft


def main(page: ft.Page):
    page.horizontal_alignment = ft.CrossAxisAlignment.CENTER

    def get_system_hour_format():
        """Returns the current system's hour format."""
        return "24h" if page.media.always_use_24_hour_format else "12h"

    def format_time(value: time) -> str:
        """Returns a formatted time string based on TimePicker and system settings."""
        use_24h = time_picker.hour_format == ft.TimePickerHourFormat.H24 or (
            time_picker.hour_format == ft.TimePickerHourFormat.SYSTEM
            and page.media.always_use_24_hour_format
        )
        return value.strftime("%H:%M" if use_24h else "%I:%M %p")

    def handle_change(e: ft.Event[ft.TimePicker]):
        selection.value = f"Selection: {format_time(time_picker.value)}"

    time_picker = ft.TimePicker(
        value=time(hour=19, minute=30),
        help_text="Choose your meeting time",
        on_change=handle_change,
    )

    def open_picker(e: ft.Event[ft.Button]):
        choice = format_dropdown.value
        hour_format_map = {
            "system": ft.TimePickerHourFormat.SYSTEM,
            "12h": ft.TimePickerHourFormat.H12,
            "24h": ft.TimePickerHourFormat.H24,
        }
        time_picker.hour_format = hour_format_map[choice]
        page.show_dialog(time_picker)

    page.add(
        ft.SafeArea(
            content=ft.Column(
                horizontal_alignment=ft.CrossAxisAlignment.CENTER,
                controls=[
                    ft.Row(
                        alignment=ft.MainAxisAlignment.CENTER,
                        controls=[
                            format_dropdown := ft.Dropdown(
                                label="Hour format",
                                value="system",
                                width=260,
                                key="dd",
                                options=[
                                    ft.DropdownOption(
                                        key="system",
                                        text=(
                                            f"System default "
                                            f"({get_system_hour_format()})"
                                        ),
                                    ),
                                    ft.DropdownOption(key="12h", text="12-hour clock"),
                                    ft.DropdownOption(key="24h", text="24-hour clock"),
                                ],
                            ),
                            ft.Button(
                                "Open TimePicker",
                                icon=ft.Icons.SCHEDULE,
                                on_click=open_picker,
                            ),
                        ],
                    ),
                    selection := ft.Text(weight=ft.FontWeight.BOLD),
                ],
            ),
        ),
    )


if __name__ == "__main__":
    ft.run(main)

from datetime import time

import flet as ft


def main(page: ft.Page):
    page.horizontal_alignment = ft.CrossAxisAlignment.CENTER

    page.add(
        ft.SafeArea(
            content=ft.Button(
                key="custom_locale_button",
                content="Pick time (zh_Hans locale)",
                icon=ft.Icons.CALENDAR_MONTH,
                on_click=lambda e: page.show_dialog(
                    ft.TimePicker(
                        value=time(hour=19, minute=30),
                        locale=ft.Locale("zh", "Hans"),
                    )
                ),
            ),
        )
    )


if __name__ == "__main__":
    ft.run(main)

属性

名称	类型	默认值	说明
value	Optional[time]	datetime.now().time(()	此选择器应显示的已选时间。 默认值等于当前时间。
locale	Optional[Locale]	None	此时间选择器对话框的区域设置。它用于（罕见的）需要让此对话框的区域设置与页面其余部分不同的情况。 它会覆盖页面使用的区域设置（见 locale_configuration），但不参与页面级的区域设置解析。 如果设为 None（默认）或不存在／不支持的区域设置，则回退使用 locale_configuration 的 current_locale。
modal	bool	False	是否禁止通过点击此选择器外部区域将其关闭。
entry_mode	TimePickerEntryMode	TimePickerEntryMode.DIAL	此选择器的初始时间输入方式。 默认为 DIAL。
hour_label_text	Optional[str]	None	显示在小时输入文本字段下方的文本。 默认值为 "Hour"。
minute_label_text	Optional[str]	None	显示在分钟输入文本字段下方的文本。 默认值为 "Minute"。
help_text	Optional[str]	None	显示在标题顶部的文本。 用于向用户说明他们正在为哪件事选择时间。默认值为 "Enter time"。
cancel_text	Optional[str]	None	显示在取消按钮上的文本。 默认值为 "Cancel"。
confirm_text	Optional[str]	None	显示在确认按钮上的文本。 默认值为 "OK"。
error_invalid_text	Optional[str]	None	当输入不是有效的小时／分钟时，显示在输入文本字段下方的错误消息。 默认值为 "Enter a valid time"。
orientation	Optional[Orientation]	None	显示时对话框的方向。
barrier_color	Optional[ColorValue]	None	使此选择器对话框下方所有内容变暗的模态遮罩颜色。 若为 None，则使用 barrier_color。若它也为 None，则使用 BLACK_54。
switch_to_timer_icon	Optional[IconData]	None	当 entry_mode 为 INPUT 时，显示在此选择器对话框角落的图标。 点击此图标会将 entry_mode 更改为 DIAL。 若为 None，默认为 Icons.ACCESS_TIME。
switch_to_input_icon	Optional[IconData]	None	当 entry_mode 为 DIAL 时，显示在此选择器对话框角落的图标。 点击此图标会将 entry_mode 更改为 INPUT。 若为 None，默认为 Icons.KEYBOARD_OUTLINED。
hour_format	TimePickerHourFormat	TimePickerHourFormat.SYSTEM	定义此时间选择器的小时格式。
open	bool	False	设为 True 以显示此对话框。
adaptive	Optional[bool]	None	启用平台特定渲染，或从父控件继承自适应能力。
expand	Annotated[Optional[Union[bool, int]], V.instance_of((bool, int))]	None	指定此控件是否／如何扩展以填满父布局中的可用空间。 更多信息见此处。 注意： 仅当此控件的直接父级是以下控件或其子类时才生效：Column、Row、View、Page。 抛出异常： ValueError：如果它不是 bool 或 int 类型。
expand_loose	bool	False	允许控件在主轴方向有可用空间时扩展，但不要求它填满所有可用空间。 更多信息见此处。 注意： 如果 expand_loose 为 True，则仅在以下条件满足时才生效： - expand 不为 None，且 - 此控件的直接父级是以下控件或其子类之一：Column、Row、View、Page。
col	ResponsiveNumber	12	如果此控件的父级是 ResponsiveRow，则此属性决定该控件在屏幕上跨越多少虚拟列。 可以是一个数字，也可以是一个按断点配置不同值的字典，例如 col={"sm": 6}。 值为 0 时会在该断点隐藏控件，因此它不会占用父级 ResponsiveRow 中的任何列。 此控件默认跨越 12 个虚拟列。 | 断点 | 尺寸 | |---|---| | xs | <576px | | sm | ≥576px | | md | ≥768px | | lg | ≥992px | | xl | ≥1200px | | xxl | ≥1400px |
opacity	Annotated[Number, V.between(0.0, 1.0)]	1.0	定义控件的透明度。 取值范围从 0.0（完全透明）到 1.0（完全不透明，无任何透明感）。 抛出异常： ValueError：如果它不在 0.0 到 1.0（含）之间。
tooltip	Optional[TooltipValue]	None	鼠标悬停在此控件上时显示的工具提示。
badge	Optional[BadgeValue]	None	显示在此控件顶部的徽章。
visible	bool	True	每个控件都有 visible 属性，默认为 True —— 控件会渲染在页面上。将 visible 设为 False 会彻底阻止控件（及其所有子控件，如果有）渲染到页面画布上。隐藏的控件无法通过键盘或鼠标获得焦点或选中，也不会触发任何事件。
disabled	bool	False	每个控件都有 disabled 属性，默认为 False —— 控件及其所有子控件都处于启用状态。 注意： 此属性的值会递归向下传播到所有子控件。 示例： 例如，如果你有一个包含多个输入控件的表单，可以通过禁用容器来一并禁用它们： python ft.Column( disabled = True, controls=[ ft.TextField(), ft.TextField() ] )
rtl	bool	False	控件的文本方向是否为从右到左（RTL）。
data	Any	skip_	任意类型的自定义数据。
key	Optional['KeyValue']	None	用于在更新之间保持控件标识稳定的键。

只读属性

名称	类型	默认值	说明
parent	Optional['BaseControl']	—	此控件的直接祖先（父级）。 默认为 None，只有在此控件被挂载（加入页面树）后才有值。 Page 控件（页面树的根）是个例外 —— 它的 parent 始终为 None。
page	'Page'	—	此控件所属的页面。

事件

名称	类型	默认值	说明
on_change	Optional[ControlEventHandler['TimePicker']]	None	当用户点击确认按钮时调用。 value 属性会更新为所选时间。此外，事件处理器参数的 data 属性也包含所选时间。
on_entry_mode_change	Optional[EventHandler[TimePickerEntryModeChangeEvent]]	None	当通过时间选择器对话框更改 entry_mode 时调用。
on_dismiss	Optional[ControlEventHandler['DialogControl']]	None	当对话框被关闭时调用。

方法

名称	类型	默认值	说明
is_isolated	—	—	返回此控件是否被标记为隔离。 隔离控件会被排除在父级驱动的更新遍历之外，并需要自行管理更新边界。
init	—	—	在控件实例初始化之后、第一次 build / update 周期之前调用。 重写此钩子以执行依赖已初始化字段的轻量级设置。不要在此处调用 update()。
build	—	—	在控件初始化期间调用一次，用于定义其子控件。在此方法中 page 属性可用。
before_update	—	—	每当此控件被更新时都会调用此方法。 注意： 务必不要在此处调用或请求 update()。
before_event	—	—	在事件处理器执行之前拦截事件。 返回 False 可取消分发。返回 True 或 None 则继续正常的事件处理。
did_mount	—	—	在控件挂载到页面树之后调用。 重写此方法以启动需要已挂载页面的资源，例如订阅、定时器或服务监听器。
will_unmount	—	—	在控件从页面树移除之前调用。 重写此方法以释放 did_mount() 中创建的资源，例如订阅、定时器或外部句柄。
get_data_channel	—	—	解析为此 widget 在 Dart 侧分配的 [DataChannel]。模式： on_data_channel_open: Optional[ft.EventHandler[DataChannelOpenEvent]] = None def init(self): self.on_data_channel_open = self._on_open def _on_open(self, e): self._channel = self.get_data_channel(e.channel_id) 幂等 —— 底层的 Connection 会按 id 缓存 DataChannel，因此重复调用会返回同一实例。没有错误路径：该 id 始终来自框架触发的事件，所以当此方法运行时，通道在两端都已存在。
update	None	—	为此控件请求一次 UI 更新。 在更改控件状态或属性后调用。控件必须已挂载到页面且未被标记为冻结。