moyashidaisuke's diary

フリーランスのエンジニアのダイスケです。プログラム関連とかギター関連とか旅行関連とか色々。

【vue】Vue Styleguidistの使い方を説明② 〜Sections〜

f:id:moyashidaisuke:20191004235126p:plain

概要

前回はとりあえずVueStyleguildを動かすところまで解説しました。 今回はページの設定である「Sections」の解説をします。

前回の www.moyashidaisuke.com

マニュアル

ここです。

vue-styleguidist.github.io

ベース

最初は前回の解説で使ったとりあえず動く設定から。styleguide.config.jsです。

const VueLoaderPlugin = require('vue-loader/lib/plugin')
module.exports = {
  webpackConfig: {
    module: {
      rules: [
        // Vue loader
        {
          test: /\.vue$/,
          exclude: /node_modules/,
          loader: 'vue-loader'
        },
      ]
    },
    plugins: [
      // add vue-loader plugin
      new VueLoaderPlugin()
    ]
  },

  components: 'resources/js/components/**/[A-Z]*.vue',
}

この段階ではこんな見た目です。

f:id:moyashidaisuke:20191005223317p:plain

sections

いきなりマニュアルと順番が違いますが、多分この順番がわかりやすいです。

そもそもsectionってなんぞや、なのですが、既に動いているデモがあります。

vue-styleguidist.github.io

このサイドバーを見たらわかりやすいのですが、コンポーネントをグルーピングしつつ、階層構造にする事ができます。このグルーピングされてる一つ一つがsectionです。

f:id:moyashidaisuke:20191005223852p:plain

sectionsの設定も、この階層構造を表現できるようになっています。

例えば

sections: [
    {
      name: '階層1',
      components: 'resources/js/components/**/[A-Z]*.vue',
      sections: [
        {
          name: '階層2-1',
          components: 'resources/js/components/**/[A-Z]*.vue',
        },
        {
          name: '階層2-2',
          components: 'resources/js/components/**/[A-Z]*.vue',
        },
      ],
    },
    {
      name: '階層a',
      components: 'resources/js/components/**/[A-Z]*.vue',
      sections: [
        {
          name: '階層a-1',
          components: 'resources/js/components/**/[A-Z]*.vue',
        },
        {
          name: '階層a-2',
          components: 'resources/js/components/**/[A-Z]*.vue',
        },
      ],
    },
  ]

とすると、こんな感じになります。 (nameとかcomponentsは後で説明します)

f:id:moyashidaisuke:20191005224500p:plain

以降説明する設定は、基本的にこのsectionsの中のobjectに対して設定していく事になります。

name, description

簡単なのでまとめて。

module.exports = {
  sections: [
    {
      name: 'nameだよ',
      description: 'descriptionだよ',
      components: 'resources/js/components/**/[A-Z]*.vue',
      sections: [
        {
          name: 'nestしたsectionのnameだよ',
          description: 'nestしたsectionのdescriptionだよ',
          components: 'resources/js/components/**/[A-Z]*.vue',
        },
      ]
    },
  ]
}

見た目

f:id:moyashidaisuke:20191006225932p:plain

サイドバーにも第2階層以降のnameは表示されます。

components、ignore

この2つはセットで、sectionの対象とするとコンポーネントへのpathを設定します。 componentsがホワイトリスト、ignoreはブラックリストです。componentsに含まれていて、ignoreに含まれていないものが対象となります。

どちらも、stringと配列の両方をうけとるので、

{
      components: 'lib/components/ui/*.vue',
      ignore: 'lib/components/ui/ignoreComponent.vue',
}
{
      components: ['lib/components/ui/*.vue'],
      ignore: ['lib/components/ui/ignoreComponent.vue'],
}

どちらでもいけます。が、後から増やそうと思ったときに手間なので、最初から配列に統一した方が良いと思います。

なお、pathの指定はglob patternというもので指定します。

