syncfusion-winui-slider

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Implementing Syncfusion WinUI Slider

实现Syncfusion WinUI Slider

When to Use This Skill

何时使用本技能

Use the Syncfusion WinUI Slider when you need to:

Allow users to select a single numeric value from a range
Provide an interactive way to adjust values (volume, brightness, price range, etc.)
Display value selection with visual feedback (labels, ticks, tooltips)
Create slider controls with customizable appearance and behavior
Implement range selectors for filtering or configuration
Build settings panels with adjustable numeric parameters
Add interactive controls for measurements, ratings, or scores

当你需要实现以下需求时可使用Syncfusion WinUI Slider：

允许用户从范围中选择单个数值
提供交互式的数值调整能力（音量、亮度、价格范围等）
为值选择提供可视化反馈（标签、刻度、提示框）
创建外观和行为可自定义的滑块控件
实现用于筛选或配置的范围选择器
构建带可调整数值参数的设置面板
为测量、评级或评分功能添加交互式控件

Component Overview

组件概述

The Syncfusion WinUI Slider (SfSlider) is a highly interactive UI control that enables users to select a single value from a range of values. It provides rich features including:

Numeric Value Support - Select values in any numeric range
Labels - Display formatted values with customizable styles
Ticks - Show major and minor tick marks at intervals
Dividers - Visual separators between intervals
Thumb Customization - Various built-in icons and custom styles
Tooltips - Show selected value with custom formatting
Track Styling - Customize active and inactive track appearance
Orientation - Horizontal or vertical layout
Accessibility - Full keyboard and screen reader support

Syncfusion WinUI Slider（SfSlider）是一款高交互性UI控件，支持用户从数值范围中选择单个值。它提供了丰富的功能，包括：

数值支持 - 可选择任意数值范围内的值
标签 - 展示带自定义样式的格式化数值
刻度 - 按间隔展示主刻度和次刻度
分隔线 - 间隔之间的视觉分隔标识
滑块按钮自定义 - 多种内置图标和自定义样式
提示框 - 展示带自定义格式的选中值
轨道样式 - 自定义激活态和未激活态轨道的外观
布局方向 - 支持水平或垂直布局
无障碍访问 - 完整支持键盘操作和屏幕阅读器

Documentation and Navigation Guide

文档和导航指南

Getting Started

入门指南

📄 Read: references/getting-started.md

Creating a WinUI 3 desktop application
Installing the Syncfusion.Sliders.WinUI NuGet package
Adding namespace imports
Basic slider initialization
Setting minimum, maximum, and current values
Enabling ticks, labels, and dividers
Quick implementation examples

📄 阅读： references/getting-started.md

创建WinUI 3桌面应用
安装Syncfusion.Sliders.WinUI NuGet包
添加命名空间引用
基础滑块初始化
设置最小值、最大值和当前值
启用刻度、标签和分隔线
快速实现示例

Core Features and Configuration

核心功能和配置

📄 Read: references/basic-features.md

Numeric value support and ranges
Orientation (Horizontal/Vertical)
Value property and data binding
Interval and step frequency
IsEnabled and IsInversed properties
ValueChanged event handling
Custom range implementation
Edge cases and validation

📄 阅读： references/basic-features.md

数值支持和范围设置
布局方向（水平/垂直）
值属性和数据绑定
间隔和步频设置
IsEnabled和IsInversed属性
ValueChanged事件处理
自定义范围实现
边界场景和校验

Labels

Ticks

刻度

📄 Read: references/ticks.md

ShowTicks property for major ticks
Minor ticks with MinorTicksPerInterval
Tick placement and offset
MajorTickStyle customization
MinorTickStyle customization
TickPlacement (After, Before)
Custom tick templates
Tick frequency and spacing

📄 阅读： references/ticks.md

主刻度对应的ShowTicks属性
次刻度与MinorTicksPerInterval配置
刻度放置和偏移
MajorTickStyle自定义
MinorTickStyle自定义
TickPlacement（后置/前置）
自定义刻度模板
刻度频率和间距

Dividers

分隔线

📄 Read: references/dividers.md

ShowDividers property
DividerHeight and DividerWidth
Divider styling and colors
Custom divider templates
Divider placement relative to track
Visual separation between intervals

