Это работа является логическим продолжением моего первого подробного текста для сообщества об актуальных подходах к верстке Как верстать веб-интерфейсы быстро, качественно и интересно. Но, если, в первом трактате, внимание уделялось, прежде всего, стилю кода, его качеству и эффектным современным возможностям различных препроцессоров и фреймворков, что демонстрировалось на некоторых конкретных специфических задачах, теперь хочется сфокусироваться на архитектурных или даже организационных аспектах веб-производства. Если вы не читали мой первый текст, но собираетесь при этом прочесть этот — не поленитесь перейти по ссылке и пробежать глазами самые последние разделы каждой из двух частей первого пособия: «Готовые решения» и «Песочницы». Этот текст начинает прямо с этих мест и развивает именно эти идеи: и о пагубности применения раскрученных-популярных «на все готовых» UI-«дизайн-систем»-фреймворков для создания кастомизированных веб-морд любой сложности и, о, по сути, полезности использования хотя бы минимального документирования и явных соглашений при разработке веб-GUI на фронтенде. Но я не стану тратить время, доказывая, что «ни в коем случае нельзя использовать Vuetify или AntDesign» для создания крупных UI-систем с полностью кастомным оформлением. Вам не нужно прикручивать себе огромный геморрой непроницаемый слой плохо кастомизируемого готового GUI для того чтобы написать кнопку или поле ввода! Если вам нужен датапикер — найдите и допилите что-нибудь под себя. Это понимание может только прийти или так и не придти с годами тяжелого опыта, когда вы будете постоянно тратить непростительно много своего времени на то, чтобы написать очевидно отвратительный CSS — «кряки с !important`ами поверх стилей библиотеки», выдумывать чудные костыли на javascript чтобы изменить дефолтное поведение виджетов на кастомное и хитрое-нестандартное затребованное дизайнерами... И, при этом, ваши шаблоны, стили и js-обвязки будут превращаться во все менее читаемые, запутанные нагромождения разнообразно оформленного кода, с различным подходом к наименованию и прочими бедами… Этот текст и написанный для него проект призваны наглядно показать «а как надо?».
Верстка по-прежнему остается достаточно свободной дисциплиной, в которой сосуществуют множество совершенно разных методологий, подходов и связанных с ними технических решений. Часто программисты принимают какой-то один определенный способ, и, в результате, стагнируют в общем понимании и развитии. Привычки формируют удобную зону комфорта и это мешает осознать риски в ситуациях для которых они неадекватны. Знаете, какой аргумент мне уже несколько раз приходилось слышать в технической дискуссии от оппонентов защищавших привычную для них систему, технику разметки, но совершенно непригодную, на мой взгляд, для решения текущих насущных задач, в реальной ситуации данного конкретного проекта и сроков? «Ну это же общепринятая технология?», «Гугл, Фейсбук, … это используют, чем мы хуже»... Если вы слышите от кого-то, что нечто, не относящееся к действительно используемому всеми нами известному перечню базовых спецификаций — «общепринято», это повод сразу сделать вывод о том, что ваш собеседник имеет мало разнообразного опыта в этом и просто защищает свою лень и нежелание учиться новому. Рядом с аргументом про странные пристрастия акул капитализма обычно следует еще и что-нибудь совершенно несостоятельное про «наши программисты не все знают Stylus», при том что, любой препроцессор CSS даже и тем более начинающий программист способен изучить до базового уровня за один полезный приятный вечер. Мне всегда нравилось менять технологии, синтаксисы — это освежает и придает драйву, интереса в работе. И именно совершенно разнообразный опыт реальной коммерческой практики с различными технологиями сформировал мои представления о том «что хорошо, что плохо» в тех или иных ситуациях.
Возможно, я когда-нибудь накоплю достаточно злости и найду время для того чтобы на наглядных вопиющих примерах показать «а почему вот это плохо?». Но эта статья и пример модуля о том «как надо?», что точно будет аккуратно и эффективно. Если вы являетесь упертым сторонником CSS-in-JS-подходов, или, вообще, по-прежнему наносите оформление на разметку в «бородатом» «утилитарном» стиле «много классов с говорящими названиями содержащих одно-два правило» (тут уместно вспомнить уже «продвинутую» — CSS-in-JS — реализацию Tailwind с ее оголтелым слоганом-оксюмороном: «"Best practices” don’t actually work».) — предложенная и в моей первой книжке и в ее практическом продолжении — здесь — методология, использующая только любой классический препроцессор как «абстрактный медиатор стилей» для доставки дизайн-констант и прочей стилевой абстракции, и сам компонентный фреймворк для, простите за сплошную тавтологию — аккуратной декларативной компонентности — вам все это не зайдет, наверняка. Например, попытки посадить Styled Components на дизайн-константы приводят к безобразному коду в таких «стилях»... Или утилиты «ишак вижу — ищак пою» «в стиле Taiwind» вполне способны представлять «атомы», но все равно ограничивают гибкость в случае непрогнозируемых и частых изменений, ну или просто — также выглядят излишне-невменяемо уже на самой разметке. Я встречал проекты где прикручено «вообще сразу все» — препроцессор, CSS-модули и Styled Components, Flow к зачем-то “отключенному” CRA, например — и это уже даже нельзя назвать «оверинжинирингом», так как это просто отвратительная глупость и очевидно плохая архитектура. Возможно, раскаяние и отрезвление наступит когда вы опять превысите сроки и бюджет на очередном проекте в пять, да, Карл, пять раз — и такое бывает сплошь и рядом. И/или — дизайнеры, по просьбе клиента которому никак нельзя отказать в очередной раз «все переделают» в макетах, которые «уже сверстаны»…
Мотивация
Давайте, прежде всего, четко обрисуем проблему которую мы собираемся решать. В реальном мире, в очень многих командах — проектирование практически никак не «дружит» с разработкой, общаясь, по сути — только через конечные «макеты». Даже действительно опытные «фуллы», которых бизнес предпочитает нанимать «и в качестве фронтендеров», на самом то деле, верстают совсем слабо. Кодеры сдают только им самим известно из какого гавна как собранные страницы на тестирование, которое, в свою очередь — тупо сравнивает их с макетами — замыкая порочный круг. Обычно и, тем более, в условиях жестких дедлайнов и/или в разношерстных, наспех собранных командах из специалистов с совершенно разными скилами и опытом — бывает очень сложно ввести соглашения. Общий фокус процесса неминуемо смещается на то чтобы «сделать хоть как-нибудь», «протолкнув» быстрый гавнокод через тестировщиков…
Такая организация работы как раз очень выгодна мракоделам. Мракодел отгораживается «только своей задачей» — «моя хата скраю» — и пишет ее так, как ему удобно, игнорируя best practices и напряжные соглашения, часто вообще — просто изображая работу удаленно — скопировал, чутка перековырял под макеты — ушел гулять, вечером отправил — ждет когда тестировщики обязательно и несколько раз вернут на доработку… «Есть баги — есть работа!». «Переиспользование» превращается в простое копирование и «интуитивную» модификацию «уже готовых кусков» — лавинообразно усугубляя мрачность и запутанность стилей, разметки и js-обвязок для них. И если javascript бывает еще более-менее адекватен, все его «умеют» и понимают — то стили часто превращаются в просто непроходимые дебри и бесконечную излишнюю неоптимизированную колбасу, несмотря на то какие именно технологии используются… При этом руководство, менеджеры которые не ходят читать репо могут пребывать в наивной уверенности что «все готово, только кнопку нажать» или хотя бы — «вот это уже сделано на том проекте и можно переиспользовать»... Мне приходилось получать репо с тонной «индусского» — нереально небрежного и явно копированного целыми крупными кусками и даже файлами кода, игнорирующего вполне имеющийся у фирмы единый UI-кит, его константы и компонентность, с посылом от руководства что «все готово», «надо слегка переписать»… Мне приходилось годами исправлять за «тимлидами-сеньорами» проекты с ужасной архитектурой блокирующей быструю доставку именно того, что нужно заказчику, например — сложного современного дизайна… Причем, когда проект начинали — самые важные требования остались проигнорированы, зато с совершенно ненужными в этом случае «модными трендами» покуражились вовсю...
Я заметил что с молодыми специалистами часто работать и добиваться качественного результата бывает намного проще чем с закостенелыми самоуверенными «фуллстеками», рефлексующими свою недооцененность и прочее… Ребята помоложе еще не потеряли азарт и интерес к тому что делают, не успели несколько раз перегореть, устать, и большинство как раз стремиться стать настоящими профессионалами, открыты новым идеям, подходам, ищут и перенимают хороший стиль, адекватно реагируют на критику и так далее.. Хотя бывают исключения и с теми, и с другими, конечно… Но хватить абстрактной лиричной боли — перейдем уже к «хорошим практикам по Гамбаряну»…
Разрабатывайте визуальный язык и основанные на нем шаблоны своих интерфейсов через простые четкие соглашения и документирование, а не хаотическое копирование!!!
По опыту, особенно, если речь идет о «бренной вьюхе» на фронтенде, очень многие программисты используют годную на все времена стремительно интуитивную методологию «программирование через копирование файлов или больших кусков кода» с девизом «да хз что за функция» — и такой уже распиленный системный хардкор-код практически невозможно полностью отрефакторить, точнее — по опыту — только в том случае, если это позволяют удачно выбранные изначально технологии, плюс, конечно же, организационные ресурсы... Некоторые системы в реальных коммерческих ситуациях можно только «подмести» и «заморозить», продолжая, по сути, доставлять мрак при необходимости какой-то видимости прогресса для клиента. Необходимость непрерывно править плохой код коллег, или работать с неадекватными задачам и целям проектов архитектурами после предшественников резко снижает качество жизни программистов.
Программисты такие же ленивые, хоть и мыслящие, животные как и все другие люди и коты. Да, мне кажется, что мой полосатый много думает и иногда даже пытается поделиться... Вот даже котик пытается рассказать о результатах своего умственного труда? А многие из вас не то что никогда не оставляют комментариев — в принципе — пишут такой код что я бы сразу уволил как это развидеть, к которому очевидно любые комментарии излишни, так скажем. Причем, причины такого состояния кода множества проектов всегда одни и те же: «времени совсем не было», «надо было что-то показать», «руководство попросило сделать очень быстро» и тому подобное, «будет время — перепишем»… Поверьте, в реальной коммерции — оплаченного отдельного времени на оптимизацию и рефакторинг практически никогда не бывает. Клиенты в аутсорсе, например, почти никогда не покупают его как дополнительную опцию. Даже если некий продукт очевидно неаккуратно написан, работает со сбоями и совершенно не годен для масштабирования — бизнес практически всегда будет заинтересован, прежде всего, в доставке нового функционала любой ценой, а не в исправлении «уже проданного» — и все что он действительно захочет, чаще всего, это опять — быстро — «как-нибудь подлатать все баги»… Главная задача команды разработчиков в этом смысле — прямо на старте выработать четкую систему приемлемых и удобных для всех участников соглашений, которая с самого начала позволит писать максимально консистентный, понятный, и, самое главное, в идеале — и гибкий, и, одновременно, железно надежный код.
Среднестатистический разработчик-мракодел, тянущий лямку в капитализме никогда не возвращается к своему поспешному или даже откровенно, простите мой спесишизм, «индусскому» копипасте-коду для того чтобы улучшить его, кроме ситуаций, когда служба контроля качества вернула некий конкретный баг на доработку. И, конечно, тут совсем нельзя говорить о каком-либо структурном улучшении, так как подобные правки всегда носят не системный, а полностью локальный-частный характер «быстрых фиксов», «кряков» и только усугубляют беспорядок. Не дай бог трогать код по «уже закрытым таскам», «так ведь можно что-нибудь поломать!»... Среднестатистический разработчик-мракодел нацелен, прежде всего, на закрытие своих тасков-багов по трекеру и не интересуются общим состоянием проекта, приходящим чужим кодом. Полезные соглашения его напрягают, он игнорирует или даже активно противиться им. Кроме того, я заметил, что профессиональные мракоделы в командах и на проектах стремятся объединяться в устойчивые группы… Мракоделы копируют мракокод из файла в файл, из проекта в проект, покрывая друг-друга, ломая волю ПМов и регулярно рапортуя через них начальству которое не читает репо что «все почти готово, только кнопку нажать»... Мракоделы даже иногда дорастают до сеньоров и лидов. Тогда они начинают занимаются сомнительным оверинжинирингом, накручивая ненужные, но модные технологии, пока не оказывается что все сроки сорваны и клиент не получил того чего хотел, а код такой что заплатки негде ставить без поллитры не прочитать… Как простому верстальщику противостоять вселенскому мраку?
Далее будет изложена простая методика реализации гибкого и масштабируемого GUI веб-интерфейсов, доставки дизайна в код, аккуратное использование которой сводит на минимум возможности добавления низкопробного кода в проекты фронтенда, а также способно помочь более четко, сперва — оценить, и, в дальнейшем, организовать эффективную совместную работу. Вкратце, обобщая можно тезисно описать это как то, что вам нужно добиться от разработчиков участвующих в развитии проекта фронтенда соблюдения следующих основных моментов:
Все оформление вплоть до перекастомизаций необходимых сторонних модулей неукоснительно основано на константах-«атомах» и уже собираемых на их основе более сложных паттернах которые диктует ваш дизайн, руководство по стилю.
При первоначальной оценке интерфейс разбирается на компоненты: «молекулы» и «организмы», «шаблоны» в терминах атомарного дизайна. Элементы, виджеты, раскладки, общие лейауты, все кроме уже окончательных видов роутера — на которых собирается соответствующая макетам конечная реальная вьюха из этих переиспользуемых сущностей — формируют библиотеку компонент и тем самым уже минимально документируются для всей команды. Код автоматически становится намного более оптимальным чем при хаотичном «копипаста»-подходе когда «левая нога не знает что делает правая».
Даже на «отдельном проекте» нужно стараться организовывать компонентную архитектуру таким образом, как будто ваши @/src/components — находятся в удаленном репозитории — «UI-библиотеке», и, поэтому — недоступны для «обвязок» напрямую. Компоненты «реальных вьюх» [соответствующие дизайн-макетам], например на @/src/views во Vue или @/src/pages и @/src/layouts с Nuxt —должны взаимодействовать с UI-компонентами которые они просто «собирают, предоставляя данные» — исключительно через пропсы — через явно обозначенный интерфейс, а не «состоянием». Концептуально, это напоминает нам «инкапсуляцию» из «серьезного программирования», а практически будет приводить к тому что — стили за редким исключением будут сосредоточены практически только «в UI-компонентах», а вся бизнес-логика — совершенно точно исключительно на видах. Это еще и способно организовать работу более эффективно — участники «с хорошей версткой» могут, прежде всего — поставлять качественную разметку.
Часто встречающийся в современной корпоративной культуре случай когда, предположим, два разных отдела ведут разработку разных интерфейсов основанных на одной визуальной дизайн-системе — очевидно основной когда необходимо построить работу через общую библиотеку-модуль.
Антибиблиотека
UI Library Starter это точно не еще одна библиотека «готового на все UI». Это, прежде всего, концепт и пример системного подхода, которые могут позволить вам легко поддерживать свои собственные библиотеки только из необходимых компонент, чистого оптимального кода, сопровождаемого необходимой наглядной документацией и с оформлением точно согласующимся с руководством по стилю. Проект содержит некоторый минимальный набор готовых компонент именно в качестве примера. Это то, что встречается практически в любом большом интерфейсе: простые, базовые примеры — обертка для контента, сетки, и пара важных «дорогих» контролов: датапикер с диапазоном на одном листе и кварталами, обертка над сторонним селектом...
Мысли о том что написание хардкор-кода или, точнее, написание хардкор-кода еще и с помощью чужого, обычно практически полностью изолированного от остальной системы готового кода как-то помогает решать задачи бизнеса — нужно забыть. Возможно, какие-то тактические задачи, может быть, но точно — все равно ненадежно, и всегда — стратегически создает предпосылки для очень серьезных проблем в будущем, возможно, даже самом скором. Кроме того, исключает возможность получать удовольствие от работы для тех кто трудиться с вами параллельно или будет вынужден иметь дело с этим легаси в дальнейшем.
В этом смысле сама идея UI Library Starter противоположна концепции любой обычной популярной библиотеки где «все включено». Она не в том чтобы дать вам возможность лениться, бояться и тратить рабочее время неэффективно мучаясь трудными кастомизациями через !important с неизвестным результатом, другими адовыми кряками, превращая свои проекты в неведомы зверушки из скрытых под капотом чужих кривых поделок, нечитаемые лоскутные одеяла повторяющегося кода или запутанные описания одного и того же совсем по-разному, с позорно огромным опасным пулом зависимостей. Идея этого проекта в том, чтобы аккуратно помочь вам начать писать действительно оптимальный, понятный и задокументированный, гибкий и легко масштабируемый код, который вы сможете постоянно переиспользовать и улучшать.
Пример дочернего проекта использующего модуль-библиотеку.
Далее — простите мне странные вкрапления моего никакого английского в документации…)))
Getting Started
Installation
Скачайте код ui-library-starter и оформите его в отдельный репозиторий. При выборе имени для нового репозитория необходимо сразу убедиться в том, что оно не занято на npmjs.com. Пусть это будет ui-library-starter-test.
Или, в случае, если вы не планируете менять стиль проекта под свои собственные гайды, но, собираетесь поиграться или даже внести вклад в его развитие, например, предложив еще какие-то важные компоненты — сделайте форк, конечно же. Дальнейшие инструкции относятся к первому случаю — пилим свежую либу с кастомным стилем под конкретные задачи — в этом случае многие могут захотеть удалить эту документацию и почти все компоненты, чтобы не выполнять лишнюю кастомизацию.
$ npm install
Customization
README.md
Поправьте первую строчку в @/README.md:
# Ui-library-starter test project
package.json
Далее в @/package.json вам необходимо крайне аккуратно переписать актуальной информацией следующие поля, ничего не пропустив:
{ "name": "ui-library-starter-test", "description": "UI Library Starter Demonstration", "version": "0.1.0", "main": "dist/ui-library-starter-test.umd.min.js", "unpkg": "dist/ui-library-starter-test.umd.min.js", "jsdelivr": "dist/ui-library-starter-test.umd.min.js", "scripts": { "build": "rimraf ./src/static && cp -r ./docs/.vuepress/public ./src/static && vue-cli-service build --target lib --name ui-library-starter-test src/main.js" }, "author": "Levon Gambaryan", "license": "MIT", "homepage": "", "repository": { "type": "git", "url": "https://github.com/ushliypakostnik/ui-library-starter-test" }, "bugs": { "url": "https://github.com/ushliypakostnik/ui-library-starter-test/issues" }, "keywords": [] }
Обратите внимание на имя проекта в конце длинной команды деплоя build!
Documentation config
Перейдите к документации на VuePress и сконфигурируйте ее под себя @/docs/.vuepress/config.js:
module.exports = { locales: { '/': { lang: 'en-US', title: 'UI Library', description: 'Vue Component UI Library', }, }, themeConfig: { repoLabel: 'GitHub repo', repo: 'https://github.com/ushliypakostnik/ui-library-starter-test.git', docsDir: 'docs', search: false, locales: { '/': { nav: [{ text: '', link: '' }], sidebar: [ { title: `Components`, children: [ // ... готовые компоненты библиотеки без Sandbox и папки /Tests с тестовыми ], }, { title: `Sandbox`, path: '/sandbox/sandbox', }, ], }, }, }, };
Connecting fonts
Перепишите имя шрифта и переменные начертаний если требуется в файле ~/src/stylus/utils/_typography.styl:
$font-family = "Open Sans" $font-weight = { regular: 400, bold: 700, }
Поместите папку с правильным шрифтом рядом с папкой /Ubuntu в @/docs/.vuepress/public/fonts/.
Пропишите правильные импорты и пути в файле кастомизации документации на VuePress @/docs/.vuepress/styles/palette.styl/:
@import "../../../src/stylus/_stylebase.styl" // Import fonts ////////////////////////////////////////////////////// @font-face { font-family: $font-family; src: url('/fonts/OpenSans/OpenSans-Regular.eot'); src: local('Open Sans Regular'), local('OpenSans-Regular'), url('/fonts/OpenSans/OpenSans-Regular.eot?#iefix') format('embedded-opentype'), url('/fonts/OpenSans/OpenSans-Regular.woff') format('woff'), url('/fonts/OpenSans/OpenSans-Regular.ttf') format('truetype'); font-weight: $font-weight.regular; font-style: normal; } @font-face { font-family: $font-family; src: url('/fonts/OpenSans/OpenSans-Bold.eot'); src: local('Open Sans Bold'), local('OpenSans-Bold'), url('/fonts/OpenSans/OpenSans-Bold.eot?#iefix') format('embedded-opentype'), url('/fonts/OpenSans/OpenSans-Bold.woff') format('woff'), url('/fonts/OpenSans/OpenSans-Bold.ttf') format('truetype'); font-weight: $font-weight.bold; font-style: normal; } // Customization ////////////////////////////////////////////////////// ...
Удалите директорию со старым шрифтом @/docs/.vuepress/public/fonts/Ubuntu.
Сleaning project
Если вы хотите получить полностью чистую документацию — произведите следующую очистку папок и файлов.
Удалите все папки и файлы в @/docs/ кроме директорий @/docs/.vuepress, @/docs/components и @/docs/sandbox — если желаете оставить Песочницу. И файла @/docs/README.md, который нужно оставить, но очистить:
# UI Library ...
Удалите директорию @/src/components/tests.
Вычистите импорты тестовых компонент в индексном файле @/src/components/index.js:
// Tests - следующие три строчки удалить!!! export { default as TestColors } from './tests/TestColors'; export { default as TestBreakpoints } from './tests/TestBreakpoints'; export { default as TestTypography } from './tests/TestTypography'; // Elements ...
Вы можете выбрать какие компоненты оставить или даже удалить их все, если уверенны в себе и не нуждаетесь в наглядных примерах под рукой. Вернитесь к конфигурации документации и отразите изменения в @/docs/.vuepress/config.js.
Style setting
Запустите разработку документации командой:
$ npm run docs:dev
Прочитайте раздел Constants этой документации.
Вам необходимо настроить препроцессор вашей библиотеки в точном соответствии с вашим руководством по фирменному стилю.
Adding a component
После того как стили библиотеки настроены вы можете добавлять свои специфические компоненты.
Выберете имя для компонента в PascalCase стиле написания, предположим это ComponentName.
Некоторые имена могут оказаться зарезервированы VuePress. Layout, например. Самая достойная замена Layout видится как View.
Добавьте директорию @/src/components/ComponentName.
Добавьте в нее индексный файл c импортом-экспортом @/src/components/ComponentName/index.js:
import ComponentName from './ComponentName.vue'; export default ComponentName;
И сам компонент @/src/components/ComponentName/ComponentName.vue:
<template> <div class="component-name" :class="{ '.component-name__element--modifier1': prop1, '.component-name__element--modifier2': prop2, }" > This is test component!!! </div> </template> <script> export default { name: 'ComponentName', props: { prop1: { type: Boolean, required: true, }, prop2: { type: Boolean, required: false, default: false, }, }, }; </script> <style lang="stylus" scoped> @import "~/src/stylus/_stylebase.styl"; .component-name background $colors.primary // test styles // add adaptive +$mobile() display block &__element $text("natasha") // add typography &--modifier1 color $colors.primary // add good color &--modifier2 color $colors.secondary </style>
Добавьте экспорт в индексный файл библиотеки @/src/components/index.js:
export { default as ComponentName } from './ComponentName';
Добавьте документацию компонента в файл @/docs/components/component-name.md:
# ComponentName ## Description This is new custom component. ## Connection ```vue <template> <ComponentName prop1 /> </template> ``` ## Render <ComponentName prop1 /> ## API ### Props | **Name** | **Type** | **Description** | **Default** | | :-------- | :------- | :-------------- | ----------: | | **prop1** | Boolean | - | (required) | | **prop2** | Boolean | - | `false` | ## Source code <code>@/src/components/ComponentName/ComponentName.vue</code> <<< @/src/components/ComponentName/ComponentName.vue
И далее — рендер-тест и исходный код по аналогии с другими файлами.
Добавьте компонент в конфигурацию VuePress @/docs/.vuepress/config.js:
module.exports = { themeConfig: { locales: { '/': { sidebar: [ { title: `Components`, children: [ { title: `ComponentName`, path: '/components/component-name', }, ], }, ], }, }, }, };
Using third party modules
Используйте только относительные пути для импорта чего-либо в javascript ваших компонентов. Не используйте «абсолютные» алиасы:
<script> import { dateFilter } from '../../../node_modules/vue-date-fns/src/index'; import Icon from '../Icon/Icon'; export default { components: { Icon, }, }; </script>
В реальных проектах вам потребуется очень часто закрывать «самые дорогие требования» с помощью аккуратно подобранных подходящих готовых решений. В таких случаях логично будет создавать обертку над чужим модулем, предоставляющую всю необходимую кастомизацию. Пример этого: Select.
Установите и импортируйте модуль как обычно в главном файле @/src/main.js:
import vSelect from 'vue-select'; import 'vue-select/dist/vue-select.css'; Vue.component('v-select', vSelect);
Так как мы используем глобальные стили собственной кастомизации модуля — невозможно будет защитить стили перекастомизации в SFC-обертке с помощью scoped:
<style lang="stylus"> @import "~/src/stylus/_stylebase.styl"; .vs &__dropdown-toggle // ... // ... // ... </style>
Use the sandbox
Используйте специальный компонент @/src/components/Sandbox/Sandbox.vue и роут документации Sandbox как экспериментальную площадку и холст для создания новых компонент на простых мокках или тестирования взаимодействия между ними. Хотя, очевидно, некоторые компоненты, такие как, например, лейаут — удобнее создавать непосредственно в проекте и уже после этого переносить в библиотеку.
Library publishing
Зарегистрируйтесь на npmjs.com и подтвердите регистрацию (дождитесь письма на почту).
$ npm run build $ npm version patch $ npm publish
Connecting to projects
Вы можете либо использовать стартовый шаблон для новых проектов ui-library-start, тогда вам придется заменить библиотеку:
$ npm uninstall ui-library-starter --save-dev $ npm install ui-library-starter-test --save-dev
Либо установить библиотеку как любой другой модуль в любой другой проект:
$ npm install ui-library-starter-test --save-dev
Организация стилей дочерних проектов может или иметь подобную библиотеке структуру или любую другую (например, если вы внедряете бибилиотеку в старый проект). Единственное требование: первый импорт в основном файле — основного файла библиотеки. Второй — подключение шрифтов и стилизация :root и body.
@/src/stylus/_stylebase.styl проекта использующего библиотеку:
// Import UI Library stylebase @import '~ui-library-starter-test/src/stylus/_stylebase.styl'; // core @import "core/_base"; // normalize
@/src/stylus/core/_base.styl проекта использующего библиотеку:
// Import UI Library fonts @font-face { font-family: $font-family; src: url('~ui-library-starter-test/src/static/fonts/OpenSans/OpenSans-Regular.eot'); src: local('Open Sans Regular'), local('OpenSans-Regular'), url('~ui-library-starter-test/src/static/fonts/OpenSans/OpenSans-Regular.eot?#iefix') format('embedded-opentype'), url('~ui-library-starter-test/src/static/fonts/OpenSans/OpenSans-Regular.woff') format('woff'), url('~ui-library-starter-test/src/static/fonts/OpenSans/OpenSans-Regular.ttf') format('truetype'); font-weight: $font-weight.regular; font-style: normal; } @font-face { font-family: $font-family; src: url('~ui-library-starter-test/src/static/fonts/OpenSans/OpenSans-Bold.eot'); src: local('Open Sans Bold'), local('OpenSans-Bold'), url('~ui-library-starter-test/src/static/fonts/OpenSans/OpenSans-Bold.eot?#iefix') format('embedded-opentype'), url('~ui-library-starter-test/src/static/fonts/OpenSans/OpenSans-Bold.woff') format('woff'), url('~ui-library-starter-test/src/static/fonts/OpenSans/OpenSans-Bold.ttf') format('truetype'); font-weight: $font-weight.bold; font-style: bold; } // Base normalize :root scroll-behavior smooth body font-family $font-family, sans-serif -moz-osx-font-smoothing grayscale -webkit-font-smoothing antialiased text-rendering: optimizeSpeed color $colors.text overflow-x hidden
Практически единственный повод что-то поменять в этом файле — крайне маловероятная ситуация — замена или добавление шрифта в гайдлайн. Предполагается что отредактировать пути шрифтов придется только один раз — при подключении библиотеки под определенный стиль.
Подключите все это к главному шаблону @/src/App.vue:
<template> <div id="app"></div> </template> <script> export default { name: 'App', }; </script> <style lang="stylus"> @import "~/src/stylus/_stylebase.styl"; </style>
Исправьте имя библиотеки в импортах в точку входа @/src/main.js если вы брали готовый репо или подключите:
import ComponentLibrary from 'ui-library-starter-test'; import 'ui-library-starter-test/dist/ui-library-starter-test.css'; Vue.use(ComponentLibrary);
Исправьте имя или добавьте команду update в @/package.json:
{ "name": "ui-library-start-test", "scripts": { "update": "npm install ui-library-starter-test@latest" }, }
Updating in projects
Обновляйте библиотеку до последней версии в проектах:
$ npm run update
Constants
_stylebase.styl
Глобальный медиатор стилей собирает не компилируемые /utils, компилируемые /core сущности и необходимые глобально кастомизации используемых сторонних модулей /libs (но, те которые позволяют это сделать без scoped— стоит разместить в SFC-обертках).
@/src/stylus/_stylebase.styl библиотеки:
// utils @import "utils/_variables"; @import "utils/_placeholders"; @import "utils/_mixins"; @import "utils/_typography"; // core @import "core/_base"; // normalize @import "core/_animations"; // libs ...
Теперь можно использовать всю эту кухню на компонентах:
<style lang="stylus" scoped> @import "~/src/stylus/_stylebase.styl"; ... </style>
Это можно назвать «глобальными стилями-невидимками», что-то такое — они, с одной стороны — участвуют в правильном оформлении везде, но, при этом, «их не видно». Мы предоставляем глобальные константы гайдлайна и всю прочую мощь препроцессора всем компонентным системам — библиотеке и всем ее «читателям».
Mixins and placeholders
UI Library Starter дает надежду на то, что в вашей разметке код будет полностью оптимальный и консистентный. Это способно сделать даже крупную систему из нескольких проектов базирующихся на одном визуальном языке — и полностью управляемой, и, в тоже время — гибкой.
Не копируйте код кусками по компонентам — оптимизируйте очевидно одинаковые наборы в миксинах и плейсхолдерах!
Или вы можете делать примеси без параметров для того, чтобы — забегая вперед (см. раздел Breakpoints) — такой же набор стал доступен внутри медиа-миксинов @/src/stylus/utils/_mixins.styl:
// Utilities ////////////////////////////////////////////////////// // Mixins without arguments duplicate placeholders, // so it can be passed to media mixins $flex--center() display flex align-items center justify-content center
Теперь:
.selector +$tablet() $flex--center()
Colors
Абстрагируйте все цвета из гайдлайна в короткие имена-маркеры.
~/src/stylus/utils/_variables.styl:
// Palette ////////////////////////////////////////////////////// $colors = { cat: #515bd4, dog: #ffffff, bird: #fd5f00, wood: #fed564, stone: #8bc24c, sea: #13334c, } // Dependencies colors $colors["text"] = $colors.sea $colors["placeholder"] = rgba($colors.sea, $opacites.rock) $colors["primary"] = $colors.cat $colors["secondary"] = $colors.dog
В любом месте кода препроцессора или секции стилей SFC (при условии импорта стилевой базы) библиотеки или дочерних проектов вы можете передавать правильные цвета:
.selector color $colors.primary
Легко поддерживать тестовый компонент наглядно демонстрирующий палитру в @/src/components/tests/TestColors/TestColors.vue.
Breakpoints
Переменные-брекпоинты лучше называть более интуитивно-понятно.
~/src/stylus/utils/_variables.styl:
// Breakpoints ////////////////////////////////////////////////////// $breakpoints = { tablet: 768px, desktop: 1025px, } $breakpoints["mobile--max"] = $breakpoints.tablet - 1 $breakpoints["tablet--max"] = $breakpoints.desktop - 1
Основные точки перехода: в стилевой базе препроцессора в px и в константах скриптов библиотеки в Number — должны соответствовать друг-другу.@/src/utils/сonstants.js:
// Design constants ////////////////////////////////////////////////////// export const DESIGN = { BREAKPOINTS: { tablet: 768, desktop: 1025, }, };
В препроцессоре — мощнейшее, очень удобное средство — построенные на брекпоинтах примеси принимающие контент:
// Media ////////////////////////////////////////////////////// $no-gadgets() @media only screen and (max-width $breakpoints.desktop--max) {block} $desktop() @media only screen and (min-width $breakpoints.desktop) {block} $gadgets() @media only screen and (max-width $breakpoints.tablet--max) {block} $tablet() @media only screen and (min-width $breakpoints.tablet) and (max-width $breakpoints.tablet--max) {block} $not-mobile() @media only screen and (min-width $breakpoints.tablet) {block} $mobile() @media only screen and (max-width $breakpoints.mobile--max) {block}
Использование в любом блоке стилей SFC:
.selector +$desktop() // styles only for desktops +$tablet() // styles only for tablet +$mobile() // styles only for mobile
В строгой традиции запрещается использование любых глобальных классов со стилями, за исключением анимаций для Vue и вынужденных кастомизаций действительно необходимых сторонних модулей где «классический ад с !important»))). Мы стараемся минимизировать количество зависимостей и «точечно» закрываем самые «дорогие», неподъемные по ресурсам проблемные места.
Точки перехода скриптов обрабатываются специальным модулем-помощником для экрана через matchMedia:
// Viewport utils module ////////////////////////////////////////////////////// import { DESIGN } from './constants.js'; const ScreenHelper = (() => { const TABLET = DESIGN.BREAKPOINTS.tablet; const DESKTOP = DESIGN.BREAKPOINTS.desktop; const isMobile = () => { return window.matchMedia(`(max-width: ${TABLET - 1}px)`).matches; }; const isTablet = () => { return window.matchMedia( `(min-width: ${TABLET}px) and (max-width: ${DESKTOP - 1}px)`, ).matches; }; const isDesktop = () => { return window.matchMedia(`(min-width: ${DESKTOP}px)`).matches; }; const getOrientation = () => { if (window.matchMedia('(orientation: portrait)').matches) { return 'portrait'; } return 'landscape'; }; const getPixelRatio = () => { // eslint-disable-next-line prettier/prettier return ( window.devicePixelRatio || window.screen.deviceXDPI / window.screen.logicalXDPI ); }; return { isMobile, isTablet, isDesktop, getOrientation, getPixelRatio, }; })(); export default ScreenHelper;
Для того чтобы компоненты могли всегда верно определять типоразмер устройства предоставлена общая функциональность обновляющая переменные в событии ресайза. Этот миксин может быть невероятно полезен и на этапе конечной сборки адаптивных видов — в дочерних проектах.
@/src/mixins/resize.js:
import ScreenHelper from '../utils/screen-helper.js'; export default { data() { return { isMobile: null, isTablet: null, isDesktop: null, }; }, mounted() { window.addEventListener('resize', this.onWindowResizeCommon, false); this.onWindowResizeCommon(); }, beforeDestroy() { window.removeEventListener('resize', this.onWindowResizeCommon, false); }, methods: { onWindowResizeCommon() { // console.log('onWindowResizeCommon!!!!'); this.isMobile = ScreenHelper.isMobile(); this.isTablet = ScreenHelper.isTablet(); this.isDesktop = ScreenHelper.isDesktop(); }, }, };
На любых компонентах или видах в библиотеке:
<template> <Component v-show="isDesktop" /> <div v-if="isDesktop" /> </template> <script> import resize from '../../../src/mixins/resize.js'; export default { name: 'ComponentName', mixins: [resize], }; </script>
В проектах:
<script> import resize from 'ui-library-starter/src/mixins/resize.js'; export default { name: 'Test', mixins: [resize], }; </script>
Тестовый компонент в @/src/components/Tests/TestBreakpoints/TestBreakpoints.vue.
Typography
Абстрагируйте все гарнитуры из гайдлайна в короткие имена-маркеры.
~/src/stylus/utils/_typography.styl:
// Typography ////////////////////////////////////////////////////// ////////////////////////////////////////////////////// ////////////////////////////////////////////////////// // Typographic Variables ////////////////////////////////////////////////////// // Guide $font-family = "Ubuntu" $font-weight = { regular: 400, bold: 700, } $letter-spacing = { normal: normal } // Universal Typographic Mixin ////////////////////////////////////////////////////// // We use one, only one, Karl, a universal mixin for all cases! $text($name) font-family $font-family letter-spacing $letter-spacing.normal if $name == "elena" font-size 72px line-height 72px font-weight $font-weight.bold if $name == "olga" font-size 56px line-height 56px font-weight $font-weight.bold if $name == "anna" font-size 40px line-height 44px font-weight $font-weight.bold if $name == "maria" font-size 32px line-height 36px font-weight $font-weight.bold if $name == "katya" font-size 24px line-height 28px font-weight $font-weight.regular if $name == "alena" font-size 20px line-height 28px font-weight $font-weight.regular if $name == "natasha" font-size 16px line-height 28px font-weight $font-weight.regular if $name == "nina" font-size 13px line-height 16px font-weight $font-weight.regular
Others
~/src/stylus/utils/_variables.styl:
// Others from guide ////////////////////////////////////////////////////// $border-radiuses = { soccer: 0, dancing: 2px, swimming: 3px, shooting: 10px, } $opacites = { waltz: 1, funky: 0.75, rock: 0.66, psy: 0.45, pop: 0.2, reggae: 0, } $effects = { duration: 0.1s, }
Можно получить из этого миксины для более лаконичного синтаксиса ~/src/stylus/utils/_mixins.styl:
// Rounding ////////////////////////////////////////////////////// $border-radius($name) if $name == "soccer" border-radius $border-radiuses.soccer // 0 if $name == "dancing" border-radius $border-radiuses.dancing // 2px if $name == "swimming" border-radius $border-radiuses.swimming // 3px if $name == "shooting" border-radius $border-radiuses.shooting // 10px // Opacity ////////////////////////////////////////////////////// $opacity($name) if $name == "waltz" opacity $opacites.waltz // 1 if $name == "funky" opacity $opacites.funky // 0.75 if $name == "rock" opacity $opacites.rock // 0.66 if $name == "psy" opacity $opacites.psy // 0.45 if $name == "pop" opacity $opacites.pop // 0.2 if $name == "reggae" opacity $opacites.reggae // 0
Теперь можно:
.selector $opacity("dancing") $border-radius("funky")
Переменные все равно могут пригодиться если дизайнеры захотят сделать новый цвет с разрешенной прозрачностью:
.selector color rgba($colors.dog, $opacites.psy)
Анимации
Единственные глобально компилируемые стилевые классы которые в строгой традиции разрешено использовать — для анимаций Vue. Вы можете добавлять их после соответсвующих @keyframes в специальном файле стилевой базы ~/src/stylus/core/_animation.styl:
// Project animations ////////////////////////////////////////////////////// ////////////////////////////////////////////////////// ////////////////////////////////////////////////////// // Keyframes ////////////////////////////////////////////////////// @keyframes fade 0% opacity 0 100% opacity 1 // Vue classes for animation ////////////////////////////////////////////////////// .fade &-enter-active animation fade ($effects.duration * 2) forwards &-leave-active animation fade ($effects.duration * 2) reverse
Теперь в разметке:
<template> <transition name="fade"> <div v-if="Boolean" /> </transition> </template>
Structure
. ├─ docs/ // documentation folder │ ├── .vuepress/ // VuePress │ │ ├─ stylus/ // import of fonts and customization of documentation │ │ │ └─ palette.styl │ │ ├─ config.js // configuration │ │ └─ enhanceApp.js // improvements - installation of library components │ ├─ components/ // components documentation folder │ │ ├─ link.md │ │ └─ ... │ ├─ constants/ // library documentation folder │ │ ├─ breakpoints.md │ │ ├─ colors.md │ │ ├─ others.md │ │ ├─ stylebase.md │ │ └─ typography.md │ ├─ sandbox/ // sandbox view │ │ └─ sandbox.md │ ├─ links.md // useful reading links │ ├─ README.md // homepage │ ├─ start.md // getting started │ └─ structure.md // structure ├─ src/ // source folder │ ├─ components/ │ │ ├─ Icon │ │ │ ├─ index.js │ │ │ └─ Icon.vue │ │ ├─ Sandbox │ │ │ ├─ index.js │ │ │ └─ Sandbox.vue │ │ ├─ Tests │ │ │ └─ ... │ │ └─ ... │ ├─ mixins/ │ │ ├─ resize.js // adaptive to components │ │ └─ ... │ ├─ static/ // after build fonts will be copied here │ │ └─ fonts/ │ │ └─ ... │ ├─ stylus/ │ │ ├─ core │ │ │ ├─ _animations.styl // keyframes and Vue animationss classes │ │ │ └─ _base.styl // normalize │ │ ├─ utils │ │ │ ├─ _mixins.styl │ │ │ ├─ _placeholders.styl │ │ │ ├─ _typography.styl // Use one, only one, Karl, a universal mixin for all cases! │ │ │ └─ _variables.styl │ │ └─ _stylebase.styl // main file of stylus │ ├─ utils/ // scripts │ │ ├─ constants.js // javascript constants │ │ ├─ screen-helper.js // adaptive viewport │ │ └─ ... │ └─ main.js // library connection ├─ .browserslistrc // configuration of supported browsers ├─ .eslintrc.js // linter configuration ├─ .gitignore // git ignore ├─ .prettierrc // prettier configuration ├─ babel.config.js // babel configuration ├─ colors.jpg // image for README ├─ package.json // project configuration └─ README.md ```
Мы сегодня многое поняли
Чистый код начинается с четких концепций и годной архитектуры, эффективная работа команды — с аккуратной коммуникации и внятных соглашений. Я потратил всего один вечер для того чтобы написать сам пример модуля-библиотеки на Vue со Stylus (без компонент). Точно тоже самое можно быстро легко осуществить для связки любого современного компонентного фреймворка и препроцессора. Даже если вы не хотите, или по каким-то внешним причинам — не можете — выделить атомарный и подробно-компонентный UI своего интерфейса в модуль-библиотеку, изложенные выше подходы все равно способны помочь вам и вашей команде писать действительно красивые и удобные проекты фронтенда с по-настоящему качественной версткой.
Удачи в написании собственных библиотек!
@@
