뷰포트 (Viewport)

React | Vue | Angular | Web Components | 그 외(More)

뷰포트(Viewport) 기능을 사용하면 스토리가 그려지는 iframe의 가로세로 크기를 마음대로 조절할 수 있습니다. 덕분에 화면 크기에 따라 디자인이 변하는 반응형(responsive) UI를 개발하기가 훨씬 수월해집니다.

설정하기 (Configuration)

스토리북을 설치하면 뷰포트 기능이 자주 쓰이는 기기 크기들을 모아놓은 기본 세트(standard set)를 알아서 제공해 줍니다.

하지만 기본 제공되는 기기 목록이 마음에 들지 않거나, 프로젝트 전용 뷰포트 세트가 필요하다면 .storybook/preview.js|ts 파일의 viewport 파라미터(parameter)를 만져서 완전히 새로 구성할 수 있어요.

이때 사용할 수 있는 두 가지 핵심 속성이 있습니다. options 속성으로 툴바 목록에 띄워줄 뷰포트 기기 종류를 정의하고, initialGlobals 속성으로 스토리북을 처음 켰을 때 기본으로 선택되어 있을 뷰포트를 지정해 줍니다:

// Replace your-framework with the framework you are using, e.g. react-vite, nextjs, vue3-vite, etc.
import type { Preview } from '@storybook/your-framework';
 
import { INITIAL_VIEWPORTS } from 'storybook/viewport';
 
const preview: Preview = {
  parameters: {
    viewport: {
      // 👇 스토리북이 제공하는 풍부한 기본 기기 목록(INITIAL_VIEWPORTS)을 가져와 적용합니다.
      options: INITIAL_VIEWPORTS,
    },
  },
  initialGlobals: {
    viewport: {
      // 👇 처음에 스토리북이 켜지면 무조건 'ipad' 크기로 보여주게 만듭니다.
      value: 'ipad', 
      isRotated: false, // 가로 모드(회전)는 끕니다.
    },
  },
};
 
export default preview;

더 상세한 기기 목록 사용하기 (Use a detailed set of devices)

기본적으로 뷰포트 기능은 여러분이 흔한 반응형 환경만 딱 빠르고 간결하게 테스트해 볼 수 있도록 가장 필수적인 기기들만 모아놓은 '미니멀(minimal)' 세트를 씁니다. 이 미니멀 세트는 내부적으로 MINIMAL_VIEWPORTS라는 이름으로 추출(export)되어 있고, 다음 기기들을 포함합니다:

식별자 (Key)	설명 (Description)	해상도 크기 (Dimensions, 너비×높이 px)
mobile1	작은 모바일 (Small mobile)	320 × 568
mobile2	큰 모바일 (Large mobile)	414 × 896
tablet	태블릿 (Tablet)	834 × 1112
desktop	데스크톱 (Desktop)	1024 × 1280

만약 "나는 아이폰 기종별로 다 테스트해 볼래!" 하신다면, 스토리북에서 미리 만들어둔 아주 방대한 기기 목록인 INITIAL_VIEWPORTS export를 가져다 쓰면 됩니다. 이 목록에는 다음과 같은 수많은 기기들이 들어있어요:

식별자 (Key)	설명 (Description)	해상도 크기 (Dimensions, 너비×높이 px)
iphone5	iPhone 5	320 × 568
iphone6	iPhone 6	375 × 667
iphone6p	iPhone 6 Plus	414 × 736
iphone8p	iPhone 8 Plus	414 × 736
iphonex	iPhone X	375 × 812
iphonexr	iPhone XR	414 × 896
iphonexsmax	iPhone XS Max	414 × 896
iphonese2	iPhone SE (2nd generation)	375 × 667
iphone12mini	iPhone 12 mini	375 × 812
iphone12	iPhone 12	390 × 844
iphone12promax	iPhone 12 Pro Max	428 × 926
iphoneSE3	iPhone SE 3rd generation	375 × 667
iphone13	iPhone 13	390 × 844
iphone13pro	iPhone 13 Pro	390 × 844
iphone13promax	iPhone 13 Pro Max	428 × 926
iphone14	iPhone 14	390 × 844
iphone14pro	iPhone 14 Pro	393 × 852
iphone14promax	iPhone 14 Pro Max	430 × 932
galaxys5	Galaxy S5	360 × 640
galaxys9	Galaxy S9	360 × 740
nexus5x	Nexus 5X	412 × 668
nexus6p	Nexus 6P	412 × 732
pixel	Pixel	540 × 960
pixelxl	Pixel XL	720 × 1280
ipad	iPad	768 × 1024
ipad10p	iPad Pro 10.5-in	834 × 1112
ipad11p	iPad Pro 11-in	834 × 1194
ipad12p	iPad Pro 12.9-in	1024 × 1366

