大厂技术 高级前端 Node进阶
点击上方 程序员成长指北,关注公众号
回复1,加入高级Node交流群
AntDesign
这样的UI组件库,除了自身功能完善,良好的文档支持,也是开发者乐于使用的一大原因。
如标题,类似AntDesign的组件库文档,到底是用什么写的呢?(注意,我们本次讨论的是文档书写,而非组件本身) 😜
这里得先定义下,我们想要的文档,需要哪些必要元素?
真实组件的渲染,可交互,最好能直接复制代码
支持markdown
列出组件的所有属性(API),包括类型、说明、默认值等
按照这个目标,搜罗到市面上的现有的相关框架,有下面这些:
dumi
bisheng
storybook[2]
gitbook
vuepress
docsify
考虑到dumi
和AntDesign
是React开发,以及蚂蚁的背景,这次我们拿dumi
来一探究竟,看能否实现我们想要的东西。
文章较长,建议先 点赞、收藏。🤣
0、一些你可能需要的前置知识(别点,用到时可以回来看🤣)
dumi官网[3]
AntDesign组件文档[4]
1、初始化
从头开始,我们先初始化一个dumi
工程叫my-dumi-doc
mkdir my-dumi-doc && cd my-dumi-doc
yarn create @umijs/dumi-lib --site
yarn
复制代码
![42c7c7ebe2062be6c3a53990041d4e29.png](https://i-blog.csdnimg.cn/blog_migrate/ebfd69b3d5797eed8d12e77bd3296e3c.png)
这里需要注意,node 版本必须是
10.13
以上。无法成功安装的小伙伴,记得切换 node 版本。
跑起来看看
yarn start
复制代码
首页:
![d65d09edeebfea710fa12c3a2383bdd2.png](https://i-blog.csdnimg.cn/blog_migrate/c3e37db875a973d51c1f977f2b09a054.png)
详情页:
![f6f730cad3e919e4a928ec8f18975baf.png](https://i-blog.csdnimg.cn/blog_migrate/056eeeadc41e17e1475ca93241a77cb6.png)
到此,我们已经看到一个组件文档的雏形。接下来需要仔细看下目录结构。
![13495db9df185cb1e264b25683d4dd27.png](https://i-blog.csdnimg.cn/blog_migrate/03f62888082cefc715142b62f694bd24.png)
src
目录下,一个组件一个目录,默认的例子生成了
md 文档(index.md)
组件源码(index.tsx)
测试文件(index.test.tsx)
写过组件的同学,都知道这样一个目录结构,基本是标配。但因为我们本次是重在文档书写,其实可以只保留 md 文档。
如上图也能看到,md 文档内,jsx
和 tsx
的代码块将会被 dumi 解析为 React 组件。这正好帮我们做到了第一个点:真实组件的渲染。👍
2、目录结构和路由
我们在src
下写多两个组件,看下浏览器里的文档会变成什么样。
分别新建一个MyButton/index.md
、MyModa/index.md
,
![5d440cb9c9f80614ad8ebcd09142a854.png](https://i-blog.csdnimg.cn/blog_migrate/796ee0ce27826b58e837b910f79e2eee.png)
内容如下:
<!-- /src/MyButton/index.md -->
## MyButton
复制代码
<!-- /src/MyModal/index.md -->
## MyModal
复制代码
刷新浏览器,效果如下:
![3d8f10de7551f594e013cd8dafe7a10a.png](https://i-blog.csdnimg.cn/blog_migrate/8107dfb7be98ac24ddc21606d36c3501.png)
能看到,导航栏立马有了。
看着还不戳,不过,一个组件占一个一级导航,并不是我们想要的,我们按照 FrontMAtter
语法,做如下调整:
<!-- /src/MyButton/index.md -->
---
nav:
title: Components
path: /components
group:
title: MyButton
---
## MyButton
复制代码
<!-- /src/MyModal/index.md -->
---
nav:
title: Components
path: /components
group:
title: MyModal
---
## MyModal
复制代码
刷新浏览器再看下,嗯,是我们想要的样子了。
![1b8a5e619248ba378d36090521617fa2.png](https://i-blog.csdnimg.cn/blog_migrate/f68129e3df81fa414cc44d9d0f41b286.png)
上面有提到
FrontMAtter
语法,文档在这:d.umijs.org/zh-CN/confi…[5]
接下来,我们就需要简单提供下MyButton
、MyModel
两个组件的源码,试着在 md
文档里引入试试。
3、组件完善
因为组件编写不是重点,这里我们引入Antd
,分别继承它提供的Button
、Modal
组件,快速完善源代码。
安装 Antd
yarn add antd
复制代码
新建一个MyButton/index.tsx
,内容如下:
import React from 'react';
import { Button, ButtonProps } from 'antd';
import 'antd/dist/antd.css';
export interface MyButtonProps extends ButtonProps {
isMy?: boolean;
}
const MyButton: React.FC<MyButtonProps> = (props) => {
const { children, ...restProps } = props;
return (
<Button {...restProps}>{children}</Button>
);
}
export default MyButton;
复制代码
能看到,我们只对 Button
组件做个简单的包装,多加了一个 isMy
属性。
接下来,在/src/MyButton/index.md
里引入并使用它。
![2e98a16f03402b10ced622693597816e.png](https://i-blog.csdnimg.cn/blog_migrate/58c1c1d2571a73ee4626236d35a77895.png)
哎呀,上面直接贴图了,代码块套代码块好像显示有问题。文末有仓库地址,记得去看。🤡
对了,组件还需在 /src/index.ts
里引入,不然会有报错😅。/src/index.ts
是组件的入口文件。
export { default as MyButton } from './MyButton';
复制代码
![cd4e8c2f258a2cdb3fca09e207190e99.png](https://i-blog.csdnimg.cn/blog_migrate/cf79377b2682c1b6f67b95e2352e23eb.png)
回到浏览器,这时应该可以看到下方的画面了。
![4ccb4cd26d501dcfde80f23b1cad8873.png](https://i-blog.csdnimg.cn/blog_migrate/9dfac85eabb96abaaa02c659b7296daf.png)
Antd
自带的 Button
组件,已经渲染在页面上,也能正常交互。
相应的,我们完善下 MyModal
。
新建一个MyModal/index.tsx
,内容如下:
import React from 'react';
import { Modal, ModalProps } from 'antd';
import 'antd/dist/antd.css';
export interface MyModalProps extends ModalProps {
isMy?: boolean;
}
const MyModal: React.FC<MyModalProps> = (props) => {
const { children, ...restProps } = props;
return (
<Modal {...restProps}>{children}</Modal>
);
}
export default MyModal;
复制代码
在 /src/MyModal/index.md
里引入并使用它
![9e64a3da3be349b5241a4f69f11ab1ac.png](https://i-blog.csdnimg.cn/blog_migrate/ad875f8929e36486d3e3e35fc4ed912d.png)
回到浏览器,Modal
应该也能被渲染出来了。
![10e7d1c8e61ba50fa75ca6e2665380d0.png](https://i-blog.csdnimg.cn/blog_migrate/b2331029ed10f9a6a5d65940bbbcc6b1.png)
点击事件也能被正确响应。
![e46058e474ec40b97b3e9faed0eb6105.png](https://i-blog.csdnimg.cn/blog_migrate/f2e07095aa8287b6aa0302889bb0531e.png)
至此,我们最初定义的前两条必要元素,都已经实现。接下来是组件 API
的书写。
4、API的生成
已经支持 md
了,一点点用表格语法手动写,也能达到最终的效果。
| Name | Description | Type | Default |
|------|-------------|---------|---------|
| isMy | 自定义属性 | boolean | - |
| ... | ... | ... | ... |
复制代码
![67b1f4548ba309305f09898bc6111277.png](https://i-blog.csdnimg.cn/blog_migrate/498997a5c082d6f4d504be5ba50fc159.png)
但这并不是我们想要的结果。
如果你的组件遵从 TypeScript 类型定义 + JS Doc 注解,dumi
能自己推导出 API 的内容。
参考文档:d.umijs.org/zh-CN/guide…[6]
我们在 md
文件末尾,追加上 dumi
内置的组件 API
,用来渲染API表格。
<API></API>
复制代码
效果如下,看起来相当不错。描述、类型啥的,已经自动帮我们填充好了。
![bea8cdfadd52015c54261e9ff266c479.png](https://i-blog.csdnimg.cn/blog_migrate/58e2a6f94423d3f778fd434a64d944f7.png)
学着 JS Doc 注解,也来完善下那个唯独是我们添加的 isMy
属性
![226526b858b35c7530521af5ff09e405.png](https://i-blog.csdnimg.cn/blog_migrate/da443fb6c8bf05110314e35848530d0f.png)
回到浏览器刷新页面,效果立马就看到了,这可真是方便啊。
![0c0a8f6c4af023fe1d6a94bf008ebf63.png](https://i-blog.csdnimg.cn/blog_migrate/d2be163b122ebb7e0f7e780955810ce2.png)
至此,我们想要的组件文档书写三要素,都已齐活。dumi
在文档书写上的便利,还请小伙伴多多尝试呀。
本次练手的工程也已上传到 github,看这里:my-dumi-doc[7]
最后最后,原创不易,欢迎给波 点赞、评论、关注、收藏。
关于本文
作者:这个需要威少看下
https://juejin.cn/post/7070156525842464781
Node 社群
我组建了一个氛围特别好的 Node.js 社群,里面有很多 Node.js小伙伴,如果你对Node.js学习感兴趣的话(后续有计划也可以),我们可以一起进行Node.js相关的交流、学习、共建。下方加 考拉 好友回复「Node」即可。
如果你觉得这篇内容对你有帮助,我想请你帮我2个小忙:
1. 点个「在看」,让更多人也能看到这篇文章2. 订阅官方博客 www.inode.club 让我们一起成长
点赞和在看就是最大的支持❤️