React Styleguidist 入門

此文章是由我的對該技術的理解和解讀官網翻譯而來，難免有不太恰當的地方，望多多指教，共同窗習。

react-styleguidist 會把全部組件都顯示在一個頁面上，包含 props 文檔和用法示例，以及一個獨立開發組件的環境。 在Styleguidist 中，能夠在 Markdown 中編寫示例，每一個代碼段都會當即呈現；

原理

Styleguidist會加載組件，使用react-docgen生成文檔，可能須要更改代碼才能正常工做。

React-docgen會把組件做爲靜態文本文件讀取，而後相似於查找React組件的模式去查找組件（例如類或函數聲明）。React-docgen不會運行任何JavaScript代碼，所以，若是組件是動態生成，或包裝在高階組件中，或拆分爲多個文件，react-docgen可能沒法理解。

React-docgen支持經過React.createClass，ES6 classes 和函數組件定義的組件；
React-docgen支持Flow和TypeScript註釋；

在某些狀況下，能夠經過導出兩個組件 欺騙 Styleguidist和react-docgen：

• 做爲命名導出的基本組件
• 做爲默認導出的加強組件

import React from 'react'
import CSSModules from 'react-css-modules'
import styles from './Button.css'

// Base component will be used by react-docgen to generate documentation
export function Button({ color, size, children }) {
  /* ... */
}

// Enhanced component will be used when you write <Button /> in your example files
export default CSSModules(Button, styles)

開始

安裝 Styleguidist:

// npm
npm install --save react-styleguidist

// yarn
yarn add react-styleguidist

配置package.json腳本

"scripts": {
  "styleguide": "NODE_ENV=development styleguidist server",
  "styleguide:build": "NODE_ENV=production styleguidist build",
}

運行Styleguidist

npm run styleguide  //啓動styleguidist開發服務器
npm run styleguide:build  //構建生產HTML版本

組件生成文檔

Styleguidist根據組件中的註釋，propTypes聲明和Readerme.md爲組件生成文檔。

解析props

默認行爲：Styleguidist從propTypes中獲取props並生成一個表格，並根據props的註釋顯示組件的說明，根據defaultProps獲取props的默認值。

import React from 'react'
import PropTypes from 'prop-types'
/**
 * General component description in JSDoc format. Markdown is    *supported*.
 */
export default class Button extends React.Component {
  static propTypes = {
    /** Description of prop "foo". */
    foo: PropTypes.number,
    /** Description of prop "baz". */
    baz: PropTypes.oneOfType([PropTypes.number, PropTypes.string])
  }

  static defaultProps = {
    foo: 42
  }

  render() {
    /* ... */
  }
}

修改默認行爲

可使用propsParser和resolver更改解析props默認行爲;

propsParser: Function
此方法能夠從新個從源文件如何解析props。默認是使用react-docgen進行解析。

module.exports = {
  propsParser(filePath, source, resolver, handlers) {
    return require('react-docgen').parse(source, resolver, handlers)
  }
}

resolver
此方法能夠肯定哪些類/組件須要解析。默認行爲是在每一個文件中查找全部導出的組件，能夠配置它以讓全部查找到的組件使用自定義解析方法。

module.exports = {
  resolver: require('react-docgen').resolver
    .findAllComponentDefinitions
}

組件的PropType和文檔註釋由react-docgen庫解析, 可使用updateDocs函數對其進行修改。有關解析props的更多信息，可參見react-docgen文檔。

示例文件查找與編寫

默認行爲：Styleguidist默認在組件文件夾下查找Readme.md或[ComponentName].md的文件並生成示例文件。
帶有js，jsx或javascript標記的代碼塊將被呈現爲帶有交互式的React組件。爲了向後兼容，不帶語言標籤的代碼塊也會展現成帶有交互式的React組件。

React component example:

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

You can add a custom props to an example wrapper:

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

To render an example as highlighted source code add a `static` modifier:

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

修改默認行爲

能夠經過getExampleFilename自定義md 文件名字，此方法經過提供的組建文件路徑返回新的 md 文件路徑。
例如：用 ComponentName.examples.md代替 Readme.md

