حقل الرمز لمرة واحدة

نظرة عامة

link

Web

tanrei-one-time-code-field

schedule

SwiftUI

TanreiOneTimeCodeField

radio_button_unchecked

Jetpack Compose

TanreiOneTimeCodeField

radio_button_unchecked

Flutter

TanreiOneTimeCodeField

radio_button_unchecked

React Native

OneTimeCodeField

radio_button_unchecked

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

حقل رمز لمرة واحدة، وآخر رفض المنتج رمزه

استخدم حقل الرمز لمرة واحدة (one-time-code field) حيثما يطلب المنتج من الشخص رمزًا قصيرًا أرسله إليه: لتسجيل الدخول، أو لتأكيد عنوان أو رقم هاتف، أو للموافقة على عملية دفع. وهو الحالة المعتادة، جاهزًا للاستخدام: تسمية، وخانات، وسطر يقول إلى أين أُرسل الرمز، والكلمات التي تقول إن الرمز خاطئ.

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

هو بعرض المكان الذي يوضع فيه، وخاناته تبدأ من حافة البداية فيه.

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

الاستخدام

link

الخاصية value هي الرمز المُدخل حتى الآن، بلا فاصل، أيًّا كانت المجموعات المرسومة. والأحداث الأربعة هي أحداث حقل إدخال الرمز لمرة واحدة نفسها، وحين يُسمع أيٌّ منها تكون value في الحقل قد صارت القيمة الجديدة.

<form>
  <tanrei-one-time-code-field name="code" label="رمز التحقق"
    supporting-text="أدخِل الرمز المكوّن من 6 أرقام الذي أرسلناه إلى هاتفك."
    error-text="الرمز غير صحيح. تحقق من الرسالة وحاول مرة أخرى."
    required required-text="مطلوب"
    group-size="3"></tanrei-one-time-code-field>
</form>

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

  const code = document.querySelector('tanrei-one-time-code-field');
  // غيّر الشخص القيمة. وهي الآن القيمة الجديدة.
  code.addEventListener('input', () => (code.error = false));
  // مُلئت الخانة الأخيرة، أو لُصق رمز كامل أو عُبِّئ تلقائيًّا. ولا يحدث شيء آخر من تلقاء نفسه.
  code.addEventListener('complete', async (e) => {
    code.readOnly = true;
    const right = await verify(e.detail.value);
    code.readOnly = false;
    code.error = !right;
  });
</script>

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

<OneTimeCodeField name="code" label="رمز التحقق" error={wrong}
  supportingText="أدخِل الرمز المكوّن من 6 أرقام الذي أرسلناه إلى هاتفك."
  errorText="الرمز غير صحيح. تحقق من الرسالة وحاول مرة أخرى."
  groupSize={3} value={code}
  onInput={(event) => setCode(event.currentTarget.value)}
  onComplete={(event) => verify(event.detail.value)} />

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

link

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

<tanrei-field label="رمز التحقق"
  supporting-text="أدخِل الرمز المكوّن من 6 أرقام الذي أرسلناه إلى هاتفك."
  error-text="الرمز غير صحيح. تحقق من الرسالة وحاول مرة أخرى.">
  <tanrei-one-time-code-input name="code" group-size="3"></tanrei-one-time-code-input>
</tanrei-field>

الحقل نفسه مكتوبًا باليد: حقل بداخله حقل إدخال الرمز لمرة واحدة

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

تحتاج إلى	استخدم
تسمية وخانات ومساعدة وخطأ	حقل الرمز لمرة واحدة
شيء من عندك داخل الإطار بجانب الخانات، كعنصر تحكم لإعادة إرسال الرمز أو عدّ تنازلي	حقل بداخله حقل إدخال الرمز لمرة واحدة وعنصرك أنت
الخانات وحدها، تحت تسمية مرسومة في مكان آخر، كالعنوان الرئيسي لمربع حوار أو عنوان خطوة	حقل إدخال الرمز لمرة واحدة وحده، وتسمّيه label الخاصة به
مربع واحد بلا خانات، لرمز لا يُعرف طوله	حقل نص معه autocomplete="one-time-code"

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

