Firefox 的 Storybook¶
Storybook 是一款交互式工具，可以为 UI 组件创建游乐场。我们使用 Storybook 来记录我们的设计系统、可复用组件以及您可能想要使用虚拟数据测试的任何特定组件。查看我们的 Storybook 实例！
背景¶
Storybook 列出了可以复用的组件，并有助于记录我们拥有的常用元素。它还可以列出特定于实现的组件，但应将其添加到“特定领域 UI 组件”部分。
对 Storybook 直接引用的文件（基本上是非 chrome:// 路径）的更改应该会自动反映在打开的浏览器中。如果您对 chrome:// 引用的文件进行了更改，则需要进行硬刷新 (Cmd+Shift+R/Ctrl+Shift+R) 以注意到更改。如果您使用的是 Windows，则可能需要 ./mach build faster 以使 chrome:// URL 显示最新版本。
运行 Storybook¶
安装 npm 依赖项并运行 storybook npm 脚本应该足以使 Storybook 运行。这可以通过 ./mach storybook 命令或与您碰巧兼容的个人 npm/node 来完成。
使用 mach 命令运行¶
这是在本地安装依赖项并运行 Storybook 的推荐方法。
要安装依赖项，启动 Storybook 服务器并在 Firefox 的本地构建中启动 Storybook 网站，只需运行
# This uses npm ci under the hood to install the package-lock.json exactly.
./mach storybook
此单个命令将首先安装任何缺少的依赖项，然后启动本地 Storybook 服务器。它还将启动您的本地浏览器并将其指向 https://127.0.0.1:5703，同时启用某些首选项以确保组件按预期显示（特别是 svg.context-properties.content.enabled 和 layout.css.light-dark.enabled）。
有必要使用您的本地构建在 Storybook 中进行测试，因为 chrome:// URL 当前是从正在运行的浏览器中提取的，因此例如对 common-shared.css 的任何更改都将来自您的构建。
Storybook 服务器将继续运行，并将监视组件文件更改。
替代 mach 命令¶
虽然运行 ./mach storybook 是在本地与 Storybook 交互最方便的方式，但也可以运行单独的命令来启动 Storybook 服务器并在本地构建中启用必要的首选项。
如果您只想启动 Storybook 服务器 - 例如在您已经运行本地构建的情况下 - 您可以将 --no-open 标志传递给 ./mach storybook
# Start the storybook server without launching a local Firefox build.
./mach storybook --no-open
如果您只想启动启用了所需首选项的 Firefox 本地构建，可以使用 launch 子命令
# In another terminal:
./mach storybook launch
这将运行您的本地浏览器并将其指向 https://127.0.0.1:5703。
或者，您可以简单地导航到 https://127.0.0.1:5703/ 或运行
# In another terminal:
./mach run https://127.0.0.1:5703/
但是，使用此选项，某些首选项将不会启用，因此 Storybook 中显示的内容可能不会完全反映组件在 Firefox 中使用时的外观。
个人 npm¶
您可以使用您自己的 npm 来安装和运行 Storybook。兼容性由您自己解决。
cd browser/components/storybook
npm ci # Install the package-lock.json exactly so lockfileVersion won't change.
npm run storybook
更新 Storybook 依赖项¶
有时您可能需要更新或添加 Storybook 的 npm 依赖项。这可以使用与 mach 打包的 npm 版本来完成
# Install a dev dependency from within the storybook directory.
cd browser/components/storybook && ../../../mach npm i -D your-package
添加新的故事¶
Storybook 当前配置为在 toolkit/content/widgets 和 browser/components/storybook/stories 中搜索故事文件（任何扩展名为 .stories.(js|mjs|md) 的文件）。
toolkit/content/widgets 中的故事用于记录设计系统组件，也称为 UI 组件。只要您正确使用了 ./mach addwidget，就不需要进行其他设置即可在 Storybook 中查看您新创建的故事。
browser/components/storybook/stories 中的故事用于非设计系统组件，也称为特定领域 UI 组件。对非设计系统元素使用 Storybook 的最简单方法是使用 ./mach addstory new-component "Your Project"。您还可以使用 ./mach addstory new-component "Your Project" --path browser/components/new-component.mjs，其中 --path 是您新组件源代码的路径。请参阅凭据管理/时间轴小部件以了解示例。
如果您想将您的故事与它所记录的代码放在一起，则需要添加到 .storybook/main.js 配置文件 中的 stories 数组中，以便 Storybook 知道在哪里查找您的文件。
Storybook 文档站点有一个关于编写新故事的 良好概述。为了方便起见，您可以使用 Lit 库 来定义故事的模板代码，但这并不是必需的。
UI 组件与特定领域 UI 组件¶
属于 我们的设计系统 并且旨在在 Mozilla 产品套件中使用的组件位于 Storybook 中的“UI 组件”类别下，以及 Firefox 中的 toolkit/content/widgets/ 下。这些全局组件在代码中以其名称中的 moz- 前缀表示。例如，名称 moz-support-link 告诉我们此组件符合设计系统，可以在 Firefox 中的任何地方使用。
Storybook 还可以用于帮助记录和原型设计特定于代码库一部分且不打算用于更全局使用的组件。这些类型组件的故事位于“特定领域 UI 组件”类别下，而代码可以位于 mozilla-central 中的任何适当文件夹中。请参阅凭据管理文件夹以了解特定领域文件夹的示例，以及 请参阅 login-timeline.stories.mjs 以了解如何在 Storybook 中创建特定领域文件夹。要将非团队特定组件添加到“特定领域 UI 组件”部分，请参阅 migration-wizard.stories.mjs 文件。
创建和记录特定领域 UI 组件可以让其他团队了解并从现有的 UI 模式中获得灵感。使用这些组件，**不能保证该元素对您的领域有效。**如果您需要在特定领域之外使用特定领域组件，则可能值得讨论如何将此特定领域组件转换为全局 UI 组件。