Esikatselu
<Spinner />
Käyttötarkoitus
Käytä Spinner-komponenttia antamaan asiakkaalle palautetta tilanteissa, joissa käyttöliittymän tai sen osan
latautuminen/päivitys kestää yli sekunnin.
Käytettävyyden perusperiaatteisiin kuuluu käyttöliittymän nopea reagointi asiakkaan syötteisiin ja muihin tapahtumiin. Latausprosessia kuvaava Spinner-komponentin avulla asiakas saa reaaliaikaisen vahvistuksen siitä, että tietty toiminto edistyy.
Spinner soveltuu pääsääntöisesti tilanteisiin, joissa latausaika on lyhyt eikä
sen tarkkaa kestoa tai edistymistä voida esittää. Latausindikaattori esitetään ensisijaisesti sinisävyisenä.
Tummilla taustoilla voi käyttää vaaleaa latausindikaattoria. Muut värit ovat erikoistapauksia tilanteisiin, joihin
sininen väri ei sovellu.
Kela Design Systemin ensisijainen tapa esittää asioiden latautumista on Skeleton-komponentti. Käytä Spinner-komponenttia tilanteisiin, joihin Skeleton ei sovellu.
- Käytä Spinner-komponenttia latausindikaattorina silloin, kun Skeleton-komponentti ei sovellu käyttötilanteeseen.
- Käytä komponenttia tilanteissa, joissa viiveen kesto on tuntematon.
- Käytä komponenttia latausindikaattorina tilanteissa, joissa tarvittava sisältö on jo näkyvissä.
- Älä käytä Spinneriä, jos viiveen kesto tai valmistumisaika on mahdollista esittää.
- Älä käytä komponenttiä sovelluksen käynnistyksen tai kokonaisten näkymien latausindikaattorina.
- Älä käytä saman lataustapahtuman esittämiseen samanaikaisesti sekä Spinner- että Skeleton-komponenttia.
Saavutettavuus
Hitaasti valmistuvan toiminnon suorituksesta pitää välittyä viesti myös ruudunlukijalle. Toteutustapa riippuu käyttötilanteesta.
Komponentille voi antaa vain ruudunlukijoille näkyvän tekstin srLoadingText-propilla.
Tilatietoa lataustapahtumasta voi myös välittää automaattisesti ruudunlukijoille
käyttämällä aria-live ja aria-atomic -attribuutteja tai role="status"-attribuuttia.
Näiden toteutus jää kunkin sovelluksen ja sen kehittäjien vastuulle.
Alla on kuvitteellinen ja interaktiivinen esimerkki latausindikaattorin käytöstä
toimintopainikkeen yhteydessä. Tässä esimerkissä ruudunlukija lukee asiakkaalle
automaattisesti vihjeen, kun hidasta toimintoa suoritetaan ja kun se on valmistunut.
const DemoButtons = () => {
const [isBusy, setIsBusy] = useState(false);
const [isFinished, setFinished] = useState(false);
const saveTimer = useRef();
// Clean timeout on unmount
useEffect(() => () => clearTimeout(saveTimer.current), []);
const onAction = () => {
clearTimeout(saveTimer.current);
setIsBusy(true);
setFinished(false);
saveTimer.current = setTimeout(() => onFinish(), Math.round(Math.random() * (4000 - 1000) + 1000));
};
const onCancel = () => {
setIsBusy(false);
setFinished(false);
};
const onFinish = () => {
setIsBusy(false);
setFinished(true);
};
return (
<>
<ButtonGroup horizontal="sm">
<Button disabled={isBusy} iconBefore={isBusy ? <Spinner /> : null} onClick={() => onAction()}>
Tallenna
</Button>
<Button disabled={isBusy} appearance="outline" onClick={() => onCancel()}>
Peruuta
</Button>
</ButtonGroup>
<div className="kds-mt-4">
<span>Ruudunlukija lukee automaattisesti: </span>
<div aria-live="assertive" aria-atomic="true" className="kds-inline-block">
{isBusy && <strong>Tallennus käynnissä</strong>}
{isFinished && <strong>Tallennus valmis</strong>}
</div>
</div>
</>
);
};
render(<DemoButtons />);
Esimerkit
Väri
Spinner-komponentti on toteutettu svg-kuvakkeena, joka on animoitu CSS:llä. Komponentti
perii oletuksena käyttökontekstin mukaisen tekstivärin.. Väriä voi lisäksi muuttaa variant- tai util-propeilla.
<div className="kds-flex kds-justify-around">
<Spinner srLoadingText="Tekstin värinen Spinner" />
<Spinner variant="primary" srLoadingText="Sininen Spinner" />
<Spinner variant="light" srLoadingText="Vaaleanharmaa Spinner" />
</div>
Koko
Komponentin koko periytyy kuvakkeiden tapaan käyttökontekstin tekstikoon mukaan.
Kokoa voi myös muokata size propin tarjoamilla kokovaihtoehdoilla, jotka vastaavat KDS:n kuvakekokoja.
<div className="kds-flex kds-justify-around kds-items-center">
<Spinner variant="primary" srLoadingText="Tekstin kokoinen Spinner" />
<Spinner variant="primary" size="sm" srLoadingText="Pieni Spinner" />
<Spinner variant="primary" size="md" srLoadingText="Keskikokoinen Spinner" />
<Spinner variant="primary" size="lg" srLoadingText="Iso Spinner" />
</div>
Spinnerin käyttö taulukossa
Esimerkki liitetiedostojen lähetyksestä FileInput-komponentin yhteydessä.
<Table>
<TableHead>
<TableHeadRow>
<TableHeader colSpan="2">Valitut liitteet</TableHeader>
</TableHeadRow>
</TableHead>
<TableBody>
<TableRow>
<TableCell>
<Link href="#">liitetiedosto-A.jpg</Link>
<small className="kds-text-muted kds-block">Liitettä lähetetään...</small>
</TableCell>
<TableCell align="numeric">
<Spinner variant="primary" size="sm" />
</TableCell>
</TableRow>
<TableRow>
<TableCell className="kds-flex kds-flex-col">
<Link href="#">liitetiedosto-B.jpg</Link>
<small className="kds-text-muted kds-block">Liitettä lähetetään...</small>
</TableCell>
<TableCell align="numeric">
<Spinner variant="primary" size="sm" />
</TableCell>
</TableRow>
<TableRow>
<TableCell className="kds-flex kds-flex-col">
<Link href="#">liitetiedosto-C.jpg</Link>
<small className="kds-text-muted kds-block">Liitettä lähetetään...</small>
</TableCell>
<TableCell align="numeric">
<Spinner variant="primary" size="sm" />
</TableCell>
</TableRow>
</TableBody>
</Table>
Spinnerin käyttö painikkeessa
Painikkeissa komponenttia tulee käyttää ilman variant-propia. Näin se saa automaattisesti
oikean värin painikkeen tekstivärin perusteella.
<>
<ButtonGroup horizontal="sm">
<Button iconBefore={<Spinner />}>Tallenna</Button>
<Button variant="danger" iconBefore={<Spinner />}>
Poista
</Button>
<Button appearance="outline" iconBefore={<Spinner />}>
Tallenna
</Button>
<Button variant="danger" appearance="outline" iconBefore={<Spinner />}>
Poista
</Button>
<Button appearance="ghost" iconBefore={<Spinner />}>
Peruuta
</Button>
</ButtonGroup>
<ButtonGroup horizontal="sm" className="mt-3">
<Button disabled iconBefore={<Spinner />}>
Tallenna
</Button>
<Button disabled appearance="outline" iconBefore={<Spinner />}>
Tallenna
</Button>
<Button disabled appearance="ghost" iconBefore={<Spinner />}>
Peruuta
</Button>
</ButtonGroup>
</>