Мощное живое руководство по стилю для компонентов React.
В предыдущих историях я привел несколько причин, по которым я использую экосистему React (№1) и Стилизованные компоненты (№2) для создания веб-приложений и мобильных приложений.
Теперь давайте свяжем эти две темы вместе и узнаем, как создать руководство по стилю повторно используемых компонентов.
Зачем мне вообще создавать какое-либо руководство по стилю?
Такой инструмент дает вам:
- Визуальный обзор всех имеющихся у вас компонентов.
- Документирование и разбивка компонентов на логические группы.
- Площадка, где можно попробовать всевозможные варианты реквизита и контента.
Мой любимый инструмент - React Styleguidist.
Конечно, есть и другие замечательные инструменты. Например, Сборник рассказов. Его преимущество в том, что помимо React он поддерживает также другие JavaScript-фреймворки, такие как Angular или Vue.
Я просто придерживаюсь Styleguidist, потому что в нем есть все, что мне нужно.
Установка и настройка
Если вы начали свой проект с помощью Create React App, то вам просто нужно выполнить эту простую команду:
npm install --save-dev react-styleguidist
Если вы начали свой проект с использованием других инструментов или настроек, вам также необходимо:
Наконец, запустите руководство по стилю с помощью этой команды:
npx styleguidist server
И откройте его в своем браузере:
http://localhost:6060
Конфигурация
Создайте styleguide.config.js
файл в корневой папке вашего проекта. Вы можете настроить руководство по стилю в соответствии со своими потребностями. Вы можете изменить номер порта по умолчанию, основной заголовок руководства по стилю, разделы компонентов и многие другие параметры.
Начните документировать свои компоненты
Рекомендую прочитать официальную документацию. Всего несколько советов от меня.
Реквизит и комментарии
Первая часть документации автоматически генерируется из PropTypes и комментариев к коду (JSDoc).
/** * Description of the component if needed */ const Button = props => (...); Button.propTypes = { /** No user action on button is allowed */ disabled: PropTypes.bool, /** Primary theme color */ primary: PropTypes.bool, /** Shadow effect */ raised: PropTypes.bool }; Button.defaultProps = { disabled: false, primary: false, raised: false };
Компонент выше даст такой четкий вывод в руководстве по стилю:
Живые примеры
Вторая часть документации - это живые редактируемые примеры, созданные с использованием файлов Markdown.
components/ Button/ Button.js Button.md
Styleguidist по умолчанию ищет файлы Readme.md
или ComponentName.md
.
```jsx <Button primary>Click me!</Button> ```
Результат выглядит так:
Стилизованные компоненты
Styleguidist по умолчанию находит и анализирует компоненты JSX. Но он может легко обрабатывать также стилизованные компоненты с помощью простого трюка.
Вам просто нужно явно указать, что является компонентом:
const Button = styled.button``; /* @component */ export default Button;
Настроить видимое имя
Возможно, вам потребуется изменить имя компонента, используемого в руководстве по стилю:
/** * @visibleName Default Button */ const Button = props => (...);
Классификация компонентов
Когда ваше руководство по стилю будет расти, может оказаться полезным разделить компоненты на категории. Вы можете сделать это в styleguide.config.js
файле.
module.exports = { ... sections: [ { name: 'Basics', components: 'src/basics/**/*.js' }, { name: 'Advanced', components: 'src/advanced/**/*.js' } ] };
Темы
Стилизованные компоненты поддерживают создание тем из коробки. Но в руководстве по стилю тема не применяется, потому что ThemeProvider
недоступен.
Самое простое решение - предоставить настраиваемую оболочку для всех живых примеров.
В styleguide.config.js
файле добавьте эту запись:
module.exports = { ... styleguideComponents: { Wrapper: path.join(__dirname, 'src/ThemeProvider.js') }, };
Затем создайте свой ThemeProvide.js
файл:
import React from 'react'; import { ThemeProvider } from 'styled-components'; import theme from './theme' export default props => ( <ThemeProvider theme={theme}> {props.children} </ThemeProvider> );
Продолжение следует…
Я вернусь к теме «Гид по стилю жизни» в одной из следующих статей. Я покажу вам, как создать библиотеку многоразовых платформенно-независимых компонентов. Просто оставайся на связи.
Заключение
React Styleguidist - один из инструментов, который значительно упрощает вашу разработку. Установка и первоначальная настройка очень просты, а документация проста.
Вы можете настроить свое руководство по стилю разными способами. Например, я добавил собственные теги к каждому компоненту в моем руководстве по стилю. Это делает поиск и фильтрацию более мощными.
Вы можете работать в команде. В таком случае вы быстро увидите огромную выгоду от обмена своими компонентами и шаблонами проектирования с товарищами по команде в ясной и наглядной форме.
Если у вас есть опыт работы с различными инструментами для создания руководств по стилю, дайте мне знать в комментариях ниже.
Ваш отзыв важен!
Если вам нравится моя история и вы хотели бы побуждать меня писать чаще, пожалуйста, хлопайте в ладоши, делитесь и комментируйте. Ваш интерес - лучшая мотивация поделиться моими мыслями.