Индикатор прогресса
Индикатор прогресса показывает, какая часть задачи выполнена на известной шкале. Он только сообщает о ходе работы: на него нельзя перейти фокусом или нажать.
<tk-progress-bar value="60" show-value label="Uploading report.pdf"></tk-progress-bar>
Анатомия
| Часть | Что это |
|---|---|
tk-progress-bar |
сам элемент; role="progressbar", фокуса не получает |
| дорожка | полоса во всю ширину: вся шкала |
| заполнение | выполненная часть, от начального края |
| значение | число рядом с дорожкой или над ней, с show-value |
| слот по умолчанию | ваша подпись или статус; заменяет значение |
Варианты
<tk-progress-bar value="60" show-value label="Import"></tk-progress-bar> <tk-progress-bar value="100" intent="success" label="Import">Import complete</tk-progress-bar> <tk-progress-bar value="40" intent="error" label="Import">Import failed. Try again.</tk-progress-bar>
accent(по умолчанию): обычный ход работы, в том числе на 100%.success: задача завершена, и текст об этом говорит.error: задача не удалась, и текст говорит, что пошло не так.
На 100% полоса сама не зеленеет. Задавайте intent сами и всегда добавляйте текст: одного
цвета мало, его видят не все.
Сегменты
segments делит дорожку на равные ячейки. Это только вид: значение остаётся непрерывным, у
ячеек нет подписей и по ним нельзя ходить с клавиатуры.
<tk-progress-bar value="3" max="5" segments="5" show-value value-format="fraction" label="Profile setup"></tk-progress-bar>
Размеры
<tk-progress-bar value="60" size="small" label="Uploading photos"></tk-progress-bar> <tk-progress-bar value="60" label="Uploading photos"></tk-progress-bar>
size |
Толщина |
|---|---|
small |
4px (space-4) |
medium (по умолчанию) |
8px (space-8) |
Состояния
<tk-progress-bar label="Loading messages"></tk-progress-bar>
- Определённое: задайте
value. Оно не выходит за пределыmin(0) иmax(100). - Неопределённое: не задавайте
value. По дорожке бежит отрезок, числа нет; подпись в слоте, например «Загружаем сообщения», показать можно.segmentsне действует.
Значение
<tk-progress-bar value="18" max="25" show-value value-format="fraction" label="Files uploaded"></tk-progress-bar> <tk-progress-bar value="72" show-value value-position="top" label="Exporting video"></tk-progress-bar>
show-valueпоказывает значение: по умолчанию72%, сvalue-format="fraction"—18 of 25.value-position="top"ставит его над дорожкой, по умолчанию оно рядом. На заполнении оно не бывает никогда.- Текст в слоте по умолчанию заменяет значение.
Когда использовать
- Индикатор прогресса — когда известен объём работы: загрузка, импорт, форма из нескольких шагов.
- Без значения — когда линейная задача идёт, но измерить её нельзя.
- В тесном или квадратном месте, или чтобы показать значение в центре, берите
Progress ring . - Для короткого ожидания без шкалы, например у кнопки или панели, есть
Spinner . - Не используйте его для пронумерованных шагов, между которыми переходит пользователь, и для статичных величин вроде занятого места на диске.
Текст
- Назовите задачу в
label: «Загрузка report.pdf», а не «Прогресс». - В статусе скажите, что происходит: «Загружено 18 из 25 файлов». При ошибке скажите, что не получилось и что делать.
Подробнее в
Можно / нельзя
| ✅ Можно | ❌ Нельзя |
|---|---|
intent вместе с текстом |
Только цвет для успеха или ошибки |
| Тот же цвет на 100% | Само собой зеленеть по завершении |
Без value, если измерить нельзя |
Выдуманное значение, чтобы выглядеть определённым |
| Spinner для короткого ожидания без шкалы | Неопределённый индикатор у кнопки |
| Значение рядом или сверху | Значение поверх заполнения |
| Сегменты, чтобы показать задачу равными частями | Пошаговый мастер из сегментов |
Связанные
Progress ring : то же значение в виде круга.Spinner : ожидание без шкалы.Skeleton : заглушка по форме загружаемого содержимого.
API
Атрибуты
| Атрибут | Тип | По умолчанию | Что делает |
|---|---|---|---|
value |
number | не задан | место на шкале; без него индикатор неопределённый |
min |
number | 0 |
начало шкалы |
max |
number | 100 |
конец шкалы |
intent |
accent | success | error |
accent |
цвет заполнения; всегда с текстом |
show-value |
boolean | false |
показывает значение |
value-format |
percent | fraction |
percent |
72% или 18 of 25 |
value-position |
end | top |
end |
значение рядом с дорожкой или над ней |
size |
small | medium |
medium |
толщина 4px или 8px |
segments |
number | 0 |
от 2 и больше делит дорожку на ячейки |
label |
string | не задан | доступное имя |
Слоты
| Слот | Содержимое |
|---|---|
| по умолчанию | подпись или статус; заменяет значение и объявляется вежливо |
События
Нет.
Токены
| Часть | Токен |
|---|---|
| дорожка | surface/sunken |
| заполнение | fill/accent, fill/success, fill/error |
| значение | text/secondary, Label Small (font-size-sm, font-weight-medium) |
| углы | radius-full у дорожки, заполнения и каждой ячейки |
Значения по темам:
Доступность
Встроено:
role="progressbar"сaria-valuemin,aria-valuemax,aria-valuenowиaria-valuetext(текст значения). У неопределённогоaria-valuenowнет.- Текст из слота лежит в вежливой live-области: статус или ошибка объявляются, а фокус остаётся на месте.
- Фокуса не получает и в порядок Tab не входит.
- При сокращённой анимации заполнение сразу встаёт на новое место, а бегущий отрезок замирает.
На вашей стороне:
- Дайте имя каждому индикатору через
label,aria-labelилиaria-labelledby. Без имени в консоли будет предупреждение. successиerror— только вместе с текстом.
Пределы контраста
- Заполнение
accentна фоне дорожки: не ниже 3:1 с основным цветом blue, indigo, purple и black. В светлой теме падает до 1.65–2.63:1 с orange, green, mint, teal, brown и gray; в контрастной — до 2.02–2.94:1 с orange, green, mint, teal и gray. В тёмной теме 3:1 держится с любым цветом. Где не хватает, включитеshow-valueили напишите значение текстом. - Заполнения
successиerror: не ниже 3.50:1 во всех темах.