Da li ste ikada razmišljali o tome da sve svoje komponente korisničkog interfejsa smestite na jedno centralizovano mesto unutar React aplikacije?
Ako ste tek počeli da se upoznajete sa React svetom, verovatno još niste imali priliku da o tome razmišljate.
Šta se tačno podrazumeva pod tim?
Pogledajte react-beautiful-dnd primere.
Ono što ste videli u ovim primerima nazivaju se „priče“ (stories). A alatka koja služi za kreiranje tih priča naziva se Storybook.
Sada verovatno imate bolju predstavu o čemu ćemo pričati u ovom članku. Bez daljeg odlaganja, hajde da istražimo.
Šta je Storybook?
Storybook je izolovano razvojno okruženje za korisnički interfejs koje obezbeđuje prostor za eksperimentisanje sa vašim komponentama. Možemo se „igrati“ sa našim komponentama na različite načine, bez pokretanja glavne aplikacije. Storybook se može pokrenuti na svom portu, sa sopstvenim podešavanjima.
Nije ograničen samo na React. Storybook je kompatibilan sa većinom frontend okvira, kao što su Vue, Angular, Mithril, Marko, Svelte, i mnogi drugi.
Više o Storybook-u možete pronaći ovde.
Šta je „priča“ (story)?
Priča definiše kako se komponenta prikazuje u određenom stanju. Uzmimo za primer uobičajenu komponentu; ona se može koristiti na različite načine, sa različitim rekvizitima (props). Za svako od tih stanja, možemo napisati po jednu priču.
Recimo da imamo komponentu dugmeta.
Dugme može postojati u raznim stanjima, kao što su onemogućeno, u stanju učitavanja, primarno, sekundarno, malo, veliko, srednje itd. Ako bismo naveli sva moguća stanja, vodič bi se otegao unedogled. Verujem da razumete. Više ćete shvatiti kada počnete da radite sa Storybook-om.
Možete videti kako se prikazuju priče dugmeta u različitim slučajevima (veliko, srednje, malo).
Podešavanje Storybook-a u projektu
Sada ćemo podesiti Storybook u React projektu.
Krenimo!
- Kreirajte novi React projekat pomoću sledeće komande. Naravno, možete dati projektu ime koje želite.
npx create-react-app storybook-demo
- Sada instalirajte Storybook u vaš projekat koristeći sledeću komandu.
npx sb init
Time smo završili podešavanje Storybook-a.
Storybook obezbeđuje poseban server za nas.
Kako da ga pokrenemo?
Storybook automatski dodaje komandu u našu `package.json` datoteku, u sekciju skripti. Možete je proveriti u datoteci `package.json`. Za sada, pokrenite sledeću komandu da biste pokrenuli Storybook server.
npm run storybook
Storybook će pokrenuti novi server na portu definisanom u `package.json` fajlu (isto kao React server). Automatski će otvoriti Storybook u vašem podrazumevanom pretraživaču.
Videćete različite „priče“ koje su već tu kao podrazumevane. Možete ih obrisati ako ne želite da ih koristite, ili ih ostaviti kao referencu. Kao što smo već pominjali, dugme može imati mnogo različitih stanja, i neka od njih ćete moći da vidite u Storybook-u (ne sva). U poslednjem delu ovog vodiča, napisaćemo veći broj priča za dugme.
Istražite različite delove Storybook-a i upoznajte se sa njegovim različitim sekcijama. U ovom tutorijalu, pokrićemo neke od njih.
Hajde da napišemo našu prvu priču.
Testiranje Storybook-a
Videli smo kako Storybook radi i neke primere u njemu.
- Kreirajte folder pod nazivom Button unutar src foldera.
- Kreirajte datoteke pod nazivom Button.jsx, Button.css i constants.js
- U odgovarajuće datoteke kopirajte kod koji se nalazi u nastavku.
Button.jsx
import React, { Component } from "react";
import PropTypes from "prop-types";
import "./Button.css";
import { buttonTypes, buttonVariants, buttonSizes } from "./constants";
class Button extends Component {
static defaultProps = {
isDisabled: false,
type: "filled",
variant: "oval",
size: "medium",
backgroundColor: "#1ea7fd",
textColor: "#ffffff",
};
static buttonTypes = buttonTypes;
static buttonVariants = buttonVariants;
static buttonSizes = buttonSizes;
renderButton = () => {
const {
text,
isDisabled,
type,
variant,
size,
backgroundColor,
textColor,
onClick,
} = this.props;
return (
);
};
render() {
return this.renderButton();
}
}
Button.propTypes = {
text: PropTypes.string,
isDisabled: PropTypes.bool,
type: PropTypes.oneOf([buttonTypes.outline, buttonTypes.filled]),
variant: PropTypes.oneOf([buttonVariants.oval, buttonVariants.rectangular]),
size: PropTypes.oneOf([
buttonSizes.small,
buttonSizes.medium,
buttonSizes.large,
]),
backgroundColor: PropTypes.string,
textColor: PropTypes.string,
onClick: PropTypes.func,
};
export { Button };
Button.css
.default {
border: none;
cursor: pointer;
background-color: transparent;
}
.default:focus {
outline: none;
}
.disabled {
opacity: 0.75;
cursor: not-allowed;
}
.small {
font-size: 12px;
padding: 4px 8px;
}
.medium {
font-size: 14px;
padding: 8px 12px;
}
.large {
font-size: 16px;
padding: 12px 16px;
}
.oval {
border-radius: 4px;
}
.rectangular {
border-radius: 0;
}
constants.js
export const buttonTypes = {
outline: "outline",
filled: "filled",
};
export const buttonVariants = {
oval: "oval",
rectangular: "rectangular",
};
export const buttonSizes = {
small: "small",
medium: "medium",
large: "large",
};
Šta ovaj kod radi?
Napisali smo generičku komponentu dugmeta koja se može koristiti na različite načine. Sada imamo komponentu koja može imati različita stanja.
Hajde da napišemo našu prvu priču, prateći korake u nastavku.
- Kreirajte fajl pod nazivom Button.stories.jsx
- Uvezite React i našu komponentu Button u datoteku.
- Sada definišite naslov (title) ili putanju (path) za naše priče o komponenti. Definisaćemo ga pomoću sledećeg koda.
export default {
title: ‘common/Button’,
}
Gornji kod će smestiti sve priče koje se nalaze u trenutnoj datoteci u `common/Button/` direktorijum.
- Izvezite dugme sa obaveznim rekvizitima na sledeći način.
export const defaultButton = () => (
Završili smo našu prvu priču. Pokrenite Storybook pomoću sledeće komande i pogledajte rezultat.
npm run storybook
Napisaćemo još priča, ne brinite.
Koliko je ovo korisno u Frontend razvoju?
Koja je glavna prednost korišćenja Storybook-a?
Recimo da radimo u timu od 10 članova. I moramo da proverimo sve uobičajene komponente koje su svi napisali za trenutni projekat.
Kako to možemo uraditi?
Morali bismo da idemo kroz svaku od tih uobičajenih komponenti da bismo ih proverili. Ali, to oduzima mnogo vremena i nije preferirani način. Tu nam na scenu stupa Storybook.
Kako možemo iskoristiti Storybook da rešimo ovaj problem?
Možemo da pišemo „priče“ za sve uobičajene komponente (bilo koje komponente korisničkog interfejsa) pomoću Storybook-a. I kad god neko od vaših kolega želi da proveri komponente koje su drugi napravili, jednostavno pokrenu Storybook server i videće sve komponente korisničkog interfejsa, kao što smo već videli.
Možemo uraditi mnogo više sa komponentama prikazanim u Storybook-u. Storybook ima koncept pod nazivom „Addons“ (dodaci) koji „daju supermoći“ našim pričama.
Na primer, ako moramo da proverimo odzivnost komponenti korisničkog interfejsa unutar samog Storybook-a, možemo koristiti dodatak pod nazivom „Viewport“. Više o dodacima ćemo saznati u sledećim delovima.
Rad sa Storybook-om
U ovom odeljku, napisaćemo različite „priče“ koje definišu različita stanja naše generičke komponente dugmeta.
Pisanje priča nije teško. Priča definiše stanje komponente. Ako dobro pogledate rekvizite (props) komponente, lako ćete razumeti različite slučajeve njene upotrebe.
Hajde da napišemo neke priče, dajući im opcione rekvizite.
export const largeButton = () => (
Gore navedene tri priče definišu različite slučajeve upotrebe naše komponente Button. Sada je na vama red da dodate još neke slučajeve priča za našu uobičajenu komponentu. Pokušajte da dodate `disabledSmallRectangularButton`, `dangerButton`, `successDisabledButton` itd.
Neću dati kod za gore navedene slučajeve. Sami ga morate napisati da biste ga razumeli. Možete videti kompletan kod priča koje smo do sada napisali.
import React from "react";
import { Button } from "./Button";
export default {
title: "src/common/Button",
};
export const defaultButton = () => (
Sada imate punu kontrolu nad pisanjem priča za komponentu.
Pređimo na sledeći odeljak gde ćemo učiti o dodacima (addons) i kako oni „poboljšavaju“ naše priče.
Storybook Addons
Po podrazumevanom, imamo nekoliko dostupnih dodataka. U ovom delu, istražićemo najkorisnije dodatke za naš razvoj.
Hajde da „pojačamo“ naše priče o dugmetu.
Kontrole
Dodatak „Controls“ (kontrole) omogućava nam da dajemo prilagođene rekvizite komponenti unutar samog Storybook-a. Za našu komponentu dugmeta, možemo dodati kontrole za promenu različitih rekvizita unutar Storybook-a.
Recimo da moramo da pronađemo najbolju boju pozadine za dugme. Bilo bi dugotrajno testirati različite boje pozadine, tako što bismo ih menjali jednu po jednu u kodu komponente. Umesto toga, možemo dodati kontrolu koja nam omogućava da biramo različite boje unutar Storybook-a. Boju pozadine možemo testirati direktno u Storybook-u.
Hajde da vidimo kako da dodamo kontrole našim pričama o dugmetu.
Prvo, moramo da definišemo sve rekvizite ispod naslova, na sledeći način.
export default {
title: "src/common/Button",
argTypes: {
text: { control: "text" },
backgroundColor: { control: "color" },
isDisabled: { control: "boolean" },
size: {
control: { type: "select", options: ["small", "medium", "large"] },
},
type: {
control: { type: "select", options: ["filled", "outline"] },
},
variant: {
control: { type: "select", options: ["oval", "rectangular"] },
},
},
};
Zatim, izdvojte rekvizite iz komponente i prosledite ih kao argumente na sledeći način.
export const outlineSmallButton = (args) => (
Možete videti kontrole na dnu prozora za pregled komponente.
Možete videti tab „Controls“ (kontrole) na dnu prozora za pregled komponente. „Igrajte se“ sa njima.
Ažurirajte sve priče kao gore. Ovo sve više liči na upoznavanje sa sintaksom dodataka Storybook-a. U `argTypes` smo koristili različite tipove kontrola. Možete pronaći sve kontrole koje su prisutne u Storybook-u ovde.
Ažurirane priče o dugmadima će izgledati na sledeći način.
import React from "react";
import { Button } from "./Button";
export default {
title: "src/common/Button",
argTypes: {
text: { control: "text" },
backgroundColor: { control: "color" },
isDisabled: { control: "boolean" },
size: {
control: { type: "select", options: ["small", "medium", "large"] },
},
type: {
control: { type: "select", options: ["filled", "outline"] },
},
variant: {
control: { type: "select", options: ["oval", "rectangular"] },
},
},
};
export const defaultButton = (args) =>
Akcije
Akcije su događaji u JavaScript-u. Možemo da kliknemo na dugme, što je jedan JavaScript događaj. Možemo uraditi neke radnje klikom na dugme, pomoću dodatka „Actions“ (akcije).
Uz pomoć akcija, možemo testirati da li događaji funkcionišu ispravno. Onemogućeno dugme ne može se kliknuti, dok omogućeno dugme treba da se može kliknuti. To možemo potvrditi pomoću akcija.
Hajde da vidimo kako da dodamo akciju kliku na dugme.
Prethodno smo davali anonimnu funkciju `onClick` rekvizitu. Sada to moramo da ažuriramo.
- Uvezite akciju iz Storybook dodatka koristeći sledeću izjavu.
import { action } from "@storybook/addon-actions";
- Zamenite sve `() => {}` sledećom komandom.
action("Button is clicked!")
Sada idite na Storybook i kliknite na dugme. Videćete poruku odštampanu ispod taba sa akcijama koji se nalazi pored taba sa kontrolama. Poruka se neće odštampati ako kliknete na onemogućeno dugme, jer je ono onemogućeno.
Akciju možemo koristiti za različite događaje kao što su `onChange`, `onMouseOver`, `onMouseOut` itd., kako bismo bili sigurni da rade ispravno. Pokušajte da implementirate isto za `onChange` kod ulaznog elementa.
Pogledajte dokumentaciju za akcije ovde.
Pozadina
Možemo da promenimo pozadinu prozora za pregled pomoću dodatka „Backgrounds“ (pozadine). Ne moramo da pišemo nikakav kod, samo je promenimo u Storybook-u. Pogledajte gif ispod.
Viewport
Takođe možemo testirati odzivnost naših komponenti u Storybook-u. Pogledajte gif ispod da biste saznali više o opcijama okvira za prikaz.
Docs
Možemo dokumentovati naše komponente u Storybook-u, koristeći dodatak „Docs“ (dokumenti). Ovo je posebno korisno kada radimo u timu. Kolege će moći da pročitaju dokumentaciju komponente i direktno je razumeju. To štedi mnogo vremena programerima.
U prozoru za pregled komponenti Storybook-a, možete videti tab „Docs“ u gornjem desnom uglu, na tabu „Canvas“. Sadržaće sve dokumente svih priča za komponentu. Moramo koristiti `Button.stories.mdx` ako želimo da dokumentujemo komponentu sa markdaun sintaksom i renderovanjem komponente. Jednostavno, napišemo dodatni markdaun kod unutar ovog fajla, zajedno sa pričama o komponentama.
Napisaćemo dokumentaciju za naše priče. Kod uključuje markdaun i renderovanje komponente. Sve je samo učenje sintakse. Shvatićete je brzo.
Hajde da vidimo kod `Button.stories.mdx` dokumenta.
import {
Meta,
Story,
Preview,
ArgsTable
} from '@storybook/addon-docs/blocks';
import { Button } from './Button';
# Button Documentation
With `MDX` we can define a story for `Button` right in the middle of our
Markdown documentation.
{Template.bind({})}
## Large Button
We are writing sample docs for two stories, you can write rest of them
{Template.bind({})}
Saznajte više o komponentama za dokumentovanje ovde.
Možete saznati više o dodacima ovde.
Zaključak
Nadam se da ste uživali u vodiču i da ste naučili nešto o Storybook-u. Iskoristite ga efikasno u svom timu kako biste svoj rad učinili produktivnijim.
Jeste li tek počeli sa Reactom? Pogledajte ove resurse za učenje.
Srećno kodiranje 🙂