syncfusion-wpf-timespan-editor

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Implementing Syncfusion WPF TimeSpanEdit

实现Syncfusion WPF TimeSpanEdit控件

The TimeSpanEdit control allows users to set or display time as Days:Hours:Minutes:Seconds (d.h:m:s) format with support for keyboard and mouse interactions, custom formatting, and theming.

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

When to Use This Skill

适用场景

Use the TimeSpanEdit control when you need to:

Capture or display time durations/intervals in your WPF application
Provide Days:Hours:Minutes:Seconds input with a user-friendly interface
Enable users to increment/decrement time values using keyboard, mouse wheel, or buttons
Display time with custom formats and labels (e.g., "5 days, 3 hours, 15 minutes, 30 sec")
Apply min/max constraints to limit allowed time ranges
Support null values with watermark text for empty states
Style the control with colors, themes, and RTL support

在以下场景中可使用TimeSpanEdit控件：

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

Component Overview

组件概述

Key Capabilities:

✓ Display time as Days:Hours:Minutes:Seconds (with milliseconds support)
✓ Programmatic and user-based value changes
✓ Keyboard navigation between fields (arrow keys)
✓ Mouse wheel and click-drag interactions
✓ Custom format strings with field labels
✓ Min/Max value constraints
✓ ValueChanged event notifications
✓ ReadOnly mode for display-only scenarios
✓ Null value support with watermarks
✓ Theme integration (SfSkinManager, ThemeStudio)
✓ RTL (Right-to-Left) flow direction support

核心功能：

✓ 以天:时:分:秒格式显示时间（支持毫秒）
✓ 程序化和用户触发的数值变更
✓ 通过键盘箭头键在各字段间导航
✓ 鼠标滚轮和点击拖拽交互
✓ 带字段标签的自定义格式字符串
✓ 最小/最大值约束
✓ ValueChanged事件通知
✓ 仅显示模式的只读状态
✓ 支持空值及水印
✓ 主题集成（SfSkinManager、ThemeStudio）
✓ RTL（从右到左）流向支持

Documentation and Navigation Guide

文档与导航指南

Getting Started

快速入门

📄 Read: references/getting-started.md

Assembly installation and NuGet setup
Adding TimeSpanEdit via Designer
Adding TimeSpanEdit via XAML
Adding TimeSpanEdit via C# code
Basic setup examples

📄 阅读： references/getting-started.md

程序集安装与NuGet配置
通过设计器添加TimeSpanEdit
通过XAML添加TimeSpanEdit
通过C#代码添加TimeSpanEdit
基础设置示例

Value Setting & Custom Formats

数值设置与自定义格式

📄 Read: references/value-and-formats.md

Setting time values programmatically
Custom format strings (d, h, m, s, z)
Format examples with labels ("days", "hours", etc.)
Displaying milliseconds
Null values and watermark text

📄 阅读： references/value-and-formats.md

程序化设置时间数值
自定义格式字符串（d、h、m、s、z）
带标签的格式示例（"days"、"hours"等）
显示毫秒
空值与水印文本

User Interactions

用户交互

📄 Read: references/user-interactions.md

Field navigation with mouse and keyboard
Step intervals for precise increments
UpDown button controls
Mouse wheel interaction
Click & drag (extended scrolling)
Keyboard arrow key navigation
ReadOnly mode for preventing edits

📄 阅读： references/user-interactions.md

通过鼠标和键盘进行字段导航
用于精确增减的步长间隔
上下调节按钮控件
鼠标滚轮交互
点击拖拽（扩展滚动）
键盘箭头键导航
防止编辑的只读模式

Constraints & Events

约束与事件

📄 Read: references/constraints-and-events.md

Min/Max value constraints
ValueChanged event handling
Event binding in XAML and C#
Value change notifications

📄 阅读： references/constraints-and-events.md

最小/最大值约束
ValueChanged事件处理
XAML和C#中的事件绑定
数值变更通知

Appearance & Theming

外观与主题

📄 Read: references/appearance-and-theming.md

Background and selection colors
Foreground text color
Flow direction (RTL support)
Built-in theme application
SfSkinManager integration
ThemeStudio custom themes

📄 阅读： references/appearance-and-theming.md

背景色与选中高亮色
文本前景色
流向设置（RTL支持）
内置主题应用
SfSkinManager集成
ThemeStudio自定义主题

Quick Start Example

快速入门示例

XAML:

xml

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

C# Code-Behind:

csharp

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;
    }
}

Assembly Reference: Add this to your WPF project:

```
Syncfusion.Shared.WPF
```

XAML：

xml

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

C#代码后置：