module.exports = {
  getExampleFilename(componentPath) {
    return componentPath.replace(/\.jsx?$/, '.examples.md')
  }
}

關聯其餘示例文件

可使用@example doclet語法將其餘示例文件與組件關聯。
例子：Button 組件有一個從extra.examples.md文件加載的示例

/**
 * Component is described here.
 *
 * @example ./extra.examples.md
 */
export default class Button extends React.Component {
  // ...
}

寫 code

• 導入依賴項: 經過import導入
• 管理狀態：每一個示例都是一個function組件，可使用useState Hook來處理狀態。

// ```jsx inside Markdown
import React from 'react'
import Button from 'rsg-example/components/Button'
import Placeholder from 'rsg-example/components/Placeholder'
;<Button size="large">Push Me</Button>


// ```jsx inside Markdown
const [isOpen, setIsOpen] = React.useState(false)
;<div>
  <button onClick={() => setIsOpen(true)}>Open</button>
  <Modal isOpen={isOpen}>
    <h1>Hallo!</h1>
    <button onClick={() => setIsOpen(false)}>Close</button>
  </Modal>
</div>

moduleAliases
定義模塊的別名，能夠在示例文件中導入這些別名，以使示例代碼更加實際和可複製；

const path = require('path');

module.exports = {
  moduleAliases: {
    'rsg-example': path.resolve(__dirname, 'src')
  }
}

• Markdown語法都被支持；
• 若是須要在文檔中顯示一些不想被呈現爲交互式的JavaScript代碼，則能夠將static修飾符與語言標籤一塊兒使用；
• Styleguidist 經過 Bublé 運行ES6代碼, 大多數ES6功能都支持；
• rsg-example模塊是由moduleAliases 選項定義的別名;
• 若是須要更復雜的演示，一般最好將其定義在一個單獨的JavaScript文件中，而後將其導入Markdown中

公共方法

默認狀況下，組件所具備的任何方法均被視爲私有方法，不會被髮布。使用JSDoc @public標記方法，就可使其成爲公共方法並會在文檔中發佈。

/**
 * @param {string} name
 * @public
 */
getName(name) {
  // ...
}

隱藏props

默認狀況下，組件全部的props都是公開並可發佈。在某些狀況下代碼存在某props, 但願文檔中不展現這個props，使用JSDoc @ignore標記props，就能夠將其從文檔中刪除。

Button.propTypes = {
  /**
   * A prop that should not be visible in the documentation.
   * @ignore
   */
  hiddenProp: React.PropTypes.string
}

定位組件

查找組件

默認狀況下，Styleguidist將使用此模式定位組件：src/components/**/*.{js,jsx,ts,tsx}。
例如：

• src/components/Button.js
• src/components/Button/Button.js
• src/components/Button/index.js

可是會忽略 tests 文件:

• __tests__ 文件夾
• 文件名裏包含.test.js 或 .spec.js (相似於： .jsx, .ts , .tsx)

修改默認查找方式

在styleguide.config.js文件裏的配置components能夠修改組件查找方式來適應不一樣的項目；

例如：若是組件路徑是components/Button/Button.js，爲了簡化導入在components/Button/index.js中再次導出（export { default } from './Button'），【爲了讓components/Button替代components/Button/Button】， 這時候須要跳過 index.js。

module.exports = {
  components: 'src/components/**/[A-Z]*.js'
}

使用ignore可將某些文件從樣式指南中排除

ignore：String[]

默認值：

[
  '**/__tests__/**', 
  '**/*.test.{js,jsx,ts,tsx}', 
  '**/*.spec.{js,jsx,ts,tsx}', 
  '**/*.d.ts'
]

使用getComponentPathLine更改組件導入路徑

getComponentPathLine: Function
默認值： 組件文件名
返回值：返回組件路徑

例如: 從components/Button中導入Button，而不是components/Button /Button.js

const path = require('path');
module.exports = {
  getComponentPathLine(componentPath) {
    const name = path.basename(componentPath, '.js')
    const dir = path.dirname(componentPath)
    return `import ${name} from '${dir}';`
  }
}

