[Storybook] 필수 addon - Viewport

스토리북에서 Viewport 툴바를 사용하면 스토리가 렌더링되는 iframe의 크기를 조정할 수 있습니다. 이를 통하여 반응형 UI를 쉽게 개발할 수 있습니다.

 

설치

$ npm i -D @storybook/addon-viewport

그런 다음 .storybook/main.ts 에 다음과 같이 추가합니다.

export default {
  addons: ['@storybook/addon-viewport'],
};

설정

기본적으로 Viewport 애드온은 표준 Viewport 세트를 제공합니다.

기본 Viewport 세트를 변경하려는 경우, 전역 파라미터로 설정할 수 있습니다. 다음과 같이 .storybook/preview.js 에 viewport 파라미터로 설정 가능합니다.

// .storybook/preview.ts

// Replace your-framework with the framework you are using (e.g., react, vue3)
import { Preview } from '@storybook/your-framework';

const preview: Preview = {
  parameters: {
    viewport: {
      viewports: newViewports, // newViewports would be an ViewportMap. (see below for examples)
      defaultViewport: 'someDefault',
    },
  },
};

export default preview;

키	타입	설명	예제 값
defaultViewport	String	기본 viewport를 설정합니다.	'responsive'
defaultOrientation	String	기본 방향을 설정합니다. (ex. portrait, landscape)	'portrait'
disable	Boolean	viewport를 비활성화합니다.	N/A
viewports	Object	viewport에 대한 설정 객체	{}

viewports 객체

키	타입	설명	예제 값
name	String	viewport 이름	'Responseive'
styles	Object	스토리에 적용할 인라인 스타일을 설정합니다.	{width:0,height:0}
type	String	기기 타입(ex. desktop, mobile, tablet)	desktop

상세한 기기 세트 사용

기본적으로, 스토리북은 최소한의 뷰포트 세트를 사용하여 시작할 수 있습니다. 

.storybook/preview.js 를 다음과 같이 수정합니다.

// .storybook/preview.ts

// Replace your-framework with the framework you are using (e.g., react, vue3)
import { Preview } from '@storybook/your-framework';

import { INITIAL_VIEWPORTS } from '@storybook/addon-viewport';

const preview: Preview = {
  parameters: {
    viewport: {
      viewports: INITIAL_VIEWPORTS,
    },
  },
};

export default preview;

스토리북을 시작하면, 사용할 수 있는 새 장치를 확인할 수 있습니다.

장치 및 구성의 전체 목록은 여기를 참조하세요.

새 장치 추가

특정 viewport가 필요한 경우, .storybook/preview.ts 파일에 다음과 같이 추가할 수 있습니다.

// .storybook/preview.js|ts

const customViewports = {
  kindleFire2: {
    name: 'Kindle Fire 2',
    styles: {
      width: '600px',
      height: '963px',
    },
  },
  kindleFireHD: {
    name: 'Kindle Fire HD',
    styles: {
      width: '533px',
      height: '801px',
    },
  },
};

스토리북에서 사용하려면 다음과 같이 수정합니다.

// .storybook/preview.ts

// Replace your-framework with the framework you are using (e.g., react, vue3)
import { Preview } from '@storybook/your-framework';

const preview: Preview = {
  parameters: {
    viewport: { viewports: customViewports },
  },
};

export default preview;

컴포넌트, 스토리별 구성

때로는 보편적인 viewport 보다 컴포넌트별, 스토리별 개별 viewport를 설정하여 사용해야 할 때가 있습니다. 이를 사용하기 위해서는 Story 의 parameter 에 viewport를 추가하면 됩니다. 아래의 코드를 참조합니다.

// MyComponent.stories.ts|tsx

import type { Meta, StoryObj } from '@storybook/react';

import { INITIAL_VIEWPORTS } from '@storybook/addon-viewport';

import { MyComponent } from './MyComponent';

const meta: Meta<typeof MyComponent> = {
  component: MyComponent,
  parameters: {
    //👇 The viewports object from the Essentials addon
    viewport: {
      //👇 The viewports you want to use
      viewports: INITIAL_VIEWPORTS,
      //👇 Your own default viewport
      defaultViewport: 'iphone6',
    },
  },
};

export default meta;
type Story = StoryObj<typeof MyComponent>;

export const MyStory: Story = {
  parameters: {
    viewport: {
      defaultViewport: 'iphonex',
    },
  },
};

단축키

• 이전 viewport로 전환: shift + v
• 다음 viewport로 전환: v
• viewport reset: alt + v

필요한 경우, shortcuts 페이지에서 편집할 수 있습니다.