84,621
返回整合

Storybook 附加元件，用於顯示元件的 README (適用於 React 和 Vue)

在 Github 上檢視

Storybook README 附加元件

注意：此 README 僅適用於 ^5.0.0 版本。對於較舊的版本，請參閱README_V4.md

所有先前的 API 應該在 ^5.0.0 及以上版本中正常運作。但是 Vue 使用者需要更改他們的導入路徑，因為 Vue 命令已移至它們自己的資料夾。

Storybook README addon

此附加元件與以下項目相容：

即時範例

功能

  • 自動產生 props 表格 (僅適用於 React)
  • 100% 支援 Markdown
  • 程式碼高亮
  • 可將文件新增至附加元件面板或 story 周圍
  • 接受多個 README (適用於高階元件 - 新增元件和原始元件的 README)
  • 外觀類似 Github 的 README
  • 支援 Vue 元件的 <docs/> 標籤 (example-vue/components/MyButton/MyButton.vue)。

此外，它非常有用，因為大多數專案和元件已經有 *README.md* 檔案。現在，可以輕鬆將它們新增到您的 Storybook 中。

如果安裝了 Storybook Info 附加元件，則將使用 *.addWithInfo* 方法新增 Story。

安裝

npm install --save-dev storybook-readme

或

yarn add --dev storybook-readme

React Storybook 的 Webpack 設定

無需操作 :)

但是，如果您將 Typescript 與 React 一起使用，則需要在您的 webpack 設定中新增 markdown-loader

{
  test: /\.md$/,
  use: [
    {
      loader: 'markdown-loader',
    }
  ]
}

Vue Storybook 的 Webpack 設定

僅適用於使用 <docs> 標籤進行文件記錄的單一檔案元件。

module.exports = storybookBaseConfig => {
  storybookBaseConfig.module.rules.push({
    resourceQuery: /blockType=docs/,
    use: ['storybook-readme/vue/docs-loader', 'html-loader', 'markdown-loader'],
  });
};

在 vue 模組內定義 <docs> 標籤

<docs>
Docs inside vue module 
</docs>

<template>
  <button class="button">
    <slot></slot>
  </button>
</template>

使用它在 story 中定義文件

import MyButton from '../components/MyButton/MyButton.vue';

storiesOf('Vue <docs>', module).addParameters({
  readme: {
    content: MyButton.__docs,
  },
});

設定

在 * .storybook / addons.js * 中註冊附加元件

import 'storybook-readme/register';

注意：可以設定附加元件的面板標題

import registerWithPanelTitle from 'storybook-readme/registerWithPanelTitle';

registerWithPanelTitle('Docs');

在 * .storybook / config.js * 中新增裝飾器

import { addDecorator, configure } from '@storybook/react';
import { addReadme } from 'storybook-readme';

// for Vue storybook
import { addReadme } from 'storybook-readme/vue'; // <---- vue subpackage

// for HTML storybook
import { addReadme } from 'storybook-readme/html'; // <---- html subpackage

addDecorator(addReadme);

function loadStories() {
  require('../stories/index.js');
}

configure(loadStories, module);

注意：對於 html storybook，僅可使用側邊欄文件。

用法

希望它非常簡單。

import React from 'react';
import { storiesOf } from '@storybook/react';

import Button from '../components/Button';
import ButtonReadme from '../components/Button/README.md';

storiesOf('Buttons', module)
  .addDecorator(withKnobs)
  .addParameters({
    readme: {
      // Show readme before story
      content: ButtonReadme,
      // Show readme at the addons panel
      sidebar: ButtonReadme,
    },
  })
  .add('Button', () => <Button />);

可以覆寫 story 的文件

import React from 'react';
import { storiesOf } from '@storybook/react';

import Button from '../components/Button';
import ButtonReadme from '../components/Button/README.md';

storiesOf('Buttons', module)
  .addDecorator(withKnobs)
  .addParameters({
    readme: {
      content: ButtonReadme,
      sidebar: ButtonReadme,
    },
  })
  .add('Button', () => <Button />)
  .add('Button', () => <Button />)
  .add('Button', () => <Button />, {
    readme: {
      // override docs
      content: CustomButtonReadme,
      sidebar: CustomButtonReadme,
    },
  });

完整選項清單

將應用於一系列 story。

