react-slingshot 组件文档生成：Storybook 集成教程

鲁日姝Hunter

274人浏览 · 2025-10-21 02:06:37

鲁日姝Hunter · 2025-10-21 02:06:37 发布

react-slingshot 组件文档生成：Storybook 集成教程

【免费下载链接】react-slingshot React + Redux starter kit / boilerplate with Babel, hot reloading, testing, linting and a working example app built in 项目地址: https://gitcode.com/gh_mirrors/re/react-slingshot

为什么需要 Storybook？

在开发 React 组件时，你是否遇到过这些问题：组件在不同页面复用导致样式冲突、新功能开发意外破坏旧组件、团队协作时组件用法不清晰？Storybook（故事书）是一个开源工具，它能帮助开发者独立构建、测试和展示 UI 组件，让组件开发脱离业务环境，大幅提升开发效率和组件质量。

环境准备

react-slingshot 是基于 React 和 Redux 的 starter kit，首先确保项目已正确初始化：

git clone https://gitcode.com/gh_mirrors/re/react-slingshot
cd react-slingshot
npm install

查看项目 package.json 文件了解现有依赖和脚本：package.json

安装 Storybook

由于项目使用较旧的依赖版本，需要指定兼容的 Storybook 版本并使用 --legacy-peer-deps 解决依赖冲突：

npm install --save-dev @storybook/react@6.5.16 @storybook/addon-docs@6.5.16 --legacy-peer-deps

配置 Storybook

创建 Storybook 配置目录和主配置文件：

mkdir -p .storybook
touch .storybook/main.js

在 .storybook/main.js 中添加配置：

module.exports = {
  stories: ['../src/components/**/*.stories.js'],
  addons: ['@storybook/addon-docs']
};

编写组件故事

以 FuelSavingsTextInput 组件为例，创建故事文件：

touch src/components/FuelSavingsTextInput.stories.js

添加以下内容：

import React from 'react';
import FuelSavingsTextInput from './FuelSavingsTextInput';

export default {
  title: 'Components/FuelSavingsTextInput',
  component: FuelSavingsTextInput,
};

export const Default = () => (
  <FuelSavingsTextInput
    name="gallons"
    value="10"
    onChange={() => {}}
    placeholder="Enter gallons"
  />
);

export const WithLabel = () => (
  <FuelSavingsTextInput
    name="mpg"
    value="30"
    onChange={() => {}}
    label="Miles Per Gallon"
  />
);

启动 Storybook

添加启动脚本到 package.json：

"scripts": {
  "storybook": "start-storybook -p 6006"
}

运行 Storybook：

npm run storybook

浏览组件文档

打开浏览器访问 http://localhost:6006，即可看到 FuelSavingsTextInput 组件的不同状态展示。通过左侧导航可以切换不同组件和故事，右侧面板可以查看组件源码和文档。

常见问题解决

依赖冲突：使用 --legacy-peer-deps 参数安装依赖
组件样式丢失：在 .storybook/preview.js 中导入全局样式：
```
import '../src/styles/styles.scss';
```
启动失败：检查 Node 版本是否符合要求（>=8），参考 package.json 中的 engines 配置