التخطّي إلى المحتوى
menumenu tanreiexpand_morecontrasttranslate
tanreiexpand_more
البدءWebReactSwiftUIJetpack ComposeFlutterReact Nativeالإعدادات الجاهزةنظام التصميم الخاص بكاستخدام Tanrei مع وكلاء الذكاء الاصطناعيالعلامة التجاريةرموز التصميمأنظمة التصميم والتخصيصTheme Studioاللونالطباعةالأيقوناتالشكلالارتفاعالحركةحالات التفاعلالسلوكالتخطيطإمكانية الوصولالكلماترموز الألوانرموز السلّم الطباعيرموز الشكلرموز الارتفاعرموز الحركةرموز الحالةرموز التباعد والقياسالمكوّناتالزرزر الإجراء الرئيسيالزر المقسَّممجموعة الأزرارزر مع قائمةشريط الأدواتزر النسخخانة الاختيارزر الاختيارمفتاح التبديلالرقاقةقائمة الخياراتشريط التمريرحقل شريط التمريرالتقويمDateTimePickerمجموعة الحقولمجموعة أزرار الاختيارمجموعة خانات الاختيارعنصر الاختيارحقل الاختيارشريط القوائمرفع الملفاتمنتقي الملفات متقدّمساحة الإفلاتحقل إدخال النص متقدّمحقل النصحقل الرقاقاتالحقلمربع التحرير والسرد متقدّمحقل التحرير والسردحقل إدخال العدد متقدّمحقل العددحقل إدخال اللون متقدّمحقل اللونحقل إدخال الرمز لمرة واحدة متقدّمحقل الرمز لمرة واحدةحقل إدخال النص المدمج متقدّممربع كتابة الرسائلالبطاقةالفاصلالطبقة النمطية متقدّممربع الحوارالقائمة (list)صف القائمةاللوحة السفليةاللوحة الجانبيةالعرض الدوّاركتلة الشيفرةالجدولاللوحة المنبثقةالخطواتالأكورديونقائمة الوصفالشكل التوضيحيهيكل التطبيقرأس الصفحةالعرض الشجريالخط الزمنيمعاينة الصورمقبض تغيير الحجمالإطار القابل لتغيير الحجممنطقة التمريرالشارةمؤشر التقدمالعدّادعارض الأرقام المتحرّكمؤشر التحميلشريط الإشعار (Snackbar)التلميحاختصار لوحة المفاتيحالوسمالشيفرة المضمَّنةالتنويهالصورة الرمزيةالحالة الفارغةمجموعة الوسومهيكل التحميلعنصر الملفمربع اللونالنص المتحركعلامات التبويبعرض التبويباتشريط التطبيقشريط التنقلدرج التنقلالبحثالرابطالتنقل بين الصفحاتروابط السابق والتاليمؤشر الخطواتمسار التنقلجدول المحتوياتبطاقة الرابطقائمة FABالحالةكيف يُبنى Tanreiالمساهمةالترخيص والإسناد
الرئيسيةالمكوّناتحقل النص

حقل النص

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

content_copyعرض بتنسيق Markdown
الفئة
إدخال النص
الرموز
comp.field
المستوى
مركّب
مبني من
Field, Text input

نظرة عامة

Web
tanrei-text-field
schedule
SwiftUI
TanreiTextField
schedule
Jetpack Compose
TanreiTextField
schedule
Flutter
TanreiTextField
schedule
React Native
TextField
schedule
أشكال غير متوفرة في
tanrei: filled, outlined

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

مواصفة معدَّلة، لم تصل بعد إلى كل منصة

تصف هذه الصفحة حقل النص كما هو في المواصفة الآن: طراز (variant) هو stacked، وهو الافتراضي، وتسميته فوق الحقل؛ والطرازان filled و outlined باقيان لإعدادات Material الجاهزة والإعداد الجاهز cupertino فقط؛ وثلاثة ارتفاعات هي 32 و 40 و 56 (و 40 و 48 و 56 للحقل من الطراز filled أو outlined، الذي تعوم تسميته داخله)؛ وأنواع للتاريخ والوقت، مع زر منتقٍ؛ وحقل متعدد الأسطر يتبع نصه أو يُغيَّر حجمه بمقبض (resize)؛ وتاريخ أو وقت يُدخل وحدةً وحدةً، في مقاطع؛ والخاصيتان required و optional اللتان تعلّمان الحقل بأنه مطلوب أو اختياري. مكوّن الويب يفعل ذلك كله منذ الآن، وكذلك العروض التوضيحية. ويمكن للحقل أيضًا أن يحمل شيفرة (type="code"، ومعه wrap لأسطرها): بناه الويب، ولم تبنِه أي منصة أخرى بعد. وحقل النص حقل حول حقل إدخال النص، كما تصفه هذه الصفحة: بنى الويب ذلك أيضًا، وزالت فيه خاصية HTML required. أما SwiftUI و Compose و Flutter و React Native فموسومة أعلاه بأنها متأخرة: إلى أن تلحق تقدّم المراجعة السابقة، وهي من الطراز outlined افتراضيًّا بارتفاعي 36 و 40، وفيها راية required لا ترسم علامة، وليس فيها الطراز stacked ولا أنواع التاريخ والوقت ولا زر المنتقي ولا أوضاع تغيير الحجم، وتعرض عيّناتها تلك المراجعة.

الطراز Stacked، وهو الافتراضي: حقل مطلوب، وتاريخ مع زر المنتقي

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

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

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

ساحة التجربة

textemailpasswordnumbersearchtelurlcodedatetimedate-time
يضبط كل عنصر تحكم خاصية واحدة في المكوّن المباشر، وتتغيّر الشيفرة معه. ويحفظ عنوان الصفحة ما ضبطته، فيفتحها الرابط كما تركتها. هذه الشيفرة للويب. وللمنصات الأخرى، راجع «مطابقة الأسماء بين المنصات».

الاستخدام

<form>
  <tanrei-text-field name="email" label="البريد الإلكتروني" type="email" autocomplete="email" required required-text="مطلوب"
    supporting-text="نستخدمه لتسجيل دخولك فقط."></tanrei-text-field>
  <tanrei-text-field name="company" label="الشركة" optional optional-text="اختياري"></tanrei-text-field>
  <!-- يتبع نصه من 3 أسطر إلى 8، ثم يُمرَّر. -->
  <tanrei-text-field name="message" label="الرسالة" multiline min-rows="3" max-rows="8"></tanrei-text-field>
  <!-- يُغيَّر حجمه باليد، بمقبض. -->
  <tanrei-text-field name="notes" label="الملاحظات" multiline resize="manual" resize-label="تغيير حجم الملاحظات"></tanrei-text-field>
</form>

<!-- الصندوق وحده، في شريط أدوات: حقل إدخال النص، وتسمّيه label الخاصة به. واستيراد حقل النص يعرّفه. -->
<tanrei-text-input label="بحث" type="search" placeholder="ابحث في المكوّنات">
  <span slot="leading-icon">search</span>
</tanrei-text-input>

<!-- شيفرة: من اليسار إلى اليمين وبخط الشيفرة في كل اتجاه للصفحة، ولا تُصحَّح ولا تُدقَّق إملائيًّا أبدًا. -->
<tanrei-text-field label="النمط" type="code" value="tanrei.comp.button.*.container.color"></tanrei-text-field>
<tanrei-text-field label="محتوى طلب Webhook" type="code" multiline min-rows="4" supporting-text="JSON"></tanrei-text-field>
<!-- بلا التفاف: كل سطر من الشيفرة يبقى في سطر واحد، والسطر الطويل يُمرَّر داخل الحقل. -->
<tanrei-text-field label="الصفوف" type="code" multiline no-wrap></tanrei-text-field>

<!-- تاريخ يُدخل وحدةً وحدةً بترتيب الإعدادات المحلية، ويُحفظ في الصورة 2026-09-27، مع زر منتقٍ. -->
<tanrei-text-field id="start" label="تاريخ البدء" type="date" min="2026-01-01" disabled-dates="2026-05-01 2026-12-25"
  invalid-text="أكمِل التاريخ." unavailable-text="اختر يوم عمل في 2026 أو بعدها."
  picker picker-label="اختيار تاريخ البدء" segment-empty-text="فارغ"></tanrei-text-field>
<tanrei-date-time-picker id="start-picker" presentation="docked" anchor="start" label="تاريخ البدء"></tanrei-date-time-picker>

<script type="module">
  import '@tanrei/web/components/text-field';
  const email = document.querySelector('[name="email"]');
  email.addEventListener('input', () => draft(email.value)); // كل تعديل
  email.addEventListener('change', () => save(email.value)); // غادر التركيز أو ضُغط Enter، والقيمة تغيّرت
  // التحقق من شأنك: الحقل لا يعيّن error بنفسه أبدًا.
  email.error = submitted && !isValid(email.value);
  email.errorText = 'أدخِل عنوان بريد إلكتروني كاملًا.';

  // الحقل يطلب؛ والمنتج يعرض المنتقي ويكتب القيمة في الحقل.
  const start = document.querySelector('#start');
  const picker = document.querySelector('#start-picker');
  start.addEventListener('pickerrequest', (e) => {
    Object.assign(picker, { value: e.detail.value, min: e.detail.min, max: e.detail.max, disabledDates: start.disabledDates, open: true });
  });
  picker.addEventListener('change', () => (start.value = picker.value));
  picker.addEventListener('close', () => (picker.open = false));
</script>
 
import { TextField } from '@tanrei/react';

<TextField
  label="البريد الإلكتروني"
  type="email"
  autocomplete="email"
  value={email}
  onInput={(e) => setEmail(e.currentTarget.value)}
  onChange={() => save(email)}
  required
  requiredText="مطلوب"
  error={submitted && !isValid(email)}
  errorText="أدخِل عنوان بريد إلكتروني كاملًا."
/>

<TextField label="الرسالة" multiline minRows={3} maxRows={8} value={message}
  onInput={(e) => setMessage(e.currentTarget.value)} />

// تاريخ: القيمة بصيغة ISO 8601، أو فارغة ما دام أحد المقاطع فارغًا.
<TextField
  label="تاريخ البدء"
  type="date"
  min="2026-01-01"
  value={start}
  invalidText="أكمِل التاريخ."
  unavailableText="اختر تاريخًا في 2026 أو بعدها."
  segmentEmptyText="فارغ"
  picker
  pickerLabel="اختيار تاريخ البدء"
  onChange={(e) => setStart(e.currentTarget.value)}
  onEntryError={(e) => report(e.detail.reason)}
  onPickerRequest={() => setPickerOpen(true)}
/>
 
import Tanrei

TanreiTextField("البريد الإلكتروني", text: $email, type: .email,
                supportingText: "نستخدمه لتسجيل دخولك فقط.",
                errorText: "أدخِل عنوان بريد إلكتروني كاملًا.",
                error: submitted && !isValid(email),
                textContentType: "email", // اسم تعبئة تلقائية من HTML
                onCommit: save,
                // مرِّر الإجراء هنا: المُعدِّل .onSubmit المحيط يعمل قبل onCommit.
                onSubmit: signIn)

// تعدد الأسطر هو المحور العمودي مع مدى لحد الأسطر.
TanreiTextField("الرسالة", text: $message, axis: .vertical, lineLimit: 3...8)
 
import androidx.compose.foundation.text.KeyboardActions
import io.github.chnotchy.tanrei.components.TanreiTextField
import io.github.chnotchy.tanrei.components.TanreiTextFieldType

var email by remember { mutableStateOf("") }
TanreiTextField(
    value = email,
    onValueChange = { email = it },
    label = "البريد الإلكتروني",
    type = TanreiTextFieldType.Email,
    contentType = "email", // اسم تعبئة تلقائية من HTML
    supportingText = "نستخدمه لتسجيل دخولك فقط.",
    isError = submitted && !isValid(email),
    errorText = "أدخِل عنوان بريد إلكتروني كاملًا.",
    onCommit = { save(it) },
    keyboardActions = KeyboardActions(onDone = { signIn() }),
)

// singleLine هي عكس multiline التي في المواصفة.
TanreiTextField(value = message, onValueChange = { message = it }, label = "الرسالة", singleLine = false, minLines = 3)
 
