组件库文档搭建-Storybook

发表于 更新于 本文字数： 1.6k 阅读时长 ≈ 3 分钟
本文介绍关于组件库文档搭建-Storybook，包括使用场景、实现细节等，以提高关于组件库文档搭建-Storybook的效率。

最近参与组件库开发，为更好的推广使用组件库，需要搭建下文档。调研了几款组件库文档框架，务实的选择了storybook，因为其流行且满足诉求。

框架简单，但还是踩了些坑，这里mark下。

使用

1
2
3
4
5
# 初始化
$ npx sb init

# 热启动，即可WEB浏览
$ npm run storybook

注意

sb init is not made for empty projects，init执行是在在组件库根目录下，并非空目录下执行初始化命令，storybook会将配置加到项目原先配置中

说明

如上命令执行后即可正常浏览，剩下工作是按需进行的一些特殊配置及开始书写组件库例子代码了。

项目配置

简单描述下文档库相关文件

  1. .storybook文件夹中即为文档相关配置

    1. main.js

      主配置，无论是打包还是预览均需要

    2. preview.js

      预览的相关配置

  2. 代码中所有后缀为.stories.tsx文件即为配套文档描述文件

    也可以选择mdx格式

组件stories.tsx

  • 注意title中的/用于控制多级story，从而形成多级菜单，可以是2+层级目录

  • 关于组件相关描述有两种

    • 组件描述是在组件类/函数增加多行注释

    • 字段描述是在组件参数字段上增加多行注释

      以上注释必须是多行注释符号

常见问题

  1. 导入公共样式CSS文件

有时组件依赖某个全局样式，而预览时也需要保障全局加载，解决办法是在.storybook/preview.js中手动导入

1
import 'tea-component/dist/tea.css';
  1. 发布包时，TSC exclude stories.tsx文件

该文档方案下，组件与组件文档是放在一块，而比如组件编译发版是不需要编译打包story文件，因此对于编译组件的tsconfig文件可以通过exclude排除下文件

1
2
3
4
5
6
7
{
 "exclude": [
    "node_modules",
    "test/**/*",
    "lib/**/*.stories.tsx"
  ]
}

​ 针对整体项目的tsconfig文件注意还是包含下story文件，毕竟都是TS程序文件，整体类型安全比较合适。

  1. 解决i18n-t函数问题

    如果是全局初始化需要执行执行的函数，可以在.storybook/preview.js中执行，类似全局样式问题。

    1
    2
    3
    const translation = {};
    // 初始化国际化词条
    i18n.init({translation});

  2. Parsing error: “parserOptions.project” has been set for @typescript-eslint/parser.

Parsing error: “parserOptions.project” has been set for @typescript-eslint/parser.
The file does not match your project config: lib/button.stories.tsx.
The file must be included in at least one of the projects provided.

该报错是因为eslint配置中声明了使用tsconfig文件，而文件中对应include的文件并没有包含当前文件。解决办法是修改tsconfig include，确保包含该文件。

  1. Default export of the module has or is using private name ‘HeaderProps

  2. 组件参数description不热更？

当修改组件参数类型注释时，发现并没有实时更新，

延伸

参考资料