詳しくはこちら。

github.com

content

name、descriptionと各コンポーネントの説明の間にoverview(概要)として任意のmarkdownファイルを指定できます。

  sections: [
    {
      name: 'nameだよ',
      description: 'descriptionだよ',
      components: 'resources/js/components/**/[A-Z]*.vue',
      content: 'doc/test.md', // これ
      sections: [
        {
          name: 'nestしたsectionのnameだよ',
          description: 'nestしたsectionのdescriptionだよ',
          components: 'resources/js/components/**/[A-Z]*.vue',
        },
      ]
    },
  ]

doc/test.md

# test.md h1

test.md本文

f:id:moyashidaisuke:20191006231128p:plain

usageMode

PROPS, METHODS, EVENTS & SLOTS の部分の事がusageModeです。

collapse(デフォルト)

javascript

  sections: [
    {
      name: 'nameだよ',
      description: 'descriptionだよ',
      components: 'resources/js/components/**/[A-Z]*.vue',
      usageMode: 'collapse',
    },
  ]

f:id:moyashidaisuke:20191006232006p:plain

↑をクリックすると

f:id:moyashidaisuke:20191006232021p:plain

hide

  sections: [
    {
      name: 'nameだよ',
      description: 'descriptionだよ',
      components: 'resources/js/components/**/[A-Z]*.vue',
      usageMode: 'hide',
    },
  ]

f:id:moyashidaisuke:20191006232204p:plain

リンクすらでなくなります。

expand

  sections: [
    {
      name: 'nameだよ',
      description: 'descriptionだよ',
      components: 'resources/js/components/**/[A-Z]*.vue',
      usageMode: 'expand',
    },
  ]

最初から展開された状態で表示されます。

f:id:moyashidaisuke:20191006232317p:plain

個人的にはこれがデフォルトでいいんじゃないの・・?と思います。

exampleMode

まず、exampleなのですが、何もしないと「Add examples to this component」というメッセージが画面に表示されていて、クリックすると下記のメッセージが出ます。

Create Readme.md or TestComponent.md file in the component’s folder like this:

TestComponent example:

指定のファイル名でmarkdownファイルを作ると、使用例とともに実際に動くコンポーネントをドキュメントに挿入する事ができます。

こんな感じです。

f:id:moyashidaisuke:20191006231613p:plain

ここもusageModeと同じく、collapse、hide、expandが指定できます。 やっぱりなぜかcollapseがデフォルトです、、、

href

外部リンクを作成できます。

  sections: [
    {
      name: 'nameだよ',
      description: 'descriptionだよ',
      components: 'resources/js/components/**/[A-Z]*.vue',
      sections: [
        {
          name: '外部リンク',
          href: 'https://www.google.jp',
          external: true,
        },
      ]
    },
  ]

f:id:moyashidaisuke:20191006233047p:plain

クリックすると別タブでgoogleが開きます。

externalは別ウインドウで開くかどうからしいのですが、指定無し、falseにしても挙動は同じでした。謎。

sectionDepth

pagePerSection とセットで使います。

vue-styleguidist.github.io

まず、pagePerSectionですが、デフォルトのfalseの場合、全sectionの内容が1ページに表示されます。これをtureにすると、sedtion毎にページが分かれて表示されます。(実際にはフィルタリングされて非表示になるだけなのだけど)

で、その時にさらにsectionsがネストして階層化されている時に、どこまでを1ページに設定するかがsectionDepthです。

ここはマニュアルに詳しく例がのってるので、試してみるとわかりやすいです。

以上、sectionsの内容を頑張って一通り解説しました。

実は、これはsectionsに設定できる項目だけで、全体に設定できるものはたくさんあります。

vue-styleguidist.github.io

全部説明するとドキュメントの日本語訳作った方が早いので、個人的に設定した方が良いと思うものだけ解説できたらと思っています。(いつかは未定、、、