前言
随着前端技术的发展，我们不仅需要完成基本的功能实现，还需要考虑代码结构、可读性、可复用性等方面。这时一个良好的文档就显得非常重要了。@storybook/addon-docs 就是一个能够帮助我们方便地为 React 组件生成文档的工具，今天我们就来学习一下它的使用方法。
安装
@storybook/addon-docs 是 Storybook 子项目中的一个附加组件，需要我们先安装 Storybook 后再进行安装。具体步骤如下：
- 安装 Storybook：
npm install @storybook/react --save-dev
- 安装 addon-docs：
npm install @storybook/addon-docs --save-dev
使用
安装完成后，在 .storybook/addons.js 文件中加入：
import '@storybook/addon-docs/register';
这个文件用于 Storybook 所有附加组件的注册。
在 .storybook/config.js 文件中加入：
-- -------------------- ---- ------- ------ - ---------- ------------ - ---- ------------------- ------ - -------- - ---- ------------------------ ------ - -------- - ---- ------------------------ ----- --- - ----------------------------- ----- ----------------- -------- ------------- - ----------------------------- -- -------------- - ----------------------- ----------------------- ---------------------- --------
这个文件用于配置 Storybook。
现在就可以开始为组件添加文档了。我们提供的文档可以分为两部分：
- 组件的描述文档。
在组件文件中添加一个格式如下的文档注释即可：
-- -------------------- ---- -------
------ ----- ---- --------
---
- ---- ------ ---
-
- ------ -------- ---- - --------
- ------ -------- ---- - -----------------------------
- ------ ---------- ------- - -----------
- -------- ----------------- ------ ---
--
----- ------ - -- ----- ---- - ---------- ------- -- -- -
------ -
------- --------------- --------- ------------------
------
---------
--
--
------ ------- -------- 组件的用例文档。
在 .stories.js 文件中添加一个格式如下的文档即可：
-- -------------------- ---- -------
------ ----- ---- --------
------ - --------- - ---- -------------------
------ ------ ---- -----------
------------------- -------
----------------
----- -
----- -
---------------------------------------
--
--
--
--------------- -- -- -
------- --------- ----------- -- -------------------- --
--
--------------- -- -- -
-------
----------
--------------
----------- -- ---------------------
--
--
-------------- -- -- -
-------
-----------
-------------
----------- -- ----------------------
--
---这个文档的参数表示为 Button 组件添加一些描述信息，并添加了三个示例用例（默认类型的按钮、主要类型的按钮和危险类型的按钮）。
示例代码
-- -------------------- ---- -------
------ ----- ---- --------
---
- ---- ------ ---
-
- ------ -------- ---- - --------
- ------ -------- ---- - -----------------------------
- ------ ---------- ------- - -----------
- -------- ----------------- ------ ---
--
----- ------ - -- ----- ---- - ---------- ------- -- -- -
------ -
------- --------------- --------- ------------------
------
---------
--
--
------ ------- --------- -------------------- ---- -------
------ ----- ---- --------
------ - --------- - ---- -------------------
------ ------ ---- -----------
------------------- -------
----------------
----- -
----- -
---------------------------------------
--
--
--
--------------- -- -- -
------- --------- ----------- -- -------------------- --
--
--------------- -- -- -
-------
----------
--------------
----------- -- ---------------------
--
--
-------------- -- -- -
-------
-----------
-------------
----------- -- ----------------------
--
---总结
通过本文的介绍，我们学习了如何使用 @storybook/addon-docs 为 React 组件生成文档，以及如何利用它更好地为我们的项目进行文档管理。使用文档能够提高我们代码的可读性、可维护性，更好的利用它，能够游刃有余地进行项目开发。
来源：JavaScript中文网 ，转载请注明来源 https://www.javascriptcn.com/post/storybook-addon-docs