深入理解Storybook项目实战：从入门到上手

概述

Storybook项目实战指南介绍如何构建和测试UI组件，采用组件优先的开发流程，支持快速迭代与复用。通过本地环境准备、安装故事书、创建基本组件与Markdown文档，以及编写故事实例，实现组件的描述与功能展示。实践还包括故事编写、组件库共享与协作，以及部署与集成到现有项目中，以加速开发流程和提高团队效率。

起源与基本功能

Storybook 是由 Facebook 开发并维护的一款用于 UI 组件开发和测试的强大工具。它允许开发者在一个集中环境中创建、测试和共享组件，而无需在项目中构建完整的页面。Storybook 的核心理念是组件优先的开发流程，支持组件的快速迭代和复用，同时提供了一种易于维护和理解的组件库组织方式。

本地环境准备

首先，确保你的环境中已安装 Node.js 和 npm（Node 包管理器）。然后，你可以在项目根目录下通过命令行执行以下命令来全局安装 Storybook：

npm install -g @storybook/cli

接下来，为你的项目安装 Storybook：

npm install --save-dev @storybook/react @storybook/react-webpack5

项目目录结构

创建一个基本的项目目录结构，通常包括以下部分：

my-storybook-project
│
├── node_modules
│
├── package.json
│
├── src
│   ├── components
│   │   └── Button.js
│   ├── docs
│   │   └── Button.md
│   └── App.js
│
└── storybook.config.js

Markdown 文档与组件描述

在 docs 目录中，为每个组件创建一个 .md 文件，用于描述组件的功能、用法以及任何特定的参数或属性。例如，为 Button 组件创建一个文件：

# Button

## 使用示例

### 基本按钮

```jsx
import Button from './Button';

function MyComponent() {
  return <Button label="点击我" />;
}

自定义文案按钮

import Button from './Button';

function MyComponent() {
  return <Button label="自定义按钮" />;
}

按钮状态变化

import Button from './Button';
import { useState } from 'react';

function MyComponent() {
  const [state, setState] = useState(false);
  const handleClick = () => setState(!state);

  return (
    <>
      <Button label="切换状态" onClick={handleClick} />
      <p>当前状态: {state ? '已激活' : '未激活'}</p>
    </>
  );
}

创建故事

在每个 .md 文件中，可以通过添加 stories: 部分来定义不同的故事实例，展示组件的不同用例。例如，在 Button.md 文件中：

# Button

## 基本按钮

### 默认样式

```jsx
import Button from './Button';

function MyComponent() {
  return <Button label="点击我" />;
}

主题变更

import Button from './Button';
import { theme } from '@theme';

function MyComponent() {
  const buttonTheme = theme.button.theme;
  return <Button theme={buttonTheme} label="主题按钮" />;
}

状态改变

import Button from './Button';
import { useState } from 'react';

function MyComponent() {
  const [isActive, setActive] = useState(false);
  return (
    <>
      <Button label="动态状态按钮" onClick={() => setActive(!isActive)} />
      <p>当前状态: {isActive ? '激活' : '未激活'}</p>
    </>
  );
}

动画效果

import Button from './Button';
import { useEffect } from 'react';

function MyComponent() {
  useEffect(() => {
    const timer = setTimeout(() => {
      console.log('按钮加载完毕');
    }, 2000);
    return () => clearTimeout(timer);
  }, []);

  return <Button label="加载动画" />;
}

GitHub 集成

将你的 Storybook 项目托管在 GitHub 上，并使用 GitHub Actions 自动构建和部署 Storybook。这样，团队成员可以直接通过提交代码来触发构建，查看组件库的最新状态。

权限设置

通过 GitHub 的权限设置，允许特定团队成员访问和编辑 Storybook。同时，可以设置只读权限的团队，用于展示和测试组件库。

部署到 GitHub Pages

使用 GitHub Pages 部署 Storybook 的静态页面，可以通过 .nojekyll 文件来确保文件结构正确解析：

touch .nojekyll

然后在 package.json 中配置 deploy 脚本：

"scripts": {
  "deploy": "next export && cd out && git init && git add . && git commit -m 'deploy' && git remote add origin git@github.com:username/project.git && git push -u origin master"
}

集成到现有项目

通过引入 @storybook/nextjs 插件，将 Storybook 与 Next.js 项目集成，让开发者可以在开发过程中直接访问组件库。

npm install --save-dev @storybook/nextjs

// next.config.js
module.exports = {
  experimental: {
    serverActions: true,
    serverActionsTimeout: 5000
  },
  webpack(config, { isServer }) {
    if (!isServer) {
      config.plugins.push(new StorybookPlugin());
    }
    return config;
  },
};

通过遵循这些步骤，你可以构建和维护一个高效、协作的 UI 组件库，利用 Storybook 提供的工具和功能加速开发流程，提高代码质量和团队效率。