介绍
Storybook是一个用户界面 (UI) 库,可用于记录组件。
注意:本文基于Storybook 简介,其中介绍了如何使用它来组织和构建 JavaScript 组件。
在本文中,您将使用 React 和 Storybook 构建一个交互式 UI 组件。
在本教程结束时,您将把故事书部署为一个独立的应用程序,作为风格指南。
先决条件
要完成本教程,您需要:
- Node.js 安装在本地,您可以按照如何安装 Node.js 和创建本地开发环境来完成。
本教程已通过 Node v14.4.0、npm
v6.14.5、react
v16.13.1 和@storybook/react
v5.3.19 验证。
步骤 1 — 设置项目
首先,我们需要创建一个新的 React 项目,为此,我们将使用create-react-app
这是一个很好的工具来搭建 React 应用程序。
- npx create-react-app storybook-app
然后导航到新创建的项目目录:
cd storybook-app
下一步是将storybook
包安装到我们的项目中:
- npx -p @storybook/cli sb init
该命令可以自动从package.json
文件中检测我们正在使用的框架并安装该框架的 Storybook 版本。
运行这两个命令后,我们可以@storybook/react
通过打开package.json
文件来验证是否安装了软件包来确认我们已经安装了依赖项,然后我们可以运行应用程序以及运行 Storybook。
- npm start
- npm run storybook
运行这两个命令后,我们将在不同的端口上运行 React 应用程序和 Storybook 应用程序。
手动添加配置
如果我们按照上面列出的步骤进行了操作,那么它已经为我们进行了预配置。如果我们@storybook/react
在一个已经存在的 React 项目中安装了这个包,那么我们需要按照这些步骤来设置 Storybook。
我们首先要.storybook
在 React 项目的根目录中创建一个文件夹,然后在名为的文件夹中创建一个文件config.js
并添加以下代码行:
import { configure } from '@storybook/react';
function loadStories() {
require('../src/stories');
}
configure(loadStories, module);
上面的代码块是 Storybook 的配置,它告诉 Storybook 在src/stories
目录中查找故事。如果我们尚未设置该文件夹,我们将创建该文件夹。在src
文件夹中创建一个名为stories
. 这是我们将为其创建故事的所有组件最终所在的位置。
注意: Storybook 5.3.0 及更高版本介绍了main.js
它处理config.js
过去所做的事情。这些更改记录在官方迁移文档中。
如果您使用的是 Storybook 5.3.0 或更高版本,则不需要config.js
文件,可以忽略此步骤。
在官方文件还提出了在何处放置不同的方法stories
。
至此,Storybook 就设置好了,可以使用了。
第 2 步 – 向 React 应用程序添加故事
现在我们完成了设置,我们可以使用 Storybook 创建组件。
在本教程中,我们将创建一个<Button>
组件,对于该组件,我们将在stories
文件夹中为它们记录故事。继续并使用以下代码行在目录中创建一个<Button>
组件component
:
import React from 'react';
import './Button.css';
const Button = props => (
<button onClick={props.onClick} style={props.style}>
{props.label && <span>{props.label}</span>}
</button>
);
export default Button;
并为组件添加样式:
button {
padding: 20px;
width: 20em;
margin: 10px;
color: white;
font-size: 19px;
cursor: pointer;
border: 2px solid #fecd43;
background: #fecd43;
}
现在,我们可以为<Button>
创建的组件添加一个故事。在stories
目录中创建一个文件并调用它buttonStories.js
,然后将以下代码行添加到文件中:
import React from 'react';
import { storiesOf } from '@storybook/react';
import Button from '../components/Button';
storiesOf('Button', module)
.add('with primary', () => <Button label="Primary Button" />)
.add('with outline', () => <Button
label="Ouline Button"
style={{ background: 'transparent', border: '3px solid #fecd43' }}
/>)
.add('with rounder corners', () => <Button
label="Rounded Button"
style={{ borderRadius: '15px' }}
/>)
.add('disabled', () => <Button disabled
label="Disabled Button"
style={{ background: 'gray' , border: 'gray', cursor: 'not-allowed' }}
/>);
接下来,创建一个index.js
文件。导入buttonStories.js
文件:
import './buttonStories';
这将作为包含所有故事的基本文件,我们可以将它们全部导入到此文件中。
注意: Storybook 5.3.0 及更高版本采用以下文件名模式:*.stories.js
. 为了符合这个约定,buttonStories.js
应该重命名为button.stories.js
.
您可能还会遇到1-Button.stories.js
使用相同Button
标题的演示故事的生成文件。为避免混淆,您可以将该文件的内容注释掉。
然后对于stories
目录下创建的每个新文件,我们将它们导入到这个文件中。
第 3 步 – 集成插件
带有 Storybook 的插件有助于实现额外的功能,使其更有用和更具交互性。可在官方网站上找到适用于 Storybook 的所有插件的完整列表。
在本文中,我们将把Action
插件添加到创建的故事中。Actions Addon 可用于显示 Storybook 中事件处理程序接收到的数据。
手动添加插件
如果默认情况下尚未完成,我们可以设置插件,您需要按照以下步骤操作。
注意:如果您使用的是 Storybook 5.3.0 或更高版本,就本教程而言,您将不需要addons.js
文件并且可以忽略此步骤。
使用以下命令安装插件包:
- npm install --save-dev @storybook/addon-actions
然后,将以下内容添加到.storybook/addons.js
:
import '@storybook/addon-actions/register';
现在您的 Storybook 支持插件。
第 4 步 – 使用插件操作
为了使我们的 Button 故事与 Storybook 交互,我们可以将以下代码添加到buttonStories.js
:
import React from 'react';
import { storiesOf } from '@storybook/react';
import { action } from '@storybook/addon-actions';
import Button from '../components/Button';
storiesOf('Button', module)
.add('with primary', () => <Button
onClick={action('click')}
label="Primary Button"
/>)
.add('with outline', () => <Button
label="Ouline Button"
onClick={action('click')}
style={{ background: 'transparent', border: '3px solid #fecd43' }}
/>)
.add('with rounder corners', () => <Button
label="Rounded Button"
onClick={action('click')}
style={{ borderRadius: '15px' }}
/>)
.add('disabled', () => <Button disabled
label="Disabled Button"
onClick={action('click')}
style={{ background: 'gray' , border: 'gray', cursor: 'not-allowed' }}
/>);
然后运行 Storybook:
在下面的选项卡上,您会看到Actions tab
每当我们与按钮交互时记录操作的位置。
第 5 步 – 自定义主题
使用 Storybook,我们可以自定义所使用的默认主题,并且 Storybook 捆绑了一个默认的浅色主题。现在,让我们探索如何将其定制为不同的东西。黑暗主题可能或完全不同的东西。首先,我们需要config.js
通过添加以下代码行来修改我们在文件中设置的配置:
import { addParameters } from '@storybook/react';
import { themes } from '@storybook/theming';
addParameters({
options: {
theme: themes.dark
}
});
注意: Storybook 5.3.0 及更高版本引入了manager.js
. 使用这个新约定进行主题化的步骤在官方主题化文档中进行了讨论。
配置了深色主题后,我们可以观察到整个 Storybook 主题都切换到了深色主题。在任何时候,这都可以根据我们的喜好切换回浅色或深色主题。
如果我们想要一个完全不同的主题,我们也可以定义一个现成的动态主题。第一步是为我们的主题创建一个文件,在.storybook
文件夹中创建一个名为yourTheme.js
. 下一步是使用create()
from的函数生成一个新主题storybook/theming
。
这是一个pink.js
主题的示例:
import { create } from '@storybook/theming';
export default create ({
base: 'light',
colorPrimary: 'hotpink',
colorSecondary: 'deepskyblue',
// UI
appBg: 'rgb(234, 0, 133)',
appContentBg: 'white',
appBorderColor: 'white',
appBorderRadius: 4,
// Typography
fontBase: '"Open Sans", sans-serif',
fontCode: 'monospace',
// Text colors
textColor: 'rgb(255, 250, 250)',
textInverseColor: 'white',
// Toolbar default and active colors
barTextColor: 'white',
barSelectedColor: 'white',
barBg: 'rgb(246, 153, 190)',
// Form colors
inputBg: 'white',
inputBorder: 'silver',
inputTextColor: 'black',
inputBorderRadius: 4,
brandTitle: 'Pink Storybook'
});
然后,我们可以继续导入pink.js
我们的 Storybook 配置文件。
import pink from './pink';
addParameters({
options: {
theme: pink
}
});
与之前的图像相比,这为我们提供了一个完全不同的主题。
第 6 步 — 部署 Storybook
Storybook 附带的一项功能是,我们可以将 Storybook 部署为静态站点,我们可以将其部署到我们选择的任何托管选项。要配置它,我们需要添加一个build-storybook
脚本到我们的package.json
:
{
"scripts": {
"build-storybook": "build-storybook -c .storybook -o .out"
}
}
该脚本将做的是将我们的故事书目录构建到一个静态 Web 应用程序中,并将其输出到一个.out
目录中。我们可以运行这个脚本并.out
在构建完成后部署目录的内容。继续并运行命令:
- npm run build-storybook
构建完成后,我们现在可以使用我们选择的任何主机部署目录的内容。
要在本地测试它是否有效,我们可以运行以下命令:
- npx http-server .out
:
注意:您package.json
可以表征一个build-storybook
脚本类似于:build-storybook -s public
。这不是指定的.out
目录,而是将静态站点文件输出到storybook-static
目录。
这将作为静态站点提供文件夹的内容。
结论
在本文中,我们学习了如何使用 Storybook 和 React 构建交互式组件。现在我们已经探索了 Storybook 的可能性,并且还有一个关于如何将 Storybook 作为组件库集成到我们的 React 项目中的指南。使用 Storybook 进行开发可为团队中的开发人员和设计人员提供单一的事实来源,并且可以与其他前端框架集成。
这篇文章只概述了它是如何与 React 一起使用的。如果您正在寻找有关其他框架的指南,请随时查看Storybook 的官方文档。
您还可以在 GitHub 上找到本文的代码。