syncfusion-wpf-domain-updown

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Implementing Syncfusion WPF DomainUpDown

实现Syncfusion WPF DomainUpDown控件

Guide for implementing the Syncfusion® WPF DomainUpDown (SfDomainUpDown) control - a versatile input control that allows users to cycle through a predefined list of items using spin buttons (increment/decrement arrows).

本指南介绍如何实现Syncfusion® WPF DomainUpDown（SfDomainUpDown）控件——这是一款多功能输入控件，允许用户通过点击上下按钮、鼠标滚轮或键盘导航从预定义列表中选择值。与数值增减控件不同，DomainUpDown可处理任意类型的数据——字符串、对象或自定义类型。

When to Use This Skill

适用场景

Use this skill when you need to:

Implement a DomainUpDown control for item selection with spin buttons
Populate predefined item lists that users can cycle through
Customize spin button positioning (left, right, or both sides)
Bind complex data objects with custom display templates
Style and theme the control appearance
Enable auto-reverse cycling from max to min values
Handle mouse wheel and keyboard navigation gestures
Create data-driven selectors with MVVM pattern support

在以下场景中可使用本技能：

实现DomainUpDown控件：通过旋转按钮进行项目选择
填充预定义项目列表：供用户循环浏览
自定义旋转按钮位置（左侧、右侧或两侧）
绑定复杂数据对象：使用自定义显示模板
设置控件样式与主题
启用自动反转：从最大值循环到最小值
处理鼠标滚轮与键盘导航
创建数据驱动选择器：支持MVVM模式

Component Overview

组件概述

The

SfDomainUpDown

control provides an elegant way for users to select values from a predefined list by clicking up/down buttons or using mouse wheel/keyboard navigation. Unlike numeric up-down controls, DomainUpDown works with any type of data - strings, objects, or custom types.

Key Capabilities:

Data binding support with
```
ItemsSource
```
Custom content templates for complex objects
Configurable spin button alignment (left, right, both)
Smooth spin animations
Auto-reverse cycling behavior
Mouse wheel and keyboard gestures
Extensive styling and theming options
MVVM-friendly architecture

Assemblies Required:

```
Syncfusion.SfInput.WPF
```
```
Syncfusion.SfShared.WPF
```

SfDomainUpDown

控件为用户提供了一种优雅的方式，可通过点击上下按钮、鼠标滚轮或键盘导航从预定义列表中选择值。与数值增减控件不同，DomainUpDown可处理任意类型的数据——字符串、对象或自定义类型。

核心功能：

支持通过
```
ItemsSource
```
进行数据绑定
可为复杂对象自定义内容模板
可配置旋转按钮对齐方式（左侧、右侧、两侧）
流畅的旋转动画
自动反转循环行为
支持鼠标滚轮与键盘操作
丰富的样式与主题选项
符合MVVM架构的设计

所需程序集：

```
Syncfusion.SfInput.WPF
```
```
Syncfusion.SfShared.WPF
```

Documentation and Navigation Guide

文档与导航指南

Getting Started

快速入门

📄 Read: references/getting-started.md

When you need to:

Install and set up the DomainUpDown control
Add the control via designer or code
Understand assembly dependencies
Create your first basic implementation
Configure the
```
Value
```
property
Import necessary namespaces

📄 阅读： references/getting-started.md

适用于以下场景：

安装与配置DomainUpDown控件
通过设计器或代码添加控件
了解程序集依赖
创建首个基础实现
配置
```
Value
```
属性
导入必要的命名空间

Data Population and Binding

数据填充与绑定

📄 Read: references/data-population.md

When you need to:

Populate the control with a list of items
Bind data using
```
ItemsSource
```
property
Create data models and ViewModels
Use
```
ContentTemplate
```
for custom display
Display complex objects with multiple properties
Implement MVVM data binding patterns

📄 阅读： references/data-population.md

适用于以下场景：

