حقل الاختيار

نظرة عامة

link

Web

tanrei-select-field

schedule

SwiftUI

TanreiSelectField

radio_button_unchecked

Jetpack Compose

TanreiSelectField

radio_button_unchecked

Flutter

TanreiSelectField

radio_button_unchecked

React Native

SelectField

radio_button_unchecked

أشكال غير متوفرة في

tanrei: filled, outlined

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

حقل اختيار مطلوب، وآخر خياراته في مجموعات ومعه رسم أيقونة يدل على الحقل

كندافرنسااليابانكينيانيوزيلنداpublicطوكيوسوللشبونةبرلين

استخدم حقل الاختيار (select field) في نموذج لقيمة واحدة من قائمة معروفة ومغلقة: بلد، أو منطقة زمنية، أو خطة. وهو الحالة المعتادة، جاهزًا للاستخدام: تسمية، والصندوق الذي يعرض الخيار المختار ويفتح القائمة، وسطر مساعدة، والكلمات التي تُقال لقيمة رُفضت.

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

عرضه عرض المكان الذي يوضع فيه، وصندوقه يملؤه. لصندوق أضيق، أعطِه مكانًا أضيق.

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

الاستخدام

link

الخيارات فروع لحقل الاختيار: لكل خيار قيمة وتسمية. والخاصية value تسمّي الخيار المختار. والحدثان change و toggle هما حدثا عنصر الاختيار نفسه، وحين يُسمع أحدهما تكون value و open في الحقل قد أخذتا قيمتيهما الجديدتين.

<form>
  <tanrei-select-field name="country" label="البلد" value="jp" required required-text="مطلوب"
    supporting-text="البلد الذي تُوجَّه إليه فواتيرك.">
    <tanrei-option value="ca">كندا</tanrei-option>
    <tanrei-option value="jp">اليابان</tanrei-option>
  </tanrei-select-field>
</form>

<!-- في مجموعات، مع سطر تحت تسمية كل خيار ورسم أيقونة يدل على الحقل. -->
<tanrei-select-field label="المنطقة الزمنية" value="Europe/Lisbon">
  <span slot="leading-icon">public</span>
  <tanrei-option-group label="آسيا">
    <tanrei-option value="Asia/Tokyo" supporting-text="UTC+9">طوكيو</tanrei-option>
  </tanrei-option-group>
  <tanrei-option-group label="أوروبا">
    <tanrei-option value="Europe/Lisbon" supporting-text="UTC+0">لشبونة</tanrei-option>
  </tanrei-option-group>
</tanrei-select-field>

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

  const country = document.querySelector('[name="country"]');
  // اختار الشخص خيارًا آخر. والقيمة هي الآن القيمة الجديدة.
  country.addEventListener('change', () => save(country.value));
  // فتحها الشخص أو أغلقها؛ والإغلاق يقول السبب.
  country.addEventListener('toggle', (e) => console.log(e.detail.open, e.detail.reason));
  // التحقق من شأنك: حقل الاختيار لا يعيّن error بنفسه أبدًا.
  country.error = submitted && !ships(country.value);
  country.errorText = 'لا نستطيع الشحن إلى هذا البلد بعد. اختر بلدًا آخر.';
</script>

import { Option, SelectField } from '@tanrei/react';

<SelectField label="البلد" value={country} required requiredText="مطلوب" onChange={(event) => setCountry(event.currentTarget.value)}>
  <Option value="ca">كندا</Option>
  <Option value="jp">اليابان</Option>
</SelectField>

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

link

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

<tanrei-field label="البلد" required required-text="مطلوب"
  supporting-text="البلد الذي تُوجَّه إليه فواتيرك.">
  <tanrei-select name="country" placeholder="اختر بلدًا">
    <tanrei-option value="jp">اليابان</tanrei-option>
    <tanrei-option value="ke">كينيا</tanrei-option>
  </tanrei-select>
</tanrei-field>

الحقل نفسه مكتوبًا باليد: حقل بداخله عنصر اختيار

اليابانكينيا

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

تحتاج إلى	استخدم
تسمية، والصندوق، ومساعدة، وخطأ	حقل الاختيار
شيء من عندك داخل الإطار، بجانب الصندوق أو تحته	حقل بداخله عنصر اختيار وعنصرك أنت
الصندوق وحده، حيث تقف تسميته في مكان آخر: سمة في شريط، ترتيب فرز في شريط أدوات، خلية في جدول	عنصر الاختيار وحده، وتسمّيه label الخاصة به
قائمة طالت حتى صار الناس يفضّلون الكتابة على التمرير	مربع التحرير والسرد

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

المواصفات

link