المواصفات

link

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

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

link

الجانب	من الحقل	من حقل إدخال الرمز لمرة واحدة
الخصائص	label، labelHidden، supportingText، errorText، error، disabled، required، optional، requiredMark، requiredText، optionalText	value، length، type، groupSize، mask، readOnly
الأحداث	—	input، change، complete، action
المنافذ (slots)	label-icon	—
رموز التصميم	comp.field.*	comp.one-time-code-input.*

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

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

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

link

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

<tanrei-one-time-code-field label="رمز التحقق"
  style="--tanrei-comp-field-label-gap: 12px"></tanrei-one-time-code-field>

البنية

البنية

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

الجزء	الوصف
1 field	The frame: a Field, whole — its label row with the label glyph and the requirement mark, and its supporting row, where the error text stands in the help's place or below it (FLD-7). Drawn by the Field from the Field's tokens (FLD-1 to FLD-9).
2 one-time-code-input	The frame's one control: a One-time-code input, whole — its cells, its characters, its caret and its group marks. Drawn by the One-time-code input from its own tokens (OTC-1 to OTC-3, OTC-15).

الخصائص

الخاصية	النوع	القيمة الافتراضية	الوصف
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 Always given: the control of a one-time-code field never names itself, so the case of an empty label does not arise.
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
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 one error of the one-time-code field: the Field passes it to the control (FLD-8, OTC-17), whose own error is not a prop here.
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 one-time-code field: the Field passes it to the control (FLD-14, OTC-20), whose own disabled is not a prop here.
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	string	""	The code entered so far: at most length characters, digits or, for alphanumeric, digits and upper-case letters, with no separator. One string, whatever the cells and groups drawn. — One-time-code input
length	number	6	How many characters the code has, and so how many cells are drawn. A whole number of 1 or more. — One-time-code input
type	numeric | alphanumeric	"numeric"	What a cell takes: numeric is the digits 0 to 9, with a numeric keypad; alphanumeric is digits and the letters A to Z, held in upper case, with a general keyboard. — One-time-code input
groupSize	number	0	Draws the cells in groups of this many, counted from the first, with a mark between two groups (3 for a six-character code written "123 456"). 0 draws one group. It changes the drawing only: the value has no separator. — One-time-code input
mask	boolean	false	Draws the platform's obscuring mark in each filled cell in place of its character, and exposes the field as protected. For a screen other people can see; a code that is used once and expires rarely needs it. — One-time-code input
readOnly	boolean	false	Keeps the field focusable and its value readable, and lets nothing change it: for the moment a complete code is being checked, when taking focus away would lose the place of a person who must then correct it. — One-time-code input

المنافذ

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

الأحداث

الحدث	الوصف
input	The person changed the value; carries the new value. Emitted for every change, not when the product sets value. — One-time-code input
change	The person committed a changed value (focus left the field, or the action key was pressed); carries the value. — One-time-code input
complete	A change by the person left the value length characters long; carries the value. Emitted after input, once for that change. The field does nothing else: checking the code is the product's. — One-time-code input
action	The person pressed the keyboard's action key (Enter, Return, Done). — One-time-code input

الحالات

السلوك

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

