Frontend Academy · Lekcja

Storybook: stories, Controls i Docs

Napisze Pan/Pani stories dla każdego stanu komponentu, użyje Controls do interaktywnego modyfikowania propsów i wygeneruje strony Docs na podstawie JSDoc oraz argTypes.

Storybook: stories, Controls i Docs to bezpłatna lekcja Frontend Academy na CoddyKit. To lekcja 1 z 4. Możesz przeczytać całą lekcję poniżej za darmo — a potem ćwiczyć ją interaktywnie w przeglądarce z wbudowanym edytorem kodu i tutorem AI dostępnym 24/7. To część ścieżki edukacyjnej Frontend Academy, a Twój postęp synchronizuje się między webem a aplikacją CoddyKit. Kurs Frontend Academy zawiera 4 lekcji w sumie.

Czym jest Storybook?

Storybook to środowisko pracy z komponentami UI, odizolowane od aplikacji. Pisze się w nim „stories” — przykładowe zastosowania każdego komponentu w różnych stanach — a następnie przegląda je na serwerze deweloperskim. Jest niezbędny przy tworzeniu systemów projektowych.

Dlaczego warto używać Storybooka?

1) Tworzenie komponentów w izolacji, bez konfigurowania kontekstu aplikacji. 2) Wizualny przegląd wszystkich stanów (ładowanie, błąd, pusty). 3) Projektanci i product managerowie mogą przeglądać katalog. 4) Automatyczne generowanie dokumentacji. 5) Automatyzacja testów regresji wizualnej.

Instalowanie Storybooka

Należy użyć oficjalnego inicjalizatora — wykryje on używany framework i skonfiguruje wszystko automatycznie.

npx storybook@latest init

# Adds:
#  .storybook/        config
#  src/stories/       example stories
#  scripts: 'storybook' and 'build-storybook'

npm run storybook   # opens http://localhost:6006

Pisanie story (CSF 3.0)

Component Story Format 3: eksport domyślny = metadane, eksporty nazwane = stories.

// Button.stories.tsx
import type { Meta, StoryObj } from '@storybook/react';
import { Button } from './Button';

const meta: Meta<typeof Button> = {
  title: 'Atoms/Button',
  component: Button,
  tags: ['autodocs']
};
export default meta;

type Story = StoryObj<typeof Button>;

export const Primary: Story = {
  args: { label: 'Save', variant: 'primary' }
};

export const Disabled: Story = {
  args: { label: 'Save', variant: 'primary', disabled: true }
};

Wiele stories dla jednego komponentu

Należy utworzyć jedną story dla każdego istotnego stanu: domyślnego, po najechaniu, ładowania, błędu, pustego i wypełnionego. Osoby przeglądające mogą przeklikać wszystkie warianty i od razu je zobaczyć.

export const Loading: Story = { args: { state: 'loading' } };
export const Error: Story    = { args: { state: 'error', message: 'Network failed' } };
export const Empty: Story    = { args: { items: [] } };
export const Populated: Story = { args: { items: mockItems } };

Controls (tabela args)

Dodatek Controls w Storybooku zamienia obiekt args w interaktywne kontrolki formularza. Można na żywo zmieniać wartości propsów w interfejsie, aby testować przypadki brzegowe.

const meta: Meta<typeof Button> = {
  component: Button,
  argTypes: {
    variant: {
      control: 'select',
      options: ['primary', 'secondary', 'danger']
    },
    onClick: { action: 'clicked' }
  }
};

Dodatek Actions

Należy użyć action(), aby rejestrować wywołania handlerów zdarzeń w panelu Actions. To świetne rozwiązanie do testowania callbacków bez podłączania prawdziwego stanu.

argTypes: {
  onClick: { action: 'clicked' },
  onChange: { action: 'changed' }
}

Autodocs — automatycznie generowana dokumentacja

Należy dodać tags: ['autodocs'] do metadanych; Storybook wygeneruje stronę Docs z tabelą propsów komponentu, opisami i przykładami możliwymi do uruchomienia.

