Slider#

연속적인 값 또는 범위를 선택할 수 있는 슬라이더 컴포넌트입니다.

Live Preview#

class SliderDefaultExample extends StatefulComponent {
  const SliderDefaultExample({super.key});

  @override
  State<SliderDefaultExample> createState() => _SliderDefaultExampleState();
}

class _SliderDefaultExampleState extends State<SliderDefaultExample> {
  double _value = 50;

  @override
  Component build(BuildContext context) {
    return CoSlider(
      value: _value,
      min: 0,
      max: 100,
      onChanged: (v) => setState(() => _value = v),
    );
  }
}

class SliderDefaultExample extends StatefulWidget {
  const SliderDefaultExample({super.key});

  @override
  State<SliderDefaultExample> createState() => _SliderDefaultExampleState();
}

class _SliderDefaultExampleState extends State<SliderDefaultExample> {
  double _value = 50;

  @override
  Widget build(BuildContext context) {
    return CoSlider(
      value: _value,
      min: 0,
      max: 100,
      onChanged: (v) => setState(() => _value = v),
    );
  }
}

사용 시기 (When to Use)#

이 컴포넌트를 사용하세요:

• 볼륨, 밝기 등 연속적인 값을 직관적으로 조절할 때
• 가격 범위, 나이 범위 등 두 값 사이의 범위를 선택할 때
• 값의 상대적 위치를 시각적으로 확인하면서 조절할 때

대신 다른 컴포넌트를 사용하세요:

• Input: 정확한 숫자 입력이 필요할 때
• Progress: 사용자 조작 없이 진행률만 표시할 때
• Select: 불연속적인 옵션 중 선택할 때

기본 사용법 (Basic Usage)#

// 기본 슬라이더
CoSlider(
  value: volume,
  onChanged: handleVolumeChange,
  min: 0,
  max: 100,
)

// 단계 지정
CoSlider(
  value: rating,
  onChanged: handleRatingChange,
  min: 0,
  max: 5,
  divisions: 5,
)

// 비활성화
CoSlider(
  value: volume,
  enabled: false,
  min: 0,
  max: 100,
)

// 기본 슬라이더
CoSlider(
  value: volume,
  onChanged: handleVolumeChange,
  min: 0,
  max: 100,
)

// 단계(step) 지정
CoSlider(
  value: rating,
  onChanged: handleRatingChange,
  min: 0,
  max: 5,
  step: 1,
)

// 비활성화
CoSlider(
  value: volume,
  enabled: false,
  min: 0,
  max: 100,
)

