الانتقال إلى المحتوى الرئيسي

نظرة عامة

يدعم Slider رقمًا واحدًا أو مصفوفة من الأرقام لنطاق. أنشئ التسمية والمسار والمؤشر والمقابض داخله Root.

استخدام

حالة غير متحكم بها

استخدم defaultValue لتعيين مستوى الصوت الأولي. يتولى شريط التمرير التغييرات اللاحقة.

خيارات مرئية

قارن بين ألوان التمييز والنجاح عند القيم الدنيا والوسطى والقصوى وقيم التعطيل. تظل أشرطة التمرير المفعّلة تفاعلية.

البنية التشريحية العربية

ضع المسار والمقابض داخل Slider.Control، الذي يتعامل مع تفاعل المؤشر. تُظهر هذه الشجرة شريط تمرير بمقبض واحد.
للنطاق، أضف مقبضًا لكل قيمة مع index المطابق لها واسم مميز يمكن الوصول إليه. تبقى التسميات والمخرجات الرقمية خارج Control، كي لا تصبح جزءًا من المنطقة القابلة للسحب.

حالة متحكم بها

مرر value وحدّثه باستخدام onValueChange لتتولى التحكم في مستوى الصوت نفسه ضمن حالة React. تتلقى دالة الاستدعاء القيمة التالية وتفاصيل الحدث.
استخدم onValueChange لإبقاء القيمة المتحكم بها محدّثة أثناء التفاعل. يتعامل onValueCommitted مع القيمة النهائية عند انتهاء التفاعل، لحفظها على سبيل المثال. تتوفر دالتا الاستدعاء أيضًا في الوضع غير المتحكم به دون تولي التحكم في القيمة. تتضمن تفاصيل التغيير event المصدر، وreason التفاعل، وactiveThumbIndex، وcancel(). تستخدم تفاصيل الالتزام عقد الأحداث العام لـ Base UI ولا تتضمن إلغاء التغيير. لا يتم الالتزام بالتغيير المُلغى.

النطاق

امنح مقابض النطاق أسماء مميزة يمكن الوصول إليها وindex يتوافق مع قيمتها. يعيّن minStepsBetweenValues الحد الأدنى للفجوة بالخطوات. نوع القيمة العام للجذر هو رقم أو مصفوفة أرقام للقراءة فقط. للتحكم في نطاق، خزّن المصفوفة في حالة React ومررها عبر value وonValueChange، تمامًا كما في القيمة المفردة.

لوحة المفاتيح والمظهر

