@ozo/react-rock
Version:
React 移动端开发脚手架，基于CRA3，通用、开箱即用。
148 lines (95 loc) • 3.91 kB
Markdown
# 编写组件文档
## 背景
主流UI组件库：
+ Bootstrap（Js+Jq）
+ Material-UI （React）
+ Ant Design （React）
+ Element （Vue）
+ iView（Vue）
通过UI 组件，前端项目就像搭积木一样简单。为了提升开发效率，沉淀一套适合自己团队的 UI 组件库是一种较为有效的方式之一：可以减少重复工作、提高可复用。
**构建思路：**在大厂开源 UI 组件库的基础上个性化色彩（一般都提供颜色定制）、增加团队的个性化需求组件、减少不需要的组件。
UI 组件库少不了使用文档，这里通过Docz+ MDX 来写 React UI 组件文档。下图左边是创建的 MDX 文档，右边是 Docz 渲染出的组件及组件代码。
> [Docz](https://github.com/pedronauck/docz) ：用于构建演示文档，其特色是零配置、简单、快速，它使用 Markdown 语法的扩展 MDX (在 Markdown 里引入 React 组件并渲染出组件)来书写文档。
非常简单！
## 使用
1. 在项目中安装 Docz：
```
yarn add docz --dev
或
npm install docz --save-dev
```
2. 创建 .mdx 文件并输入：
```md
---
name: Button
---
import { Playground, PropsTable } from 'docz'
import Button from './'
# Button
<PropsTable of={Button} />
## Basic usage
<Playground>
<Button>Click me</Button>
<Button kind="secondary">Click me</Button>
</Playground>
```
3. 运行：
```
yarn docz dev
```
打完收工，这样你就收获了一个简单的 Button 组件的演示文档。
##### 
4. 构建
```
yarn docz build
```
更多详情，请参照[官方文档](https://www.docz.site/)。
### 编辑组件的[propTypes](https://www.npmjs.com/package/prop-types)
可能你发现上图中除了自己写的演示案例外，还多了一个Properies。 这个属性列表里的说明是哪来的？其实这是Docz等演示文档生成工具会直接从组件的PropTypes列表中的注释提取来的。所以你编写组件时，应该为组件编写详尽的`propTypes`注释，就像这样：
```jsx
class Button extends Component {
static propTypes = {
/**
* button的size，包括"xs","sm","md","lg","xl"，支持*markdown*
*/
size: Proptypes.oneOf(["xs","sm","md","lg","xl"]);
/**
* call after button is clicked，支持*markdown*
*/
onClick: PropTypes.func,
}
...
}
```
## 配置
零配置方便是方便，但有时想界面个性化点还是很费事的(官方提供 Themes 支持，但现仅有一套官方的默认主题)，下面分享一个通过引入本地 CSS 的方式来改变默认主题的配置。
1. 创建配置文件 doczrc.js ，增加 htmlContext 内容。
> 更多配置：https://www.docz.site/documentation/project-configuration
```js
export default {
htmlContext: {
head: {
links: [
{ rel: 'stylesheet', href: '/base.css' }
]
}
}
}
```
2. .docz 目录下创建 public 文件夹并创建 base.css ，在 base.css 里写自己的样式覆盖默认的即可。
## 最后
+ [Docz](https://github.com/pedronauck/docz)：简单好用，但现在只支持 React。
+ [Storybook](https://github.com/storybooks/storybook)：是一个更强大的集组件开发、查看、测试的文档工具，支持：
- React
- React Native
- Vue
- Angular
- Polymer
- Mithril
- Marko
- HTML
- Svelte
- Riot
+ [Docsify](https://github.com/docsifyjs/docsify)： 搭配 Vuep 写 Playground 。
+ [redemo](https://github.com/imweb/redemo)： 依赖[react-docgen](https://github.com/reactjs/react-docgen)来提取组件的`propTypes`注释。