حقل شريط التمرير

نظرة عامة

link

Web

tanrei-slider-field

schedule

SwiftUI

TanreiSliderField

radio_button_unchecked

Jetpack Compose

TanreiSliderField

radio_button_unchecked

Flutter

TanreiSliderField

radio_button_unchecked

React Native

SliderField

radio_button_unchecked

مولَّد من docs/status/status.json, specs/slider-field.spec.json

حقل شريط تمرير، وآخر مدرَّج، ومدى

استخدم حقل شريط التمرير (slider field) لقيمة تُختار بالإحساس وتُقرأ بعد ذلك بالكلمات: حجم نص مقداره 120%، أو مسافة مقدارها 5 كم، أو سعر من 100 دولار إلى 300 دولار. شريط التمرير وحده ليست له تسمية مرسومة، ومساره لا يقول القيمة التي ضُبط عليها. وحقل شريط التمرير هو الحالة المعتادة، جاهزًا للاستخدام: تسمية، والقيمة بالكلمات، والمسار، وسطر مساعدة، وخطأ.

يُبنى من حقل وشريط تمرير. الحقل هو الإطار: التسمية، وعلامة المطلوب أو الاختياري، ونص القيمة في نهاية صف التسمية، والمساعدة، والخطأ. وشريط التمرير هو عنصر التحكم: المسار والمقابض وكل ما يفعله الشخص بها. وحقل شريط التمرير لا يرسم شيئًا من عنده وليس له أي رمز تصميم (token): فكل خاصية له هي خاصية لأحد الاثنين، تُعطى له كما هي، إلا valueHidden فهي خاصة به.

عرضه عرض المكان الذي يوضع فيه، ومساره يملؤه.

على الويب هو <tanrei-slider-field>. والمنصات الأخرى لم تنفّذه بعد.

الاستخدام

link

الخاصية value هي قيمة المقبض، وقيمة مقبض النهاية في المدى؛ والخاصية startValue هي مقبض البداية في المدى. والحدثان هما حدثا شريط التمرير نفسه: input عند كل تغيّر والشخص يسحب، و change مرة واحدة حين ينتهي التغيّر. وحين يُسمع أحدهما تكون value و startValue في الحقل قد أخذتا قيمتيهما الجديدتين.

<form>
  <tanrei-slider-field name="text-size" label="حجم النص"
    supporting-text="ينطبق على كل صفحة."
    min="50" max="200" step="10" value="120"></tanrei-slider-field>

  <!-- المدى يرسل start-value ثم value، تحت الاسم الواحد. سمِّ كل مقبض. -->
  <tanrei-slider-field name="price" label="السعر" range
    min="0" max="500" step="10" start-value="100" value="300"
    start-label="أدنى سعر" end-label="أعلى سعر"></tanrei-slider-field>
</form>

<script type="module">
  import '@tanrei/web/components/slider-field';

  // كلمات القيمة، تُعطى مرة واحدة: خاصية للعنصر، وليست خاصية HTML أبدًا.
  const percent = new Intl.NumberFormat(document.documentElement.lang, { style: 'percent' });
  const size = document.querySelector('[name="text-size"]');
  size.formatValue = (value) => percent.format(value / 100);
  size.addEventListener('input', () => applyTextSize(size.value));

  const dollars = new Intl.NumberFormat('en-US', { style: 'currency', currency: 'USD', maximumFractionDigits: 0 });
  document.querySelector('[name="price"]').formatValue = (value) => dollars.format(value);
</script>

import { SliderField } from '@tanrei/react';

<SliderField name="text-size" label="حجم النص" supportingText="ينطبق على كل صفحة."
  min={50} max={200} step={10} value={size}
  formatValue={(value) => percent.format(value / 100)}
  onInput={(event) => setSize(event.currentTarget.value)} />

القيمة بالكلمات

link

تُرسم القيمة في نهاية صف التسمية، بالكلمات التي يعطيها شريط التمرير لمقبضه، وهي الكلمات نفسها التي يسمعها قارئ الشاشة ويعرضها مؤشر القيمة. وهي، بهذا الترتيب:

الكلمات	متى
نص valueText، ونص startValueText لمقبض البداية في المدى	تكتب الكلمات بنفسك، وتكتبها من جديد عند كل حدث input.
ما تكتبه الدالة formatValue	تعطي دالة واحدة تحوّل القيمة إلى كلماتها، مرة واحدة. ويسألها شريط التمرير عن كل مقبض عند كل تغيّر.
العدد بالإعدادات المحلية للصفحة	لم يُعطَ أيٌّ منهما.

قيمتا المدى تصل بينهما شرطة متوسطة (en dash)، بترتيب القراءة: ففي تخطيط من اليمين إلى اليسار تقف كلمات البداية في اليمين، حيث مقبض البداية. وحقل شريط التمرير لا يكتب بنفسه عددًا ولا وحدة ولا كلمة.

نص قيمة يشارك التسمية سطرها، وآخر يأخذ سطرًا خاصًّا به، وحقل يخفيه

يقف نص القيمة على خط الأساس للسطر الأول من التسمية، وتلتفّ التسمية في المكان المتبقي. وحيث كان ذلك سيترك للتسمية أقل من نصف الصف، يأخذ نص القيمة سطرًا خاصًّا به بعد التسمية، ويلتفّ هناك إن لزم. والخاصية valueHidden تحذفه، لشريط تمرير لا يعني عدده شيئًا للشخص: مستوى صوت، أو سطوع. والمقبض يظل يقول قيمته للتقنيات المساعدة.

مستوى واحد إلى الأسفل

link

الحقل نفسه مكتوبًا باليد من عضويه هو الصورة نفسها، وشريط التمرير نفسه عند التقنيات المساعدة:

<tanrei-field label="حجم النص" supporting-text="ينطبق على كل صفحة." value-text="120 %">
  <tanrei-slider name="text-size" min="50" max="200" step="10" value="120"></tanrei-slider>
</tanrei-field>