📄 阅读： references/dividers.md

ShowDividers属性
DividerHeight和DividerWidth配置
分隔线样式和颜色
自定义分隔线模板
分隔线相对于轨道的放置位置
间隔之间的视觉分隔

Thumb and Tooltip

滑块按钮和提示框

📄 Read: references/thumb-tooltip.md

Thumb icon and customization
ThumbStyle property
Thumb overlay effects
ShowToolTip property
Tooltip placement (Top/Bottom)
TooltipFormat for custom display
Custom tooltip templates
Hover and interaction states
Thumb accessibility features

📄 阅读： references/thumb-tooltip.md

滑块按钮图标和自定义
ThumbStyle属性
滑块按钮覆盖层效果
ShowToolTip属性
提示框放置位置（顶部/底部）
用于自定义展示的TooltipFormat
自定义提示框模板
hover和交互状态
滑块按钮无障碍特性

Track Customization

轨道自定义

📄 Read: references/track-customization.md

ActiveTrackHeight and InactiveTrackHeight
ActiveTrackStyle and InactiveTrackStyle
Track colors and brushes
Track fill customization
Gradient tracks
Custom track templates
Corner radius and styling
Track interaction states

📄 阅读： references/track-customization.md

ActiveTrackHeight和InactiveTrackHeight配置
ActiveTrackStyle和InactiveTrackStyle配置
轨道颜色和画笔
轨道填充自定义
渐变轨道
自定义轨道模板
圆角和样式
轨道交互状态

Quick Start Example

快速入门示例

Basic Slider Implementation

基础滑块实现

xml

<!-- Add namespace -->
<Window xmlns:slider="using:Syncfusion.UI.Xaml.Sliders">

    <Grid>
        <slider:SfSlider Value="50"
                         Minimum="0"
                         Maximum="100"
                         Width="400"
                         Margin="20" />
    </Grid>
</Window>

xml

<!-- Add namespace -->
<Window xmlns:slider="using:Syncfusion.UI.Xaml.Sliders">

    <Grid>
        <slider:SfSlider Value="50"
                         Minimum="0"
                         Maximum="100"
                         Width="400"
                         Margin="20" />
    </Grid>
</Window>

Slider with Labels and Ticks

带标签和刻度的滑块

xml

<slider:SfSlider Value="50"
                 Minimum="0"
                 Maximum="100"
                 Interval="10"
                 ShowLabels="True"
                 ShowTicks="True"
                 Width="400" />

xml

<slider:SfSlider Value="50"
                 Minimum="0"
                 Maximum="100"
                 Interval="10"
                 ShowLabels="True"
                 ShowTicks="True"
                 Width="400" />

Fully Featured Slider

全功能滑块

xml

<slider:SfSlider Value="50"
                 Minimum="0"
                 Maximum="100"
                 Interval="10"
                 ShowLabels="True"
                 ShowTicks="True"
                 ShowDividers="True"
                 ShowToolTip="True"
                 MinorTicksPerInterval ="1"
                 Width="400"
                 Height="60" />

xml

<slider:SfSlider Value="50"
                 Minimum="0"
                 Maximum="100"
                 Interval="10"
                 ShowLabels="True"
                 ShowTicks="True"
                 ShowDividers="True"
                 ShowToolTip="True"
                 MinorTicksPerInterval ="1"
                 Width="400"
                 Height="60" />

Code-Behind Implementation

后置代码实现

csharp

using Syncfusion.UI.Xaml.Sliders;

// Create slider
SfSlider slider = new SfSlider();
slider.Value = 50;
slider.Minimum = 0;
slider.Maximum = 100;
slider.Interval = 10;
slider.ShowLabels = true;
slider.ShowTicks = true;
slider.Width = 400;

// Handle value changes
slider.ValueChanged += (sender, e) =>
{
    double newValue = e.NewValue;
    Console.WriteLine($"Value changed to: {newValue}");
};

// Add to layout
rootGrid.Children.Add(slider);

csharp

using Syncfusion.UI.Xaml.Sliders;