为控件填充项目列表
通过
```
ItemsSource
```
属性绑定数据
创建数据模型与ViewModel
使用
```
ContentTemplate
```
自定义显示效果
显示包含多个属性的复杂对象
实现MVVM数据绑定模式

Spin Button Configuration

旋转按钮配置

📄 Read: references/spin-button-alignment.md

When you need to:

Customize spin button positioning
Use
```
SpinButtonsAlignment
```
property
Place buttons on the right (default)
Place buttons on the left
Split buttons on both sides (decrement left, increment right)
Choose appropriate alignment for your UI

📄 阅读： references/spin-button-alignment.md

适用于以下场景：

自定义旋转按钮位置
使用
```
SpinButtonsAlignment
```
属性
将按钮放置在右侧（默认）
将按钮放置在左侧
拆分按钮到两侧（递减按钮在左，递增按钮在右）
根据UI需求选择合适的对齐方式

Appearance and Styling

外观与样式设置

📄 Read: references/appearance-styling.md

When you need to:

Enable or disable spin animations
Customize accent colors with
```
AccentBrush
```
Style up/down buttons with
```
UpDownStyle
```
Create custom control templates
Modify borders, backgrounds, and foregrounds
Apply fonts and layout customization
Build comprehensive custom themes

📄 阅读： references/appearance-styling.md

适用于以下场景：

启用或禁用旋转动画
使用
```
AccentBrush
```
自定义强调色
使用
```
UpDownStyle
```
设置上下按钮样式
创建自定义控件模板
修改边框、背景与前景色
应用字体与布局自定义
构建全面的自定义主题

Advanced Features

高级功能

📄 Read: references/advanced-features.md

When you need to:

Enable auto-reverse cycling behavior
Handle mouse wheel scrolling
Implement keyboard navigation
Understand edge cases
Optimize performance

📄 阅读： references/advanced-features.md

适用于以下场景：

启用自动反转循环行为
处理鼠标滚轮滚动
实现键盘导航
了解边缘情况
优化性能

Quick Start Example

快速入门示例

Basic DomainUpDown with String Values

基础字符串值DomainUpDown

XAML:

xml

<Window xmlns:syncfusion="http://schemas.syncfusion.com/wpf"
        xmlns="http://schemas.microsoft.com/winfx/2006/xaml/presentation">
    <Grid>
        <syncfusion:SfDomainUpDown x:Name="domainUpDown" 
                                   Height="30" 
                                   Width="150" 
                                   Value="James">
            <syncfusion:SfDomainUpDown.ItemsSource>
                <x:Array Type="sys:String" xmlns:sys="clr-namespace:System;assembly=mscorlib">
                    <sys:String>Lucas</sys:String>
                    <sys:String>James</sys:String>
                    <sys:String>Jacob</sys:String>
                    <sys:String>Michael</sys:String>
                </x:Array>
            </syncfusion:SfDomainUpDown.ItemsSource>
        </syncfusion:SfDomainUpDown>
    </Grid>
</Window>

C#:

csharp

using Syncfusion.Windows.Controls.Input;

SfDomainUpDown domainUpDown = new SfDomainUpDown();
domainUpDown.Height = 30;
domainUpDown.Width = 150;
domainUpDown.ItemsSource = new List<string> { "Lucas", "James", "Jacob", "Michael" };
domainUpDown.Value = "James";
this.Content = domainUpDown;

XAML：

xml

<Window xmlns:syncfusion="http://schemas.syncfusion.com/wpf"
        xmlns="http://schemas.microsoft.com/winfx/2006/xaml/presentation">
    <Grid>
        <syncfusion:SfDomainUpDown x:Name="domainUpDown" 
                                   Height="30" 
                                   Width="150" 
                                   Value="James">
            <syncfusion:SfDomainUpDown.ItemsSource>
                <x:Array Type="sys:String" xmlns:sys="clr-namespace:System;assembly=mscorlib">
                    <sys:String>Lucas</sys:String>
                    <sys:String>James</sys:String>
                    <sys:String>Jacob</sys:String>
                    <sys:String>Michael</sys:String>
                </x:Array>
            </syncfusion:SfDomainUpDown.ItemsSource>
        </syncfusion:SfDomainUpDown>
    </Grid>
