专栏首页前端皮小蛋? 对比三个强大的组件文档展示工具

? 对比三个强大的组件文档展示工具

背景

前段时间, 部门在热火朝天的搞各类组件库

做组件库,不可避免的就需要做组件的展示和说明, 要用到一些文档工具

我们项目里面也尝试了几种不同的文档工具,今天和大家分享一些经验, 希望对大家有所帮助。

正文

目前, 我们的组件库 一共使用了三种文档工具, 分别是:

  1. Story Book
  2. Docz
  3. Dumi

下面我会根据实际的使用情况,对这三种工具做一些对比 并给出一些结论

1. Story Book

StoryBook 提供了一套UI组件的开发环境。

它允许你浏览组件库,查看每个组件的不同状态,以及交互式开发和测试组件, 目前支持 reactvueangular 等前端类库和框架。

代码示例

// 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. 其他问题

  1. dumi 是否支持 api 文档的部分属性隐藏呢?

暂不支持

  1. dumi 是否支持搜索呢?

site 模式支持,doc 模式暂不支持。

  1. dumi 是否 md 文档单独放在组件目录下的一个文件夹下呢?

暂不支持,需要直接放在组件目录下,如 Button 组件:

├── Button
│   └── index.md

结论

经多对比之后, 我们把一个 React 组件库 迁移到了 dumi, 并取得了不错的效果。

有需要做 React 组件库的小伙伴可以留意下dumi.

至于 Vue 组件文档库, 大家就根据自己的情况灵活选择吧。

希望这篇文章能对大家有所帮助, 谢谢。

最后

如果觉得内容有帮助, 可以关注下我的公众号,掌握最新动态,一起学习!

相关链接

  1. https://zhuanlan.zhihu.com/p/110381664
  2. https://storybook.js.org/docs/react/get-started/browse-stories
  3. https://d.umijs.org/zh-CN

本文分享自微信公众号 - 前端皮小蛋(gh_e69260c16440),作者:南山皮小蛋

原文出处及转载信息见文内详细说明,如有侵权,请联系 yunjia_community@tencent.com 删除。

原始发表时间:2021-04-29

本文参与腾讯云自媒体分享计划,欢迎正在阅读的你也加入,一起分享。

我来说两句

0 条评论
登录 后参与评论

相关文章

  • 以开发者为中心的小程序生态

    小程序现有的开发模式是基于已有的小程序基础库提供的组件,通过自定义业务的样式实现自定义化和功能。

    villainhr
  • Golang框架选型比较: goframe, beego, iris和gin

    原文地址:https://itician.org/pages/viewpage.action?pageId=3673375

    Golang
  • 为什么选择Django?

    Python作为当前最火爆最热门,也是最主要的Web开发语言之一,在其二十多年的历史中出现了数十种Web框架,比如Django、Tornado、Flask、Tw...

    萌海无涯
  • 数据防泄漏DLP技术深度剖析(2015-10-30)

    在企业中提到数据保护,大家可能常常想起文档,很少有人会关注文档中的内容,对数据的管理也比较单一,通常就是全加密、全授权,对文档的重要性不做区分,随着社会的发展,...

    网络安全观
  • 使用 MarkDown & DocFX 升级 Rafy 帮助文档

    用户1172223
  • HTML5 概述及基本语法

    (1)HTML5 的历史 HTML5 是继 HTML4.01 和 XHTML1.0 之后的超文本标记语言的最新版本。它是由一群自由思想者组成的团队设计出来,并...

    魏晓蕾
  • Python测试开发django1.简介

    Django是一种基于Python开发的开源的高级Web应用框架,使用Django,使你能够以最小的代价构建和维护高质量的Web应用。Djang...

    王大力测试进阶之路
  • 工欲善其事必先利其器——产品篇

    善其事,关键在于搞明白产品经理相关的工作内容,针对工作,合理有效的利用软件,才能达到事半功倍的效果。

    雪雁-心莱科技
  • 开源React Native组件库beeshell 2.0发布

    2018年,我们开源了React Native组件库——beeshell 1.0。时隔一年,我们对React Native组件库继续优化,实现beeshell ...

    美团技术团队
  • 收藏夹吃灰了:GitHub 上值得收藏的100个精选前端项目

    codrops 一系列具有相当具有创意且有趣的前端效果的集合,是非常棒的学习资料,可以欣赏和下载使用。并且有些项目,也托管到了github仓库中

    王小婷
  • 基于Chrome插件的开发工具链

    在项目开发过程中,时不时会碰上需要使用一些工具来做一些自动操作或者附加功能。特别是有一些外部组件只会提供Web工具,或者如果产品会发布在Web上的时候,在线上的...

    owent
  • PHP中常用的七大框架的优点与缺点

    长期以来,PHPer一直在讨论各种PHP框架的优缺点,互联网上的信息相对分散。现在我收集并总结了几个主流框架,其中我只使用了yii2、laravel、YAF和T...

    叫我可儿呀
  • GitHub 上100个优质前端项目整理,非常全面!

    作 者:小明小明长大了 来 源:https://www.jianshu.com/p/72ca8192f7b8

    开发者技术前线
  • HTML5 学习总结(一)——HTML5概要与新增标签

    一、HTML5概要 ? 1.0、写在最前面 1.0.1、行业前景 https://www.lagou.com/ http://www.51job.com/ ? ...

    张果
  • 整合QC质控结果的利器——MultiQC

    NGS技术的进步催生了新的实验设计、分析类型和极高通量测序数据的生成。对于这些数据的质量评估,每一步分析结果的评估是后续结果可信度的衡量和保障。不少生信工具都可...

    生信宝典
  • HTML5学习-day01【悟空教程】

    网页超文本应用技术工作小组是一个以推动网络HTML 5 标准为目的而成立的组织。在2004年,由Opera、Mozilla基金会和苹果这些浏览器厂商组成。

    Java帮帮
  • 数据工程师需要掌握的18个python库

    Selenium是一个Web测试自动化框架,最初是为软件测试人员创建的。它提供了Web驱动程序API,供浏览器与用户操作交互并返回响应。它运行时会直接实例化出一...

    数说君
  • OpenStack第七次调研报告丨编译

    翻译:丽丽 编辑:张宇婷 编者注:这是自 2013 年 4 月以来 OpenStack 的第七次社区用户调查,本次用户调查用户的参与度最强, 到目前为止, 有...

    人称T客
  • 2018-05-28 Google Guava官方教程(中文版)from ifeve.com

    Albert陈凯

扫码关注云+社区

领取腾讯云代金券