Vue Styleguidist

# Руководство разработчика

Vue Styleguidist, созданный на основе React Styleguidist (opens new window), обеспечивает дополнительную поддержку для чтения и компиляции файлов .vue.

Styleguided — это не обычное одностраничное приложение, и некоторые дизайнерские решения могут показаться постороннему человеку запутанными. В этом руководстве мы объяснили эти решения, чтобы не запутать представителей.

Главное приложение мы запускаем два раза одновременно: пользовательские компоненты и пользовательский интерфейс Styleguidist. Мы используем Webpack конфигурации и стили в одной области действия (в CSS только одну область действия). И мы можем управлять только одним из этих двух приложений: пользовательским интерфейсом Styleguidist. Это накладывает на нас некоторые ограничения:

  • Наши стили не должны влиять на основные компоненты стилей.
  • Пользовательские стили (особенно глобальные, такие как Bootstrap) не должны влиять на пользовательский интерфейс Styleguidist.
  • Стили body (например, font-family) должны влиять на пользовательские компоненты так, как ожидает пользователь, но не на пользовательский интерфейс Styleguidist.

# Как это работает

Vue Styleguidist использует vue-docgen-api для анализа файлов source (нетранспилируемых). vue-docgen-api находит экспортированные компоненты Vue и следующую документацию.

Styleguidist использует Markdown для документации: каждый блок кода JavaScript отображается как интерактивная игровая площадка с CodeMirror (opens new window). Для этого мы извлекаем все эти блоки кода, используя Remark (opens new window).

Загрузчики Webpack (см. ниже) генерируют модули JavaScript. В каждом из этих модулей каждый компонент, указанный пользователем, анализируется вместе с его документацией и примерами. Затем весь модуль в приложении React, который отображает руководство по стилю.

# Загрузчики Webpack и изменения Webpack

Мы используем загрузчики Webpack для горячей перезагрузки в соответствии с изменениями стилей компонентов, стилей и документации Markdown. У нас есть три загрузчика (папка loaders (opens new window)):

  • styleguide-loader: загружает компоненты и разделы;
  • vuedoc-loader: загружает документацию по реквизитам, с помощью vue-docgen-api;
  • examples-loader: загружает файлы из файлов Markdown;

Есть еще два загрузчика — css-loader и styles-loader. Это однострочные псевдонимы соответствующих загрузчиков Webpack. Мы не надеемся на преобразователь загрузчика Webpack, поскольку его поведение может быть изменено пользовательской конфигурацией Webpack (например, это создаёт приложение React). Таким образом, мы можем обойти преобразователь Webpack и вместо этого использовать преобразователь Node. Эти загрузчики обращались следующим образом:

require('!!../../../loaders/style-loader!../../../loaders/css-loader!codemirror/lib/codemirror.css')

Префикс !! сообщает, что Webpack не использует другие загрузчики, которые могут быть указаны в конфигурации Webpack, для загрузки этого модуля. Это означает, что изменение пользователя Webpack не влияет на Styleguidist.

Styleguidist загрузите и повторно используйте конфигурацию пользователя Webpack (webpack.config.js в корневой папке проекта). В большинстве случаев он работает, но имеет некоторые ограничения: Styleguidist игнорирует (opens new window), некоторые поля и плагины, поскольку они уже включены (например, webpack.HotModuleReplacementPlugin), не имеют смысла для управления стилями (например, output) или могут сломать Styleguidist (например, entry).

