syncfusion-flutter-sliders

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Syncfusion Flutter Slider Controls

Syncfusion Flutter Slider 控件

This skill groups three related Syncfusion Flutter components for value selection and range interaction: SfSlider (single value), SfRangeSlider (two-thumb range), and SfRangeSelector (range selector with child content such as charts). They share many visual and configuration features but have distinct responsibilities and integration patterns.

本技能汇总了三类用于数值选择和范围交互的相关Syncfusion Flutter组件：SfSlider（单值选择）、SfRangeSlider（双滑块范围选择）和SfRangeSelector（支持图表等子内容的范围选择器）。它们共享大量视觉和配置特性，但职责和集成模式各不相同。

When to Use This Skill

何时使用本技能

Use this skill when you need to:

Select a single numeric or date value in a compact UI (use
```
SfSlider
```
).
Select a start/end range with two thumbs (use
```
SfRangeSlider
```
).
Select a range that drives another widget (chart zoom/selection) or shows child content (use
```
SfRangeSelector
```
).
Customize visual track, ticks, labels, thumbs, or tooltips across slider controls.
Integrate slider range with charts for selection or zooming.
Support RTL, accessibility, and keyboard navigation for slider controls.

当你需要完成以下需求时可使用本技能：

在紧凑UI中选择单个数值或日期值（使用
```
SfSlider
```
）。
通过两个滑块选择起止范围（使用
```
SfRangeSlider
```
）。
选择可驱动其他组件的范围（图表缩放/选择）或展示子内容（使用
```
SfRangeSelector
```
）。
跨滑块控件自定义视觉轨道、刻度、标签、滑块或提示框。
将滑块范围与图表集成实现选择或缩放功能。
为滑块控件支持RTL、无障碍访问和键盘导航。

Choosing the Right Component

选择合适的组件

Use SfSlider when:

选择 SfSlider 场景：

You need a single value picker (volume, progress percentage, timeline scrubber).
Simplicity and small surface area are required.

你需要单值选择器（音量、进度百分比、时间轴拖动）。
要求使用简单、占用空间小。

Use SfRangeSlider when:

选择 SfRangeSlider 场景：

You need the user to pick a numeric/date interval with two thumbs.
You need drag modes that control thumb behavior (onThumb, betweenThumbs, both).

你需要用户通过两个滑块选择数值/日期间隔。
你需要控制滑块行为的拖拽模式（仅滑块、滑块间、两者都可）。

Use SfRangeSelector when:

选择 SfRangeSelector 场景：

You need a range control that contains or controls a child widget (commonly charts).
You require a
```
RangeController
```
for programmatic updates and chart integrations.

你需要包含或控制子组件（通常是图表）的范围控件。
你需要
```
RangeController
```
实现程序化更新和图表集成。

Key Differences Summary:

核心差异汇总：

Feature	SfSlider	SfRangeSlider	SfRangeSelector
Primary purpose	Single value	Two-thumb range	Range with child (chart)
Value type	`value`	`values` (SfRangeValues)	`initialValues` / `controller`
Child content	❌	❌	✅ (any widget, often charts)
Controller support	❌	❌	✅ ( `RangeController` )
Drag modes	—	✅ (dragMode)	✅ (dragMode)
Deferred updates	❌	❌	✅ (enableDeferredUpdate)

功能	SfSlider	SfRangeSlider	SfRangeSelector
核心用途	单值选择	双滑块范围选择	带子组件（图表）的范围选择
值类型	`value`	`values` (SfRangeValues)	`initialValues` / `controller`
子内容支持	❌	❌	✅（任意组件，通常为图表）
控制器支持	❌	❌	✅ ( `RangeController` )
拖拽模式	—	✅ (dragMode)	✅ (dragMode)
延迟更新	❌	❌	✅ (enableDeferredUpdate)

Documentation and Navigation Guide

文档与导航指南

Getting Started

入门指南

📄 Read: references/getting-started.md

Installation and package setup for all three slider controls
Basic SfSlider implementation (horizontal and vertical)
Basic SfRangeSlider implementation
Basic SfRangeSelector implementation with chart integration
Package dependencies and imports
Quick comparison and first examples
Numeric and date-based slider examples

📄 阅读： references/getting-started.md

