常见问题
以下是一些常见问题的解答。如果您有疑问,可以在我们的 GitHub 讨论区 提问。
错误:未找到 angular.json 文件
Storybook 可以为单项目和多项目 Angular 工作区进行设置。要为项目设置 Storybook,请在 安装命令 所在的 angular.json
文件根目录运行。在初始化期间,将创建 .storybook
文件夹,并将编辑 angular.json
文件以添加所选项目的 Storybook 配置。重要的是在根级别运行命令,以确保 Storybook 正确检测到所有项目。
如何选择退出 Angular Ivy?
如果您在使用 Angular Ivy 时遇到问题,可以在您的 main.js|ts
中禁用它
export default {
stories: [
/* ... */
],
addons: [
/* ... */
],
framework: {
name: '@storybook/angular',
options: {
enableIvy: false,
},
},
};
如何选择退出 Angular ngcc?
如果您 postinstall 了 ngcc,您可以禁用它
export default {
stories: [
/* ... */
],
addons: [
/* ... */
],
framework: {
name: '@storybook/angular',
options: {
enableNgcc: false,
},
},
};
请在我们的 GitHub Issue Tracker 中报告任何与 Ivy 相关的问题,因为对 View Engine 的支持将在 Angular 的未来版本中删除。
如何使用 Create React App 运行覆盖率测试并排除 stories?
Create React App 不允许在您的 package.json
中提供 Jest 的选项,但是您可以使用命令行参数运行 jest
npm test -- --coverage --collectCoverageFrom='["src/**/*.{js,jsx}","!src/**/stories/*"]'
如果您正在使用 Yarn
作为包管理器,您需要相应地调整命令。
如何设置 Storybook 以与 Next.js 共享 Webpack 配置?
您通常可以通过将 Webpack 规则放在一个文件中来重用它们,该文件可以从您的 next.config.js
和 .storybook/main.js|ts
文件中 require()
引入。例如
export default {
webpackFinal: async (baseConfig) => {
const nextConfig = require('/path/to/next.config.js');
// merge whatever from nextConfig into the webpack config storybook will use
return { ...baseConfig, ...nextConfig };
},
};
如何在特殊环境中修复模块解析?
如果您正在使用 Yarn Plug-n-Play 或者您的项目设置在单仓库环境中,则在运行 Storybook 时可能会遇到类似于此的模块解析问题
WARN Failed to load preset: "@storybook/react-webpack5/preset"
Required package: @storybook/react-webpack5 (via "@storybook/react-webpack5/preset")
要解决此问题,您可以将包名称包装在您的 Storybook 配置文件(即 .storybook/main.js|ts
)中,如下所示
// Replace your-framework with the framework you are using (e.g., react-webpack5, vue3-vite)
import type { StorybookConfig } from '@storybook/your-framework';
import path from 'path';
const getAbsolutePath = (packageName: string): any =>
path.dirname(require.resolve(path.join(packageName, 'package.json')));
const config: StorybookConfig = {
framework: {
// Replace your-framework with the same one you've imported above.
name: getAbsolutePath('@storybook/your-framework'),
options: {},
},
stories: ['../src/**/*.mdx', '../src/**/*.stories.@(js|jsx|mjs|ts|tsx)'],
addons: [
//👇 Use getAbsolutePath when referencing Storybook's addons and frameworks
getAbsolutePath('@storybook/addon-essentials'),
],
};
export default config;
如何使用 Storybook 设置新的 React Context Root API?
如果您安装的 React 版本等于或高于 18.0.0,则会自动使用新的 React Root API,并且可以使用最新的 React 并发特性。
您可以通过在您的 .storybook/main.js|ts
文件中设置以下属性来选择退出新的 React Root API
export default {
framework: {
name: '@storybook/react-webpack5',
options: {
legacyRootApi: true,
},
},
};
为什么没有 addons 通道?
一个常见的错误是插件尝试访问“通道”,但通道未设置。这可能发生在几种不同的情况下
-
您正在尝试在非浏览器环境(如 Jest)中访问插件通道(例如,通过调用
setOptions
)。您可能需要添加一个通道模拟import { addons, mockChannel } from '@storybook/preview-api'; addons.setChannel(mockChannel());
-
在 React Native 中,这是一个记录在 #1192 中的特殊情况
为什么 Controls 在 Canvas 面板中不可见,但在 Docs 中可见?
如果您正在手动添加 Storybook 的依赖项,请确保在您的项目中包含 @storybook/addon-controls
依赖项,并在您的 .storybook/main.js|ts
中引用它,如下所示
export default {
addons: ['@storybook/addon-controls'],
};
为什么插件在组合的 Storybook 中不起作用?
组合是我们随版本 6.0 发布的新功能,它仍然存在一些限制。
目前,您在组合的 Storybook 中使用的插件将无法工作。
我们正在努力克服此限制,很快您就可以像使用非组合的 Storybook 一样使用它们。
我可以拥有一个没有本地 stories 的 Storybook 吗?
除非您的项目中至少定义了一个本地 story(或文档页面),否则 Storybook 无法工作。在此上下文中,本地是指在您的项目的 .storybook/main.js
配置中引用的 .stories.*
或 .mdx
文件。
如果您处于 Storybook 组合 场景中,您有多个 Storybook,并且想要拥有一个额外的 Storybook,它本身没有 stories,而是作为项目中所有其他 Storybook 的“粘合剂”,用于演示/文档目的,您可以执行以下步骤
引入一个单独的 .mdx
文档页面(需要 addon-essentials 或 addon-docs),作为介绍页面,如下所示
# Welcome
Some description here
然后在您的 Storybook 配置文件中引用它
const config = {
// define at least one local story/page here
stories: ['../Introduction.mdx'],
// define composed Storybooks here
refs: {
firstProject: { title: 'First', url: 'some-url' },
secondProject: { title: 'Second', url: 'other-url' },
},
// ...
};
export default config;
哪些社区插件与最新版本的 Storybook 兼容?
从 Storybook 版本 6.0 开始,我们引入了一些旨在简化您的开发工作流程的强大功能。
因此,我们想指出,如果您计划使用我们出色的社区创建的插件,您需要考虑到其中一些插件可能正在使用过时的 Storybook 版本。
我们正在积极努力提供更好的方法来解决这种情况,但与此同时,我们希望您谨慎一点,以免遇到意外问题。请在以下 GitHub issue 中留下评论,以便我们收集信息并扩展当前需要更新以与最新版本的 Storybook 一起使用的插件列表。
是否可以浏览过去版本的 Storybook 文档?
随着版本 6.0 的发布,我们也更新了我们的文档。但这并不意味着旧文档被删除了。我们保留了它,以帮助您进行 Storybook 迁移过程。结合我们的 迁移指南 使用下表中的内容。
我们仅涵盖版本 5.3 和 5.0,因为它们是 Storybook 的重要里程碑。如果您想稍微回到过去,则必须在 monorepo 中查看特定版本。
部分 | 页面 | 当前位置 | 版本 5.3 位置 | 版本 5.0 位置 |
---|---|---|---|---|
不适用 | 为什么选择 Storybook | 请参阅当前文档 | 不存在的功能或未记录 | 不存在的功能或未记录 |
开始使用 | 安装 | 请参阅当前文档 | 请参阅版本化文档 | 请参阅版本化文档 |
什么是 story | 请参阅当前文档 | 请参阅您的框架的版本化文档 | 请参阅您的框架的版本化文档 | |
浏览 Stories | 请参阅当前文档 | 请参阅您的框架的版本化文档 | 请参阅您的框架的版本化文档 | |
设置 | 请参阅当前文档 | 请参阅您的框架的版本化文档 | 请参阅您的框架的版本化文档 | |
编写 stories | 简介 | 请参阅当前文档 | 请参阅版本化文档 | 请参阅版本化文档 |
Parameters | 请参阅当前文档 | 请参阅版本化文档 | 不存在的功能或未记录 | |
Decorators | 请参阅当前文档 | 请参阅版本化文档 | 请参阅版本化文档 | |
命名组件和层级结构 | 请参阅当前文档 | 请参阅版本化文档 | 请参阅版本化文档 | |
构建页面和屏幕 | 请参阅当前文档 | 不存在的功能或未记录 | 不存在的功能或未记录 | |
多个组件的 Stories | 请参阅当前文档 | 不存在的功能或未记录 | 不存在的功能或未记录 | |
编写文档 | Autodocs | 请参阅当前文档 | 请参阅版本化插件文档 | 不存在的功能或未记录 |
MDX | 请参阅当前文档 | 请参阅版本化插件文档 | 不存在的功能或未记录 | |
Doc Blocks | 请参阅当前文档 | 不存在的功能或未记录 | 不存在的功能或未记录 | |
预览和构建文档 | 请参阅当前文档 | 不存在的功能或未记录 | 不存在的功能或未记录 | |
测试 | 可视化测试 | 请参阅当前文档 | 请参阅版本化文档 | 请参阅版本化文档 |
可访问性测试 | 请参阅当前文档 | 不存在的功能或未记录 | 不存在的功能或未记录 | |
组件测试 | 请参阅当前文档 | 请参阅版本化文档 | 请参阅版本化文档 | |
快照测试 | 请参阅当前文档 | 请参阅版本化文档 | 请参阅版本化文档 | |
在测试中导入 stories/单元测试 | 请参阅当前文档 | 请参阅版本化文档 | 请参阅版本化文档 | |
在测试中导入 stories/端到端测试 | 请参阅当前文档 | 请参阅版本化文档 | 请参阅版本化文档 | |
分享 | 发布 Storybook | 请参阅当前文档 | 请参阅版本化文档 | 请参阅版本化文档 |
嵌入 | 请参阅当前文档 | 不存在的功能或未记录 | 不存在的功能或未记录 | |
组合 | 请参阅当前文档 | 不存在的功能或未记录 | 不存在的功能或未记录 | |
包组合 | 请参阅当前文档 | 不存在的功能或未记录 | 不存在的功能或未记录 | |
必备插件 | Controls | 请参阅当前文档 | Controls 是版本 6.0 特有的,请参阅 Knobs 版本化文档 | Controls 是版本 6.0 特有的,请参阅 Knobs 版本化文档 |
Actions | 请参阅当前文档 | 请参阅插件版本化文档 | 请参阅插件版本化文档 | |
Viewport | 请参阅当前文档 | 请参阅插件版本化文档 | 请参阅插件版本化文档 | |
Backgrounds | 请参阅当前文档 | 请参阅插件版本化文档 | 请参阅插件版本化文档 | |
工具栏和全局变量 | 请参阅当前文档 | 请参阅版本化文档 | 不存在的功能或未记录 | |
配置 | 概述 | 请参阅当前文档 | 请参阅版本化文档 | 请参阅版本化文档 |
集成/框架 | 请参阅当前文档 | 不存在的功能或未记录 | 不存在的功能或未记录 | |
集成/框架对框架的支持 | 请参阅当前文档 | 不存在的功能或未记录 | 不存在的功能或未记录 | |
集成/编译器 | 请参阅当前文档 | 请参阅版本化文档 此处 | 请参阅版本化文档 此处 | |
集成/Typescript | 请参阅当前文档 | 请参阅版本化文档 | 请参阅版本化文档 | |
集成/样式和 CSS | 请参阅当前文档 | 请参阅版本化文档 | 请参阅版本化文档 | |
集成/图像和资源 | 请参阅当前文档 | 请参阅版本化文档 | 请参阅版本化文档 | |
Story 渲染 | 请参阅当前文档 | 请参阅版本化文档 此处 和 此处 | 请参阅版本化文档 此处 | |
Story 布局 | 请参阅当前文档 | 不存在的功能或未记录 | 不存在的功能或未记录 | |
用户界面/功能和行为 | 请参阅当前文档 | 请参阅版本化文档 | 请参阅版本化文档 | |
用户界面/主题 | 请参阅当前文档 | 请参阅版本化文档 | 请参阅版本化文档 | |
用户界面/侧边栏 & URL | 请参阅当前文档 | 请参阅版本化文档 | 请参阅版本化文档 | |
环境变量 | 请参阅当前文档 | 请参阅版本化文档 | 请参阅版本化文档 | |
构建器 | 简介 | 请参阅当前文档 | 不存在的功能或未记录 | 不存在的功能或未记录 |
Vite | 请参阅当前文档 | 不存在的功能或未记录 | 不存在的功能或未记录 | |
Webpack | 请参阅当前文档 | 请参阅版本化文档 | 请参阅版本化文档 | |
构建器 API | 请参阅当前文档 | 不存在的功能或未记录 | 不存在的功能或未记录 | |
插件 | 简介 | 请参阅当前文档 | 请参阅版本化文档 | 请参阅版本化文档 |
安装插件 | 请参阅当前文档 | 请参阅版本化文档 | 请参阅版本化文档 | |
编写插件 | 请参阅当前文档 | 请参阅版本化文档 | 请参阅版本化文档 | |
编写预设 | 请参阅当前文档 | 请参阅版本化文档 | 不存在的功能或未记录 | |
插件知识库 | 请参阅当前文档 | 请参阅版本化文档 | 请参阅版本化文档 | |
插件类型 | 请参阅当前文档 | 不存在的功能或未记录 | 不存在的功能或未记录 | |
插件 API | 请参阅当前文档 | 请参阅版本化文档 | 请参阅版本化文档 | |
API | @storybook/blocks/ArgTypes | 请参阅当前文档 | 不存在的功能或未记录 | 不存在的功能或未记录 |
@storybook/blocks/Canvas | 请参阅当前文档 | 不存在的功能或未记录 | 不存在的功能或未记录 | |
@storybook/blocks/ColorPalette | 请参阅当前文档 | 不存在的功能或未记录 | 不存在的功能或未记录 | |
@storybook/blocks/Controls | 请参阅当前文档 | 不存在的功能或未记录 | 不存在的功能或未记录 | |
@storybook/blocks/Description | 请参阅当前文档 | 不存在的功能或未记录 | 不存在的功能或未记录 | |
@storybook/blocks/IconGallery | 请参阅当前文档 | 不存在的功能或未记录 | 不存在的功能或未记录 | |
@storybook/blocks/Markdown | 请参阅当前文档 | 不存在的功能或未记录 | 不存在的功能或未记录 | |
@storybook/blocks/Meta | 请参阅当前文档 | 不存在的功能或未记录 | 不存在的功能或未记录 | |
@storybook/blocks/Primary | 请参阅当前文档 | 不存在的功能或未记录 | 不存在的功能或未记录 | |
@storybook/blocks/Source | 请参阅当前文档 | 不存在的功能或未记录 | 不存在的功能或未记录 | |
@storybook/blocks/Stories | 请参阅当前文档 | 不存在的功能或未记录 | 不存在的功能或未记录 | |
@storybook/blocks/Story | 请参阅当前文档 | 不存在的功能或未记录 | 不存在的功能或未记录 | |
@storybook/blocks/Subtitle | 请参阅当前文档 | 不存在的功能或未记录 | 不存在的功能或未记录 | |
@storybook/blocks/Title | 请参阅当前文档 | 不存在的功能或未记录 | 不存在的功能或未记录 | |
@storybook/blocks/Typeset | 请参阅当前文档 | 不存在的功能或未记录 | 不存在的功能或未记录 | |
@storybook/blocks/Unstyled | 请参阅当前文档 | 不存在的功能或未记录 | 不存在的功能或未记录 | |
@storybook/blocks/useOf | 请参阅当前文档 | 不存在的功能或未记录 | 不存在的功能或未记录 | |
Stories/组件 Story 格式(请参阅下面的注释) | 请参阅当前文档 | 请参阅版本化文档 | 不存在的功能或未记录 | |
ArgTypes | 请参阅当前文档 | 不存在的功能或未记录 | 不存在的功能或未记录 | |
main.js 配置/概述 | 请参阅当前文档 | 不存在的功能或未记录 | 不存在的功能或未记录 | |
main.js 配置/框架 | 请参阅当前文档 | 不存在的功能或未记录 | 不存在的功能或未记录 | |
main.js 配置/stories | 请参阅当前文档 | 不存在的功能或未记录 | 不存在的功能或未记录 | |
main.js 配置/插件 | 请参阅当前文档 | 不存在的功能或未记录 | 不存在的功能或未记录 | |
main.js 配置/babel | 请参阅当前文档 | 不存在的功能或未记录 | 不存在的功能或未记录 | |
main.js 配置/babelDefault | 请参阅当前文档 | 不存在的功能或未记录 | 不存在的功能或未记录 | |
main.js 配置/build | 请参阅当前文档 | 不存在的功能或未记录 | 不存在的功能或未记录 | |
main.js 配置/core | 请参阅当前文档 | 不存在的功能或未记录 | 不存在的功能或未记录 | |
main.js 配置/docs | 请参阅当前文档 | 不存在的功能或未记录 | 不存在的功能或未记录 | |
main.js 配置/env | 请参阅当前文档 | 不存在的功能或未记录 | 不存在的功能或未记录 | |
main.js 配置/features | 请参阅当前文档 | 不存在的功能或未记录 | 不存在的功能或未记录 | |
main.js 配置/indexers | 请参阅当前文档 | 不存在的功能或未记录 | 不存在的功能或未记录 | |
main.js 配置/logLevel | 请参阅当前文档 | 不存在的功能或未记录 | 不存在的功能或未记录 | |
main.js 配置/managerHead | 请参阅当前文档 | 不存在的功能或未记录 | 不存在的功能或未记录 | |
main.js 配置/previewAnnotations | 请参阅当前文档 | 不存在的功能或未记录 | 不存在的功能或未记录 | |
main.js 配置/previewBody | 请参阅当前文档 | 不存在的功能或未记录 | 不存在的功能或未记录 | |
main.js 配置/previewHead | 请参阅当前文档 | 不存在的功能或未记录 | 不存在的功能或未记录 | |
main.js 配置/refs | 请参阅当前文档 | 不存在的功能或未记录 | 不存在的功能或未记录 | |
main.js 配置/staticDirs | 请参阅当前文档 | 不存在的功能或未记录 | 不存在的功能或未记录 | |
main.js 配置/swc | 请参阅当前文档 | 不存在的功能或未记录 | 不存在的功能或未记录 | |
main.js 配置/typescript | 请参阅当前文档 | 不存在的功能或未记录 | 不存在的功能或未记录 | |
main.js 配置/viteFinal | 请参阅当前文档 | 不存在的功能或未记录 | 不存在的功能或未记录 | |
main.js 配置/webpackFinal | 请参阅当前文档 | 不存在的功能或未记录 | 不存在的功能或未记录 | |
框架 | 请参阅当前文档 | 不存在的功能或未记录 | 不存在的功能或未记录 | |
CLI 选项 | 请参阅当前文档 | 请参阅版本化文档 | 请参阅版本化文档 |
我的工具栏或插件可以使用哪些图标?
使用 @storybook/components
包,您可以获得一组图标,您可以使用这些图标自定义您的 UI。在编写插件或定义 Storybook 全局类型时,请使用下表作为参考。浏览此 story 以查看图标的外观。
我在 Storybook 生产构建中看到“No Preview”错误
如果您正在使用 serve
包来验证 Storybook 的生产构建,您将收到该错误。这与 serve
如何处理重写有关。例如,/iframe.html
被重写为 /iframe
,您将收到该错误。
我们建议您改用 http-server,并使用以下命令预览 Storybook
npx http-server storybook-static
假设您不想经常运行上面的命令。将 http-server
添加为开发依赖项,并创建一个新脚本来预览 Storybook 的生产构建。
我可以在 Vue 2 中使用 Storybook 吗?
Vue 2 于 2023 年 12 月 31 日进入 生命周期结束 (EOL),并且不再受 Vue 团队支持。因此,我们已停止在 Storybook 8 及更高版本中支持 Vue 2,并且不会发布任何支持它的新版本。我们建议将您的项目升级到 Storybook 完全支持的 Vue 3。如果这不是一个选项,您仍然可以通过安装最新版本的 Storybook 7 在 Vue 2 中使用 Storybook,命令如下
npx storybook@^7 init
为什么我的代码块在 Storybook MDX 中没有高亮显示?
开箱即用,Storybook 为一组语言(例如,Javascript、Markdown、CSS、HTML、Typescript、GraphQL)提供语法高亮显示,您可以将它们用于代码块。目前,当您尝试注册自定义语言以获得语法高亮显示时,存在一个已知的限制。我们正在努力修复此问题,并在可用后更新此部分。
为什么我的 MDX 样式在 Storybook 中不起作用?
使用 MDX 编写文档可能很麻烦,尤其是在使用带有代码块的换行符时,代码的格式设置方式。例如,这将中断
<style>{`
.class1 {
...
}
.class2 {
...
}
`}</style>
但是这会起作用
<style>
{`
.class1 {
...
}
.class2 {
...
}
`}
</style>
有关更多信息,请参见以下 issue。
为什么我的模拟 GraphQL 查询在使用 Storybook 的 MSW 插件时失败?
如果您正在使用 Vue 3,您需要安装 @vue/apollo-composable
。对于 Svelte,您需要安装 @rollup/plugin-replace
并将您的 rollup.config
文件更新为以下内容
// Boilerplate imports
import replace from '@rollup/plugin-replace';
const production = !process.env.ROLLUP_WATCH;
// Remainder rollup.config implementation
export default {
input: 'src/main.js',
output: {
sourcemap: true,
format: 'iife',
name: 'app',
file: 'public/build/bundle.js',
},
plugins: [
// Other plugins
// Configures the replace plugin to allow GraphQL Queries to work properly
replace({
'process.env.NODE_ENV': JSON.stringify('development'),
}),
]
};
对于 Angular,最常见的问题是 mockServiceWorker.js
文件的位置。使用此 示例 作为参考点。
我可以使用其他 GraphQL 提供程序与 Storybook 的 MSW 插件一起使用吗?
是的,查看 插件的示例,了解如何集成不同的提供程序。
我可以使用 Storybook 的 MSW 插件模拟 GraphQL mutations 吗?
否,目前,MSW 插件仅支持 GraphQL 查询。如果您有兴趣包含此功能,请在 MSW 插件仓库 中打开一个 issue,并与维护者跟进。
为什么在使用某些字符时我的 stories 未正确显示?
Storybook 允许您在使用故事命名时使用大多数字符。但是,当 Storybook 为故事生成内部标识符时,特定字符(例如 #
)可能会导致问题,从而导致冲突并错误地输出正确的故事。我们建议少量使用此类字符。
为什么 Storybook 的 source loader 在使用柯里化函数时返回 undefined?
这是一个 Storybook 的已知问题。如果您有兴趣修复它,请打开一个 issue 并提供 可重现的示例,以便可以在未来的版本中对其进行分类和修复。
为什么我的 args 不再显示默认值了?
在 6.3 版本之前,如果指定了 argTypes.defaultValue
或者从组件的属性(例如,React 的 prop types、Angular 的 inputs、Vue 的 props)推断出来,未设置的 args 会被设置为 argTypes.defaultValue
。从 6.3 版本开始,Storybook 不再推断默认值,而是在未设置时将 arg 的值定义为 undefined
,从而允许框架提供其默认值。
如果您正在使用 argTypes.defaultValue
来修复上述问题,您不再需要这样做,并且可以安全地从您的 stories 中删除它。
此外,假设您之前使用 argTypes.defaultValue
或依赖推断来为 arg 设置默认值。在这种情况下,您应该在组件级别定义 arg 的值
export default {
component: MyComponent,
args: {
//👇 Defining the arg's value at the component level.
text: 'Something',
},
};
对于 Storybook 的文档,您可以通过配置 table.defaultValue
设置来手动配置显示的值
export default {
component: MyComponent,
argTypes: {
//👇 Defining the arg's display value in docs.
text: {
table: { defaultValue: { summary: 'SomeType<T>' } },
},
},
};
为什么 Storybook 的测试运行器无法工作?
Storybook 的测试运行器和最新版本的 Jest(即 28 版本)存在一个问题,这阻止了它有效地运行。作为一种解决方法,您可以将 Jest 降级到之前的稳定版本(即 27 版本),这样您就可以运行它了。有关更多信息,请参阅以下 issue。
Storybook 如何处理环境变量?
Storybook 内置支持环境变量。默认情况下,环境变量仅在 Node.js 代码中可用,在浏览器中不可用,因为某些变量应该保密(例如,API 密钥),并且不应暴露给任何访问已发布 Storybook 的人。
要公开一个变量,您必须在其名称前加上 STORYBOOK_
。因此,STORYBOOK_API_URL
将在浏览器代码中可用,但 API_KEY
将不可用。此外,您还可以通过在 env
字段在 .storybook/main.js
文件中设置来自定义哪些变量被公开。
变量在 JavaScript 编译时设置,即在开发服务器启动或您构建 Storybook 时。环境变量文件不应提交到 Git,因为它们通常包含不适合添加到 Git 的秘密信息。相反,将 .env.*
添加到您的 .gitignore
文件中,并在您的托管服务提供商(例如,GitHub)上手动设置环境变量。