نص مساعد مع خيار معطَّل، واختياري، وخطأ، وللقراءة فقط، ومعطَّل

المجانيةالفرقالمؤسساتأوروبا والشرق الأوسط وأفريقياآسيا والمحيط الهادئاليابانكينيااليابانكينيااليابانكينيا

الطرازان filled و outlined: تسمية الحقل تعوم في صندوق عنصر الاختيار، مع نجمة للحقل المطلوب

اليابانكينيااليابانكينيا

مع m3-like

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

link

الجانب	من الحقل	من عنصر الاختيار
الخصائص	label، labelHidden، supportingText، errorText، error، disabled، required، optional، requiredMark، requiredText، optionalText	variant، size، value، placeholder، readOnly، open، separation، iconSpace، status، statusText، emptyText
الأحداث	—	change، toggle
المنافذ (slots)	label-icon	leading-icon، والخيارات
رموز التصميم	comp.field.*	comp.input-box.* للصندوق، وهي التي يقرؤها كل صندوق إدخال؛ و comp.select.* للقائمة

لعنصر الاختيار label و labelHidden و error و disabled خاصة به. وهي ليست من خصائص حقل الاختيار: فالخاصية label في الحقل تسمّي عنصر التحكم، و error فيه تضع الصندوق في حالة الخطأ، و disabled فيه تعطّله. وهكذا تعيّن كلًّا منها مرة واحدة، على حقل الاختيار، وتسميته تتغيّر مع عنصر التحكم.

في الطراز stacked التسمية هي صف الحقل الذي فوق الصندوق. وفي الطرازين filled و outlined يرسم عنصر الاختيار التسمية نفسها بنفسه، عائمةً في صندوقه، ولا يرسم الحقل صف تسمية؛ والحقل المطلوب تعلّمه عندئذ نجمة بعد التسمية، أيًّا كانت العلامة التي يسمّيها نظام التصميم. والمساعدة تبدأ حيث تبدأ القيمة، بعد أيقونة البداية. وما دامت القائمة مفتوحة تُرسم التسمية والمساعدة في حالة التركيز، كما يُرسم الصندوق.

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

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

link

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

<tanrei-select-field label="البلد"
  style="--tanrei-comp-field-label-gap: 12px"></tanrei-select-field>

البنية

البنية

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

الجزء	الوصف
1 field	The Field: the label row with its glyph and its requirement mark, and the supporting row with the help and the error text. In a look whose select floats the label it draws no label row.
2 select	The select, as the Field's one control: the trigger with the value it shows, its leading icon and its chevron, the label that floats in it in the looks that float one, and the list of options that opens from it.

الخصائص

