Frontend Storybook: Átfogó útmutató a komponensfejlesztési környezetekhez

A frontend fejlesztés folyamatosan változó világában a robusztus és karbantartható felhasználói felületek (UI-k) létrehozása kiemelten fontos. A Storybook vezető eszközzé vált ezen kihívás kezelésére, erőteljes környezetet biztosítva az UI komponensek izolált fejlesztéséhez. Ez az útmutató átfogóan bemutatja a Storybookot, lefedve annak alapkoncepcióit, előnyeit, gyakorlati megvalósítását és a frontend fejlesztési munkafolyamat javítására szolgáló haladó technikákat.

Mi az a Storybook?

A Storybook egy nyílt forráskódú eszköz az UI komponensek izolált fejlesztésére. Dedikált környezetet biztosít, ahol a komponenseket a fő alkalmazástól függetlenül építheti, tesztelheti és dokumentálhatja. Ez az izoláció lehetővé teszi, hogy a komponens funkcionalitására és megjelenésére összpontosítson anélkül, hogy a komplex alkalmazáslogika vagy a függőségek akadályoznák.

Gondoljon a Storybookra mint egy élő stílus útmutatóra vagy komponens könyvtárra, amely vizuálisan bemutatja az UI komponenseit. Lehetővé teszi a fejlesztők, tervezők és érdekelt felek számára, hogy egységes és szervezett módon böngésszék és interakcióba lépjenek a komponensekkel, elősegítve az együttműködést és biztosítva a felhasználói felület közös megértését.

Miért használjunk Storybookot? Az előnyök

A Storybook integrálása a frontend fejlesztési munkafolyamatba számos előnnyel jár:

• Jobb komponens újrafelhasználhatóság: A komponensek izolált fejlesztése moduláris megközelítésre ösztönöz, így azok könnyebben újra felhasználhatók az alkalmazás különböző részein, vagy akár több projektben is.
• Gyorsabb fejlesztés: A Storybook felgyorsítja a fejlesztést, mivel lehetővé teszi, hogy az egyes komponensekre összpontosítson a teljes alkalmazás futtatásának többletterhe nélkül. Gyorsan iterálhat a komponensek tervezésén és funkcionalitásán.
• Egyszerűsített tesztelés: A Storybook megkönnyíti a komponensek különböző állapotokban és forgatókönyvekben történő tesztelését. Létrehozhat olyan story-kat, amelyek különböző felhasználási eseteket képviselnek, és vizuálisan ellenőrizheti, hogy a komponens az elvártaknak megfelelően viselkedik-e.
• Átfogó dokumentáció: A Storybook élő dokumentációként szolgál az UI komponenseihez. Automatikusan generál dokumentációt a komponenskód és a story-k alapján, megkönnyítve mások számára a használatuk és testreszabásuk megértését.
• Jobb együttműködés: A Storybook központi csomópontot biztosít a fejlesztők, tervezők és érdekelt felek számára az UI komponenseken való együttműködéshez. Lehetővé teszi a vizuális ellenőrzéseket, a visszajelzéseket és az UI könyvtár közös megértését.
• Hibák korai felismerése: A komponensek izolált fejlesztésével a hibákat már a fejlesztési ciklus korai szakaszában azonosíthatja és megoldhatja, mielőtt azok bonyolultabbá és költségesebbé válnának.
• Design System következetesség: A Storybook elősegíti a design system következetességét azáltal, hogy vizuális referenciát biztosít az összes UI komponenshez. Biztosítja, hogy a komponensek megfeleljenek a tervezési irányelveknek és egységes megjelenést biztosítsanak az alkalmazás egészében.

Első lépések a Storybookkal

A Storybook beállítása egyszerű, és zökkenőmentesen integrálódik olyan népszerű frontend keretrendszerekkel, mint a React, a Vue és az Angular.

Telepítés

A Storybook telepítésének legegyszerűbb módja a parancssori felület (CLI) használata. Nyissa meg a terminált, navigáljon a projekt könyvtárába, majd futtassa a következő parancsot:

            npx storybook init
            

              
                Copy
              
            
          

Ez a parancs automatikusan felismeri a projekt keretrendszerét és telepíti a szükséges függőségeket. Létrehoz egy .storybook könyvtárat is a projektben, amely a Storybook konfigurációs fájljait tartalmazza.

Az első story létrehozása

A Storybookban egy „story” egy komponens specifikus állapotát vagy használati esetét képviseli. Egy story létrehozásához általában egy új fájlt kell készítenie a projekt src/stories könyvtárában (vagy hasonló helyen, a projekt struktúrájától függően). A fájlnak .stories.js vagy .stories.jsx kiterjesztéssel kell rendelkeznie (React esetén), vagy a Vue vagy Angular megfelelőjével.

