# Meter
## Кратко
`Meter` показывает ограниченное количественное значение, как правило без семантики прогресса во времени, свойственной индикатору выполнения. Это полоса описательного измерения для случаев, когда интерфейс должен читаться как уровень, оценка, ёмкость или качество, а не как выполнение задачи.
## Импорт
```tsx
import {
Meter,
MeterTrack,
type MeterProps,
type MeterSize,
type MeterVariant,
} from '@vega-ui/react';
```
## Экспортируемые типы
- `MeterProps`
- `MeterTrackProps`
- `MeterSize`
- `MeterVariant`
## Минимальная композиция
По умолчанию `max` равен `1`, поэтому дробному значению вроде `0.72` `max` не нужен; для любой другой шкалы передайте `max` (`value={36} max={50}`). Своей видимой подписи у индикатора нет: задайте `aria-label` или `aria-labelledby`.
```tsx
import { Meter, MeterTrack } from '@vega-ui/react';
export default function MinimalComposition() {
return (
);
}
```
## Обязательные части
- `Meter`: корневая поверхность индикатора
- `MeterTrack`: видимая дорожка заполнения
## Необязательные части
- Помимо корня и дорожки, других публичных частей нет
## Порядок композиции
1. `Meter`
2. `MeterTrack`
## Варианты
- Размеры: `sm`, `md`, `lg`
- Варианты: `primary`, `secondary`
- Состояния: нейтральное, хорошее, предупреждающее, плохое — через пороги
## Пограничные случаи
- `Meter` предназначен для ограниченного измерения, а не для асинхронного выполнения.
- Пропсы порогов, такие как `low`, `high` и `optimum`, могут менять семантическое цветовое состояние.
- Окружающий текст должен объяснять измеряемое значение и диапазон.
- Если измерение на самом деле складывается из нескольких значимых частей, `MeterStack` обычно понятнее одной сплошной полосы.
## Частые ошибки
- Использование `Meter` для загрузки или асинхронной работы.
- Значение без объяснения диапазона или смысла.
- Игнорирование семантики порогов, когда она важна для интерпретации.
## Примеры
### Базовый
#### Базовый: занятое хранилище с видимой сводкой
Индикатор на реальной шкале: `max` — лимит тарифа, поэтому `value` передаётся в гигабайтах, а не долей. Видимый заголовок задаёт доступное имя через `aria-labelledby`, а `valueText` повторяет понятную сводку для скринридера вместо голого числа.
```tsx
import { Meter, MeterTrack, Text } from '@vega-ui/react';
import { useId } from 'react';
export default function StorageUsage() {
const labelId = useId();
const usedGb = 36.2;
const limitGb = 50;
const summary = `${usedGb} GB of ${limitGb} GB used`;
return (
Cloud storage{summary}
);
}
```
### Контролируемый/с состоянием
#### Контролируемый/с состоянием: заряд батареи с пороговыми зонами
Уровнем владеет родитель и передаёт его в индикатор вместе с `low`, `high` и `optimum`. Дорожка сама становится красной, жёлтой или зелёной, а те же пороги формируют текстовый статус, связанный через `aria-describedby`. Так смысл не держится на одном цвете.
```tsx
import { Button, Meter, MeterTrack, Text } from '@vega-ui/react';
import { useId, useState } from 'react';
export default function BatteryLevel() {
const labelId = useId();
const statusId = useId();
const [level, setLevel] = useState(64);
let status = 'Battery is fine';
if (level < 20) {
status = 'Battery is low — connect the charger';
} else if (level > 80) {
status = 'Battery is almost full';
}
const discharge = () => setLevel(Math.max(level - 15, 0));
const charge = () => setLevel(Math.min(level + 15, 100));
return (
Headphones battery{level}%
{status}
);
}
```
### Форма/интеграция
#### Форма/интеграция: лимит символов под полем
Индикатор следит за длиной текста в `TextArea` внутри настоящей формы. `optimum={0}` делает короткий текст хорошей зоной, поэтому у лимита полоса желтеет, а на нём краснеет; `maxLength` держит жёсткое ограничение, а остаток символов связан с полем. Обработчик отправки читает значение через `FormData`, сброс очищает состояние.
```tsx
import { Button, HelperText, Label, Meter, MeterTrack, TextArea } from '@vega-ui/react';
import { FormEvent, useId, useState } from 'react';
export default function BioLengthMeter() {
const fieldId = useId();
const counterId = useId();
const limit = 160;
const [bio, setBio] = useState('Product designer in Lisbon. I write about design systems and accessible forms.');
const [saved, setSaved] = useState(null);
const left = limit - bio.length;
const handleSubmit = (event: FormEvent) => {
event.preventDefault();
const data = new FormData(event.currentTarget);
const value = String(data.get('bio'));
setSaved(`Saved, ${value.length} characters`);
};
const handleReset = () => {
setBio('');
setSaved(null);
};
return (