import 'package:tanrei/tanrei.dart';

TanreiTextField(
  controller: email, // أو initialValue: '…'
  labelText: 'البريد الإلكتروني',
  type: TanreiTextFieldType.email,
  autofillHints: TanreiTextField.autofillHintsFromHtml('email'),
  helperText: 'نستخدمه لتسجيل دخولك فقط.',
  isError: submitted && !isValid(email.text),
  errorText: 'أدخِل عنوان بريد إلكتروني كاملًا.',
  onCommit: save,
  onSubmitted: (String value) => signIn(),
);

TanreiTextField(labelText: 'الرسالة', multiline: true, minLines: 3);
 
import { TextField } from '@tanrei/react-native';

<TextField
  label="البريد الإلكتروني"
  type="email"
  autoComplete="email"
  value={email}
  onChangeText={setEmail}
  supportingText="نستخدمه لتسجيل دخولك فقط."
  error={submitted && !isValid(email)}
  errorText="أدخِل عنوان بريد إلكتروني كاملًا."
  onEndEditing={save}
  onSubmitEditing={signIn}
/>
<TextField label="الرسالة" multiline minRows={3} value={message} onChangeText={setMessage} />

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

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

<tanrei-field label="البريد الإلكتروني" required required-text="مطلوب"
  supporting-text="نستخدمه لتسجيل دخولك فقط.">
  <tanrei-text-input name="email" type="email" autocomplete="email"></tanrei-text-input>
</tanrei-field>

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

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

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

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

وشيء واحد يفعله حقل النص ولا يفعله الحقل وحقل إدخال النص المكتوبان باليد: يُبقي العدد مواكبًا. وباليد، مع تعيين counter، أعطِ الحقل عدد حقل الإدخال عند كل تغيّر:

field.countText = input.countText;
input.addEventListener('input', () => (field.countText = input.countText));

المواصفات

الخطأ، والتعطيل، والقراءة فقط، والبادئة واللاحقة، والعدّاد

الأنواع: كلمة المرور، والبحث، والرقم، والهاتف، وعنوان URL

search

مطلوب واختياري: الوسمان، والنجمة

عدة أسطر: يتبع النص، ويُغيَّر حجمه بمقبض (نزولًا، وفي الاتجاهين)، وثابت

شيفرة: نمط في سطر واحد، و JSON في عدة أسطر، وأسطر لا تلتفّ

شيفرة في صفحة من اليمين إلى اليسار: التسمية والمساعدة تتبعان الصفحة، والشيفرة تبدأ من اليسار

تاريخ، ووقت، وتاريخ ووقت، في مقاطع. يملؤها المفتاح Tab ومفاتيح الأسهم والأرقام

الطرازان Filled و outlined في إعدادات Material الجاهزة

مع m3-like

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

الجانب من الحقل من حقل إدخال النص
الخصائص label، labelHidden، supportingText، errorText، error، disabled، required، optional، requiredMark، requiredText، optionalText كل ما عداها: variant، size، type، value، placeholder، readOnly، والأسطر وتغيير الحجم، wrap، maxLength، counter، والبادئة واللاحقة، autocomplete، وكل ما يخص التاريخ أو الوقت
الأحداث — input، change، action، pickerRequest، entryError
المنافذ (slots) label-icon leading-icon، trailing-icon
رموز التصميم comp.field.* comp.input-box.* للصندوق، وهي التي يقرؤها كل صندوق إدخال؛ و comp.text-input.* لما يرسمه حقل إدخال النص وحده

لحقل إدخال النص label و labelHidden و error و disabled خاصة به. وهي ليست ما يعيّنه حقل النص: فالخاصية label فيه هي تسمية الحقل، وهي تسمّي حقل الإدخال، وفي الحقل من الطراز filled أو outlined هي ما يعوم في الصندوق.

رموز التصميم

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

<tanrei-text-field label="البريد الإلكتروني"
  style="--tanrei-comp-field-label-gap: 12px"></tanrei-text-field>

البنية

البنية

مرسوم فوق نموذج الاختبار outlined-empty كما ترسمه حزمة الويب.
الجزء الوصف
1 field The Field: the label row with its glyph and its requirement mark, and the supporting row with the help, the error text and the count the text field gives it (TXF-67). In a look whose input floats the label it draws no label row.
2 text-input The text input, as the Field's one control: the box and everything typed in it, the icons, the prefix and the suffix, the segments of a date, the picker button, the resize handle, and the label that floats in the box in the looks that float one.

الخصائص

الخاصية النوع القيمة الافتراضية الوصف
variant stacked | filled | outlined "stacked" 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, marked by a tinted box and a bottom line, or by a border. Use one style per form. A design system may leave some out (the Tanrei system ships stacked only) or add values. — Text input
size small | medium | large "medium" Minimum height of a single-line input's container: stacked 32 / 40 / 56, as tall as a Button of the same size, so that an input 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. Medium and large are for forms; small is for an input in an app bar, a toolbar or a dense row of controls, beside a small select or button. The hit area always meets the minimum target. — Text input
type text | email | password | number | search | tel | url | code | date | time | date-time "text" What the value is: chooses the keyboard, autocorrection, obscured entry and semantics. code is text written for a machine rather than for a reader — a snippet of configuration, a pattern, an identifier, a query, a key: a left-to-right run in the code face that the platform does not correct, capitalise, check for spelling or complete, on one line or, with multiline, on many. date, time and date-time are entered segment by segment in the locale's numeric form and held as ISO 8601. The value is a string for every type. — Text input
value string "" The text in the field; for date, time and date-time, the ISO 8601 form of what its segments give (2026-09-27, 14:30, 2026-09-27T14:30), or empty while a segment is empty or the value is not available. — Text input
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 text input. In a filled or outlined look the input draws it, floating in its box, and the Field draws no label row (FLD-25, TXI-13).
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 input's floating label (FLD-25).
placeholder string "" A hint shown while the value is empty and the label is not in the input line (above, floated or hidden). Never a replacement for label. In a code field it is an example of the code and is drawn as code (TXI-53, TXI-54); a hint in words belongs in the supportingText of its Field. Ignored by a date, time or date-time field, whose empty segments each show their own. — Text input
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 text input in the input's own error condition (FLD-8, TXI-11).
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 text input (FLD-14, TXI-5); the text field is then left out of its form (TXF-63).
readOnly boolean false The value can be focused, selected and copied, but not changed. — Text input
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 text input as required (FLD-10, TXI-23).
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
multiline boolean false Accepts line breaks and shows several lines, sized as resize says. Ignored for password, date, time and date-time. — Text input
minRows number 2 The fewest lines a multi-line field shows: the height of an empty auto-resized field, the starting and smallest height of a manually resized one, and the height of a fixed one. — Text input
maxRows number 0 The most lines an auto-resized field grows to before it scrolls, and the tallest a manually resized one can be made; 0 is no limit. Ignored while resize is fixed. — Text input
resize auto | manual | fixed "auto" How a multi-line field gets its height. auto: it follows the number of lines between minRows and maxRows, with an animated change, and has no handle. manual: it starts at minRows lines and the person resizes it with the handle in its bottom end corner. fixed: it stays at minRows lines, with no handle. Ignored unless multiline. — Text input
resizeAxis vertical | both "vertical" What the person can resize by hand: the height only, or the height and the width. Ignored unless resize is manual. — Text input
resizeLabel string "" The accessible name of the resize handle, in the product's language ("Resize"). The product's: Tanrei has no word for it. Empty reads the product's words. Required while the handle is shown. — Text input
wrap boolean true Whether a multi-line code field continues a line that does not fit on following rows (true), or keeps every line of the code on one row and scrolls sideways inside its container (false) — for code whose lines are read as rows: a table of values, a log, a file in which a line break means something. The value is the same either way. Ignored unless type is code and multiline is true: prose always wraps, and a single line always scrolls in its line. — Text input
maxLength number 0 The most user-perceived characters the user can enter; 0 is no limit. Ignored for date, time and date-time. — Text input
counter boolean false Keeps the character count (and maxLength, when set): part of the input's description and announced when typing pauses (TXI-19). The input draws none: a text field gives the count to its Field, which draws it at the end of its supporting row, and a product that frames the input by hand gives it to the Field's countText. — Text input The input keeps the count, the text field gives it to its Field, and the Field draws it (TXI-19, TXF-67, FLD-27).
counterText string "" The count said to assistive technology while counter is true and maxLength is greater than 0: the whole sentence in the product's language with three places the input fills — {count} with the characters entered, {limit} with maxLength and {remaining} with how many more can be entered ("{remaining} characters left", "{limit}文字中{count}文字"). Empty reads the product's words; with neither, the count is said as the digits it is drawn in ("12/40"). A sentence that is right for every number, or a prop set per count where the language needs another form for one. — Text input
counterNoLimitText string "" The count said to assistive technology while counter is true and maxLength is 0: the whole sentence with one place, {count}, filled with the characters entered ("{count} characters", "{count}文字"). Empty reads the product's words; with neither, the count is said as its digits. — Text input
prefixText string "" Fixed text before the value, not part of it. In a code field it is code: drawn in the code face at the left of the value in every layout direction (TXI-53). — Text input
suffixText string "" Fixed text after the value, not part of it. In a code field it is code: drawn in the code face at the right of the value in every layout direction (TXI-53). — Text input
autocomplete string "" The autofill hint, as an HTML autofill field name (email, current-password, new-password, one-time-code, tel, postal-code, …); each platform maps it to its own content type. A code field left without one asks the platform to offer no remembered entry (TXI-55). — Text input
locale string "" A BCP 47 language tag ("en-US", "ja-JP") for how a date, time or date-time field shows and reads its value: the order of the year, month and day segments, the separators, the clock, the digits and the names of the units. Empty uses the platform's current locale. The calendar is the Gregorian calendar in every locale. — Text input
min string "" The earliest value a date, time or date-time field accepts from the person, in its ISO 8601 form; empty for no limit. — Text input
max string "" The latest value a date, time or date-time field accepts from the person, in its ISO 8601 form; empty for no limit. — Text input
disabledDates strings Dates inside min and max that a date or date-time field does not accept from the person, as ISO 8601 calendar dates — the same list the product gives its DateTimePicker. Ignored by a time field. — Text input
invalidText string "" The words for a date, time or date-time input committed with some segments filled and others empty: given to the Field that frames it, which shows them as its error text (TXI-30). — Text input Shown by the Field, in its supporting row (FLD-28).
unavailableText string "" The words for a date, time or date-time input committed with a value before min, after max or, for a date, listed in disabledDates: given to the Field that frames it, which shows them as its error text (TXI-30). — Text input Shown by the Field, in its supporting row (FLD-28).
segmentEmptyText string "" What assistive technology reads as the value of a date or time segment that holds nothing yet, in the product's language ("Empty"). The product's: Tanrei has no word for it. Empty reads the product's words; with neither, an empty segment has no value text. — Text input
picker boolean false Shows the picker button in a date, time or date-time field. The field presents no picker itself: it emits pickerRequest, and the product presents a DateTimePicker in the matching mode and sets value to what was picked. — Text input
pickerLabel string "" The accessible name of the picker button ("Choose date"). Required while picker is shown. — Text input

المنافذ

المنفذ الوصف
leading-icon An icon at the start of the input. — Text input
trailing-icon An icon at the end of the input, or the product's own icon-only Button (clear, reveal password). A date or time field's picker button comes after it. — Text input
label-icon A glyph before the label. — Field

الأحداث

الحدث الوصف
input The user changed the value; carries the new value. Emitted for every change, not when the product sets value. A date, time or date-time field emits it when its value changes — when its last segment is filled, a filled field is edited, or it is emptied — not for a segment that leaves the value empty. — Text input
change The user committed a changed value (focus left the field, or the action key was pressed in a single-line field); carries the value. — Text input
action The user pressed the keyboard's action key (Enter, Return, Go, Search, Done) in a single-line field. — Text input
pickerRequest The user activated the picker button of a date, time or date-time field; carries the value, type, min and max. The product presents the picker and sets value to the picked value. — Text input
entryError The user committed a date, time or date-time field that is half-filled or whose value is not available; carries the reason (invalid: some segments are empty; unavailable: before min, after max or a listed date) and the text of the row of segments as drawn. The entry error itself is shown by the Field that frames the input (TXI-30). — Text input
resizeEnd The person finished changing the size of a field resized by hand: a drag of its handle ended, or a key or an activation of the handle changed the size (TXI-69). Carries lines, the number of lines the input shows, and width, the field's width in pixels WHILE resizeAxis is both (null otherwise). Not emitted when a change of resize, resizeAxis, minRows or maxRows gives the size back. — Text input