المعرّف	المتطلب
OTF-1	THE one-time-code field SHALL be a Field whose one control is a One-time-code input, and SHALL draw nothing of its own: every row, text, mark, cell and line it shows is drawn by one of the two, from that component's own tokens, as FLD-1 to FLD-8 and OTC-1 to OTC-3, OTC-7 and OTC-15 to OTC-17 say. THE one-time-code field SHALL have no token, no size and no gap of its own: the Field places the control and gives it its width (FLD-1), and the One-time-code input lays its row out in that width (OTC-1, OTC-23). What it shows SHALL be the picture a product gets by placing that One-time-code input in that Field by hand with the same values, and what assistive technology is told SHALL be the same name, description and states (FLD-10, FLD-11, OTC-22).
OTF-2	THE one-time-code field SHALL give each of its props, unchanged, to the member it is from and SHALL hold no state between the two: label, labelHidden, supportingText, errorText, error, disabled, required, optional, requiredMark, requiredText and optionalText are the Field's; value, length, type, groupSize, mask and readOnly are the One-time-code input's. A value a member does not know SHALL be passed on as given and answered by that member (FLD-22, OTC-19). THE one-time-code field SHALL never set the One-time-code input's own label, error or disabled: the Field's label names the control (FLD-10, OTC-22), the Field's error puts it in its error condition (FLD-8, OTC-17) and the Field's disabled disables it (FLD-14, OTC-20), so that each is said once, in the place where the label follows.
OTF-3	THE one-time-code field SHALL hold one value, the One-time-code input's. WHEN the person changes it THE one-time-code field's value SHALL be the new one before any event is reported, and THE one-time-code field SHALL report input, change, complete and action as the One-time-code input emits them — the same events, carrying the same value, in the same order and as often (OTC-13, OTC-14) — as its own, adding none and holding none back. WHEN the product sets value THE one-time-code field SHALL show it as OTC-18 says and SHALL report no event.
OTF-4	WHERE the platform has forms (the web) THE one-time-code field SHALL be the one control the form meets, and what OTC-29 says of a One-time-code input SHALL hold of the one-time-code field as a whole: it takes name; it submits the code alone, an empty string WHILE it holds none, and nothing WHILE disabled (OTC-20); it is restored on navigation and resets to the value it was first given; and it reports a missing value WHILE required is true and the value is empty, and nothing for a code shorter than length. Its members SHALL add no entry of their own to the form, and the action key SHALL submit the form the one-time-code field belongs to as OTC-13 says, unless action was cancelled.
OTF-5	THE one-time-code field SHALL be one stop in the focus order, its control's (FLD-12, OTC-2). WHEN the product moves focus to the one-time-code field THE one-time-code field SHALL pass it to the control, whose active cell is then the one OTC-5 names. A press on the label row SHALL move focus to the control and a press on the supporting row SHALL do nothing (FLD-12); THE one-time-code field SHALL take focus for no other press, SHALL add no key, and SHALL draw no focus indicator of its own: the frame's focused tokens and the active cell's focused line are the members' (FLD-13, OTC-7).
OTF-6	THE one-time-code field SHALL hold exactly one control and SHALL take no other from the product: it has no place for a child but the Field's label glyph (FLD-3, FLD-20), so that the cases of FLD-15 — no control, several controls — and of FLD-23 — a control replaced by another — never arise in it. IF the one-time-code field is placed in a Field THEN THE one-time-code field SHALL be drawn as it is and reported in debug builds as a field placed in a Field (FLD-15); WHERE it is placed in a field group THE one-time-code field SHALL follow the group's disabled as a Field does (FGR-14) and SHALL take nothing else from the group.
OTF-7	THE one-time-code field SHALL have no words of its own: every word it shows or says is a prop of the Field's, read as FLD-24 says — the instance's, else the product's words of the same name — and the One-time-code input has none (OTC-30). THE one-time-code field SHALL read no key of the product's words itself.
OTF-8	THE one-time-code field SHALL add nothing to how its members answer the place they are used in: the layout direction (FLD-18 to FLD-21; OTC-27 and OTC-28, by which the cells stay a left-to-right run and stand at the start edge, under the label), enlarged text (FLD-16, OTC-23, OTC-24), a person's own forced colors (FLD-17, OTC-26) and the caret's reduced motion are each member's own answer. THE one-time-code field SHALL have no direction, size, color or motion setting of its own, and SHALL never be wider than its layout gives it.
OTF-9	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 one-time-code 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 one-time-code field is invalid — except those the one-time-code field owns (aria-label, aria-labelledby, aria-disabled), which it SHALL move and not expose: its name is label (OTF-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 one-time-code field SHALL take it off that element. WHEN the product sets an aria- attribute the one-time-code field owns THE one-time-code field SHALL report it in debug builds.

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

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

المواصفة	Web	SwiftUI	Jetpack Compose	Flutter	React Native
المكوّن	tanrei-one-time-code-field	TanreiOneTimeCodeField	TanreiOneTimeCodeField	TanreiOneTimeCodeField	OneTimeCodeField
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	code	value	controller	value
length · الخاصية	length	length	length	length	length
type · الخاصية	type	type	type	type	type
groupSize · الخاصية	groupSize	groupSize	groupSize	groupSize	groupSize
mask · الخاصية	mask	isMasked	masked	obscureText	secureTextEntry
readOnly · الخاصية	readOnly	readOnly	readOnly	readOnly	readOnly
input · الحدث	input	code	onValueChange	onChanged	onChangeText
change · الحدث	change	onCommit	onCommit	onCommit	onEndEditing
complete · الحدث	complete	onComplete	onComplete	onCompleted	onComplete
action · الحدث	action	onSubmit	keyboardActions	onSubmitted	onSubmitEditing
ملاحظات	<tanrei-one-time-code-field name="code" label="Verification code" supporting-text="Enter the 6-digit code we sent to your phone." group-size="3"></tanrei-one-time-code-field>. Composed: a custom element with a shadow root that holds its members' own elements — <tanrei-field part="field" exportparts="label, label-icon, requirement-label, supporting-text"><tanrei-one-time-code-input part="one-time-code-input" exportparts="input, cell, character, caret, separator"></tanrei-one-time-code-input></tanrei-field> — and nothing else but the passage of the label-icon slot; its module imports both members' modules, so where it is defined they are. Each prop is a property and an attribute of the element under its member's own attribute name (label-hidden, supporting-text, error-text, required-mark, required-text, optional-text, group-size, readonly) and is set on that member as a property; the element writes no custom property and reads no token, so every --tanrei-comp-field-* and --tanrei-comp-one-time-code-input-* value reaches the members by inheritance, and one instance is set apart by setting such a property on this element. One level down, the same by hand: <tanrei-field label="Verification code" supporting-text="…"><tanrei-one-time-code-input name="code" group-size="3"></tanrei-one-time-code-input></tanrei-field>. Form-associated itself (static formAssociated = true): its members stand in its shadow root, outside any form, so it takes name and form, repeats on its own ElementInternals the value, the state and the validity its One-time-code input tells its own — the same flags, the same message and the same anchor, the native input, so the browser's message points where it points one level down — resets to its value attribute, and passes a disabled <fieldset> on to its Field (OTF-4); Enter in the cells presses the default button of this element's form. The shadow root does not delegate focus — a press on the supporting row must do nothing (FLD-12) — so focus() and blur() are passed to the control, a click that arrives on the element itself (a page's own <label for>) moves focus there, and autofocus is copied to the control (OTF-5). The four events are the One-time-code input's own composed, bubbling CustomEvents: they leave the shadow root by themselves with the element as their target, and the element's value is at every moment its One-time-code input's — what was last set on the element until the input has taken it, and from then on what the input holds — so event.target.value is the code in every listener, capturing or bubbling (OTF-3); it dispatches nothing itself. The name, the description and the states reach the native input as values, by the tanrei-field-connect exchange between the two members inside the one shadow root, exactly as in a product's markup; the element's own host has no role, and an aria-* attribute the product writes on it moves to data-aria-* and reaches the cells' input, as its accessibility notes say — but for the name: name it with label (and label-hidden), never with aria-label, which a debug build reports. Inside a tanrei-field-group it follows the group's disabled through its Field (OTF-6). custom-elements.json shows it whole — sixteen attributes with their members' descriptions, four events with TanreiOneTimeCodeInputDetail, the label-icon slot, the two member parts and the nine exported ones, and the form attribute — and the React wrapper OneTimeCodeField is generated from that, with onInput, onChange, onComplete and onAction. Before the element is defined it has no size and shows nothing but a label-icon child, which a page hides with tanrei-one-time-code-field:not(:defined) > *; a page that must not jump gives the tag a block size of its own, and a page that must work without script writes a <label> around a plain <input autocomplete="one-time-code" inputmode="numeric"> with its help beside it. The host is display: block. Words: the element has none; required-text and optional-text left empty are read by its Field from the product's words.	TanreiOneTimeCodeField("Verification code", code: $code, supportingText: "…", groupSize: 3, onComplete: verify): a view whose body is TanreiField(…) { TanreiOneTimeCodeInput(…) } with each argument passed to the member it is from, and nothing else. code is the input's Binding<String>; labelHidden follows .labelsHidden() and disabled follows .disabled(_:), as the Field's do; the glyph is the Field's labelIcon:. One field is set apart by .tanreiTheme(_:) on this view. Planned: owed after the One-time-code input itself.	TanreiOneTimeCodeField(label = "Verification code", value = code, onValueChange = { code = it }, supportingText = …, groupSize = 3, onComplete = ::verify): a composable that calls TanreiField(…) { TanreiOneTimeCodeInput(…) } with each argument passed to the member it is from, and nothing else. enabled is the Field's inverse flag; the glyph is the Field's labelIcon. One field is set apart by a TanreiTheme(…) { } around this call. Planned: owed after the One-time-code input itself.	TanreiOneTimeCodeField(labelText: 'Verification code', controller: code, helperText: …, groupSize: 3, onCompleted: verify): a widget whose build returns TanreiField(…, child: TanreiOneTimeCodeInput(…)) with each argument passed to the member it is from, and nothing else. The names follow the members'; enabled is the Field's inverse flag; the glyph is the Field's labelIcon. One field is set apart by a TanreiTheme widget around it. Planned: owed after the One-time-code input itself.	<OneTimeCodeField label="Verification code" value={code} onChangeText={setCode} supportingText="…" groupSize={3} onComplete={verify} />: a component that returns <Field …><OneTimeCodeInput … /></Field> with each prop passed to the member it is from, and nothing else. The glyph is the Field's labelIcon prop. One field is set apart by a provider around it. Planned: owed after the One-time-code input 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

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

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

