React

React - Storybook 組件視覺化工具

React, Storybook

React - Storybook 安裝和使用 notes、viewport 套件

這套件超好用的，搭配 React 的組件概念，可以直接顯示切版的樣子，又可以切換不同裝置，還可以寫 Markdown 文件，方便給其他開發者觀看，真的是超棒的，那就開始教學吧，分3個部分教學：

  1. Storybook 安裝教學
  2. Storybook notes 套件使用方法
    可以寫 Markdown 說明文件
  3. Storybook viewport 套件使用方法
    直接在 Storybook 視窗切換裝置大小，查看響應式

此教學的資料夾配置都是個人習慣，你也可以按你個人習慣做調整。

一、Storybook 安裝

  1. 下載 Storybook
    自動設定，如果您使用的是Create React App 創建專案，則使用以下命令，會自動判斷下載檔案：

    1
    npx -p @storybook/cli sb init

  2. 變更storybook主題
    到.storybook資料夾，新增manager.js，這部份就看個人習慣了，我習慣看黑色的，所以改成黑色的。

    1
    2
    3
    4
    5
    6
    7
    8
    9
    /*
    manager.js
    */
    import { addons } from '@storybook/addons';
    import { themes } from '@storybook/theming';

    addons.setConfig({
        theme: themes.dark,
    });

  3. 自訂資料夾位置
    開啟.storybook/main.js
    變更第2行，改為: stories: [‘../src/*/.stories.[tj]s’],

    1
    2
    3
    4
    5
    6
    7
    8
    module.exports = {
      stories: ['../src/**/*.stories.[tj]s'],
      addons: [
        '@storybook/preset-create-react-app',
        '@storybook/addon-actions',
        '@storybook/addon-links',
      ],
    };

  4. 在src資料夾底下新增相關資料夾
    新增資料夾resources底下在新增components(此設定要跟.storybook/main.js對應)
    接下來components底下的資料夾可以自行命名，我會分成3個資料夾

    1. atoms

    2. molecules

    3. organisms

  1. 接下來我會在atoms資料夾新增一個簡單的元件
    新增2個檔案、1個資料夾(底下包含一個檔案)

    1. Title.tsx

      1
      2
      3
      4
      5
      6
      7
      8
      9
      10
      11
      12
      13
      14
      15
      16
       /*
       Title.tsx
       */
      import React, { FunctionComponent } from 'react';

       interface Props {
           children: string;
       }

       const Title: FunctionComponent<Props> = (props: Props) => {
           const { children } = props;

           return <div>{children}</div>;
       };

       export default Title;

    2. index.tsx

      1
      2
      3
      4
      5
      6
      /*
      index.tsx
      */
      import Title from './Title';

      export default Title;

    3. test/Title.stories.js
      Title.stories.js有兩種寫法，如下，我自己的話，會使用第一種方法撰寫

      a. 第一種使用storiesOf

      1
      2
      3
      4
      5
      6
      7
      8
      9
      10
      11
      12
      13
      14
      15
      16
      17
      18
      19
      20
      21
      22
      /*
      Title.stories.js，第一種使用storiesOf
      */
      import React from 'react';
      import { storiesOf } from '@storybook/react';
      import '../../../../../reset.css';
      import Title from '../Title';

      //需要import storiesOf，'atoms|Title' atoms是分類資料夾，Title是要顯示的元件名稱
      // | 後面可以是階層式管理 tags/Title2，以斜線'/'分開管理
      //可以新增多個storiesOf，'Title1、Title2'則是個別顯示在Title底下
      //箭頭涵式後面是顯示的元件程式

      storiesOf('atoms|Title', module).add('default', () => <Title>Title1</Title>);
      storiesOf('atoms|tags/Title2', module).add('default1', () => (
          <Title>Title2</Title>
      ));

      //如果有多個元件，不同型態要顯示，資料夾又一樣的，改為如下即可
      storiesOf('atoms|Title', module)
          .add('Title1', () => <Title>Title1</Title>)
          .add('Title2', () => <Title>Title2</Title>);

      b. 第二種使用 export const

      1
      2
      3
      4
      5
      6
      7
      8
      9
      10
      11
      12
      13
      14
      15
      16
      /*
      Title.stories.js，第二種使用 export const
      */
      import React from 'react';
      import '../../../../../reset.css';
      import Title from '../Title';

      //第12行，一樣可以做階層管理，使用斜線'/'即可
      export const Title1 = () => <Title>Title1</Title>;
      export const Title2 = () => <Title>Title2</Title>;
      export default {
          title: 'atoms|Title',
          parameters: {
              notes: someNotes
          }
      };

  1. 執行storybook

    1
    npm run storybook

    正確執行，會自動開啟瀏覽器，圖片如下