الحالات

السلوك

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

المعرّف المتطلب
TXF-62 THE text field SHALL be a Field that frames one text input, 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 text input, each unchanged; SHALL hold the label-icon slot for its Field and the leading-icon and trailing-icon slots for its text input; and SHALL emit its text input's events as its own, each once. THE text field SHALL be as wide as the place it stands in, and its text input SHALL fill it: it is a block with no width of its own, as its Field is (FLD-1), around a control that fills the width it is given (TXI-63). It SHALL draw no part of its own, have no token of its own and hold no state of its own but the count it carries from one member to the other (TXF-67): what it shows, how it behaves and what it exposes to assistive technology SHALL be exactly what that Field and that text input do when a product places the one in the other (FLD-1 to FLD-28; TXI-1 to TXI-63), with the Field given the input's count — 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, TXI-13, TXI-50); the supporting row, the error and the count (FLD-7 to FLD-9, FLD-26, FLD-27, TXI-19, TXF-67); the name, the description and the states (FLD-10, FLD-11, FLD-14, TXI-23); and a date's entry error shown in the Field's row (FLD-28, TXI-30).
TXF-63 WHERE the platform has forms (the web) THE text field SHALL be the one control the form sees: it SHALL take name, submit its text input's value, reset to the value it was first given, restore it on navigation, report to the form's constraint validation exactly what its text input would report there (TXI-23, TXI-30), and be left out WHILE disabled is true or a disabled group of the form holds it; its text input and its Field SHALL take no part in the form themselves. WHEN the action key asks for the form's submission (TXI-3) the form asked SHALL be the text field's own.
TXF-64 WHEN the text field is given focus — by the product, by a press on any part of it that FLD-12 or TXI-8 gives to the input, or by a form that reports its validity — THE text field SHALL pass the focus to its text input (in a date, time or date-time field, to the segment TXI-43 names) and SHALL add no stop to the focus order: the stops inside it are its text input's, in that input's order (an interactive slot element, the picker button, the resize handle). WHILE focus is anywhere inside it THE text field SHALL count as focused for its Field (FLD-13).
TXF-65 IF the text field is placed in a Field THE text field SHALL in debug builds report that it is a field already and that the bare control is the text input, and both SHALL still render (FLD-15). WHILE it stands in a field group THE text field SHALL follow that group's disabled, through its own Field, and take nothing else from the group (FGR-20).
TXF-66 THE text field SHALL have no words of its own and SHALL read none: requiredText and optionalText are read by its Field (FLD-24), resizeLabel and segmentEmptyText by its text input (TXI-52), each from the instance's prop and then from the product's words.
TXF-67 WHILE counter is true THE text field SHALL give its Field, as its count text (FLD-27), the count its text input keeps (TXI-19), as the input writes it, and SHALL give the new one in the same frame in which the value changes — by typing, by a paste, because the product set value or maxLength — without a motion and without an announcement of its own: the input describes and announces its count itself (TXI-19) and the Field keeps the drawn text from assistive technology (FLD-27). WHILE counter is false THE text field SHALL give its Field no count text. THE text field SHALL NOT count, format or write a digit itself.
TXF-68 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 text 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 text field is invalid — except those the text field owns (aria-label, aria-labelledby, aria-disabled), which it SHALL move and not expose: its name is label (TXF-62). 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 text field SHALL take it off that element. WHEN the product sets an aria- attribute the text field owns THE text field SHALL report it in debug builds.

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

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

المواصفة Web SwiftUI Jetpack Compose Flutter React Native
المكوّن tanrei-text-field TanreiTextField TanreiTextField TanreiTextField TextField
variant · الخاصية variant variant variant variant variant
size · الخاصية size size size size size
type · الخاصية type type type type type
value · الخاصية value text value controller 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
multiline · الخاصية multiline axis singleLine multiline multiline
minRows · الخاصية minRows lineLimit minLines minLines minRows
maxRows · الخاصية maxRows lineLimit maxLines maxLines maxRows
resize · الخاصية resize resize resize resize resize
resizeAxis · الخاصية resizeAxis resizeAxis resizeAxis resizeAxis resizeAxis
resizeLabel · الخاصية resizeLabel resizeLabel resizeContentDescription resizeSemanticLabel resizeAccessibilityLabel
wrap · الخاصية noWrap wrap softWrap softWrap wrap
maxLength · الخاصية maxLength maxLength maxLength maxLength maxLength
counter · الخاصية counter counter counter showCounter counter
counterText · الخاصية counterText counterText counterText counterSemanticText counterAccessibilityText
counterNoLimitText · الخاصية counterNoLimitText counterNoLimitText counterNoLimitText counterNoLimitSemanticText counterNoLimitAccessibilityText
prefixText · الخاصية prefixText prefix prefix prefixText prefix
suffixText · الخاصية suffixText suffix suffix suffixText suffix
autocomplete · الخاصية autocomplete textContentType contentType autofillHints autoComplete
locale · الخاصية locale locale locale locale locale
min · الخاصية min min min min min
max · الخاصية max max max max max
disabledDates · الخاصية disabledDates disabledDates disabledDates disabledDates disabledDates
invalidText · الخاصية invalidText invalidText invalidText invalidText invalidText
unavailableText · الخاصية unavailableText unavailableText unavailableText unavailableText unavailableText
segmentEmptyText · الخاصية segmentEmptyText segmentEmptyText segmentEmptyText segmentEmptyText segmentEmptyText
picker · الخاصية picker onPickerRequest onPickerRequest onPickerRequest onPickerRequest
pickerLabel · الخاصية pickerLabel pickerLabel pickerContentDescription pickerSemanticLabel pickerAccessibilityLabel
input · الحدث input text onValueChange onChanged onChangeText
change · الحدث change onCommit onCommit onCommit onEndEditing
action · الحدث action onSubmit keyboardActions onSubmitted onSubmitEditing
pickerRequest · الحدث pickerrequest onPickerRequest onPickerRequest onPickerRequest onPickerRequest
entryError · الحدث entryerror onEntryError onEntryError onEntryError onEntryError
resizeEnd · الحدث resizeend onResizeEnd onResizeEnd onResizeEnd onResizeEnd
ملاحظات The tag is tanrei-text-field, the class TanreiTextField, the React name TextField. Members: <tanrei-field> holding one <tanrei-text-input> in its default slot; the product places none. The host is display: block, as wide as its place, and the input fills it (TXF-62). Value member: tanrei-text-input. The host is the form's element — name, the value and its state, validity anchored on the input, reset to the value attribute, restore, form, a disabled fieldset — and the input 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 text input: variant, size, type, value, placeholder, readOnly, multiline, minRows, maxRows, resize, resizeAxis, resizeLabel, noWrap (the inverse of wrap, attribute no-wrap), maxLength, counter, prefixText, suffixText, autocomplete, locale, min, max, disabledDates, invalidText, unavailableText, segmentEmptyText, picker, pickerLabel. Attributes are the members' own: kebab-case, except readonly, maxlength, autocomplete, min and max. Props of one name on both members — label, labelHidden, error, disabled — are the Field's; the input's are never set by the element and reach the input through the connection. Events: input, change, action, pickerrequest, entryerror are the text input's own composed events and leave by themselves, with the host as their target and value already new; action stays cancelable. None is stopped and none is copied. Slots: label-icon is passed to the Field, leading-icon and trailing-icon to the text input, each by a slot element of the same name rendered only while the host has a child for it; the product's own Button in trailing-icon stays the product's element. Parts: the member hosts are field and text-input. Exported from the Field: label, label-icon, requirement-label, supporting-text, counter. Exported from the text input: container, outline, active-indicator, label, requirement-label, input, segment, prefix, suffix, leading-icon, trailing-icon, picker-button, resize-handle. Two names collide, label and requirement-label. Each is exported with its member's name before it, always (field-label, text-input-label, field-requirement-label, text-input-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 — while its control draws the label itself the Field draws no label row and no requirement tag, and a stacked input draws neither (TXI-13, TXI-50). So tanrei-text-field::part(label) keeps meaning the drawn label. Focus: the shadow root does not delegate. focus() and blur() call the text input's; a press on the label row — the label, its glyph, the requirement mark — focuses the input by FLD-12, the Field's own sentence (the Field calls focus() on its control, which stands beside it in the same tree); a press on the box, and on a label that floats in it, by TXI-8; and a press on the supporting row — the help, the error text, the count — or on the gap between a row and the box does nothing (FLD-12). The connection is the Field's with its control, in both directions (FLD-25, FLD-26, FLD-28, TXI-62); the element takes no part in it. A member's prop it sets itself (fills): the Field's countText, from the text input's read-only countText after each of the input's updates, in the same task (TXF-67). Parts and tokens of its own: none. The element writes no custom property: --tanrei-comp-field-*, --tanrei-comp-input-box-* and --tanrei-comp-text-input-* reach the members by inheritance, and one text field is set apart by setting any of them on the element. What its twin cannot do that it does: keep the Field's count text equal to the input's count as the person types (TXF-67); nothing else. The twin: <tanrei-field label="Email" supporting-text="We never share your address." required><tanrei-text-input name="email" type="email" autocomplete="email"></tanrei-text-input></tanrei-field>. Its Field draws the help and the error text together (FLD-7, FLD-31), and the five fixtures *-supporting-error* hold the pair to its twin. Lagging: this platform draws the text field as one view that draws its own frame, written against the token group comp.text-field, which the tokens do not have. It owes, first, its sources moved to the generated names of comp.input-box, comp.text-input and comp.field: they do not compile until then. Then the split: the text input as a view of its own, and the text field as the Field around it. Its names and its props stay. What it does today: text: Binding<String> (as TextField); every edit writes the binding, which is the input event. password draws a SecureField; multiline is TextField(axis: .vertical) with .lineLimit(minRows...maxRows) — not TextEditor, which has no prompt and does not grow. labelHidden follows the .labelsHidden() environment; disabled follows .disabled(_:); action is the onSubmit: parameter, called after the commit (TXI-3); an enclosing .onSubmit modifier still fires, but before the commit, because SwiftUI runs the outer handler first. onCommit is Tanrei's own parameter (SwiftUI deprecated its own), called when focus leaves with a changed value. type maps to .keyboardType, .textInputAutocapitalization, .autocorrectionDisabled and .submitLabel; autocomplete maps HTML names to UITextContentType. locale follows the \.locale environment when not given. The picker button is shown when an onPickerRequest: closure is given (a nil closure is picker false); the product presents the picker and writes the binding. Not built on this platform yet: the optional flag (optional) beside the required flag; the resize modes and the handle (TXI-37–TXI-41, TXI-69), the segmented date and time row (TXI-42–TXI-47) and the requirement label (FLD-4, FLD-5, TXI-50). The platform proposes its own idiom for the segments when it catches up — each unit focusable and adjustable on its own, with the same value and events. Not built on this platform yet: the words props have no defaults, and the product's words are read from the \.tanreiWords environment value. Not built on this platform yet, for type code: .autocorrectionDisabled(), .textInputAutocapitalization(.never), .keyboardType(.asciiCapable), a monospaced design of the input's size, and .environment(\.layoutDirection, .leftToRight) on the input row alone; smart quotes, smart dashes and smart insert and delete are traits of the UIKit and AppKit text view (smartQuotesType, smartDashesType, smartInsertDeleteType, isAutomaticQuoteSubstitutionEnabled), so a code field is drawn on that view where SwiftUI's TextField gives no access to them; wrap: false needs that view too (a text container that does not track the view's width, in a scroll view), because TextField(axis: .vertical) always wraps. Not built on this platform yet: the count said as the product's sentence (counterText, counterNoLimitText, TXI-19); today the digits are said. Not built on this platform yet: comp.field.error-text.placement — the error text takes the help's place under every system, which is replace, the default; append, which keeps the help and draws the error text below it, is not drawn (FLD-7, FLD-31). Not built on this platform yet: size small (40), and in a right-to-left layout the value of an always left-to-right type beside its prefix (TXI-67). Lagging: this platform draws the text field as one view that draws its own frame, written against the token group comp.text-field, which the tokens do not have. It owes, first, its sources moved to the generated names of comp.input-box, comp.text-input and comp.field: they do not compile until then. Then the split: the text input as a view of its own, and the text field as the Field around it. Its names and its props stay. What it does today: Compose idiom (as TextField): value / onValueChange, with a TextFieldValue overload for products that manage selection and composition themselves; enabled and singleLine are inverse flags; isError, readOnly, minLines, maxLines, prefix and suffix keep Compose's names. Built on BasicTextField. type maps to KeyboardOptions (keyboard type, capitalization, autocorrect, IME action) and, for password, PasswordVisualTransformation; autocomplete maps to ContentType semantics. onCommit is Tanrei's own callback, called when focus leaves with a changed value or the IME action commits. locale defaults to the current configuration's locale. The picker button is shown when onPickerRequest is not null (null is picker false); pickerContentDescription follows Compose's naming for an icon's accessible name. Not built on this platform yet: the optional flag (optional) beside the required flag; the resize modes and the handle (TXI-37–TXI-41, TXI-69), the segmented date and time row (TXI-42–TXI-47) and the requirement label (FLD-4, FLD-5, TXI-50). The platform proposes its own idiom for the segments when it catches up — each unit focusable and adjustable on its own, with the same value and events. Not built on this platform yet: the words props have no defaults, and the product's words are read from LocalTanreiWords. Not built on this platform yet, for type code: KeyboardOptions(capitalization = KeyboardCapitalization.None, autoCorrectEnabled = false, keyboardType = KeyboardType.Ascii), TextStyle(textDirection = TextDirection.Ltr, textAlign = TextAlign.Left, fontFamily = …, fontFeatureSettings = "liga 0") on the input row inside CompositionLocalProvider(LocalLayoutDirection provides LayoutDirection.Ltr); softWrap = false puts the BasicTextField in a horizontalScroll that follows the cursor's rectangle. Not built on this platform yet: the count said as the product's sentence (counterText, counterNoLimitText, TXI-19); today the digits are said. Not built on this platform yet: comp.field.error-text.placement — the error text takes the help's place under every system, which is replace, the default; append, which keeps the help and draws the error text below it, is not drawn (FLD-7, FLD-31). Not built on this platform yet: size small (40), and in a right-to-left layout the value of an always left-to-right type beside its prefix (TXI-67). Lagging: this platform draws the text field as one view that draws its own frame, written against the token group comp.text-field, which the tokens do not have. It owes, first, its sources moved to the generated names of comp.input-box, comp.text-input and comp.field: they do not compile until then. Then the split: the text input as a view of its own, and the text field as the Field around it. Its names and its props stay. What it does today: Flutter idiom (as TextField and InputDecoration): the value lives in a TextEditingController (or an internal one with initialValue); labelText, hintText, helperText, errorText, prefixText, suffixText, minLines, maxLines, maxLength, readOnly, enabled and autofillHints keep Flutter's names, enabled being the inverse flag. isRequired and showCounter avoid Dart's required keyword and Flutter's own counter, which Tanrei replaces (it counts grapheme clusters with characters). maxRows: 0 is maxLines: null. type maps to keyboardType, obscureText, autocorrect, textCapitalization and textInputAction. onCommit is Tanrei's own callback, called when focus leaves with a changed value. locale defaults to Localizations.localeOf(context). The picker button is shown when onPickerRequest is not null (null is picker false). Not built on this platform yet: the optional flag (optional) beside the required flag; the resize modes and the handle (TXI-37–TXI-41, TXI-69), the segmented date and time row (TXI-42–TXI-47) and the requirement label (FLD-4, FLD-5, TXI-50). The platform proposes its own idiom for the segments when it catches up — each unit focusable and adjustable on its own, with the same value and events. Not built on this platform yet: the words props have no defaults, and the product's words are read from the TanreiWords inherited widget, which the app fills from its own localizations. Not built on this platform yet, for type code: autocorrect: false, enableSuggestions: false, textCapitalization: TextCapitalization.none, smartDashesType: SmartDashesType.disabled, smartQuotesType: SmartQuotesType.disabled, spellCheckConfiguration: const SpellCheckConfiguration.disabled(), textDirection: TextDirection.ltr, textAlign: TextAlign.left, a TextStyle with the code family and fontFeatures: [FontFeature.disable('liga')], the input row in a Directionality(textDirection: TextDirection.ltr); softWrap: false is an EditableText of unbounded width in a horizontal Scrollable that keeps the caret in view, because a multi-line TextField always wraps. Not built on this platform yet: helperText stays while the field is in error and errorText is drawn below it (FLD-7, FLD-31), unlike InputDecoration; today the error text takes the help's place. Not built on this platform yet: the count said as the product's sentence (counterText, counterNoLimitText, TXI-19); today the digits are said. Not built on this platform yet: comp.field.error-text.placement (FLD-7, FLD-31), size small (40), and in a right-to-left layout the value of an always left-to-right type beside its prefix (TXI-67). Lagging: this platform draws the text field as one view that draws its own frame, written against the token group comp.text-field, which the tokens do not have. It owes, first, its sources moved to the generated names of comp.input-box, comp.text-input and comp.field: they do not compile until then. Then the split: the text input as a view of its own, and the text field as the Field around it. Its names and its props stay. What it does today: React Native idiom (as TextInput): value / onChangeText, onEndEditing for a commit, onSubmitEditing for the action key; multiline, readOnly, maxLength and autoComplete keep TextInput's names. type maps to keyboardType, secureTextEntry, autoCapitalize, autoCorrect, inputMode and returnKeyType. A controlled value echoed back during a composition must not reset it (TXI-4). React Native gives JavaScript no signal that a composition is in progress, so the component cannot defer a write the product makes mid-composition; echoing the value back is safe. For date, time and date-time, onChangeText receives the value (ISO 8601 or empty), not the text as typed (TXI-29). The picker button is shown when onPickerRequest is given (undefined is picker false). Locale data needs Intl with formatToParts, which Hermes has only in part. Not built on this platform yet: the optional flag (optional) beside the required flag; the resize modes and the handle (TXI-37–TXI-41, TXI-69), the segmented date and time row (TXI-42–TXI-47) and the requirement label (FLD-4, FLD-5, TXI-50). The platform proposes its own idiom for the segments when it catches up — each unit focusable and adjustable on its own, with the same value and events. Not built on this platform yet: the words props have no defaults, and the product's words are read from the TanreiWordsProvider context. Not built on this platform yet, for type code: autoCorrect={false}, autoCapitalize="none", spellCheck={false}, autoComplete="off", smartInsertDelete={false}, keyboardType="ascii-capable" on iOS and "visible-password" on Android only where suggestions cannot be turned off otherwise, style={{ writingDirection: 'ltr', textAlign: 'left', fontFamily: … }}, the input row with direction: 'ltr'. TextInput has no multi-line form that does not wrap: wrap={false} needs a native text view, and until one exists the field wraps and its README says so. Not built on this platform yet: the count said as the product's sentence (counterText, counterNoLimitText, TXI-19); today the digits are said. Not built on this platform yet: comp.field.error-text.placement — the error text takes the help's place under every system, which is replace, the default; append, which keeps the help and draws the error text below it, is not drawn (FLD-7, FLD-31). Not built on this platform yet: size small (40), and in a right-to-left layout the value of an always left-to-right type beside its prefix (TXI-67).

