react-styleguidist是一个基于JSDOC可以帮助react项目快速构建项目文档的一个插件。

一、简单入门

1.1 环境准备

准备一个新鲜的react项目(非必需)

npx create-react-app react-app

添加react-styleguidist

npm install --save-dev react-styleguidist

在package.json添加启动脚本

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

1.2 写一个button组件

src/components/Button下新建两个文件: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 生成文档

运行yarn styleguide就可以启动文档服务器了。打开localhost:6060

 
styleguide文档

1.4 总结

styleguide会默认为src/components/**/*.js的js文件生成文档。通过生成的styleguide文档我们可以看出,styleguide读取了注解Button.propTypesButton.defaultProps为我们生成了组件文档,并且将propTypes的注解放到description中,可谓是非常贴心了。
注意:styleguide读取的是注解,不是注释语句

二、Documenting components

经过第一节,styleguide已经帮助我们生成了组件的使用文档。只有一些props的文档显然是不够的,除了JSDoc styleguide还支持markdown来生成我们自定义的文档。在src/components/Button文件夹下新建Readme.md

// Readme.md 
React component example: 
 
```js 
<Button size="large">Push Me</Button> 
``` 
 
通过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'; 
``` 
 
其他语言高亮: 
 
```html 
<Button size="large">Push Me</Button> 
```
 _支持所有的_ [Markdown](http://daringfireball.net/projects/markdown/) _语法_. 

刷新localhost:6060就可以看到我们组建的样例和自定义文档了。而且,我们还可以点击VIEW CODE来实时更新example代码,这样就可以面向文档编程了。更多的styleguide的知识可在官方文档按需学习,高阶用法请参考Cookbook

三、配置

我们之前启动都styleguide server都是使用了styleguide的默认配置,styleguide默认会读取项目根目录下的styleguide.config.js来替换默认配置,当然也可以使用--config来指定配置文件。官方文档--配置

四、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') 
}

区别于普通的react,ts的props是通过interface来声明的。所以在ts中就不需要写propTypes了。

作者:zhiqiangx
链接:https://www.jianshu.com/p/5d6de52f7b57
来源:简书
著作权归作者所有。商业转载请联系作者获得授权,非商业转载请注明出处。


评论关闭
IT序号网

微信公众号号:IT虾米 (左侧二维码扫一扫)欢迎添加!