이 수많은 기기들을 내 스토리북 툴바에 추가하고 싶다면, 아까 본 예시처럼 설정 파일의 options 속성에 INITIAL_VIEWPORTS를 넘겨주기만 하면 됩니다!

나만의 새로운 기기 추가하기 (Add new devices)

스토리북이 아무리 많은 기기를 기본으로 줘도, 우리 회사 프로덕트에 꼭 필요한 독특한 기기가 없을 수도 있죠. 그럴 땐 뷰포트 목록에 나만의 기기를 직접 만들어 넣으면 됩니다.

기존에 있던 '미니멀 뷰포트(MINIMAL_VIEWPORTS)' 목록은 그대로 유지한 채로, 우리가 만든 'Kindle' 기기 두 개를 살짝 얹어(추가해) 볼게요:

// Replace your-framework with the framework you are using, e.g. react-vite, nextjs, vue3-vite, etc.
import type { Preview } from '@storybook/your-framework';
 
import { INITIAL_VIEWPORTS, MINIMAL_VIEWPORTS } from 'storybook/viewport';
 
// 👇 우리가 추가할 새로운 기기들의 설정 객체입니다.
const kindleViewports = {
  kindleFire2: {
    name: 'Kindle Fire 2',
    styles: {
      width: '600px',
      height: '963px',
    },
  },
  kindleFireHD: {
    name: 'Kindle Fire HD',
    styles: {
      width: '533px',
      height: '801px',
    },
  },
};
 
const preview: Preview = {
  parameters: {
    viewport: {
      options: {
        // 기존의 미니멀 뷰포트 객체를 쫙 풀어주고...
        ...MINIMAL_VIEWPORTS,
        // 그 위에 우리가 만든 킨들 뷰포트 객체를 얹어 합칩니다!
        ...kindleViewports,
      },
    },
  },
};
 
export default preview;

특정 컴포넌트나 스토리에만 뷰포트 설정하기 (Configuring per component or story)

모든 스토리에 일괄적으로 뷰포트를 적용하는 게 말이 안 되는 경우도 생깁니다. 컴포넌트마다, 심지어 스토리마다 어울리는 화면 크기가 각기 다를 수 있으니까요.

그럴 땐 파라미터(Parameters) 기능을 프로젝트 전체뿐만 아니라 컴포넌트 단위나 개별 스토리 단위에 달아주면 됩니다.

예를 들어, MyComponent라는 컴포넌트가 가진 모든 스토리들이 오직 INITIAL_VIEWPORTS (상세 기기 목록) 안에서만 놀도록 강제하고 싶다면 이렇게 하시면 돼요:

// Replace your-framework with the framework you are using, e.g. react-vite, nextjs, nextjs-vite, etc.
import type { Meta, StoryObj } from '@storybook/your-framework';
 
import { INITIAL_VIEWPORTS } from 'storybook/viewport';
 
import { MyComponent } from './MyComponent';
 
const meta = {
  component: MyComponent,
  parameters: {
    viewport: {
      //👇 이 파일 안의 '모든' 스토리는 이 뷰포트 옵션만 사용할 수 있게 됩니다.
      options: INITIAL_VIEWPORTS,
    },
  },
} satisfies Meta<typeof MyComponent>;
 
export default meta;
type Story = StoryObj<typeof meta>;

특정 스토리만 뷰포트 크기 고정하기 (Defining the viewport for a story)

뷰포트 모듈을 켜두면, 툴바에 있는 미리 정의된 뷰포트 목록에서 이것저것 클릭해가며 화면 크기를 바꿀 수 있습니다. 하지만 특정 스토리를 켤 땐 "묻지도 따지지도 말고 무조건 이 뷰포트 크기로만 보여줘!"라고 고정해 버려야 할 때가 있죠. 이럴 때는 globals 옵션을 쓰면 됩니다:

// Replace your-framework with the framework you are using, e.g. react-vite, nextjs, vue3-vite, etc.
import type { Meta, StoryObj } from '@storybook/your-framework';
 