三类滑块控件的安装与包配置
SfSlider基础实现（水平与垂直方向）
SfRangeSlider基础实现
集成图表的SfRangeSelector基础实现
包依赖与导入
快速对比与入门示例
数值和日期类型滑块示例

Component Overview

组件概览

📄 For Slider: references/slider-overview.md

SfSlider widget overview and features
When to use single-value slider vs range controls
Numeric and date value support
Horizontal and vertical orientations
Slider-specific capabilities
Basic slider configuration

📄 For Range Slider: references/range-slider-overview.md

SfRangeSlider widget overview and features
When to use Range Slider vs Range Selector
SfRangeValues class for start/end values
Introduction to drag modes
Active and inactive track regions
Range slider-specific examples

📄 For Range Selector: references/range-selector-overview.md

SfRangeSelector widget overview and features
When to use Range Selector for chart integration
Child widget support (charts, graphs, custom content)
RangeController introduction
Difference between initialValues and controller
Deferred updates pattern
Chart integration patterns

📄 滑块组件： references/slider-overview.md

SfSlider组件概览与特性
单值滑块与范围控件的适用场景对比
数值与日期值支持
水平与垂直方向适配
滑块专属能力
基础滑块配置

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

SfRangeSlider组件概览与特性
范围滑块与范围选择器的适用场景对比
存储起止值的SfRangeValues类介绍
拖拽模式入门
激活与未激活轨道区域
范围滑块专属示例

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

SfRangeSelector组件概览与特性
范围选择器用于图表集成的场景
子组件支持（图表、图形、自定义内容）
RangeController入门
initialValues与controller的差异
延迟更新模式
图表集成模式

Value Configuration

值配置

📄 Read: references/values-and-intervals.md

Minimum and maximum value configuration
Value types (double, DateTime) for each widget
Interval configuration and step values
Numeric ranges with custom formatting
Date and DateTime ranges
DateIntervalType configuration
NumberFormat and DateFormat usage
Value constraints and validation

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

最小值与最大值配置
各组件支持的值类型（double、DateTime）
间隔配置与步长值
支持自定义格式化的数值范围
日期与DateTime范围
DateIntervalType配置
NumberFormat与DateFormat使用
值约束与校验

Visual Customization

视觉自定义

📄 Read: references/track-and-shapes.md

Active and inactive track colors
Track height and thickness customization
Track corners and shapes
Custom track styling patterns
Region colors for RangeSelector
Track appearance across all three widgets

📄 Read: references/ticks-and-dividers.md

Enabling and configuring tick marks
Major ticks configuration
Minor ticks and intervals
Divider configuration
Tick and divider styling
Complete examples for all three widgets

📄 Read: references/labels-and-formatting.md

Showing and positioning labels
NumberFormat for numeric values (currency, percentage, compact)
DateFormat for date values (various patterns)
Custom label formatting with labelFormatterCallback
Label text styling
Label offset and positioning
Edge label visibility

📄 Read: references/thumbs-tooltips-overlay.md

Thumb size, color, and customization
Thumb icons and custom widgets
Thumb stroke (border) configuration
Overlay (ripple) configuration
Enabling and configuring tooltips
Tooltip shapes (rectangular, paddle)
Tooltip text formatting
Always-visible tooltip option

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

激活与未激活轨道颜色
轨道高度与粗细自定义
轨道圆角与形状
自定义轨道样式模式
RangeSelector的区域颜色
三类组件的轨道外观配置

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

刻度的启用与配置
主刻度配置
次刻度与间隔
分割线配置
刻度与分割线样式
三类组件的完整示例

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

标签的展示与定位
数值的NumberFormat配置（货币、百分比、紧凑格式）
日期的DateFormat配置（多种格式）
通过labelFormatterCallback自定义标签格式
标签文本样式
标签偏移与定位
边缘标签可见性配置

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

滑块大小、颜色与自定义
滑块图标与自定义组件
滑块描边（边框）配置
覆盖层（涟漪效果）配置
提示框的启用与配置
提示框形状（矩形、 paddle形）
提示框文本格式化
始终展示提示框选项

Advanced Features

高级特性

📄 Read: references/drag-modes.md

Drag mode functionality (RangeSlider and RangeSelector only)
SliderDragMode.onThumb explanation
SliderDragMode.betweenThumbs explanation
SliderDragMode.both explanation
Choosing the right drag mode
Use cases and examples for each mode

