角度成分の文書化:物語

開発者として、私たちの日々の仕事の中で、我々は使用するライブラリと技術の良いドキュメントを見つけるのが好きです.したがって、私たちの責任は、我々の仕事をうまく文書化することです.私たちがそれを使用して、そして/またはそれを継続するために来る人々はそれを評価します.apiumhubで我々は非常に我々のプロジェクトを文書化するのが好きです.
Markdown (. md )形式でドキュメントを書くことができるツールや、UIコンポーネントをドキュメント化するためのツールもたくさんあります.それらのほとんどが書かれ、反応のために焦点を当てた.私たちの角度プロジェクトのコンポーネントを文書化したい場合はどうなりますか?
私たちのUIコンポーネントを文書化する最も人気のあるツールの一つはStorybookです.それは独立して再利用可能な方法で私たちのUIライブラリを作成するための理想的なツールです.また、コンポーネントと相互作用することができる少数のうちの1つです.そして、そのクリエイターは、それが角度が含まれているコンポーネント駆動型アーキテクチャに従う複数のフレームワークに焦点を当てていると主張していますが、真実は、角度のコンポーネントの話を使用して、JSXに基づいていることです.MDXファイル(マークダウンとJSXを組み合わせた形式)は、彼らが主張するほど簡単ではありません、いくつかの機能が動作しない、角のための童話のドキュメント自体もいくつかの例は、ネット上で簡単にチェックを書いている場合、我々は、我々は多くの角度の開発者が共通の問題に遭遇する実現:混乱とソリューションの欠如を実現します.

絵本を使う

いくつかの例を見せてみましょう.
私たちは、以下のコマンドで、我々の角のプロジェクトルートからストーリーブックをインストールします

npx sb init

すべてがうまくいけば、NPMの実行ストーリーブックコマンドは、私たちの物語を実行する必要があります.我々も、それを見ます.ストーリーブックフォルダーは、プロジェクトのルートにいくつかの設定ファイルを内部に作成されています.この記事を書く時に使われる絵本のバージョンはv 6です.4.9 .このバージョンでは、すでに自動的にインストールされ、compodocs、我々のプロジェクトを分析し、我々が適応し、使用できる自動ドキュメントを生成するツールを設定します.これは以前のバージョンでは起こりませんでした.
物語は、コンポーネントの状態のキャプチャです.これは、我々が表示したいコンポーネントの状態として多くのストーリーを作成することを意味します.Storybookは既にインストールされた例をいくつか紹介してくれました.プライマリボタンの例で作業します.

import { Story, Meta } from '@storybook/angular/types-6-0';
import Button from './button.component';

export default {
 title: 'Components/UI/CSF Stories',
 component: Button,
 argTypes: {
   backgroundColor: { control: 'color' },
 },
} as Meta;

const Template: Story<Button> = (args: Button) => ({
 props: args,
});

export const Primary = Template.bind({});
Primary.args = {
 primary: true,
 label: 'Button',
};

プライマリは私たちの最初の話であり、それはタイトルのパラメータで示されたパスの下の左側のメニューに表示されます.キャンバスタブでは、指定された状態のコンポーネントとドキュメントタブで、異なるプロパティを編集し、現在の状態を変更するには、リアルタイムで編集できます.興味深いことに、現在の状態でコンポーネントを使用するコードが表示されます.
今すぐ興味深い部分に直面しましょう:我々はMDX形式でマークダウンコードを書くことができますし、私たちに合った時にストーリーを埋め込む.2つの方法があります.

前に見たことがあるとして、以前に見たことがありますし、私たちに合ったときに、各ストーリーを呼び出すMDXファイルを作成すると、以前はCSF(コンポーネントストーリー形式)でストーリーを作成します.この方法でMarkdownを書くと、左側のメニューのCSFとMDXを持ちます.

import { Meta, Story } from '@storybook/addon-docs';

<Meta title="Components/UI/Embedded stories" />

# Embedded Stories

Lorem ipsum

## Primary button
<Story id='components-ui-csf-stories--primary'></Story>

IDは各ストーリーのURLにあります.

はるかにエレガントで強力な方法は、MDXに直接物語を書くことです.このようにして、メニューの項目が表示されます.メニューの項目は、メニューのサブメニューの形で、その内部に作成されたすべてのストーリーで、そのコンポーネントをキャンバスタブの下に配置します.docsタブの下にはMDXの内容があり、メニューを通してナビゲーション可能になります.純粋な優雅さ.

import { Meta, Story, ArgsTable } from '@storybook/addon-docs';
import Button from './button.component';

<Meta title="Components/UI/MDX Stories" component={Button} />

export const Template = (args) => ({ props: args });

# MDX Stories

Lorem ipsum

## Primary button

<Canvas>
 <Story
   name="Primary"
   args={{
     primary: true,
     label: 'Button',
   }}>
   {Template.bind({})}
 </Story>
 <ArgsTable story='Primary' />
</Canvas>

ArgSstableは、コンポーネントの状態を変更し、コンポーネントを使用するコードを表示できるようにする引数ボックスを表示します.
しかし、我々が現在最後のケースをもう少し見るならば、ちょっと複雑ですか?ControlValueAccessorを実装するコンポーネントがあることを想像しましょう.また、フォームグループの形式でラッパーを必要とするコンテキストを作成する必要があります.そのコンポーネントは、ラベルパラメータとFormControlNameによって制御される値で、古典的なスイッチボタンです.物語はこんな感じです.

import {moduleMetadata} from "@storybook/angular";
import {FormBuilder, FormControl, FormsModule, ReactiveFormsModule} from "@angular/forms";
import {Story} from "@storybook/angular/types-6-0";
import {SwitchComponent} from "./switch.component";

export default {
 title: 'Switch',
 component: SwitchComponent,
 decorators: [
   moduleMetadata({
     declarations: [SwitchComponent],
     imports: [FormsModule, ReactiveFormsModule],
   })
 ]
};

export const SwitchStory: Story = () => {
 let formGroup = new FormBuilder().group({
   agree: new FormControl()
 });
 const label = 'Switch label';

 return {
   template: `<form [formGroup]="group">
               <switch [label]="label" [formControlName]="controlName"></switch>
              </form>`,
   props: {
     group: formGroup,
     controlName: 'agree',
     label
   }
 }
}

@ storybook/角ライブラリからModulemetMatadataを必要とし、必要なコンポーネントとモジュールを定義します.一旦我々がモジュールを輸入したならば、我々が文脈を準備する物語の中に.この例では、FormBuilderを使用してフォームグループを作成します.ストーリープロップセクションでは、コンポーネントとそのラッパーをテンプレートプロパティに渡した変数を定義します.このようにして、ControlValueAccessorを用意して、状態を変更できるようにします.
これらの例では、可能な限り簡単にシナリオを作成しようとしました.アドオンは、我々がすべての種類のツールで我々の話を補うことができるコミュニティによってつくられて、維持されるプラグインです.アドオンの詳細については、hereをクリックします.
私たちが見たように、私たちのUIコンポーネントをこの方法で文書化し、マークダウンファイルでそれらを補完する機会を与えて、少しの愛と献身をもってそれらを補完する機会を得て、複雑な構成の必要なしで、そして、同じプロジェクトのすべてで、ファイル自身を一緒にファイルを持つことなく、使いやすくて、非常に魅力的であるドキュメンテーションプロジェクトを持つことができます.