Itt egy példa egy egyszerű story-ra egy React gomb komponenshez:

            // src/stories/Button.stories.jsx
import React from 'react';

import { Button } from './Button'; // Feltételezve, hogy a Button komponens a Button.jsx fájlban van

export default {
  title: 'Example/Button',
  component: Button,
};

const Template = (args) => <Button {...args} />;

export const Primary = Template.bind({});
Primary.args = {
  primary: true,
  label: 'Primary Button',
};

export const Secondary = Template.bind({});
Secondary.args = {
  label: 'Secondary Button',
};

export const Large = Template.bind({});
Large.args = {
  size: 'large',
  label: 'Large Button',
};

export const Small = Template.bind({});
Small.args = {
  size: 'small',
  label: 'Small Button',
};

            

              
                Copy
              
            
          

Ebben a példában definiálunk egy Button nevű komponenst, és létrehozunk négy story-t: Primary, Secondary, Large és Small. Minden story a gomb komponens egy-egy különböző variációját képviseli, különböző prop-okkal.

A Storybook futtatása

A Storybook futtatásához egyszerűen használja a következő parancsot:

            npm run storybook
            

              
                Copy
              
            
          

Ez elindít egy helyi fejlesztői szervert, és megnyitja a Storybookot a böngészőjében. Látnia kell a story-kat a Storybook felhasználói felületén.

A Storybook alapkoncepciói

A Storybook hatékony használatához fontos megérteni annak alapvető koncepcióit:

• Komponensek: Az UI alapvető építőkövei. A Storybook célja az egyes komponensek bemutatása és fejlesztése izoláltan.
• Story-k: Egy komponens specifikus állapotait vagy felhasználási eseteit képviselik. Meghatározzák a komponensnek átadott prop-okat és adatokat, lehetővé téve a különböző forgatókönyvek vizualizálását és tesztelését.
• Kiegészítők (Addons): Bővítik a Storybook funkcionalitását különböző funkciókkal, mint például a témázás, az akadálymentességi tesztelés és a dokumentáció generálása.
• Dekorátorok (Decorators): További funkcionalitással látják el a komponenseket, például kontextust vagy stílust biztosítva.
• Args: (Korábbi nevén knobs) Lehetővé teszik a komponens prop-jainak interaktív módosítását a Storybook felületén. Ez hasznos a különböző variációk és konfigurációk felfedezéséhez.
• Kontrollok (Controls): Az Args módosítására szolgáló UI elemek, amelyek megkönnyítik a komponens tulajdonságainak beállítását a böngészőben.

Haladó Storybook technikák

Miután megértette a Storybook alapjait, felfedezhet haladó technikákat a munkafolyamat további javítására:

Kiegészítők (Addons) használata

A Storybook számos kiegészítőt kínál, amelyek bővíthetik funkcionalitását. Néhány népszerű kiegészítő:

• @storybook/addon-knobs: (Elavult, az Args/Controls javára) Lehetővé teszi a komponens prop-jainak interaktív módosítását a Storybook felületén.
• @storybook/addon-actions: Megjeleníti a komponens interakciói által kiváltott eseménykezelőket.
• @storybook/addon-links: Linkeket hoz létre a story-k között, lehetővé téve a navigációt a különböző komponensállapotok között.
• @storybook/addon-docs: Dokumentációt generál a komponensekhez a kód és a story-k alapján.
• @storybook/addon-a11y: Akadálymentességi ellenőrzéseket végez a komponenseken, hogy biztosítsa azok használhatóságát a fogyatékkal élők számára.
• @storybook/addon-viewport: Lehetővé teszi a komponensek megtekintését különböző képernyőméretekben és eszközökön.
• @storybook/addon-backgrounds: Lehetővé teszi a story-k háttérszínének megváltoztatását a komponensek kontrasztjának teszteléséhez.
• @storybook/addon-themes: Lehetővé teszi a különböző témák közötti váltást a Storybookban.

Egy kiegészítő telepítéséhez használja a következő parancsot:

            npm install @storybook/addon-name --save-dev
            

              
                Copy
              
            
          

Ezután adja hozzá a kiegészítőt a .storybook/main.js fájlhoz:

            module.exports = {
  stories: ['../src/**/*.stories.mdx', '../src/**/*.stories.@(js|jsx|ts|tsx)'],
  addons: [
    '@storybook/addon-links',
    '@storybook/addon-essentials',
    '@storybook/addon-interactions',
    '@storybook/addon-a11y',
  ],
  framework: '@storybook/react',
  core: {
    builder: '@storybook/builder-webpack5',
  },
  features: {
    interactionsDebugger: true,
  },
};

            

              
                Copy
              
            
          