스타일 시스템 — sliderStyle (Epic #1302)#

CoSlider 의 track + thumb chrome / 슬롯 미세 조정은 단일 sliderStyle (CoreSliderStyle) 으로 흐릅니다. Slider 는 시맨틱 enum (variant) 이 없어 behaviour 필드만 위젯 파라미터.

CoSlider(
  value: temperature,
  min: 0,
  max: 100,
  divisions: 10,
  onChanged: handleChange,
  sliderStyle: CoreSliderStyle(
    trackColor: cs.outline,
    activeColor: cs.primary,
    trackHeight: 4,
    thumbColor: cs.onPrimary,
    thumbBorderColor: cs.outline,
    thumbSize: 20,
    tickLabelStyle: CoreTextStyle(fontSize: 12, color: cs.onSurfaceVariant),
  ),
)

CoreSliderStyle 필드#

Props / Parameters#

변형 (Variants)#

단계 지정#

CoSlider(
  value: temperature,
  onChanged: handleTempChange,
  min: 16,
  max: 30,
  divisions: 14,
)

Step 지정#

CoSlider(
  value: rating,
  onChanged: handleRatingChange,
  min: 0,
  max: 5,
  step: 1,
)

동작 스펙 (Behavior)#

SliderController#

CoSlider(
  value: 50,
  min: 0,
  max: 100,
  onChanged: (v) => setState(() => _value = v),
)

• value, min, max, onChanged 기본 API
• step 또는 divisions으로 이산 값 스냅

드래그 인터랙션#

• 단일 모드: 트랙 아무 곳이나 클릭하면 썸이 이동. 썸 드래그 지원
• 범위 모드: 클릭 시 가까운 썸이 선택됨. 각 썸 독립 드래그
• 드래그 중 onChangeStart/onChangeEnd 콜백 호출

Divisions (스냅)#

CoSlider(
  value: rating,
  onChanged: handleRating,
  min: 0, max: 5, divisions: 5,
)

• divisions가 설정되면 값이 가장 가까운 단계에 스냅
• SliderValue.roundToDivisions(int) 메서드로 반올림
• 시각적 틱 마크 표시

Hint Value#

CoSlider(
  value: volume,
  onChanged: handleVolume,
  min: 0,
  max: 100,
)

내부 상수#

키보드 네비게이션#

• increaseStep / decreaseStep으로 화살표 키 단계 크기 지정
• FocusableActionDetector 기반 포커스 관리

Web 구현#

• 네이티브 HTML <input type="range"> 오버레이 (opacity-0)
• 커스텀 트랙/range div로 시각적 표현
• step 속성으로 단계 크기 지정
• showValue: true로 현재 값 라벨 표시

사용 가이드라인 (Usage Guidelines)#

✅ Do#

CoSlider(
  value: temperature,
  onChanged: handleTemp,
  min: 16, max: 30,
  divisions: 14,
)

❌ Don't#

// ❌ Bad — 정확한 금액 입력이 어려움
CoSlider(value: price, min: 0, max: 1000000, onChanged: handlePrice)

// ✅ Good — 슬라이더 + 입력 필드 조합
Row(children: [
  Expanded(child: CoSlider(value: price, min: 0, max: 1000000, onChanged: handlePrice)),
  SizedBox(width: 16),
  SizedBox(width: 80, child: CoTextField(initialValue: price.toString())),
])

✅ Do#

CoSlider(
  value: minPrice,
  onChanged: handleMinPriceFilter,
  min: 0,
  max: 500000,
  step: 10000,
)
CoSlider(
  value: maxPrice,
  onChanged: handleMaxPriceFilter,
  min: 0,
  max: 500000,
  step: 10000,
)

❌ Don't#

✅ Do#

// 별점 1~5
CoSlider(
  value: stars, min: 1, max: 5, divisions: 4,
  onChanged: handleStars,
)

접근성 (Accessibility)#

키보드 인터랙션#

스크린 리더#

• Flutter: 현재 값, 최솟값, 최댓값이 시맨틱으로 전달
• Web: 네이티브 <input type="range">의 aria-valuenow, aria-valuemin, aria-valuemax 자동 적용

터치 영역#

• 썸(16px)보다 넓은 터치 영역 확보 (트랙 전체 클릭 가능)
• 모바일에서 충분한 드래그 감도

크로스 플랫폼 차이점 (Platform Differences)#

v3.0부터 기본 API (enabled, onChanged, value 등)가 통일되었습니다. 아래는 플랫폼 고유 차이점만 나열합니다.

관련 컴포넌트 (Related Components)#

• Progress: 진행률 표시. Slider는 입력, Progress는 출력
• Input: 정확한 숫자 입력. Slider와 함께 사용 가능

조합 예제#

// 가격 범위 필터 패턴
Column(
  crossAxisAlignment: CrossAxisAlignment.start,
  children: [
    Text('가격 범위'),
    SizedBox(height: 8),
    CoSlider(
      value: minPrice,
      onChanged: (v) => setState(() => minPrice = v),
      min: 0,
      max: 500000,
      step: 10000,
    ),
    CoSlider(
      value: maxPrice,
      onChanged: (v) => setState(() => maxPrice = v),
      min: 0,
      max: 500000,
      step: 10000,
    ),
    SizedBox(height: 4),
    Row(
      mainAxisAlignment: MainAxisAlignment.spaceBetween,
      children: [
        Text('₩${minPrice.toInt()}'),
        Text('₩${maxPrice.toInt()}'),
      ],
    ),
  ],
)