AtomUI/docs/Desktop.Controls/Slider/SliderUsage.md

Slider 使用文档

本文档介绍 AtomUI Slider 控件的各种使用方式和常见场景。

📖 Gallery 源码位置：controlgallery/AtomUIGallery/ShowCases/Views/DataEntry/SliderShowCase.axaml

---

前置准备

AXAML 命名空间

xmlns:atom="https://atomui.net"

C# 命名空间

using AtomUI.Desktop.Controls;

---

1. 基本用法

最简单的滑动条，通过拖拽选择一个值：

<atom:Slider Maximum="100" Minimum="0" Value="50" TickFrequency="5" />

通过 IsEnabled 控制启用/禁用状态：

<atom:Slider Maximum="100" Minimum="0" Value="50" IsEnabled="False" />

配合 ToggleSwitch 动态切换启用状态（参考 Gallery Basic 示例）：

<StackPanel Orientation="Vertical" Spacing="20">
    <atom:Slider
        Maximum="100" Minimum="0"
        TickFrequency="5"
        IsEnabled="{Binding NormalEnabled}"
        Value="50" />
    <StackPanel Orientation="Horizontal" Spacing="2">
        <atom:TextBlock VerticalAlignment="Center">Enabled:</atom:TextBlock>
        <atom:ToggleSwitch SizeType="Small" IsChecked="{Binding NormalEnabled, Mode=TwoWay}" />
    </StackPanel>
</StackPanel>

---

2. 范围选择（双滑块）

通过 IsRangeMode="True" 启用双滑块模式，使用 RangeValue 设置范围。拖拽时自动判断离哪个滑块更近：

<atom:Slider
    Maximum="100" Minimum="0"
    IsRangeMode="True"
    TickFrequency="5"
    RangeValue="20, 80" />

在 C# 中设置范围值：

slider.RangeValue = new SliderRangeValue { StartValue = 20, EndValue = 80 };

约束：StartValue 必须 ≤ EndValue，否则解析时抛出 FormatException。

---

3. 自定义 Tooltip

通过 ValueFormatTemplate 自定义 Tooltip 显示格式，使用 string.Format 语法：

<atom:Slider
    Maximum="100" Minimum="0"
    TickFrequency="1"
    IsSnapToTickEnabled="True"
    ValueFormatTemplate="\{0\}%"
    Value="20" />

⚠️ 注意：AXAML 中的 { 和 } 需要用 \{ 和 \} 转义，避免被识别为标记扩展。

常用格式示例：

格式模板	效果	适用场景
\{0\}%	50%	百分比
\{0:F1\}°C	26.0°C	温度
$\{0:N0\}	$1,000	金额
\{0:0\}	50（默认）	整数

---

4. 垂直方向

通过 Orientation="Vertical" 切换为垂直滑动条。垂直模式下需要为容器设置固定高度：

<StackPanel Orientation="Horizontal" Spacing="20" Height="300">
    <!-- 单值垂直 -->
    <atom:Slider
        Maximum="100" Minimum="0"
        Orientation="Vertical"
        TickFrequency="1"
        Value="20" />

    <!-- 范围垂直 + 刻度吸附 -->
    <atom:Slider
        Maximum="100" Minimum="0"
        Orientation="Vertical"
        IsRangeMode="True"
        TickFrequency="5"
        IsSnapToTickEnabled="True"
        RangeValue="20, 80" />
</StackPanel>

---

5. 刻度标记（Marks）

通过 Marks 属性添加刻度标注。刻度标记在轨道上显示为小圆点，标签文字渲染在刻度下方（水平）或右侧（垂直）。点击标记可直接跳转到对应值：

slider.Marks = new List<SliderMark>
{
    new("0°C", 0),
    new("26°C", 26),
    new("37°C", 37),
    new("100°C", 100) { LabelBrush = Brushes.Red, LabelFontWeight = FontWeight.Bold }
};

每个 SliderMark 支持自定义样式：

属性	说明
Label	标注文字
Value	对应值
LabelBrush	文字颜色（可选）
LabelFontStyle	字体样式（可选）
LabelFontWeight	字体粗细（可选）

在 Gallery 中，Slider4~Slider7 演示了带刻度标记的滑动条（通过 code-behind 设置 Marks）。

---

6. 刻度吸附

设置 TickFrequency 和 IsSnapToTickEnabled 使滑块只能停留在刻度位置：

<atom:Slider
    Maximum="100" Minimum="0"
    TickFrequency="10"
    IsSnapToTickEnabled="True"
    Value="30" />

键盘操作时也遵循刻度吸附规则。

---

7. 不包含模式

设置 Included="False" 时，轨道不高亮已覆盖部分，只显示刻度标记和滑块位置：

<!-- 单值不包含 -->
<atom:Slider Maximum="100" Minimum="0" Included="False" Value="20" />

<!-- 范围不包含 -->
<atom:Slider
    Maximum="100" Minimum="0"
    IsRangeMode="True"
    TickFrequency="5"
    Included="False"
    RangeValue="20, 80" />

---

8. 方向反转

设置 IsDirectionReversed="True" 反转滑动方向：

<atom:Slider Maximum="100" Minimum="0" IsDirectionReversed="True" Value="70" />

• 水平模式：值从右到左递增
• 垂直模式：值从上到下递增

---

9. 禁用动画

通过 IsMotionEnabled="False" 禁用滑块的过渡动画：

<atom:Slider Maximum="100" Value="50" IsMotionEnabled="False" />

---

常见组合模式

表单中的滑动条

Slider 实现了 IFormItemAware 接口，可直接嵌入 FormItem：

<atom:FormItem Label="Volume">
    <atom:Slider Maximum="100" Minimum="0" Value="60" />
</atom:FormItem>

范围模式下表单值类型为 SliderRangeValue：

<atom:FormItem Label="Price Range">
    <atom:Slider Maximum="1000" Minimum="0" IsRangeMode="True" RangeValue="200, 800" />
</atom:FormItem>

与数值输入联动

<StackPanel Orientation="Horizontal" Spacing="16">
    <atom:Slider Name="LinkedSlider" Maximum="100" Value="50" Width="200" />
    <atom:NumericUpDown Value="{Binding #LinkedSlider.Value}" Maximum="100" Minimum="0" />
</StackPanel>

数据绑定

<atom:Slider Maximum="100" Minimum="0" Value="{Binding Volume, Mode=TwoWay}" />

范围模式数据绑定：

<atom:Slider
    Maximum="100" Minimum="0"
    IsRangeMode="True"
    RangeValue="{Binding PriceRange, Mode=TwoWay}" />

---

键盘操作速查

按键	说明
← / ↓	减少 SmallChange
→ / ↑	增加 SmallChange
PageUp	增加 LargeChange
PageDown	减少 LargeChange
Home	跳转到 Minimum
End	跳转到 Maximum

当 IsDirectionReversed="True" 时，方向键的增减方向会反转。