Узрите, Документатор Компонента Vue… Компонент
Автор Ян Джонсон, старший инженер по фронтенду в Skilljar
Рассматриваемый Vue Documenter, чтобы вы могли следить за ним дома -
- NPM - https://www.npmjs.com/package/vue-documenter
- GitHub - https://github.com/theianjohnson/vue-documenter
Я один из трех интерфейсных инженеров в нашей команде, состоящей из примерно десятка бэкенд-инженеров, а это значит, что при развертывании компонентов всей команды нужно поддерживать гораздо больше, чем мы сами. буду использовать.
Имея в виду? Drumroll, ведение некоторой формы документации по всем нашим компонентам стало необходимостью (для нашего здравомыслия)… в противном случае мы являемся документацией. И если вы когда-нибудь тратили время на ответы на вопросы о Slack о том, какие свойства входят в какой компонент, это не супер-масштабируемый.
Вы говорите документацию?
"Легкий!" вы думаете, что «там уже есть куча документалистов!»
Нравиться:
- Https://storybook.js.org/docs/guides/guide-vue/ (генератор статических сайтов)
- Https://vuepress.vuejs.org/guide/ (генератор статических сайтов)
- Https://vue-styleguidist.github.io (генератор статических сайтов)
- Https://www.npmjs.com/package/vue-documentor (требуется Vue Router)
- Https://github.com/viljamis/vue-design-system/wiki (построено на основе нескольких других пакетов, но более полно)
И это здорово! Но Skilljar еще не живет полностью в Vue-land (Vueville? E-Vue?) - мы живем в большом, уже существующем проекте jQuery и Django (фреймворк Python), в который мы постепенно внедряем Vue.
Медленно.
И поскольку мы еще не используем Vue Router или Vuex, а добавление инструмента для создания статических сайтов просто не принесет успеха, когда у всех есть реальная работа, которую нужно выполнить, мы приходим к моему любимому типу решения - простому , вставной компонент. Это выводит… компоненты. Эээ ...
Я вам просто покажу.
Ты волшебник, Арри
(Потому что это похоже на волшебство. Клянусь, это круто)
Учитывая такую простую вещь:
// YourVueDocumentationPage.vue <template> <div> <vue-documenter> <sj-datatable></sj-datatable> <sj-calendar></sj-calendar> </vue-documenter> </div> </template> <script> import VueDocumenter from 'vue-documenter'; import SjDatatable from './components/Datatable.vue'; import SjCalendar from './components/Calendar.vue'; export default { components: { VueDocumenter, SjDatatable, SjCalendar, }, data () { return {} } } </script>
Vue Documenter выведет что-то вроде этого примера нашего компонента Datatable.vue:
И для нашего компонента Calendar.vue, который генерирует одно событие date-selected
:
Наконец-то! Решение, которое дает всем нашим компонентам минимум документации без каких-либо дополнительных усилий.
Почти… без усилий?
"Хромой", я вижу, вы думаете, что я не подписывался на усилие.
Но обещаю, этого совсем немного! Вам нужно только добавить немного метаданных к компонентам, которые вы хотите задокументировать, чтобы заполнить то, что Vue Documenter не может проанализировать на лету, и БАМ! ™
Усилия tl; dr
- Имя компонента: сопоставьте свойство имени компонента (в PascalCase) с тем, как вы регистрируете его в своем приложении (в случае kebab), чтобы Vue Documenter мог правильно сгенерировать пример
<tag></tag>
. - Метаданные компонента: добавьте метаданные к самому компоненту для событий и слотов.
- Метаданные свойства: добавьте в свойства компонента некоторые метаданные для его значения по умолчанию, примера и обязательных / устаревших флагов.
Effort kol; bpd (вроде длинное, но довольно подробное)
C название компонента
Вы должны определить (и сопоставить) свойство name
компонента с тем, что вы регистрируете в своем приложении, то есть:
Это свойство ComponentA
name в вашем ComponentA.vue
<script> export default { name: 'ComponentA', // Vue Documenter will generate <component-a> ... </component-a> data() { // etc } } </script>
C метаданные компонента (необязательно)
Есть несколько вещей, которые мы просто не можем извлечь из компонента, загрузив его и проанализировав, поэтому, чтобы получить события и слоты в нашей документации, давайте добавим несколько безопасных свойств на уровне компонента (см. Полужирный шрифт ниже).
// Datatable.vue export default { name: 'SjDatatable', // Our magic meta: { events: [{ name: 'date-selected', on: 'click', example: '2019-02-11', }], slots: { default: { type: 'component', valid: ['ValidComponent', 'AnotherValidComponent'], }, named: [ { name: 'some-slot-name', type: 'html' } ], }, }, // etc }
Примечание. В настоящее время поддерживается только ограниченная поддержка свойств слотов type
и valid
, но в будущем я добавлю больше, когда мы увидим, к чему это приведет.
P метаданные rop (частично необязательно)
«Полу» часть означает только, что все свойства вашего компонента должны быть объектами с их свойствами type
и default
- а теперь - (необязательная часть) с новым свойством meta
!
// Datatable.vue props: { apiEndpoint: { type: String, // Standard Vue default: '', // Standard Vue // Our magic meta: { example: '/api/v1/users', required: true, // deprecated: 'Message explaining deprecation reason', }, }, // etc }
Передайте свои компоненты (довольно необязательно)
Единственный фактически обязательный шаг здесь - передать ваши компоненты в <vue-documenter> ... </vue-documenter>
Примерно так (в основном тот же фрагмент примера с самого начала):
// YourVueDocumentationPage.vue <template> <div> // Our magic <vue-documenter> <sj-datatable></sj-datatable> <sj-calendar></sj-calendar> </vue-documenter> </div> </template> <script> import VueDocumenter from 'vue-documenter'; import SjDatatable from './components/Datatable.vue'; import SjCalendar from './components/Calendar.vue'; export default { components: { VueDocumenter, SjDatatable, SjCalendar, }, data () { return {} } } </script>
Вот так и крошится печенье. Следите за новостями в следующий раз, когда я просто объясню, как я перенес эту вещь из локального компонента в опубликованный компонент NPM, который будет потреблен миром, потому что мальчик был этим кластером.
Хотите узнать больше о Skilljar? Посетите нас на https://www.skilljar.com/. Мы будем рады поговорить с вами, если вы хотите присоединиться к нашей команде. Вы можете узнать больше об открытых вакансиях на странице https://www.skilljar.com/about/careers/.