react-styleguidist是一個(gè)基于JSDOC可以幫助react項(xiàng)目快速構(gòu)建項(xiàng)目文檔的一個(gè)插件。

一、簡(jiǎn)單入門(mén)

1.1 環(huán)境準(zhǔn)備

準(zhǔn)備一個(gè)新鮮的react項(xiàng)目(非必需)

npx create-react-app react-app

添加react-styleguidist

npm install --save-dev react-styleguidist

在package.json添加啟動(dòng)腳本

"scripts": {
    ...
    "styleguide": "styleguidist server",
    "styleguide:build": "styleguidist build"
  }

1.2 寫(xiě)一個(gè)button組件

在src/components/Button下新建兩個(gè)文件：index.js、index.css

// index.js
import React from 'react';
import PropTypes from 'prop-types';

import './Button.css';

/**
 * The only true button.
 */
export default function Button({ color, size, onClick, disabled, children }) {
  const styles = {
    color,
    fontSize: Button.sizes[size],
  };

  return (
    <button className="button" style={styles} onClick={onClick} disabled={disabled}>
      {children}
    </button>
  );
}
Button.propTypes = {
  /** Button label */
  children: PropTypes.node.isRequired,
  /** The color for the button */
  color: PropTypes.string,
  /** The size of the button */
  size: PropTypes.oneOf(['small', 'normal', 'large']),
  /** Disable button */
  disabled: PropTypes.bool,
  /** Gets called when the user clicks on the button */
  onClick: PropTypes.func,
};
Button.defaultProps = {
  color: '#333',
  size: 'normal',
  onClick: event => {
    // eslint-disable-next-line no-console
    console.log('You have clicked me!', event.target);
  },
};
Button.sizes = {
  small: '10px',
  normal: '14px',
  large: '18px',
};

// index.css
.button {
    padding: 0.5em 1.5em;
    color: #666;
    background-color: #fff;
    border: 1px solid currentColor;
    border-radius: 0.3em;
    text-align: center;
    vertical-align: middle;
    cursor: pointer;
}

.button[disabled] {
    opacity: 0.35;
    cursor: default;
}

.button + .button {
    margin-left: 8px;
}

.checks {
    background-image: linear-gradient(45deg, #f5f5f5 25%, transparent 25%),
    linear-gradient(-45deg, #f5f5f5 25%, transparent 25%),
    linear-gradient(45deg, transparent 75%, #f5f5f5 75%),
    linear-gradient(-45deg, transparent 75%, #f5f5f5 75%);
    background-size: 16px 16px;
    background-position: 0 0, 0 8px, 8px -8px, -8px 0px;
}

1.3 生成文檔

運(yùn)行yarn styleguide就可以啟動(dòng)文檔服務(wù)器了。打開(kāi)localhost:6060：

styleguide文檔

1.4 總結(jié)

styleguide會(huì)默認(rèn)為src/components/**/*.js的js文件生成文檔。通過(guò)生成的styleguide文檔我們可以看出，styleguide讀取了注解、Button.propTypes和Button.defaultProps為我們生成了組件文檔，并且將propTypes的注解放到description中，可謂是非常貼心了。
注意：styleguide讀取的是注解，不是注釋語(yǔ)句

二、Documenting components

經(jīng)過(guò)第一節(jié)，styleguide已經(jīng)幫助我們生成了組件的使用文檔。只有一些props的文檔顯然是不夠的，除了JSDoc styleguide還支持markdown來(lái)生成我們自定義的文檔。在src/components/Button文件夾下新建Readme.md：

// Readme.md
React component example:

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

通過(guò)props配置Code wrapper樣式:

```js { "props": { "className": "checks" } }
<Button>I’m transparent!</Button>
```

disable `view code` 按鈕:

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

`static` modifier支持js代碼高亮:

```jsx static
import React from 'react';
```

其他語(yǔ)言高亮:

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

_支持所有的_ [Markdown](http://daringfireball.net/projects/markdown/) _語(yǔ)法_.

刷新localhost:6060就可以看到我們組建的樣例和自定義文檔了。而且，我們還可以點(diǎn)擊VIEW CODE來(lái)實(shí)時(shí)更新example代碼，這樣就可以面向文檔編程了。更多的styleguide的知識(shí)可在官方文檔按需學(xué)習(xí)，高階用法請(qǐng)參考Cookbook。
。

三、配置

我們之前啟動(dòng)都styleguide server都是使用了styleguide的默認(rèn)配置，styleguide默認(rèn)會(huì)讀取項(xiàng)目根目錄下的styleguide.config.js來(lái)替換默認(rèn)配置，當(dāng)然也可以使用--config來(lái)指定配置文件。官方文檔--配置。

四、TS

styleguide也支持了Typescript，只需要添加react-docgen插件就可以了。
安裝插件

npm i -D react-docgen-typescript

配置插件，在styleguide.config.js中添加：

module.exports = {
  ...
  resolver: require('react-docgen').resolver.findAllComponentDefinitions,
  propsParser: require('react-docgen-typescript').parse,
  webpackConfig: require('./config/webpack.config')
}

區(qū)別于普通的react，ts的props是通過(guò)interface來(lái)聲明的。所以在ts中就不需要寫(xiě)propTypes了。