syncfusion-flutter-sliders

Syncfusion Flutter 滑块控件

此技能整合了三个相关的 Syncfusion Flutter 组件，用于选择值和进行范围交互：SfSlider（单个值）、SfRangeSlider（双滑块范围）和 SfRangeSelector（带有图表等子内容的范围选择器）。它们共享许多外观和配置特性，但各自承担不同的职责，并采用不同的集成方式。

何时使用此技能

在以下情况下使用此技能：

• 在紧凑的 UI 中选择单个数值或日期（使用 SfSlider）。
• 使用两个滑块选择起始值和结束值范围（使用 SfRangeSlider）。
• 选择一个可驱动其他控件的范围（例如图表缩放／选择），或显示子内容（使用 SfRangeSelector）。
• 自定义滑块控件的轨道、刻度、标签、滑块或工具提示外观。
• 将滑块范围与图表集成，以进行选择或缩放。
• 为滑块控件提供 RTL、无障碍支持和键盘导航。

选择合适的组件

在以下情况下使用 SfSlider：

• 需要单值选择器（音量、进度百分比、时间轴拖动条）。
• 需要简单且占用空间小的控件。

在以下情况下使用 SfRangeSlider：

• 需要用户使用两个滑块选择数值／日期区间。
• 需要通过拖动模式控制滑块行为（onThumb、betweenThumbs、both）。

在以下情况下使用 SfRangeSelector：

• 需要包含或控制子控件（通常为图表）的范围控件。
• 需要使用 RangeController 进行程序化更新和图表集成。

主要差异汇总：

特性	SfSlider	SfRangeSlider	SfRangeSelector
主要用途	单个值	双滑块范围	带子控件的范围（图表）
值类型	value	values (SfRangeValues)	initialValues / controller
子内容	❌	❌	✅（任意控件，通常为图表）
控制器支持	❌	❌	✅ (RangeController)
拖动模式	—	✅ (dragMode)	✅ (dragMode)
延迟更新	❌	❌	✅ (enableDeferredUpdate)

文档与导航指南

入门

📄 阅读： references/getting-started.md

• 三种滑块控件的安装和包配置
• SfSlider 基本实现（水平和垂直）
• SfRangeSlider 基本实现
• 与图表集成的 SfRangeSelector 基本实现
• 包依赖和导入
• 快速比较和首批示例
• 数值和日期滑块示例

组件概览

📄 滑块： references/slider-overview.md

• SfSlider 控件概览和功能
• 何时使用单值滑块而非范围控件
• 数值和日期值支持
• 水平和垂直方向
• 滑块专属功能
• 滑块基本配置

📄 范围滑块： references/range-slider-overview.md

• SfRangeSlider 控件概览和功能
• 何时使用 Range Slider 而非 Range Selector
• 用于起始值／结束值的 SfRangeValues 类
• 拖动模式简介
• 活动和非活动轨道区域
• 范围滑块专属示例

📄 范围选择器： references/range-selector-overview.md

• SfRangeSelector 控件概览和功能
• 何时使用 Range Selector 进行图表集成
• 子控件支持（图表、绘图、自定义内容）
• RangeController 简介
• initialValues 与 controller 的区别
• 延迟更新模式
• 图表集成模式

值配置

📄 阅读： references/values-and-intervals.md

• 最小值和最大值配置
• 各控件的值类型（double、DateTime）
• 间隔配置和步长值
• 自定义格式的数值范围
• 日期和 DateTime 范围
• DateIntervalType 配置
• NumberFormat 和 DateFormat 的用法
• 值约束和验证

视觉自定义

📄 阅读： references/track-and-shapes.md

• 激活和未激活轨道的颜色
• 自定义轨道高度和厚度
• 轨道圆角和形状
• 自定义轨道样式模式
• RangeSelector 的区域颜色
• 三种组件中的轨道外观

📄 阅读： references/ticks-and-dividers.md

• 启用和配置刻度线
• 主刻度配置
• 次刻度和间隔
• 分隔线配置
• 刻度线和分隔线样式
• 三种组件的完整示例

📄 阅读： references/labels-and-formatting.md

• 显示和定位标签
• 用于数值的 NumberFormat（货币、百分比、紧凑格式）
• 用于日期值的 DateFormat（多种格式）
• 使用 labelFormatterCallback 自定义标签格式
• 标签文本样式
• 标签偏移和定位
• 边缘标签可见性

📄 阅读： references/thumbs-tooltips-overlay.md

• 滑块拇指的大小、颜色和自定义
• 滑块拇指图标和自定义组件
• 滑块拇指描边（边框）配置
• 覆盖层（涟漪）配置
• 启用和配置工具提示
• 工具提示形状（矩形、拨片形）
• 工具提示文本格式
• 始终显示工具提示选项

高级功能

📄 阅读： references/drag-modes.md

• 拖动模式功能（仅适用于 RangeSlider 和 RangeSelector）
• SliderDragMode.onThumb 说明
• SliderDragMode.betweenThumbs 说明
• SliderDragMode.both 说明
• 选择合适的拖动模式
• 各模式的使用场景和示例

📄 阅读： references/range-controller.md

• RangeController 概述（仅适用于 RangeSelector）
• 何时使用 RangeController
• 创建和释放控制器
• 用于提升性能的延迟更新
• 以编程方式更新范围
• 监听范围变化
• 使用控制器集成图表
• Controller 与 initialValues 对比
• 高级模式（应用按钮、同步选择器）

事件处理

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

• onChanged 回调（连续更新）
• onChangeStart 回调（交互开始）
• onChangeEnd 回调（交互完成）
• 完整生命周期示例
• 在回调中进行验证和设置约束
• 异步操作和防抖
• 事件处理模式
• 回调使用最佳实践

