Frontend Academy · Урок

Storybook: истории, элементы управления и документация

Пишите истории для каждого состояния компонента, используйте Controls для интерактивной настройки свойств и создавайте страницы Docs из JSDoc и argTypes

Урок 1 из 414 шагов

«Storybook: истории, элементы управления и документация» — бесплатный урок Frontend Academy на CoddyKit. Это урок 1 из 4. Ты можешь прочитать весь урок бесплатно ниже — а потом практиковать его прямо в браузере с встроенным редактором кода и ИИ-репетитором 24/7. Это часть пути обучения Frontend Academy, и твой прогресс синхронизируется между веб-версией и приложением CoddyKit. Курс Frontend Academy содержит 4 уроков всего.

Что такое Storybook

Storybook — это среда для разработки компонентов пользовательского интерфейса, изолированная от приложения. Вы создаёте «истории» — примеры использования каждого компонента в различных состояниях — и просматриваете их на сервере разработки. Это незаменимый инструмент для дизайн-систем.

Зачем использовать Storybook

1) Разрабатывайте компоненты изолированно, не настраивая контекст приложения. 2) Визуально проверяйте все состояния (загрузка, ошибка, пустое состояние). 3) Дизайнеры и менеджеры продукта могут просматривать каталог. 4) Создавайте документацию. 5) Автоматизируйте визуальное регрессионное тестирование.

Установка Storybook

Используйте официальный инициализатор — он определит ваш фреймворк и настроит всё необходимое.

npx storybook@latest init

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

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

Написание истории (CSF 3.0)

Component Story Format 3: экспорт по умолчанию = метаданные, именованные экспорты = истории.

// 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 }
};

Несколько историй для одного компонента

Создавайте отдельную историю для каждого важного состояния: обычного, при наведении, загрузки, ошибки, пустого и заполненного. Проверяющие смогут быстро просмотреть все варианты.

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 в Storybook превращает объект args в интерактивные элементы управления формы. Меняйте значения свойств прямо в интерфейсе, чтобы проверять крайние случаи.

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

Дополнение Actions

Используйте action(), чтобы записывать вызовы обработчиков событий в панели Actions. Это удобно для проверки обратных вызовов без подключения настоящего состояния.

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

Autodocs — автоматически создаваемая документация

Добавьте tags: ['autodocs'] в метаданные; Storybook создаст страницу Docs с таблицей свойств компонента, описаниями и примерами, которые можно запустить.

MDX для подробной документации

Пишите документацию компонентов в MDX — Markdown со встроенным JSX. Сочетайте обычный текст с интерактивными примерами компонентов.

{/* 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} />

Декораторы — обёртки для историй с контекстом

Оборачивайте истории в провайдеры (Theme, Router, Redux) с помощью decorators.

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

Визуальное регрессионное тестирование

Chromatic (от команды Storybook) делает снимок каждой истории при каждом коммите и сравнивает его с эталоном. Визуальные регрессии обнаруживаются автоматически.

Публикация Storybook

npm run build-storybook создаёт статический сайт в storybook-static/. Разместите его в Netlify, Vercel или GitHub Pages — и сотрудники без навыков разработки получат доступный для просмотра каталог компонентов.

Быстрая проверка

Что делает добавление tags: ['autodocs'] в метаданные компонента Storybook?

Ответь в интерактивном уроке

Итоги: Storybook

Изолированная среда для разработки компонентов пользовательского интерфейса. CSF 3.0: экспорт по умолчанию = meta, именованные экспорты = истории. argTypes для Controls. action() для записи вызовов обратных вызовов. tags: ['autodocs'] для автоматической документации. MDX для подробного текста и JSX. Decorators добавляют провайдеры. Chromatic — для визуального регрессионного тестирования. Build-storybook — для статического размещения.

Можно начать бесплатно

Изучай HTML с ИИ-репетитором — бесплатно

Пиши и запускай код прямо в браузере, получай мгновенную помощь от ИИ-репетитора 24/7 и продолжи учиться на сайте или в приложении.

Курсы: 41
Уроки: 163

Начать учиться бесплатно Посмотреть полный курс

Часто задаваемые вопросы

Урок «Storybook: истории, элементы управления и документация» бесплатный?

Да — полный текст урока «Storybook: истории, элементы управления и документация» бесплатно доступен здесь в веб-версии. Чтобы практиковать его интерактивно (встроенный редактор кода и ИИ-репетитор 24/7) и разблокировать остальной курс Frontend Academy, подпишись на CoddyKit PRO. Курс Frontend Academy содержит 4 уроков всего.

Чему я научусь в уроке «Storybook: истории, элементы управления и документация»?

Пишите истории для каждого состояния компонента, используйте Controls для интерактивной настройки свойств и создавайте страницы Docs из JSDoc и argTypes Ты практикуешь Frontend Academy с помощью реального кода, который запускаешь прямо в браузере, и ИИ-репетитор 24/7 отвечает на твои вопросы во время урока.

Нужен ли мне опыт, чтобы начать Frontend Academy?

Предыдущий опыт не требуется. Frontend Academy на CoddyKit структурирован для всех уровней — от новичков до продвинутых, поэтому ты можешь начать отсюда или с самого начала и учиться в своем темпе. Это урок 1 из 4.

Сколько времени занимает урок «Storybook: истории, элементы управления и документация»?

Большинство уроков CoddyKit занимают около 5–10 минут. Каждый из них компактный и интерактивный, поэтому ты постоянно делаешь прогресс и продолжаешь с того же места в веб-версии и приложении.

Можно ли писать и запускать код в этом уроке Frontend Academy?

Да. Каждый урок Frontend Academy включает встроенный редактор кода, поэтому ты пишешь и запускаешь реальный код прямо в браузере и получаешь моментальную обратную связь от AI — локальная установка не требуется.

Все уроки этого курса

Storybook: истории, элементы управления и документация
Токены дизайна со Style Dictionary
Версионирование и публикация в npm
Использование дизайн-системы

← Назад к Frontend Academy