# TimePicker 使用文档
本文档介绍 AtomUI TimePicker 和 RangeTimePicker 控件的各种使用方式，示例代码摘自 Gallery 演示程序。
> 📖 Gallery 源码位置：`controlgallery/AtomUIGallery/ShowCases/Views/DataEntry/TimePickerShowCase.axaml`
---
## 前置准备
在 AXAML 中使用 TimePicker，需要引入以下命名空间：
```xml
xmlns:atom="https://atomui.net"
xmlns:antdicons="https://atomui.net/icons/antdesign"
```
在 C# 代码中引入：
```csharp
using AtomUI.Desktop.Controls; // TimePicker, RangeTimePicker 控件
using AtomUI.Controls; // SizeType 等共享类型
```
---
## 1. 基本用法
最简单的 TimePicker 用法，点击输入框弹出时间选择面板：
```xml
```
默认配置下：
- 使用 24 小时制
- 显示"此刻"快捷按钮
- 不需要点击确认（双击选项或点击"此刻"直接应用）
---
## 2. 确认模式
启用确认模式后，用户需要点击"确定"按钮才会应用选择的时间：
```xml
```
---
## 3. 时钟格式（12/24 小时制）
通过 `ClockIdentifier` 属性切换时钟格式：
```xml
```
12 小时制下，弹出面板会增加 AM/PM（上午/下午）选择列。
---
## 4. 三种尺寸
通过 `SizeType` 属性设置尺寸，支持 `Large`、`Middle`（默认）、`Small` 三种：
```xml
```
---
## 5. 禁用状态
通过 `IsEnabled="False"` 禁用时间选择器：
```xml
```
---
## 6. 步进选择
通过 `MinuteIncrement` 和 `SecondIncrement` 控制分钟和秒钟列的候选项粒度：
```xml
```
设置 `MinuteIncrement="15"` 后，分钟列仅显示 `00`、`15`、`30`、`45` 四个选项。
---
## 7. 样式变体（Variants）
TimePicker 支持三种样式变体：Outline（默认）、Filled、Borderless。
```xml
```
---
## 8. 验证状态（Status）
通过 `Status` 属性设置验证状态反馈：
```xml
```
---
## 9. 时间范围选择器（RangeTimePicker）
使用 `RangeTimePicker` 选择时间范围，提供起始和结束两个输入框：
```xml
```
**交互流程**：
1. 点击起始输入框 → 弹出面板 → 选择起始时间
2. 如果结束时间为空 → 自动切换到结束输入框
3. 两个时间都选定后 → 自动关闭面板
RangeTimePicker 也支持确认模式：
```xml
```
---
## 10. 默认值
通过 `DefaultTime` 设置控件加载时的默认时间：
```xml
```
---
## 11. MVVM 数据绑定
TimePicker 的 `SelectedTime` 属性支持双向绑定，可在 MVVM 模式下使用：
```xml
```
```csharp
// ViewModel（使用 ReactiveUI）
public class MyViewModel : ReactiveObject
{
[Reactive]
public TimeSpan? SelectedTime { get; set; }
}
```
RangeTimePicker 的 `RangeStartSelectedTime` 和 `RangeEndSelectedTime` 同样支持双向绑定：
```xml
```
---
## 12. Code-Behind 操作
在代码中操作 TimePicker：
```csharp
// 获取选中时间
TimeSpan? selectedTime = myTimePicker.SelectedTime;
// 设置时间
myTimePicker.SelectedTime = new TimeSpan(14, 30, 0);
// 清除值（不考虑默认值）
myTimePicker.Clear();
// 重置为默认值
myTimePicker.Reset();
// 关闭弹出面板
myTimePicker.ClosePickerFlyout();
```
---
## 常见组合模式
### 表单中的时间选择
```xml
```
### 时间范围筛选
```xml
工作时段：
```
### 12 小时制 + 确认模式
```xml
```
### 步进选择 + 紧凑尺寸
```xml
```