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

# عارض الأرقام المتحرّك

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

## نظرة عامة

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

تتبع أمثلة Web و React المواصفات الحالية. أما SwiftUI و Compose و Flutter و React Native فهي مخطَّطة: لا تتضمن عارض أرقام متحرّكًا بعد.

**Web**

```html
<tanrei-number-ticker value="1234" label="الطلبات"></tanrei-number-ticker>
<tanrei-number-ticker value="98400" number-style="currency" currency="USD" label="الإيرادات"></tanrei-number-ticker>

<!-- يرتفع رقم لوحة المعلومات من 0 في أول مرة يظهر فيها. -->
<tanrei-number-ticker start-value="0" value="0.426" number-style="percent" fraction-digits="1"></tanrei-number-ticker>

<!-- عدد يغيّره الشخص: يُعلَن مرة واحدة عند استقرار كل تغيير. -->
<tanrei-number-ticker value="2" live="polite" label="العناصر في السلة"></tanrei-number-ticker>

<script type="module">
  import '@tanrei/web/components/number-ticker';
  const ticker = document.querySelector('tanrei-number-ticker');
  ticker.value = orders.length;
  ticker.addEventListener('settle', (event) => console.log('now showing', event.detail.value));
</script>
```

**React**

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

<NumberTicker value={orders.length} label="الطلبات" />
<NumberTicker value={revenue} numberStyle="currency" currency="USD" label="الإيرادات" />
<NumberTicker startValue={0} value={0.426} numberStyle="percent" fractionDigits={1} />
<NumberTicker value={count} live="polite" label="العناصر في السلة" onSettle={(event) => setShown(event.detail.value)} />
```

## المواصفات

- Category: Communication
- Level: base
- Listing: default
- Page: https://tanrei.chnotchy.com/components/number-ticker/
- Spec: https://github.com/chnotchy/tanrei/blob/main/specs/number-ticker.spec.json

### Availability

| Design system | Has it | Notes |
| --- | --- | --- |
| Tanrei (`tanrei`) | Yes | — |
| 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-ticker>`, registered by importing `@tanrei/web` (or only its own module, `@tanrei/web/components/number-ticker`).
- React: `NumberTicker` from `@tanrei/react`.

| Platform | Name | Status |
| --- | --- | --- |
| Web | `tanrei-number-ticker` | alpha |
| SwiftUI | `TanreiNumberTicker` | planned |
| Jetpack Compose | `TanreiNumberTicker` | planned |
| Flutter | `TanreiNumberTicker` | planned |
| React Native | `NumberTicker` | planned |

Names a platform gives in its own idiom:

| Spec | Web | SwiftUI | Jetpack Compose | Flutter | React Native |
| --- | --- | --- | --- | --- | --- |
| `style` (prop) | `numberStyle` | `format` | `format` | `format` | `format` |
| `currency` (prop) | `currency` | `format` | `format` | `format` | `format` |
| `unit` (prop) | `unit` | `format` | `format` | `format` | `format` |
| `notation` (prop) | `notation` | `format` | `format` | `format` | `format` |
| `fractionDigits` (prop) | `fractionDigits` | `format` | `format` | `format` | `format` |
| `signDisplay` (prop) | `signDisplay` | `format` | `format` | `format` | `format` |
| `settle` (event) | `settle` | `onSettle` | `onSettle` | `onSettle` | `onSettle` |

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

- `number`: The formatted number, laid out as text in the style of where it stands: every digit in a column of its own, every other character (a sign, a separator, a currency, a unit, a compact suffix) as plain text between them.
- `digit`: One digit's place: a window one digit high showing one digit of a column of the digits 0 to 9 stacked from top to bottom, which moves through the window to show another.
- `text`: The label and the formatted value as one text for assistive technology, not drawn.

### Props