الخاصية	النوع	القيمة الافتراضية	الوصف
variant	stacked | filled | outlined	"stacked"	The text input's three looks, so that a select is drawn as the text inputs beside it. Stacked is a filled box that shows focus and error with a line inside its edge and draws no label: the label of the Field that frames it stands above it. Filled and outlined float the label inside the box. Use one style per form. A design system may leave some out (the Tanrei system ships stacked only) or add values. — Select
size	small | medium | large	"medium"	Minimum height of the container: stacked 32 / 40 / 56, as tall as a Button of the same size, so that the box and a Button side by side in one row stand as tall as each other; filled and outlined 40 / 48 / 56, which hold the label that floats inside them. The text input's three sizes: medium and large for forms, small for a select in an app bar, a toolbar or a dense row of controls, where nothing frames it. The hit area always meets the minimum target. A design system may add values. — Select
value	string	""	The value of the chosen option. The select shows that option's label; while value names no option it shows the placeholder. An option whose value is the empty string is a choice like any other ("None", "Any") and is the chosen one while value is empty. — Select
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 Names the select. In a filled or outlined look the select draws it, floating in its box, and the Field draws no label row (FLD-25, SEL-15).
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 Hides the label wherever it would be drawn: the Field's row, or the select's floating label (FLD-25).
placeholder	string	""	A hint shown while nothing is chosen and the label is not in the line ("Choose a country"). Never a replacement for label, and never a choice. — Select
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 The Field puts its select in the select's own error condition (FLD-8, SEL-9).
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 Field disables its select (FLD-14, SEL-46); the select field is then left out of its form (SEF-2).
readOnly	boolean	false	The value is shown, can be focused and is submitted, but cannot be changed: the list does not open and no chevron is drawn. — Select
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 The Field exposes its select as required (FLD-10, SEL-11).
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
open	boolean	false	Whether the list is shown. The select opens and closes itself and emits toggle; the product may also set it. Ignored while the select is disabled or read-only or has nothing to show: no option, no status row and no empty text (SEL-61). — Select
separation	auto | divider | gap	"auto"	How a group of options is told from what is next to it. divider: a line between them. gap: empty space and no line. Auto takes comp.select.separation, which follows the design system's choice. — Select
iconSpace	auto | always | never	"auto"	Whether an option keeps the room of the leading icon column where it has no icon, so that the labels of a section start on one line — a section being an option group, or a run of adjacent options outside any group. auto: an option keeps the column while another option of its section has a leading icon, so that a section without icons starts its labels where the row's content starts. always: every option keeps it. never: only an option that has an icon has the column. The menu's iconSpace, with the same values and default (SEL-66). — Select
density	regular | compact	"regular"	How much room an option of the list takes: its least height, its paddings, the gap between its columns and the size of its glyphs (the leading icon, the check), and never its text style. regular (a 48 row in the default system) is for a product used by touch as well as by pointer; compact (a 32 row with 20 glyphs, the menu's compact row) is for a tool used with a pointer, whose lists are long. For touch an option is never lower than the touch target in either (SEL-37). The field's own box is not changed: its height is size's. A design system may add values. — Select
status	idle | loading | error	"idle"	What the product's source of options is doing, which the product sets: idle (the options given are final), loading (options are on their way: the status row shows a loading indicator and the list is marked busy) or error (the source failed: the status row shows statusText in the error color, announced at once). The combobox's and the search's values, with the same meaning. The select never loads anything itself. — Select
statusText	string	""	The status row's text, in the product's language, read to assistive technology when the list opens and when it changes: a count ("20 of 340 projects shown"), that loading failed ("Projects could not be loaded"), or, while status is loading, the loading indicator's name ("Loading projects"). Empty draws no status row unless status is loading. — Select
emptyText	string	""	Shown in the list while the select holds no option, status is idle and statusText is empty, in the product's language ("No projects yet"), so that the select still opens and says why there is nothing to choose. The product's: Tanrei has no words for it. Empty reads the product's words (noOptionsText); with neither, the select has nothing to show and does not open (SEL-61), and it is reported. — Select

المنافذ

المنفذ	الوصف
leading-icon	A glyph at the start of the container that stands for the field whatever is chosen (a globe before a language). It takes the place of the chosen option's own glyph. — Select
label-icon	A glyph before the label. — Field

الأحداث

الحدث	الوصف
change	The person chose an option whose value differs from the select's; carries the new value. Not emitted when the product sets value, when the chosen option is chosen again, or while the person only moves through the list. — Select
toggle	The list was opened or closed by the person; carries the new open and, for a close, the reason: select, escape, back, outside, focus-out, anchor-hidden, press or tab (in the platform's casing). After a choice it follows change. — Select

العناصر

أنواع العناصر التي يكررها المكوّن. يسرد كل نموذج اختبار عناصره بالترتيب، وتسمّي كل منصة كل نوع بأسلوبها.

option

One choice of the select: a label, the value it stands for, and optionally a supporting line and a glyph.

الخاصية	النوع	القيمة الافتراضية	الوصف
label	string	""	The option's text and its accessible name; the container shows it once the option is chosen. Required.
value	string	""	Identifies the choice: the option is the chosen one while the select's value equals it. Unique within the select. The empty string is a value like any other, for an option that stands for no choice ("None").
supportingText	string	""	A line below the label that says more about the choice. Shown in the list, not in the container.
leadingIcon	string	""	The name of an icon (a glyph of the system's icon set) before the label; the container shows it too while the option is chosen and the select has no leading icon of its own.
disabled	boolean	false	Prevents the option from being chosen. It stays reachable with the arrow keys.

المواصفة	Web	SwiftUI	Jetpack Compose	Flutter	React Native
العنصر	tanrei-option	TanreiSelectOption	TanreiSelectOption	TanreiSelectOption	SelectOption
label · الخاصية	label	title	text	label	label
value · الخاصية	value	tag	value	value	value
supportingText · الخاصية	supportingText	supportingText	supportingText	supportingText	supportingText
leadingIcon · الخاصية	leadingIcon	leadingIcon	leadingIcon	leadingIcon	leadingIcon
disabled · الخاصية	disabled	disabled	enabled	enabled	disabled
ملاحظات	<tanrei-option> children of <tanrei-select-field>, exactly as of <tanrei-select>: the product's elements in the light DOM, passed to the select inside through the default slot and read by it as data (web-options.md).	The select's own option, under the same name: the select field passes it to its select and reads nothing of it.	The select's own option, under the same name: the select field passes it to its select and reads nothing of it.	The select's own option, under the same name: the select field passes it to its select and reads nothing of it.	The select's own option, under the same name: the select field passes it to its select and reads nothing of it.

option-group · مجموعة — تحتوي عناصر

A run of related options, optionally titled. The select separates a group from what is next to it by a divider or a gap.

الخاصية	النوع	القيمة الافتراضية	الوصف
title	string	""	A short heading drawn above the group's options, which also names the group; empty draws none and leaves the group unnamed.

المواصفة	Web	SwiftUI	Jetpack Compose	Flutter	React Native
العنصر	tanrei-option-group	TanreiSelectSection	TanreiSelectGroup	TanreiSelectGroup	SelectOptionGroup
title · الخاصية	label	title	title	title	title
ملاحظات	As the option: the same element, the product's child, with its options inside it.	The select's own option group, under the same name: the select field passes it to its select and reads nothing of it.	The select's own option group, under the same name: the select field passes it to its select and reads nothing of it.	The select's own option group, under the same name: the select field passes it to its select and reads nothing of it.	The select's own option group, under the same name: the select field passes it to its select and reads nothing of it.

الحالات

السلوك

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

المعرّف	المتطلب
SEF-1	THE select field SHALL be a Field that frames one select, and nothing else. It SHALL give label, labelHidden, supportingText, errorText, error, disabled, required, optional, requiredMark, requiredText and optionalText to its Field and every other prop to its select, each unchanged; SHALL hold the label-icon slot for its Field and the leading-icon slot for its select; SHALL give its select every option and option group the product gives it, in the order given, as that select's own items, read, drawn and chosen by the select (SEL-17, SEL-31 to SEL-45); and SHALL emit its select's events as its own, each once. It SHALL draw no part of its own, hold no state of its own and have no token of its own: what it shows, how it behaves and what it exposes to assistive technology SHALL be exactly what that Field and that select do when a product places the one in the other (FLD-1 to FLD-28; SEL-1 to SEL-64) — the label row and its requirement mark (FLD-2 to FLD-6), or the label that floats in the box with the Field's row left out (FLD-25, SEL-15, SEL-7); the supporting row and the error, started where the value starts (FLD-7 to FLD-9, FLD-26); the rows drawn focused while the list is open (FLD-13, SEL-20); the name, the description and the states (FLD-10, FLD-11, FLD-14, SEL-11); and the width, which is the Field's and which the select fills (FLD-1, SEL-49).
SEF-2	WHERE the platform has forms (the web) THE select field SHALL be the one control the form sees: it SHALL take name, submit its select's value, reset to the value it was first given, restore it on navigation, report to the form's constraint validation exactly what its select would report there (SEL-11), be submitted WHILE readOnly is true (SEL-47), and be left out WHILE disabled is true or a disabled group of the form holds it (SEL-46); its select and its Field SHALL take no part in the form themselves.
SEF-3	WHEN the select field is given focus — by the product, by a press on its label row (FLD-12), or by a form that reports its validity — THE select field SHALL pass the focus to its select's container and SHALL add no stop to the focus order: the one stop inside it is its select's (SEL-13). WHILE focus is anywhere inside it, or its select's list is open, THE select field SHALL count as focused for its Field (FLD-13).
SEF-4	IF the select field is placed in a Field THE select field SHALL in debug builds report that it is a field already and that the bare control is the select, and both SHALL still render (FLD-15). WHILE it stands in a field group THE select field SHALL follow that group's disabled, through its own Field, and take nothing else from the group (FGR-20).
SEF-5	THE select field SHALL have no words of its own and SHALL read none: requiredText and optionalText are read by its Field (FLD-24), emptyText by its select (SEL-62), each from the instance's prop and then from the product's words.
SEF-6	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 select 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 select field is invalid — except those the select field owns (aria-label, aria-labelledby, aria-disabled, aria-haspopup, aria-expanded, aria-controls), which it SHALL move and not expose: its name is label (SEF-1). 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 select field SHALL take it off that element. WHEN the product sets an aria- attribute the select field owns THE select field SHALL report it in debug builds.

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

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

المواصفة	Web	SwiftUI	Jetpack Compose	Flutter	React Native
المكوّن	tanrei-select-field	TanreiSelectField	TanreiSelectField	TanreiSelectField	SelectField
variant · الخاصية	variant	variant	variant	variant	variant
size · الخاصية	size	size	size	size	size
value · الخاصية	value	selection	value	value	value
label · الخاصية	label	label	label	labelText	label
labelHidden · الخاصية	labelHidden	labelsHidden	labelHidden	labelHidden	labelHidden
placeholder · الخاصية	placeholder	prompt	placeholder	hintText	placeholder
supportingText · الخاصية	supportingText	supportingText	supportingText	helperText	supportingText
errorText · الخاصية	errorText	errorText	errorText	errorText	errorText
error · الخاصية	error	error	isError	isError	error
disabled · الخاصية	disabled	disabled	enabled	enabled	disabled
readOnly · الخاصية	readOnly	readOnly	readOnly	readOnly	readOnly
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
open · الخاصية	open	isPresented	expanded	controller	open
separation · الخاصية	separation	separation	separation	separation	separation
iconSpace · الخاصية	iconSpace	iconSpace	iconSpace	iconSpace	iconSpace
density · الخاصية	density	density	density	density	density
status · الخاصية	status	status	status	status	status
statusText · الخاصية	statusText	statusText	statusText	statusText	statusText
emptyText · الخاصية	emptyText	emptyText	emptyText	emptyText	emptyText
change · الحدث	change	selection	onValueChange	onChanged	onValueChange
toggle · الحدث	toggle	isPresented	onExpandedChange	onOpenChanged	onOpenChange
ملاحظات	The tag tanrei-select-field, the class TanreiSelectField, the React name SelectField. It takes every attribute, property, event and child of the select and of its Field, under the same names. The element is composed as every field element is; what follows is what is particular to it. Members: <tanrei-field> holding one <tanrei-select> in its default slot; the product places none, and gives the options. The host is display: block, as the Field is. Value member: tanrei-select. The host is the form's element — name, the value and its state, validity anchored on the select's trigger, reset to the value attribute, restore, form, a disabled fieldset — and the select inside has no name. Props, set as properties on the member each is from. On the Field: label, labelHidden, supportingText, errorText, error, disabled, required, optional, requiredMark, requiredText, optionalText. On the select: variant, size, value, placeholder, readOnly, open, separation, iconSpace, status, statusText, emptyText, and inline, the select's attribute for tests and fixtures, which is no prop of the spec and is passed on so that an open fixture and its twin are staged alike. Attributes are the members' own: kebab-case, except readonly. Props of one name on both members — label, labelHidden, error, disabled — are the Field's; the select's are never set by the element and reach the select through the connection. Events: change is the select's own composed, bubbling Event and leaves by itself with the host as its target. toggle is the select's CustomEvent, composed and not bubbling: it is heard on the host, as on any shadow host, and by no ancestor. Two props are the select's at every moment and are read through to it, never copied — value (the element's value is its value member's) and open, by the same accessor, as the combobox field reads its three — so each is already new in every listener of change and of toggle, capturing or bubbling, and when open is taken back with no event. No listener of the element's takes either. None is stopped and none is copied. Slots: label-icon is passed to the Field and leading-icon to the select, each by a slot element of the same name rendered only while the host has a child for it. The default slot is passed to the select — <tanrei-select><slot></slot></tanrei-select> — and is always rendered, where a field element otherwise has no default slot: the product's <tanrei-option> and <tanrei-option-group> children are assigned to it, and the select reads them through it. A child that is neither, and has no slot name the element has, is not rendered and is reported in a debug build. Parts: the member hosts are field and select. Exported from the Field: label, label-icon, requirement-label, supporting-text, counter (never drawn here). Exported from the select: container, outline, active-indicator, label, requirement-label, value, placeholder, leading-icon, chevron, list, option, option-label, option-supporting-text, option-leading-icon, mark, group, group-title, divider, status. Two names collide, label and requirement-label. Each is exported with its member's name before it, always (field-label, select-label, field-requirement-label, select-requirement-label), and under the bare name from both members as well, because the two are one thing to a person and are never drawn at once: FLD-25 is the sentence that holds it. Focus: the shadow root does not delegate. focus() and blur() call the select's; a press on the label row focuses the trigger by FLD-12 and opens nothing, a press on the trigger opens the list, and a press on the help does nothing. The list is the select's own popover in the top layer: it is placed against the trigger, both in the select's shadow tree, and a press on the Field's rows is a press outside it (SEL-27). The connection is the Field's with its control, with one value more upward, drawnFocused (SEL-63, FLD-13), the same value the combobox says; the element takes no part in it. Parts and tokens of its own: none. The element writes no custom property: --tanrei-comp-field-*, --tanrei-comp-input-box-* and --tanrei-comp-select-* reach the members by inheritance, and one select field is set apart by setting any of them on the element. What its twin cannot do that it does: nothing. The twin: <tanrei-field label="Country" required supporting-text="Where your invoices are addressed."><tanrei-select name="country" value="jp"><tanrei-option value="jp">Japan</tanrei-option></tanrei-select></tanrei-field>. Before the element is defined its options are running text in the page, as a select's are: hide tanrei-select-field:not(:defined) > * and reserve the block size. Words: none of its own; required-text and optional-text left empty are read by the Field from the product's words.	TanreiSelectField("Country", selection: $country, supportingText: "…") { TanreiSelectOption("Japan").tag("jp") … }: a view whose body is TanreiField(…) { TanreiSelect(selection:) { options } } with each argument passed to the member it is from, and nothing else. The option content is the select's own, passed through as a view builder. labelHidden follows .labelsHidden() and disabled follows .disabled(_:), both read by the Field. The product's words are read by the Field from the \.tanreiWords environment value. Not built on this platform yet, nor is the select itself.	TanreiSelectField(value, onValueChange, label, supportingText = …) { TanreiSelectOption("Japan", "jp") … }: a composable that calls TanreiField(…) { TanreiSelect(…) { content() } } with each argument passed to the member it is from, and nothing else; the content lambda is the select's. enabled is the inverse flag and isError keeps Compose's name, both the Field's. The product's words are read by the Field from LocalTanreiWords. Not built on this platform yet, nor is the select itself.	TanreiSelectField(value:, onChanged:, labelText:, helperText:, options: […]): a widget that builds TanreiField(child: TanreiSelect(…)) with each argument passed to the member it is from, and nothing else; labelText, hintText, helperText, errorText and enabled keep InputDecoration's names. TanreiSelectFormField wraps it as a FormField<String> (validator, onSaved, autovalidateMode), which is how a Flutter form takes part, and its errorText is the Field's. The product's words are read by the Field from the TanreiWords inherited widget. Not built on this platform yet, nor is the select itself.	<SelectField label="Country" value={value} onValueChange={setValue} supportingText="…" options={[…]} />: a component that renders <Field …><Select … /></Field> with each prop passed to the member it is from, and nothing else; options is the select's array. The product's words are read by the Field from the TanreiWordsProvider context. Not built on this platform yet, nor is the select itself.

الرموز

الرمز	يشير إلى	القيمة المحلولة (فاتح)
--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

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

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

variant: stacked (41)

stacked-empty

variant: stacked label: Country items: 5

stacked-value

variant: stacked value: jp label: Country items: 5

stacked-open

variant: stacked value: jp label: Country open: true items: 5 مرسوم وحده في نافذة بحجم 312 × 472

stacked-large

variant: stacked size: large value: jp label: Country items: 5

stacked-small

variant: stacked size: small value: jp label: Country items: 5

stacked-error

variant: stacked label: Country errorText: Choose a country. error: true items: 5

stacked-disabled

variant: stacked value: jp label: Country disabled: true items: 5

stacked-placeholder

label: Country placeholder: Choose a country items: 5

stacked-open-none-chosen

label: Country placeholder: Choose a country open: true items: 5 مرسوم وحده في نافذة بحجم 312 × 473

stacked-label-hidden

value: fr label: Country labelHidden: true items: 5

stacked-supporting

value: jp label: Country supportingText: Where your invoices are addressed. items: 5

stacked-error-value

value: ke label: Country errorText: We cannot ship there yet. error: true items: 5

stacked-read-only

value: jp label: Country readOnly: true items: 5

stacked-required

label: Country required: true requiredText: Required items: 5

stacked-optional

label: Country placeholder: Choose a country optional: true optionalText: Optional items: 5

stacked-required-asterisk

label: Country required: true requiredMark: asterisk items: 5

stacked-required-disabled

value: jp label: Country disabled: true required: true requiredText: Required items: 5

stacked-required-error

label: Country errorText: Choose a country. error: true required: true requiredText: Required items: 5

stacked-required-ja

label: 国 placeholder: 国を選択 required: true requiredText: 必須 items: 3

stacked-optional-ja

value: jp label: 国 optional: true optionalText: 任意 items: 3

stacked-label-icon

value: Asia/Tokyo label: Time zone items: 3 slots: label-icon

stacked-option-icon

value: dark label: Theme items: 3

stacked-leading-icon

value: ja label: Language items: 2 slots: leading-icon

open-icons

value: dark label: Theme open: true items: 3 مرسوم وحده في نافذة بحجم 312 × 473

open-supporting-text

value: team label: Plan open: true items: 3 مرسوم وحده في نافذة بحجم 312 × 473

open-disabled-chosen

value: enterprise label: Plan open: true items: 3 مرسوم وحده في نافذة بحجم 312 × 473

open-groups

value: Europe/Lisbon label: Time zone open: true items: 3 مرسوم وحده في نافذة بحجم 312 × 473

open-groups-divider

value: Europe/Lisbon label: Time zone open: true separation: divider items: 3 مرسوم وحده في نافذة بحجم 312 × 473

open-groups-gap

value: Europe/Lisbon label: Time zone open: true separation: gap items: 3 مرسوم وحده في نافذة بحجم 312 × 473

open-many

value: corner.small label: Token open: true items: 24 مرسوم وحده في نافذة بحجم 312 × 473

open-long-options

value: weekly label: Email me open: true items: 3 مرسوم وحده في نافذة بحجم 312 × 473

long-value

value: all label: Email me items: 3

empty-value-option

value: label: Contrast items: 3

small-label-hidden

size: small value: high label: Contrast labelHidden: true items: 3

small-label-hidden-icons

size: small value: light label: Theme labelHidden: true items: 3

small-label-hidden-leading-icon

size: small value: en label: Language labelHidden: true items: 2 slots: leading-icon

small-label-hidden-open

size: small value: light label: Theme labelHidden: true open: true items: 3 مرسوم وحده في نافذة بحجم 312 × 473

small-open

size: small value: jp label: Country open: true items: 5 مرسوم وحده في نافذة بحجم 312 × 473

stacked-required-rtl

value: Asia/Tokyo label: المنطقة الزمنية supportingText: تُعرض المواعيد بهذا التوقيت. required: true requiredText: مطلوب direction: rtl items: 2 slots: label-icon

open-rtl

value: Asia/Tokyo label: المنطقة الزمنية open: true direction: rtl items: 2 مرسوم وحده في نافذة بحجم 312 × 473

long-value-rtl

value: all label: Email me direction: rtl items: 3

variant: filled (7)

filled-empty

variant: filled label: Country items: 5

filled-value

variant: filled value: jp label: Country items: 5

filled-open

variant: filled value: jp label: Country open: true items: 5 مرسوم وحده في نافذة بحجم 312 × 473

filled-large

variant: filled size: large value: jp label: Country items: 5

filled-small

variant: filled size: small value: jp label: Country items: 5

filled-error

variant: filled label: Country errorText: Choose a country. error: true items: 5

filled-disabled

variant: filled value: jp label: Country disabled: true items: 5

variant: outlined (9)

outlined-empty

variant: outlined label: Country items: 5

outlined-value

variant: outlined value: jp label: Country items: 5

outlined-open

variant: outlined value: jp label: Country open: true items: 5 مرسوم وحده في نافذة بحجم 312 × 473

outlined-large

variant: outlined size: large value: jp label: Country items: 5

outlined-small

variant: outlined size: small value: jp label: Country items: 5

outlined-error

variant: outlined label: Country errorText: Choose a country. error: true items: 5

outlined-disabled

variant: outlined value: jp label: Country disabled: true items: 5

outlined-required

variant: outlined label: Country required: true requiredText: Required items: 5

outlined-rtl

variant: outlined value: Europe/Lisbon label: المنطقة الزمنية direction: rtl items: 2

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

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

link

• جذر الظل (shadow root) في العنصر فيه عنصر <tanrei-field> بداخله عنصر <tanrei-select>، ولا شيء غيرهما. واستيراد العنصر يعرّف الاثنين.
• الخيارات تبقى فروعك أنت لعنصر <tanrei-select-field>. ولا تُنقل ولا تُنسخ أبدًا: تصل إلى عنصر الاختيار الداخلي عبر منفذ، وعنصر الاختيار يقرؤها من جديد حين تتغيّر. واستبدالها باليد (replaceChildren()) يعمل كما يعمل على عنصر اختيار.
• العنصر مرتبط بالنماذج (form-associated). يأخذ name و form، ويرسل القيمة وحدها، ولا يرسل شيئًا وهو معطَّل، ويظل يرسلها وهو للقراءة فقط، ويعود عند إعادة الضبط إلى قيمة خاصية HTML (attribute) value، ويتبع عنصر <fieldset> المعطَّل، ويبلّغ بأن القيمة ناقصة ما دامت required معيَّنة والقيمة فارغة. وعضواه لا يضيفان أي مُدخلة (entry) إلى النموذج.
• الحدث change هو حدث عنصر الاختيار، وهو يعبر حدود جذر الظل (composed) ويتصاعد (bubbles). والحدث toggle هو حدث عنصر الاختيار من النوع CustomEvent ومعه detail.open و detail.reason: يعبر حدود جذر الظل ولا يتصاعد، فيُسمع على العنصر ولا يسمعه أبدًا عنصر سلف مثل <details>. وهدفهما هو العنصر، و event.target.value و event.target.open جديدتان في كل مستمع.
• الأجزاء: field و select هما العضوان. وأجزاؤهما لها هنا الأسماء نفسها التي لها في المستوى الأدنى: label-icon، supporting-text؛ container، outline، active-indicator، value، placeholder، leading-icon، chevron، list، option، option-label، option-supporting-text، option-leading-icon، mark، group، group-title، divider، status. والجزآن label و requirement-label هما المرسوم من الاثنين، أي صف الحقل أو التسمية العائمة في عنصر الاختيار، والأجزاء field-label و select-label و field-requirement-label و select-requirement-label تسمّي ما لعضو واحد وحده.
• العنصر نفسه غير قابل للتركيز: فالدالة focus() تذهب إلى المشغِّل، وعنصر <label for> من عند الصفحة ينقل التركيز إليه. والضغط على صف التسمية ينقل التركيز إلى المشغِّل ولا يفتح شيئًا؛ والضغط على المشغِّل يفتح القائمة؛ والضغط على المساعدة لا يفعل شيئًا.
• ليس للعنصر دور. سمِّه بالخاصية label، ومعها label-hidden حيث تُرسم التسمية في مكان آخر، ولا تسمِّه أبدًا بالخاصية aria-label، فهي لا تسمّي شيئًا هنا.
• خصائص HTML هي خصائص العضوين نفسها: label-hidden، supporting-text، error-text، required-mark، required-text، optional-text، readonly.
• الفرع الذي ليس خيارًا ولا مجموعة خيارات ولا رسم أيقونة للمنفذ label-icon أو leading-icon لا يُرسم؛ وتبلّغ بنيات التنقيح (debug) عن ذلك.
• قبل أن يُعرَّف العنصر، تكون خياراته نصًّا جاريًا في الصفحة. أخفِ tanrei-select-field:not(:defined) > * واحجز الارتفاع. والصفحة التي يجب أن تعمل بلا سكربت تستخدم عنصر <select> أصليًّا مع عنصر <label> خاص به.

الإرشادات

link

افعل

link

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

لا تفعل

link

• لا تستخدم حقل اختيار مع labelHidden في شريط أو شريط أدوات. فذاك عنصر الاختيار مجرَّدًا، تسمّيه label الخاصة به.
• لا تستخدم النص النائب تسميةً. فهو يختفي ما إن يُختار شيء.
• لا تنقل إلى صفحة أخرى ولا ترسل ولا تحذف عند الحدث change من غير أن تقول ذلك. فالناس يتنقلون في القائمة ليقرؤوها.
• لا تضع حقل اختيار داخل حقل. فهو حقل أصلًا؛ وتبلّغ بنيات التنقيح عن ذلك. وعنصر التحكم الذي يؤطّره الحقل هو عنصر الاختيار.
• لا تسمِّه بالخاصية aria-label. وحيث يجب ألا تُرسم تسمية، أعطِ label و labelHidden.

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

link

الدور

combobox

التسمية

The select field adds nothing to what its members expose and coordinates nothing: the Field gives the select its name, its description and its required, invalid and disabled states (FLD-8, FLD-10, FLD-11, FLD-14), and the select carries them on its own trigger and names its list by the same name (SEL-11, SEL-48). Assistive technology meets one control that opens a list of choices, named by label, with the chosen option's label as its value — exactly as it meets a Field around a select written by hand.

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

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

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

المفاتيح	الإجراء
Every key	The select's (its accessibility block; SEL-23, SEL-27, SEL-28, SEL-31, SEL-33, SEL-34). The select field handles no key and adds no focus stop (SEF-3).

ملاحظات

• One level down is the same thing: a Field with a select in it, holding the same options. Every fixture has that pair as its twin, and the accessibility tree of the two is the same (SEF-1).
• On the web the two members stand in the select field's own shadow root, so the form meets the select field and not the select (SEF-2), focus passes through to the trigger (SEF-3), and the options, which stay the product's children, reach the select through a slot and are read by it as data.
• A select with no visible label of its own — in a header, a toolbar, a column of a table — is the bare select, named by its own label, not a select field with labelHidden.

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

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

link

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

الفجوات المعروفة على الويب هي فجوات عضويه: الفاصل بين مجموعتين لا يُعرَض للتقنيات المساعدة فاصلًا (separator)، والكتابة تقارن التسميات على طريقة JavaScript، وقبل أن يُعرَّف العنصر لا يُرسم شيء سوى الخيارات نصًّا.

ما عليك فعله

link

• أعطِ كل حقل اختيار label، وكل خيار تسمية.
• تحقق من القيمة بنفسك، وعيِّن error، واكتب errorText بحيث يقول كيف تُصحَّح الإجابة.
• أعطِ كلمات المطلوب والاختياري: required-text و optional-text على حقل الاختيار، أو مرة واحدة للمنتج كله بالاستدعاء setWords({ requiredText, optionalText }). لا يتضمن Tanrei أي كلمة: من دون requiredText تقف نجمة في مكان الوسم، ومن دون optionalText لا يُرسم وسم ولا يُقال شيء. انظر كلمات المنتج.
• أبقِ قيم الخيارات فريدة داخل حقل الاختيار الواحد.