设置 Storybook
现在你已经了解了什么是故事以及如何浏览它们,让我们演示一下如何使用你的一个组件。
¥Now that you’ve learned what stories are and how to browse them, let’s demo working on one of your components.
从你的项目中选择一个简单的组件,例如一个按钮,并编写一个 .stories.js
或 .stories.ts
文件来配合它。它可能看起来像这样:
¥Pick a simple component from your project, like a Button, and write a .stories.js
, or a .stories.ts
file to go along with it. It might look something like this:
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 以查看渲染的组件。如果现在看起来有点不寻常,也没关系。
¥Go to your Storybook to view the rendered component. It’s OK if it looks a bit unusual right now.
根据你的技术堆栈,你可能还需要进一步配置 Storybook 环境。
¥Depending on your technology stack, you also might need to configure the Storybook environment further.
渲染组件样式
¥Render component styles
Storybook 不会对你如何生成或加载 CSS 发表意见。它渲染你提供的任何 DOM 元素。但有时,开箱即用的东西看起来并不“正确”。
¥Storybook isn’t opinionated about how you generate or load CSS. It renders whatever DOM elements you provide. But sometimes, things won’t “look right” out of the box.
你可能必须为 Storybook 的渲染环境配置 CSS 工具。以下是社区中一些流行工具的设置指南。
¥You may have to configure your CSS tooling for Storybook’s rendering environment. Here are some setup guides for popular tools in the community.
没有看到你要查找的工具?查看 样式和 css 页面以了解更多详情。
¥Don't see the tool that you're looking for? Check out the styling and css page for more details.
为你的堆栈配置 Storybook
¥Configure Storybook for your stack
Storybook 带有一个宽容的 默认配置。它会尝试自定义自身以适合你的设置。但它并非万无一失。
¥Storybook comes with a permissive default configuration. It attempts to customize itself to fit your setup. But it’s not foolproof.
你的项目在组件可以单独渲染之前可能还有其他要求。这需要进一步自定义配置。你可能需要三类广泛的配置。
¥Your project may have additional requirements before components can be rendered in isolation. This warrants customizing configuration further. There are three broad categories of configuration you might need.
Build configuration like Webpack and Babel
如果你在运行 yarn storybook
命令时在 CLI 上看到错误,则可能需要更改 Storybook 的构建配置。以下是一些可以尝试的事情:
¥If you see errors on the CLI when you run the yarn storybook
command, you likely need to make changes to Storybook’s build configuration. Here are some things to try:
-
预设 将各种技术的通用配置打包到 Storybook 中。特别是,Create React App 和 Ant Design 存在预设。
¥Presets bundle common configurations for various technologies into Storybook. In particular, presets exist for Create React App and Ant Design.
-
为 Storybook 指定自定义 Babel 配置。如果可以,Storybook 会自动尝试使用你项目的配置。
¥Specify a custom Babel configuration for Storybook. Storybook automatically tries to use your project’s config if it can.
-
调整 Storybook 使用的 Webpack 配置。如果需要,请尝试在你自己的配置中进行修补。
¥Adjust the Webpack configuration that Storybook uses. Try patching in your own configuration if needed.
Runtime configuration
如果 Storybook 构建成功,但在浏览器中连接到它时立即看到错误,在这种情况下,很可能是你的某个输入文件未正确编译/转译以供浏览器解释。Storybook 支持常用浏览器,但你可能需要检查 Babel 和 Webpack 设置(见上文)以确保你的组件代码正常工作。
¥If Storybook builds but you see an error immediately when connecting to it in the browser, in that case, chances are one of your input files is not compiling/transpiling correctly to be interpreted by the browser. Storybook supports evergreen browsers, but you may need to check the Babel and Webpack settings (see above) to ensure your component code works correctly.
Component context
如果某个故事在渲染时出现问题,通常意味着你的组件需要特定的环境可供该组件使用。
¥If a particular story has a problem rendering, often it means your component expects a specific environment is available to the component.
一种常见的前端模式是组件假设它们在特定的“上下文”中渲染,父组件在渲染层次结构中处于更高的位置(例如,主题提供程序)。
¥A common frontend pattern is for components to assume that they render in a specific “context” with parent components higher up the rendering hierarchy (for instance, theme providers).
使用 decorators 将每个故事“封装”在必要的上下文提供程序中。.storybook/preview.js
文件允许你自定义组件在预览 iframe Canvas 中的渲染方式。在下面的示例中,了解如何使用 Styled Components ThemeProvider
、Vue 的 Fontawesome 或 Angular 主题提供程序组件封装 Storybook 中渲染的每个组件。
¥Use decorators to “wrap” every story in the necessary context providers. The .storybook/preview.js
file allows you to customize how components render in Canvas, the preview iframe. See how you can wrap every component rendered in Storybook with Styled Components ThemeProvider
, Vue's Fontawesome, or with an Angular theme provider component in the example below.
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;
加载资源和资源
¥Load assets and resources
我们建议使用 Storybook 静态提供组件中请求的外部资源和资源。它确保资源始终可用于你的故事。阅读我们的 documentation,了解如何使用 Storybook 托管静态文件。
¥We recommend serving external resources and assets requested in your components statically with Storybook. It ensures that assets are always available to your stories. Read our documentation to learn how to host static files with Storybook.