syncfusion-wpf-timespan-editor

实现 Syncfusion WPF TimeSpanEdit

TimeSpanEdit 控件允许用户以 天:小时:分钟:秒（d.h:m:s）格式设置或显示时间，并支持键盘和鼠标交互、自定义格式设置及主题。

何时使用此技能

在以下情况下，请使用 TimeSpanEdit 控件：

• 在 WPF 应用程序中捕获或显示时间长度/间隔
• 通过友好的界面提供天:小时:分钟:秒输入
• 允许用户使用键盘、鼠标滚轮或按钮增加/减少时间值
• 使用自定义格式和标签显示时间（例如，“5 天，3 小时，15 分钟，30 秒”）
• 应用最小值/最大值限制，以限定允许的时间范围
• 支持空值，并在空状态下显示水印文本
• 使用颜色、主题和 RTL 支持设置控件样式

组件概览

主要功能：

• ✓ 以天:小时:分钟:秒格式显示时间（支持毫秒）
• ✓ 支持通过程序和用户操作更改值
• ✓ 在字段之间进行键盘导航（方向键）
• ✓ 支持鼠标滚轮和单击拖动交互
• ✓ 自定义格式字符串和字段标签
• ✓ 最小值/最大值约束
• ✓ ValueChanged 事件通知
• ✓ 适用于仅显示场景的只读模式
• ✓ 支持空值和水印
• ✓ 主题集成（SfSkinManager、ThemeStudio）
• ✓ 支持 RTL（从右到左）流向

---

文档指南

主题	文件	重点
设置	getting-started.md	安装 NuGet，通过 Designer/XAML/C# 添加
格式	value-and-formats.md	自定义格式字符串、标签、毫秒
交互	user-interactions.md	键盘、鼠标、按钮、拖动、方向键
约束和事件	constraints-and-events.md	最小值/最大值、ValueChanged 事件、验证
外观	appearance-and-theming.md	颜色、主题、RTL、SfSkinManager

---

快速入门示例

XAML：

<Window xmlns:syncfusion="http://schemas.syncfusion.com/wpf">
    <Grid>
        
        <syncfusion:TimeSpanEdit 
            x:Name="timeSpanEdit"
            Value="5.12:30:45"
            Width="150"
            Height="30" />
    </Grid>
</Window>

C# 代码隐藏：

using Syncfusion.Windows.Shared;

public partial class MainWindow : Window {
    public MainWindow() {
        InitializeComponent();
        
        // Create and configure TimeSpanEdit
        TimeSpanEdit editor = new TimeSpanEdit();
        editor.Value = new TimeSpan(5, 12, 30, 45);
        editor.Width = 150;
        editor.Height = 30;
        
        this.Content = editor;
    }
}

程序集引用： 将其添加到 WPF 项目中：

• Syncfusion.Shared.WPF

---

常见模式

使用场景	XAML 设置
带约束	MinValue="2.00:00:00" MaxValue="10.00:00:00"
自定义格式	Format="d 'days' h 'hours' m 'minutes' s 'seconds'"
精确间隔	StepInterval="1.00:15:30" IncrementOnScrolling="True"
只读	IsReadOnly="True" ShowArrowButtons="False"
可空	AllowNull="True" NullString="Enter duration..."

快速示例：

<syncfusion:TimeSpanEdit 
    Value="5.08:30:00"
    MinValue="2.00:00:00"
    MaxValue="10.00:00:00"
    Format="d 'days' h 'hours'" />

---

关键属性参考

属性	类型	默认值	用途
Value	TimeSpan?	0.0:0:0	要显示或编辑的时间长度
Format	string	d.h:m:s	自定义格式字符串（d=天，h=小时，m=分钟，s=秒，z=毫秒）
MinValue	TimeSpan	—	允许的最短时间长度
MaxValue	TimeSpan	—	允许的最长时间长度
StepInterval	TimeSpan	1.01:01:01	按钮、滚轮或键盘的增减间隔
AllowNull	bool	false	允许 null/空值
NullString	string	""	值为 null 时显示的水印文本
ShowArrowButtons	bool	true	显示向上/向下微调按钮
IncrementOnScrolling	bool	true	允许使用鼠标滚轮更改值
EnableExtendedScrolling	bool	false	允许单击并拖动来更改值
IsReadOnly	bool	false	禁止用户编辑（只读模式）
Background	Brush	White	控件背景颜色
Foreground	Brush	Black	文本颜色
SelectionBrush	Brush	RoyalBlue	选中内容的高亮颜色
FlowDirection	FlowDirection	LeftToRight	RTL 支持（RightToLeft）

---

常见用例

场景	关键设置
输入时长	启用按钮、滚轮和键盘；设置 Min/Max；使用标签
仅显示	IsReadOnly="True" ShowArrowButtons="False"；使用清晰的格式
精确控制	设置 StepInterval（例如 15 分钟）；使用键盘逐字段输入
灵活输入	启用所有交互；使用合理的步进间隔；提供视觉反馈

---

后续步骤

1. 从入门指南开始：阅读 getting-started.md 以设置控件
2. 设置显示格式：查看 value-and-formats.md 了解自定义格式
3. 启用交互：阅读 user-interactions.md 以获得最佳用户体验
4. 添加逻辑：使用 constraints-and-events.md 了解事件和限制
5. 设置样式：通过 appearance-and-theming.md 应用颜色和主题