Docs
Storybook Docs

浏览故事

上一章，我们了解到故事与离散组件状态相对应。本章演示了如何使用 Storybook 作为构建组件的研讨会。

¥Last chapter, we learned that stories correspond with discrete component states. This chapter demonstrates how to use Storybook as a workshop for building components.

侧边栏和画布

¥Sidebar and Canvas

*.stories.js 文件定义组件的所有故事。每个故事都有相应的侧边栏项目。当你单击一个故事时，它会在 Canvas 中渲染一个独立的预览 iframe。

¥A *.stories.js file defines all the stories for a component. Each story has a corresponding sidebar item. When you click on a story, it renders in the Canvas an isolated preview iframe.

通过单击侧边栏中的故事来在故事之间导航。尝试使用侧边栏搜索按名称查找故事。

¥Navigate between stories by clicking on them in the sidebar. Try the sidebar search to find a story by name.

或者使用键盘快捷键。单击 Storybook 的菜单以查看可用的快捷方式列表。

¥Or use keyboard shortcuts. Click on the Storybook's menu to see the list of shortcuts available.

Storybook keyboard shortcuts examples

工具栏

¥Toolbar

Storybook 内置了省时工具。工具栏包含允许你调整故事在画布中渲染方式的工具：

¥Storybook ships with time-saving tools built-in. The toolbar contains tools that allow you to adjust how the story renders in the Canvas:

  • 🔍 缩放功能可以直观地缩放组件，以便你可以检查详细信息。

    ¥🔍 Zooming visually scales the component so you can check the details.

  • 🖼 Background 会更改组件后面的渲染背景，以便你可以验证组件在不同的视觉环境中的渲染方式。

    ¥🖼 Background changes the rendered background behind your component so you can verify how your component renders in different visual contexts.

  • 📐 Grid 在网格布局之上渲染你的组件，以便你可以验证你的组件是否正确对齐。

    ¥📐 Grid renders your component on top of a grid layout so you can verify if your component is aligned correctly.

  • 📏 测量切换测量覆盖以帮助你检查组件的尺寸。

    ¥📏 Measure toggles a measurement overlay to help you inspect the dimensions of components.

  • 🎚️ 轮廓显示组件的边界框，以便你可以验证组件是否定位正确。

    ¥🎚️ Outline displays the component's bounding box so you can verify if your component is positioned correctly.

  • 📱 视口以各种尺寸和方向渲染组件。它是检查组件响应能力的理想选择。

    ¥📱 Viewport renders the component in a variety of dimensions and orientations. It’s ideal for checking the responsiveness of components.

“文档” 页面显示组件的自动生成文档（从源代码推断）。在与你的团队共享可重用组件（例如在应用中）时，使用文档很有用。

¥The “Docs” page displays auto-generated documentation for components (inferred from the source code). Usage documentation is helpful when sharing reusable components with your team, for example, in an application.

Storybook keyboard shortcuts examples

工具栏是可自定义的。你可以使用 globals 快速切换主题和语言。或者从社区安装 Storybook 工具栏 addons 以启用高级工作流程。

¥The toolbar is customizable. You can use globals to quickly toggle themes and languages. Or install Storybook toolbar addons from the community to enable advanced workflows.

插件

¥Addons

插件是扩展 Storybook 核心功能的插件。你可以在插件面板中找到它们，这是 Storybook UI 中画布下方的保留位置。每个选项卡都显示插件为所选故事生成的元数据、日志或静态分析。

¥Addons are plugins that extend Storybook's core functionality. You can find them in the addons panel, a reserved place in the Storybook UI below the Canvas. Each tab shows the generated metadata, logs, or static analysis for the selected story by the addon.

Storybook addon examples

  • 控件允许你动态地与组件的参数（输入）交互。尝试使用组件的替代配置来发现边缘情况。

    ¥Controls allows you to interact with a component’s args (inputs) dynamically. Experiment with alternate configurations of the component to discover edge cases.

  • 操作可帮助你验证交互是否通过回调产生正确的输出。例如，如果你查看 Header 组件的“已登录”故事，我们可以验证单击“注销”按钮是否会触发 onLogout 回调，该回调由使用 Header 的组件提供。

    ¥Actions help you verify interactions produce the correct outputs via callbacks. For instance, if you view the “Logged In” story of the Header component, we can verify that clicking the “Log out” button triggers the onLogout callback, which would be provided by the component that made use of the Header.

  • 交互提供了一个有用的用户界面，用于使用 play 功能调试 组件测试。

    ¥Interactions provides a helpful user interface for debugging component tests with the play function.

  • 通过直接在 Storybook 中提供即时反馈，Visual Tests 可让你查明本地开发环境中的 UI 错误。

    ¥Visual Tests lets you pinpoint UI bugs in your local development environment by providing instant feedback directly in Storybook.

Storybook 可扩展。我们丰富的插件生态系统可帮助你测试、记录和优化你的故事。你还可以创建一个插件来满足你的工作流程要求。在 插件部分 中阅读更多内容。

¥Storybook is extensible. Our rich ecosystem of addons helps you test, document, and optimize your stories. You can also create an addon to satisfy your workflow requirements. Read more in the addons section.

在下一章中，我们将在 Storybook 中渲染你的组件，以便你可以使用它来增强组件开发。

¥In the next chapter, we'll get your components rendering in Storybook so you can use it to supercharge component development.

使用故事来构建 UI

¥Use stories to build UIs

在构建应用时，最大的挑战之一是确定代码库中是否已经存在某个 UI，以及如何将其用于你正在构建的新功能。

¥When building apps, one of the biggest challenges is to figure out if a piece of UI already exists in your codebase and how to use it for the new feature you're building.

Storybook 对你的所有组件及其用例进行分类。因此，你可以快速浏览它以找到你要查找的内容。

¥Storybook catalogues all your components and their use cases. Therefore, you can quickly browse it to find what you're looking for.

以下是工作流程的样子：

¥Here's what the workflow looks like:

  • 🗃 使用侧边栏查找合适的组件

    ¥🗃 Use the sidebar to find a suitable component

  • 👀 查看其故事以选择适合你需求的变体

    ¥👀 Review its stories to pick a variant that suits your needs

  • 📝 将故事定义复制/粘贴到你的应用代码中并将其连接到数据

    ¥📝 Copy/paste the story definition into your app code and wire it up to data

你可以从故事文件中访问故事定义，也可以使用 Storysource 插件 或 文档插件 在你发布的 Storybook 中提供它。

¥You can access the story definition from the stories file or make it available in your published Storybook using the Storysource addon or the Docs addon.

Docblock source