在前端开发过程中，我们经常需要在 React 项目中编写文档，以便团队成员更好地了解代码和组件的使用方法。为了方便编写文档，可以使用 @jcribeiro/babel-plugin-react-docgen 这个 npm 包来自动生成组件文档，本文将详细介绍它的使用方法。
什么是 @jcribeiro/babel-plugin-react-docgen
@jcribeiro/babel-plugin-react-docgen 是一个基于 Babel 的插件，它可以在编译过程中分析 React 组件并生成组件的文档信息，如 props、propTypes、defaultProps、state 等，以及描述组件的注释。这个插件可以帮助我们避免手动编写组件文档的繁琐工作，提高开发效率。
安装 @jcribeiro/babel-plugin-react-docgen
使用 @jcribeiro/babel-plugin-react-docgen 必须先安装它和 babel-core（如果你还没有安装 babel-core）：
npm install --save-dev @jcribeiro/babel-plugin-react-docgen babel-core
配置 Babel
安装完依赖后，需要修改 babel 配置，在 .babelrc 或 package.json 中添加如下配置：
-- -------------------- ---- -------
-
---------- -
--------------------
--
------ -
-------------- -
---------- -
--------------------------------------
-
-
-
-其中，presets 的配置根据你的项目而定，这里以 babel-preset-react 为例；env 的 development 字段是用于开发环境的配置，production 字段是用于生产环境的配置，这里只演示开发环境的配置。@jcribeiro/babel-plugin-react-docgen 必须放在 plugins 中，以便在编译时被执行。
生成组件文档
配置完成后，重新编译项目，在编译过程中，@jcribeiro/babel-plugin-react-docgen 会扫描项目中的所有 React 组件，并生成相应的文档信息。生成的文档信息默认保存在文件 .react-docgen.json 中，你可以手动指定一个路径，如：
"plugins": [
[
"@jcribeiro/babel-plugin-react-docgen", {
"DOC_GEN_COLLECTION_NAME": "STORYBOOK_REACT_CLASSES",
"DOC_GEN_COLLECTION_PATH": "node_modules/storybook-readme/dotcom/components.js"
}]
]说明：
DOC_GEN_COLLECTION_NAME：定义一个名字，以便 Storybook 等库可以引用组件集合。
DOC_GEN_COLLECTION_PATH：定义组件集合文件的输出路径。
完成上述配置后，再次运行 npm run build，即可在指定的路径下找到生成的文档信息。
在文档中使用组件
文档生成完毕后，可以通过 Storybook 等库来展示组件库。以 Storybook 为例，它可以扫描与组件集合同一级目录下的 README.md 或 README.markdown 文件，自动生成文档页面。在文档中使用组件时，我们需要先引入组件集合，在使用之前先注入到 Storybook 中，如下所示：
-- -------------------- ---- ------- ------ ----- ---- -------- ------ - ----------- - ---- ------------------------ ------ - ---------- --------- ------------ - ---- ------------------- ------ ---------- - ----------- -- --------------- - ---- ------------------------ -- ------ ------ - -------------- - ---- ------------------------------- ------ ----------------------------------- ------ ------------------ -- ------ ----------------------------- -------------------- -- ------ ----------------- ------- ----- ------- ------ ------- ----- --- ------------- ------- ----- --- -- ---- ------- ------ ----- --- - ------------------------- ----- --------------- -------- ------------- - ------------------------ - ---------------------- --------
其中，withPropsTable 是 @jcribeiro/babel-plugin-react-docgen 提供的一个辅助函数，其作用是将组件集合加入到 Storybook 中，以便在使用组件时可以自动生成文档信息。
示例代码
下面是一个简单的 React 组件：
-- -------------------- ---- -------
------ ------ - --------- - ---- --------
---
- ----- --
-
- ----------
-
- --------
-
- ------ ------------ ------- --
-
- ----- -------- ---- - ------ -------
- ----- -------- --- - --
--
----- ----- ------- --------- -
-------- -
----- - ---- - -------- --- - - - - -----------
------ -
-----
------ ------- -----
------
--
-
-
------ ------- ------在使用 @jcribeiro/babel-plugin-react-docgen 后，这个组件会自动生成一个名为 .react-docgen.json 的文件，其中包含如下信息：
-- -------------------- ---- -------
-
-------- -
-------------- ------ ----
---------- ---
-------- -
------- -
------- -
------- --------
--
----------- ------
-------------- ------- ----------
--
------ -
------- -
------- --------
--
----------- ------
-------------- ----
-
-
-
-在使用了组件集合 withPropsTable 后，在 Storybook 中使用组件时，即可自动获得这个组件的文档信息，方便开发人员查看和使用：
import React from 'react';
import { storiesOf } from '@storybook/react';
import Hello from './Hello';
storiesOf('Hello', module).add('default', () => <Hello />);总结
使用 @jcribeiro/babel-plugin-react-docgen 插件，可以方便地自动生成 React 组件的文档信息，避免手动编写文档的繁琐工作，提高开发效率。同时，本文还演示了如何在 Storybook 等库中快速使用组件集合，并自动生成组件文档信息，以方便开发人员查看和使用。
来源：JavaScript中文网 ，转载请注明来源 https://www.javascriptcn.com/post/60057bc281e8991b448eb9bb