الرموز

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

stacked-empty

variant: stacked label: Email

stacked-filled

variant: stacked value: [email protected] label: Email

stacked-placeholder

variant: stacked label: Email placeholder: [email protected]

stacked-large

variant: stacked size: large value: [email protected] label: Email

stacked-small

variant: stacked size: small value: tokens label: Search

stacked-label-hidden

variant: stacked label: Search labelHidden: true placeholder: Search

stacked-supporting

variant: stacked value: [email protected] label: Email supportingText: We never share your address.

stacked-error

variant: stacked value: ada@ label: Email errorText: Enter a complete address. error: true

stacked-supporting-error

variant: stacked type: password value: ada1 label: Password supportingText: At least 8 characters, with one number. errorText: This password is too short. error: true

stacked-supporting-error-long

variant: stacked value: 12 Example Stret label: Billing address supportingText: Use the address your bank has on file, w… errorText: We could not find this address. Check th… error: true

stacked-supporting-error-rtl

variant: stacked type: password value: ada1 label: סיסמה supportingText: לפחות 8 תווים, כולל ספרה אחת. errorText: הסיסמה קצרה מדי. error: true direction: rtl

stacked-disabled

variant: stacked value: [email protected] label: Email disabled: true

stacked-read-only

variant: stacked value: [email protected] label: Email readOnly: true

stacked-icons

variant: stacked value: tanrei label: Search

stacked-label-icon

variant: stacked value: Ada Lovelace label: Display name slots: label-icon

stacked-affixes

variant: stacked type: number value: 120 label: Amount prefixText: $ suffixText: USD

stacked-counter

variant: stacked value: Ada Lovelace label: Display name maxLength: 40 counter: true

stacked-supporting-error-counter

variant: stacked value: Ada label: Display name supportingText: Shown beside your posts. errorText: This name is taken. Choose another. error: true maxLength: 40 counter: true

stacked-multiline

variant: stacked value: Thanks for the review. The new tokens ar… label: Message multiline: true minRows: 3

stacked-password

variant: stacked type: password value: correct horse label: Password

stacked-date

variant: stacked type: date value: 2026-09-27 label: Start date locale: en-US

stacked-date-empty

variant: stacked type: date label: Start date locale: en-US segmentEmptyText: Empty

stacked-date-picker

variant: stacked type: date value: 2026-09-27 label: Start date locale: en-US picker: true pickerLabel: Choose date

stacked-date-picker-large

variant: stacked size: large type: date value: 2026-09-27 label: Start date locale: en-US picker: true pickerLabel: Choose date

stacked-date-ja

variant: stacked type: date value: 2026-09-27 label: 開始日 locale: ja-JP picker: true pickerLabel: 日付を選択

stacked-time-picker

variant: stacked type: time value: 14:30 label: Start time locale: en-US picker: true pickerLabel: Choose time

stacked-date-time-picker

variant: stacked type: date-time value: 2026-09-27T14:30 label: Starts locale: en-US picker: true pickerLabel: Choose date and time

stacked-date-error

variant: stacked type: date value: 2026-09-27 label: Start date errorText: Choose a date after today. error: true locale: en-US picker: true pickerLabel: Choose date

stacked-date-disabled

variant: stacked type: date value: 2026-09-27 label: Start date disabled: true locale: en-US picker: true pickerLabel: Choose date

stacked-multiline-auto-grown

variant: stacked value: Thanks for the review. The new tokens ar… label: Message multiline: true

stacked-multiline-auto-grown-icons

variant: stacked value: Thanks for the review. The new tokens ar… label: Message multiline: true

stacked-multiline-auto-max

variant: stacked value: Thanks for the review. The new tokens ar… label: Message multiline: true maxRows: 3

stacked-multiline-manual

variant: stacked value: Thanks for the review. The new tokens ar… label: Message multiline: true minRows: 3 resize: manual resizeLabel: Resize

stacked-multiline-manual-both

variant: stacked value: Thanks for the review. The new tokens ar… label: Message multiline: true minRows: 3 resize: manual resizeAxis: both resizeLabel: Resize

stacked-multiline-manual-rtl

variant: stacked value: תודה על הסקירה. label: הודעה multiline: true minRows: 3 resize: manual resizeAxis: both resizeLabel: שינוי גודל direction: rtl

stacked-multiline-fixed

variant: stacked value: Thanks for the review. The new tokens ar… label: Message multiline: true minRows: 3 resize: fixed

stacked-time-empty

variant: stacked type: time label: Start time locale: en-US segmentEmptyText: Empty

stacked-time-24h

variant: stacked type: time value: 14:30 label: 開始時刻 locale: ja-JP

