Docz 组件库文档实现方案 （一）

Docz 组件库文档实现方案 （一）

相关

• 基于 next.js + mdx 搭建组件库文档 Docz 维护较差，可以考虑自己搭建一个项目
• Docz 组件库文档实现方案 （一） Docz 使用说明及简单使用
• Docz 组件库文档实现方案（二） 实现 Docz 定制化方案
• Docz 组件库文档实现方案（三） Docz 与 lerna 项目的结合 – 将 docs 文档从组件库中分离出，作为一个单独的子项目维护
• Docz 官方文档
• Docz 官方实现案例
• 本文的实现案例 需要进入到 packages/mjz-ui 下查看
• 本文Lerna + Docz 实现案例（docs 与 components 分离）

说明

Docz 是一套与 Storybook 相比更简约的组件库文档实现方案，它解决了组件库文档开发最主要的问题（组件列表、组件展示、组件属性列表、组件编辑调试），虽然 Storybook 在社区支持方面更强一些（更多的配置控件，更多的功能）但是 Storybook 在开发成本上来说比 Docz 方案还是差一些的

Docz 基于 MDX 实现，MDX（Markdown + jsx） 允许你在 markdown 样式的文件中导入根使用 JSX 组件，并且 Docz 提供了一些内置组件，可以方便快速的实现文档搭建，并且 Docz 对 Typescript 的支持良好，可以根据 ts 的类型与注释生成文档

Docz 基本上可以零配置使用，但是同时也提供比 Storybook 更容易且方便的自定义能力 – Docz 内部通过 Gatsby 实现，Gatsby 提供了一个名为 Component Shadowing 的概念，他的原理就是通过相同的命名使用自定义组件来覆盖默认的组件，达到自定义的效果，这种方式使我们在充分利用 Docz 文档实现的同时，具有更高的自主性

Docz 简单使用

1. 下载安装并开启一个 组件库项目

#  在已有的 组件库项目中安装如下依赖
yarn add docz react react-dom

// 在组件库项目的 package.json 中增减如下脚本
{
  "scripts": {
    "docz:dev": "docz dev", // 启动开发环境
    "docz:build": "docz build", // build 出静态网站资源
    "docz:serve": "docz build && docz serve" // build 出静态网站资源并开启一个站点服务
  }
}

按照如下目录结构创建文件

 .
├── package.json
└── src
    ├── components # components 下用来存放我们开发的组件
    └── index.mdx # 文档文件，可以创建在任意地方

index.mdx 中写入如下内容，然后运行 yarn docz:dev 打开浏览器 http://localhost:3000/ 即可看到文档了

---
name: 组件库文档测试Root # 整个顶部区域用来配置导航 name 字段就是导航的名称
route: / # route 字段用来控制导航的层级
---

# Mjz-ui 开源组件库文档测试

Hello, I'm a mdx file!

2. 编写组件，并使用 Docz 内置组件生成这个组件的文档

Docz 提供多个内置组件，用来帮助我们快速的生成文档，下面我们先写一个组件 Button 然后使用 Docz 来实现文档

我们下面会使用 Typescript 作为主要开发语言 yarn add -D typescript, 要在 Docz 中使用 TS 组件还需要做简单的配置

/*
    1. /doczrc.js 项目根目录创建 doczrc.js 作为 docz 的配置文件，加入如下配置
*/ 
export default {
  typescript: true,
}

/*
    2. tsconfig.json 项目根目录创建 tsconfig.json 作为 TS 的配置文件
*/
{
  "compilerOptions": {
    "target": "es5",
    "lib": [
      "dom",
      "dom.iterable",
      "esnext"
    ],
    "allowJs": true,
    "skipLibCheck": true,
    "esModuleInterop": true,
    "allowSyntheticDefaultImports": true,
    "strict": true,
    "forceConsistentCasingInFileNames": true,
    "module": "esnext",
    "moduleResolution": "node",
    "resolveJsonModule": true,
    "isolatedModules": true,
    "noEmit": true,
    "jsx": "react"
  },
  "include": [
    "src"
  ]
}

/*
    3. /src/components/Button/(index.tsx | Button.tsx) 创建组件文件
*/
/*
  Button.tsx 实际的组件实现
*/ 
import * as React from 'react';

interface IButtonProps {
  className?: string;
  children?: React.ReactChildren;
  type?: 'primary' | 'Error' | 'default';
  size?: 'large' | 'small' | 'default';
}

const Button = (props: IButtonProps) => {
  const color = props.type === 'primary' ? '#5352ED' : props.type === 'Error' ? 'FF4757' : '#333333'
  const height = props.size === 'large' ? 40 : props.size === 'small' ? 24 : 32;
  return (
    <button className={props.className} style={{
      padding: '0 18px',
      borderRadius: 4,
      backgroundColor: '#fff',
      borderColor: color,
      color,
      height
    }}>
      {props.children}
    </button>
  )
}
Button.defaultProps = {
  type: 'primary',
  size: 'default'
}

