Кольцо прогресса
Кольцо прогресса показывает дугой, какая часть задачи выполнена на известной шкале. Оно только сообщает о ходе работы: на него нельзя перейти фокусом или нажать.
<tk-progress-ring value="72" show-value label="Uploading photos"></tk-progress-ring>
Анатомия
| Часть | Что это |
|---|---|
tk-progress-ring |
сам элемент; role="progressbar", фокуса не получает |
| дорожка | полный круг: вся шкала |
| дуга | выполненная часть, от 12 часов по часовой стрелке, со скруглёнными концами |
| значение в центре | число посередине, с show-value |
| слот по умолчанию | ваша подпись или статус рядом с кольцом |
Варианты
<tk-progress-ring value="40" show-value label="Sync"></tk-progress-ring> <tk-progress-ring value="100" intent="success" label="Sync">Synced</tk-progress-ring> <tk-progress-ring value="40" intent="error" label="Sync">Sync failed</tk-progress-ring>
accent(по умолчанию): обычный ход работы, в том числе на 100%.success: задача завершена, и текст об этом говорит.error: задача не удалась, и текст говорит, что пошло не так.
Всегда добавляйте к intent текст: одного цвета мало, его видят не все.
Размеры
<tk-progress-ring value="72" size="small" show-value label="Export"></tk-progress-ring> <tk-progress-ring value="72" show-value label="Export"></tk-progress-ring> <tk-progress-ring value="72" size="large" show-value label="Export"></tk-progress-ring> <tk-progress-ring value="72" size="xlarge" show-value label="Export"></tk-progress-ring>
size |
Диаметр | Толщина | Значение |
|---|---|---|---|
small |
24px | 2px | рядом с кольцом |
medium (по умолчанию) |
40px | 4px | в центре |
large |
64px | 4px | в центре |
xlarge |
96px | 8px | в центре |
На medium значение в центре набрано в 10px. Если его должны легко читать, возьмите
large или напишите значение текстом.
Значение
- Задайте
value; оно не выходит за пределыmin(0) иmax(100). Без значения кольцо рисуется пустым, а в консоли появляется предупреждение. show-valueпоказывает72%, сvalue-format="fraction"—18 of 25.- Текст из слота по умолчанию стоит рядом с кольцом.
Когда использовать
- Кольцо — когда доля известна, а места мало или оно квадратное, либо значение должно стоять в центре.
- В широком линейном месте, например в строке загрузки, берите
Progress bar . - Если ход работы измерить нельзя, нужен
Spinner . У кольца всегда есть значение, крутиться без конца оно не умеет.
Текст
- Назовите задачу в
label: «Загрузка фото», а не «Прогресс». - В статусе скажите, что произошло: «Синхронизировано», «Не удалось синхронизировать».
Можно / нельзя
| ✅ Можно | ❌ Нельзя |
|---|---|
| Кольцо, когда доля известна | Бесконечно крутящееся кольцо; для этого есть spinner |
| Для работы, которая продвигается | Для постоянной величины, например занятого места |
intent вместе с текстом |
Только цвет для успеха или ошибки |
| Тот же цвет дуги на 100% | Само собой зеленеть по завершении |
Связанные
Progress bar : то же значение полосой, есть неопределённый режим.Spinner : ожидание без шкалы.
API
Атрибуты
| Атрибут | Тип | По умолчанию | Что делает |
|---|---|---|---|
value |
number | не задан | место на шкале; обязателен |
min |
number | 0 |
начало шкалы |
max |
number | 100 |
конец шкалы |
intent |
accent | success | error |
accent |
цвет дуги; всегда с текстом |
show-value |
boolean | false |
показывает значение: в центре, а у small рядом |
value-format |
percent | fraction |
percent |
72% или 18 of 25 |
size |
small | medium | large | xlarge |
medium |
24, 40, 64 или 96px |
label |
string | не задан | доступное имя |
Слоты
| Слот | Содержимое |
|---|---|
| по умолчанию | подпись или статус рядом с кольцом; объявляется вежливо |
События
Нет.
Токены
| Часть | Токен |
|---|---|
| дорожка | surface/sunken |
| дуга | fill/accent, fill/success, fill/error |
| значение в центре | text/default, font-weight-semibold |
| значение рядом, текст слота | text/secondary, Label Small |
Значения по темам:
Доступность
Встроено:
role="progressbar"сaria-valuemin,aria-valuemax,aria-valuenowиaria-valuetext(текст значения).- Текст из слота лежит в вежливой 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 во всех темах.