supporting

label: Verification code supportingText: Enter the 6-digit code we sent to your p… value: 123 groupSize: 3

error

label: Verification code supportingText: Enter the 6-digit code we sent to your p… errorText: That code is not right. Check the messag… error: true value: 123456 groupSize: 3

disabled

label: Verification code supportingText: Enter the 6-digit code we sent to your p… disabled: true value: 123456 groupSize: 3

required-rtl

label: رمز التحقق supportingText: أدخل الرمز المكوّن من 6 أرقام الذي أرسلن… required: true requiredText: مطلوب value: 123 groupSize: 3 direction: rtl

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

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

link

• جذر الظل (shadow root) في العنصر فيه عنصر <tanrei-field> بداخله عنصر <tanrei-one-time-code-input>، ولا شيء غيرهما. واستيراد العنصر يعرّف الاثنين.
• العنصر مرتبط بالنماذج (form-associated). يأخذ name و form، ويرسل الرمز وحده، ولا يرسل شيئًا وهو معطَّل، ويعود عند إعادة الضبط إلى قيمة خاصية HTML (attribute) value، ويتبع عنصر <fieldset> المعطَّل، ويبلّغ بأن القيمة ناقصة ما دامت required معيَّنة وهو فارغ. وعضواه لا يضيفان أي مُدخلة (entry) إلى النموذج. والمفتاح Enter في الخانات يضغط الزر الافتراضي في نموذج العنصر؛ ألغِ الحدث action لتمنع ذلك.
• الأحداث input و change و complete و action هي أحداث حقل إدخال الرمز لمرة واحدة، من النوع CustomEvent ومعها detail.value. وهدفها هو العنصر، و event.target.value هي الرمز في كل مستمع.
• الأجزاء: field و one-time-code-input هما العضوان. وأجزاؤهما لها هنا الأسماء نفسها التي لها في المستوى الأدنى: label، label-icon، requirement-label، supporting-text؛ input، cell، character، caret، separator.
• العنصر نفسه غير قابل للتركيز: فالدالة focus() تذهب إلى الخانات، وعنصر <label for> من عند الصفحة ينقل التركيز إليها. وخاصية HTML autofocus على العنصر تنقل التركيز إلى الخانات حين يُرسم أول مرة، إلا إذا كان التركيز على شيء آخر.
• ليس للعنصر دور. سمِّه بالخاصية label، ومعها label-hidden حيث تُرسم التسمية في مكان آخر، ولا تسمِّه أبدًا بالخاصية aria-label، فهي لا تسمّي شيئًا هنا.
• خصائص HTML هي خصائص العضوين نفسها: label-hidden، supporting-text، error-text، required-mark، required-text، optional-text، group-size، readonly.
• له منفذ واحد، هو label-icon. وعنصر التحكم الثاني الذي يوضع داخله لا يُرسم.
• قبل أن يُعرَّف العنصر لا يكون له حجم، ولا يعرض إلا عنصرًا فرعيًّا في label-icon. أخفِه بالمحدِّد tanrei-one-time-code-field:not(:defined) > * واحجز الارتفاع. والصفحة التي يجب أن تعمل بلا سكربت تستخدم عنصر <label> حول عنصر <input autocomplete="one-time-code" inputmode="numeric"> عادي، ومساعدته بجانبه.