stacked-date-rtl

variant: stacked type: date value: 2026-09-27 label: תאריך התחלה locale: he-IL picker: true pickerLabel: בחירת תאריך direction: rtl

stacked-required

variant: stacked label: Email required: true requiredText: Required

stacked-optional

variant: stacked label: Company optional: true optionalText: Optional

stacked-required-asterisk

variant: stacked label: Email required: true requiredMark: asterisk

stacked-required-ja

variant: stacked value: 山田 太郎 label: 氏名 required: true requiredText: 必須

stacked-optional-ja

variant: stacked label: 会社名 optional: true optionalText: 任意

stacked-required-label-icon

variant: stacked value: Ada Lovelace label: Display name required: true requiredText: Required slots: label-icon

stacked-required-error

variant: stacked label: Email errorText: Enter your email address. error: true required: true requiredText: Required

stacked-required-disabled

variant: stacked value: [email protected] label: Email disabled: true required: true requiredText: Required

stacked-required-rtl

variant: stacked label: אימייל required: true requiredText: חובה direction: rtl

stacked-code

variant: stacked type: code value: tanrei.comp.button.*.container.color label: Pattern

stacked-code-empty

variant: stacked type: code label: Pattern placeholder: tanrei.comp.*.color

stacked-code-large

variant: stacked size: large type: code value: tanrei.comp.button.*.container.color label: Pattern

stacked-code-affixes

variant: stacked type: code value: ^sys\.color\. label: Pattern supportingText: A regular expression, matched against a… prefixText: / suffixText: /u

stacked-code-multiline