Dekorátorok használata

A dekorátorok olyan funkciók, amelyek további funkcionalitással látják el a komponenseket. Használhatók kontextus, stílus vagy más globális konfigurációk biztosítására.

Itt egy példa egy dekorátorra, amely egy téma kontextust biztosít a komponenseknek:

            // src/stories/decorators/ThemeProvider.jsx
import React from 'react';
import { ThemeProvider } from 'styled-components';
import { theme } from './theme'; // A téma objektumod

export const ThemeDecorator = (Story) => (
  <ThemeProvider theme={theme}>
    <Story />
  </ThemeProvider>
);

            

              
                Copy
              
            
          

A dekorátor használatához adja hozzá a story konfigurációjához:

            // src/stories/Button.stories.jsx
import React from 'react';
import { Button } from './Button';
import { ThemeDecorator } from './decorators/ThemeProvider';

export default {
  title: 'Example/Button',
  component: Button,
  decorators: [ThemeDecorator],
};

            

              
                Copy
              
            
          

Automatizált tesztelés a Storybookkal

A Storybook integrálható különböző tesztelési eszközökkel az UI komponensek tesztelésének automatizálásához. Néhány népszerű tesztelési keretrendszer:

• Jest: Egy JavaScript tesztelési keretrendszer, amellyel egységteszteket írhat a komponensekhez.
• React Testing Library: Egy tesztelési könyvtár, amely a komponensek felhasználói szemszögből történő tesztelésére összpontosít.
• Cypress: Egy végponttól végpontig terjedő (end-to-end) tesztelési keretrendszer, amellyel a teljes alkalmazást tesztelheti, beleértve az UI komponenseket is.
• Playwright: Hasonló a Cypress-hez, a Playwright-ot végponttól végpontig terjedő tesztelésre használják különböző böngészőkben és platformokon.

A Storybook csapata fenntart egy @storybook/testing-react (vagy hasonló Vue/Angular esetében) nevű könyvtárat is, amely segédprogramokat biztosít a komponensek Storybookban történő teszteléséhez.

A Storybook publikálása

Könnyedén publikálhatja Storybookját, hogy megossza azt a csapatával vagy a szélesebb közösséggel. Számos lehetőség áll rendelkezésre:

• Netlify: Népszerű platform statikus weboldalak, köztük Storybookok telepítésére.
• GitHub Pages: A GitHub által biztosított ingyenes hosting szolgáltatás, amelyen hosztolhatja a Storybookját.
• Chromatic: Egy felhőalapú platform, amelyet kifejezetten Storybookok hosztolására és kezelésére terveztek. A Chromatic olyan funkciókat kínál, mint a vizuális regressziós tesztelés és az együttműködési eszközök.
• AWS S3: A statikus Storybook fájlokat egy Amazon S3 bucket-ben is hosztolhatja.

A Storybook publikálásához általában létre kell hoznia egy statikus verziót a következő paranccsal:

            npm run build-storybook
            

              
                Copy
              
            
          

Ez létrehoz egy storybook-static (vagy hasonló) nevű könyvtárat, amely a kiválasztott hosting platformra telepíthető statikus fájlokat tartalmazza.

Bevált gyakorlatok a Storybook használatához

A Storybook előnyeinek maximalizálása érdekében kövesse az alábbi bevált gyakorlatokat:

• Tartsa a komponenseket kicsinek és fókuszáltnak: Tervezze a komponenseket a lehető legkisebbre és legfókuszáltabbra. Ez megkönnyíti a tesztelésüket, újrafelhasználásukat és dokumentálásukat.
• Írjon átfogó story-kat: Hozzon létre olyan story-kat, amelyek lefedik a komponensek összes különböző állapotát és felhasználási esetét. Ez biztosítja, hogy a komponensek alaposan tesztelve és dokumentálva legyenek.
• Használja okosan a kiegészítőket: Válasszon olyan kiegészítőket, amelyek relevánsak a projekt igényeihez, és kerülje a túl sok kiegészítő hozzáadását, mivel ez befolyásolhatja a teljesítményt.
• Dokumentálja alaposan a komponenseket: Használja a @storybook/addon-docs kiegészítőt a komponensek dokumentációjának generálásához. Ez megkönnyíti mások számára a használatuk és testreszabásuk megértését.
• Integrálja a Storybookot a fejlesztési munkafolyamatba: Tegye a Storybookot a fejlesztési munkafolyamat szerves részévé. Használja az UI komponensek fejlesztésére, tesztelésére és dokumentálására a projekt kezdetétől.
• Hozzon létre egy tiszta komponens könyvtár struktúrát: Szervezze a komponens könyvtárat logikus és következetes módon. Ez megkönnyíti mások számára a komponensek megtalálását és újrafelhasználását.
• Karbantartsa rendszeresen a Storybookot: Tartsa naprakészen a Storybookot az UI komponensek legújabb változásaival. Ez biztosítja, hogy a dokumentáció pontos legyen, és hogy a komponensek mindig a legújabb kód alapján legyenek tesztelve.
• Használjon verziókövetést: Tárolja a Storybook konfigurációját és a story-kat verziókövető rendszerben (pl. Git) a változások követése és a másokkal való együttműködés érdekében.

