Slider · Tinyrack Design System

가로 또는 세로 트랙에서 단일 값이나 범위를 선택해요.

핵심 속성

속성	설명
값	`TRSlider`는 `double` 하나를 다뤄요. 범위는 `RangeValues`를 다루는 별도 위젯인 `TRRangeSlider`예요. 두 위젯 모두 `defaultValue`를 받는 비제어 생성자와 `value`를 받는 `.controlled` 생성자가 있어요.
범위	`min`, `max`, `step`이 포인터와 키보드 변경을 모두 제한하고 눈금에 맞춰요. `TRRangeSlider`의 `minGap`은 스텝 개수가 아니라 값 단위의 거리이고, 움직이는 쪽 썸이 그 간격을 흡수해요. 두 썸은 서로를 밀거나 교차하지 않고 맞닿는 지점에서 멈춰요.
폼	`name`이나 숨은 입력 요소는 없어요. Flutter `Form` 안에 `TRSliderFormField`나 `TRRangeSliderFormField`를 두고 `validator`, `onSaved`, `FormState`로 값을 다루세요.
검증	검증 규칙은 폼 필드가 가져요. 폼 필드는 메시지를 `errorText`로 내려보내고, 그 문구가 트랙 아래에 표시되면서 채워진 부분에 오류 색이 입혀져요. 첫 제출 전에 메시지를 보일지는 `autovalidateMode`로 정하세요. `Form` 밖에서는 `errorText`를 직접 넘기세요.
키보드	포커스된 트랙은 Right·Up에서 `step`만큼 올라가고 Left·Down에서 같은 만큼 내려가요. 큰 단위 이동은 없고 Page Up, Page Down, Home, End는 처리하지 않아요. `TRRangeSlider`에서는 마지막 포인터 입력이 고른 썸을 방향키가 움직이고, 처음에는 아래쪽 썸이에요.
레이블	`label`은 트랙 위에 현재 값을 함께 보여주는 제목 줄을 그리고, `labelBuilder`는 보이는 텍스트와 시맨틱 값 모두를 포맷해요. 접근성 이름을 보이는 레이블과 다르게 하거나 보이는 레이블이 없을 때는 `semanticLabel`을 설정하세요.

볼륨이나 트래픽 비중처럼 알려진 범위에서 대략적인 값을 고를 때 TRSlider를 쓰세요. 위치보다 정확한 숫자가 중요하다면 TRTextField나 TRNumberField를 쓰세요.

설치

패키지를 추가한 뒤 공개 라이브러리를 가져오세요.

flutter pub add tinyrack_ui

import 'package:tinyrack_ui/tinyrack_ui.dart';

플레이그라운드

Flutter 미리보기를 불러오는 중이에요

사용법

import 'package:material_ui/material_ui.dart';
import 'package:tinyrack_ui/tinyrack_ui.dart';

TRSlider.controlled(
  label: 'Traffic',
  value: traffic,
  onValueChange: (value) => setState(() => traffic = value),
)

예시

볼륨 고유 링크

비제어 생성자가 값을 소유해요. 슬라이더는 부모가 주는 너비를 채우므로 너비를 제약하세요.

Flutter 미리보기를 불러오는 중이에요

크기 고유 링크

`uiSize`는 트랙 두께는 그대로 두고 썸과 트랙 주변 공간의 크기를 조절해요. 밀도가 높은 컨트롤 영역에 놓을 때는 `TRUiSize.md`을 쓰세요.

Flutter 미리보기를 불러오는 중이에요

방향 고유 링크

세로 슬라이더는 최댓값을 위에 두고 고정 너비를 쓰며 주어진 높이를 채워요. 트랙이 들어갈 자리가 생기도록 높이를 제약하세요.

Flutter 미리보기를 불러오는 중이에요

비활성 슬라이더 고유 링크

값은 계속 보이되 바꿀 수 없어야 한다면 `enabled: false`를 설정하세요. 시맨틱 노드에서 증가·감소 동작이 빠지므로 보조 기술도 더 이상 제공하지 않아요.

Flutter 미리보기를 불러오는 중이에요

두 썸 범위 고유 링크

`TRRangeSlider`는 `RangeValues`를 다루고 두 썸을 값 단위로 `minGap`만큼 떨어뜨려 유지해요. `labelBuilder`는 제목 줄과 시맨틱 값 양쪽에서 각 끝을 포맷하고, 방향키는 마지막 포인터 입력이 고른 썸을 움직여요.

Flutter 미리보기를 불러오는 중이에요

폼 제출 고유 링크

`TRSliderFormField`는 감싸는 `Form`에 참여하므로 `FormState.save`가 `onSaved`로 값을 모아요. 직렬화를 위한 `name`이나 숨은 입력은 없어요.

Flutter 미리보기를 불러오는 중이에요

필드가 담당하는 검증 고유 링크

