Как создать пользовательский аддон панели инструментов для Storybook?

Storybook позволяет быстрее создавать прототипы элементов пользовательского интерфейса независимо от фреймворка. В этой статье мы рассмотрим, как создать аддон панели инструментов для Storybook. Примером для этой темы будет переключение темы с помощью пользовательского аддона меню панели инструментов.

Я пока пропущу настройку storybook как для нового приложения, так и для существующего приложения на базе любого поддерживаемого фреймворка.

Как только вы создали новое приложение или добавили storybook в существующее приложение, запустите npm run storybook, чтобы просмотреть storybook для вашего приложения.

Основными файлами для storybook являются .storybook/main.js и .storybook/preview.js.

Откройте .storybook/main.js и добавьте "@storybook/addon-toolbar" в массив addons, если его там нет. Этот пакет позволяет нам добавлять пользовательские аддоны на панель инструментов storybook.

Как упоминалось ранее, мы хотим добавить меню выбора темы на панель инструментов storybook в качестве пользовательского аддона. Для этого откройте файл preview.js и приведенную ниже часть кода:

// .storybok/preview.js

export const globalTypes = {
  theme: {
    name: 'Toggle theme',
    description: 'Global theme for components',
    defaultValue: 'light',
    toolbar: {
      icon: 'circlehollow',
      items: ['light', 'dark'],
      showName: true,
      dynamicTitle: true
    }
  }
}

После сохранения изменения будут отражены на вашем localhost. И вы увидите новое меню панели инструментов с опциями light и dark.

Отлично. Мы создали новое пользовательское меню для панели инструментов storybook 😎.

Но при выборе любой опции из нового меню ничего не происходит.

Прежде чем приступить к решению этой проблемы, я хочу напомнить нашу задачу. Изменить тему для выбранного элемента пользовательского интерфейса. Для этого давайте напишем очень простой css

// your angular/react application's base.(s)css

:root:not([data-theme='dark']) {
  --bg-color: #fff;
}

[data-theme='dark'] {
  --bg-color: #000;
}

body {
  background-color: var(--bg-color);
}

Здесь нет ничего причудливого. Мы создали css-переменную --bg-color и присвоили ей значение на основе атрибута данных data-theme. И наконец, мы используем эту css-переменную для установки цвета фона тега body.

Круто. Но куда и как добавить этот атрибут данных?

Ответ на первый вопрос появится, если мы посмотрим на отрисованный элемент пользовательского интерфейса. Любой элемент пользовательского интерфейса в storybook отображается внутри iframe с id storybook-preview-iframe. Нам нужно добавить наш атрибут данных data-theme к тегу body внутри этого iframe.

Очень хорошо. Теперь пришло время ответить на второй вопрос КАК.

Для этого давайте добавим файл useTheme.js в папку .storybook приложения. И добавим приведенный ниже код:

// .storybook/useTheme.js

import { useEffect, useGlobals } from '@storybook/addons';

export const useTheme = (StoryFn) => {
  const [{ theme }] = useGlobals();

  useEffect(() => {
    //document.body refers to body tag inside iframe#storybook-preview-iframe
    document.body.setAttribute('data-theme', theme);
  }, [theme]);

  return StoryFn();
};

Это много. Давайте посмотрим, что это делает. Storybook предоставляет api под названием decorators. Мы только что создали декоратор под названием useTheme. Ранее в main.js мы добавили тему в globalTypes. Мы можем прочитать значение выбранной темы в нашем декораторе, используя useGlobals из @storybook/addons. А в useEffect мы устанавливаем выбранную тему как значение атрибута data-theme тега iframe body.

После создания декоратора useTheme нам нужно использовать его внутри preview.js как:

// .storybook/preview.js

import {useTheme} from './useTheme';

export const globalTypes = {
  theme: {
    name: 'Toggle theme',
    description: 'Global theme for components',
    defaultValue: 'light',
    toolbar: {
      icon: 'circlehollow',
      items: ['light', 'dark'],
      showName: true,
      dynamicTitle: true
    }
  }
}

export const decorators = [useTheme];

Виола. Каждый раз, когда мы выбираем тему из меню панели инструментов, цвет фона тела iframe будет меняться.

Вот так мы создали пользовательский аддон панели инструментов для изменения темы. Вы можете создать еще несколько переменных css для изменения внешнего вида элементов пользовательского интерфейса в зависимости от выбранной темы.

На этом мы заканчиваем эту статью. Пожалуйста, опубликуйте свои идеи по поводу аддонов для панелей инструментов в разделе комментариев ниже.

Спасибо,
Киран 👋