</Window>

C#：

csharp

using Syncfusion.Windows.Controls.Input;

SfDomainUpDown domainUpDown = new SfDomainUpDown();
domainUpDown.Height = 30;
domainUpDown.Width = 150;
domainUpDown.ItemsSource = new List<string> { "Lucas", "James", "Jacob", "Michael" };
domainUpDown.Value = "James";
this.Content = domainUpDown;

Data-Bound DomainUpDown with Custom Template

数据绑定的DomainUpDown与自定义模板

Model:

csharp

public class Employee
{
    public string Name { get; set; }
    public string Email { get; set; }
}

ViewModel:

csharp

public class ViewModel
{
    public List<Employee> Employees { get; set; }
    
    public ViewModel()
    {
        Employees = new List<Employee>
        {
            new Employee { Name = "Lucas", Email = "lucas@syncfusion.com" },
            new Employee { Name = "James", Email = "james@syncfusion.com" },
            new Employee { Name = "Jacob", Email = "jacob@syncfusion.com" }
        };
    }
}

XAML:

xml

<syncfusion:SfDomainUpDown x:Name="domainUpDown" 
                           Width="200" 
                           ItemsSource="{Binding Employees}">
    <syncfusion:SfDomainUpDown.ContentTemplate>
        <DataTemplate>
            <StackPanel Orientation="Horizontal">
                <TextBlock Text="{Binding Name}" FontWeight="Bold" Margin="0,0,5,0"/>
                <TextBlock Text="{Binding Email}" Foreground="Gray"/>
            </StackPanel>
        </DataTemplate>
    </syncfusion:SfDomainUpDown.ContentTemplate>
</syncfusion:SfDomainUpDown>

模型：

csharp

public class Employee
{
    public string Name { get; set; }
    public string Email { get; set; }
}

ViewModel：

csharp

public class ViewModel
{
    public List<Employee> Employees { get; set; }
    
    public ViewModel()
    {
        Employees = new List<Employee>
        {
            new Employee { Name = "Lucas", Email = "lucas@syncfusion.com" },
            new Employee { Name = "James", Email = "james@syncfusion.com" },
            new Employee { Name = "Jacob", Email = "jacob@syncfusion.com" }
        };
    }
}

XAML：

xml

<syncfusion:SfDomainUpDown x:Name="domainUpDown" 
                           Width="200" 
                           ItemsSource="{Binding Employees}">
    <syncfusion:SfDomainUpDown.ContentTemplate>
        <DataTemplate>
            <StackPanel Orientation="Horizontal">
                <TextBlock Text="{Binding Name}" FontWeight="Bold" Margin="0,0,5,0"/>
                <TextBlock Text="{Binding Email}" Foreground="Gray"/>
            </StackPanel>
        </DataTemplate>
    </syncfusion:SfDomainUpDown.ContentTemplate>
</syncfusion:SfDomainUpDown>

Common Patterns

常见模式

Pattern 1: Simple Item Selection

模式1：简单项目选择

When: User needs to select from a fixed list of simple values (strings, enums).

Approach:

Define items directly in XAML or populate
```
ItemsSource
```
in code
Set initial
```
Value
```
property
Handle value changes if needed

适用场景： 用户需要从固定的简单值列表（字符串、枚举）中选择。

实现步骤：

在XAML中直接定义项目，或在代码中填充
```
ItemsSource
```
设置初始
```
Value
```
属性
如有需要，处理值变更事件

Pattern 2: Data-Bound Object Selection with Display Template

模式2：带显示模板的数据绑定对象选择

When: User needs to select from a collection of complex objects with custom display.

Approach:

Create data model class
Populate collection in ViewModel
Bind
```
ItemsSource
```
to collection
Define
```
ContentTemplate
```
to display desired properties
Use data binding for MVVM compliance

