初学者的storybook学习指南

概述

本文详细介绍了如何进行storybook学习，包括其基本概念、安装配置、组件创建与展示，以及高级功能和定制化设置，帮助开发者高效利用Storybook进行UI组件开发和管理。

Storybook简介

Storybook是什么

Storybook 是一个开源的开发工具，专为 UI 组件设计、开发和文档化而创建。它提供了一个独立的开发环境，使得开发人员可以专注于组件级别的开发，而无需处理整个应用程序的复杂性。通过这个工具，你可以独立地测试、预览、文档化和管理组件。

Storybook的作用和好处

1. 组件化开发：将应用程序分割为独立的组件，便于管理和复用。
2. 实时预览：在 Storybook 中可以实时预览组件的效果，不需要重新启动整个应用。
3. 文档生成：自动为每个组件生成详细的文档，方便团队成员参考和使用。
4. 状态管理：可以创建不同的状态和场景，帮助开发人员更好地理解组件的行为。
5. 版本控制：支持版本控制，便于追踪组件的变化历史。
6. 集成测试：可以与各种测试工具集成，进行组件级别的测试。
7. 团队协作：通过 Storybook，团队成员可以在单一的环境中协作工作，便于沟通和协作。

Storybook支持的技术栈

• React: Storybook 与 React 组件的兼容性非常好。
• Vue: 支持 Vue 组件的开发和预览。
• Angular: 支持 Angular 组件的开发和预览。
• Web Components: 支持 Web Components 的开发和预览。
• 其他技术栈: 除了上述几种主流的技术栈外，Storybook 也支持其他一些技术栈。

Storybook安装与配置 安装Node.js

首先，确保安装了 Node.js。可以通过官网下载安装包，或者通过 npm（Node.js 包管理器）进行安装。

检查Node.js是否已安装

在命令行中输入以下命令检查 Node.js 是否已安装：

node -v
npm -v

如果已安装，将会显示版本号；否则需要先安装 Node.js。

安装Node.js

安装 Node.js 的一个简单方法是通过官网下载并安装最新版本。也可以通过以下命令使用 Node Version Manager (NVM) 安装 Node.js：

# 安装 NVM
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.1/install.sh | bash

# 安装 Node.js 的最新 LTS 版本
nvm install --lts

# 设置默认 Node.js 版本
nvm alias default v16.13.2

初始化项目

创建一个新的项目

假设你正在使用 React 作为项目的技术栈，下面是在命令行中初始化一个新项目的步骤：

1. 创建项目目录：

mkdir my-storybook-project
cd my-storybook-project

1. 初始化一个新的 React 项目：

npx create-react-app .

注意 ., 表示在当前目录创建项目。

安装Storybook插件

安装 Storybook 插件来支持 React 项目：

npx sb init

这将自动安装 Storybook 并配置好项目，你可以选择是否将 Storybook 集成到现有项目中。如果选择集成，Storybook 将会为 React 项目自动配置好依赖。

创建第一个Storybook组件 创建基本的React组件

首先，在项目的 src 目录中创建一个新的组件文件。例如，在 src/components 目录下创建一个 Button.js 文件：

// src/components/Button.js
import React from 'react';

const Button = ({ label }) => {
  return (
    <button>{label}</button>
  );
};

export default Button;

将组件添加到Storybook

在 Storybook 中引入并展示组件。在 src 目录下创建一个 stories 文件夹，并在其中创建一个 Button.stories.js 文件。

// src/stories/Button.stories.js
import React from 'react';
import { Story, Meta } from '@storybook/react';
import Button from '../components/Button';

const Template = args => <Button {...args} />;

export const Primary = Template.bind({});
Primary.args = {
  label: 'Button',
};

使用Storybook查看组件

运行 Storybook 服务器：

npm run storybook

这将启动 Storybook 服务器，你可以在浏览器中访问 http://localhost:6006 来查看 Storybook。在浏览器中打开后，你会看到一个类似下面的界面，其中会展示你创建的组件：

Storybook组件的高级功能 使用参数化Storybook组件

在 Storybook 中可以使用参数化来改变组件的行为。例如，在 Button.stories.js 中，我们可以通过参数化改变按钮的标签：

// src/stories/Button.stories.js
import React from 'react';
import { Story, Meta } from '@storybook/react';
import Button from '../components/Button';

const Template = (args) => <Button {...args} />;

export const Primary = Template.bind({});
Primary.args = {
  label: 'Primary',
};

export const Secondary = Template.bind({});
Secondary.args = {
  label: 'Secondary',
};

添加组件状态和交互

Storybook 支持添加组件状态和交互。例如，你可以创建一个带有状态的按钮组件：

// src/components/ToggleButton.js
import React from 'react';
import { useState } from 'react';

const ToggleButton = ({ label }) => {
  const [toggle, setToggle] = useState(false);

  return (
    <button onClick={() => setToggle(!toggle)}>
      {toggle ? 'On' : 'Off'}
    </button>
  );
};

export default ToggleButton;

在 stories 文件夹中创建一个 ToggleButton.stories.js 文件：

// src/stories/ToggleButton.stories.js
import React from 'react';
import { Story, Meta } from '@storybook/react';
import ToggleButton from '../components/ToggleButton';

