syncfusion-winui-slider

实现 Syncfusion WinUI 滑块

何时使用此技能

在以下情况下使用 Syncfusion WinUI 滑块：

• 允许用户从某个范围内选择单个数值
• 提供交互式方式来调整数值（音量、亮度、价格范围等）
• 通过视觉反馈显示数值选择（标签、刻度、工具提示）
• 创建外观和行为可自定义的滑块控件
• 实现用于筛选或配置的范围选择器
• 构建包含可调数值参数的设置面板
• 添加用于测量、评分或分数的交互式控件

组件概述

Syncfusion WinUI 滑块（SfSlider）是一种高度交互的 UI 控件，可让用户从一系列数值中选择一个值。它提供丰富的功能，包括：

• 数值支持 - 在任意数值范围内选择数值
• 标签 - 以可自定义的样式显示格式化数值
• 刻度 - 按间隔显示主刻度和次刻度
• 分隔线 - 在间隔之间显示视觉分隔线
• 滑块拇指自定义 - 提供各种内置图标和自定义样式
• 工具提示 - 以自定义格式显示所选数值
• 轨道样式 - 自定义活动和非活动轨道的外观
• 方向 - 水平或垂直布局
• 无障碍功能 - 完整支持键盘和屏幕阅读器

文档与导航指南

入门

📄 阅读： references/getting-started.md

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

核心功能与配置

📄 阅读： references/basic-features.md

• 数值支持和范围
• 方向（水平/垂直）
• Value 属性和数据绑定
• 间隔和步进频率
• IsEnabled 和 IsInversed 属性
• ValueChanged 事件处理
• 自定义范围实现
• 边缘情况和验证

标签

📄 阅读： references/labels.md

• ShowLabels 属性
• 标签放置和定位
• 标签格式字符串（数字、百分比、货币、自定义）
• LabelStyle 自定义
• LabelOffset 配置
• 自定义标签模板
• 标签可见性和间距
• 标签的 RTL 支持

刻度

📄 阅读： references/ticks.md

• 用于主刻度的 ShowTicks 属性
• 使用 MinorTicksPerInterval 设置次刻度
• 刻度放置和偏移
• MajorTickStyle 自定义
• MinorTickStyle 自定义
• TickPlacement（After、Before）
• 自定义刻度模板
• 刻度频率和间距

分隔线

📄 阅读： references/dividers.md

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

滑块拇指和工具提示

📄 阅读： references/thumb-tooltip.md

• 滑块拇指图标和自定义
• ThumbStyle 属性
• 滑块拇指叠加效果
• ShowToolTip 属性
• 工具提示位置（顶部/底部）
• 用于自定义显示的 TooltipFormat
• 自定义工具提示模板
• 悬停和交互状态
• 滑块拇指的无障碍功能

轨道自定义

📄 阅读： references/track-customization.md

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

快速入门示例

基本滑块实现

<Window xmlns:slider="using:Syncfusion.UI.Xaml.Sliders">

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

带标签和刻度的滑块

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

功能齐全的滑块

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

代码隐藏实现

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

常见模式

音量控制模式

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

价格范围筛选模式

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

垂直滑块模式

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

禁用状态模式

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

关键属性

属性	类型	描述
Value	double	滑块的当前值
Minimum	double	最小值（默认值：0）
Maximum	double	最大值（默认值：100）
Interval	double	标签和刻度之间的间隔（默认值：自动计算）
ShowLabels	bool	显示数值标签（默认值：false）
ShowTicks	bool	显示刻度线（默认值：false）
ShowDividers	bool	显示间隔分隔线（默认值：false）
ShowToolTip	bool	拖动或悬停滑块拇指时显示工具提示（默认值：false）
Orientation	Orientation	水平或垂直（默认值：Horizontal）
IsInversed	bool	反转方向（默认值：false）
MinorTicksPerInterval	int	每个间隔中的次刻度数量（默认值：0）
ActiveTrackHeight	double	已填充轨道的高度
InactiveTrackHeight	double	未填充轨道的高度
DividerHeight	double	分隔标记的高度
DividerWidth	double	分隔标记的宽度

关键事件

事件	描述
ValueChanged	滑块值更改时触发

常见使用场景

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

最佳实践

1. 设置合适的范围： 定义有意义的 Minimum 和 Maximum 值
2. 合理使用间隔： 选择适合数据的间隔
3. 启用视觉反馈： 显示标签、刻度或工具提示，以改善用户体验
4. 数据绑定： 使用双向绑定实现响应式更新
5. 无障碍访问： 确保键盘导航正常工作（Tab、方向键）
6. 自定义格式： 使用 LabelFormat 和 TooltipFormat 提高清晰度
7. 响应式宽度： 根据布局设置合适的 Width
8. 验证： 处理 ValueChanged 以验证并限制数值

故障排除

滑块未显示：

• 确认已安装 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"
• 确认鼠标/触控交互正常工作

后续步骤

• 浏览 labels.md，了解自定义标签格式
• 了解 ticks.md，掌握精确的数值指示器
• 使用 track-customization.md 自定义外观
• 通过 thumb-tooltip.md 添加工具提示