适用场景： 用户需要从复杂对象集合中选择，并自定义显示效果。

实现步骤：

创建数据模型类
在ViewModel中填充集合
将
```
ItemsSource
```
绑定到集合
定义
```
ContentTemplate
```
以显示所需属性
使用数据绑定符合MVVM规范

Pattern 3: Styled DomainUpDown with Custom Buttons

模式3：自定义按钮样式的DomainUpDown

When: User needs a fully customized appearance matching application theme.

Approach:

Define custom styles in Resources
Use
```
UpDownStyle
```
property for button customization
Customize borders, backgrounds, and accents
Apply control template for comprehensive theming

适用场景： 用户需要与应用主题匹配的完全自定义外观。

实现步骤：

在资源中定义自定义样式
使用
```
UpDownStyle
```
属性自定义按钮
自定义边框、背景与强调色
应用控件模板实现全面主题定制

Pattern 4: Auto-Reverse List Cycling

模式4：自动反转列表循环

When: User wants continuous cycling (max → min, min → max).

Approach:

Set
```
AutoReverse="True"
```
Populate items normally
Cycling automatically wraps around boundaries

适用场景： 用户需要连续循环（最大值→最小值，最小值→最大值）。

实现步骤：

设置
```
AutoReverse="True"
```
正常填充项目
循环会自动在边界处折返

Key Properties

核心属性

Property	Type	Description	When to Use
`ItemsSource`	`IEnumerable`	Collection of items to display	Populate control with data
`Value`	`object`	Currently selected item	Get/set selected value
`ContentTemplate`	`DataTemplate`	Template for displaying items	Customize item appearance
`SpinButtonsAlignment`	`SpinButtonsAlignment`	Position of spin buttons (Left, Right, Both)	Control button placement
`AccentBrush`	`Brush`	Color for control hotspots	Theme customization
`EnableSpinAnimation`	`bool`	Enable/disable spin transitions	Control animation behavior
`AutoReverse`	`bool`	Enable cycling from max to min	Continuous list navigation
`UpDownStyle`	`Style`	Custom style for up/down buttons	Advanced button styling

属性	类型	描述	适用场景
`ItemsSource`	`IEnumerable`	要显示的项目集合	为控件填充数据
`Value`	`object`	当前选中的项目	获取/设置选中值
`ContentTemplate`	`DataTemplate`	项目显示模板	自定义项目外观
`SpinButtonsAlignment`	`SpinButtonsAlignment`	旋转按钮的位置（左侧、右侧、两侧）	控制按钮布局
`AccentBrush`	`Brush`	控件热点区域的颜色	主题定制
`EnableSpinAnimation`	`bool`	启用/禁用旋转过渡动画	控制动画行为
`AutoReverse`	`bool`	启用从最大值到最小值的循环	连续列表导航
`UpDownStyle`	`Style`	上下按钮的自定义样式	高级按钮样式设置

Common Use Cases

常见用例

1. Day of Week Selector

1. 星期选择器

Select day names with cycling support:

xml

<syncfusion:SfDomainUpDown AutoReverse="True" Value="Monday">
    <syncfusion:SfDomainUpDown.ItemsSource>
        <x:Array Type="sys:String">
            <sys:String>Monday</sys:String>
            <sys:String>Tuesday</sys:String>
            <!-- ... other days ... -->
        </x:Array>
    </syncfusion:SfDomainUpDown.ItemsSource>
</syncfusion:SfDomainUpDown>

支持循环选择星期名称：

xml

<syncfusion:SfDomainUpDown AutoReverse="True" Value="Monday">
    <syncfusion:SfDomainUpDown.ItemsSource>
        <x:Array Type="sys:String">
            <sys:String>Monday</sys:String>
            <sys:String>Tuesday</sys:String>
            <!-- ... 其他星期 ... -->
        </x:Array>
    </syncfusion:SfDomainUpDown.ItemsSource>
</syncfusion:SfDomainUpDown>