const Template = (args) => <ToggleButton {...args} />;

export const Default = Template.bind({});
Default.args = {
  label: 'Toggle',
};

使用装饰器和参数

Storybook 支持装饰器来修改组件的渲染方式。例如，添加一个背景色装饰器：

// src/stories/Button.stories.js
import React from 'react';
import { Story, Meta } from '@storybook/react';
import Button from '../components/Button';

const Template = (args) => <Button {...args} />;

export const Primary = Template.bind({});
Primary.args = {
  label: 'Primary',
};
Primary.decorators = [
  (Story) => (
    <div style={{ backgroundColor: 'lightblue', padding: '20px' }}>
      <Story />
    </div>
  ),
];

export const Secondary = Template.bind({});
Secondary.args = {
  label: 'Secondary',
};
Secondary.decorators = [
  (Story) => (
    <div style={{ backgroundColor: 'lightgray', padding: '20px' }}>
      <Story />
    </div>
  ),
];

Storybook的样式与定制 添加全局样式

你可以通过 Storybook 的 .storybook/ 目录下添加全局样式文件。例如，创建一个 main.css 文件：

/* .storybook/main.css */
body {
  background-color: #f0f0f0;
  font-family: Arial, sans-serif;
}

在 Storybook 的 main.js 配置文件中引用这个样式文件：

// .storybook/main.js
module.exports = {
  stories: ['../src/**/*.stories.mdx', '../src/**/*.stories.js'],
  addons: [
    '@storybook/addon-links',
    '@storybook/addon-essentials',
  ],
  core: {
    builder: '@storybook/builder-vite',
  },
  staticDirs: ['../public'],
  webpackFinal: async (config) => {
    config.module.rules.push({
      test: /\.css$/,
      use: ['style-loader', 'css-loader'],
    });
    return config;
  },
};

自定义Storybook主题

Storybook 支持自定义主题，这可以通过 @storybook/theming 添加。例如，创建一个自定义主题文件：

// .storybook/preview.js
import { create } from '@storybook/theming';

export const theme = create({
  base: 'light',
  brandTitle: 'My Storybook',
  brandUrl: 'https://example.com',
  brandImage: 'https://example.com/logo.png',
});

你还可以通过调整 create 函数中的选项来自定义颜色、字体等其他属性。

使用附加模板和布局

你可以通过添加自定义模板来自定义 Storybook 的布局。例如，创建一个 iframe.html 文件并在 Storybook 的 .storybook 目录下添加：

<!-- .storybook/iframe.html -->
<!DOCTYPE html>
<html>
  <head>
    <meta charset="UTF-8" />
    <title>My Storybook</title>
    <link rel="stylesheet" href="./main.css" />
  </head>
  <body>
    <div id="storybook-root"></div>
  </body>
</html>

Storybook的测试与开发 Storybook与测试工具的集成

Storybook 可以与各种测试工具集成，如 Jest 和 React Testing Library。例如，安装 Jest 和 React Testing Library：

npm install --save-dev jest @testing-library/react @testing-library/jest-dom @storybook/testing-library

创建一个测试文件，例如 Button.test.js：

// src/components/Button.test.js
import React from 'react';
import { render } from '@testing-library/react';
import Button from './Button';

test('renders a button with the correct label', () => {
  const { getByText } = render(<Button label="Test Button" />);
  expect(getByText('Test Button')).toBeInTheDocument();
});

Storybook的版本控制和部署

你可以将 Storybook 的配置文件和源代码添加到版本控制系统中，例如 Git。这有助于团队成员保持一致的开发环境。你还可以将 Storybook 部署到 CI/CD 系统中，以便自动构建和部署。

配置 Git 仓库：

git init
git add .
git commit -m "Initial commit"
git remote add origin <repository-url>
git push -u origin master

部署 Storybook：

npx storybook-builder --build-storybook --dist ./.storybook/build

在 .storybook 目录下创建 main.js 和 preview.js 文件，并配置相关设置：

// .storybook/main.js
module.exports = {
  stories: ['../src/**/*.stories.mdx', '../src/**/*.stories.js'],
  addons: [
    '@storybook/addon-links',
    '@storybook/addon-essentials',
  ],
  core: {
    builder: '@storybook/builder-vite',
  },
  staticDirs: ['../public'],
  webpackFinal: async (config) => {
    config.module.rules.push({
      test: /\.css$/,
      use: ['style-loader', 'css-loader'],
    });
    return config;
  },
};

// .storybook/preview.js
import { create } from '@storybook/theming';

export const theme = create({
  base: 'light',
  brandTitle: 'My Storybook',
  brandUrl: 'https://example.com',
  brandImage: 'https://example.com/logo.png',
});

故障排查与常见问题解答

导入错误

如果遇到导入错误，例如 Module not found，检查文件路径是否正确，确保所有依赖项已正确安装。

Storybook 不启动

确保安装了所有必要的依赖项，并且正确配置了 main.js 和 preview.js 文件。检查是否有错误的配置或缺失的文件。

故障排查步骤

1. 检查 Storybook 的配置文件。
2. 确保所有依赖项已正确安装。
3. 重新启动 Storybook 服务器。
4. 查看 Storybook 的日志文件以获取更多信息。