> ## 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.

# التقدم

> أنشئ مكون تقدم متاحًا مع نطاق مشترك ودلالات للتسمية والقيمة.

## نظرة عامة

يكشف `Progress` عن أجزاء Base UI المثبتة: `Root` و`Track` و`Indicator` و`Label` و`Value`. استوردها من `twenty-ui/primitives/feedback`. استخدم [شريط التقدم](https://docs.twenty.com/ar/ui/primitives/feedback/progress-bar.md) أو [حلقة التقدم](https://docs.twenty.com/ar/ui/primitives/feedback/progress-ring.md) للحصول على مظهر ملائم مع العقد الدلالي نفسه.

**Light**

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

**Dark**

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

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

## استخدام

يمتلك `Root` القيمة المتحكَّم بها ودلالات شريط التقدم المتاح. يوفر `Label` اسمه المتاح. يعرض `Value` القيمة المنسقة. يصف `Track` و`Indicator` التعبئة المرئية؛ ويأتي عرض المؤشر من النطاق المطبع للجذر. لا تفرض الأجزاء مظهرًا.

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

export const ImportProgress = () => (
  <Progress.Root
    value={70}
    min={20}
    max={120}
    style={{
      display: 'grid',
      gridTemplateColumns: '1fr auto',
      alignItems: 'center',
      gap: 8,
      width: 320,
      maxWidth: '100%',
    }}
  >
    <Progress.Label render={<Text />}>Importing records</Progress.Label>
    <Progress.Value render={<Text />} />
    <Progress.Track
      style={{
        gridColumn: '1 / -1',
        height: 8,
        background: 'var(--t-background-tertiary)',
      }}
    >
      <Progress.Indicator
        style={{
          height: '100%',
          background: 'var(--t-font-color-primary)',
        }}
      />
    </Progress.Track>
  </Progress.Root>
);
```

يعرض هذا النطاق `50%` بينما تكون قيمة `aria-valuenow` هي `70`، وقيمة `aria-valuemin` هي `20`، وقيمة `aria-valuemax` هي `120`. يمتلك التطبيق الطلبات والتوقيت وتحديثات التقدم. لا توجد `defaultValue` ولا زيادة تلقائية.

## القيم والنطاقات والتقدم غير المحدد

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

مرّر `value={null}` عندما يكون مقدار التقدم غير معروف. يكون للجذر عندئذٍ حالة غير محددة، ويُغفل `aria-valuenow`، ويستخدم `indeterminate progress` كنص قيمة متاح افتراضيًا. تظل القيم غير المنتهية غير محددة أيضًا؛ ولا تُحوَّل إلى صفر. لا يحتوي `Indicator` الأولي على عرض نسبة مئوية محسوب في تلك الحالة، لذا يختار التركيب مظهره غير المحدد.

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

export const PendingImport = () => (
  <ProgressBar value={null} aria-label="Preparing the import" />
);
```

## التسميات والتنسيق

أنشئ `Progress.Label` داخل `Root`، أو عيّن `aria-label` أو `aria-labelledby` الأصليين. استخدم `aria-valuetext` لبديل قابل للقراءة البشرية عندما لا تكون النسبة المئوية كافية.

يعرض المنسق الافتراضي النسبة المئوية المطبعة. يحتفظ `locale` و`format` بعقد `Intl.NumberFormat` المثبت؛ ويقوم `format` الصريح بتنسيق القيمة الرقمية المقيّدة. تتلقى `getAriaValueText(formattedValue, value)` ذلك النص المنسق وقيمة التطبيق الأولية، بما في ذلك `null`. يغيّر نص القيمة المتاح دون تغيير التعبئة.

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

export const RecordCount = () => (
  <Progress.Root
    value={600}
    max={1000}
    format={{ style: 'decimal' }}
    getAriaValueText={(formattedValue) => `${formattedValue} of 1,000 records`}
  >
    <Progress.Label>Importing records</Progress.Label>
    <Progress.Value>
      {(formattedValue) => `${formattedValue} / 1,000`}
    </Progress.Value>
  </Progress.Root>
);
```

يتلقى `Progress.Value` كلًا من القيمة المنسقة والقيمة الأولية من خلال رد نداء الطفل الاختياري الخاص به. بالنسبة إلى التقدم غير المحدد، يتلقى رد النداء `indeterminate` كنص منسق؛ وبدون رد نداء، لا يعرض جزء القيمة أي محتوى. لا يصبح محتوى العرض تلقائيًا الاسم المتاح أو نص القيمة المتاح.

## الخصائص الأصلية والمراجع والتركيب

| الجزء | DOM الافتراضي وهدف المرجع |
| - | - |
| `Root` | عنصر `div` خارجي بدلالات شريط التقدم |
| `Track` | عنصر `div` للمسار |
| `Indicator` | عنصر `div` للتعبئة |
| `Label` | عنصر `span` للتسمية |
| `القيمة` | عنصر `span` للقيمة |

يحافظ كل جزء على الخصائص الأصلية والمراجع وعقد تركيب `render` المثبت. مرّر الخصائص والمرجع المزوَّدين عند استبدال عنصر. تتلقى ردود النداء `className` و`style` و`render` الحالة العامة مع `status`: `progressing` أو `complete` أو `indeterminate`. تجعل سمات الحالة الحالة نفسها متاحة للأنماط.

تصدّر نقطة الإدخال `ProgressStatus` وأنواع `Props` و`State` لكل جزء، بما في ذلك `ProgressRootProps` و`ProgressRootState` و`ProgressIndicatorProps` و`ProgressIndicatorState`. يمرر كل جزء معالجات الأحداث الأصلية. تمتلك التطبيقات تنسيق الميزات وردود نداء الإكمال.

## الخصائص

### Progress.Root

**Root.aria-label** `string`

Accessible name identifying the measured operation.

**Root.aria-labelledby** `string`

ID of the visible label that names the operation.

**Root.aria-valuetext** `string`

Human-readable progress value overriding the default formatted value.

**Root.children** `ReactNode`

Composed Progress parts and supporting content.

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

Class applied to this part, or a callback receiving its progress status.

**Root.format** `NumberFormatOptions`

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

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

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

**Root.locale** `LocalesArgument`

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

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

Inclusive maximum. Defaults to 100.

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

Inclusive minimum. Defaults to 0.

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

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

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

Composes this part with an element or render callback. Forward the supplied props and ref to the corresponding DOM element.

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

Inline styles applied to this part, or a callback receiving its progress status.

**Root.value** `number | null` *required*

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

### Progress.Track

**Track.children** `ReactNode`

The indicator and optional supporting content.

**Track.className** `string | ((state: ProgressTrackState) =\> string | undefined)`

Class applied to this part, or a callback receiving its progress status.

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

Ref to the track div, or the element composed through Track.render.

**Track.render** `ReactElement\<unknown, string | JSXElementConstructor\<any\>\> | ComponentRenderFn\<HTMLProps, ProgressTrackState\>`

Composes this part with an element or render callback. Forward the supplied props and ref to the corresponding DOM element.

**Track.style** `CSSProperties | ((state: ProgressTrackState) =\> CSSProperties | undefined)`

Inline styles applied to this part, or a callback receiving its progress status.

### Progress.Indicator

**Indicator.className** `string | ((state: ProgressIndicatorState) =\> string | undefined)`

Class applied to this part, or a callback receiving its progress status.

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

Ref to the indicator div, or the element composed through Indicator.render.

**Indicator.render** `ReactElement\<unknown, string | JSXElementConstructor\<any\>\> | ComponentRenderFn\<HTMLProps, ProgressIndicatorState\>`

Composes this part with an element or render callback. Forward the supplied props and ref to the corresponding DOM element.

**Indicator.style** `CSSProperties | ((state: ProgressIndicatorState) =\> CSSProperties | undefined)`

Inline styles applied to this part, or a callback receiving its progress status.

### Progress.Value

**Value.children** `((formattedValue: string | null, value: number | null) =\> ReactNode) | null`

Optional callback receiving the formatted value and raw value. Indeterminate progress passes indeterminate as formatted text. Without a callback, indeterminate progress displays no content.

**Value.className** `string | ((state: ProgressValueState) =\> string | undefined)`

Class applied to this part, or a callback receiving its progress status.

**Value.ref** `Ref\<HTMLSpanElement\>`

Ref to the value span, or the element composed through Value.render.

**Value.render** `ReactElement\<unknown, string | JSXElementConstructor\<any\>\> | ComponentRenderFn\<HTMLProps, ProgressValueState\>`

Composes this part with an element or render callback. Forward the supplied props and ref to the corresponding DOM element.

**Value.style** `CSSProperties | ((state: ProgressValueState) =\> CSSProperties | undefined)`

Inline styles applied to this part, or a callback receiving its progress status.

### Progress.Label

**Label.children** `ReactNode`

Visible text that supplies the accessible name of the root.

**Label.className** `string | ((state: ProgressLabelState) =\> string | undefined)`

Class applied to this part, or a callback receiving its progress status.

**Label.ref** `Ref\<HTMLSpanElement\>`

Ref to the label span, or the element composed through Label.render.

**Label.render** `ReactElement\<unknown, string | JSXElementConstructor\<any\>\> | ComponentRenderFn\<HTMLProps, ProgressLabelState\>`

Composes this part with an element or render callback. Forward the supplied props and ref to the corresponding DOM element.

**Label.style** `CSSProperties | ((state: ProgressLabelState) =\> CSSProperties | undefined)`

Inline styles applied to this part, or a callback receiving its progress status.


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