| Prop | Type | Default | Web attribute | Description |
| --- | --- | --- | --- | --- |
| `value` | `number` | `0` | `value` | The number shown. |
| `style` | `enum`: `decimal`, `percent`, `currency`, `unit` | `"decimal"` | — | How the number is written, by the platform's number formatter. percent multiplies by 100 and adds the locale's percent sign; currency writes it as an amount of currency; unit with the unit unit names. |
| `currency` | `string` | `""` | `currency` | The currency while style is currency, as its three-letter code ("JPY", "EUR"). Not words: the formatter writes the locale's symbol. |
| `unit` | `string` | `""` | `unit` | The unit while style is unit, as the formatter's identifier of a unit ("kilometer-per-hour", "megabyte"). Not words: the formatter writes the locale's form. |
| `notation` | `enum`: `standard`, `compact` | `"standard"` | `notation` | standard writes every digit; compact writes the number short with the locale's suffix (1.2K, 1.2万). |
| `fractionDigits` | `number` | — | `fraction-digits` | How many digits after the decimal separator are always written. Null leaves it to the formatter for the style (none for a whole decimal, the currency's own for currency). |
| `signDisplay` | `enum`: `auto`, `always`, `except-zero` | `"auto"` | `sign-display` | When a sign is written: auto for a negative number only; always for every number; except-zero for every number but zero (a change: +12, −3, 0). |
| `locale` | `string` | `""` | `locale` | The language the number is written in, as a language tag ("ja-JP", "ar-EG"). Empty takes the language of where the ticker stands, and the platform's where none is set. |
| `trend` | `enum`: `auto`, `up`, `down`, `digit` | `"auto"` | `trend` | Which way the digits move. auto: every changed digit moves the way the whole number moved — up when it grew, down when it shrank — so that 19 to 20 moves both digits up. up and down force one way. digit: each digit moves the way its own value moved, so that 19 to 20 moves the ones down from 9 to 0. |
| `animation` | `enum`: `auto`, `slide`, `blur`, `blur-slide`, `flip`, `none` | `"auto"` | `animation` | How a digit changes. slide: its column moves through the window. blur: the old digit blurs out as the new one sharpens in. blur-slide: both, the new one coming from the side the digit moves from. flip: the upper half of the old digit turns down over the lower half, as a split-flap board. none: at once. auto takes comp.number-ticker.animation, the design system's answer (slide in the default system). |
| `startValue` | `number` | — | `start-value` | A value to move from the first time the ticker comes into view (a dashboard's figures rising to their values). Null draws the first value at once. |
| `duration` | `number` | — | `duration` | How long a change takes, in milliseconds. Null takes comp.number-ticker.motion.duration. |
| `live` | `enum`: `off`, `polite` | `"off"` | `live` | Whether assistive technology is told each new value as it settles. off for a number that is not the point of the moment (most figures); polite for one a person waits for (a counter they are changing, a result arriving). |
| `label` | `string` | `""` | `label` | Words read before the value ("Revenue"), where nothing visible beside the number already says what it is. Never drawn. |

### Events

| Event | Description |
| --- | --- |
| `settle` | The digits came to rest at value: once at the end of each change's motion (at once where there is none). Carries value. |

### States

`enabled`

### Accessibility

- Role: `none (text)`
- Labeling: Read as one text: label, then the number as the formatter writes it. The drawn digits are hidden. With live polite, the settled value is told once per change.
- Minimum target size: yes

- Not interactive: no focus, no input, no target; minimumTarget holds trivially.
- Live regions: a number that is not the point of the moment is told nothing (off); one a person waits for is told politely once it settles, never each value it passes through.
- Pause, Stop, Hide (WCAG 2.2.2): one change's motion ends well within five seconds. A number the product updates by itself, again and again, alongside other content is auto-updating content: the product gives the means to pause the updates, or to set how often they come.
- Animation from interactions (WCAG 2.3.3): where motion is reduced, the number changes at once (NTK-7).

### Behaviour

Requirements in EARS form, each with its stable id.

- **NTK-1** THE number ticker SHALL write value with the platform's number formatter in locale (the language of where it stands while locale is empty), with style, currency, unit, notation, fractionDigits and signDisplay, SHALL draw every digit of the result — in the locale's own digits — in a digit place of its own, in tabular figures of the font of where it stands so that every digit is as wide as every other, and every other character the formatter writes as plain text in that font; it SHALL lay the number out inline, in the text style, color and direction of where it stands, as one run isolated from the text around it, and SHALL draw no fill, edge or color of its own.
- **NTK-2** THE number ticker SHALL draw each digit place as a window one line high that shows one digit of a column of the locale's digits 0 to 9 stacked from top to bottom, clipped to the window, so that a greater digit lies lower in the column; to show a digit the column SHALL stand with that digit in the window.
- **NTK-3** WHEN value changes while animation is slide THE number ticker SHALL move the column of every digit place whose digit changes from the old digit to the new one: WHILE trend is digit, down the column toward a greater digit (the column moving up through the window, the new digit rising from below) and up it toward a lesser one; WHILE trend is auto, every changed digit in the direction the whole number moved — toward the greater digits when value grew and toward the lesser when it shrank — going on past 9 to 0 (or back past 0 to 9) where the new digit lies the other way, so that 19 to 20 moves the ones one step on from 9 to 0 and the tens one step on from 1 to 2; WHILE trend is up or down, every changed digit in that direction as auto does for a number that grew or shrank. Each column SHALL move over the change's duration (duration, or comp.number-ticker.motion.duration while it is null) with comp.number-ticker.motion.easing, each digit place, from the most significant to the least, starting comp.number-ticker.motion.stagger after the one before it.
- **NTK-4** WHEN value changes while animation is blur THE number ticker SHALL cross-fade each changed digit over the change's duration, the old digit blurring from none to comp.number-ticker.blur.radius as it fades out and the new one sharpening from that radius to none as it fades in; WHILE animation is blur-slide it SHALL do the same while moving the old digit out and the new one in by comp.number-ticker.blur-slide.distance in the direction slide would (NTK-3); WHILE animation is flip it SHALL turn the upper half of the old digit down about the digit's middle over the lower half, showing the upper half of the new digit behind it and then its lower half, as a split-flap board, over the change's duration with comp.number-ticker.motion.easing.
- **NTK-5** WHEN the formatted number gains or loses characters (99 to 100, 999 to 1,000, a sign that appears) THE number ticker SHALL move its width to the new one with the digits' motion, keeping its end edge still WHILE it is aligned to the end of where it stands and its start edge still otherwise; a digit place that appears SHALL slide in with its column from the side the change moves from and fade in, one that goes SHALL slide out the other way and fade out, and a character that is not a digit SHALL fade in or out in its place.
- **NTK-6** WHEN value changes again before a change's motion has ended THE number ticker SHALL move every digit place from where it is drawn at that moment to the new digit, by the rule of NTK-3 for the new change, and SHALL never jump to a digit first; the change's duration SHALL start again from that moment.
- **NTK-7** WHERE motion is reduced, or WHILE animation is none, THE number ticker SHALL show the new number at once, its width included — cross-fading the old number to the new one over comp.number-ticker.motion.reduced-duration where motion is reduced and the platform can fade — and SHALL emit settle at once.
- **NTK-8** WHEN the ticker first comes into view WHILE startValue is not null THE number ticker SHALL draw startValue and move to value as a change of NTK-3 and NTK-4, once; WHILE startValue is null, and on every later first drawing, it SHALL draw value at once without a motion.
- **NTK-9** THE number ticker SHALL expose to assistive technology one text — label where it is not empty, then the number written as NTK-1 says — and SHALL hide every drawn digit, column and character from it, so that the number is read once, as written, and never digit by digit or as the digits passing through the windows; the text SHALL be the current value, in place, read where the ticker stands — WHILE live is polite, the value of the last change that settled (NTK-10).
- **NTK-10** WHILE live is polite THE number ticker SHALL tell assistive technology the text of NTK-9, politely and without moving focus, once WHEN a change's motion ends — the text itself changing only then, so that what a region holds is what it says — and SHALL tell it no value in between, nor any value of a change that a later change replaced before it ended; WHILE live is off it SHALL tell it nothing by itself.
- **NTK-11** WHEN the digits come to rest at value THE number ticker SHALL emit settle once with value; a change that a later change replaces before its end SHALL emit none.
- **NTK-12** IF value is not a finite number THE number ticker SHALL draw what the formatter writes for it (the locale's sign for infinity, or its word for a value that is not a number) as plain text at once, without a motion, and in debug builds report it; IF style is currency and currency is not a code the formatter knows, or style is unit and unit is not a unit it knows, THE number ticker SHALL write the number as decimal and in debug builds report the value.
- **NTK-13** WHERE the layout direction is right-to-left THE number ticker SHALL lay out the number as the formatter writes it for its locale — digits in the order the locale writes them, which is left to right in every locale, isolated from the text around it — and SHALL move its columns up and down as in a left-to-right layout; only the side it stands at and the edge NTK-5 keeps still follow the direction.
- **NTK-14** THE number ticker SHALL take its layout direction and its language from where it is used — the nearest ancestor that sets one, and the platform's own where none does — and SHALL have no direction setting of its own; WHEN either changes while the ticker is shown THE number ticker SHALL write and draw the number for the new one at once, without a motion.
- **NTK-15** WHILE the text size is enlarged THE number ticker SHALL grow with the text it stands in, its windows a line of the larger text high and its motion's distances with them.
- **NTK-16** WHEN animation names a value the active design system does not have, or trend, style, notation, signDisplay or live a value the component does not define, THE number ticker SHALL use the default value (auto, decimal, standard, auto, off) and in debug builds report the unknown value; WHEN duration is not a positive number, or fractionDigits not a whole number from 0 to 100, THE number ticker SHALL treat it as null and in debug builds report it.
- **NTK-17** THE number ticker SHALL have no words of its own and SHALL read none of the product's words: label is about this one number, and every sign, separator, symbol and suffix is the platform's formatter's, in the locale.

### 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.number-ticker.…` → `--tanrei-comp-number-ticker-…`).

#### `tanrei.comp.number-ticker`

| Token | Type | Value |
| --- | --- | --- |
| `comp.number-ticker.animation` | `number` | `0` |
| `comp.number-ticker.motion.duration` | `duration` | `{tanrei.sys.motion.role.resize.large}` |
| `comp.number-ticker.motion.easing` | `cubicBezier` | `{tanrei.sys.motion.easing.spatial}` |
| `comp.number-ticker.motion.stagger` | `duration` | `{tanrei.sys.motion.duration.short1}` |
| `comp.number-ticker.motion.reduced-duration` | `duration` | `{tanrei.sys.motion.role.reduced}` |
| `comp.number-ticker.blur.radius` | `dimension` | `{tanrei.sys.space.space100}` |
| `comp.number-ticker.blur-slide.distance` | `dimension` | `{tanrei.sys.space.space100}` |

## الإرشادات

### متى يُستخدم

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

الرقم الذي نادرًا ما يتغيّر، أو الذي لا يراه أحد وهو يتغيّر، نص عادي. والمستوى داخل مدى معروف — مثل التخزين المستخدم من حصة — هو [العدّاد](https://tanrei.chnotchy.com/ar/components/meter/). الأوقات والتواريخ ليست أرقامًا: اكتبها بتنسيق التاريخ والوقت في المنصة.

### كيف يُكتب الرقم

ليس للعارض كلمات ولا قواعد أرقام خاصة به. يكتب منسّق الأرقام في المنصة الرقم بلغة القارئ: فواصل المجموعات والفاصلة العشرية، ورمز العملة، وعلامة النسبة المئوية، والصيغة المختصرة للرقم الكبير (1.2K، 1.2万)، والأرقام نفسها (١٢٣٤ بالعربية كما تُكتب في مصر). اختر نمطًا (decimal أو percent أو currency أو unit)، ورمز عملة أو وحدة، والصيغة المختصرة، وعددًا ثابتًا من الخانات العشرية، ومتى تُكتب الإشارة؛ وإن لم تحدد لغة أخذ لغة المكان الذي يقع فيه.

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

### اختيار الحركة

| الحركة | تُستخدم لـ |
| --- | --- |
| Slide | معظم الأرقام. يدور عمود كل خانة متغيّرة حتى يصل إلى رقمها الجديد. اختيار النظام الافتراضي. |
| Blur | تغيير أهدأ: يتموّه الرقم القديم ويختفي بينما يتضح الجديد. |
| Blur slide | الشيء نفسه، مع تحرّك الأرقام مسافة قصيرة في اتجاه التغيير. |
| Flip | لوحة بأوراق قلّابة: مواعيد المغادرة، أو عدّ تنازلي، أو منتج ذو مظهر ميكانيكي. |
| None | رقم يجب أن يتغيّر فورًا. |

حافظ على حركة واحدة في منتجك كله: حدّدها مرة واحدة في نظام التصميم (`comp.number-ticker.animation`) بدلًا من تحديدها في كل عارض.

### اختيار trend

افتراضيًا تتحرك كل خانة متغيّرة في الاتجاه الذي تحرّك فيه الرقم كله: إلى الأعلى إن زاد وإلى الأسفل إن نقص، فمن 19 إلى 20 ترتفع الخانتان معًا. هكذا يُقرأ تغييرًا واحدًا لرقم واحد. اختر `digit` حين يكون لكل خانة معنى في ذاتها — عندها تتحرك كل خانة وفق تغييرها هي، فتنزل خانة الآحاد من 9 إلى 0. أما `up` و `down` فيثبّتان اتجاهًا واحدًا، لرقم لا يعدّ إلا في اتجاه واحد.

### افعل

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

### لا تفعل

- لا تلوّن الارتفاع بالأخضر ولا الانخفاض بالأحمر عبر العارض: ليست لديه هذه الألوان. إن كان للتغيير معنى فقُله بجوار الرقم — وسم، أو كلمة، أو سهم بتسمية.
- لا تحدّث رقمًا مرات عدة في الثانية. يستغرق كل تغيير مدة الحركة؛ وسيل التغييرات يُقرأ ضجيجًا. حدّثه بإيقاع يستطيع الشخص متابعته.
- لا تستخدمه للوقت. خانات الساعة تعود إلى الصفر عند 59 لا عند 9.

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

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

- تقرأ التقنيات المساعدة نصًا واحدًا: التسمية، ثم الرقم كما يكتبه المنسّق. الخانات المرسومة مخفية، فلا يُقرأ الرقم خانة خانة أبدًا، ولا كأرقام تمرّ عبر نوافذها.
- افتراضيًا لا يُعلَن شيء: معظم الأرقام ليست محور اللحظة. ومع ضبط live على polite يُعلَن الرقم بلطف مرة واحدة عند استقرار كل تغيير، ولا تُعلَن أبدًا قيمة يمرّ بها، ولا قيمة حلّ محلها تغيير لاحق.
- عند طلب تقليل الحركة يظهر الرقم الجديد فورًا، ويتلاشى القديم لوقت قصير.
- يأخذ لغة المكان الذي يقع فيه واتجاهه، ويعيد كتابة الرقم فورًا عند تغيّر أي منهما.
- يُبلَّغ في إصدارات التصحيح عن قيمة غير معروفة لـ animation أو trend أو style أو notation أو sign display أو live، وعن duration غير موجبة، وعن عملة أو وحدة لا يعرفها المنسّق، وعن قيمة ليست رقمًا.

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

- إن كان منتجك يحدّث رقمًا من تلقاء نفسه مرة بعد مرة بجوار محتوى آخر، فقدّم طريقة لإيقاف التحديثات مؤقتًا أو لاختيار عدد مرات وصولها (WCAG 2.2.2 الإيقاف المؤقت والإيقاف والإخفاء).
- اشرح معنى التغيير بالكلمات حيث يهم. تُظهر الحركة أن الرقم تغيّر؛ ولا تقول إن كان ذلك جيدًا أم سيئًا.