썸을 60% 아래로 옮기면 오류가 나타나고, 값을 올리면 메시지가 사라져요. `AutovalidateMode.onUserInteraction`은 조작 전까지 조용히 있고, 제출할 때는 `validate`가 `save`를 막아줘요.

Flutter 미리보기를 불러오는 중이에요

API

TRSlider 속성

Prop	타입 / 기본값	용도
`defaultValue`	`double · 0`	비제어 생성자의 시작 값을 정해요. 이후에는 위젯이 값을 소유하고 변경될 때마다 `onValueChange`로 알려요.
`value`	`double? · required on .controlled`	직접 관리하는 상태로 썸을 움직여요. 위젯이 스스로 값을 바꾸지 않으니 `onValueChange` 안에서 상태를 갱신하세요.
`onValueChange`	`ValueChanged<double>? · null`	조작이 진행되는 동안 포인터와 키보드 변경마다 호출돼요. 별도의 커밋 콜백은 없으니 드래그 비용이 큰 작업은 직접 디바운스하세요.
`min, max, step`	`double · 0, 100, 1`	범위를 정해요. 값은 경계 안으로 잘리고 가장 가까운 스텝에 맞춰져요. 생성자는 `min < max`와 `step > 0`을 단언해요.
`label`	`String? · null`	트랙 위에 레이블과 현재 값을 보여주는 제목 줄을 더해요. `null`로 두면 트랙만 남으니 대신 `semanticLabel`을 주세요.
`labelBuilder`	`TRSliderLabelBuilder? · null`	제목 줄과 시맨틱 값에 쓰일 값을 포맷해요. 단위나 백분율에 사용하세요. 지정하지 않으면 정수는 소수점 없이 표시돼요.
`semanticLabel`	`String? · null`	보조 기술에 컨트롤 이름을 알려줘요. 지정하지 않으면 `label`을 따르니, 보이는 레이블이 없거나 그것만으로 뜻이 불분명할 때 설정하세요.
`errorText`	`String? · null`	트랙 아래에 오류 색 메시지를 표시하고 채워진 부분에도 그 색을 입혀요. `TRSliderFormField`가 검증기에서 이 값을 넘겨주므로, 직접 설정하는 건 `Form` 밖일 때만 하세요.
`uiSize`	`TRUiSize · TRUiSize.md`	썸과 트랙 주변에 확보되는 공간의 크기를 조절해요. 트랙 두께는 모든 크기에서 같아요. 밀도가 높은 화면에는 `TRUiSize.md`을 쓰세요.
`vertical`	`bool · false`	트랙을 세로로 세우고 최댓값을 위쪽에 둬요. 세로 슬라이더는 고정 너비를 쓰고 부모가 주는 높이를 채우니 그 높이를 제약하세요.
`enabled`	`bool · true`	포인터와 키보드 변경을 막고 시맨틱 노드에서 증가·감소 동작을 없애요. 값은 계속 보여요. Flutter는 React 문서의 `disabled` 대신 `enabled`를 써요.

TRRangeSlider 속성

Prop	타입 / 기본값	용도
`defaultValue`	`RangeValues · RangeValues(25, 75)`	비제어 생성자의 시작 쌍을 정해요. `.controlled` 생성자는 대신 `value`를 받고 이 값은 필수예요.
`minGap`	`double · 0`	두 썸 사이를 값 단위로 최소 이만큼 벌려요. 움직이는 썸이 그 간격에서 멈추고, 나머지 썸은 원래 자리에 남아요.
`onValueChange`	`ValueChanged<RangeValues>? · null`	경계와 최소 간격이 적용된 뒤의 값 쌍 전체를 변경마다 알려요.
`labelBuilder`	`TRSliderLabelBuilder? · null`	양쪽 끝을 각각 포맷해요. 제목 줄은 두 결과를 `20%–80%`처럼 en 대시로 이어요.

TRSliderFormField와 TRRangeSliderFormField

Prop	타입 / 기본값	용도
`initialValue`	`double · 0 / RangeValues · RangeValues(25, 75)`	필드의 초기값이에요. `FormState.reset`은 슬라이더를 이 값으로 되돌려요.
`validator`	`FormFieldValidator? · null`	오류 메시지를 반환해 `FormState.validate`를 막고, `null`을 반환하면 값을 받아들여요. 폼 필드는 그 메시지를 `errorText`로 슬라이더에 전달해요.
`autovalidateMode`	`AutovalidateMode? · null`	검증을 언제 실행할지 정해요. `AutovalidateMode.onUserInteraction`은 썸을 움직이기 전까지 조용히 있다가, 값이 조건을 만족하면 바로 오류를 지워요.
`onSaved`	`FormFieldSetter? · null`	`FormState.save`가 실행될 때 값을 받아요. `validate`를 통과한 뒤 제출 결과를 모을 때 쓰세요.