الإرشادات

link

افعل

link

• قل في supportingText كم حرفًا يُنتظر وإلى أين أُرسل الرمز.
• ارسم المجموعات كما تكتبها الرسالة: groupSize="3" لرمز أُرسل في الصورة «123 456».
• قل بالكلمات إن الرمز خاطئ، بالخاصيتين error و errorText. وقرّر بنفسك هل يُمسح الرمز الخاطئ: فكثيرًا ما يكون الخطأ في رقم واحد.
• استخدم readOnly لا disabled ما دام الرمز المكتمل قيد التحقق. فالحقل المعطَّل يفقد التركيز، والشخص الذي عليه بعد ذلك أن يصحّح الرمز يفقد موضعه.
• ضع بجانب الحقل طريقة طلب رمز جديد، وأي مهلة زمنية. وحيث يكون مكانهما داخل الإطار، اكتب الحقل باليد، في المستوى الأدنى.

لا تفعل

link

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

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

link

الدور

textbox

التسمية

One text box, the One-time-code input's (OTC-2); the frame has no role. Its accessible name is label, drawn or not (labelHidden), and its description is the supporting text with, in error, the error text after it, with optionalText while optional is true (FLD-10, FLD-11, OTC-22). It is exposed as invalid while error is true, required while required is true, disabled while disabled is true, read-only while readOnly is true, and as a protected text entry while mask is true. The label's drawn text, the requirement mark, the cells, the caret and the group marks are not exposed a second time (FLD-11, OTC-2).

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

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

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