无障碍功能和状态

📄 阅读： references/accessibility-and-states.md

• 无障碍功能概述及其重要性
• 屏幕阅读器语义标签
• 启用和禁用状态
• 键盘导航支持
• 屏幕阅读器支持（VoiceOver、TalkBack）
• 从右向左（RTL）语言支持
• WCAG 合规指南
• 颜色对比度注意事项
• 触控目标尺寸
• 测试无障碍功能

快速入门示例

SfSlider — 基本单值滑块

double _value = 40.0;

SfSlider(
  min: 0.0,
  max: 100.0,
  value: _value,
  interval: 20,
  showLabels: true,
  onChanged: (dynamic newValue) {
    setState(() { _value = newValue; });
  },
)

SfRangeSlider — 基本范围

SfRangeValues _values = const SfRangeValues(40.0, 60.0);

SfRangeSlider(
  min: 0.0,
  max: 100.0,
  values: _values,
  interval: 20,
  showLabels: true,
  onChanged: (SfRangeValues newValues) {
    setState(() { _values = newValues; });
  },
)

SfRangeSelector — 带图表子项和控制器的范围

final SfRangeValues _initial = SfRangeValues(0.3, 0.7);
RangeController _controller = RangeController(start: 0.3, end: 0.7);

SfRangeSelector(
  min: 0,
  max: 1,
  initialValues: _initial,
  controller: _controller,
  child: SizedBox(height: 130, child: SfCartesianChart(...)),
)

常见模式

模式 1：根据需求选择组件

• 单个值 → SfSlider
• 范围选择 → SfRangeSlider
• 控制图表/子项的范围 → SfRangeSelector

模式 2：受控与非受控

• SfSlider 和 SfRangeSlider 通常由父级状态通过 value/values 和 onChanged 控制。
• SfRangeSelector 可通过 RangeController 驱动，以进行编程式更新和图表集成。

关键属性

SfSlider 基本属性

• min - 最小值（double 或 DateTime）
• max - 最大值（double 或 DateTime）
• value - 当前滑块值
• interval - 刻度间隔
• stepSize - 离散值的步进间隔
• onChanged - 值变化时的回调
• onChangeStart - 拖动开始时的回调
• onChangeEnd - 拖动结束时的回调
• showLabels - 显示刻度标签
• showTicks - 显示刻度线
• showDividers - 显示分隔线
• enableTooltip - 启用交互时的工具提示
• activeColor - 活动轨道颜色
• inactiveColor - 非活动轨道颜色
• numberFormat - 数值的 NumberFormat
• dateFormat - DateTime 值的 DateFormat
• dateIntervalType - 日期的间隔类型（年、月、日等）
• labelFormatterCallback - 自定义标签格式化
• tooltipTextFormatterCallback - 自定义工具提示格式化
• semanticFormatterCallback - 无障碍标签格式化

SfRangeSlider 基本属性

• min - 最小值（double 或 DateTime）
• max - 最大值（double 或 DateTime）
• values - 当前范围值（包含 start 和 end 的 SfRangeValues）
• interval - 刻度间隔
• stepSize - 离散值的步进间隔
• onChanged - 值变化时的回调
• onChangeStart - 拖动开始时的回调
• onChangeEnd - 拖动结束时的回调
• dragMode - 拖动交互模式（onDragStart、onThumb、betweenThumbs、both）
• showLabels - 显示刻度标签
• showTicks - 显示刻度线
• showDividers - 显示分隔线
• enableTooltip - 启用交互时的工具提示
• activeColor - 活动轨道颜色（两个滑块之间）
• inactiveColor - 非活动轨道颜色
• numberFormat - 数值的 NumberFormat
• dateFormat - DateTime 值的 DateFormat
• dateIntervalType - 日期的间隔类型
• labelFormatterCallback - 自定义标签格式化
• tooltipTextFormatterCallback - 自定义工具提示格式化
• semanticFormatterCallback - 无障碍标签格式化

SfRangeSelector 基本属性

• min - 最小值（double 或 DateTime）
• max - 最大值（double 或 DateTime）
• initialValues - 初始范围值（SfRangeValues）
• controller - 用于程序化控制的 RangeController
• interval - 刻度间隔
• stepSize - 离散值的步进间隔
• onChanged - 值变化时的回调（使用 controller 时可选）
• onChangeStart - 拖动开始时的回调
• onChangeEnd - 拖动结束时的回调
• dragMode - 拖动交互模式（onDragStart、onThumb、betweenThumbs、both）
• enableDeferredUpdate - 启用延迟更新以提升性能
• deferredUpdateDelay - 延迟更新的等待时间
• showLabels - 显示刻度标签
• showTicks - 显示刻度线
• showDividers - 显示分隔线
• enableTooltip - 启用交互时的工具提示
• activeColor - 活动轨道颜色（两个滑块之间）
• inactiveColor - 非活动轨道颜色
• child - 子组件（通常为图表）
• numberFormat - 数值的 NumberFormat
• dateFormat - DateTime 值的 DateFormat
• dateIntervalType - 日期的间隔类型
• labelFormatterCallback - 自定义标签格式化
• tooltipTextFormatterCallback - 自定义工具提示格式化
• semanticFormatterCallback - 无障碍标签格式化
• enableIntervalSelection - 启用按间隔选择
• showDivisors - 显示区域分隔线

常见用例

1. 音量或亮度控制 — SfSlider
2. 日期范围筛选 — SfRangeSlider
3. 图表缩放/片段选择 — SfRangeSelector + 图表集成
4. 分析仪表板的时间范围选择器 — SfRangeSelector
5. 商品列表中的双端价格范围筛选 — SfRangeSlider