安装 Storybook
既然您已经了解了什么是 stories 以及如何浏览它们,现在让我们演示如何处理您的一个组件。
从您的项目中选择一个简单的组件,例如 Button,并编写一个与之配套的 .stories.js
、.stories.ts
或 .stories.svelte
文件。它可能看起来像这样
import type { Meta, StoryObj } from '@storybook/react';
import { YourComponent } from './YourComponent';
//👇 This default export determines where your story goes in the story list
const meta: Meta<typeof YourComponent> = {
component: YourComponent,
};
export default meta;
type Story = StoryObj<typeof YourComponent>;
export const FirstStory: Story = {
args: {
//👇 The args you need here will depend on your component
},
};
转到您的 Storybook 以查看渲染的组件。如果现在看起来有点不寻常,也没关系。
根据您的技术栈,您可能还需要进一步配置 Storybook 环境。
渲染组件样式
Storybook 对于您如何生成或加载 CSS 没有特定意见。它会渲染您提供的任何 DOM 元素。但有时,事情可能不会“开箱即用”地“看起来正确”。
您可能需要为 Storybook 的渲染环境配置您的 CSS 工具。这里有一些社区常用工具的设置指南。
没有找到您要找的工具?请查看样式和 CSS 页面以获取更多详细信息。
为您的技术栈配置 Storybook
Storybook 附带一个宽松的默认配置。它尝试自定义自身以适应您的设置。但它并非万无一失。
您的项目在组件可以隔离渲染之前可能还有其他要求。这证明需要进一步自定义配置。您可能需要三种广泛的配置类别。
构建配置,例如 Webpack 和 Babel
如果您在运行 yarn storybook
命令时在 CLI 上看到错误,您可能需要更改 Storybook 的构建配置。以下是一些可以尝试的方法
- Presets 将各种技术的常用配置捆绑到 Storybook 中。特别是,Create React App 和 Ant Design 存在预设。
- 为 Storybook 指定自定义 Babel 配置。如果可以,Storybook 会自动尝试使用您项目的配置。
- 调整 Storybook 使用的 Webpack 配置。如果需要,尝试修补您自己的配置。
运行时配置
如果 Storybook 构建成功,但在浏览器中连接到它时立即看到错误,在这种情况下,很可能是您的一个输入文件未正确编译/转译以供浏览器解释。Storybook 支持常青浏览器,但您可能需要检查 Babel 和 Webpack 设置(见上文)以确保您的组件代码正常工作。
组件上下文
如果某个特定的 story 在渲染时出现问题,通常意味着您的组件期望组件可以使用特定的环境。
一种常见的前端模式是组件假定它们在特定的“上下文”中渲染,父组件在渲染层次结构中更高(例如,主题提供程序)。
使用装饰器将每个 story “包裹”在必要的上下文提供程序中。`.storybook/preview.js|ts` 文件允许您自定义组件在 Canvas(预览 iframe)中的渲染方式。请参阅如何在下面的示例中,使用 Styled Components ThemeProvider、Vue's Fontawesome 或 Angular 主题提供程序组件来包裹 Storybook 中渲染的每个组件。
import React from 'react';
import { Preview } from '@storybook/react';
import { ThemeProvider } from 'styled-components';
const preview: Preview = {
decorators: [
(Story) => (
<ThemeProvider theme="default">
{/* 👇 Decorators in Storybook also accept a function. Replace <Story/> with Story() to enable it */}
<Story />
</ThemeProvider>
),
],
};
export default preview;
加载资源和资产
我们建议使用 Storybook 静态地提供组件中请求的外部资源和资产。这确保了资产始终可用于您的 stories。阅读我们的文档以了解如何使用 Storybook 托管静态文件。