تضبط مفاتيح الأسهم مقبضًا محددًا بخطوة واحدة. ينقل مفتاحا Home وEnd المقبض نحو الحدود مع مراعاة قيود النطاق. يغيّر orientation="vertical" التخطيط واتجاه لوحة المفاتيح. استخدم disabled على Root لمنع التغييرات. عيّن color="success" للوحة الألوان البديلة؛ والافتراضي هو accent. القيمة الافتراضية لـ thumbAlignment هي edge. مرر center أو edge-client-only لتجاوزها. تظل تركيبة className وstyle وrender الأصلية متاحة في كل جزء، بما في ذلك دوال الحالة.
باستخدام محاذاة edge وedge-client-only، لا يعيد Base UI 1.8 و1.9 أبدًا قياس مقبض بعد تغيير حجم Slider.Control، ويحتفظ شريط التمرير الذي يتم تحميله أثناء إخفائه بمقابضه مخفيةً عند إظهاره (mui/base-ui#5995). تواجه مكوّنات واجهة React المشكلة نفسها عند تصييرها الأول. استخدم thumbAlignment="center" إلى أن يتضمن إصدار من Base UI الإصلاح (mui/base-ui#6000).

التكامل والأنواع الأصلية

يستنتج Slider.Root رقماً أو مصفوفة أرقام للقراءة فقط من value أو defaultValue، مع الاحتفاظ بهذا النوع في كلا الاستدعاين. يقبل SliderRootProps كليهما افتراضياً؛ استخدم SliderRootProps\<number> للمساعدات ذات القيمة الواحدة أو SliderRootProps\<readonly number[]> للمساعدات الخاصة بالنطاق. لكل جزء نوع خصائص مُصدَّر في twenty-ui/primitives/input: SliderRootProps وSliderControlProps وSliderTrackProps وSliderIndicatorProps وSliderThumbProps وSliderLabelProps وSliderValueProps. تستهدف المراجع عناصر div لـ Root وControl وTrack وIndicator وThumb وLabel، وعنصر output لـ Value. يستهدف مرجع Thumb مقبضه المرئي؛ وينتمي اسمه المتاح وقيمة النموذج الأصلية الخاصة به إلى إدخال النطاق المتداخل. استخدم name وform على Root للإرسال الأصلي، مع إدخال واحد لكل قيمة نطاق.

الإزاحة

يُنشأ المرجع من أنواع المكونات العامة. تُقبل أيضًا السمات الأصلية، بما في ذلك الأسماء التي يمكن الوصول إليها ومعالجات الأحداث، على الأجزاء التي تعرض عناصر.

Slider.Root

string | ((state: SliderRootState) => string | undefined)
CSS class applied to the element, or a function that returns a class based on the component’s state.
"accent" | "success"
افتراضي:"accent"
Color of the indicator and thumbs.
number | readonly number[]
The uncontrolled value of the slider when it’s initially rendered.To render a controlled slider, use the value prop instead.
boolean
افتراضي:"false"
Whether the slider should ignore user interaction.
string
Identifies the form that owns the slider inputs. Useful when the slider is rendered outside the form.
NumberFormatOptions
Options to format the value.
number
افتراضي:"10"
The granularity with which the slider can step through values when using Page Up/Page Down or Shift + Arrow Up/Arrow Down.
LocalesArgument
The locale used by Intl.NumberFormat when formatting the value. Defaults to the user’s runtime locale.
number
افتراضي:"100"
The maximum allowed value of the slider. Should not be equal to min.
number
افتراضي:"0"
The minimum allowed value of the slider. Should not be equal to max.
number
افتراضي:"0"
The minimum steps between values in a range slider.
string
Identifies the field when a form is submitted.
((value: TValue extends number ? number : TValue, eventDetails: SliderRootChangeEventDetails) => void)
Callback function that is fired when the slider’s value changed. Receives the new value as the first argument; the originating event is available as eventDetails.event. The value is also reflected on eventDetails.event.target.value for form integration.The eventDetails.reason indicates what triggered the change:
  • 'input-change' when the hidden range input emits a change event (for example, via form integration)
  • 'track-press' when the control track is pressed
  • 'drag' while dragging a thumb
  • 'keyboard' for keyboard input
  • 'none' when the change is triggered without a specific interaction
((value: TValue extends number ? number : TValue, eventDetails: SliderRootCommitEventDetails) => void)
Callback function that is fired when a value change is committed. Does not fire if the value did not change, or if the change was canceled. Warning: This is a generic event, not a change event.The eventDetails.reason indicates what triggered the commit:
  • 'drag' while dragging a thumb
  • 'track-press' when the control track is pressed
  • 'keyboard' for keyboard input
  • 'input-change' when the hidden range input emits a change event (for example, via form integration)
  • 'none' when the commit occurs without a specific interaction
"horizontal" | "vertical"
افتراضي:"horizontal"
The component orientation.
ReactElement<unknown, string | JSXElementConstructor<any>> | ComponentRenderFn<HTMLProps, SliderRootState>
Allows you to replace the component’s HTML element with a different tag, or compose it with another component.Accepts a ReactElement or a function that returns the element to render.
number
افتراضي:"1"
The granularity with which the slider can step through values. (A “discrete” slider.) The min prop serves as the origin for the valid values. We recommend (max - min) to be evenly divisible by the step.
CSSProperties | ((state: SliderRootState) => CSSProperties | undefined)
Style applied to the element, or a function that returns a style object based on the component’s state.
"center" | "edge-client-only" | "edge"
افتراضي:"edge"
How the thumb(s) are aligned relative to Slider.Control when the value is at min or max:
  • center: The center of the thumb is aligned with the control edge
  • edge: The thumb is inset within the control such that its edge is aligned with the control edge
  • edge-client-only: Same as edge but renders after React hydration on the client, reducing bundle size in return
"none" | "push" | "swap"
افتراضي:"push"
Controls how thumbs behave when they collide during pointer interactions.
  • 'push' (default): Thumbs push each other without restoring their previous positions when dragged back.
  • 'swap': Thumbs swap places when dragged past each other.
  • 'none': Thumbs cannot move past each other; excess movement is ignored.
number | readonly number[]
The value of the slider. For range sliders, provide an array with one value per thumb.

Slider.Control

string | ((state: SliderControlState) => string | undefined)
CSS class applied to the element, or a function that returns a class based on the component’s state.
ReactElement<unknown, string | JSXElementConstructor<any>> | ComponentRenderFn<HTMLProps, SliderControlState>
Allows you to replace the component’s HTML element with a different tag, or compose it with another component.Accepts a ReactElement or a function that returns the element to render.
CSSProperties | ((state: SliderControlState) => CSSProperties | undefined)
Style applied to the element, or a function that returns a style object based on the component’s state.

Slider.Track

string | ((state: SliderTrackState) => string | undefined)
CSS class applied to the element, or a function that returns a class based on the component’s state.
ReactElement<unknown, string | JSXElementConstructor<any>> | ComponentRenderFn<HTMLProps, SliderTrackState>
Allows you to replace the component’s HTML element with a different tag, or compose it with another component.Accepts a ReactElement or a function that returns the element to render.
CSSProperties | ((state: SliderTrackState) => CSSProperties | undefined)
Style applied to the element, or a function that returns a style object based on the component’s state.

Slider.Indicator

string | ((state: SliderIndicatorState) => string | undefined)
CSS class applied to the element, or a function that returns a class based on the component’s state.
ReactElement<unknown, string | JSXElementConstructor<any>> | ComponentRenderFn<HTMLProps, SliderIndicatorState>
Allows you to replace the component’s HTML element with a different tag, or compose it with another component.Accepts a ReactElement or a function that returns the element to render.
CSSProperties | ((state: SliderIndicatorState) => CSSProperties | undefined)
Style applied to the element, or a function that returns a style object based on the component’s state.

Slider.Thumb

string
A string value forwarded to the aria-valuetext attribute of the input. Ignored when getAriaValueText is provided.
string | ((state: SliderThumbState) => string | undefined)
CSS class applied to the element, or a function that returns a class based on the component’s state.
boolean
افتراضي:"false"
Whether the thumb should ignore user interaction.
((index: number) => string) | null
A function which returns a string value for the aria-label attribute of the input.
((formattedValue: string, value: number, index: number) => string) | null
A function which returns a string value for the aria-valuetext attribute of the input. This is important for screen reader users.
number
The index of the thumb which corresponds to the index of its value in the value or defaultValue array. This prop is required to support server-side rendering for range sliders with multiple thumbs.
Ref<HTMLInputElement>
A ref to access the nested input element.
FocusEventHandler<HTMLInputElement>
A blur handler forwarded to the input.
FocusEventHandler<HTMLInputElement>
A focus handler forwarded to the input.
KeyboardEventHandler<HTMLInputElement>
A keydown handler forwarded to the input.
ReactElement<unknown, string | JSXElementConstructor<any>> | ComponentRenderFn<HTMLProps, SliderThumbState>
Allows you to replace the component’s HTML element with a different tag, or compose it with another component.Accepts a ReactElement or a function that returns the element to render.
CSSProperties | ((state: SliderThumbState) => CSSProperties | undefined)
Style applied to the element, or a function that returns a style object based on the component’s state.
number
Optional tab index attribute forwarded to the input.

Slider.Label

string | ((state: SliderRootState) => string | undefined)
CSS class applied to the element, or a function that returns a class based on the component’s state.
ReactElement<unknown, string | JSXElementConstructor<any>> | ComponentRenderFn<HTMLProps, SliderRootState>
Allows you to replace the component’s HTML element with a different tag, or compose it with another component.Accepts a ReactElement or a function that returns the element to render.
CSSProperties | ((state: SliderRootState) => CSSProperties | undefined)
Style applied to the element, or a function that returns a style object based on the component’s state.

Slider.Value

string | ((state: SliderValueState) => string | undefined)
CSS class applied to the element, or a function that returns a class based on the component’s state.
ReactElement<unknown, string | JSXElementConstructor<any>> | ComponentRenderFn<HTMLProps, SliderValueState>
Allows you to replace the component’s HTML element with a different tag, or compose it with another component.Accepts a ReactElement or a function that returns the element to render.
CSSProperties | ((state: SliderValueState) => CSSProperties | undefined)
Style applied to the element, or a function that returns a style object based on the component’s state.