<script type="module">
  const field = document.querySelector('tanrei-field');
  const slider = field.querySelector('tanrei-slider');
  slider.formatValue = (value) => percent.format(value / 100);
  // ما يفعله حقل شريط التمرير بنفسه: نص القيمة في الحقل هو نص شريط التمرير، عند كل تغيّر.
  slider.addEventListener('input', () => (field.valueText = slider.shownValueText));
</script>

الحقل نفسه مكتوبًا باليد: حقل بداخله شريط تمرير، أُعطي نص القيمة مرة واحدة، ومن دون المستمع المكتوب أعلاه لا يبقى متوافقًا مع القيمة

انزل إلى هذا المستوى حين تحتاج إلى ترتيب لا يقدّمه حقل شريط التمرير:

تحتاج إلى	استخدم
تسمية، والقيمة بالكلمات، والمسار، ومساعدة، وخطأ	حقل شريط التمرير
نص قيمة لا يقوله شريط التمرير، كجملة مثل «أي سعر»، أو شيء من عندك داخل الإطار	حقل بداخله شريط تمرير، ومعه value-text من عندك
المسار وحده، يسمّيه شيء مرسوم في مكان آخر: عمود في جدول، رسم أيقونة في شريط أدوات، عنصر التحكم بمستوى الصوت في مشغِّل وسائط	شريط التمرير وحده، وتسمّيه label الخاصة به
شريط تمرير عمودي	شريط التمرير وحده: فليس لحقل شريط التمرير اتجاه
قيمة معروفة تُكتب	حقل العدد، وحده أو بجانب شريط تمرير

ما يتغيّر في المستوى الأدنى هو الموضع الذي يُقال فيه كل شيء. الخصائص name و value و startValue تكون على شريط التمرير، وهو عندئذ عنصر التحكم الذي يلقاه النموذج، وأحداثه تُسمع عليه. أما label و disabled فتبقيان على الحقل، وهو يمرّرهما إلى شريط التمرير. ومقبض النهاية في المدى تسمّيه label الخاصة بشريط التمرير، وهي ما يسمّيه حقل شريط التمرير endLabel.

المواصفات

link

مطلوب بكلمة المنتج، واختياري، وفي حالة الخطأ، ومعطَّل

ما يعطيه كل عضو

link

الجانب	من الحقل	من شريط التمرير
الخصائص	label، labelHidden، supportingText، errorText، error، disabled، required، optional، requiredMark، requiredText، optionalText	value، startValue، range، min، max، step، origin، stops، size، valueIndicator، valueText، startValueText، startLabel، ثم endLabel وهي label الخاصة بشريط التمرير
الأحداث	—	input، change
المنافذ (slots)	label-icon	—
رموز التصميم	comp.field.*	comp.slider.*

خاصية واحدة هي لحقل شريط التمرير نفسه: valueHidden. وخاصية واحدة من خصائص الحقل يملؤها حقل شريط التمرير بنفسه وليس لك أن تعيّنها: valueText في الحقل، من كلمات شريط التمرير.

لشريط التمرير disabled و orientation خاصتان به. وليست أيٌّ منهما من خصائص حقل شريط التمرير: فالخاصية disabled في الحقل تعطّل شريط التمرير، لتتبعها التسمية ونص القيمة، والمسار يمتد دائمًا في اتجاه السطر: فليس لحقل شريط التمرير اتجاه عمودي.

لشريط التمرير قيمة دائمًا، فالخاصية required لا تعني هنا «غير فارغ». والنموذج الذي يعلّم كل عنصر تحكم مطلوبًا أو اختياريًّا يعلّم هذا أيضًا؛ وما يرفضه، كمستوى مقداره 0 أو مدى أضيق مما ينبغي، عليك أن تقوله بالخاصيتين error و errorText. والخطأ لا يغيّر شيئًا في المسار: الكلمات وحالة عدم الصلاحية هما اللتان تحملانه.

ما تفعله المقابض، أي السحب والمفاتيح والدرجات ومؤشر القيمة، في صفحة شريط التمرير. وما يفعله الإطار، أي علامة المطلوب ونص القيمة والمساعدة والخطأ وكيف يُعلَن، في صفحة الحقل.

تخصيص حقل واحد دون غيره

link

ليس لحقل شريط التمرير رمز تصميم خاص به. إطاره يقرأ رموز تصميم الحقل، ومساره يقرأ رموز تصميم شريط التمرير، أينما عُيِّنت. ولتغيير مثيل واحد، عيِّن رمز تصميم العضو عليه:

<tanrei-slider-field label="مستوى الصوت" value="40"
  style="--tanrei-comp-field-standard-value-text-color: var(--tanrei-sys-color-on-surface)"></tanrei-slider-field>

البنية

البنية

مرسوم فوق نموذج الاختبار default كما ترسمه حزمة الويب.

الجزء	الوصف
1 field	The Field itself: the label row with its label glyph, its requirement mark and, at its end, the value text; and the supporting row with the help and the error text. Drawn by the Field from the Field's tokens. A member: it frames the component.
2 slider	The Slider itself, as the Field's one control: its track, active track, handles, stop dots, state layer, value indicator and focus ring, drawn by the Slider from the Slider's tokens. A member: it holds the component's value.

الخصائص