variant: stacked type: code value: { "id": "acme", "extends": "tanrei"… label: Layer multiline: true minRows: 3

stacked-code-multiline-empty

variant: stacked type: code label: Layer placeholder: { "id": "acme", "extends": "tanrei" } multiline: true minRows: 3

stacked-code-multiline-wrap

variant: stacked type: code value: { "match": "tanrei.comp.button.*.hovered… label: Rule multiline: true

stacked-code-multiline-nowrap

variant: stacked type: code value: { "match": "tanrei.comp.button.*.hovered… label: Rule multiline: true minRows: 3 wrap: false

stacked-code-multiline-tabs

variant: stacked type: code value: build: pnpm generate pnpm check label: Recipe multiline: true

stacked-code-multiline-error

variant: stacked type: code value: { "id": "acme", } label: Layer errorText: Line 3: a name was expected before }. error: true multiline: true minRows: 3

stacked-code-multiline-counter

variant: stacked type: code value: { "id": "acme", "extends": "tanrei"… label: Layer multiline: true maxLength: 200 counter: true

stacked-code-multiline-manual

variant: stacked type: code value: { "match": "tanrei.comp.button.*.hovered… label: Rule multiline: true minRows: 3 resize: manual resizeAxis: both resizeLabel: Resize wrap: false

stacked-code-multiline-read-only

variant: stacked type: code value: { "match": "tanrei.comp.button.*.hovered… label: Rule readOnly: true multiline: true wrap: false

stacked-code-multiline-disabled

variant: stacked type: code value: { "id": "acme", "extends": "tanrei"… label: Layer disabled: true multiline: true

stacked-code-rtl

variant: stacked type: code value: tanrei.comp.button.*.container.color label: النمط supportingText: معرّف رمز، مع * لأي جزء. direction: rtl

stacked-code-empty-rtl

variant: stacked type: code label: النمط placeholder: tanrei.comp.*.color direction: rtl

stacked-code-affixes-rtl

variant: stacked type: code value: ^sys\.color\. label: النمط prefixText: / suffixText: /u direction: rtl

stacked-code-multiline-rtl

variant: stacked type: code value: { "id": "acme", "extends": "tanrei"… label: الطبقة supportingText: الصق ملف الطبقة هنا. required: true requiredText: مطلوب multiline: true minRows: 3 maxLength: 200 counter: true direction: rtl

stacked-code-multiline-empty-rtl

variant: stacked type: code label: الطبقة placeholder: { "id": "acme", "extends": "tanrei" } multiline: true minRows: 3 direction: rtl

stacked-code-multiline-brace-rtl

variant: stacked type: code value: { label: الطبقة multiline: true minRows: 3 direction: rtl

stacked-code-multiline-arabic-first-rtl

variant: stacked type: code value: ["مرحبا", "acme"] // تعليق: comment label: المصادر multiline: true minRows: 3 direction: rtl

stacked-code-multiline-nowrap-rtl

variant: stacked type: code value: { "match": "tanrei.comp.button.*.hovered… label: القاعدة errorText: السطر 2: القاعدة ينقصها سبب. error: true multiline: true minRows: 3 wrap: false direction: rtl

stacked-code-multiline-manual-rtl

variant: stacked type: code value: { "id": "acme", "extends": "tanrei"… label: الطبقة multiline: true minRows: 3 resize: manual resizeAxis: both resizeLabel: تغيير الحجم direction: rtl

variant: filled (7)

filled-empty

variant: filled label: Email

filled-filled

variant: filled value: [email protected] label: Email

filled-large

variant: filled size: large value: [email protected] label: Email

filled-error

variant: filled value: ada@ label: Email errorText: Enter a complete email address. error: true

filled-disabled

variant: filled value: [email protected] label: Email disabled: true

filled-multiline

variant: filled value: Thanks for the review. The new tokens ar… label: Message multiline: true minRows: 3

filled-code-multiline

variant: filled type: code value: { "id": "acme", "extends": "tanrei"… label: Layer multiline: true minRows: 3

variant: outlined (19)

outlined-empty

variant: outlined label: Email

outlined-filled

variant: outlined value: [email protected] label: Email

outlined-large

variant: outlined size: large value: [email protected] label: Email

outlined-label-hidden

variant: outlined type: search label: Search labelHidden: true placeholder: Search components

outlined-supporting

variant: outlined value: [email protected] label: Email supportingText: We only use it to sign you in.

outlined-error

variant: outlined value: ada@ label: Email errorText: Enter a complete email address. error: true

outlined-supporting-error

variant: outlined value: ada@ label: Email supportingText: We never share your address. errorText: Enter a complete email address. error: true

outlined-disabled

variant: outlined value: [email protected] label: Email disabled: true

outlined-read-only

variant: outlined value: [email protected] label: Email readOnly: true

outlined-icons

variant: outlined value: tanrei label: Search

outlined-affixes

variant: outlined type: number value: 120 label: Amount prefixText: $ suffixText: USD

outlined-counter

variant: outlined value: Ada Lovelace label: Display name maxLength: 40 counter: true

outlined-multiline

variant: outlined value: Thanks for the review. The new tokens ar… label: Message multiline: true minRows: 3

outlined-password

variant: outlined type: password value: correct horse label: Password

outlined-date-picker

variant: outlined type: date value: 2026-09-27 label: Start date locale: en-US picker: true pickerLabel: Choose date

outlined-multiline-manual

variant: outlined value: Thanks for the review. The new tokens ar… label: Message multiline: true minRows: 3 resize: manual resizeLabel: Resize

outlined-required

variant: outlined label: Email required: true requiredText: Required

outlined-optional

variant: outlined label: Company optional: true optionalText: Optional

outlined-code-multiline

variant: outlined type: code value: { "id": "acme", "extends": "tanrei"… label: Layer multiline: true minRows: 3

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

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

  • جذر الظل (shadow root) في العنصر فيه عنصر <tanrei-field> بداخله عنصر <tanrei-text-input>، ولا شيء غيرهما. واستيراد العنصر يعرّف الاثنين.
  • العنصر كتلة تملأ مكانها، لا صندوق مضمَّن في السطر بعرض حقل الإدخال النصي الخاص بالمتصفح.
  • العنصر مرتبط بالنماذج (form-associated). يأخذ name و form، ويرسل القيمة، ولا يرسل شيئًا وهو معطَّل، ويعود عند إعادة الضبط إلى قيمة خاصية HTML (attribute) value، ويُستعاد عند التنقل، ويتبع عنصر <fieldset> المعطَّل، ويبلّغ بأن القيمة ناقصة ما دامت required معيَّنة وهو فارغ. وعضواه لا يضيفان أي مُدخلة (entry) إلى النموذج. والمفتاح Enter في حقل من سطر واحد يضغط الزر الافتراضي في نموذج العنصر؛ ألغِ الحدث action لتمنع ذلك.
  • الأحداث input و change و action و pickerrequest و entryerror هي أحداث حقل إدخال النص نفسه. وهدفها هو العنصر، و event.target.value هي القيمة الجديدة في كل مستمع. وأنواع التفاصيل (detail) هي أنواع حقل الإدخال: TanreiTextInputActionDetail و TanreiTextInputPickerRequestDetail و TanreiTextInputEntryErrorDetail.
  • الأجزاء: field و text-input هما العضوان. وأجزاؤهما لها هنا الأسماء نفسها التي لها في المستوى الأدنى: label-icon، supporting-text، counter؛ container، outline، active-indicator، input، segment، prefix، suffix، leading-icon، trailing-icon، picker-button، resize-handle. والجزءان label و requirement-label هما المرسومان، أيًّا كان العضو الذي يرسمهما؛ أما field-label و text-input-label و field-requirement-label و text-input-requirement-label فتسمّي ما يخص عضوًا واحدًا.
  • العنصر نفسه غير قابل للتركيز وليس له دور: فالدالة focus() تذهب إلى حقل الإدخال. والضغط على صف التسمية أو على الصندوق أو على تسمية عائمة ينقل التركيز إلى حقل الإدخال. والضغط على المساعدة أو نص الخطأ أو العدد أو الفجوة بين صف والصندوق لا يفعل شيئًا.
  • سمِّه بالخاصية label، ومعها label-hidden حيث لا يُراد رسم التسمية، ولا تسمِّه أبدًا بالخاصية aria-label، فهي لا تسمّي شيئًا هنا.
  • خصائص HTML هي خصائص العضوين نفسها: بصيغة kebab-case، مثل supporting-text و error-text و min-rows و no-wrap، ما عدا readonly و maxlength و autocomplete و min و max. ولا توجد خاصية HTML اسمها required: اكتب required.
  • قبل أن يُعرَّف العنصر لا يكون له حجم. احجز ارتفاعه.

الإرشادات

متى يُستخدم

استخدم حقل النص حين يكتب الأشخاص قيمة: اسمًا، عنوان بريد إلكتروني، بحثًا، رسالة. وحين ينتقون من مجموعة قيم معروفة، استخدم عنصر تحكم صُنع للاختيار. وحيث لا يُراد إلا الصندوق، لأن التسمية تقف في مكان آخر، كعامل تصفية في شريط أدوات أو خلية في جدول، استخدم حقل إدخال النص.

اختيار الطراز والحجم

استخدم طرازًا واحدًا في النموذج كله.

الطراز يميّزه أين
الطراز Stacked، وهو الافتراضي التسمية فوق صندوق ملوَّن تلوينًا خفيفًا بلا حافة. التركيز يرسم خطًّا داخل حافة الصندوق، فلا يحرّك شيئًا؛ والخطأ يرسم خطًّا رفيعًا في حالة السكون. كل نظام. وهو الطراز الوحيد الذي يقدّمه نظام Tanrei.
الطراز Filled صندوق ملوَّن تلوينًا خفيفًا وخط سفلي، والتسمية تعوم داخله إعدادات Material الجاهزة والإعداد الجاهز cupertino
الطراز Outlined حدّ يثخن عند التركيز، والتسمية تعوم إليه إعدادات Material الجاهزة والإعداد الجاهز cupertino

الافتراضي هو stacked في كل نظام، ومنها الإعدادات الجاهزة. والمنتج المبني على Material الذي يريد تسمية Material العائمة يعيّن variant في حقوله بالقيمة outlined أو filled. وتحت نظام Tanrei ما زال الطرازان filled و outlined يعملان، مع تحذير في أثناء التطوير.

الحجم medium (40) هو الحقل المكثَّف، والحجم large (56) هو الحقل القياسي. استخدم medium في عوامل التصفية والإعدادات الكثيفة، و large في نماذج تسجيل الدخول وإتمام الشراء. والحجم small (32) هو ارتفاع قائمة الاختيار الصغيرة، لحقل في شريط تطبيق أو شريط أدوات أو صف كثيف من عناصر التحكم، ونص الإدخال فيه 14. ونص الإدخال 16 في الحجمين الآخرين في النظام الافتراضي. والارتفاعات حدود دنيا: يكبر الحقل مع النص الأكبر، ومنطقة اللمس تبلغ الحد الأدنى للهدف دائمًا.

التسميات والنصوص النائبة

  • كل حقل يحتاج إلى الخاصية label. في الحقل من الطراز stacked تقف فوق الصندوق، من حافة بدايته، ولا تتحرك ولا يتغيّر حجمها أبدًا؛ والتسمية الطويلة تلتفّ ولا تُقطع. ويستطيع المنفذ label-icon أن يضع رسم أيقونة (glyph) قبلها. وفي الحقل من الطراز filled أو outlined تستقر التسمية داخل الحقل ما دام فارغًا، وتعوم حين يكون عليه التركيز أو فيه قيمة.
  • الخاصية labelHidden توقف رسم التسمية، لكنها تبقى الاسم المتاح للتقنيات المساعدة، وتبقى المساعدة والخطأ تحت الصندوق. وحيث لا يُراد إلا الصندوق، كعامل تصفية في شريط أدوات، أو خلية، أو صف تقف تسميته بجانبه، استخدم بدلًا منها حقل إدخال النص بالخاصية label الخاصة به.
  • النص النائب تلميح، كقيمة نموذجية. يظهر ما دام الحقل فارغًا والتسمية ليست في سطر الإدخال: دائمًا في الحقل من الطراز stacked، وفي الطرازين الآخرين فقط ما دامت التسمية عائمة أو مخفيّة. وليس هو الاسم أبدًا.

مطلوب واختياري

الخاصيتان required و optional تقولان ما يطلبه النموذج من الحقل: required أن الجواب لازم، و optional أنه يجوز تركه فارغًا. والحقل لا يكون الاثنين معًا أبدًا: فإن عُيِّنتا كلتاهما كان مطلوبًا.

  • المطلوب يعرض الحقل على أنه مطلوب ويرسم علامة المطلوب بجانب التسمية.
  • الاختياري يرسم وسم الاختياري ويضيف نصه إلى وصف الحقل.
  • العلامة وسم صغير بعد التسمية في الطراز stacked افتراضيًّا: من الطراز filled للمطلوب، ومن الطراز tonal للاختياري. كلماتها هي requiredText و optionalText، وهي كلماتك: على الحقل، أو مرة واحدة للمنتج كله بالدالة setWords(). لا يتضمن Tanrei أي كلمة: من دون requiredText تقف نجمة في مكان الوسم، ومن دون optionalText لا يُرسم وسم. وهي لا تزيد صف التسمية ارتفاعًا، وتلتفّ إلى سطر خاص بها حين لا تترك لها التسمية مكانًا.
  • نجمة بدلًا منها. أيّ علامة يرسمها الحقل المطلوب اختيار واحد يختاره نظام التصميم لكل النماذج بالرمز sys.behavior.requirement-mark: الوسم في النظام الافتراضي، ونجمة في إعدادات Material الجاهزة، ولا شيء في cupertino. والخاصية requiredMark تتجاوزه لحقل واحد (tag أو asterisk أو none، والأخيرة تُبقي الدلالات ولا ترسم شيئًا). والحقل من الطراز filled أو outlined يرسم النجمة حيث يُطلب الوسم.
  • الاختياري في تسمية عائمة. الحقل من الطراز filled أو outlined لا مكان فيه لوسم الاختياري بجانب تسمية تعوم: فيرسم optionalText بعد التسمية بدلًا منه، كلمةً («الشركة اختياري»، «会社名 （任意）»)، ساكنة وعائمة معها. اكتب الكلمة كما تعرضها نماذجك، بأقواس أو من دونها.
  • لا تتحقق من شيء. الحقل لا يعيّن error أبدًا لقيمة ناقصة. أنت تفعل ذلك، بالخاصيتين error و errorText.

علِّم الأقل من النوعين في النموذج: حيث تكون أكثر الحقول مطلوبة علِّم الاختيارية، والعكس بالعكس. وإن استخدمت النجمة — والحقل من الطراز filled أو outlined يستخدمها دائمًا للحقل المطلوب — فقل مرة واحدة في النموذج، قرب أعلاه، ما معناها («* مطلوب»): فالنجمة عُرف لا كلمة، وليس كل أحد يعرفه.

والحقل المطلوب يعرض علامة: عيِّن requiredMark بالقيمة none حيث لا تريدها.

نص المساعدة ونص الخطأ

  • الخاصية supportingText سطر واحد من المساعدة تحت الحقل. ويُقرأ أيضًا وصفًا للحقل.
  • التحقق من شأنك. حين تكون القيمة خاطئة عيِّن error واكتب errorText: فهو يأخذ مكان النص المساعد ما دام الحقل في حالة الخطأ، فلا يزيد ارتفاع النموذج في حالة الخطأ عنه في الراحة. قل فيه ما قالته المساعدة حيث يظل مهمًّا. ونظام التصميم الذي يُبقي المساعدة ظاهرة يعيّن comp.field.error-text.placement بالقيمة append: فيُرسم نص الخطأ عندئذ تحت المساعدة، ويزيد ارتفاع الحقل سطرًا ما دام في حالة الخطأ (انظر الحقل).
  • قل كيف تُصحَّح القيمة، لا أنها خاطئة فحسب: «أدخِل عنوان بريد إلكتروني كاملًا.»، لا «غير صالح».
  • اعرض الخطأ بعد أن يغادر الشخص الحقل أو يرسل النموذج، لا وهو ما زال يكتب.

العدّاد

  • الخاصية maxLength تحدّ ما يستطيع الشخص كتابته. وهي تعدّ الأحرف كما يراها الناس، فالإيموجي أو الحرف ذو العلامة يُعدّ مرة واحدة. واللصق يُقصَّر ليناسب الحد. أما القيمة التي تعيّنها أنت فلا تُقصَّر أبدًا.
  • الخاصية counter تعرض العدد في نهاية صف النص المساعد، يتبعه الحد حين تكون maxLength معيَّنة («12/40»).
  • اعرض العدّاد فقط حين يهمّ الحدُّ الشخصَ، كما في اسم معروض أو نبذة قصيرة.

أنواع الإدخال

الخاصية type تختار لوحة المفاتيح والتصحيح التلقائي والإدخال المحجوب. والقيمة سلسلة نصية في كل الأنواع.

النوع لوحة المفاتيح والسلوك
text لوحة مفاتيح عامة.
email لوحة مفاتيح للبريد الإلكتروني، بلا تكبير تلقائي للأحرف ولا تصحيح تلقائي.
password إدخال محجوب وآمن، بلا تصحيح تلقائي. سطر واحد دائمًا.
number لوحة مفاتيح رقمية فيها فاصلة عشرية. القيمة لا تُحلَّل ولا تُقرَّب ولا يُتحقق منها.
search لوحة مفاتيح عامة يُقرأ مفتاح الإجراء فيها «بحث».
tel لوحة أرقام الهاتف.
url لوحة مفاتيح لعناوين URL، بلا تكبير تلقائي للأحرف ولا تصحيح تلقائي.
code لوحة مفاتيح عامة، ولا يُفعل بالنص شيء: بلا تصحيح تلقائي ولا تكبير تلقائي للأحرف ولا تدقيق إملائي ولا استبدال أحرف. سطر واحد، أو عدة أسطر مع multiline. انظر الشيفرة.
date و time و date-time تاريخ أو وقت أو كلاهما، يُدخل وحدةً وحدةً بالصيغة الرقمية للإعدادات المحلية. سطر واحد دائمًا. انظر التواريخ والأوقات.

أضِف autocomplete باسم تعبئة تلقائية من HTML (email و current-password و one-time-code …) لتستطيع المنصة ملء الحقل. وكل منصة تقابله بنوع المحتوى الخاص بها. أما الرمز القصير المعروف الطول الذي يُرسم في خانات فله حقل إدخال الرمز لمرة واحدة.

عدة أسطر

الخاصية multiline تقبل فواصل الأسطر وتعرض عدة أسطر. والخاصية resize تقول كيف يأخذ الحقل ارتفاعه:

resize الارتفاع المقبض minRows و maxRows
auto (الافتراضي) يتبع عدد الأسطر، بحركة قصيرة لا شيء أقل عدد من الأسطر وأكثره. وبعد الأكثر يُمرَّر؛ والقيمة 0 تعني بلا حد
manual ما يعطيه إياه الشخص. يبدأ عند minRows في الزاوية السفلى عند حافة النهاية أصغر ما يمكن أن يُجعل عليه وأطوله
fixed minRows من الأسطر لا شيء تُتجاهل maxRows
  • الوضع Auto يناسب أكثر الحقول: تعليق، رسالة، وصف. عيِّن maxRows حيث يجب ألا يدفع نص طويل بقية النموذج بعيدًا.
  • الوضع Manual يناسب نصًّا يعيد الشخص قراءته ويرتّبه: ملاحظات، وصف طويل، شيفرة. الخاصية resizeAxis قيمتها vertical افتراضيًّا؛ والقيمة both تتيح للشخص أيضًا أن يغيّر عرض الحقل، ضمن ما يسمح به تخطيطه. ويُحفظ الحجم، والنص يلتفّ ويُمرَّر داخله.
  • الوضع Fixed يناسب نموذجًا يجب ألا يتحرك تخطيطه، ككتلة العنوان البريدي.
  • المقبض يعمل بلا سحب. هو مقبض تغيير حجم بالحجم small في الزاوية السفلى عند حافة النهاية، لا يظهر حتى يمرّ المؤشر فوق الحقل أو يأخذ الحقل التركيز، وهو موضع توقف للتركيز تسمّيه الخاصية resizeLabel. مفاتيح الأسهم تغيّر الحجم بسطر، والمفتاحان Page Up و Page Down بعدد minRows من الأسطر، والمفتاحان Home و End يذهبان إلى الأصغر والأطول، والنقرة أو المفتاح Enter أو Space تلائم الارتفاع مع النص، أو تعيده إلى minRows حين يكون ملائمًا سلفًا. وحيث تكون resizeAxis بالقيمة both، تجعل النقرة نفسها الحقل بعرض مكانه، وتعيد النقرة التالية العرض الذي كان له، فيستطيع المؤشر تغيير العرض بلا سحب. وهدفه هو الحد الأدنى للهدف، مع أن خطه صغير. وحين يغيّر الشخص الحجم، يصدر الحقل resizeend مع عدد الأسطر التي يعرضها (ومع عرضه، حيث يتغيّر حجمه في الاتجاهين)، فتستطيع أن تحتفظ بالحجم الذي اختاره. والحقل المعطَّل لا مقبض له؛ والحقل الذي للقراءة فقط يحتفظ به، لأن القراءة قد تحتاج إلى المساحة.
  • لا شيء فوق النص يتحرك. السطر الأول في الحقل المتعدد الأسطر يقف حيث يرسم الحقل ذو السطر الواحد سطره، وأيقوناته وبادئته ولاحقته موسَّطة على ذلك السطر. وكل سطر آخر يقع تحته، فتبقى التسمية والسطر الأول في مكانهما والارتفاع يتغيّر.

الشيفرة

الحقل من النوع code (type="code") لنص كُتب لآلة لا لقارئ: نمط، أو معرّف، أو مفتاح، أو استعلام، أو مقتطف من JSON أو YAML. وهو الحقل نفسه، بالتسمية والمساعدة والخطأ والعدّاد والأحجام وسلوك النموذج نفسها، وسطر إدخاله يحفظ الشيفرة كما كُتبت تمامًا.

  • من اليسار إلى اليمين، في كل لغة. القيمة ومؤشر الكتابة فيها والنص النائب والبادئة واللاحقة صف واحد من اليسار إلى اليمين يبدأ من اليسار، حتى في صفحة من اليمين إلى اليسار، وأيًّا كان الحرف الأول في الشيفرة: فالحقل الفارغ، والحقل الذي ليس فيه إلا {، والحقل الذي أول سلسلة نصية فيه عربية، تُخطَّط كلها بالطريقة نفسها. وكل ما عدا ذلك يتبع الصفحة: التسمية والأيقونات ونص المساعدة أو نص الخطأ والعدّاد ومقبض تغيير الحجم. والسلسلة النصية أو التعليق المكتوب بنظام كتابة من اليمين إلى اليسار يُخطَّط داخل سطره، ولا يغيّر ترتيب شيء مما حوله.
  • خط الشيفرة، بمقاس نص الإدخال. عائلة الخط هي التي لدور الشيفرة؛ أما المقاس وارتفاع السطر فيبقيان ما لنص الإدخال، فيكون حقل الشيفرة بارتفاع حقل النص الذي بجانبه. وتُحفظ كل مسافة، وحرف الجدولة (tab) يصل إلى موضع الجدولة التالي، ولا يُدمج حرفان في حرف مركَّب (ligature). ولا يُلوَّن شيء بحسب معناه.
  • تُترك كما هي. يُطلب من المنصة ألا تصحّح القيمة ولا تكبّر أحرفها ولا تدقّقها إملائيًّا ولا تترجمها ولا تكملها، وألا تحوّل علامات الاقتباس المستقيمة إلى معقوفة. واللصق نص عادي، حرفًا بحرف. والقيمة لا تُحذف المسافات من طرفيها ولا تُحلَّل ولا يُتحقق منها أبدًا: فالقول بسلامة صياغتها من شأنك، بالخاصيتين error و errorText.
  • سطر واحد أو عدة أسطر. السطر الواحد يناسب نمطًا أو مفتاحًا. ومع multiline يكمل السطر الذي لا يتسع له العرض في الصفوف التالية افتراضيًّا؛ ولا تحمل القيمة من فواصل الأسطر إلا ما في الشيفرة.
  • أسطر لا تلتفّ. الخاصية wrap بالقيمة false، وهي no-wrap على الويب، تُبقي كل سطر من الشيفرة في سطر واحد من الحقل، لجدول قيم، أو سجل أحداث (log)، أو ملف لفاصل السطر فيه معنى. والسطر الطويل يُمرَّر جانبيًّا داخل الحقل ولا يوسّع شيئًا. ولا يقرأ wrap إلا حقل شيفرة متعدد الأسطر: فالنص المتصل يلتفّ دائمًا، والسطر الواحد يُمرَّر دائمًا في سطره.
  • المفتاح Tab ينقل التركيز. لا يتغيّر معنى أي مفتاح: المفتاح Tab لا يضيف مسافة بادئة أبدًا، والمفتاح Enter لا يضيف مسافة بادئة، ولا يُغلق قوس بالنيابة عنك. وحرف الجدولة يصل باللصق أو من منتجك، ويُحفظ.
  • ليس محرّرًا. لا ألوان للصيغة، ولا أرقام أسطر، ولا طيّ، ولا علامات خطأ بحسب السطر. للشيفرة التي تُعرض ولا تُكتب استخدم كتلة الشيفرة؛ وللمحرّر ضمِّن المحرّر الذي اختاره منتجك.
  • النص النائب مثال من الشيفرة، يُرسم شيفرةً. أما التلميح بالكلمات فمكانه supportingText، وفيه أيضًا يقول الحقل ما ينتظره («JSON»).

في حقل من اليمين إلى اليسار تبدأ قيمة الشيفرة من اليسار، أما قيمة النوع email أو url أو tel أو number أو password فتُكتب من اليسار إلى اليمين عند حافة البداية للحقل، أي اليمين. والمنصات الأخرى لم تبنِ النوع code بعد.

التواريخ والأوقات

الحقل من النوع date أو time أو date-time صف من المقاطع في سطر الإدخال، مقطع لكل وحدة: الشهر واليوم والسنة، والساعة والدقيقة، وفي نظام 12 ساعة فترة اليوم. تقف بترتيب الإعدادات المحلية وبفواصلها. ويحفظ الحقل القيمة بصيغة ISO 8601، بلا منطقة زمنية.

النوع القيمة الصف في en-US الصف في ja-JP
date 2026-09-27 09/27/2026 2026/09/27
time 14:30 2:30 PM 14:30
date-time 2026-09-27T14:30 09/27/2026, 2:30 PM 2026/09/27 14:30
  • الإعدادات المحلية. الخاصية locale، أو إعدادات المنصة، تعيّن الترتيب والفواصل ونظام الساعة والأرقام. والمقطع الفارغ يعرض نصه النائب (mm، dd، yyyy)، فيعرض الصف صيغته دائمًا. وكل مقطع بعرض الأعرض من نصه النائب وأعرض قيمه، فلا يتحرك الصف وأنت تكتب أو تمحو. وهذه الأنواع تتجاهل placeholder و prefixText و suffixText و maxLength و multiline.
  • التنقل. المفتاح Tab يزور كل مقطع، ثم زر المنتقي. ومفتاحا السهمين الأيسر والأيمن ينقلان إلى المقطع الذي في تلك الجهة، في كل اتجاه للتخطيط: فالصف مكتوب من اليسار إلى اليمين، كما يُكتب التاريخ بالأرقام. والضغط على مقطع ينقل التركيز إليه. والمقطع الذي عليه التركيز يُرسم نصًّا محدَّدًا، بلا مؤشر كتابة (caret).
  • التدرّج. مفتاحا السهمين العلوي والسفلي يغيّران المقطع بواحد ويدوران عند الطرفين؛ وعلى مقطع فارغ يبدآن من تاريخ اليوم أو الوقت الحالي. والمفتاحان Page Up و Page Down يخطوان أبعد، والمفتاحان Home و End يذهبان إلى طرفي المدى.
  • الكتابة. الرقم يملأ المقطع، وينتقل التركيز إلى التالي حين لا يمكن أن يمدّه رقم آخر، أو حين يُكتب الفاصل. والمفتاح Backspace يزيل رقمًا، وعلى مقطع فارغ يرجع إلى الوراء. والسنة تحتاج إلى أربعة أرقام. والتاريخ الذي لا وجود له لا يمكن إدخاله: اليوم الذي يتجاوز نهاية شهر اختير للتو يصير آخر يوم في ذلك الشهر.
  • اللصق. تاريخ كامل أو وقت كامل يُلصق على أي مقطع يملأ الصف. يُقرأ على أنه ثلاث مجموعات من الأرقام بترتيب الإعدادات المحلية، والمجموعة الأولى ذات الأرقام الأربعة تُقرأ على أنها السنة، فيعمل تاريخ ISO الملصوق في كل مكان. والنسخ والقص يأخذان الصف كله.
  • القيمة فارغة إلى أن يُملأ كل مقطع وتكون النتيجة متاحة. يصدر الحدث input حين تتغيّر القيمة، أي حين يُملأ المقطع الأخير أو يُعدَّل صف مملوء أو يُفرَّغ، ولا يصدر لمقطع يترك القيمة فارغة. ويصدر الحدث change حين يغادر التركيز مقاطع الحقل وزر المنتقي، أو حين يُضغط مفتاح الإجراء، والقيمة قد تغيّرت. والتنقل بين المقاطع لا يعتمد شيئًا.
  • خطأ الإدخال. الحقل الذي يُترك نصف مملوء يعرض invalidText. والحقل الذي يُترك بقيمة قبل min أو بعد max أو مدرجة في disabledDates يعرض unavailableText. وكلاهما يُرسم خطأً ويصدر entryError مع سببه (invalid أو unavailable)؛ والتعديل التالي ينهيه. وهو الخطأ الوحيد الذي يعيّنه الحقل بنفسه، ولا يمسّ الخاصية error التي لك.
  • ما تعيّنه أنت يُعرض كما هو، ولا يُتحقق منه أبدًا، ولا يصدر شيئًا.

نظام الساعة في الحقل هو نظام إعداداته المحلية: ليس فيه إعداد لنظام 12 أو 24 ساعة ولا درجة للدقائق، كما في DateTimePicker.

زر المنتقي. مع picker يرسم الحقل في نهايته زرًّا بأيقونة فقط، calendar_month للتاريخ و schedule للوقت، تسمّيه الخاصية pickerLabel. تفعيله يصدر pickerRequest مع القيمة والنوع و min و max؛ والصف النصف مملوء يرسل قيمة فارغة ولا يثير خطأ إدخال، لأن المنتقي يوشك أن يعطي قيمة كاملة. والحقل لا يعرض شيئًا بنفسه: منتجك يفتح DateTimePicker في الوضع المطابق، مرتكزًا على الحقل حين يكون مُرسى (docked)، ويعيّن الخاصية value في الحقل من الحدث change في المنتقي. أعطِ المنتقي قيم min و max و disabledDates نفسها التي للحقل. ويعود التركيز إلى الزر حين يُغلق المنتقي. والزر يتعطّل مع الحقل ولا يُرسم ما دام الحقل للقراءة فقط.

افعل

  • ضع النص الثابت الذي ليس جزءًا من القيمة في prefixText و suffixText: علامة عملة، وحدة.
  • ضع إجراء المسح أو إجراء إظهار كلمة المرور في منفذ النهاية زرًّا بأيقونة فقط من عندك، له اسمه. زر المنتقي هو الإجراء الوحيد المبني في الحقل، ويأتي بعد إجراءاتك.
  • استخدم multiline للنص الذي قد يمتد إلى عدة أسطر. وهو افتراضيًّا يكبر من minRows إلى maxRows، ثم يُمرَّر.
  • عيِّن required على الحقول التي يطلبها النموذج، وقل مع ذلك ما الناقص في errorText حين يُرسل النموذج.
  • استخدم type="code" لقيمة تقرؤها آلة، كنمط أو مفتاح أو مقتطف من إعدادات، وقل ما يجب أن تكون عليه في التسمية وفي supportingText.

لا تفعل

  • لا تستخدم النص النائب تسميةً. فهو يختفي ما إن يكتب أحد.
  • لا تستخدم number لقيم ليست كميات، كرقم بطاقة أو رمز بريدي. استخدم text مع قيمة autocomplete المناسبة.
  • لا تخلط الطُرُز في نموذج واحد.
  • لا تضع حقل نص داخل حقل. فهو حقل أصلًا؛ وبنية التنقيح (debug) تقول ذلك. وعنصر التحكم الذي يؤطّره الحقل هو حقل إدخال النص.
  • لا تستخدم حقلًا من النوع text وتحليلًا من عندك لتاريخ. استخدم date، ليأتي معه ترتيب الإعدادات المحلية ومفاتيح المقاطع وخطأ الإدخال.
  • لا تكتب «(مطلوب)» في التسمية وتعيّن required معًا. العلامة تقول ذلك سلفًا، وقارئ الشاشة سيسمعه مرتين.
  • لا تجعل الحقل الذي يُغيَّر حجمه باليد الطريقة الوحيدة لرؤية نص طويل. أعطِه من minRows ما يكفي ليكون نافعًا حين يُفتح.
  • لا تعطِّل حقلًا لمجرد عرض قيمة لا تتغيّر. استخدم readOnly، ليبقى في وسع الناس أن يركّزوا عليها ويحدّدوها وينسخوها.
  • لا تعيّن خط الشيفرة لحقل نص من الخارج، بالمحدِّد ::part(input) أو بنمط من عندك، ولا تضف dir أو spellcheck إلى العنصر. استخدم type="code": فالخط وحده يترك حقلًا يبدو صحيحًا وما زال يصحّح ما يُكتب.
  • لا تستخدم حقل الشيفرة محرّرًا، ولا تستخدم حقل شيفرة معطَّلًا لعرض شيفرة طويلة: فالحقل المعطَّل ليس فيه مؤشر كتابة يُمرَّر به. استخدم readOnly، أو كتلة الشيفرة.

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

الدور
textbox
التسمية
The text field adds nothing to what its members expose, and the one thing it coordinates — the drawn count (TXF-67) — is kept from assistive technology, which hears the count from the input: the Field gives the text input its name, its description and its required, invalid and disabled states (FLD-8, FLD-10, FLD-11, FLD-14), and the text input carries them on its own element (TXI-23). Assistive technology meets one text box — or, for a date or a time, one group of spin buttons — named by label, exactly as it meets a Field around a text input written by hand.
الحد الأدنى للهدف
تستوفي مساحة اللمس الحد الأدنى لحجم الهدف حتى لو كان الحجم المرئي أصغر. minimum 32px · pointer 44px · spacing 8px · touch 48px

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

المفاتيح الإجراء
Every key The text input's (its accessibility block; TXI-3, TXI-41, TXI-43 to TXI-45, TXI-59). The text field handles no key and adds no focus stop (TXF-64).

ملاحظات

  • One level down is the same thing: a Field with a text input in it. Every fixture has that pair as its twin, and the accessibility tree of the two is the same (TXF-62). What the pair by hand does not do by itself is keep the Field's count text equal to the input's count as the person types (TXF-67): the product writes it at each input.
  • On the web the two members stand in the text field's own shadow root, so the form meets the text field and not the input (TXF-63); focus passes through to the input (TXF-64).

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

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

  • يُحرَّر النص في عنصر النص الخاص بالمنصة، فتعمل أساليب الإدخال والإملاء والتعبئة التلقائية والتحديد والحافظة كما تعمل في سائر المنصة. والتاريخ أو الوقت هو الاستثناء المصرَّح به: صف مقاطعه من صنع الحقل نفسه.
  • حقل التاريخ أو الوقت مجموعة تسمّيها التسمية. وكل مقطع زر دوّار (spin button) تسمّيه وحدته والتسمية («الشهر، تاريخ البدء»)، مع مداه وقيمته؛ والمقطع الفارغ يُقرأ نص segmentEmptyText.
  • الحقل المطلوب يُعرض على أنه مطلوب. والعلامة نفسها مخفيّة عن التقنيات المساعدة، فلا تُقرأ مرتين؛ والنص الاختياري يُقرأ مع وصف الحقل.
  • مقبض تغيير الحجم موضع توقف للتركيز تسمّيه الخاصية resizeLabel، ويُعرض فاصلًا (separator) قيمته عدد الأسطر. مفاتيح الأسهم والمفتاحان Home و End تغيّر الحجم، فلا شيء يتوقف على السحب، ومساحة لمسه تستوفي الحد الأدنى للهدف.
  • التسمية هي الاسم المتاح للتقنيات المساعدة، مرسومةً كانت أو مخفيّة. والنص النائب ليس كذلك أبدًا.
  • النص المساعد أو نص الخطأ المعروض والعدد هي وصف الحقل. وكذلك البادئة واللاحقة ما دامتا معروضتين، فتُقرأ الوحدة أو العملة مع القيمة.
  • يعرض حالة التعطيل، وحالات عدم الصلاحية والمطلوب والقراءة فقط حيث تكون للمنصة. وخطأ الإدخال في حقل تاريخ أو وقت يُعرض تمامًا كما تُعرض error.
  • زر المنتقي زر تسمّيه الخاصية pickerLabel، ويُعرض على أنه يفتح مربع حوار، وهو موضع توقف للمفتاح Tab بعد المقطع الأخير.
  • حين يظهر خطأ أو يتغيّر والتركيز على الحقل، يُعلَن مرة واحدة، بتهذيب. والعدد يُعلَن كما هو معروض («12/40») حين تتوقف الكتابة ثانية واحدة، لا عند كل ضغطة مفتاح أبدًا.
  • حقل البحث يُعرض مربع بحث (search box) حيث يكون للمنصة هذا الدور.
  • حقل الشيفرة هو مربع النص نفسه الذي لكل نوع آخر، ومتعدد الأسطر مع multiline: لا دور ولا وصف دور ولا كلمة تقول إنه يحمل شيفرة، ولا يُعلَّم أي جزء من قيمته خطأً إملائيًّا. والمفتاح Tab يغادره دائمًا. وحيث لا تلتفّ أسطره يمرّره مؤشر الكتابة، ويُعرض التركيز على الحاوية، وهي لا تُمرَّر.
  • يُعرض التركيز بحافة الحقل نفسها، سواء جاء من لوحة المفاتيح أو من مؤشر: خط داخل صندوق الحقل من الطراز stacked، والحافة الأثخن الملوَّنة للحقل من الطراز filled أو outlined. ومساحة اللمس تستوفي الحد الأدنى للهدف.
  • الضغط على التسمية أو على الصندوق ينقل التركيز إلى حقل الإدخال ولا يشغّل شيئًا. والضغط على المساعدة أو نص الخطأ أو العدد لا يفعل شيئًا.
  • الاسم والوصف والحالات مربوطة به تمامًا كما يربطها الحقل بأي عنصر تحكم يؤطّره. والحقل المكتوب باليد، في المستوى الأدنى، هو مربع النص نفسه.
  • غياب التسمية يُبلَّغ عنه في بنيات التنقيح (debug).

فجوات معروفة في المنصات:

  • تحتفظ SwiftUI و Compose و Flutter و React Native بالراية required التي لا ترسم علامة، وليس فيها أوضاع تغيير الحجم ولا مقبض ولا مقاطع.
  • الويب: ينزاح صف المقاطع بضعة بكسلات حين يأخذ الشهر أو الدقيقة رقمه الأول؛ وقد يصدر input مرتين حيث يكون المقطع الأخير في الإعدادات المحلية من رقمين؛ وعلى لوحة مفاتيح Android التي على الشاشة لا يستطيع المفتاح Backspace على مقطع فارغ أن يرجع إلى الوراء؛ والصف الأعرض من حقل ضيق يفيض بدل أن يُمرَّر.
  • لا يستطيع المنتج أن يفرّغ صف تاريخ نصف مملوء بتعيين value بالسلسلة الفارغة التي هي فيه سلفًا.
  • الويب: تحت نمط التركيز بالتوهّج (glow)، توهّج الحقل من الطراز filled مدوَّر عند الزاويتين السفليين، وهما مربعتان.
  • الويب: التركيب في أسلوب الإدخال (input-method composition) والتسمية المعبَّأة تلقائيًّا مختبَران في Chromium فقط.
  • الويب: حقل الشيفرة الذي للقراءة فقط ولا تلتفّ أسطره يُمرَّر من لوحة المفاتيح كما يمرّر المتصفح أي نص لا يحرّره: بمؤشر الكتابة في Firefox، وبمفاتيح الأسهم في Chrome، وبالمفتاح Option مع مفاتيح الأسهم في Safari. ويعيد Firefox مثل هذا الحقل إلى حافته اليسرى حين يتغيّر اتجاه الصفحة.
  • لم يبنِ SwiftUI و Compose و Flutter و React Native النوع code: فليس في type هناك القيمة code، وليس في الحقل wrap.
  • ليس في SwiftUI حالات لعدم الصلاحية ولا للمطلوب ولا للقراءة فقط. فهي تُرسم أو تُفرض، ولا تُعلَن. والخطأ يُسمع فقط نصًّا في الوصف.
  • لا يستطيع SwiftUI رؤية التركيب في أسلوب الإدخال، فتنطبق maxLength أيضًا على نص ما زال يُركَّب، والقيمة التي تعيّنها في أثناء التركيب لا تؤجَّل.
  • في SwiftUI: النص المحدَّد يُظلَّل بصبغة مؤشر الكتابة، لا بلون التحديد الخاص بالحقل.
  • يرسم SwiftUI قيمة الحقل الذي للقراءة فقط نصًّا قابلًا للتحديد، لا حقل نص.
  • لا يقرأ SwiftUI المُعدِّل .labelsHidden() إلا من iOS 18 و macOS 15. وفي الإصدارات الأقدم ما زالت التسمية تُرسم.
  • لا يستطيع React Native رؤية التركيب في أسلوب الإدخال. القيمة التي تغيّرها في أثناء التركيب، وحد maxLength، يُطبَّقان فورًا وقد ينهيان التركيب.
  • ليس في React Native حالات لعدم الصلاحية ولا للمطلوب ولا للقراءة فقط. الخطأ يُسمع فقط نصًّا في الوصف؛ والمطلوب والقراءة فقط لا يُعلَنان.
  • في React Native: الإعلانات والتعبئة التلقائية ولوحة المفاتيح لكل نوع مختبَرة بكائنات وهمية (mocks) فقط، لا على جهاز بعد.
  • في React Native على iOS صبغة واحدة لمؤشر الكتابة ولتظليل التحديد. يحتفظ الحقل بلون مؤشر الكتابة، فيكون التظليل صبغة منه لا لون التحديد الخاص بالحقل.
  • في React Native: توهّج الحقل من الطراز filled يتبع زاويتيه العلويين فقط، ولونا النص النائب ومؤشر الكتابة ينقلبان فورًا بدل أن يتغيّرا على مدى حركة الحالة.
  • يعرض Flutter حقل البحث نوعَ إدخال للبحث، لا دور مربع البحث.
  • لا يرسم Flutter مقابض تحديد ولا شريط أدوات للتحديد على Android وغيره من شاشات اللمس. الضغط المطوَّل واختصارات لوحة المفاتيح ما زالت تحدّد وتنسخ؛ و iOS يعرض قائمة نظامه.
  • في Flutter: العنصر التفاعلي في منفذ البداية يأتي قبل حقل الإدخال في ترتيب التركيز، لا بعده.
  • ليس في Compose حالة للمطلوب: يقرأ الحقل «Required» وصفًا لحالته بدلًا منها.
  • في Compose: الخاصية maxLength والعدّاد يعدّان الأحرف كما يراها الناس، لكن تسلسلات الإيموجي والأعلام غير مختبَرة. تعمل الاختبارات على JVM تحت Robolectric، وقواعد الأحرف فيه لا تعرفها.
  • في Compose: إعلانات TalkBack عن الخطأ والعدد، وأسلوب إدخال حقيقي، وخدمة تعبئة تلقائية حقيقية لم تُختبر على جهاز.

ما عليك فعله

  • اكتب تسمية تسمّي القيمة، وأبقِها حتى حين تخفيها.
  • اكتب نص خطأ يقول كيف تُصحَّح القيمة، وعيِّن error بنفسك. على SwiftUI و React Native ذلك النص هو الطريقة الوحيدة التي يُسمع بها الخطأ. ولحقل تاريخ أو وقت اكتب أيضًا invalidText و unavailableText، وأعطِ segmentEmptyText: من دونه يُقرأ المقطع الفارغ بلا قيمة.
  • أعطِ زر المنتقي الخاصية pickerLabel بلغة منتجك، وافتح المنتقي من الحدث pickerRequest.
  • عيِّن required أو optional، وأعطِ requiredText و optionalText: على الحقل، أو مرة واحدة للمنتج كله بالاستدعاء setWords({ requiredText, optionalText })، كما يمكن أن تُعطى resizeLabel و segmentEmptyText بالطريقة نفسها. لا يتضمن Tanrei أي كلمة على الويب، والكلمة الناقصة يُبلَّغ عنها أثناء التطوير. انظر كلمات المنتج. وإلى أن يلحق SwiftUI و Compose و Flutter و React Native لا ترسم حقولها علامة، و SwiftUI و React Native لا يُعلِنان حالة المطلوب: قل «مطلوب» في التسمية هناك.
  • سمِّ مقبض تغيير الحجم بالخاصية resizeLabel. من دونها يُرسم المقبض ويعمل، ولا اسم له.
  • ضع الوحدة أو العملة في prefixText أو suffixText، لا في القيمة، لتُقرأ مع القيمة ولا تُكتب.
  • لحقل الشيفرة، قل ما يجب أن تكون عليه الشيفرة في label و supportingText («محتوى طلب Webhook» و«JSON»)، وقل ما الخطأ فيها في errorText: فالحقل لا يعرف اللغة.
  • أعطِ زر الأيقونة الذي في النهاية اسمه الخاص بلغة منتجك.
  • على Compose تأتي الكلمتان «Invalid» و«Required» من موارد السلاسل النصية في المكتبة (tanrei_invalid و tanrei_required). تجاوزهما في مواردك لتترجمهما.
  • على الويب يكبّر iOS Safari العرض على حقل إدخال نصه أصغر من 16 px. حقول النظام الافتراضي تستخدم نصًّا بمقاس 16 px في الحجمين؛ والطبقة التي تصغّره تعيد التكبير.

الشيفرة المصدرية والمشكلات على GitHub