二、Storybook notes 套件使用方法

新增各個元件 Markdown 說明文件

  1. 安裝 notes 套件，顯示各個元件 Markdown 說明文件

    1
    npm install -D @storybook/addon-notes --save

  2. 開啟.storybook/main.js
    注意:二選一，會有不同的呈現效果，呈現效果在最下面

    1
    2
    3
    4
    5
    6
    7
    //二選一
    module.exports = {
      addons: ['@storybook/addon-notes/register']
    }
    module.exports = {
      addons: ['@storybook/addon-notes/register-panel']
    }

  3. Title.stories.js一樣有兩種寫法，如下，我自己的話，會使用第一種方法撰寫
    需要在test資料夾底下新增 notes.md

    1
    2
    3
    4
    /*
    notes.md，使用 Markdown 語法撰寫
    */
    # Title說明文件檔

    a. 第一種使用storiesOf

    1
    2
    3
    4
    5
    6
    7
    8
    9
    10
    11
    12
    13
    14
    /*
    Title.stories.js，第一種使用storiesOf
    */
    import React from 'react';
    import { storiesOf } from '@storybook/react';
    import '../../../../../reset.css';
    import Title from '../Title';

    //載入 Markdown 檔案
    import someNotes from './notes.md';

    storiesOf('atoms|Title', module).add('Title1', () => <Title>Title1</Title>, {
        notes: someNotes
    });

    b. 第二種使用 export const

    1
    2
    3
    4
    5
    6
    7
    8
    9
    10
    11
    12
    13
    14
    15
    16
    17
    18
    19
    /*
    Title.stories.js，第二種使用 export const
    */
    import React from 'react';
    import { storiesOf } from '@storybook/react';
    import '../../../../../reset.css';
    import Title from '../Title';

    //載入 Markdown 檔案
    import someNotes from './notes.md';

    export const Title1 = () => <Title>Title1</Title>;
    export const Title2 = () => <Title>Title2</Title>;
    export default {
    title: 'atoms|Title',
    parameters: {
        notes: someNotes
    }
    };

  4. 兩種呈現效果
    注意:如果有更改檔案，要重新啟動 storybook

    1. 第一種是‘@storybook/addon-notes/register’
      最上面可以切換到 Notes 查看說明文件

    2. 第二種是‘@storybook/addon-notes/register-panel’
      在下面呈現，可以一邊看渲染畫面，一邊看說明文件

三、Storybook viewport 套件使用方法

可以切換不同裝置顯示，不需要開啟瀏覽器開發者工具就能直接切換觀看了

  1. 安裝 viewport 套件

    1
    npm install @storybook/addon-viewport --save

  2. 開啟.storybook/main.js

    1
    2
    3
    4
    5
    6
    /*
    main.js
    */
    module.exports = {
      addons: ['@storybook/addon-viewport/register'],
    };

  3. 新增.storybook/preview.js
    套件已經幫你做了一些常用的裝置配置了，如果要新增也是可以，沒問題的。

    1
    2
    3
    4
    5
    6
    7
    8
    9
    10
    11
    12
    13
    14
    15
    16
    17
    18
    19
    20
    21
    22
    23
    24
    25
    26
    27
    28
    29
    30
    31
    32
    33
    /*
    preview.js
    */
    import { addParameters } from '@storybook/react';
    import { INITIAL_VIEWPORTS } from '@storybook/addon-viewport';

    //自訂的裝置大小
    const customViewports = {
        kindleFire2: {
            name: 'Kindle Fire 2',
            styles: {
                width: '600px',
                height: '963px',
            },
        },
        kindleFireHD: {
            name: 'Kindle Fire HD',
            styles: {
                width: '533px',
                height: '801px',
            },
        },
    };

    addParameters({
        viewport: {
            viewports: {
            ...INITIAL_VIEWPORTS,
            // or ...MINIMAL_VIEWPORTS,
            ...customViewports,
            },
        },
    });

    這樣就可以切換不同裝置了

分享到