全部路徑都相對於config文件夾;

加載組件

Styleguidist加載組件並暴露在全局以供示例使用。

標識符

Styleguidist默認使用組件的displayName做爲標識符。若是它不能理解displayName（displayName動態生成），它將退回到它能夠理解的東西。

Sections

Sections: Array[{}]

將組件分組，或將額外的Markdown文檔添加到樣式指南中。

Sections數組的每一項有：

• name — Sections 標題；
• content — 包含概述內容的Markdown文件的位置；
• components — 能夠是glob模式字符串，組件路徑數組，glob模式字符串數組，返回一個組件數組的函數或返回glob模式字符串的函數。規則與根選項components相同；
• sections — 嵌套的Sections數組（能夠再嵌套）；
• description — section描述；
• sectionDepth — 單個頁面的小節數，僅在pagePerSection中可用;
• exampleMode — 代碼示例的初始狀態，使用 exampleMode.
• usageMode — props和方法的初始狀態， 使用 usageMode.
• ignore — 須要忽略的文件，值能夠是字符串或數組；
• href - navigate的URL（不是導航到Sections 內容的URL）；
• external - 若是設置，會打開一個新頁面；
• expand - 在常規設置中將tocMode設置爲collapse摺疊時，確認是否應該被展開；

上述全部字段都是可選的；

// styleguide.config.js

module.exports = {
  sections: [
    {
      name: 'Introduction',
      content: 'docs/introduction.md'
    },
    {
      name: 'Documentation',
      sections: [
        {
          name: 'Installation',
          content: 'docs/installation.md',
          description: 'The description for the installation section'
        },
        {
          name: 'Configuration',
          content: 'docs/configuration.md'
        },
        {
          name: 'Live Demo',
          external: true,
          href: 'http://example.com'
        }
      ]
    },
    {
      name: 'UI Components',
      content: 'docs/ui.md',
      components: 'lib/components/ui/*.js',
      exampleMode: 'expand', // 'hide' | 'collapse' | 'expand'
      usageMode: 'expand' // 'hide' | 'collapse' | 'expand'
    }
  ]
}

配置webpack

Styleguidist依賴webpack，使用webpack肯定如何加載項目的文件，但項目也不必定非要配置webpack。
默認狀況下，Styleguidist會在項目的根目錄中查找webpack.config.js並使用它。

自定義Webpack配置

若是webpack配置在其餘位置，則須要手動加載：

module.exports = {
  webpackConfig: require('./configs/webpack.js')
}

也能夠merge多個webpack配置：

module.exports = {
  webpackConfig: Object.assign({}, require('./configs/webpack.js'), {
    /* Custom config options */
  })
}

• 配置entry, externals, output, watch, 和 stats .會被忽略。生產上，devtool 也會被忽略；
• 插件 CommonsChunkPlugins, HtmlWebpackPlugin, MiniHtmlWebpackPlugin, UglifyJsPlugin, TerserPlugin, HotModuleReplacementPlugin 會被忽略， 由於 Styleguidist 已經引入了他們，再次引入會影響 Styleguidist;
• 若是loaders 不起做用，請嘗試包含和排除絕對路徑；

styleguide配置

title: String

serverPort: Number
端口號

require: Array
添加用戶自定義的js, CSS 或 polyfills

assetsDir: String
資源文件名

styleguideDir: String
默認值：styleguide
定義styleguidist構建命令生成的靜態HTML的文件夾；

getComponentPathLine: Function
獲取組件加載路徑

template: Object | Function
更改應用程序的HTML。 一個能夠添加favicon，meta 標籤, 內嵌JavaScript或CSS的對象。

styles: Object | String | Function
自定義Styleguidist組件的樣式。

theme: Object | String
配置值能夠是對象或導出此類對象的文件的路徑實現自定義UI字體，顏色等;
配置的文件路徑是相對配置文件或者絕對路徑。

sections
設置組件分組；

styleguideComponents: Object
重寫被用於渲染到瀏覽器的React組件;

webpackConfig
自定義webpack配置;

更多配置選項查看官方文檔：configuration