csharp

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
```

Common Patterns

常见模式

Pattern 1: Duration Entry with Constraints

模式1：带约束的时长输入

Restrict time selection to specific range (e.g., 2-10 days):

xml

<syncfusion:TimeSpanEdit 
    Value="5.08:30:00"
    MinValue="2.00:00:00"
    MaxValue="10.00:00:00"
    ShowArrowButtons="True" />

将时间选择限制在特定范围内（例如2-10天）：

xml

<syncfusion:TimeSpanEdit 
    Value="5.08:30:00"
    MinValue="2.00:00:00"
    MaxValue="10.00:00:00"
    ShowArrowButtons="True" />

Pattern 2: Custom Formatted Display

模式2：自定义格式显示

Show user-friendly format with labels:

xml

<syncfusion:TimeSpanEdit 
    Value="3.14:25:30"
    Format="d 'days' h 'hours' m 'minutes' s 'seconds'" />

显示带标签的友好格式：

xml

<syncfusion:TimeSpanEdit 
    Value="3.14:25:30"
    Format="d 'days' h 'hours' m 'minutes' s 'seconds'" />

Pattern 3: Precise Step Intervals

模式3：精确步长间隔

Control increment/decrement precision:

xml

<syncfusion:TimeSpanEdit 
    Value="5.10:00:00"
    StepInterval="1.00:15:30"
    IncrementOnScrolling="True" />

控制增减的精度：

xml

<syncfusion:TimeSpanEdit 
    Value="5.10:00:00"
    StepInterval="1.00:15:30"
    IncrementOnScrolling="True" />

Pattern 4: Read-Only Display

模式4：只读显示

Show time value without allowing user edits:

xml

<syncfusion:TimeSpanEdit 
    Value="7.18:45:30"
    IsReadOnly="True"
    AllowNull="False" />

显示时间数值但不允许用户编辑：

xml

<syncfusion:TimeSpanEdit 
    Value="7.18:45:30"
    IsReadOnly="True"
    AllowNull="False" />

Pattern 5: Null Value with Watermark

模式5：带水印的空值

Allow empty state with placeholder text:

xml

<syncfusion:TimeSpanEdit 
    AllowNull="True"
    Value="{x:Null}"
    NullString="Enter time duration..." />

允许空状态并显示占位文本：

xml

<syncfusion:TimeSpanEdit 
    AllowNull="True"
    Value="{x:Null}"
    NullString="Enter time duration..." />

Key Props Reference

核心属性参考

Property	Type	Default	Purpose
`Value`	`TimeSpan?`	`0.0:0:0`	The time duration to display/edit
`Format`	`string`	`d.h:m:s`	Custom format string (d=days, h=hours, m=minutes, s=seconds, z=milliseconds)
`MinValue`	`TimeSpan`	—	Minimum allowed time duration
`MaxValue`	`TimeSpan`	—	Maximum allowed time duration
`StepInterval`	`TimeSpan`	`1.01:01:01`	Increment/decrement interval for buttons/wheel/keyboard
`AllowNull`	`bool`	`false`	Allow null/empty values
`NullString`	`string`	`""`	Watermark text when value is null
`ShowArrowButtons`	`bool`	`true`	Show up/down spinner buttons
`IncrementOnScrolling`	`bool`	`true`	Allow mouse wheel to change values
`EnableExtendedScrolling`	`bool`	`false`	Allow click & drag to change values
`IsReadOnly`	`bool`	`false`	Prevent user edits (read-only mode)
`Background`	`Brush`	`White`	Control background color
`Foreground`	`Brush`	`Black`	Text color
`SelectionBrush`	`Brush`	`RoyalBlue`	Selection highlight color
`FlowDirection`	`FlowDirection`	`LeftToRight`	RTL support (RightToLeft)

属性	类型	默认值	用途
`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`	是否允许空值
`NullString`	`string`	`""`	值为空时的水印文本
`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）

Common Use Cases

后续步骤

Use Case 1: Time Duration Picker Users need to input work duration, task time, or interval:

Use custom format with labels:
```
"d 'days' h 'hrs' m 'min'"
```
Enable all interaction modes (buttons, wheel, keyboard)
Set reasonable Min/Max constraints

Use Case 2: Display-Only Duration Show calculated time values without editing:

Set
```
IsReadOnly="True"
```
Use clear format with labels
Hide UpDown buttons:
```
ShowArrowButtons="False"
```

Use Case 3: Precise Time Entry Users need exact control over hours/minutes:

Set
```
StepInterval
```
for coarse control (e.g., 15-min increments)
Enable keyboard navigation for field-by-field entry
Consider smaller step intervals for seconds

Use Case 4: Flexible Time Input Users prefer multiple input methods:

Keep all interactions enabled (buttons, wheel, keyboard, drag)
Use logical step intervals
Provide visual feedback with custom colors

从快速入门开始：阅读getting-started.md完成控件设置
设置显示格式：查看value-and-formats.md了解自定义格式
启用用户交互：参考user-interactions.md优化用户体验
添加业务逻辑：使用constraints-and-events.md实现事件与限制
设置控件样式：通过appearance-and-theming.md应用颜色和主题

Next Steps

—

Start with Getting Started: Read getting-started.md to set up the control
Format Your Display: Check value-and-formats.md for custom formats
Enable Interactions: Review user-interactions.md for optimal UX
Add Logic: Use constraints-and-events.md for events and limits
Style It: Apply colors and themes with appearance-and-theming.md

—