المفاتيح	الإجراء
Tab / Shift+Tab	Moves focus to the control and on from it: the one-time-code field is one stop, its control's, and adds none (OTF-5).
Every other key	The One-time-code input's own, as its spec's keyboard table says (OTC-6, OTC-8 to OTC-11, OTC-13). The one-time-code field handles no key.

ملاحظات

• What the one-time-code field adds to its members is their being one thing: one tag or one call, one set of props, one value and one entry in a form (OTF-2 to OTF-4). The tie between the two — the name, the description, required, invalid, disabled — is not the one-time-code field's: it is what a Field gives any control it frames, and it runs here exactly as it runs in a product's own Field.
• One level down: a Field with a One-time-code input in it, written by the product, is the same picture and the same text box, and the Field's fixtures code-supporting, code-error, code-disabled and code-required-rtl are this component's twins. A product drops to it for an arrangement the one-time-code field does not offer: something of its own inside the frame beside the cells (a resend control, a countdown), or the One-time-code input alone under a dialog's headline, named by its own label.
• The members' notes hold as written and are not repeated: errors are words (the Field's); nothing happens by itself when the code is complete, and paste and the platform's autofill are never blocked (the One-time-code input's).
• The hit area is the control's (OTC-25); the label widens where a press can land without widening what a press does (FLD-12).
• Not pressable: a press focuses the control and is not an action (OTC-25), so BTN-8, BTN-9 and BTN-10 are not copied.
• 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/one-time-code-field.spec.json, tokens/sys/measure.tokens.json

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

link

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

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

ما عليك فعله

link

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