AtomUI/docs/Desktop.Controls/TimePicker/TimePickerAPI.md

TimePicker API 参考

命名空间

namespace AtomUI.Desktop.Controls;

AXAML 命名空间前缀：atom（xmlns:atom="https://atomui.net"）

---

枚举类型

ClockIdentifierType

时钟格式枚举，定义 12 小时制或 24 小时制。

值	说明
HourClock12	12 小时制，面板额外显示 AM/PM 列
HourClock24	24 小时制（默认）

InputControlStyleVariant（来自 AtomUI.Controls）

输入控件样式变体枚举。

值	说明
Outline	带边框的标准样式（默认）
Filled	填充背景样式
Borderless	无边框样式

InputControlStatus（来自 AtomUI.Controls）

输入控件验证状态枚举。

值	说明
Default	默认状态
Warning	警告状态（黄色系）
Error	错误状态（红色系）

SizeType（来自 AtomUI.Controls）

尺寸类型枚举。

值	说明
Small	小号
Middle	中号（默认）
Large	大号

---

TimePicker 公共属性（StyledProperty）

TimePicker 特有属性

属性名	类型	默认值	说明
SelectedTime	TimeSpan?	null	当前选中的时间值，支持双向绑定和数据验证
DefaultTime	TimeSpan?	null	默认时间值。控件加载时若 SelectedTime 为 null 则自动设置为该值
ClockIdentifier	ClockIdentifierType	HourClock24	时钟格式，12 小时制或 24 小时制
MinuteIncrement	int	1	分钟列步进值，有效范围 1–59
SecondIncrement	int	1	秒钟列步进值，有效范围 1–59
IsNeedConfirm	bool	false	是否启用确认模式（面板底部显示"确定"按钮）
IsShowNow	bool	true	是否显示"此刻"快捷按钮

继承自 InfoPickerInput 的属性

属性名	类型	默认值	说明
SizeType	SizeType	SizeType.Middle	控件尺寸（共享属性）
StyleVariant	InputControlStyleVariant	Outline	样式变体（Outline / Filled / Borderless）
Status	InputControlStatus	Default	验证状态（Default / Warning / Error）
PlaceholderText	string?	null	占位提示文本
InfoIcon	PathIcon?	ClockCircleOutlined	右侧图标（默认为时钟图标）
PickerPlacement	PlacementMode	BottomEdgeAlignedLeft	弹出面板的放置位置
IsShowArrow	bool	false	弹出面板是否显示箭头
IsPointAtCenter	bool	false	弹出面板箭头是否指向中心
MarginToAnchor	double	由系统决定	弹出面板与锚点的间距
MouseEnterDelay	int	由系统决定	鼠标进入延迟（毫秒）
MouseLeaveDelay	int	由系统决定	鼠标离开延迟（毫秒）
IsReadOnly	bool	false	输入框是否只读
IsMotionEnabled	bool	跟随全局 Token	是否启用过渡动画（共享属性）
LeftAddOn	object?	null	输入框左侧附加内容
RightAddOn	object?	null	输入框右侧附加内容
ContentLeftAddOn	object?	null	内容区左侧附加内容
ContentRightAddOn	object?	null	内容区右侧附加内容

继承自 TemplatedControl 的常用属性

属性名	类型	默认值	说明
IsEnabled	bool	true	是否启用
FontSize	double	由 Token 控制	字体大小
FontFamily	FontFamily	由 Token 控制	字体族
Width	double	NaN（自动）	控件宽度
MinWidth	double	NaN	最小宽度
MaxWidth	double	NaN	最大宽度

---

RangeTimePicker 公共属性（StyledProperty）

RangeTimePicker 特有属性

属性名	类型	默认值	说明
RangeStartSelectedTime	TimeSpan?	null	起始时间值，支持双向绑定和数据验证
RangeEndSelectedTime	TimeSpan?	null	结束时间值，支持双向绑定和数据验证
RangeStartDefaultTime	TimeSpan?	null	起始时间默认值
RangeEndDefaultTime	TimeSpan?	null	结束时间默认值
MinuteIncrement	int	1	分钟列步进值，有效范围 1–59
SecondIncrement	int	1	秒钟列步进值，有效范围 1–59
ClockIdentifier	ClockIdentifierType	HourClock24	时钟格式
IsNeedConfirm	bool	false	是否启用确认模式
IsShowNow	bool	true	是否显示"此刻"快捷按钮

继承自 RangeInfoPickerInput 的属性

属性名	类型	默认值	说明
SecondaryPlaceholderText	string?	null	结束时间输入框的占位文本

其余属性与 TimePicker 继承自 InfoPickerInput 的属性一致。

---

公共方法

TimePicker

方法名	返回类型	说明
Clear()	void	将 SelectedTime 设为 null，不考虑默认值
Reset()	void	将 SelectedTime 重置为 DefaultTime
ClosePickerFlyout()	void	关闭弹出面板（继承自 InfoPickerInput）

RangeTimePicker

方法名	返回类型	说明
Clear()	void	将 RangeStartSelectedTime 和 RangeEndSelectedTime 都设为 null
Reset()	void	将起止时间重置为各自的默认值
ClosePickerFlyout()	void	关闭弹出面板（继承自 InfoPickerInput）

---

伪类（Pseudo-Classes）

TimePicker 和 RangeTimePicker 继承自 InfoPickerInput，支持以下伪类：

伪类	常量	触发条件
:flyout-open	InfoPickerPseudoClass.FlyoutOpen	弹出面板处于打开状态
:choosing	InfoPickerPseudoClass.Choosing	用户正在弹出面板中选择时间

继承的标准伪类

伪类	触发条件
:pointerover	鼠标悬浮在控件上
:disabled	IsEnabled == false
:focus	获得焦点
:focus-visible	通过键盘（Tab）获得焦点

---

实现的接口

ISizeTypeAware

public SizeType SizeType { get; set; }

IInputControlStyleVariantAware

public InputControlStyleVariant StyleVariant { get; set; }

IInputControlStatusAware

public InputControlStatus Status { get; set; }

IMotionAwareControl

public bool IsMotionEnabled { get; set; }

ICompactSpaceAware

在 Space.Compact 容器中使用时自动调整圆角和边框。

IFormItemAware

可作为 FormItem 的子控件参与表单验证流程。TimePicker 的表单值为 TimeSpan?，RangeTimePicker 的表单值为 (TimeSpan?, TimeSpan?)。

---

国际化资源

TimePicker 通过 LanguageProvider 系统提供以下可本地化字符串：

资源键	英文（en_US）	中文（zh_CN）	用途
AMText	"AM"	"上午"	12 小时制上午标识
PMText	"PM"	"下午"	12 小时制下午标识
Now	"Now"	"现在"	"此刻"快捷按钮文案

在 AXAML 中引用：{atom:TimePickerLangResource AMText}

---

键盘交互

弹出面板（TimePickerPresenter）支持以下键盘操作：

按键	行为
Escape	关闭面板（不应用选择）
Enter	确认选择并关闭面板
Tab	在面板内的时/分/秒列之间切换焦点