export default Button;

/*
  index.tsx 组件的入口，负责最终输出内容的整合
  具体实现组件代码在与目录同名的组件内实现
*/

import Button from './Button';

export default Button;

以上就完成了一个简单的组件创建，如果是使用 Jsx 来开发则需要使用 prop-types 来帮助类型定义

<Playground> 组件

<Playground><CustomComponentUse></Playground> ： 被这个组件包裹的组件会被渲染到文档中，并附加一个可编辑的代码区域，在这个区域改动代码可以实时的查看到组件的变化，这个功能既可以用来查看代码，又可以用来编辑开发组件，我们在 Button.tsx 同级别的目录创建一个 名为 Button.mdx 的文档作为组件的说明

---
name: Button
menu: Components
---

import { Playground } from 'docz'; // 引入docz 提供的组件展示平台
import Button from './index.tsx'; // 引入我们开发的组件

# Button 按钮组件


## Basic usage

<Playground>
  <Button>Open</Button>
  <Button type="error">Open</Button>
  <Button type="default">Open</Button>
</Playground>

针对一些复杂的演示场景，我们通常需要 state 来进行状态转换，这个时候可以使用 useState 来实现

// 在 Button.mdx 中加入如下内容
## 复杂一点，带有状态管理的使用

<Playground>
  {() => {
    const [status, setStatus] = React.useState('primary');
    function onButtonClick() {
      setStatus(status === 'primary' ? 'error' : 'primary');
    }
    const color = status === 'primary' ? '#5352ED' : '#FF4757';
    return (
      <div>
        <Button onClick={onButtonClick} type={status}>change Status</Button>
        <div style={{
          backgroundColor: color, 
          color: '#fff',
          textAlign: 'center',
          padding: 10,
          marginTop: 20
        }}>
          button status
        </div>
      </div>
    );
  }}
</Playground>

<Props> 属性文档组件

组件库文档最重要的目的就是告诉开发者，我们的组件要怎么用，一个好的属性文档可以解决大部分问题， Docz 提供一个 名为 <Props> 的组件，可以通过简单实用实现属性文档，但是使用的前提是你要使用了 prop-types 或者你的组件是 Typescript 编写的

// 1. 首先给我们的 Button 组件属性增加一些注释 尽量使用 这种格式（`/** 说明内容 */`）的注释，否则不会被使用

// Button.tsx
interface IButtonProps {
  /** 允许覆盖样式 */
  className?: string;
  /** 可以传入 children */
  children?: React.ReactChildren;
  /** 组件类型 */
  type?: 'primary' | 'error' | 'default';
  /** 组件大小 */
  size?: 'large' | 'small' | 'default';
  /** 
   * 单击事件, // 注意这种多行的也可以 起始两个 **
   */
  onClick?: () => void;
}

// 2. 在 Button.mdx
文档中加入

## 组件 Props 

<Props of={Button}/>

配置后效果如下

3. 文档的配置

可以发现每个 mdx 文件的顶部总有一个通过 --- 规划的区域，这个区域就是当前这个 mdx 文档的配置，默认的配置有如下三个，除此之外我们还可以自定义配置

• name : 文档名称，会显示到导航部分
• route(选填) : 文档生成后显示的路由或者路径 设置后通过这个路径可以访问文档 （可能需要重启下项目）
• menu(选填) : 侧边菜单的分类
• 除此之外可以我们可以做一些自定义的设置，这些设置会被 docz 收集，我们在后续 “定制化 Docz” 的阶段在讲解如何使用

4. 文档的发布

运行 yarn docz:build 即可生成静态资源到 .docz/dist 目录，如果想要编译到指定为目录，可以在 doczrc.js 文件中配置 dest

// doczrc.js
export default {
  dest: '/build', // 再次执行 yarn docz:build 静态资源就会被生成到 /build 目录下
  typescript: true,
};

有的时候文档需要发布到非根路径下，例如 要发布到 https://your-username.github.io/docz 这个时候可以配置 base

export default {
  typescript: true,
  base: '/docz'
};

5. 如果组件使用了 css 预处理器

如果组件使用了 css 预处理器例如 sass less , 那么我们还需要做些配置，docz 的底层是使用 gatsby 实现的，我们需要下载 gatsby 的相关插件，以使其适配 css 预处理器

// Sass 项目
// 1. 下载插件
// yarn add -D node-sass gatsby-plugin-sass

// 2. 根目录创建 gatsby-config.js 配置文件
module.exports = {
  plugins: ['gatsby-plugin-sass']
}

// 3. 然后我们就可以给组件创建扩展名为 .scss 的样式文件,并且在 组件中以及 mdx 中使用了

// Less 项目
// 1. 与 sass 项目类似只要下载如下插件，在进行 gatsby 配置即可
// yarn add -D less gatsby-plugin-less

// 2. 根目录创建 gatsby-config.js 配置文件
module.exports = {
  plugins: ['gatsby-plugin-less']
}