📄 Read: references/range-controller.md

RangeController overview (RangeSelector only)
When to use RangeController
Creating and disposing controllers
Deferred updates for performance
Programmatic range updates
Listening to range changes
Chart integration with controller
Controller vs initialValues comparison
Advanced patterns (apply button, synchronized selectors)

📄 阅读： references/drag-modes.md

拖拽模式功能（仅支持RangeSlider和RangeSelector）
SliderDragMode.onThumb说明
SliderDragMode.betweenThumbs说明
SliderDragMode.both说明
选择合适的拖拽模式
各模式的适用场景与示例

📄 阅读： references/range-controller.md

RangeController概览（仅支持RangeSelector）
RangeController的适用场景
控制器的创建与销毁
提升性能的延迟更新
程序化范围更新
监听范围变化
基于控制器的图表集成
控制器与initialValues对比
高级模式（应用按钮、同步选择器）

Event Handling

事件处理

📄 Read: references/callbacks-and-events.md

onChanged callback (continuous updates)
onChangeStart callback (interaction start)
onChangeEnd callback (interaction complete)
Complete lifecycle examples
Validation and constraints in callbacks
Async operations and debouncing
Event handling patterns
Best practices for callback usage

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

onChanged回调（持续更新）
onChangeStart回调（交互开始）
onChangeEnd回调（交互完成）
完整生命周期示例
回调中的校验与约束
异步操作与防抖
事件处理模式
回调使用最佳实践

Accessibility and States

无障碍访问与状态

📄 Read: references/accessibility-and-states.md

Accessibility overview and importance
Semantic labels for screen readers
Enabled and disabled states
Keyboard navigation support
Screen reader support (VoiceOver, TalkBack)
Right-to-Left (RTL) language support
WCAG compliance guidelines
Color contrast considerations
Touch target sizing
Testing accessibility features

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

无障碍访问概览与重要性
屏幕阅读器的语义标签
启用与禁用状态
键盘导航支持
屏幕阅读器支持（VoiceOver、TalkBack）
从右到左（RTL）语言支持
WCAG合规指南
色彩对比度注意事项
触摸目标大小
无障碍功能测试

Quick Start Examples

快速入门示例

SfSlider — Basic single-value slider

SfSlider — 基础单值滑块

dart

double _value = 40.0;

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

dart

double _value = 40.0;

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

SfRangeSlider — Basic range

SfRangeSlider — 基础范围选择

dart

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

dart

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 — Range with chart child and controller

SfRangeSelector — 带图表子组件和控制器的范围选择器

dart

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(...)),
)

dart

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(...)),
)

Common Patterns

常用模式

Pattern 1: Choose widget by need

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

Single value →
```
SfSlider
```
Range selection →
```
SfRangeSlider
```
Range controlling chart/child →
```
SfRangeSelector
```

单值选择 →
```
SfSlider
```
范围选择 →
```
SfRangeSlider
```
范围控制图表/子组件 →
```
SfRangeSelector
```

Pattern 2: Controlled vs Uncontrolled

模式2：受控与非受控模式

```
SfSlider
```
and
```
SfRangeSlider
```
are typically controlled by parent state via
```
value
```
/
```
values
```
and
```
onChanged
```
.
```
SfRangeSelector
```
can be driven via
```
RangeController
```
for programmatic updates and chart integrations.

```
SfSlider
```
和
```
SfRangeSlider
```
通常通过
```
value
```
/
```
values
```
和
```
onChanged
```
由父级状态控制。
```
SfRangeSelector
```
可通过
```
RangeController
```
驱动，实现程序化更新和图表集成。

Key Properties

核心属性

SfSlider Essential Properties

SfSlider 核心属性

```
min
```
- Minimum value (double or DateTime)
```
max
```
- Maximum value (double or DateTime)
```
value
```
- Current slider value
```
interval
```
- Interval between divisions
```
stepSize
```
- Step interval for discrete values
```
onChanged
```
- Callback when value changes
```
onChangeStart
```
- Callback when drag starts
```
onChangeEnd
```
- Callback when drag ends
```
showLabels
```
- Display labels at intervals
```
showTicks
```
- Display tick marks
```
showDividers
```
- Display dividers
```
enableTooltip
```
- Enable tooltip on interaction
```
activeColor
```
- Active track color
```
inactiveColor
```
- Inactive track color
```
numberFormat
```
- NumberFormat for numeric values
```
dateFormat
```
- DateFormat for DateTime values
```
dateIntervalType
```
- Interval type for dates (years, months, days, etc.)
```
labelFormatterCallback
```
- Custom label formatting
```
tooltipTextFormatterCallback
```
- Custom tooltip formatting
```
semanticFormatterCallback
```
- Accessibility label formatting