Мы сохраняем собственную [конфигурацию Webpack] Styleguidist (https://github.com/vue-styleguidist/vue-styleguidist/blob/dev/packages/vue-stylebook-engine/scripts/make-webpack-config.js) минимально, чтобы уменьшить конфликты с конфигурацией пользователя.

# Компоненты реагирования

Большинство компонентов пользовательского интерфейса StyleGuidist состоят из двух частей: Foo/Foo.js, который содержит всю логику, и Foo/FooRenderer.js, который содержит всю разметку и стили. Это позволяет пользователям настраивать рендеринг, переопределяя компонент *Renderer с псевдонимами веб-пакета (или с помощью параметра конфигурации styleguideComponents):

// styleguide.config.js
const path = require('path')
module.exports = {
  webpackConfig: {
    resolve: {
      alias: {
        'rsg-components/Wrapper': path.join(
          __dirname,
          'lib/styleguide/Wrapper'
        )
      }
    }
  }
}

Все компоненты Styleguidist должны быть импортированы следующим образом: import Foo from 'rsg-components/Foo', чтобы псевдонимы работали.

В каждой папке компонента обычно имеется несколько файлов:

  • Foo/Foo.js (необязательно для буквенных компонентов);
  • Foo/FooRenderer.js;
  • Foo/Foo.spec.js — тесты;
  • Foo/index.js — реэкспорт Foo.js или FooRenderer.js.

# Стили

Для стиля, который мы используем JSS (opens new window), он позволяет пользователям настраивать руководство по стилю и обеспечивает изоляцию стиля (спасибо jss-plugin-isolate (opens new window)). Никакие пользовательские стили не должны влиять на пользовательский интерфейс Styleguidist, а стили Styleguidist не должны влиять на пользовательские компоненты.

Используйте classnames (opens new window), чтобы создать несколько имен классов или для условных имен классов, импортируйте их как cx (import cx from 'classnames').

Мы используем компонент более высокого порядка Styled, чтобы разрешить использование темы (см. параметры конфигурации управления по стилю theme и style). Используйте это следующим образом:

import React from 'react'
import Styled from 'rsg-components/Styled'

export const styles = ({ fontFamily, fontSize, color }) => ({
  button: {
    fontSize: fontSize.base,
    fontFamily: fontFamily.base,
    color: color.light,
    '&:hover, &:active': {
      isolate: false,
      color: color.lightest
    }
  }
})

export function ExamplePlaceholderRenderer({ classes }) {
  return (
    <button className={classes.button}>I am a styled button</button>
  )
}

Проверьте доступные переменные темы в src/styles/theme.js (opens new window).

Из-за открытия и темы вам необходимо явно объявить fontFamily, fontSize и color. Добавьте isolate: false в стили на выведения, иначе вам пригодятся базовые стили без наведения.

# Рендеринг компонентов Vue

Для рендеринга компонентов Vue Styleguidist использует компоненты React Preview.js (opens new window).

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

Примеры функции рендеринга при обновлении codemirror — executeCode().

# Отделить скрипт от шаблона

Сначала мы извлекли из него весь JavaScript, выполнив следующие действия:

  • если он содержит new Vue, преобразуйте традицию как скрипт
  • если это один файловый компонент, извлеките шаблон и скрипт и скомпилируйте скрипт.
  • еще прочтите первый текст, который начинается с <, тогда все, что перед ней, — js, а остальное — HTML.

# Подготовьте код

Скрипты преобразуются из es6 или jsx в es5 с помощью Buble. Имена целей, объявленных в глобальном масштабе, извлекаются, поскольку их невозможно использовать при затратах. Затем код обрабатывается с понижением getConfig.

# Пример рендеринга

Во-первых, убедитесь, что точка монтирования готова, и сохраните ее в переменном состоянии. Во-вторых, подготовьте компонент, выполнив функцию, созданную выше exampleComponent(). И, наконец, создайте экземпляр vue для монтирования нашего компонентного компонента в точку монтирования.

# Горячая перезагрузка

Чтобы включить горячую перезагрузку даже при компиляции сайта, нам необходимо оставить основной компонент Preview неизменным. Вместо этого мы будем играть со всем, что находится внутри этого дома. При размонтировании, когда компонент Preview перезагружается, мы очищаем экземпляр vue, чтобы создать новую ссылку: unmountPreview().

←