> ## Documentation Index
> Fetch the complete documentation index at: https://docs.twenty.com/llms.txt
> Use this file to discover all available pages before exploring further.

# حلقة التقدّم

> اعرض تقدماً مقاساً أو غير محدد في مؤشر دائري مدمج.

## نظرة عامة

يوفر `ProgressRing` مظهراً دائرياً لـ [التقدم](https://docs.twenty.com/ar/ui/primitives/feedback/progress.md). يتشارك النطاق المخصص للجذر، والقيمة الخالية، والتنسيق، ووضع التسميات، والخاصية الأصلية، والمرجع، وعقد العرض. تعرض العناصر الفرعية الاختيارية قيمة منسقة مسبقاً بجانب الحلقة.

**Light**

[مثال على حلقة التقدّم (light)](https://storybook.twenty.com/iframe.html?id=ui-feedback-progressring-progressring--display\&viewMode=story\&globals=colorScheme:light)

**Dark**

[مثال على حلقة التقدّم (dark)](https://storybook.twenty.com/iframe.html?id=ui-feedback-progressring-progressring--display\&viewMode=story\&globals=colorScheme:dark)

[Open in Storybook](https://storybook.twenty.com/?path=/story/ui-feedback-progressring-progressring--display)

## استخدام

وفّر القيمة الأولية المتحكَّم بها واسماً متاحاً. استخدم `aria-valuetext` عندما تشرح القيمة المنسقة التقدّم بوضوح أكبر من النسبة المئوية.

```tsx theme={null}
import { ProgressRing } from 'twenty-ui/primitives/feedback';

export const ImportProgress = () => (
  <ProgressRing
    value={600}
    max={1000}
    aria-label="Importing records"
    aria-valuetext="600 of 1,000 records"
  >
    600 / 1,000
  </ProgressRing>
);
```

استخدم `aria-labelledby` لربط الحلقة بتسمية مرئية موجودة، أو أنشئ `Progress.Label` كعنصر فرعي. لا توفر العناصر الفرعية المنسقة مسبقاً اسم الحلقة المتاح تلقائياً.

## التقدم والنطاقات المتحكَّم بها

يحسب التطبيق `value` وينسّق محتوى العرض. لا تجلب الحلقة البيانات، ولا تتقدم في التقدّم، ولا تحسب الحصص. القيمة الافتراضية لـ `min` هي `0`، والقيمة الافتراضية لـ `max` هي `100`. تُقيَّد القيم المحدودة ضمن النطاق للقيم الدلالية وهندسة القوس. يمتلئ القوس وفقاً للنسبة المئوية المطبّعة، بما في ذلك عندما يكون الحد الأدنى غير صفري.

**Light**

[تقدم دائري ضمن نطاق مخصص (light)](https://storybook.twenty.com/iframe.html?id=ui-feedback-progressring-progressring--custom-range\&viewMode=story\&globals=colorScheme:light)

**Dark**

[تقدم دائري ضمن نطاق مخصص (dark)](https://storybook.twenty.com/iframe.html?id=ui-feedback-progressring-progressring--custom-range\&viewMode=story\&globals=colorScheme:dark)

[Open in Storybook](https://storybook.twenty.com/?path=/story/ui-feedback-progressring-progressring--custom-range)

مرّر `value={null}` للتقدم غير المحدد. تحذف الحلقة `aria-valuenow` وتعرض قوساً غير محدد. تبقى القيم غير المحدودة غير محددة أيضاً؛ ولا تصبح صفراً أو اكتمالاً. يبقى محتوى العرض متحكَّماً به من التطبيق.

استخدم `locale` و`format` و`getAriaValueText` كما هو موضح في [التقدم](https://docs.twenty.com/ar/ui/primitives/feedback/progress.md). أنشئ `Progress.Value` لعرض القيمة المنسقة للجذر.

استخدم [ProgressBar](https://docs.twenty.com/ar/ui/primitives/feedback/progress-bar.md) للتقدم الأفقي أو [MetricRow](https://docs.twenty.com/ar/ui/components/data-display/metric-row.md) للحصول على تسمية وقيمة محاذاة.

## المظهر والتركيب

يعرض `size="md"` حلقة بحجم 16px؛ ويعرض `size="sm"` حلقة بحجم 14px. يستخدم كلاهما حدًا بعرض 2px ويملآن باتجاه عقارب الساعة بدءًا من الأعلى. يقبل `barColor` ألوان CSS، بما في ذلك متغيرات السمة. إن SVG زخرفي ومخفي عن واجهات برمجة تطبيقات إمكانية الوصول.

تتحرك تغييرات القيمة لمدة 300ms. تؤدي تفضيلات تقليل الحركة إلى تعطيل الانتقال والدوران غير المحدد. تستهدف السمات الأصلية و`className` و`style` و`ref` عنصر التقدّم الخارجي. يمكن لـ `className` و`style` تلقي حالة التقدم. يمكن لـ `render` استبدال الجذر مع الاحتفاظ بدلالاته.

## الإزاحة

**aria-label** `string`

Accessible name identifying the measured operation.

**aria-labelledby** `string`

ID of the visible label that names the operation.

**aria-valuetext** `string`

Human-readable progress value overriding the default formatted value.

**barColor** `string`

CSS color of the filled arc. Defaults to the blue theme color.

**children** `ReactNode`

Optional preformatted value or Progress parts displayed before the ring.

**className** `string | ((state: ProgressRootState) =\> string | undefined)`

Class applied to the progress root, or a callback receiving its status.

**format** `NumberFormatOptions`

Intl.NumberFormat options for the clamped numeric value. The default displays the normalized percentage.

**getAriaValueText** `((formattedValue: string, value: number | null) =\> string)`

Receives the formatted value and raw value, including null, and returns an accessible value description.

**locale** `LocalesArgument`

Locale or locale list used to format the value. Defaults to the runtime locale.

**max** `number` (default: 100)

Inclusive maximum. Defaults to 100.

**min** `number` (default: 0)

Inclusive minimum. Defaults to 0.

**ref** `Ref\<HTMLDivElement\>`

Ref to the root div, or the element composed through render.

**render** `ReactElement\<unknown, string | JSXElementConstructor\<any\>\> | ComponentRenderFn\<HTMLProps, ProgressRootState\>`

Composes the root with an element or render callback. Forward the supplied props and ref to retain progress semantics.

**size** `"md" | "sm"` (default: md)

Ring diameter: sm (14px) or md (16px). Defaults to md.

**style** `CSSProperties | ((state: ProgressRootState) =\> CSSProperties | undefined)`

Inline styles applied to the progress root, or a callback receiving its status.

**value** `number | null` *required*

Controlled value in the min/max range. Use null for indeterminate progress.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.