```
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 Essential Properties

SfRangeSlider 核心属性

```
min
```
- Minimum value (double or DateTime)
```
max
```
- Maximum value (double or DateTime)
```
values
```
- Current range values (SfRangeValues with start and end)
```
interval
```
- Interval between divisions
```
stepSize
```
- Step interval for discrete values
```
onChanged
```
- Callback when values change
```
onChangeStart
```
- Callback when drag starts
```
onChangeEnd
```
- Callback when drag ends
```
dragMode
```
- Drag interaction mode (onDragStart, onThumb, betweenThumbs, both)
```
showLabels
```
- Display labels at intervals
```
showTicks
```
- Display tick marks
```
showDividers
```
- Display dividers
```
enableTooltip
```
- Enable tooltips on interaction
```
activeColor
```
- Active track color (between thumbs)
```
inactiveColor
```
- Inactive track color
```
numberFormat
```
- NumberFormat for numeric values
```
dateFormat
```
- DateFormat for DateTime values
```
dateIntervalType
```
- Interval type for dates
```
labelFormatterCallback
```
- Custom label formatting
```
tooltipTextFormatterCallback
```
- Custom tooltip formatting
```
semanticFormatterCallback
```
- Accessibility label formatting

```
min
```
- 最小值（double或DateTime）
```
max
```
- 最大值（double或DateTime）
```
values
```
- 当前范围值（包含起止值的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 Essential Properties

SfRangeSelector 核心属性

```
min
```
- Minimum value (double or DateTime)
```
max
```
- Maximum value (double or DateTime)
```
initialValues
```
- Initial range values (SfRangeValues)
```
controller
```
- RangeController for programmatic control
```
interval
```
- Interval between divisions
```
stepSize
```
- Step interval for discrete values
```
onChanged
```
- Callback when values change (optional with controller)
```
onChangeStart
```
- Callback when drag starts
```
onChangeEnd
```
- Callback when drag ends
```
dragMode
```
- Drag interaction mode (onDragStart, onThumb, betweenThumbs, both)
```
enableDeferredUpdate
```
- Enable deferred updates for performance
```
deferredUpdateDelay
```
- Delay for deferred updates
```
showLabels
```
- Display labels at intervals
```
showTicks
```
- Display tick marks
```
showDividers
```
- Display dividers
```
enableTooltip
```
- Enable tooltips on interaction
```
activeColor
```
- Active track color (between thumbs)
```
inactiveColor
```
- Inactive track color
```
child
```
- Child widget (typically charts)
```
numberFormat
```
- NumberFormat for numeric values
```
dateFormat
```
- DateFormat for DateTime values
```
dateIntervalType
```
- Interval type for dates
```
labelFormatterCallback
```
- Custom label formatting
```
tooltipTextFormatterCallback
```
- Custom tooltip formatting
```
semanticFormatterCallback
```
- Accessibility label formatting
```
enableIntervalSelection
```
- Enable selection by interval
```
showDivisors
```
- Show region dividers

```
min
```
- 最小值（double或DateTime）
```
max
```
- 最大值（double或DateTime）
```
initialValues
```
- 初始范围值（SfRangeValues）
```
controller
```
- 用于程序化控制的RangeController
```
interval
```
- 分割间隔
```
stepSize
```
- 离散值的步长间隔
```
onChanged
```
- 值变化时的回调（使用控制器时可选）
```
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
```
- 展示区域分割线

Common Use Cases

常见使用场景

Volume or brightness controls —
```
SfSlider
```
Date range filters —
```
SfRangeSlider
```
Chart zoom/segment selection —
```
SfRangeSelector
```
+ chart integration
Time-range pickers for analytics dashboards —
```
SfRangeSelector
```
Two-ended price range filter in product lists —
```
SfRangeSlider
```

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