--- title: "مؤشر التحميل" description: "يبيّن أن انتظارًا قصيرًا مجهول الطول جارٍ، ضمن السطر أو فوق المحتوى." url: "https://tanrei.chnotchy.com/ar/components/loading-indicator/" last_updated: 2026-10-23T21:17:12.000Z --- # مؤشر التحميل > يبيّن أن انتظارًا قصيرًا مجهول الطول جارٍ، ضمن السطر أو فوق المحتوى. ## نظرة عامة > [!NOTE] > **مواصفة معدَّلة لم تصل بعد إلى كل المنصات** > > تصف هذه الصفحة مؤشر التحميل كما هو في المواصفة الآن: ينتظر قبل أن يُعرض، ثم يدخل. مكوّن الويب يفعل ذلك منذ الآن، وكذلك العروض التوضيحية التي تظهر بعد المهلة. أما SwiftUI و Compose و Flutter و React Native فموسومة أعلاه بأنها متأخرة: إلى أن تلحق، ترسم المؤشر وتعرضه للتقنيات المساعدة فور إدراجه، ولا تأخذ الخصائص الثلاث الجديدة، فعيّناتها أدناه لا تعرض إلا ما تقدّمه فعلًا. ### الاستخدام **Web** ```html
``` **React** ```tsx import { LoadingIndicator } from '@tanrei/react';
{loading ? : }
``` **SwiftUI** ```swift import Tanrei TanreiLoadingIndicator("جارٍ تحميل الرسائل") // فوق المحتوى، على حاويته المرتفعة الخاصة به. TanreiLoadingIndicator("جارٍ التحديث", size: .large, contained: true) ``` **Compose** ```kotlin import io.github.chnotchy.tanrei.components.TanreiContainedLoadingIndicator import io.github.chnotchy.tanrei.components.TanreiLoadingIndicator import io.github.chnotchy.tanrei.tokens.TanreiLoadingIndicatorSize TanreiLoadingIndicator(contentDescription = "جارٍ تحميل الرسائل") // الهيئة contained دالة composable ثانية لها المعاملات نفسها. TanreiContainedLoadingIndicator(contentDescription = "جارٍ التحديث", size = TanreiLoadingIndicatorSize.Large) ``` **Flutter** ```dart import 'package:tanrei/tanrei.dart'; const TanreiLoadingIndicator(semanticsLabel: 'جارٍ تحميل الرسائل'); const TanreiLoadingIndicator( semanticsLabel: 'جارٍ التحديث', size: TanreiLoadingIndicatorSize.large, contained: true, ); ``` **React Native** ```tsx import { LoadingIndicator } from '@tanrei/react-native'; ``` ## المواصفات - Category: Communication - Level: base - Listing: default - Page: https://tanrei.chnotchy.com/components/loading-indicator/ - Spec: https://github.com/chnotchy/tanrei/blob/main/specs/loading-indicator.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 ``, registered by importing `@tanrei/web` (or only its own module, `@tanrei/web/components/loading-indicator`). - React: `LoadingIndicator` from `@tanrei/react`. | Platform | Name | Status | | --- | --- | --- | | Web | `tanrei-loading-indicator` | lagging | | SwiftUI | `TanreiLoadingIndicator` | lagging | | Jetpack Compose | `TanreiLoadingIndicator` | lagging | | Flutter | `TanreiLoadingIndicator` | lagging | | React Native | `LoadingIndicator` | lagging | Names a platform gives in its own idiom: | Spec | Web | SwiftUI | Jetpack Compose | Flutter | React Native | | --- | --- | --- | --- | --- | --- | | `contained` (prop) | `contained` | `contained` | `TanreiContainedLoadingIndicator` | `contained` | `contained` | | `label` (prop) | `label` | `label` | `contentDescription` | `semanticsLabel` | `accessibilityLabel` | | `showDelay` (prop) | `showDelay` | `showDelay` | `showDelayMillis` | `showDelay` | `showDelay` | | `enterDuration` (prop) | `enterDuration` | `enterDuration` | `enterDurationMillis` | `enterDuration` | `enterDuration` | 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 - `indicator`: The moving mark: an arc a quarter of a circle long that turns. It has no track, because there is no value to read. - `container` (optional): A filled, raised circle behind the indicator, drawn only when contained, so the indicator can be seen over content. ### Props | Prop | Type | Default | Web attribute | Description | | --- | --- | --- | --- | --- | | `size` | `enum`: `small`, `medium`, `large` | `"medium"` | `size` | The indicator's box (16 / 24 / 40): small replaces an icon in a control, medium sits next to text, large fills an empty section. Contained, the container is 24 / 32 / 48. A design system may add values. | | `contained` | `boolean` | `false` | `contained` | Draws the indicator on a raised container of its own, for places where it floats over content (pull to refresh, over an image or a list). | | `label` | `string` | `""` | `label` | The accessible name: what is loading ("Loading messages"). Required: a moving mark alone is not a name. | | `showDelay` | `number` | — | `show-delay` | How long, in milliseconds, this indicator waits from the moment it is inserted before it is drawn and exposed to assistive technology; 0 shows it as it is inserted. Null takes comp.loading-indicator.motion.show-delay, the system's answer for every indicator. Set it only where one indicator needs another pace than the rest (a wait the product knows is never instant, a busy button that should answer the press at once). | | `entrance` | `enum`: `auto`, `fade`, `grow` | `"auto"` | `entrance` | How this indicator enters once its show delay has passed: fade eases it in, grow eases it in while it grows from its center. Auto takes comp.loading-indicator.motion.entrance, the system's answer for every indicator. Under reduced motion grow enters as fade (LDG-13). | | `enterDuration` | `number` | — | `enter-duration` | How long, in milliseconds, this indicator's entrance lasts; 0 shows it whole at once. Null takes comp.loading-indicator.motion.enter-duration. | ### States `enabled` ### Accessibility - Role: `progressbar` - Labeling: label is the accessible name. The indicator has no value: once shown, it is exposed as a progressbar in the platform's busy (indeterminate) state, never as a status message; during its show delay it is not exposed at all (LDG-11). - Minimum target size: yes - Not interactive: the indicator takes no input and is never focusable (LDG-6), so the minimum target holds without extending anything. - comp.loading-indicator.indicator.color must stay at least 3:1 against the surface behind it, and comp.loading-indicator.contained.indicator.color against comp.loading-indicator.contained.container.color (non-text contrast): the moving mark is the only sign that something is happening. - Text size does not change the indicator: it is not text. Where it replaces an icon in a control, the control keeps its size. - A product marks the region it loads as busy (aria-busy on the web) and says when the content has arrived; a wait that may exceed a few seconds, or whose length can be measured, belongs to the progress indicator. - A wait shorter than the show delay shows and exposes nothing (LDG-11): no mark that flashes for a sighted person, and no progressbar that appears and vanishes for a screen-reader user. The product's own busy marking of the region does not wait for the delay; aria-busy and its equivalents announce nothing by themselves. - Reduced motion replaces the turning arc with an opacity pulse of at most one per second (LDG-4), below the three-per-second flash threshold, and turns a grow entrance into a fade (LDG-13). The show delay is kept: it is a wait, not motion (LDG-15). ### Behaviour Requirements in EARS form, each with its stable id. - **LDG-1** THE loading indicator SHALL draw, inside a comp.loading-indicator.indicator.size.medium square for medium (and so on for each size), an arc a quarter of the circle long with round caps and a stroke of comp.loading-indicator.indicator.thickness.medium for medium (and so on), whose outer edge touches the square, and SHALL turn it clockwise once per comp.loading-indicator.motion.cycle-duration at constant speed (sys.motion.easing.linear); it SHALL draw no track. - **LDG-2** WHILE contained is false THE loading indicator SHALL take exactly its indicator square, draw no container, and draw the arc in comp.loading-indicator.indicator.color. - **LDG-3** WHILE contained is true THE loading indicator SHALL draw a container of comp.loading-indicator.container.size.medium for medium (and so on for each size) with corners of comp.loading-indicator.container.shape, filled with comp.loading-indicator.contained.container.color and raised by comp.loading-indicator.contained.container.elevation, center the indicator in it, and draw the arc in comp.loading-indicator.contained.indicator.color. - **LDG-4** WHERE reduced motion is requested THE loading indicator SHALL NOT turn: it SHALL draw the whole circle at the indicator's size and stroke and ease its opacity from 1 to 0 and back to 1 once per comp.loading-indicator.motion.cycle-duration with sys.motion.easing.standard; a container, when contained, SHALL stay still and opaque. - **LDG-5** WHILE the loading indicator is shown (LDG-12) THE loading indicator SHALL expose the progressbar role to assistive technology with label as its name, no current value, and the platform's busy or indeterminate state. - **LDG-6** THE loading indicator SHALL NOT be focusable and SHALL NOT announce itself when it appears or disappears; the region being loaded is marked busy, and its completion announced, by the product. - **LDG-7** WHILE the loading indicator is not visible (scrolled out of view, in a hidden view, or in an app in the background) THE loading indicator SHALL NOT run its animation, and SHALL resume it when it becomes visible. - **LDG-8** WHERE the layout direction is right-to-left THE loading indicator SHALL NOT be mirrored: it turns clockwise in every direction. - **LDG-9** WHEN size names a value that the active design system does not have THE loading indicator SHALL render with the default value's tokens, and in debug builds report the unknown value. - **LDG-10** WHILE label is empty THE loading indicator SHALL still render, and in debug builds report that it has no accessible name. - **LDG-11** WHEN the loading indicator is inserted into a view THE loading indicator SHALL wait for its show delay (LDG-14) before it is shown, and WHILE it waits SHALL draw nothing (no indicator, no container, no shadow), SHALL run no animation, SHALL be absent from the accessibility tree (no role, no name, no busy state), and SHALL still take the box it takes when shown (LDG-2, LDG-3), so that nothing around it moves when it appears; a show delay of 0 SHALL show it as it is inserted. - **LDG-12** WHEN its show delay ends THE loading indicator SHALL be shown: it SHALL expose itself as LDG-5 says, without announcing itself (LDG-6), start its entrance (LDG-13), and start the turn of LDG-1, or the pulse of LDG-4, at the beginning of a cycle. - **LDG-13** WHEN the loading indicator is shown THE loading indicator SHALL enter over its enter duration (LDG-14) with comp.loading-indicator.motion.enter-easing, as its entrance names: fade SHALL ease the opacity of the whole component (the indicator and, when contained, the container and its shadow) from 0 to 1, and grow SHALL ease the opacity the same way while scaling the whole component from nothing to its full size about its center, on the same curve over the same time. The entrance SHALL be drawn only: the box SHALL keep its full size throughout, and the entrance SHALL run to its end whether or not the indicator is visible (LDG-7 pauses the cycle, not the entrance). An enter duration of 0 SHALL show the indicator whole at once. WHERE reduced motion is requested THE loading indicator SHALL NOT scale: grow SHALL enter as fade, and on a platform whose reduced-motion setting removes every animation (Android's) the indicator SHALL appear at once. - **LDG-14** THE loading indicator SHALL take its show delay from showDelay and its enter duration from enterDuration, each a number of milliseconds used as given (the motion dial does not scale it), and its kind of entrance from entrance. WHILE showDelay or enterDuration is null THE loading indicator SHALL use comp.loading-indicator.motion.show-delay or comp.loading-indicator.motion.enter-duration in its place, and WHILE entrance is auto it SHALL use comp.loading-indicator.motion.entrance; IF showDelay or enterDuration is negative or not a finite number, or entrance names a kind the indicator does not know, THE loading indicator SHALL use the token likewise and in debug builds report the value it ignored. - **LDG-15** THE loading indicator SHALL treat its show delay as a waiting time, not motion: WHERE motion is reduced it SHALL keep it, on every platform, including one whose reduced-motion setting removes every animation; and it SHALL keep counting it while the indicator cannot be seen (scrolled out of view, in a hidden view), because the delay measures the wait, not what is seen. - **LDG-16** WHEN the loading indicator is removed before its show delay ends THE loading indicator SHALL have drawn, exposed and announced nothing, and WHEN it is removed while shown, during its entrance included, it SHALL disappear at once. WHEN it is inserted again THE loading indicator SHALL wait its whole show delay again; hiding it without removing it (a hidden ancestor, scrolling) SHALL neither restart nor pause the delay (LDG-15). WHEN showDelay, entrance or enterDuration changes while the delay or the entrance is running THE loading indicator SHALL finish the running one as it started and use the new value from its next insertion. - **LDG-17** THE loading indicator SHALL take its layout direction from where it is used — the direction of the nearest ancestor that sets one, and the platform's own where none does — and SHALL have no direction setting of its own; WHEN that direction changes while the loading indicator is shown THE loading indicator SHALL draw itself for the new direction at once, without a motion of its own, keeping its place in its cycle. - **LDG-18** WHERE the platform has ARIA attributes (the web), the host carries its progressbar role (LDG-5) itself, so what the product writes on it is not moved, but for a name: WHILE label is not empty THE loading indicator SHALL hold the product's aria-label and aria-labelledby on that host as their data-aria- twins, so that label is its whole name although the platform gives aria-labelledby the precedence, and WHEN label is emptied SHALL give them back as they were written; WHILE label is empty a name the product gives so — aria-label, or aria-labelledby naming an element — SHALL be its name and SHALL NOT be reported as having none in debug builds (LDG-10). WHILE it waits to be shown (LDG-11) it has no role, and SHALL hold them as well, so that nothing names an element with no role, and give them back when it is shown. WHEN the product removes one, or its data-aria- twin, or sets the ARIA property that reflects it (ariaLabel, ariaLabelledByElements) to null, THE loading indicator SHALL take it away. ### 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.loading-indicator.…` → `--tanrei-comp-loading-indicator-…`). #### `tanrei.comp.loading-indicator` | Token | Type | Value | | --- | --- | --- | | `comp.loading-indicator.indicator.size.small` | `dimension` | `16px` | | `comp.loading-indicator.indicator.size.medium` | `dimension` | `24px` | | `comp.loading-indicator.indicator.size.large` | `dimension` | `40px` | | `comp.loading-indicator.indicator.thickness.small` | `dimension` | `{tanrei.sys.border.thick}` | | `comp.loading-indicator.indicator.thickness.medium` | `dimension` | `{tanrei.sys.border.thick}` | | `comp.loading-indicator.indicator.thickness.large` | `dimension` | `{tanrei.sys.border.thick}` | | `comp.loading-indicator.indicator.color` | `color` | `{tanrei.sys.color.on-surface-variant}` | | `comp.loading-indicator.container.size.small` | `dimension` | `24px` | | `comp.loading-indicator.container.size.medium` | `dimension` | `32px` | | `comp.loading-indicator.container.size.large` | `dimension` | `48px` | | `comp.loading-indicator.container.shape` | `dimension` | `{tanrei.sys.shape.corner.full}` | | `comp.loading-indicator.contained.container.color` | `color` | `{tanrei.sys.color.surface-container-lowest}` | | `comp.loading-indicator.contained.container.elevation` | `shadow` | `{tanrei.sys.elevation.level2}` | | `comp.loading-indicator.contained.indicator.color` | `color` | `{tanrei.sys.color.on-surface-variant}` | | `comp.loading-indicator.motion.cycle-duration` | `duration` | `{tanrei.sys.motion.duration.extra-long4}` | | `comp.loading-indicator.motion.show-delay` | `duration` | `{tanrei.sys.motion.role.show-delay}` | | `comp.loading-indicator.motion.entrance` | `number` | `0` | | `comp.loading-indicator.motion.enter-duration` | `duration` | `{tanrei.sys.motion.role.state.large}` | | `comp.loading-indicator.motion.enter-easing` | `cubicBezier` | `{tanrei.sys.motion.easing.enter}` | ## الإرشادات ### متى يُستخدم استخدم مؤشر التحميل لانتظار قصير لا تستطيع معرفة طوله: قائمة تجلب صفحتها التالية، عنصر تحكم يحفظ، معاينة تُرسم. يقول إن شيئًا يجري ولا يقول شيئًا عن المدة التي سيستغرقها. حين قد يدوم الانتظار أكثر من بضع ثوانٍ، أو حين تستطيع قياس ما أُنجز منه، استخدم [مؤشر التقدم](https://tanrei.chnotchy.com/ar/components/progress-indicator/) بدلًا منه. القيمة، ولو تقريبية، تجعل الانتظار الطويل أهون. ### اختيار الحجم | الحجم | المؤشر / الحاوية في النظام الافتراضي | يُستخدم لـ | | --- | --- | --- | | صغير (small) | 16 / 24 | مكان أيقونة في عنصر تحكم، كزر يحفظ. | | متوسط (medium) | 24 / 32 | بجانب سطر من النص. وهو الافتراضي. | | كبير (large) | 40 / 48 | قسم فارغ أو عرض كامل ينتظر محتواه. | ### داخل حاوية الهيئة contained ترسم المؤشر على دائرة مرتفعة خاصة به. استخدمها حيث يطفو المؤشر فوق المحتوى، كما في السحب للتحديث أو فوق صورة أو قائمة، ليبقى مرئيًّا أيًّا كان ما خلفه. وحيث يقع على سطح بسيط، اتركه ضمن السطر. ### مهلة العرض والدخول الانتظار الذي ينتهي في لحظة ينبغي ألّا يعرض شيئًا. لذلك ينتظر المؤشر قبل أن يُعرض: 300 ms في النظام الافتراضي، محسوبة من لحظة إدراجه. ثم يتدرّج في الظهور. والانتظار الأقصر من المهلة لا يعرض أبدًا علامة تومض ثم تختفي. وفي أثناء المهلة يأخذ المؤشر مقاسه الكامل منذ البداية، فلا يتحرك شيء بجانبه حين يظهر. أدرِج المؤشر حين يبدأ الانتظار وأزِله حين ينتهي. تُحسب المهلة من الإدراج: المؤشر الذي يُخفى ثم يُعرض من جديد من دون أن يُزال لا ينتظر مرة أخرى، والذي يُدرج من جديد ينتظر المهلة كلها مرة أخرى. يقرر النظام المهلة والدخول لكل مؤشر. ولا تعيّنهما على مؤشر واحد إلا حين يحتاج إلى إيقاع مختلف: - الخاصية `showDelay` هي مدة الانتظار بالميلي ثانية. القيمة `0` تعرض المؤشر فور إدراجه، لزر مشغول ينبغي أن يستجيب للضغط فورًا. - الخاصية `entrance` قيمتها `fade` أو `grow`. القيمة grow تُظهر المؤشر تدريجيًّا وهو يكبر من مركزه. والقيمة `auto`، وهي الافتراضية، تأخذ اختيار النظام. - الخاصية `enterDuration` هي طول الدخول بالميلي ثانية. القيمة `0` تعرض المؤشر كاملًا فورًا. القيمة التي تعيّنها تُستخدم كما هي: قرص ضبط الحركة لا يغيّر مقدارها. واترك الخاصية بلا تعيين لتأخذ قيمة النظام. ### افعل - أعطِه تسمية تقول ما الذي يُحمَّل: «جارٍ تحميل الرسائل»، لا «جارٍ التحميل». وإن عُرض بجانبه شرح فاستخدم الكلمات نفسها. - ضعه حيث سيظهر المحتوى، لينظر الشخص إلى الموضع الصحيح حين يصل. - حين يحلّ محل أيقونة في عنصر تحكم، أبقِ حجم عنصر التحكم، فلا يتحرك شيء من حوله. - اترك المهلة للنظام ما لم يحتج مؤشر واحد إلى إيقاع آخر. ### لا تفعل - لا تستخدمه لانتظار تستطيع قياسه، أو قد يطول. استخدم مؤشر التقدم. - لا تعرض عدة مؤشرات لانتظار واحد. يكفي واحد لكل منطقة تُحمَّل. - لا تضعه فوق شاشة كاملة حين يكون جزء واحد منها فقط قيد التحميل. أبقِ الباقي صالحًا للاستخدام. - لا تلوّنه لتقول إن خطأ وقع. أوقفه واعرض رسالة بدلًا من ذلك. - لا تُبقِ مؤشرًا في مكانه وتُخفِه بين انتظار وآخر. أزِله، ليبدأ الانتظار التالي مهلة جديدة. ## إمكانية الوصول ### ما يتكفل به المكوّن - بعد أن يُعرض، يعرض دور شريط التقدم (progress bar) في حالة الانشغال (busy) في المنصة، والتسمية اسمًا له وبلا قيمة. ليس في Flutter دور شريط تقدم ولا حالة انشغال بعد، فيعرض هناك التسمية. - في أثناء مهلة العرض لا يكون في شجرة إمكانية الوصول إطلاقًا: لا دور ولا اسم ولا حالة انشغال. الانتظار الأقصر من أن يُرى لا يُسمع كذلك. - لا يقبل التركيز أبدًا، ولا يُعلِن نفسه حين يظهر أو يزول. - حين يُطلب تقليل الحركة يتوقف القوس عن الدوران وتنبض عتامة دائرة كاملة برفق بدلًا من ذلك، مرة في الثانية على الأكثر؛ والحاوية تبقى ساكنة. ويصير الدخول بالتكبّر تدرّجًا في الظهور. وتبقى مهلة العرض: هي انتظار لا حركة. - تتوقف حركته ما دام لا يُرى، وتُستأنف حين يُرى: في تطبيق في الخلفية في كل مكان، وحين يُمرَّر خارج مجال الرؤية أو يكون على شاشة مخفيّة حيث تستطيع المنصة أن تعرف ذلك. - التسمية الفارغة يُبلَّغ عنها في بنيات التنقيح (debug). ### ما عليك فعله - علِّم المنطقة التي تُحمَّل بأنها مشغولة ما دامت تُحمَّل (`aria-busy` على الويب)، من بداية الانتظار ومن دون انتظار مهلة المؤشر، وقل متى وصل المحتوى: رسالة في منطقة حيّة (live region)، أو نقل التركيز إلى المحتوى الجديد حين يكون الشخص قد طلبه. - أبقِ لون المؤشر بتباين 3:1 على الأقل مقابل السطح الذي خلفه، ولون المؤشر داخل الحاوية مقابل حاويته، إن غيّرتهما. العلامة المتحركة هي الدليل الوحيد على أن شيئًا يجري.