背景
前段时间， 部门在热气腾腾的搞各类组件库。
做组件库，不可避免的就须要做组件的展现和阐明， 要用到一些文档工具。
咱们我的项目外面也尝试了几种不同的文档工具，明天和大家分享一些教训， 心愿对大家有所帮忙。
注释
目前， 咱们的组件库， 一共应用三种文档工具， 别离是：
Story BookDoczDumi
上面我会依据理论的应用状况，对这三种工具做一些比照 并给出一些论断。
1. Story Book
StoryBook 提供了一套UI组件的开发环境。
它容许你浏览组件库，查看每个组件的不同状态，以及交互式开发和测试组件， 目前反对 react、vue、angular 等前端类库和框架。
代码示例
// Button.stories.tsx
import React from 'react';
import { Story } from '@storybook/react';
// We create a “template” of how args map to rendering
const Template: Story<ButtonProps> = (args) => <Button {...args} />;
export const Primary = Template.bind({});
Primary.args = {
primary: true,
label: 'Primary',
};storybook 提供能够交互的组件编写，通过 Template.bind({}) 进行组件的绑定，通过 args 裸露可交互的属性。
且反对的组件库丰盛，然而文档的编写除了须要提供示例外，还须要兼容可交互的模式。
渲染示例
比方咱们的 SSC-UI-Vue-Pro 组件库：
import STrackingHistory from './tracking-history.vue';
import './style/index.less';
export default {
title: 'Design System/展现/TrackingHistory',
component: STrackingHistory,
parameters: {
docs: {
description: {
component: '订单历史追踪，次要按工夫和状态维度跟进',
},
},
design: {
type: 'figma',
url:
'https://www.figma.com/file/zi4Lcb2H2K5JikFKeEvPD7/WMS%E5%85%B8%E5%9E%8B%E6%A8%A1%E6%9D%BFV1.1?node-id=2974%3A595',
},
},
argTypes: {
title: {
control: 'text',
description: '题目内容，必填',
type: { required: true },
},
list: {
control: 'object',
description: '历史记录列表',
type: { required: true, summary: 'array' },
},
},
};
const Template = (args, { argTypes }) => ({
components: { STrackingHistory },
props: Object.keys(argTypes),
template: '<STrackingHistory v-bind="$props" />',
});
export const Default = Template.bind({});
(Default as any).args = {
title: 'Order Tracking History',
list: [
{
time: '18:00:22',
date: '2021-11-23',
status: 'string; // 选填，缺省时不显示',
statusType: 'default',
contents: [
{
label: 'Message',
value: 'LineContent[]; // 选填，按程序展现每一行内容',
},
{
label: 'Oprater',
value: 'LineContent[]; // 选填，按程序展现每一行内容',
},
],
splitLineText: 'New Order',
},
{
date: '2021-1-2',
status: 'string; // 选填，缺省时不显示',
statusType: 'default',
contents: [
{
label: 'Operator',
value: 'LineContent[]; // 选填，按程序展现每一行内容',
},
],
},
{
date: '2021-11-23',
status: 'string; // 选填，缺省时不显示',
contents: [
{
value: 'LineContent[]; // 选填，按程序展现每一行内容',
},
],
},
{
date: '2021-11-23',
status: 'string; // 选填，缺省时不显示',
statusType: 'success',
contents: [],
},
{
date: '2021-1-23',
contents: [{}],
},
{
date: '2021-1-3',
},
{
date: '2021-11-23',
contents: [
{
label: 'Message',
},
],
},
],
};2. docz
Docz 是一个高效、零配置的事件记录工具。
Docz 基于 MDX ，有许多内置的组件能够帮忙你记录你的事件。
它同时反对增加插件，以便于通过 Docz 流程和数据管控很多事件。
代码示例
// Button.mdx
import { Playground } from 'docz'
import { Button } from './Button'
# Button
## Basic usage
<Playground>
<Button>Click me</Button>
<Button kind="secondary">Click me</Button>
</Playground>渲染示例
这是官网的一个示例，能够看出代码的示例须要写在 Playground 标签外面，由此带来一个问题，无奈在代码示例中写引入模块，这其实对开发者不太敌对。
咱们的 SSC-UI-React 组件库应用了docz, 实际效果：
3. dumi
dumi 是一款为组件开发场景而生的文档工具。
其具备开箱即用，将注意力集中在组件开发和文档编写上。
基于 TypeScript 类型定义，主动生成组件 API、挪动端组件库编写及多语言反对。
代码示例
在类型定义中：
渲染示例
总体比照
以下为三个库的个性比照：
| docz | story book | dumi | |
|---|---|---|---|
| 反对编写的组件库类型 | all ✅ | all ✅ | React Only |
| 轻量级 / 开发者敌对 | ❌ | ❌ | ✅ |
| 文档内嵌在组件目录中 | ❌ | ✅ | ✅ |
| 将引入模块写在代码示例中 | ❌ | ❌ | ✅ |
| 主动生成组件库 API | ❌ | ❌ | ✅ |
| 反对除了组件库文档的其余类型文档的编写 | ✅ | ✅ | ❌ |
综上所述，欢快地决定将 React Pro Components 组件库文档迁徙到 dumi 中。
踩坑总结
1. React 版本不兼容问题
一通迁徙操作后，咱们 yarn 了一下，发现报错了:
这是 ts 报出的对于 react 类型查看的谬误，一开始认为是 ts 查看多了，那么在tsconfig.json 配置 excluded：[‘node-modules’]，将这个查看去掉，然而配完了依然不好使。
通过一通粗疏的查看，在 yarn.lock 中发现组件库依赖的 react 版本是 16，而 dumi 依赖的 react 版本是，的版本下载了 17 版本的 react，因为两个版本的 react 的 ts 类型不同，导致了类型查看不通过。
既然如此，咱们只有显示指定 react 的版本为 16 就行了，16 在 * 的范畴，也不会导致 dumi 有谬误。
在 package.json 中退出：
"resolutions": {
"@types/react": "^16.9.23"
}即可。
2.文档援用问题
因为 dumi 的文档是面向用户的，因而写文档时引入组件的办法，举例:
如 Button 组件为:
import { EditArea } from 'react-pro-components'
因为这里引入的是 node_module 的包，这使得组件库的更改无奈映射到文档中，须要增加别名映射。
在 .umirc.ts 中增加：
const path = require('path');
const chainWebpack = require('webpack-chain');
export default {
// 其余配置
chainWebpack(memo) {
// 设置 alias
memo.resolve
.alias
.set('react-pro-components', path.resolve(__dirname, 'src', 'components'))
},
};3. 其余问题
- dumi 是否反对 api 文档的局部属性暗藏呢？
暂不反对
- dumi 是否反对搜寻呢?
site 模式反对，doc 模式暂不反对。
dumi是否 md 文档独自放在组件目录下的一个文件夹下呢？
暂不反对，须要间接放在组件目录下，如 Button 组件：
├── Button
│ └── index.md论断
经多比照之后， 咱们把一个 React 组件库 迁徙到了 dumi, 并获得了不错的成果。
有须要做 React 组件库的小伙伴能够注意下dumi.
至于 Vue 组件文档库， 大家就依据本人的状况灵便抉择吧。
心愿这篇文章能对大家有所帮忙， 谢谢。
最初
如果感觉内容有帮忙， 能够关注下我的公众号，把握最新动静，一起学习！
相干链接
- https://zhuanlan.zhihu.com/p/…
- https://storybook.js.org/docs…
- https://d.umijs.org/zh-CN
发表回复