// Create slider
SfSlider slider = new SfSlider();
slider.Value = 50;
slider.Minimum = 0;
slider.Maximum = 100;
slider.Interval = 10;
slider.ShowLabels = true;
slider.ShowTicks = true;
slider.Width = 400;

// Handle value changes
slider.ValueChanged += (sender, e) =>
{
    double newValue = e.NewValue;
    Console.WriteLine($"Value changed to: {newValue}");
};

// Add to layout
rootGrid.Children.Add(slider);

Common Patterns

常用模式

Volume Control Pattern

音量控制模式

xml

<slider:SfSlider Value="{Binding Volume, Mode=TwoWay}"
                 Minimum="0"
                 Maximum="100"
                 Interval="10"
                 ShowLabels="True"
                 ShowTicks="True"
                 ShowToolTip="True"
                 Width="300">
</slider:SfSlider>

xml

<slider:SfSlider Value="{Binding Volume, Mode=TwoWay}"
                 Minimum="0"
                 Maximum="100"
                 Interval="10"
                 ShowLabels="True"
                 ShowTicks="True"
                 ShowToolTip="True"
                 Width="300">
</slider:SfSlider>

Price Range Filter Pattern

价格范围筛选模式

xml

<slider:SfSlider Value="{Binding MaxPrice, Mode=TwoWay}"
                 Minimum="0"
                 Maximum="1000"
                 Interval="100"
                 ShowLabels="True"
                 ShowTicks="True"
                 Width="400">
</slider:SfSlider>

xml

<slider:SfSlider Value="{Binding MaxPrice, Mode=TwoWay}"
                 Minimum="0"
                 Maximum="1000"
                 Interval="100"
                 ShowLabels="True"
                 ShowTicks="True"
                 Width="400">
</slider:SfSlider>

Vertical Slider Pattern

垂直滑块模式

xml

<slider:SfSlider Value="50"
                 Minimum="0"
                 Maximum="100"
                 Orientation="Vertical"
                 ShowLabels="True"
                 ShowTicks="True"
                 Height="300"
                 Width="80" />

xml

<slider:SfSlider Value="50"
                 Minimum="0"
                 Maximum="100"
                 Orientation="Vertical"
                 ShowLabels="True"
                 ShowTicks="True"
                 Height="300"
                 Width="80" />

Disabled State Pattern

禁用状态模式

xml

<slider:SfSlider Value="50"
                 IsEnabled="False"
                 ShowLabels="True"
                 ShowTicks="True"
                 Width="400" />

xml

<slider:SfSlider Value="50"
                 IsEnabled="False"
                 ShowLabels="True"
                 ShowTicks="True"
                 Width="400" />

Key Properties

核心属性

Property	Type	Description
`Value`	`double`	Current value of the slider
`Minimum`	`double`	Minimum value (default: 0)
`Maximum`	`double`	Maximum value (default: 100)
`Interval`	`double`	Spacing between labels and ticks (default: calculated)
`ShowLabels`	`bool`	Display value labels (default: false)
`ShowTicks`	`bool`	Display tick marks (default: false)
`ShowDividers`	`bool`	Display dividers between intervals (default: false)
`ShowToolTip`	`bool`	Display tooltip on thumb hover/drag (default: false)
`Orientation`	`Orientation`	Horizontal or Vertical (default: Horizontal)
`IsInversed`	`bool`	Reverse the direction (default: false)
`MinorTicksPerInterval`	`int`	Number of minor ticks per interval (default: 0)
`ActiveTrackHeight`	`double`	Height of the filled track
`InactiveTrackHeight`	`double`	Height of the unfilled track
`DividerHeight`	`double`	Height of divider markers
`DividerWidth`	`double`	Width of divider markers

属性	类型	描述
`Value`	`double`	滑块的当前值
`Minimum`	`double`	最小值（默认：0）
`Maximum`	`double`	最大值（默认：100）
`Interval`	`double`	标签和刻度之间的间距（默认：自动计算）
`ShowLabels`	`bool`	是否展示值标签（默认：false）
`ShowTicks`	`bool`	是否展示刻度（默认：false）
`ShowDividers`	`bool`	是否展示间隔之间的分隔线（默认：false）
`ShowToolTip`	`bool`	滑块按钮hover/拖动时是否展示提示框（默认：false）
`Orientation`	`Orientation`	水平或垂直布局（默认：水平）
`IsInversed`	`bool`	是否反转方向（默认：false）
`MinorTicksPerInterval`	`int`	每个间隔内的次刻度数量（默认：0）
`ActiveTrackHeight`	`double`	已填充轨道的高度
`InactiveTrackHeight`	`double`	未填充轨道的高度
`DividerHeight`	`double`	分隔线标记的高度
`DividerWidth`	`double`	分隔线标记的宽度

