Vue Styleguidist

# Документирование компонентов

Vue Styleguidist генерирует документацию компонентов на основе комментариев в исходном коде и файлов Readme.

Примечание: Посмотрите примеры задокументированных компонентов в демо Styleguidist.

# Комментарии к коду

Vue Styleguidist отобразит стандартные блоки комментариев JSDoc ваших компонентов.

Примечание. Компоненты и комментарии к документации по умолчанию анализируются библиотекой vue-docgen-api. Вы можете изменить это поведение, используя параметры propsParser.

<template>
  <div class="Button">/* ... */</div>
</template>

<script>
  /**
   * The only true button.
   * @displayName Best Button
   */
  export default {
    name: 'Button',
    props: {
      /**
       * The color for the button.
       */
      color: {
        type: String,
        default: '#333'
      },
      /**
       * The size of the button
       * @values small, normal, large
       */
      size: {
        type: String,
        default: 'normal'
      },
      /**
       * Gets called when the user clicks on the button
       */
      onClick: {
        type: Function,
        default: event => {
          console.log('You have clicked me!', event.target)
        }
      }
    }
    /* ... */
  }
</script>

Обратите внимание на использование тега @displayName для изменения отображаемого имени вашего компонента. Этот блок комментариев верхнего уровня должен располагаться перед export default в теге скрипта.

Если вы хотите задокументировать пользовательскую v-model (opens new window), вам необходимо добавить тег model в комментарий.

<script>
  export default {
    name: 'my-checkbox',
    props: {
      /**
       * @model
       */
      value: String
    }
  }
</script>

# Доступные теги

Вы можете использовать следующие теги при документировании компонентов, пропсов и методов.

# @values

Распространенным шаблоном в компонентах Vue.js является наличие ограниченного набора допустимых значений пропса.

Например, size будет принимать только small, medium и large.

Чтобы задокументировать это в Styleguidist, используйте тег @values:

export default = {
    props: {
      /**
       * The size of the button
       * @values small, normal, large
       */
      size: {
        type: String,
        default: 'normal'
      }
    }
}

См. также:

# @example

Приведите пример того, как использовать документированный элемент. Текст, следующий за этим тегом, будет отображаться как выделенный код.

См. также:

# @deprecated

Тег @deprecated помечает сущность в коде как устаревшую:

/**
 * An example-less button.
 * @deprecated Use the [only true button component](#button) instead
 */

См. также:

# @author

# @since

# @version

# @ignore

По умолчанию все свойства ваших компонентов считаются общедоступными и публикуются. В некоторых случаях вы можете удалить свойство из документации, сохранив его в коде. Тег @ignore позволяет это сделать. Подробнее см. здесь:

# События

Для документации о событиях добавьте комментарий прямо над ним. Если ваш комментарий находится в начале функции, событие не будет обнаружено.

# В блоке скриптов

Если имя события указано явно, ничего дополнительно указывать не нужно.

/**
 * Success event.
 */
this.$emit('success')

Константы также распознаются.

/**
 * Success event.
 */
const success = 'succ'
this.$emit(success)

Если имя вашего события происходит от объекта, укажите тег @event.

/**
 * Success event.
 *
 * @event success
 */
this.$emit(EVENTS.success)

Если событие передает аргументы, используйте тег @property для их описания.

Используйте @arg или @param, если хотите.

/**
 * Triggers when the number changes
 *
 * @property {number} newValue new value set
 * @property {number} oldValue value that was set before the change
 */
this.$emit('change', newValue, oldValue)

# В шаблоне

События, созданные непосредственно в выражениях v-on, будут обнаружены автоматически. Чтобы документировать их дальше, в заголовке шаблона приводится над строкой, где появляется $emit().

Блок комментариев, включенная документация, должен сохранять один текст с @event click. Остальная часть блока комментариев будет вести себя так же, как блоки комментариев, описанные в скрипте.

@property для описания аргументов и вообще без тега для описания событий.

<div>
  <!--
    triggered on click
    @event click
    @property {object} demo - example
    @property {number} called - test called
  -->
  <button @click="$emit('click', test)"></button>
</div>

# Слоты

Статические слоты автоматически документируются с помощью styleguidist.

# В шаблоне

Чтобы добавить описание, добавьте комментарий прямо перед этим.

