Progress

Anatomia#

Instalacja#

$ pnpm dlx shadcn@latest add https://www.prfct.dev/r/progress.json

Użycie#

import { Progress, ProgressLabel, ProgressValue } from "@/components/ui/progress"

<Progress value={64}>
  <ProgressLabel>Uploading assets</ProgressLabel>
  <ProgressValue />
</Progress>

Progress sam renderuje tor i wskaźnik. Elementy potomne — zwykle etykieta i wartość — trafiają do wiersza nad paskiem.

Przykłady#

Rozmiary#

sm (4 px) mieści się w listach i komórkach tabel, default (6 px) pasuje do większości formularzy i kart, a lg (10 px) jest przeznaczony dla paska postępu, który jest głównym elementem widoku.

Stan nieokreślony#

Przekaż value={null}, gdy wiesz, że praca trwa, ale nie wiesz, ile jej zostało. Fragment paska przesuwa się wzdłuż toru, dopóki nie przełączysz go na określoną wartość.

Aktualizacje na żywo#

Wskaźnik animuje przejścia między wartościami z czasem trwania slow i krzywą standard, więc częste aktualizacje wyglądają jak płynny ruch, a nie skoki.

Przesyłanie plików#

W listach użyj rozmiaru sm, a etykietą niech będzie nazwa pliku. Gdy pozycja się zakończy, zastąp wartość potwierdzeniem, aby ukończone wiersze przestały przyciągać wzrok.

Własna wartość#

ProgressValue przyjmuje funkcję renderującą dla jednostek innych niż procent. Gdy zmieniasz widoczny format, przekaż technologiom wspomagającym te same słowa przez getAriaValueText.

<Progress
  value={7.2}
  max={10}
  getAriaValueText={() => "7.2 of 10 gigabytes used"}
>
  <ProgressLabel>Storage</ProgressLabel>
  <ProgressValue>{() => "7.2 GB of 10 GB"}</ProgressValue>
</Progress>

Wytyczne#

Kiedy używać#

• Do zadań, które trwają dłużej niż około sekundy i raportują mierzalny postęp: przesyłania, eksportu, importu, budowania.
• Do wielkości mierzonych względem limitu — miejsca na dane, licencji, przydziałów — gdy pasek jest wskaźnikiem poziomu, a nie zegarem.

Kiedy nie używać#

• Do krótkich lub niemierzalnych oczekiwań wewnątrz kontrolki — użyj Spinner albo stanu loading komponentu Button.
• Do treści, która wciąż się ładuje — użyj Skeleton, który zapowiada układ.
• Do kroków w procesie. Pasek postępu mierzy wykonaną pracę, a nie nawigację.

Skeleton, Spinner czy Progress?#

Bądź uczciwy#

Nigdy nie pozwól, by określony pasek utknął na 99% albo się cofnął. Jeśli nie potrafisz wiarygodnie oszacować postępu, użyj stanu nieokreślonego i opisz w etykiecie, co się dzieje.

Dostępność#

• Renderuje role="progressbar" z aria-valuemin, aria-valuemax i aria-valuenow. Stan nieokreślony pomija aria-valuenow — czytniki ekranu odczytują wtedy pasek jako zajęty.
• ProgressLabel jest powiązany z paskiem przez aria-labelledby. Gdy nie możesz pokazać etykiety, przekaż zamiast niej aria-label do Progress — pasek postępu zawsze musi mieć nazwę.
• aria-valuetext jest generowany ze sformatowanej wartości. Nadpisz go przez getAriaValueText za każdym razem, gdy widoczna wartość nie jest procentem.
• Paski postępu nie są regionami na żywo (live regions): czytniki ekranu odczytują wartość, gdy użytkownik do niej przejdzie, a nie przy każdej zmianie. Kamienie milowe — Przesyłanie zakończone — ogłaszaj przez Toast lub komunikat z role="status".
• Przy prefers-reduced-motion zmiany wartości i przesuwanie się paska w stanie nieokreślonym nie są animowane.

Dokumentacja API#

Progress#

Komponent główny. Renderuje <div> z twoimi elementami potomnymi, po których następują ProgressTrack i ProgressIndicator. Przyjmuje wszystkie propsy Progress.Root z Base UI.

ProgressLabel#

Dostępna nazwa paska. Renderuje <span>.

ProgressValue#

Wyświetla sformatowaną wartość wyrównaną do prawej. Renderuje <span>.

ProgressTrack i ProgressIndicator#

Progress renderuje je automatycznie. Są eksportowane na potrzeby własnych kompozycji — na przykład segmentowego miernika, który renderuje kilka wskaźników.