MDX do tworzenia rozbudowanej dokumentacji

Dokumentację komponentów należy pisać w MDX — Markdownzie z osadzonym JSX. Można łączyć opis z działającymi przykładami komponentów.

{/* Button.mdx */}
import { Meta, Story, Canvas } from '@storybook/blocks';
import * as ButtonStories from './Button.stories';

<Meta of={ButtonStories} />

# Button

The primary action element.

## Variants
<Canvas of={ButtonStories.Primary} />
<Canvas of={ButtonStories.Secondary} />

Dekoratory — opakowywanie stories w kontekst

Stories można opakowywać w providery (Theme, Router, Redux) za pomocą dekoratorów.

export const decorators = [
  (Story) => (
    <ThemeProvider theme={lightTheme}>
      <Story />
    </ThemeProvider>
  )
];

Testowanie regresji wizualnej

Chromatic (tworzony przez zespół Storybooka) wykonuje zrzut ekranu każdej story przy każdym commitcie i porównuje go z wersją bazową. Automatycznie wykrywa regresje wizualne.

Wdrażanie Storybooka

npm run build-storybook tworzy statyczną witrynę w storybook-static/. Można wdrożyć ją na Netlify, Vercel lub GitHub Pages — osoby nietechniczne otrzymają przeglądalny katalog komponentów.

Szybkie sprawdzenie

Co powoduje dodanie tags: ['autodocs'] do metadanych komponentu w Storybooku?

Podsumowanie: Storybook

Odizolowane środowisko pracy z komponentami UI. CSF 3.0: eksport domyślny = meta, eksporty nazwane = stories. argTypes służy do obsługi Controls. action() służy do rejestrowania callbacków. tags: ['autodocs'] włącza automatycznie generowaną dokumentację. MDX służy do tworzenia rozbudowanych opisów z JSX. Dekoratory wstrzykują providery. Chromatic służy do testów regresji wizualnej. build-storybook służy do hostowania wersji statycznej.

Często zadawane pytania

Czy lekcja „Storybook: stories, Controls i Docs” jest bezpłatna?

Tak — pełny tekst „Storybook: stories, Controls i Docs” jest dostępny za darmo tutaj w sieci. Aby ćwiczyć ją interaktywnie (wbudowany edytor kodu i tutor AI dostępny 24/7) i odblokować resztę kursu Frontend Academy, przejdź na CoddyKit PRO. Kurs Frontend Academy zawiera 4 lekcji w sumie.

Co nauczysz się w „Storybook: stories, Controls i Docs”?

Napisze Pan/Pani stories dla każdego stanu komponentu, użyje Controls do interaktywnego modyfikowania propsów i wygeneruje strony Docs na podstawie JSDoc oraz argTypes. Ćwiczysz Frontend Academy z praktycznym kodem, który uruchamiasz bezpośrednio w przeglądarce, a tutor AI dostępny 24/7 odpowiada na Twoje pytania podczas pracy nad lekcją.

Czy potrzebuję doświadczenia, aby zacząć Frontend Academy?

Nie wymagamy żadnego doświadczenia. Frontend Academy w CoddyKit jest strukturyzowany dla początkujących i zaawansowanych użytkowników, więc możesz zacząć tutaj lub od początku i uczyć się w swoim tempie. To lekcja 1 z 4.

Ile czasu zajmuje lekcja „Storybook: stories, Controls i Docs”?

Większość lekcji CoddyKit trwa około 5–10 minut. Każda lekcja to mały, interaktywny krok, dzięki czemu robisz systematyczne postępy i zawsze wracasz dokładnie do tego samego miejsca — na webie i w aplikacji.

Czy mogę pisać i uruchamiać kod w tej lekcji Frontend Academy?

Tak. Każda lekcja Frontend Academy zawiera wbudowany edytor kodu, więc piszesz i uruchamiasz prawdziwy kod bezpośrednio w przeglądarce i od razu otrzymujesz sprzężenie zwrotne od AI — bez konfiguracji na komputerze.

Wszystkie lekcje w tym kursie

← Powrót do Frontend Academy