<template>
  <div class="modal">
    <div class="modal-container">
      <div class="modal-head">
        <!-- @slot Use this slot header -->
        <slot name="head"></slot>
      </div>
      <div class="modal-body">
        <!-- @slot Use this slot body -->
        <slot name="body"></slot>
      </div>
    </div>
  </div>
</template>

Помимо документирования слотов и их описания, вы можете документировать привязки. Они документируются как propы или параметры с использованием ключевого слова @binding,

Тогда формат будет

<!--
  @binding {type} BindingName description of what the bindings is meant for
  -->

пример реального задокументированного слота

<div slot-scope="row" class="list-item1">
  {{row.item.text}}
  <!--
  	@slot Menu Item footer
		@binding {object} icon icon of the menu item
		@binding {string} text text of the menu item
	-->
  <slot name="test" :icon="row.item.icon" :text="row.item.text" />
</div>

Чтобы углубиться, ознакомьтесь с компонентом ScopedSlot в базовом исходном коде. Прочтите код (opens new window) и прочтите, как он отображается в живом примере (opens new window).

Примечание. Документационный блок должен быть частью того же блока комментариев. Несколько отдельных комментариев не анализируются вместе.

Примечание 2. Начиная с версии 4.44.0 вы можете использовать блоки комментариев JS, если захотите. Синтаксис такой же, как в HTML. Одно ограничение: комментарий должен быть единственным содержимым интерполяции:

  • Действительный комментарий:
  • Неверный комментарий: NaN.

# В функции рендеринга

Если ваш компонент визуализируется с использованием jsx, tsx или функции рендеринга, styleguidist все равно будет отображать ваши слоты.

Вот два примера, которые были обнаружены и задокументированы:

Определить слот по умолчанию

export default {
  render(createElement) {
    return createElement('div', [
      /**
       * @slot The header
       * @binding {object} menuItem the menu item
       */
      this.$scopedSlots.default({
        menuItem: this.message
      })
    ])
  }
}

В функциональном компоненте:

export default {
  functional: true,
  render: function (createElement, { data, children: cld }) {
    /* @slot describe destructured default */
    return createElement('div', data, cld)
  }
}

Если Vue Styleguidist не обнаруживает ваши слоты, вы можете явно сообщить об этом с помощью блока комментариев перед рендер-функцией:

export default {
  /**
   * Place the content of your menuitem here,
   * the value of index and content will be passed down to you
   * @slot menuContent
   * @binding {number} index the index in the list
   * @binding {string} content text of the item
   */
  render: function () {
    // ...
  }
}

Если у вас несколько слотов, размещайте несколько блоков один за другим:

export default {
  /**
   * @slot content
   */
  /**
   * @slot icon
   */
  render: function () {
    // ...
  }
}

# Включить миксины и расширения

Если вы импортируете mixin (opens new window) или extends (opens new window), он будет автоматически добавлен в ваш основной компонент.

# Примеры использования и файлы Readme

Vue Styleguidist будет искать любые файлы Readme.md или ComponentName.md в компоненте компонента и отображать их. Любой блок кода с языковым тегом vue, js, jsx, javascript или html будет PHP как компонент Vue с интерактивной игровой площадкой.

Благодаря поддержке MDX, Vue Styleguidist по умолчанию также ищет Readme.mdx и ComponentName.mdx.

Если вам нужен файл readme для одного компонента, используйте документ @example [none]. Используйте это, когда несколько компонентов в одном экземпляре совместно используют файл ReadMe. Это собственное многократное применение.

Пример компонента Vue:

```jsx
    <Button size="large">Push Me</Button>
```

Еще один с общим забором кода:

```
<Button size="large">Push Me</Button>
```

Вы можете включить редактор, передав модификатор noeditor:

```jsx noeditor
<Button>Push Me</Button>
```

Чтобы отобразить пример выделенного исходного кода, модификатора страниц static:

```jsx static
<Button>Push Me</Button>
```

Вы также можете реализовать идею vue для создания более сложных примеров двух методов:

  1. Создать новый экземпляр Vue

    const names = require('dog-names').all;

new Vue({
  data(){
    return {
      list: names
    }
  },
  template: `
    <div>
      <RandomButton :variants="list" />
    </div>
  `
})

  2. Однофайловые компоненты с языковым тегом vue (поддерживает

← MDX →