.addParameters({
    readme: {
      /**
       * Accepts string (markdown) or array of strings
       * string | Array<string>
       */
      content: Readme,

      /**
       * Accepts string (markdown) or array of strings
       * string | Array<string>
       */
      sidebar: Readme,

      /**
       * Enable / disable code highlighting for sidebar. true by default
       */
      highlightSidebar: true,

      /**
       * Enable / disable code highlighting for content. true by default
       */
      highlightContent: true,

      /**
       * Override theme values
       *
       * All theme values https://github.com/tuchk4/storybook-readme/blob/master/packages/storybook-readme/src/styles/githubMarkdownCss.js#L436

       */
      theme: {},

      /**
       * Prism code theme
       * Full list of theme https://github.com/PrismJS/prism-themes
       * To be used with storybook-readme, naming of the code theme should be used in one of these styles. https://github.com/tuchk4/storybook-readme/tree/master/packages/storybook-readme/src/styles/prismCodeThemes
       */
      codeTheme: 'github',

      /**
       * You can include prop tables locally here. See `propTables` example
       * for more information
       */
      includePropTables: [YourImportedReactComponent],

      /**
       * Wrapper for story. Usually used to set some styles
       * NOTE: will be applied only for content docs (docs around the story)
       *
       * React: React.ReactNode
       * Vue: Vue component
       */
      StoryPreview: ({ children}) => <div>{children}</div>

      /**
       * Wrapper for header docs. Usually used to set some styles
       * NOTE: will be applied only for content docs (docs around the story)
       *
       * React: React.ReactNode
       * Vue: Vue component
       */
      HeaderPreview: ({ children}) => <div>{children}</div>

      /**
       * Wrapper for footer docs. Usually used to set some styles
       * NOTE: will be applied only for content docs (docs around the story)
       *
       * React: React.ReactNode
       * Vue: Vue component
       */
      FooterPreview: ({ children}) => <div>{children}</div>

      /**
       * Wrapper for content and sidebar docs. Usually used to set some styles
       * NOTE: will be applied only for content docs (docs around the story)
       *
       * React: React.ReactNode
       * Vue: Vue component
       */
      DocPreview: ({ children}) => <div>{children}</div>
    },
  })

全域設定

將應用於所有 story。注意：全域設定僅適用於內容文件 (story 周圍的文件)。

import { addParameters } from '@storybook/react'; // or @storybook/vue for vuejs
import { configureReadme } from 'storybook-readme';

configureReadme({
  /**
   * Wrapper for story. Usually used to set some styles
   * React: React.ReactNode
   * Vue: Vue component
   */
  StoryPreview: ({ children }) => <div>{children}</div>,

  /**
   * Wrapper for content and sidebar docs. Usually used to set some styles
   * React: React.ReactNode
   * Vue: Vue component
   */
  DocPreview: ({ children }) => (
    <div style={{ background: '#000' }}> {children}</div>
  ),

  /**
   * Wrapper for header docs. Usually used to set some styles
   * React: React.ReactNode
   * Vue: Vue component
   */
  HeaderPreview: ({ children }) => (
    <div style={{ background: 'red' }}>{children}</div>
  ),

  /**
   * Wrapper for footer docs. Usually used to set some styles
   * React: React.ReactNode
   * Vue: Vue component
   */
  FooterPreview: ({ children }) => <div>{children}</div>,

  /**
   * Header docs in markdown format
   */
  header: '',

  /**
   * Footer docs in markdown format
   */
  footer: '',
});

addParameters({
  readme: {
    // You can set a code theme globally.
    codeTheme: 'github',

    // You can exclude prop tables globally here. See `propTables` example
    // for more information
    excludePropTables: [YourImportedReactComponent],
  },
});

Readme 預留位置

  • story 的 <!-- STORY --> 預留位置
  • story 來源的 <!-- SOURCE --> 預留位置
  • story 來源的 <!-- STORY_SOURCE --> 預留位置
  • props 表格的 <!-- PROPS --> 預留位置。props 剖析存在一些問題。澄清 issue#137
  • <!-- STORY HIDE START -->，<!-- STORY HIDE END --> 標籤所括住的內容將不會顯示在 story 中
Button variants could be imported separately.

\`\`\`js import { OutlinedButton, ContainedButton, TextButton } from 'Button'; \`\`\`

<!-- PROPS -->

Example:

<!-- STORY -->
<!-- SOURCE -->

<!-- STORY HIDE START -->

content here won't be shown in stories

<!-- STORY HIDE END -->

Some docs after story

表情符號

在冒號之間使用簡碼，將表情符號插入文件中。例如

這裡是火箭 :rocket

這裡是火箭 :rocket

所有簡碼的清單可以在 Emojipedia 或 Gist/rxaviers 上找到

  • :rocket
  • :grinning
  • :monkey

隨時提出新功能建議或回報錯誤 :)

v4 中的 Api。

先前 Api 的完整文件位於 README_V4.md

TL;DR

接受 Markdown 格式的 README 或 README 陣列。當您開發高階元件並想要新增多個 README 以及原始元件文件時，多個 README 非常有用。

withReadme

在附加元件面板中呈現 README。

import { withReadme } from 'storybook-readme';
import withReadme from 'storybook-readme/with-readme';

// as HigherOrder Component
storiesOf('Button', module).add(
  'Default',
  withReadme(ButtonReadme, () => <Button />),
);
// as Decorator
storiesOf('Button', module)
  .addDecorator(withReadme(ButtonReadme))
  .add('Default', () => <Button />);

withDocs

在 story 周圍呈現 README。

import { withDocs } from 'storybook-readme';
import withDocs from 'storybook-readme/with-docs';

// as HigherOrder Component
storiesOf('Button', module).add(
  'Default',
  withDocs(ButtonReadme, () => <Button />),
);
// as Decorator
storiesOf('Button', module)
  .addDecorator(withDocs(ButtonReadme))
  .add('Default', () => <Button />);

doc

在主框架中呈現 README，而沒有 story。

import { doc } from 'storybook-readme';

storiesOf('Button', module).add('Default', () => doc(ButtonReadme));
由以下人員製作
  • siddharthlatest
    siddharthlatest
  • anjuma
    anjuma
  • mohdashraf010897
    mohdashraf010897
  • reactivesearch
    reactivesearch
標籤
如何安裝附加元件 建立附加元件