الخاصية	النوع	القيمة الافتراضية	الوصف
label	string	""	Names the control, visibly and to assistive technology. Required, unless the control names itself (a checkbox or a switch with its own label): then leave it empty and the field adds only help and an error. — Field Drawn above the track and, for one handle, its accessible name. While range is true it is the visible name of the pair, and each handle is named by startLabel and endLabel (SLF-5).
labelHidden	boolean	false	Does not draw the label, which stays the accessible name. For a control whose visible label is elsewhere (a table column, a toolbar). — Field The label row takes the value text with it (FLD-29).
supportingText	string	""	Help shown below the control and given to assistive technology as the control's description. While the field is in error it gives way to errorText, unless the design system keeps both (comp.field.error-text.placement append). — Field
errorText	string	""	Shown while error is true, in supportingText's place — or below it, which then stays, where the design system's comp.field.error-text.placement is append: what is wrong and how to put it right, in words. — Field
error	boolean	false	Puts the field in the error condition: the error text is drawn, the control is exposed as invalid and, where it has an error condition of its own, drawn in it. What a value means is the product's to validate; the field never sets this itself. — Field A slider has no error condition of its own to draw (FLD-8): the track and the handles stay as they are, and each handle is exposed as invalid.
disabled	boolean	false	Disables the control and draws the frame as disabled. Disable a framed control here, not on the control, so that its label follows. — Field The one disabled of the slider field: the Field passes it to the Slider (FLD-14, SLD-20), whose own disabled is not a prop here, so that the label and the value text always follow.
required	boolean	false	What the form asks of the control: true exposes it as required and draws the required mark beside the label. It never validates: a missing answer is the product's to report with error. — Field
optional	boolean	false	Draws the optional tag after the label and adds optionalText to the control's description, because assistive technology has no state for it. Ignored while required is true: a control is never both. — Field
requiredMark	auto | tag | asterisk | none	"auto"	How this control shows that it is required: tag is a small filled Tag with requiredText, asterisk is "*" after the label, none draws nothing and keeps the semantics. Auto takes comp.field.requirement.mark, which follows sys.behavior.requirement-mark, the system's one answer. Ignored unless required is true. — Field
requiredText	string	""	The text of the required tag, in the product's language ("Required", "必須"). The product's: Tanrei has no word for it. Empty reads the product's words; with neither, FLD-24 says what is drawn. — Field
optionalText	string	""	The text of the optional tag, in the product's language ("Optional", "任意"); also read to assistive technology as part of the description. The product's: Tanrei has no word for it. Empty reads the product's words. — Field
value	number	0	The value of the only handle, or of a range's end handle. — Slider
startValue	number	0	The value of a range's start handle. Ignored while range is false. — Slider
range	boolean	false	Draws two handles, choosing the range from startValue to value (a price filter). — Slider
min	number	0	The lowest value, at the track's start. — Slider
max	number	100	The highest value, at the track's end. — Slider
step	number	0	0 is continuous. Above 0 the slider is discrete: its values are min plus whole multiples of step, up to max. — Slider
origin	number	null	Where the active track starts. Null starts it at min. A value inside the range makes a centered slider (a balance control) whose active track grows toward either side. Ignored while range is true. — Slider
stops	boolean	false	Draws a stop dot at every value a discrete slider can take. Meant for a few steps; ignored while step is 0. — Slider
size	small | medium | large	"small"	The track's weight and the stop dots' size (and, where a system says so, the handle's height). Small is the everyday slider; medium and large give a prominent control (a volume or brightness slider) more weight. The hit area always meets the minimum target. A design system may add values. — Slider Changes nothing of the frame.
valueIndicator	none | active | always	"none"	Whether a handle shows its value beside it: never, while it is pressed or has keyboard focus, or all the time. — Slider
valueText	string	""	The value as words ("40 %", "3 stars"), spoken and shown by the value indicator in place of the number. For a range, the end handle's. — Slider Also drawn at the end of the label row (SLF-3).
startValueText	string	""	The start handle's valueText, for a range. — Slider
startLabel	string	""	Names a range's start handle ("Minimum price"). Required while range is true. — Slider
endLabel	string	""	Names the slider (a range's end handle) for assistive technology. Never drawn: a visible label is the product's text next to the slider, in the same words. Required. — Slider The Slider's label under the name of the handle it names, because label is the visible name here. Read only while range is true, and required then (SLF-5).
valueHidden	boolean	false	Does not draw the value at the end of the label row. For a slider set by feel, whose number means nothing to the person (a volume, a brightness). The handle still says its value to assistive technology, and valueIndicator still shows it.

المنافذ

المنفذ	الوصف
label-icon	A glyph before the label. — Field

الأحداث

الحدث	الوصف
input	The person changed a value; carries value and, for a range, startValue. Emitted for every change during a drag, not when the product sets a value. — Slider
change	The person finished changing a value (the press ended, or a key or assistive-technology adjustment was made); carries value and, for a range, startValue. Always after the input it follows. — Slider

الحالات

السلوك

متطلبات بصيغة EARS. يُختبر تنفيذ كل منصة مقابل هذه المعرّفات. يُعرض نص المتطلبات كما ورد في ملف المواصفة، بالإنجليزية.

المعرّف	المتطلب
SLF-1	THE slider field SHALL be a Field whose one control is a Slider — the two components themselves, each drawn from its own tokens in every state and behaving by its own sentences (FLD-1 to FLD-24, FLD-29 and FLD-30; SLD-1 to SLD-26) — and SHALL draw nothing of its own, have no token of its own, and give neither member a look, a state or a size that the member does not have where it stands alone.
SLF-2	THE slider field SHALL give each member the value of every prop that is that member's, at once and whenever it changes, and SHALL hold none back: the Field takes label, labelHidden, supportingText, errorText, error, disabled, required, optional, requiredMark, requiredText, optionalText and the glyph of the label-icon slot; the Slider takes value, startValue, range, min, max, step, origin, stops, size, valueIndicator, valueText, startValueText, startLabel and, as its own label, endLabel. THE slider field SHALL give the Slider no orientation, so that the track always runs along the line (SLD-21), and SHALL NOT set the Slider's own disabled: the Field disables its control (FLD-14).
SLF-3	WHILE valueHidden is false THE slider field SHALL give the Field, as its value text (FLD-29), the words the Slider gives its handle as that handle's value (SLD-18): WHILE range is false the only handle's; WHILE range is true the start handle's, an en dash with a space on each side, and the end handle's, each of the two an isolated run and the two in reading order, so that in a right-to-left layout the start's words stand at the right of the dash as the start handle stands at the right of the track. THE slider field SHALL NOT write a number, a unit or a word itself. WHILE valueHidden is true THE slider field SHALL give the Field no value text.
SLF-4	WHEN a value changes — at every input of a drag, by a key, by assistive technology, because the product set value or startValue, or because min, max or step changed what the Slider draws (SLD-22) — or valueText, startValueText or the product's function for a value changes, THE slider field SHALL show the new value text in the same frame in which the handle is drawn at its new place, without a motion and without an announcement of its own: the handle says its value to assistive technology itself (SLD-19), and the Field keeps the drawn text from it (FLD-30).
SLF-5	WHILE range is false THE slider field SHALL have its handle named by label, as the Field names its control (FLD-10). WHILE range is true THE slider field SHALL have the start handle named by startLabel and the end handle by endLabel (SLD-19), which should each hold the words of label so that what is seen is in what is heard, and WHILE either is empty SHALL have that handle named by label and in debug builds report that a handle of a range has no name of its own. THE slider field SHALL have every handle described by the text the supporting row shows, with optionalText while optional is true (FLD-11), and exposed as invalid while error is true (FLD-8); WHILE required is true it SHALL have every handle exposed as required where the platform's slider has such a state and, where it has none (the web's slider role), SHALL have requiredText added to the handle's description instead.
SLF-6	THE slider field SHALL hold value and startValue as its own and report them as the Slider does: WHEN the Slider emits input or change THE slider field SHALL emit the same event exactly once, carrying value and, for a range, startValue (SLD-2 to SLD-4), with its own value and startValue already equal to what the event carries; WHEN the product sets value or startValue THE slider field SHALL emit nothing (SLD-16). WHERE the platform has forms THE slider field SHALL be the one control the form sees — it carries the name, submits what the Slider submits, is reset and restored as the Slider is, and submits nothing WHILE disabled is true — and neither member SHALL be a second one.
SLF-7	THE slider field SHALL add no stop to the focus order and handle no key: its only focus stops are the Slider's handles, in the Slider's order (SLD-5), and every key is the Slider's (SLD-3). WHEN focus is given to the slider field itself, or the person presses the label row (FLD-12), THE slider field SHALL move focus to the only handle and, WHILE range is true, to the start handle, and SHALL change no value.
SLF-8	WHILE disabled is true THE slider field SHALL be a disabled Field holding a disabled Slider (FLD-14, SLD-20): no handle takes focus or changes, no event is emitted, the value indicator is not shown, and the label, the requirement mark, the supporting row and the value text are drawn from the Field's disabled tokens; THE slider field SHALL keep the value text drawn, because what a disabled control is set to is still read.
SLF-9	WHILE the text size is enlarged THE slider field SHALL grow as the Field grows (FLD-16) and SHALL leave the Slider's track, handles and hit area as they are (SLD-7); at 200% in a width of 320 no text SHALL be cut, lie over another part or need scrolling in two directions: the label wraps beside the value text, and a value text too wide to share the label's line moves whole to a line of its own (FLD-29).
SLF-10	THE slider field SHALL take its layout direction from where it is used and have no direction setting of its own, and its two members SHALL take the same one (FLD-19, SLD-25). WHERE the layout direction is right-to-left the frame and the track mirror together — the label row starts at the right with the value text at its left end (FLD-18), the track runs from the right (min) to the left (max) and the arrow keys follow it (SLD-21) — and the words of a value SHALL NOT be mirrored: each is laid out as text of its own direction (FLD-21, SLD-26), so that a number keeps its digits, its sign and its unit in their own order.
SLF-11	WHERE the platform draws with a person's own forced colors THE slider field SHALL add nothing and remove nothing: the Field draws its texts as FLD-17 says and the Slider its track and handles as it does standing alone, and the error SHALL still be carried by the words of errorText and by the invalid state of each handle (FLD-8), never by a color.
SLF-12	THE slider field SHALL be, in what is drawn and in what assistive technology is told, exactly what a Field holding a Slider is when a product writes the two by hand with the same props and gives the Field the same value text, which is the one prop of a member the slider field fills itself: every fixture of the slider field and its twin among the Field's fixtures are the same picture, with the same names, descriptions, values and states, and a difference is a defect of the slider field.
SLF-13	THE slider field SHALL be a block as wide as its place in the layout, with no width of its own, and its Slider SHALL fill it from the start edge to the end edge, as a Slider standing in a Field does (FLD-1); the label row and the supporting row are as wide as the track's box.
SLF-14	WHERE the platform has ARIA attributes (the web), WHEN the product sets an aria- attribute on the host, by the attribute or by the ARIA property that reflects it, THE slider field SHALL move it to the data-aria- attribute of the same name, so that the host is no second node with its name, description or state, and SHALL expose it on the element that carries its role — an id reference by the elements it names in the host's tree or a tree around it, an error message as part of the description while the slider field is invalid — except those the slider field owns (aria-label, aria-labelledby, aria-disabled), which it SHALL move and not expose: its name is label (SLF-5). WHEN the product removes the aria- attribute or its data-aria- twin, or sets the ARIA property that reflects it (ariaLabel, ariaDescribedByElements…) to null, THE slider field SHALL take it off that element. WHEN the product sets an aria- attribute the slider field owns THE slider field SHALL report it in debug builds.

مطابقة الأسماء بين المنصات

التكافؤ لا يعني واجهات برمجية متطابقة. تعبّر كل منصة عن العقد نفسه بأسلوبها.

المواصفة	Web	SwiftUI	Jetpack Compose	Flutter	React Native
المكوّن	tanrei-slider-field	TanreiSliderField	TanreiSliderField	TanreiSliderField	SliderField
label · الخاصية	label	label	label	labelText	label
labelHidden · الخاصية	labelHidden	labelsHidden	labelHidden	labelHidden	labelHidden
supportingText · الخاصية	supportingText	supportingText	supportingText	helperText	supportingText
errorText · الخاصية	errorText	errorText	errorText	errorText	errorText
error · الخاصية	error	error	isError	isError	error
disabled · الخاصية	disabled	disabled	enabled	enabled	disabled
required · الخاصية	required	isRequired	required	required	required
optional · الخاصية	optional	isOptional	optional	optional	optional
requiredMark · الخاصية	requiredMark	requiredMark	requiredMark	requiredMark	requiredMark
requiredText · الخاصية	requiredText	requiredText	requiredText	requiredText	requiredText
optionalText · الخاصية	optionalText	optionalText	optionalText	optionalText	optionalText
value · الخاصية	value	value	value	value	value
startValue · الخاصية	startValue	value	value	start	startValue
range · الخاصية	range	value	value	range	range
min · الخاصية	min	bounds	valueRange	min	minimumValue
max · الخاصية	max	bounds	valueRange	max	maximumValue
step · الخاصية	step	step	step	step	step
origin · الخاصية	origin	origin	origin	origin	origin
stops · الخاصية	stops	showsStops	showStops	showStops	stops
size · الخاصية	size	size	size	size	size
valueIndicator · الخاصية	valueIndicator	valueIndicator	valueIndicator	valueIndicator	valueIndicator
valueText · الخاصية	valueText	valueText	stateDescription	semanticValue	valueText
startValueText · الخاصية	startValueText	startValueText	startStateDescription	startSemanticValue	startValueText
startLabel · الخاصية	startLabel	startLabel	startContentDescription	startSemanticLabel	startAccessibilityLabel
endLabel · الخاصية	endLabel	endLabel	endContentDescription	endSemanticLabel	endAccessibilityLabel
valueHidden · الخاصية	valueHidden	valueHidden	valueHidden	valueHidden	valueHidden
input · الحدث	input	value	onValueChange	onChanged	onValueChange
change · الحدث	change	onCommit	onValueChangeFinished	onChangeEnd	onSlidingComplete
ملاحظات	Class TanreiSliderField; React SliderField. A custom element with a shadow root that holds its members' own elements, composed as every field element is: <tanrei-field> in the shadow root, and in its default slot one <tanrei-slider> with no label of its own while range is false; the host's label-icon slot is passed on to the Field's. The host is display: block and as wide as its place (SLF-13). What differs here: (1) static formAssociated = true on the host, which carries name, submits what the Slider submits (the value; for a range the start value and then the value under the same name), and resets and restores it — the inner Slider has no name and is outside the form; (2) the shadow root does not delegate focus, because a press on the help or the error text must do nothing (FLD-12): focus() is overridden to go to the first handle, and the Slider's own shadow root delegates as before; (3) input and change leave the shadow root once each with the host as their target, after the host's value and startValue are set; (4) exportparts gives the Slider's documented parts under their own names and the Field's under theirs, with the two members' hosts as the parts field and slider, and the host has no other part of its own; (5) the host writes the Field's value-text from the Slider's value text at every input, in the same task, and joins a range's two in two <bdi> runs with an en dash between; (6) formatValue is a property of the host, never an attribute, ((value: number) => string) | null, null by default, handed to the Slider (field.formatValue = (value) => percent.format(value / 100)). Attributes are kebab-case and are the members': label-hidden, supporting-text, error-text, required-mark, required-text, optional-text, start-value, value-indicator, value-text, start-value-text, start-label, and end-label, value-hidden. No custom property of a member is written by the host: a token set on the host for one instance (--tanrei-comp-field-…, --tanrei-comp-slider-…) reaches the member by inheritance. Words: required-text and optional-text left empty read setWords(), as the Field's do. One level down, the same picture and the same tree: <tanrei-field label="Volume" value-text="40"><tanrei-slider name="volume" value="40"></tanrei-slider></tanrei-field>, with the product writing value-text at each input. With scripting off nothing of it is drawn and nothing is submitted, as for every control with a shadow root.	Planned. Not built on this platform yet, nor is this platform's Field: TanreiSliderField(_ label:, value: Binding<Double>, in bounds: ClosedRange<Double> = 0...100, step:, supportingText:, errorText:, error:, required:, optional:, format: ((Double) -> String)? = nil), a view whose body is TanreiField(label, valueText: …) { TanreiSlider(value: $value, in: bounds, …) }; a range is the initializer whose value is a Binding<ClosedRange<Double>> and which takes startLabel and endLabel. labelHidden follows .labelsHidden() and disabled follows .disabled(_:), as the Field's do. One field set apart: .tanreiTheme(_:) on the view.	Planned. Not built on this platform yet, nor is this platform's Field: TanreiSliderField(label = "Volume", value = volume, onValueChange = { volume = it }, valueRange = 0f..100f, supportingText = …, isError = …, format: ((Float) -> String)? = null), a composable that calls TanreiField(label, valueText = …) { TanreiSlider(…) }; a range is the overload whose value is a ClosedFloatingPointRange<Float>. enabled is the inverse flag. The Slider's names are kept for what is its own (stateDescription), though the slider field also draws that text. One field set apart: TanreiTheme(…) { } around the call.	Planned. Not built on this platform yet, nor is this platform's Field: TanreiSliderField(labelText: 'Volume', value: volume, onChanged: (v) => …, helperText: …, errorText: …, isError: …, format: (double value) => …), a widget that builds TanreiField(labelText:, valueText:, child: TanreiSlider(…)); a range is the named constructor TanreiSliderField.range(start:, end:, onChanged: (start, end) {…}). enabled is the inverse flag; a null onChanged also disables it, as the Slider's does. One field set apart: a TanreiTheme widget around it.	Planned. Not built on this platform yet, nor is this platform's Field: <SliderField label="Volume" value={volume} onValueChange={setVolume} supportingText="…" formatValue={(value) => …} />, a component that renders <Field label valueText={…}><Slider … /></Field>; a range adds range and startValue, and both callbacks receive (value, startValue). One field set apart: a provider around it.

الرموز

الرمز	يشير إلى	القيمة المحلولة (فاتح)
--tanrei-comp-field-counter-gap	sys.space.space200	16px
--tanrei-comp-field-error-text-gap	sys.space.space50	4px
--tanrei-comp-field-error-text-placement	—	0
--tanrei-comp-field-label-icon-gap	sys.space.space100	8px
--tanrei-comp-field-label-icon-size	sys.icon.small	20px
--tanrei-comp-field-label-gap	sys.space.space100	8px
--tanrei-comp-field-motion-state-duration	sys.motion.role.state.default	250ms
--tanrei-comp-field-motion-state-easing	sys.motion.easing.state	cubic-bezier(0.2, 0, 0, 1)
--tanrei-comp-field-requirement-asterisk-gap	sys.space.space25	2px
--tanrei-comp-field-requirement-gap	sys.space.space100	8px
--tanrei-comp-field-requirement-mark	sys.behavior.requirement-mark	0
--tanrei-comp-field-standard-counter-color	sys.color.on-surface-variant	#4b4b4b
--tanrei-comp-field-standard-disabled-counter-color	—	#1b1b1b · 38%
--tanrei-comp-field-standard-disabled-error-text-color	—	#1b1b1b · 38%
--tanrei-comp-field-standard-disabled-error-counter-color	—	#1b1b1b · 38%
--tanrei-comp-field-standard-disabled-error-label-icon-color	—	#1b1b1b · 38%
--tanrei-comp-field-standard-disabled-error-label-color	—	#1b1b1b · 38%
--tanrei-comp-field-standard-disabled-error-required-asterisk-color	—	#1b1b1b · 38%
--tanrei-comp-field-standard-disabled-error-supporting-text-color	—	#1b1b1b · 38%
--tanrei-comp-field-standard-disabled-error-value-text-color	—	#1b1b1b · 38%
--tanrei-comp-field-standard-disabled-label-icon-color	—	#1b1b1b · 38%
--tanrei-comp-field-standard-disabled-label-color	—	#1b1b1b · 38%
--tanrei-comp-field-standard-disabled-required-asterisk-color	—	#1b1b1b · 38%
--tanrei-comp-field-standard-disabled-supporting-text-color	—	#1b1b1b · 38%
--tanrei-comp-field-standard-disabled-value-text-color	—	#1b1b1b · 38%
--tanrei-comp-field-standard-error-text-color	sys.color.error	#cd262f
--tanrei-comp-field-standard-error-counter-color	sys.color.on-surface-variant	#4b4b4b
--tanrei-comp-field-standard-error-label-icon-color	sys.color.on-surface-variant	#4b4b4b
--tanrei-comp-field-standard-error-label-color	sys.color.on-surface	#1b1b1b
--tanrei-comp-field-standard-error-required-asterisk-color	sys.color.primary	#1b1b1b
--tanrei-comp-field-standard-error-supporting-text-color	sys.color.on-surface-variant	#4b4b4b
--tanrei-comp-field-standard-error-value-text-color	sys.color.on-surface-variant	#4b4b4b
--tanrei-comp-field-standard-focused-counter-color	—	#4b4b4b
--tanrei-comp-field-standard-focused-error-text-color	—	#cd262f
--tanrei-comp-field-standard-focused-error-counter-color	—	#4b4b4b
--tanrei-comp-field-standard-focused-error-label-icon-color	—	#4b4b4b
--tanrei-comp-field-standard-focused-error-label-color	—	#1b1b1b
--tanrei-comp-field-standard-focused-error-required-asterisk-color	—	#1b1b1b
--tanrei-comp-field-standard-focused-error-supporting-text-color	—	#4b4b4b
--tanrei-comp-field-standard-focused-error-value-text-color	—	#4b4b4b
--tanrei-comp-field-standard-focused-label-icon-color	—	#4b4b4b
--tanrei-comp-field-standard-focused-label-color	—	#1b1b1b
--tanrei-comp-field-standard-focused-required-asterisk-color	—	#1b1b1b
--tanrei-comp-field-standard-focused-supporting-text-color	—	#4b4b4b
--tanrei-comp-field-standard-focused-value-text-color	—	#4b4b4b
--tanrei-comp-field-standard-label-icon-color	sys.color.on-surface-variant	#4b4b4b
--tanrei-comp-field-standard-label-color	sys.color.on-surface	#1b1b1b
--tanrei-comp-field-standard-required-asterisk-color	sys.color.primary	#1b1b1b
--tanrei-comp-field-standard-supporting-text-color	sys.color.on-surface-variant	#4b4b4b
--tanrei-comp-field-standard-value-text-color	sys.color.on-surface-variant	#4b4b4b
--tanrei-comp-field-supporting-text-gap	sys.space.space50	4px
--tanrei-comp-field-value-text-gap	sys.space.space200	16px
--tanrei-comp-field-label-typescale	sys.typescale.label	500 14px/1.4286
--tanrei-comp-field-supporting-text-typescale	sys.typescale.label-small	500 12px/1.3333
--tanrei-comp-field-value-text-typescale	sys.typescale.label	500 14px/1.4286

نماذج الاختبار

عروض مرجعية. تلتقط كل المنصات لقطة لكل نموذج بالمعرّف نفسه حتى يمكن مقارنة النتائج.

default

label: Volume value: 40

supporting

label: Volume supportingText: Applies to alerts and media. value: 40

value-words

label: Text size value: 120 min: 50 max: 200 step: 10 valueText: 120 %

value-hidden

label: Volume value: 40 valueHidden: true

value-indicator

label: Volume value: 40 valueIndicator: always

range

label: Price value: 60 startValue: 20 range: true startLabel: Minimum price endLabel: Maximum price

range-words

label: Price supportingText: Per night, before taxes. value: 300 startValue: 100 range: true min: 0 max: 500 valueText: $300 startValueText: $100 startLabel: Minimum price endLabel: Maximum price

required

label: Volume required: true requiredText: Required value: 40

optional

label: Volume optional: true optionalText: Optional value: 40

required-asterisk

label: Volume required: true requiredMark: asterisk value: 40

error

label: Volume supportingText: Applies to alerts and media. errorText: Choose a level above 0. error: true value: 0

required-error

label: Volume errorText: Choose a level above 0. error: true required: true requiredText: Required value: 0

error-without-text

label: Volume supportingText: Applies to alerts and media. error: true value: 0

disabled

label: Volume supportingText: Applies to alerts and media. disabled: true value: 40

label-hidden

label: Volume labelHidden: true supportingText: Applies to alerts and media. value: 40

label-icon

label: Volume value: 40 slots: label-icon

long-label

label: How loud alerts, calls and media are pla… supportingText: A level the connected device cannot play… required: true requiredText: Required value: 40

long-value-text

label: Yearly income before tax value: 12500000 startValue: 3400000 range: true min: 0 max: 20000000 step: 100000 valueText: 12,500,000 startValueText: 3,400,000 startLabel: Lowest yearly income endLabel: Highest yearly income

required-ja

label: 音量 supportingText: 通知とメディアに適用されます。 required: true requiredText: 必須 value: 40

error-ja

label: 音量 errorText: 0 より大きい値を選んでください。 error: true required: true requiredText: 必須 value: 0

rtl

label: مستوى الصوت supportingText: ينطبق على التنبيهات والوسائط. required: true requiredText: مطلوب value: 40 direction: rtl slots: label-icon

error-rtl

label: עוצמת קול errorText: יש לבחור רמה מעל 0. error: true optional: true optionalText: רשות value: 0 direction: rtl

range-rtl

label: السعر value: 300 startValue: 100 range: true min: 0 max: 500 valueText: $300 startValueText: $100 startLabel: أدنى سعر endLabel: أعلى سعر direction: rtl

مولَّد من specs/slider-field.spec.json, tokens/comp/field.tokens.json, design/tokens/

ما يرسمه الويب بطريقة مختلفة

link

• جذر الظل (shadow root) في العنصر فيه عنصر <tanrei-field> بداخله عنصر <tanrei-slider>، ولا شيء غيرهما. واستيراد العنصر يعرّف الاثنين.
• العنصر مرتبط بالنماذج (form-associated). يأخذ name و form، ويرسل القيمة، والمدى يرسل قيمة البداية ثم القيمة تحت الاسم الواحد، ولا يرسل شيئًا وهو معطَّل، ويعود عند إعادة الضبط إلى قيمتي خاصيتي HTML (attributes) value و start-value، ويتبع عنصر <fieldset> المعطَّل. وعضواه لا يضيفان أي مُدخلة (entry) إلى النموذج.
• الحدثان input و change هما حدثا شريط التمرير، من النوع CustomEvent ومعهما detail.value (و detail.startValue للمدى). وهدفهما هو العنصر، و event.target.value هي القيمة الجديدة في كل مستمع.
• الخاصية formatValue خاصية للعنصر وليست خاصية HTML أبدًا: (value: number) => string، أو null.
• نصّا القيمة في المدى يُكتبان في النص الواحد الذي للخاصية value-text في الحقل، وبينهما شرطة متوسطة. وكلٌّ منهما مقطع له اتجاهه، يُحاط بعزل يتبع أول حرف قوي (first-strong isolate)، أي U+2068 و U+2069، إلا إذا كان عددًا بسيطًا مثل «$100» أو «3,400,000»، فهو مقطع واحد من اليسار إلى اليمين في الاتجاهين سلفًا، ويُكتب كما هو.
• الأجزاء: field و slider هما العضوان. وأجزاؤهما لها هنا الأسماء نفسها التي لها في المستوى الأدنى: label، label-icon، requirement-label، value-text، supporting-text؛ track، active-track، stop-indicator، container، handle، value-indicator.
• العنصر نفسه غير قابل للتركيز: فالدالة focus() تذهب إلى المقبض، وإلى مقبض البداية في المدى، وعنصر <label for> من عند الصفحة ينقل التركيز إليه.
• ليس للعنصر دور. سمِّه بالخاصية label، ومعها label-hidden حيث تُرسم التسمية في مكان آخر، ولا تسمِّه أبدًا بالخاصية aria-label، فهي لا تسمّي شيئًا هنا.
• خصائص HTML هي خصائص العضوين نفسها: label-hidden، supporting-text، error-text، required-mark، required-text، optional-text، start-value، value-indicator، value-text، start-value-text، start-label؛ ثم end-label و value-hidden.
• قبل أن يُعرَّف العنصر لا يكون له حجم، ولا يعرض إلا عنصرًا فرعيًّا في label-icon. والصفحة التي يجب أن تعمل بلا سكربت تستخدم عنصر <label> حول عنصر <input type="range"> عادي.

الإرشادات

link

افعل

link

• أعطِ كلمات القيمة بالدالة formatValue حين يكون العدد المجرَّد غير واضح: نسبة مئوية، عملة، وحدة.
• سمِّ مقبضي المدى كليهما، بالخاصيتين startLabel و endLabel، بكلمات تحمل كلمات label: «أدنى سعر» و«أعلى سعر» تحت «السعر».
• قل في supportingText ما تغيّره القيمة، حيث لا تقوله التسمية.
• قل ما يُرفض بالكلمات، بالخاصيتين error و errorText.
• استخدم valueHidden لقيمة تُضبط بالإحساس ولا يقول عددها شيئًا للشخص.

لا تفعل

link

• لا تكتب valueText مرة واحدة في الترميز لشريط تمرير يستطيع الشخص تحريكه: فالكلمات تصير خطأ بعد أول سحب. أعطِ formatValue، أو اكتب valueText من جديد عند كل حدث input.
• لا تضع حقل شريط تمرير داخل حقل. فهو حقل أصلًا؛ وتبلّغ بنيات التنقيح (debug) عن ذلك.
• لا تسمِّه بالخاصية aria-label. وحيث يجب ألا تُرسم تسمية، أعطِ label و labelHidden.
• لا تستخدم valueIndicator="always" لعرض القيمة: فنص القيمة يفعل ذلك، والمؤشر كان سيقع فوق صف التسمية.
• لا تستخدم حقل شريط التمرير لقيمة يجب أن تكون دقيقة. استخدم حقل العدد، وحده أو بجانبه.

إمكانية الوصول

link

الدور

slider

التسمية

The slider field has no role of its own: assistive technology meets the Slider's handles, each a slider (SLD-19), What the slider field ties together (SLF-5): label is the accessible name of the only handle; a range's two handles are named by startLabel and endLabel; the supporting text with, in error, the error text after it is every handle's description, with optionalText while optional is true; every handle is invalid while error is true and required, or described by requiredText where the role has no required state, while required is true. Each handle's value is said in the words of SLD-18 — valueText, or what the product's function writes, or the platform's number — and the same words are drawn at the end of the label row, where they are kept from assistive technology so that a value is not read twice (FLD-30).

الحد الأدنى للهدف

تستوفي مساحة اللمس الحد الأدنى لحجم الهدف حتى لو كان الحجم المرئي أصغر. minimum 32px · pointer 44px · spacing 8px · touch 48px

لوحة المفاتيح

المفاتيح	الإجراء
Tab / Shift+Tab	Moves focus to the handle — for a range to the start handle, then the end handle — and on from it: the stops are the Slider's, and the slider field adds none (SLF-7).
Every other key	The Slider's own, as its spec's keyboard table says (SLD-3). The slider field handles no key.

ملاحظات

• Everything else is a member's and is said in its spec: the Field's rows, requirement marks, error announcement and press on the label (FLD-2 to FLD-12); the Slider's roles, value limits, target size and contrast (SLD-7, SLD-19 and its accessibility notes).
• A value a person cannot read is a value only some people are told. The handle says its value to assistive technology, and a track does not say it to the eye; the value text at the end of the label row is drawn unless valueHidden says the number means nothing to the person.
• A number with a unit is words, and the words are the product's: valueText for a value the product writes itself, or one function from a value to its words, given once, which the Slider asks at every change (SLD-18). The slider field writes none, and joins a range's two with an en dash, which is a mark.
• A slider always has a value, so required does not mean "not empty" here: a product that marks every control of a form as required or optional marks this one too, and says with error and errorText what it refuses (a level of 0, a range too narrow).
• Dragging is never the only way (WCAG 2.5.7): a press on the track moves the handle to it, and the keys step it (SLD-2, SLD-3). A value that must be entered exactly is a number field, alone or beside a slider.
• How a state looks is a value decision of the active design system; components read the state's tokens and never compute the effect themselves.

مولَّد من specs/slider-field.spec.json, tokens/sys/measure.tokens.json

ما يتكفل به المكوّن

link

• كل مقبض شريط تمرير (slider). المقبض الواحد تسمّيه label، مرسومةً كانت أو غير مرسومة؛ ومقبضا المدى تسمّيهما startLabel و endLabel، وتسمّيهما label حيث تغيب إحداهما، وتبلّغ بنيات التنقيح عن ذلك.
• كل مقبض وصفه النص المساعد أو نص الخطأ المعروض، ومعه نص الاختياري ما دام الحقل اختياريًّا، ويُعرَض للتقنيات المساعدة على أنه غير صالح ما دامت error بالقيمة true، وعلى أنه معطَّل ما دامت disabled بالقيمة true. ودور شريط التمرير على الويب ليست له حالة للمطلوب، فحقل شريط التمرير المطلوب يقول requiredText في الوصف.
• كل مقبض يقول قيمته بالكلمات. والكلمات نفسها تُرسم في نهاية صف التسمية، وهناك تُحجب عن التقنيات المساعدة، فتُقرأ القيمة مرة واحدة.
• التسمية المرسومة، وعلامة المطلوب أو الاختياري، ونص القيمة لا تُعرَض للتقنيات المساعدة مرة ثانية، وتغيّر نص القيمة لا يُعلَن: فالمقبض يقول قيمته بنفسه.
• مواضع توقف التركيز فيه هي مقابض شريط التمرير، واحد أو اثنان في المدى، وكل مفتاح هو مفتاح شريط التمرير. والضغط على صف التسمية ينقل التركيز إلى المقبض ولا يغيّر شيئًا؛ والضغط على المساعدة لا يفعل شيئًا.
• وهو معطَّل، يبقى نص القيمة مرسومًا: فما ضُبط عليه عنصر تحكم معطَّل يظل يُقرأ.
• الاتجاه والنص المكبَّر والألوان المفروضة (forced colors) يستجيب لكل منها كل عضو بطريقته: في تخطيط من اليمين إلى اليسار ينعكس الإطار والمسار معًا وتحتفظ كلمات القيمة بترتيبها؛ وعند تكبير النص إلى 200% لا يُقصّ شيء ولا يُمرَّر شيء جانبيًّا.
• ليست له كلمات من عنده. والخاصيتان requiredText و optionalText إذا تُركتا فارغتين قرأهما الحقل من كلمات المنتج.

فجوات معروفة على الويب: قبل أن يُعرَّف العنصر لا يُرسم شيء، ومقبضا المدى لا يُعرَضان للتقنيات المساعدة مجموعةً واحدة تسمّيها label.

ما عليك فعله

link

• أعطِ label دائمًا، وأعطِ المدى startLabel و endLabel أيضًا.
• أعطِ كلمات القيمة حين لا يُفهم العدد وحده، وأبقِها صحيحة والقيمة تتغيّر.
• قل ما يُرفض بالخاصية errorText. واللون ليس الدليل الوحيد أبدًا.
• قدِّم حقل عدد بجانب شريط التمرير حيث يجب أن يُدخل الشخص قيمة دقيقة: فالسحب ليس أبدًا الطريقة الوحيدة لتحريك مقبض، وهو مع ذلك ليس طريقة لكتابة قيمة.