---
title: "حقل العدد"
description: "يتيح للأشخاص إدخال عدد بوصفه عددًا: يُكتب بالصورة التي تكتبه بها إعداداتهم المحلية أو يُغيَّر خطوةً خطوةً بمفتاح أو بزر، ويبقى ضمن حدوده، ووحدته بجانبه. وهو حقل كامل واحد من حقول النموذج، مبني من حقل وحقل إدخال العدد."
url: "https://tanrei.chnotchy.com/ar/components/number-field/"
last_updated: 2026-10-23T21:17:12.000Z
---

# حقل العدد

> يتيح للأشخاص إدخال عدد بوصفه عددًا: يُكتب بالصورة التي تكتبه بها إعداداتهم المحلية أو يُغيَّر خطوةً خطوةً بمفتاح أو بزر، ويبقى ضمن حدوده، ووحدته بجانبه. وهو حقل كامل واحد من حقول النموذج، مبني من حقل وحقل إدخال العدد.

## نظرة عامة

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

**يُبنى من** [حقل](https://tanrei.chnotchy.com/ar/components/field/) و [حقل إدخال العدد](https://tanrei.chnotchy.com/ar/components/number-input/). الحقل هو الإطار: التسمية، وعلامة المطلوب أو الاختياري، والمساعدة، والخطأ. وحقل إدخال العدد هو عنصر التحكم: الصندوق، والعدد، ووحدته، وزرّا التدرّج (steppers). وحقل العدد لا يرسم شيئًا من عنده وليس له أي رمز تصميم (token): فكل خاصية له هي خاصية لأحد الاثنين، تُعطى له كما هي.

حقل العدد حقل أصلًا: فلا يوضع داخل [حقل](https://tanrei.chnotchy.com/ar/components/field/) أبدًا. وحيث تقف التسمية في مكان آخر، بجانب شريط تمرير أو في خلية من جدول، استخدم [حقل إدخال العدد](https://tanrei.chnotchy.com/ar/components/number-input/) وحده.

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

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

### الاستخدام

الخاصية `value` عدد، أو `null` ما دام الحقل لا يحمل عددًا. وتتغيّر حين **يعتمد** الشخص ما أدخله، أي حين يغادر التركيز الحقل أو يُضغط المفتاح Enter أو يُغيَّر العدد خطوة، لا عند كل ضغطة مفتاح. وما دام الشخص يكتب فالنص له: لا شيء يُرفض ولا يُعاد تنسيقه ولا يُردّ إلى الحدّين ولا يُقرَّب. وفي أثناء ذلك يحمل الحدث `input` العدد الذي يُقرأ به النص.

**Web**

```html
<form>
  <tanrei-number-field name="quantity" label="الكمية" value="1" min="1" max="99"
    required required-text="مطلوب" invalid-text="أدخِل رقمًا."
    increment-label="زيادة" decrement-label="إنقاص"></tanrei-number-field>
</form>

<!-- وحدة، وخطوة مقدارها ربع، وبلا حد أعلى. -->
<tanrei-number-field id="radius" label="نصف قطر الزاوية" value="8" min="0" step="0.25" suffix-text="px"
  increment-label="زيادة" decrement-label="إنقاص"></tanrei-number-field>

<!-- المال: علامة العملة قبل العدد، واختصارها بعده، ومنزلتان عشريتان دائمًا. -->
<tanrei-number-field label="المبلغ" value="120" prefix-text="$" suffix-text="USD"
  min-fraction-digits="2" max-fraction-digits="2"
  increment-label="زيادة" decrement-label="إنقاص"></tanrei-number-field>

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

  const radius = document.querySelector('#radius');
  // اعتمادٌ غيّر القيمة. وهي الآن القيمة الجديدة: عدد، أو null.
  radius.addEventListener('change', () => save(radius.value));
  // الشخص يكتب أو يغيّر العدد خطوة: العدد الذي يُقرأ به النص، غير مردود إلى الحدّين وغير مقرَّب، أو null.
  radius.addEventListener('input', (e) => preview(e.detail.value));
  // اعتُمد نص ليس عددًا. الحقل يحتفظ به ويعرض invalidText:
  // و detail.text هو ذلك النص، ويكون فارغًا حيث لم يُعطَ الحقل نصًّا.
  radius.addEventListener('entryerror', (e) => console.log(e.detail.reason, e.detail.text));
</script>
```

**React**

```tsx
import { NumberField } from '@tanrei/react';

<NumberField label="نصف قطر الزاوية" value={radius} min={0} step={0.25} suffixText="px"
  incrementLabel="زيادة" decrementLabel="إنقاص"
  onChange={(event) => setRadius(event.currentTarget.value)} />
```

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

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

```html
<tanrei-field label="الكمية" required required-text="مطلوب"
  supporting-text="حتى 99 في الطلب الواحد.">
  <tanrei-number-input name="quantity" min="1" max="99" invalid-text="أدخِل رقمًا."
    increment-label="زيادة" decrement-label="إنقاص"></tanrei-number-input>
</tanrei-field>
```

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

| تحتاج إلى | استخدم |
| --- | --- |
| تسمية وصندوق ومساعدة وخطأ | حقل العدد |
| شيء من عندك داخل الإطار، بجانب الصندوق أو تحته | [حقل](https://tanrei.chnotchy.com/ar/components/field/) بداخله [حقل إدخال العدد](https://tanrei.chnotchy.com/ar/components/number-input/) وعنصرك أنت |
| الصندوق وحده، تحت تسمية تقف في مكان آخر: بجانب شريط تمرير، أو خلية في جدول، أو شريط أدوات | [حقل إدخال العدد](https://tanrei.chnotchy.com/ar/components/number-input/) وحده، وتسمّيه `label` الخاصة به |

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

## المواصفات

### الحقل

| الجزء | ما هو |
| --- | --- |
| التسمية | للحقل: فوق الحاوية (في الطراز `stacked`). وفي الطرازين `filled` و `outlined` يرسمها حقل إدخال العدد، عائمة داخل الصندوق، ولا يرسم الحقل صف التسمية. وهي الاسم المتاح للتقنيات المساعدة، سواء رُسمت أم أُخفيت بالخاصية `labelHidden` |
| علامة المطلوب أو الاختياري | للحقل، بعد التسمية: وسم المطلوب أو نجمة أو لا شيء حين تكون `required`، ووسم الاختياري حين تكون `optional`. والتسمية العائمة تأخذ النجمة |
| حقل الإدخال | لحقل إدخال العدد: العدد نصًّا. هو ما كتبه الشخص ما دام يعدّل، وفي غير ذلك العدد المعتمَد بالصورة التي تكتبه بها الإعدادات المحلية. سطر واحد، يُمرَّر |
| البادئة واللاحقة | لحقل إدخال العدد: نص ثابت قبل العدد وبعده، كعلامة عملة أو وحدة. وهما جزء من الصندوق، لا من القيمة أبدًا |
| زرّا التدرّج | لحقل إدخال العدد: زرّان في النهاية، الأول ينقص العدد خطوة، والثاني يزيده خطوة. يُتركان بجعل `steppers` بالقيمة false |
| النص المساعد | للحقل: سطر من المساعدة. وما دام الحقل في حالة الخطأ يأخذ نص الخطأ مكانه (أو يُرسم تحته، حيث يُبقي نظام التصميم الاثنين)، وهو `errorText` ما دامت `error` بالقيمة true، و `invalidText` ما دام النص ليس عددًا. يبدأ وينتهي عند حشو النص في الصندوق، مع زرّي التدرّج ومن دونهما |

الطُرُز الثلاثة والأحجام الثلاثة، `small` (32) و `medium` (40) و `large` (56)، هي ما لحقل النص. والنظام الافتراضي يتضمن الطراز `stacked` وحده.

ليس لحقل العدد رمز تصميم خاص به. صندوقه يقرأ [رموز تصميم حقل إدخال العدد](https://tanrei.chnotchy.com/ar/components/number-input/#%D8%A7%D9%84%D9%85%D9%88%D8%A7%D8%B5%D9%81%D8%A7%D8%AA)، وصفوفه تقرأ [رموز تصميم الحقل](https://tanrei.chnotchy.com/ar/components/field/#%D8%A7%D9%84%D9%85%D9%88%D8%A7%D8%B5%D9%81%D8%A7%D8%AA)، وزرّا التدرّج فيه يقرآن [رموز تصميم الزر](https://tanrei.chnotchy.com/ar/components/button/#%D8%A7%D9%84%D9%85%D9%88%D8%A7%D8%B5%D9%81%D8%A7%D8%AA)، أينما عُيِّنت. ولتغيير مثيل واحد، عيِّن رمز تصميم العضو عليه: `style="--tanrei-comp-field-label-gap: 0.75rem"`.

زرّا التدرّج زرّان من الطراز text بالحجم medium، متجاوران. في النظام الافتراضي يأخذان 88 من عرض الحقل، وكلٌّ منهما هدف لمس كامل. ولا يُرسمان أصغر من ذلك أبدًا ولا يُرصّ أحدهما فوق الآخر: فحيث لا يتسع الصف لهما أوقفهما. والمفاتيح تظل تغيّر العدد خطوةً خطوةً.

### القيمة والنص

| متى | ما يحدث |
| --- | --- |
| يكتب الشخص أو يلصق أو يملي | لا يتغيّر شيء. الحدث `input` يحمل العدد الذي يُقرأ به النص، أو `null` |
| يغادر التركيز، أو يُضغط المفتاح Enter | يُعتمد النص: يُرفع إلى `min`، ويُخفض إلى `max`، ويُقرَّب إلى `maxFractionDigits`، ويصير هو القيمة، ويُكتب من جديد بالصورة التي تكتبه بها الإعدادات المحلية. ويصدر الحدث `change` إن اختلفت القيمة |
| النص فارغ | تصير القيمة `null` |
| النص ليس عددًا | يبقى النص. تصير القيمة `null`، ويكون الحقل في حالة خطأ ويعرض `invalidText`، أو `errorText` الخاصة به حيث لا يوجد، ويصدر الحدث `entryerror` |
| يعيّن المنتج `value` | يُعرض العدد، أيًّا كان ما كُتب. لا يصدر أي حدث، ولا يُصحَّح العدد بالحدّين `min` و `max` |

العدد المعتمَد يُكتب بأرقام الإعدادات المحلية وفاصلتها العشرية، وبعد الفاصلة ما بين `minFractionDigits` و `maxFractionDigits` من الأرقام، وبلا فواصل للمجموعات (فواصل الآلاف)، فما يُعرض يمكن أن يُكتب من جديد كما هو.

يُقرأ النص بتسامح، بحسب الخاصية `locale` في الحقل، أو بحسب لغة الصفحة حيث تكون تلك الخاصية فارغة:

- المسافات حول العدد وداخله تُتجاهل.
- الشرطة القصيرة (hyphen-minus) أو علامة الناقص أو علامة الزائد قبل الأرقام هي إشارة العدد.
- أرقام ASCII وأرقام الإعدادات المحلية نفسها والأرقام كاملة العرض كلها أرقام.
- فاصل المجموعات في الإعدادات المحلية يُتجاهل بين الأرقام: النص `1,234.50` يُقرأ 1234.5 في الإنجليزية.
- البادئة واللاحقة المكتوبتان أو الملصوقتان تُتجاهلان: النص `12 px` يُقرأ 12.
- الأحرف، أو الأُسّ، أو فاصلتان، أو إشارة وحدها ليست عددًا.

لا يخمّن الحقل أبدًا بين إعدادات محلية وأخرى. في الألمانية، حيث العلامة `,` هي الفاصلة العشرية، يُقرأ النص `1.500` على أنه 1500 والنص `1.5` على أنه 15.

العدد ووحدته مقطع واحد من الكتابة. تُكتب البادئة قبل العدد واللاحقة بعده في اتجاه نظام كتابة الوحدة نفسه، أيًّا كان اتجاه الصفحة. ولذلك تُقرأ «`44 px`» و «`$ 120 USD`» و «`40 %`» في صفحة عربية أو عبرية كما تُقرأ في صفحة إنجليزية، والوحدة المكتوبة بأحرف عربية أو عبرية تقف عن يسار العدد. وزرّا التدرّج والتسمية يتبعان الصفحة. والقيمة `align="end"` تضع العدد لصق وحدته: عند اليمين مع وحدة مكتوبة بأحرف أو علامات لاتينية، في الاتجاهين كليهما. ولاختصار عملة بأحرف لاتينية عن يسار العدد، ابدأ اللاحقة بعلامة الاتجاه من اليمين إلى اليسار (U+200F).

### التدرّج

| الإدخال | ما يحدث |
| --- | --- |
| مفتاحا السهم للأعلى والسهم للأسفل | يغيّران العدد بمقدار `step` |
| المفتاحان Page Up و Page Down | يغيّران العدد بعشرة أمثال `step` |
| ضغطة على زر تدرّج | تغيّر العدد خطوة واحدة. وإن استمر الضغط تكرّرت الخطوة: بعد نصف ثانية، ثم عشر مرات في الثانية، ثم عشرين |
| المفتاحان Home و End ومفتاحا السهم لليسار والسهم لليمين | تحرّك مؤشر الكتابة (caret) في النص |
| عجلة الفأرة، أو السحب | لا شيء. الصفحة تُمرَّر |

الخطوة تذهب إلى العدد التالي على شبكة الخطوات، محسوبةً من `min` (ومن الصفر حين لا تكون معيَّنة): فبخطوة مقدارها 5 يصعد العدد 12 إلى 15 وينزل إلى 10. وتُحسب بالنظام العشري، فالعدد 0.2 بخطوة مقدارها 0.1 يصير 0.3. والحقل الفارغ يخطو إلى أقرب عدد إلى الصفر تسمح به الحدود.

الخاصية `step` تقول مقدار الخطوة. ولا تحدّ ما يمكن أن يُكتب: فبخطوة مقدارها 5 يبقى العدد 12 المكتوب 12. ولقبول أعداد بعينها دون غيرها، تحقق من القيمة وعيِّن `error`.

### مع شريط التمرير

العدد الذي بجانب شريط تمرير، تحت عنوان صف واحد، هو الصندوق وحده: [حقل إدخال العدد](https://tanrei.chnotchy.com/ar/components/number-input/#%D9%85%D8%B9-%D8%B4%D8%B1%D9%8A%D8%B7-%D8%A7%D9%84%D8%AA%D9%85%D8%B1%D9%8A%D8%B1)، وتسمّيه `label` الخاصة به. والعيّنة في صفحته.

- Category: Text inputs
- Level: composed
- Listing: default
- Built from: Field, Number input
- Page: https://tanrei.chnotchy.com/components/number-field/
- Spec: https://github.com/chnotchy/tanrei/blob/main/specs/number-field.spec.json

### Availability

| Design system | Has it | Notes |
| --- | --- | --- |
| Tanrei (`tanrei`) | Yes | Variants left out: `filled`, `outlined`. |
| Cupertino (Apple HIG-inspired) (`cupertino`) | Yes | — |
| M3 Expressive-like (Material 3 Expressive-inspired) (`m3-expressive-like`) | Yes | — |
| M3-like (Material 3-inspired) (`m3-like`) | Yes | — |

### Platforms

- Web: the element `<tanrei-number-field>`, registered by importing `@tanrei/web` (or only its own module, `@tanrei/web/components/number-field`).
- React: `NumberField` from `@tanrei/react`.

| Platform | Name | Status |
| --- | --- | --- |
| Web | `tanrei-number-field` | lagging |
| SwiftUI | `TanreiNumberField` | planned |
| Jetpack Compose | `TanreiNumberField` | planned |
| Flutter | `TanreiNumberField` | planned |
| React Native | `NumberField` | planned |

Names a platform gives in its own idiom:

| Spec | Web | SwiftUI | Jetpack Compose | Flutter | React Native |
| --- | --- | --- | --- | --- | --- |
| `label` (prop) | `label` | `label` | `label` | `labelText` | `label` |
| `labelHidden` (prop) | `labelHidden` | `labelsHidden` | `labelHidden` | `labelHidden` | `labelHidden` |
| `placeholder` (prop) | `placeholder` | `prompt` | `placeholder` | `hintText` | `placeholder` |
| `supportingText` (prop) | `supportingText` | `supportingText` | `supportingText` | `helperText` | `supportingText` |
| `error` (prop) | `error` | `error` | `isError` | `isError` | `error` |
| `disabled` (prop) | `disabled` | `disabled` | `enabled` | `enabled` | `disabled` |
| `required` (prop) | `required` | `isRequired` | `required` | `required` | `required` |
| `optional` (prop) | `optional` | `isOptional` | `optional` | `optional` | `optional` |
| `min` (prop) | `min` | `in` | `min` | `min` | `min` |
| `max` (prop) | `max` | `in` | `max` | `max` | `max` |
| `steppers` (prop) | `noSteppers` | `steppers` | `steppers` | `steppers` | `steppers` |
| `incrementLabel` (prop) | `incrementLabel` | `incrementLabel` | `incrementContentDescription` | `incrementSemanticLabel` | `incrementAccessibilityLabel` |
| `decrementLabel` (prop) | `decrementLabel` | `decrementLabel` | `decrementContentDescription` | `decrementSemanticLabel` | `decrementAccessibilityLabel` |
| `prefixText` (prop) | `prefixText` | `prefix` | `prefix` | `prefixText` | `prefix` |
| `suffixText` (prop) | `suffixText` | `suffix` | `suffix` | `suffixText` | `suffix` |
| `valueText` (prop) | `valueText` | `valueText` | `stateDescription` | `semanticValue` | `valueText` |
| `input` (event) | `input` | `onInput` | `onInput` | `onInput` | `onInput` |
| `change` (event) | `change` | `value` | `onValueChange` | `onChanged` | `onValueChange` |
| `action` (event) | `action` | `onSubmit` | `keyboardActions` | `onSubmitted` | `onSubmitEditing` |
| `entryError` (event) | `entryerror` | `onEntryError` | `onEntryError` | `onEntryError` | `onEntryError` |

Statuses: `planned` — In the inventory. Nothing shippable exists yet. `lagging` — An implementation of an earlier spec exists; it has not caught up with the current one. `alpha` — Implemented with tests. The API may still change. `beta` — Feature complete and at parity. Only fixes are expected. `stable` — Covered by semantic versioning. `deprecated` — Still shipped; scheduled for removal.

### Anatomy

- `field`: The Field: the label row with its glyph and its requirement mark, and the supporting row with the help and the error text. In a look whose input floats the label it draws no label row.
- `number-input`: The number input, as the Field's one control: the box, the number in it, the prefix and the suffix, the two steppers, and the label that floats in the box in the looks that float one.

### Props

| Prop | Type | Default | Web attribute | Description |
| --- | --- | --- | --- | --- |
| `variant` | `enum`: `stacked`, `filled`, `outlined` | `"stacked"` | `variant` | The text input's three looks, so that a number input is drawn as the text inputs beside it: stacked is a filled box that shows focus and error with a line inside its edge and draws no label — the label of the Field that frames it stands above it; filled and outlined float the label inside the box. Use one style per form. A design system may leave some out (the Tanrei system ships stacked only) or add values. (From Number input.) |
| `size` | `enum`: `small`, `medium`, `large` | `"medium"` | `size` | Minimum height of the container: stacked 32 / 40 / 56, as tall as a Button of the same size, so that the box and a Button side by side in one row stand as tall as each other; filled and outlined 40 / 48 / 56, which hold the label that floats inside them. These are the text input's three sizes, small for a bar, a toolbar or a dense row of controls. The hit area always meets the minimum target. A design system may add values. (From Number input.) |
| `value` | `number` | — | `value` | The committed number, or null (the platform's absent value) while the field holds none. It changes when the person commits — focus leaves, the action key, a step — not on every keystroke; input carries what is being typed. (From Number input.) |
| `label` | `string` | `""` | `label` | 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. (From Field: Names the number input. In a filled or outlined look the input draws it, floating in its box, and the Field draws no label row (FLD-25, NMI-8).) |
| `labelHidden` | `boolean` | `false` | `label-hidden` | Does not draw the label, which stays the accessible name. For a control whose visible label is elsewhere (a table column, a toolbar). (From Field: Hides the label wherever it would be drawn: the Field's row, or the input's floating label (FLD-25). Where no message is shown either, the bare number input, named by its own label, is that control without a frame.) |
| `placeholder` | `string` | `""` | `placeholder` | A hint shown while the input is empty and the label is not in the input line. Never a replacement for a name. (From Number input.) |
| `supportingText` | `string` | `""` | `supporting-text` | 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). (From Field.) |
| `errorText` | `string` | `""` | `error-text` | 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. (From Field.) |
| `error` | `boolean` | `false` | `error` | 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. (From Field: The Field puts its number input in the input's own error condition (FLD-8, NMI-10); the steppers stay as they are.) |
| `disabled` | `boolean` | `false` | `disabled` | Disables the control and draws the frame as disabled. Disable a framed control here, not on the control, so that its label follows. (From Field: The Field disables its number input, and with it both steppers (FLD-14, NMI-32); the number field is then left out of its form (NUM-48).) |
| `readOnly` | `boolean` | `false` | `readonly` | The number can be focused, selected and copied, but not changed: no key steps it and no stepper is drawn. (From Number input.) |
| `required` | `boolean` | `false` | `required` | 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. (From Field: The Field exposes its number input as required (FLD-10, NMI-12).) |
| `optional` | `boolean` | `false` | `optional` | 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. (From Field.) |
| `requiredMark` | `enum`: `auto`, `tag`, `asterisk`, `none` | `"auto"` | `required-mark` | 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. (From Field.) |
| `requiredText` | `string` | `""` | `required-text` | 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. (From Field.) |
| `optionalText` | `string` | `""` | `optional-text` | 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. (From Field.) |
| `min` | `number` | — | `min` | The lowest number a commit keeps; a lower one is raised to it. Null for no limit. It is also where the steps are counted from. (From Number input.) |
| `max` | `number` | — | `max` | The highest number a commit keeps; a higher one is lowered to it. Null for no limit. (From Number input.) |
| `step` | `number` | `1` | `step` | How far Up Arrow, Down Arrow and a stepper move the number; Page Up and Page Down move ten times as far. It does not limit what may be typed. (From Number input.) |
| `steppers` | `boolean` | `true` | — | Draws the two stepper buttons at the end of the field. False for a field in a row too narrow for them, or beside a slider that does their work; the keys still step. (From Number input.) |
| `incrementLabel` | `string` | `""` | `increment-label` | The accessible name of the stepper that steps up, in the product's language ("Increase"). The product's: Tanrei has no word for it. Empty reads the product's words. Required while the steppers are shown. (From Number input.) |
| `decrementLabel` | `string` | `""` | `decrement-label` | The accessible name of the stepper that steps down, in the product's language ("Decrease"). The product's: Tanrei has no word for it. Empty reads the product's words. Required while the steppers are shown. (From Number input.) |
| `prefixText` | `string` | `""` | `prefix-text` | Fixed text before the number, not part of the value: a currency sign ("$", "¥"). (From Number input.) |
| `suffixText` | `string` | `""` | `suffix-text` | Fixed text after the number, not part of the value: the unit ("px", "ms", "%", "kg"). Read to assistive technology with the number. (From Number input.) |
| `valueText` | `string` | `""` | `value-text` | The value as words ("12 pixels", "3 stars"), given to assistive technology in place of the number with its prefix and suffix. The same text a Slider beside the field takes as its valueText. (From Number input.) |
| `align` | `enum`: `start`, `end` | `"start"` | `align` | Where the number stands in the input: at the start, as the text of every other field, or at the end, for a number in a column of numbers whose digits should line up. (From Number input.) |
| `minFractionDigits` | `number` | `0` | `min-fraction-digits` | The fewest digits shown after the decimal separator; zeros fill them (2 for an amount of money: "12.00"). (From Number input.) |
| `maxFractionDigits` | `number` | `3` | `max-fraction-digits` | The most digits kept after the decimal separator: a commit rounds to it. 0 makes the field hold whole numbers and asks for a keyboard without a separator. (From Number input.) |
| `locale` | `string` | `""` | `locale` | A BCP 47 language tag ("en-US", "de-DE", "ar-EG") for how the number is shown and read: its digits and its decimal separator. Empty uses the platform's current locale. The value itself is a number in every locale. (From Number input.) |
| `invalidText` | `string` | `""` | `invalid-text` | The words for an input committed with a text that is not a number ("Enter a number"): given to the Field that frames it, which shows them as its error text and, while they are empty, shows its own errorText (NMI-21, FLD-28). (From Number input: Shown by the Field, in its supporting row (FLD-28).) |

### Events

| Event | Description |
| --- | --- |
| `input` | The person changed the text, or a step changed the value; carries the number the text reads as — not clamped, not rounded — or the empty value while it reads as none. Emitted for every change, not when the product sets value. What a Slider beside the field follows. (From Number input.) |
| `change` | A commit changed the value: focus left the field, the action key was pressed, a key or a stepper stepped it, or a held stepper was released; carries the value. (From Number input.) |
| `action` | The person pressed the keyboard's action key (Enter, Return, Done). (From Number input.) |
| `entryError` | The person committed a text that is not a number; carries the reason (invalid) and invalidText, the words the input has for it. The entry error itself is shown by the Field that frames the input (NMI-21). (From Number input.) |

### Slots

| Slot | Description |
| --- | --- |
| `label-icon` | A glyph before the label. (From Field.) |

### States

`enabled`, `disabled`, `hovered`, `focused`, `error`

### Accessibility

- Role: `spinbutton`
- Labeling: The number field adds nothing to what its members expose and coordinates nothing: the Field gives the number input its name, its description and its required, invalid and disabled states (FLD-8, FLD-10, FLD-11, FLD-14), and the number input carries them on its own element with its value, its limits and its value text (NMI-12, NMI-34). Assistive technology meets one spin button named by label and two buttons that are no focus stops, exactly as it meets a Field around a number input written by hand.
- Minimum target size: yes

| Keys | Action |
| --- | --- |
| Every key | The number input's (its accessibility block; NMI-20, NMI-23). The number field handles no key and adds no focus stop (NUM-49). |

- One level down is the same thing: a Field with a number input in it. Every fixture has that pair as its twin, and the accessibility tree of the two is the same (NUM-47).
- On the web the two members stand in the number field's own shadow root, so the form meets the number field and not the input (NUM-48); focus passes through to the input (NUM-49).
- Two levels down, for a number whose label is elsewhere and that shows no message, is the number input alone, named by its own label: beside a slider under one row title, in a table, in a toolbar.

### Behaviour

Requirements in EARS form, each with its stable id.

- **NUM-47** THE number field SHALL be a Field that frames one number 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 number input, each unchanged; SHALL hold the label-icon slot for its Field; and SHALL emit its number input's events as its own, each once. THE number field SHALL be as wide as the place it stands in, and its number 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 (NMI-36). It SHALL draw no part of its own, hold no state of its own and have no token of its own: what it shows, how it behaves and what it exposes to assistive technology SHALL be exactly what that Field and that number input do when a product places the one in the other (FLD-1 to FLD-28; NMI-1 to NMI-46) — 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, NMI-7, NMI-8); the supporting row and the error (FLD-7 to FLD-9, FLD-26); the name, the description and the states (FLD-10, FLD-11, FLD-14, NMI-12, NMI-32); a text that is not a number shown as an error in the Field's row, in the input's words (FLD-28, NMI-21); and the two steppers, which are the number input's Buttons and stand inside its box (NMI-25).
- **NUM-48** WHERE the platform has forms (the web) THE number field SHALL be the one control the form sees: it SHALL take name, submit its number input's value as that input submits it — a decimal number with ASCII digits and a period, or an empty string WHILE it holds none (NMI-35) — reset to the value it was first given, restore it on navigation, report to the form's constraint validation exactly what its number input would report there (a missing value WHILE required is true and it holds none, NMI-12; a bad input WHILE an entry error lasts, NMI-21), and be left out WHILE disabled is true or a disabled group of the form holds it; its number input and its Field SHALL take no part in the form themselves. WHEN the action key asks for the form's submission (NMI-20) the form asked SHALL be the number field's own.
- **NUM-49** WHEN the number field is given focus — by the product, by a press on any part of it that FLD-12 or NMI-14 gives to the input, or by a form that reports its validity — THE number field SHALL pass the focus to its number input and SHALL add no stop to the focus order: it has one stop, its input, and the steppers are none (NMI-25). A press on a stepper SHALL step and move no focus, in the number field as in the bare input (NMI-26). WHILE focus is inside it THE number field SHALL count as focused for its Field (FLD-13).
- **NUM-50** IF the number field is placed in a Field THE number field SHALL in debug builds report that it is a field already and that the bare control is the number input, and both SHALL still render (FLD-15). WHILE it stands in a field group THE number field SHALL follow that group's disabled, through its own Field, and take nothing else from the group (FGR-14).
- **NUM-51** THE number field SHALL have no words of its own and SHALL read none: requiredText and optionalText are read by its Field (FLD-24), incrementLabel and decrementLabel by its number input (NMI-44), each from the instance's prop and then from the product's words.
- **NUM-52** 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 number 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 number field is invalid — except those the number field owns (aria-label, aria-labelledby, aria-disabled), which it SHALL move and not expose: its name is label (NUM-47). 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 number field SHALL take it off that element. WHEN the product sets an aria- attribute the number field owns THE number field SHALL report it in debug builds.

### Tokens

As written in the token documents (DTCG): an alias in braces names the token it takes its value from, which each design system resolves. On the web each token is a CSS custom property: `--tanrei` and the name after `tanrei`, joined by hyphens (`tanrei.comp.field.…` → `--tanrei-comp-field-…`).

#### `tanrei.comp.field`

| Token | Type | Value |
| --- | --- | --- |
| `comp.field.label.typescale` | `typography` | `{tanrei.sys.typescale.label}` |
| `comp.field.label.gap` | `dimension` | `{tanrei.sys.space.space100}` |
| `comp.field.label-icon.size` | `dimension` | `{tanrei.sys.icon.small}` |
| `comp.field.label-icon.gap` | `dimension` | `{tanrei.sys.space.space100}` |
| `comp.field.requirement.mark` | `number` | `{tanrei.sys.behavior.requirement-mark}` |
| `comp.field.requirement.gap` | `dimension` | `{tanrei.sys.space.space100}` |
| `comp.field.requirement.asterisk-gap` | `dimension` | `{tanrei.sys.space.space25}` |
| `comp.field.supporting-text.typescale` | `typography` | `{tanrei.sys.typescale.label-small}` |
| `comp.field.supporting-text.gap` | `dimension` | `{tanrei.sys.space.space50}` |
| `comp.field.counter.gap` | `dimension` | `{tanrei.sys.space.space200}` |
| `comp.field.motion.state-duration` | `duration` | `{tanrei.sys.motion.role.state.default}` |
| `comp.field.motion.state-easing` | `cubicBezier` | `{tanrei.sys.motion.easing.state}` |
| `comp.field.standard.label.color` | `color` | `{tanrei.sys.color.on-surface}` |
| `comp.field.standard.label-icon.color` | `color` | `{tanrei.sys.color.on-surface-variant}` |
| `comp.field.standard.supporting-text.color` | `color` | `{tanrei.sys.color.on-surface-variant}` |
| `comp.field.standard.counter.color` | `color` | `{tanrei.sys.color.on-surface-variant}` |
| `comp.field.standard.required-asterisk.color` | `color` | `{tanrei.sys.color.primary}` |
| `comp.field.standard.error.label.color` | `color` | `{tanrei.sys.color.on-surface}` |
| `comp.field.standard.error.label-icon.color` | `color` | `{tanrei.sys.color.on-surface-variant}` |
| `comp.field.standard.error.supporting-text.color` | `color` | `{tanrei.sys.color.on-surface-variant}` |
| `comp.field.standard.error.counter.color` | `color` | `{tanrei.sys.color.on-surface-variant}` |
| `comp.field.standard.error.required-asterisk.color` | `color` | `{tanrei.sys.color.primary}` |
| `comp.field.standard.error.value-text.color` | `color` | `{tanrei.sys.color.on-surface-variant}` |
| `comp.field.standard.value-text.color` | `color` | `{tanrei.sys.color.on-surface-variant}` |
| `comp.field.standard.error-text.color` | `color` | `{tanrei.sys.color.error}` |
| `comp.field.value-text.typescale` | `typography` | `{tanrei.sys.typescale.label}` |
| `comp.field.value-text.gap` | `dimension` | `{tanrei.sys.space.space200}` |
| `comp.field.error-text.gap` | `dimension` | `{tanrei.sys.space.space50}` |
| `comp.field.error-text.placement` | `number` | `0` |

Per-state tokens, valued by the design system's pattern rules (not written by hand):

- `comp.field.<variant>.<state>.<property>` for the variants `standard`, the states `focused`, `disabled` and the properties `label.color`, `label-icon.color`, `supporting-text.color`, `required-asterisk.color`, `error.label.color`, `error.label-icon.color`, `error.supporting-text.color`, `error.required-asterisk.color`, `counter.color`, `error.counter.color`, `value-text.color`, `error.value-text.color`, `error-text.color`.

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

- جذر الظل (shadow root) في العنصر فيه عنصر `<tanrei-field>` بداخله عنصر `<tanrei-number-input>`. واستيراد حقل العدد يعرّف الاثنين.
- حقل العدد عنصر مرتبط بالنماذج (form-associated)، وهو عنصر التحكم الوحيد الذي يلقاه نموذجه. يأخذ `name`، ويرسل قيمته عددًا عشريًّا مجرَّدًا (`12.5`) أيًّا كان ما تعرضه الإعدادات المحلية. ويعود عند إعادة الضبط إلى قيمة خاصية HTML `value`، ويبلّغ النموذج بأن القيمة ناقصة ما دامت `required` وهو لا يحمل عددًا، وبأن الإدخال غير صالح ما دام نصه ليس عددًا.
- هو كتلة بعرض مكانه. وفي مكان لا يعطي عرضًا تجعله التسمية الطويلة أعرض من صندوقه: فأعطِه عرضًا هناك.
- الأجزاء هي أجزاء العضوين، بأسمائها: `label` و `label-icon` و `requirement-label` و `supporting-text` من الحقل؛ و `container` و `outline` و `active-indicator` و `input` و `prefix` و `suffix` و `stepper` من حقل إدخال العدد. والجزءان `label` و `requirement-label` يبلغان المرسوم من الاثنين أيًّا كان؛ أما `field-label` و `number-input-label` فيبلغان واحدًا. والعضوان هما الجزءان `field` و `number-input`.
- في الحدث `entryerror` تكون `detail.text` هي `invalidText` في حقل الإدخال، وتكون فارغة حيث لم يُعطَ نص. وأنواع التفاصيل (detail) هي أنواع حقل إدخال العدد: `TanreiNumberInputInputDetail` و `TanreiNumberInputEntryErrorDetail`.
- الخاصية `steppers` هي خاصية HTML المعكوسة `no-steppers`، والخاصية `readOnly` هي `readonly`.
- الحدث `input` من النوع CustomEvent ومعه `detail.value`. والحدثان `change` و `action` حدثان عاديان: اقرأ `value` من العنصر. وما لم يُلغَ الحدث `action` يُطلب من النموذج بعده أن يُرسل.
- من دون `locale` يقرأ الحقل أقرب خاصية `lang`، ثم لغة المتصفح.
- إلى جانب فاصلة الإعدادات المحلية، تُقرأ النقطة فاصلةً عشرية حيثما لا تكون النقطة فاصل المجموعات في الإعدادات المحلية.
- مفتاحا الصفحة يخطوان عشر خطوات على شبكة الخطوة نفسها، كما يفعل شريط التمرير: فبخطوة مقدارها 2 يعطي المفتاح Page Up من العدد 42 العدد 62، ثم 82.
- على iOS و iPadOS يطلب الحقل لوحة المفاتيح الكاملة ما دام يمكن أن يُكتب عدد سالب، لأن لوحة الأرقام العشرية هناك ليست فيها علامة الناقص.
- قبل أن يُعرَّف العنصر لا يكون له حجم. احجز الارتفاع.

## الإرشادات

### حقل عدد أم حقل نص أم شريط تمرير

| الجانب | حقل العدد | حقل النص | شريط التمرير |
| --- | --- | --- | --- |
| يحمل | عددًا | أي نص | عددًا ضمن مدى |
| طريقة الاختيار | الكتابة أو التدرّج | الكتابة | السحب |
| يصلح لـ | قيمة معروفة | أرقام ليست كمية | قيمة تُختار بالإحساس |

الرمز البريدي ورقم البطاقة ورقم الهاتف ورمز التحقق لمرة واحدة أرقام، لكنها ليست كميات: فلا أحد يضيف واحدًا إلى رمز بريدي. استخدم لها [حقل النص](https://tanrei.chnotchy.com/ar/components/text-field/).

### افعل

- اكتب تسمية تسمّي المعدود، وأبقِها مرئية في النموذج.
- ضع الوحدة في `suffixText`، وعلامة العملة في `prefixText`.
- أعطِ `valueText` حيث تُقرأ اللاحقة قراءة سيئة: «1.5 مرة» للعلامة `×`.
- اكتب `invalidText` بحيث يقول ما يُكتب: «أدخِل رقمًا.»
- عيِّن `maxFractionDigits` بالقيمة 0 للأعداد الصحيحة. فلا تكون في لوحة المفاتيح عندئذ فاصلة عشرية.
- أعطِ `incrementLabel` و `decrementLabel`، على الحقل أو مرة واحدة للمنتج كله بالدالة `setWords()`. لا يتضمن Tanrei أي كلمة: زر التدرّج الذي بلا اسم يُرسم مع ذلك ويغيّر العدد لمؤشر الإدخال، ويُحجب عن التقنيات المساعدة، حيث يغيّر الزر الدوّار العدد بنفسه.

### لا تفعل

- لا تستخدم حقل العدد لأرقام ليست كمية.
- لا تحفظ عند الحدث `input`. فهو يصدر عند كل ضغطة مفتاح؛ والحدث `change` هو الذي يحمل القيمة المعتمَدة.
- لا تنتظر من `min` و `max` أن تصحّحا قيمة عيّنتها أنت. فهما تنطبقان على ما يعتمده الشخص.
- لا تضع داخل الحقل عنصر تحكم لاختيار الوحدة. ضع [عنصر اختيار](https://tanrei.chnotchy.com/ar/components/select/) بجانبه.
- لا تضع حقل العدد داخل حقل. فهو حقل أصلًا؛ وعنصر التحكم الذي يؤطّره الحقل هو [حقل إدخال العدد](https://tanrei.chnotchy.com/ar/components/number-input/).
- لا تُخفِ تسمية حقل العدد لتضع الصندوق تحت تسمية من عندك. استخدم حقل إدخال العدد.

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

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

- حقل الإدخال زر دوّار (spin button). اسمه هو `label`، مرسومةً كانت أو مخفيّة، وليس النص النائب أبدًا.
- قيمته هي العدد المعتمَد، وحدّاه هما `min` و `max`.
- النص المساعد أو نص الخطأ المعروض هو وصفه، ومعه `optionalText` ما دام الحقل اختياريًّا.
- يُعرض على أنه غير صالح ما دامت `error` بالقيمة true أو ما دام نصه ليس عددًا، وعلى أنه مطلوب ما دامت `required` معيَّنة، وعلى أنه للقراءة فقط.
- الخطأ الذي يظهر والتركيز على الحقل يُعلَن مرة واحدة، بتهذيب، وكذلك النص الذي ليس عددًا.
- زرّا التدرّج زرّان تسمّيهما `decrementLabel` و `incrementLabel`؛ والزر الذي لم يسمِّه أحد مخفيّ عن التقنيات المساعدة. وهما خارج ترتيب التركيز، لأن مفاتيح الأسهم تغيّر العدد من حقل الإدخال؛ ومن يستكشف باللمس يجدهما مع ذلك.
- الضغط على زر تدرّج لا ينقل التركيز، فلا يُظهر لوحة المفاتيح التي على الشاشة.
- ما دام أسلوب الإدخال يركّب نصًّا (input-method composition)، لا يقرأ الحقل شيئًا ولا يعالج أي مفتاح.
- عجلة الفأرة لا تغيّر العدد أبدًا.
- مساحة اللمس للحقل تستوفي الحد الأدنى للهدف، وكل زر تدرّج هدف كامل.
- عند تكبير النص إلى 200% تلتفّ التسمية والمساعدة. والعدد يبقى في سطر واحد، ويُمرَّر.
- حيث لا يتّسع السطر للعدد وزرّي التدرّج جنبًا إلى جنب — عند تكبير النص إلى 200% في نافذة ضيقة، مع بادئة ولاحقة طويلة — ينتقل زرّا التدرّج إلى سطر خاص بهما تحت العدد، عند نهاية الصندوق. ولا يُخفيان أبدًا، لأنهما على شاشات اللمس الطريقة الوحيدة للتدرّج.
- في الألوان المفروضة (forced colors) يكتسب الحقل حدًّا، ويُعرف الخطأ بكلماته وبحالة عدم الصلاحية.
- في تخطيط من اليمين إلى اليسار ينعكس زرّا التدرّج والتسمية: يقف زرّا التدرّج عند الطرف الأيسر. والعدد ووحدته يُكتبان كما يكتبهما نظام كتابة الوحدة نفسه: الوحدة المكتوبة بأحرف أو علامات لاتينية بعد العدد، من اليسار إلى اليمين، والوحدة المكتوبة بنظام كتابة الصفحة عن يسار العدد. وما يُقرأ بصوت مسموع لا يتغيّر.

فجوات معروفة على الويب:

- يقرأ Chromium العدد بلا وحدته: فهو يأخذ نص القيمة من النص الذي في حقل الإدخال، ويتجاوز النص الذي يسمّيه الحقل. اذكر الوحدة في التسمية حيث تهمّ.
- قبل أن يُعرَّف العنصر لا يُرسم شيء.

### ما عليك فعله

- أعطِ كل حقل عدد `label`.
- اكتب `invalidText` على الحقل. وأعطِ `requiredText` و `optionalText` و `incrementLabel` و `decrementLabel` على الحقل، أو مرة واحدة للمنتج كله بالدالة `setWords()`. لا يتضمن Tanrei أي كلمة، والكلمة الناقصة يُبلَّغ عنها أثناء التطوير. انظر [كلمات المنتج](https://tanrei.chnotchy.com/ar/foundations/words/).
- تحقق من القيمة بنفسك، وعيِّن `error`، واكتب `errorText` بحيث يقول كيف يُصحَّح العدد.
- أعطِ شريط التمرير وحقل إدخال العدد الذي بجانبه الاسم نفسه.