import { Button } from './Button';
 
const meta = {
  component: Button,
} satisfies Meta<typeof Button>;
 
export default meta;
type Story = StoryObj<typeof meta>;
 
export const OnPhone: Story = {
  globals: {
    // 👇 이 스토리 하나만 콕 집어서, 뷰포트를 'mobile1' 크기로 영구 고정시킵니다!
    viewport: { value: 'mobile1', isRotated: false },
  },
};

💡 주의: globals를 사용해서 스토리(또는 컴포넌트 전체)의 뷰포트 크기를 고정해버리면, 그 뷰포트 설정이 찰싹 달라붙어서 툴바 버튼을 눌러도 크기가 바뀌지 않게 됩니다. 스토리가 반드시 특정한 화면 크기 안에서만 렌더링되어야만 할 때 유용한 기능이에요.

API

키보드 단축키 (Keyboard shortcuts)

단축키를 쓰면 툴바를 일일이 클릭할 필요 없이 키보드만으로 화면 크기를 착착 넘길 수 있습니다. (필요하다면 스토리북의 단축키 설정 페이지에서 이 키들을 내 맘대로 바꿀 수도 있어요!)

• 다음 뷰포트로 넘어가기: alt + v
• 이전 뷰포트로 넘어가기: alt + shift + v
• 뷰포트 초기화(기본 크기로 되돌리기): alt + control + v

전역 변수 (Globals)

이 모듈은 viewport 네임스페이스 아래에 다음과 같은 전역 변수들을 제공합니다.

value

타입: string

이 값이 설정되면, 뷰포트가 그 크기로 확정되며 툴바 버튼으로 바꿀 수 없게 잠깁니다. 여기에 들어갈 문자열은 반드시 현재 사용 가능한 뷰포트 옵션들(available viewports)의 이름(key) 중 하나와 정확히 일치해야 합니다.

isRotated

타입: boolean

이 값을 true로 주면, 현재 적용된 뷰포트의 가로/세로 방향이 90도 홱 돌아갑니다(rotated). (세로 모드에서 가로 모드(landscape)로 바뀌는 셈이죠!)

파라미터 (Parameters)

이 뷰포트 기능은 스토리북의 파라미터(parameters) 영역 중 viewport 네임스페이스 아래에 다음과 같은 옵션들을 제공합니다:

disable

타입: boolean

이 뷰포트 기능의 동작 자체를 끕니다. 만약 스토리북 전체에서 뷰포트 기능을 아예 빼버리고 싶다면, 여기서 하지 마시고 메인 설정 파일(main.js|ts)에서 기능을 비활성화(disable)하시는 것이 맞습니다.

이 파라미터는 보통 프로젝트 전체 수준에서는 기능을 꺼두고(true), 내가 필요한 특정 컴포넌트나 스토리에서만 다시 켤 때(false) 아주 요긴하게 쓰입니다.

options

타입:

{
  [key: string]: {
    name: string;
    styles: { height: string, width: string };
    type: 'desktop' | 'mobile' | 'tablet' | 'other';
  };
}

화면에 보여줄 수 있는 뷰포트 기기 목록들을 정의합니다. 위쪽에 있는 나만의 기기 추가하기 예시를 다시 한번 살펴보세요. 참고로 width와 height 값에는 단순히 숫자만 쓰면 안 되고, 반드시 '320px'처럼 단위(unit)가 포함된 문자열을 적어주어야 합니다!

내보내기 (Exports)

이 뷰포트 모듈을 사용하기 위해, 다음과 같은 변수들을 파일 상단으로 가져와 쓸 수 있습니다(export):

import { INITIAL_VIEWPORTS, MINIMAL_VIEWPORTS } from 'storybook/viewport';

INITIAL_VIEWPORTS

타입: object

뷰포트 모듈이 가지고 있는, 앞서 소개한 아주 방대하고 상세한 기기 목록 전체를 담고 있는 거대한 객체입니다.

MINIMAL_VIEWPORTS

타입: object

뷰포트 모듈이 제공하는, 앞서 소개한 아주 기본적이고 핵심적인 기기 목록만 담은 객체입니다. 아무 설정도 안 건드리면 스토리북이 기본값으로 이 녀석들을 씁니다.

---

이 페이지가 유용했나요? 👍 👎
✍️ 깃허브에서 편집하기 (Edit on Github)