Узрите, Документатор Компонента Vue… Компонент

Автор Ян Джонсон, старший инженер по фронтенду в Skilljar

Рассматриваемый Vue Documenter, чтобы вы могли следить за ним дома -

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

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

Вы говорите документацию?

"Легкий!" вы думаете, что «там уже есть куча документалистов!»

Нравиться:

И это здорово! Но 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/.