> ## 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`. Используйте [ProgressBar](https://docs.twenty.com/ru/ui/primitives/feedback/progress-bar.md) или [ProgressRing](https://docs.twenty.com/ru/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 и ref по умолчанию |
| - | - |
| `Root` | Внешний `div` с семантикой индикатора выполнения |
| `Track` | `div` дорожки |
| `Indicator` | `div` заполнения |
| `Label` | `span` метки |
| `Значение` | `span` значения |

Каждая часть сохраняет нативные свойства, refs и установленный контракт композиции `render`. При замене элемента передавайте предоставленные свойства и ref. Обратные вызовы `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.