Key Events

核心事件

Event	Description
`ValueChanged`	Fired when the slider value changes

事件	描述
`ValueChanged`	滑块值发生变化时触发

Common Use Cases

常见使用场景

Audio/Video Controls - Volume, playback position, brightness
Filter Sliders - Price range, age range, rating filters
Settings Panels - Adjustable parameters, configuration values
Image Editing - Brightness, contrast, saturation adjustments
Measurement Tools - Temperature, pressure, scale selectors
Rating Systems - Score selection, satisfaction ratings
Progress Indicators - Interactive progress bars
Zoom Controls - Scale/zoom level adjustment

音视频控制 - 音量、播放进度、亮度调整
筛选滑块 - 价格范围、年龄范围、评分筛选
设置面板 - 可调整参数、配置值设置
图片编辑 - 亮度、对比度、饱和度调整
测量工具 - 温度、压力、刻度选择器
评级系统 - 分数选择、满意度评分
进度指示器 - 交互式进度条
缩放控制 - 比例/缩放级别调整

Best Practices

最佳实践

Set Appropriate Ranges: Define meaningful Minimum and Maximum values
Use Intervals Wisely: Choose intervals that make sense for your data
Enable Visual Feedback: Show labels, ticks, or tooltips for better UX
Data Binding: Use two-way binding for reactive updates
Accessibility: Ensure keyboard navigation works (Tab, Arrow keys)
Custom Formatting: Use LabelFormat and TooltipFormat for clarity
Responsive Width: Set appropriate Width for your layout
Validation: Handle ValueChanged to validate and constrain values

设置合理范围：定义有实际意义的最小值和最大值
合理使用间隔：选择适配你的数据的间隔值
启用视觉反馈：展示标签、刻度或提示框提升用户体验
数据绑定：使用双向绑定实现响应式更新
无障碍访问：确保键盘导航可用（Tab、方向键）
自定义格式化：使用LabelFormat和TooltipFormat提升信息清晰度
响应式宽度：为你的布局设置合适的宽度
校验：监听ValueChanged事件来校验和约束值

Troubleshooting

故障排查

Slider Not Showing:

Verify Syncfusion.Sliders.WinUI NuGet is installed

Check namespace import:

xmlns:slider="using:Syncfusion.UI.Xaml.Sliders"

Ensure Width or Height is set appropriately

Value Not Updating:

Use Mode=TwoWay for data binding
Handle ValueChanged event properly
Check if IsEnabled is true

Labels/Ticks Not Visible:

Set ShowLabels="True" and ShowTicks="True"
Define Interval property
Ensure sufficient Width/Height for layout

Tooltip Not Appearing:

Set ShowToolTip="True"
Verify mouse/touch interaction works

滑块不展示：

确认已安装Syncfusion.Sliders.WinUI NuGet包

检查命名空间引用：

xmlns:slider="using:Syncfusion.UI.Xaml.Sliders"

确保已正确设置Width或Height

值不更新：

数据绑定时使用Mode=TwoWay
正确处理ValueChanged事件
检查IsEnabled是否为true

标签/刻度不可见：

设置ShowLabels="True"和ShowTicks="True"
定义Interval属性
确保布局有足够的Width/Height

提示框不出现：

设置ShowToolTip="True"
确认鼠标/触摸交互正常

Next Steps

后续步骤

Explore labels.md for custom label formatting
Learn about ticks.md for precise value indicators
Customize appearance with track-customization.md
Add tooltips via thumb-tooltip.md

查看labels.md了解自定义标签格式化方法
阅读ticks.md学习精准数值指示器的使用
通过track-customization.md自定义外观
参考thumb-tooltip.md添加提示框功能