Storybook különböző keretrendszerekben

Bár az alapkoncepciók hasonlóak maradnak, a Storybook implementációs részletei kissé eltérnek a használt frontend keretrendszertől függően.

Storybook React-hez

A React az egyik legnépszerűbb keretrendszer a Storybook használatához. A hivatalos Storybook dokumentáció kiváló forrásokat és példákat nyújt a React fejlesztők számára.

Storybook Vue-hoz

A Storybook zökkenőmentesen integrálódik a Vue.js-sel is. A Vue komponensek könnyen hozzáadhatók a Storybookhoz, hasonlóan a React-hez.

Storybook Angular-hoz

Az Angular fejlesztők a Storybook segítségével vizuális komponens könyvtárat hozhatnak létre Angular alkalmazásaikhoz. Az Angular CLI integráció egyszerűvé teszi a beállítási folyamatot.

Globális perspektívák és példák

Amikor a Storybookot globális projektekben használja, fontos figyelembe venni az UI komponensek lokalizációs és nemzetköziesítési szempontjait. Például:

• Szövegirány (RTL/LTR): Biztosítsa, hogy a komponensek támogassák mind a balról jobbra (LTR), mind a jobbról balra (RTL) írásirányt. A Storybook segítségével létrehozhat olyan story-kat, amelyek mindkét irányban bemutatják a komponenseket. Fontolja meg olyan könyvtárak használatát, mint a `styled-components` az `rtlcss` beépülő modullal a stílusátalakítások automatikus kezeléséhez.
• Dátum- és időformátumok: Használjon megfelelő dátum- és időformázást a felhasználó területi beállításai alapján. Használhat olyan könyvtárakat, mint a `moment.js` vagy a `date-fns` a dátumok és idők helyes formázásához. Hozzon létre olyan story-kat, amelyek különböző dátum- és időformátumokkal mutatják be a komponenseket.
• Pénznemformátumok: Jelenítse meg a pénznemértékeket a felhasználó területi beállításainak megfelelő formátumban. Használhat olyan könyvtárakat, mint a `numeral.js` vagy az `Intl.NumberFormat` a pénznemértékek formázásához. Hozzon létre olyan story-kat, amelyek különböző pénznemformátumokkal és szimbólumokkal mutatják be a komponenseket.
• Fordítás: Használjon nemzetköziesítési (i18n) könyvtárakat az UI komponensek különböző nyelvekre történő lefordításához. A Storybook használható a komponensek különböző fordításokkal történő vizualizálására. Gyakran használt könyvtárak például az `i18next`.
• Akadálymentesség: Tartsa be a webes akadálymentességi irányelveket annak érdekében, hogy az UI komponensek használhatók legyenek a fogyatékkal élők számára, tartózkodási helyüktől függetlenül.

Példa: Képzeljen el egy globálisan használt űrlap komponenst. Egy Storybook story-ban bemutathatná:

• Az űrlapot spanyolra fordított címkékkel és utasításokkal.
• Ugyanazt az űrlapot RTL elrendezéssel megjelenítve arab nyelvű felhasználók számára.
• Az űrlapot egy dátummezővel, amely az Egyesült Államok számára HH/NN/ÉÉÉÉ, Európa számára pedig NN/HH/ÉÉÉÉ formátumban jelenik meg.

Összegzés

A Storybook egy hatékony eszköz, amely jelentősen javíthatja a frontend fejlesztési munkafolyamatot. Azáltal, hogy izolált környezetet biztosít az UI komponensek fejlesztéséhez, elősegíti az újrafelhasználhatóságot, növeli a fejlesztési sebességet, egyszerűsíti a tesztelést és megkönnyíti az együttműködést. Legyen szó egy kis weboldalról vagy egy nagyszabású alkalmazásról, a Storybook segíthet robusztus, karbantartható és következetes felhasználói felületeket létrehozni.

Az ebben az útmutatóban felvázolt koncepciók és technikák elsajátításával kiaknázhatja a Storybookban rejlő teljes potenciált, és kivételes felhasználói élményt nyújthat globális közönségének.