2. Employee/Contact Selector

2. 员工/联系人选择器

Display employee names from data source:

xml

<syncfusion:SfDomainUpDown ItemsSource="{Binding Employees}">
    <syncfusion:SfDomainUpDown.ContentTemplate>
        <DataTemplate>
            <TextBlock Text="{Binding Name}"/>
        </DataTemplate>
    </syncfusion:SfDomainUpDown.ContentTemplate>
</syncfusion:SfDomainUpDown>

从数据源显示员工名称：

xml

<syncfusion:SfDomainUpDown ItemsSource="{Binding Employees}">
    <syncfusion:SfDomainUpDown.ContentTemplate>
        <DataTemplate>
            <TextBlock Text="{Binding Name}"/>
        </DataTemplate>
    </syncfusion:SfDomainUpDown.ContentTemplate>
</syncfusion:SfDomainUpDown>

3. Status/State Selector

3. 状态选择器

Allow selection from predefined status values:

csharp

domainUpDown.ItemsSource = new List<string> { "Draft", "Pending", "Approved", "Rejected" };
domainUpDown.Value = "Draft";

允许从预定义状态值中选择：

csharp

domainUpDown.ItemsSource = new List<string> { "Draft", "Pending", "Approved", "Rejected" };
domainUpDown.Value = "Draft";

4. Custom Alignment Layout

4. 自定义对齐布局

Split increment/decrement buttons:

xml

<syncfusion:SfDomainUpDown SpinButtonsAlignment="Both" 
                           ItemsSource="{Binding Items}"/>

拆分增减按钮：

xml

<syncfusion:SfDomainUpDown SpinButtonsAlignment="Both" 
                           ItemsSource="{Binding Items}"/>

Best Practices

最佳实践

Data Binding: Use
```
ItemsSource
```
with ViewModels for MVVM compliance
Templates: Define
```
ContentTemplate
```
when displaying complex objects
Initial Value: Always set an initial
```
Value
```
from your
```
ItemsSource
```
AutoReverse: Enable for seamless cycling in fixed lists
Styling: Use
```
AccentBrush
```
for simple theming,
```
UpDownStyle
```
for comprehensive customization
Performance: For large lists, consider virtualization alternatives (ComboBox may be better)
Accessibility: Ensure button contrast and provide keyboard navigation

数据绑定： 使用
```
ItemsSource
```
与ViewModel配合，符合MVVM规范
模板： 显示复杂对象时定义
```
ContentTemplate
```
初始值： 始终从
```
ItemsSource
```
中设置初始
```
Value
```
自动反转： 对于固定列表，启用该功能实现无缝循环
样式设置： 使用
```
AccentBrush
```
进行简单主题定制，使用
```
UpDownStyle
```
进行全面自定义
性能： 对于大型列表，考虑使用虚拟化替代方案（ComboBox可能更合适）
可访问性： 确保按钮对比度足够，并支持键盘导航

Troubleshooting

故障排除

Issue: Items display as object type names instead of values
Solution: Define a

ContentTemplate

to specify how items should be displayed

Issue: Spin buttons don't appear
Solution: Verify assemblies are referenced and namespace is imported correctly

Issue: Value doesn't update on spin
Solution: Ensure items exist in

ItemsSource

and

Value

is a valid item

Issue: Animation is jumpy or slow
Solution: Set

EnableSpinAnimation="False"

or adjust system performance settings

For more detailed troubleshooting, refer to the specific reference documentation sections above.

问题： 项目显示为对象类型名称而非实际值
解决方案： 定义

ContentTemplate

以指定项目的显示方式

问题： 旋转按钮未显示
解决方案： 确认已引用程序集并正确导入命名空间

问题： 旋转时值未更新
解决方案： 确保项目存在于

ItemsSource

中，且

Value

是有效的项目

问题： 动画卡顿或缓慢
解决方案： 设置

EnableSpinAnimation="False"

或调整系统性能设置

如需更详细的故障排除指南，请参考上述对应文档章节。