常见问题解答
以下是一些常见问题的解答。如果您有问题,可以在我们的 GitHub discussions 中提问。
错误:未找到 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 相关的问题,因为 Angular 未来版本将放弃对 View Engine 的支持。
如何使用 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-vite, nextjs, vue3-vite, etc.
import type { StorybookConfig } from '@storybook/your-framework';
import path from 'path';
const _require = typeof require === 'undefined' ? import.meta : require;
const getAbsolutePath = (packageName: string): any =>
path.dirname(_require.resolve(path.join(packageName, 'package.json'))).replace(/^file:\/\//, '');
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-docs'),
],
};
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 channel?
一个常见的错误是插件尝试访问“channel”,但 channel 未设置。这可能在几种不同情况下发生
-
您正在非浏览器环境(如 Jest)中尝试访问 addon channel(例如,通过调用
setOptions
)。您可能需要添加 channel mockimport { addons, mockChannel } from 'storybook/preview-api'; addons.setChannel(mockChannel());
-
在 React Native 中,这是一个特殊情况,记录在 #1192 中
为什么插件在组合 Storybook 中无法工作?
组合是我们随 6.0 版本发布的新功能,目前仍有一些限制。
目前,您在组合 Storybook 中使用的插件将无法工作。
我们正在努力克服这一限制,很快您将能够像使用非组合 Storybook 一样使用它们。
我可以创建一个没有本地故事 (stories) 的 Storybook 吗?
Storybook 只有在您的项目中定义了至少一个本地故事 (story)(或文档页面)时才能工作。在此上下文中,本地指的是您的项目 .storybook/main.js
配置中引用的 .stories.*
或 .mdx
文件。
如果您处于 Storybook 组合 场景中,您有多个 Storybook,并希望有一个额外的 Storybook 没有自己的故事 (stories),仅作为项目中所有其他 Storybook 的“粘合剂”用于演示/文档目的,您可以按照以下步骤操作
引入一个单独的 .mdx
文档页面(需要 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 版本位置 |
---|---|---|---|---|
N/A | 为何选择 Storybook | 查看当前文档 | 不存在的功能或未记录 | 不存在的功能或未记录 |
入门 | 安装 | 查看当前文档 | 查看版本化文档 | 查看版本化文档 |
什么是故事 (story) | 查看当前文档 | 查看您框架的版本化文档 | 查看您框架的版本化文档 | |
浏览故事 (Stories) | 查看当前文档 | 查看您框架的版本化文档 | 查看您框架的版本化文档 | |
设置 | 查看当前文档 | 查看您框架的版本化文档 | 查看您框架的版本化文档 | |
编写故事 (stories) | 介绍 | 查看当前文档 | 查看版本化文档 | 查看版本化文档 |
参数 | 查看当前文档 | 查看版本化文档 | 不存在的功能或未记录 | |
装饰器 | 查看当前文档 | 查看版本化文档 | 查看版本化文档 | |
组件命名与层级结构 | 查看当前文档 | 查看版本化文档 | 查看版本化文档 | |
构建页面和屏幕 | 查看当前文档 | 不存在的功能或未记录 | 不存在的功能或未记录 | |
多组件故事 (Stories) | 查看当前文档 | 不存在的功能或未记录 | 不存在的功能或未记录 | |
编写文档 | Autodocs | 查看当前文档 | 查看版本化插件文档 | 不存在的功能或未记录 |
MDX | 查看当前文档 | 查看版本化插件文档 | 不存在的功能或未记录 | |
文档块 | 查看当前文档 | 不存在的功能或未记录 | 不存在的功能或未记录 | |
预览和构建文档 | 查看当前文档 | 不存在的功能或未记录 | 不存在的功能或未记录 | |
测试 | 视觉测试 | 查看当前文档 | 查看版本化文档 | 查看版本化文档 |
无障碍测试 | 查看当前文档 | 不存在的功能或未记录 | 不存在的功能或未记录 | |
交互测试 | 查看当前文档 | 查看版本化文档 | 查看版本化文档 | |
快照测试 | 查看当前文档 | 查看版本化文档 | 查看版本化文档 | |
在测试/单元测试中导入 stories | 查看当前文档 | 查看版本化文档 | 查看版本化文档 | |
在测试/端到端测试中导入 stories | 查看当前文档 | 查看版本化文档 | 查看版本化文档 | |
共享 | 发布 Storybook | 查看当前文档 | 查看版本化文档 | 查看版本化文档 |
嵌入 | 查看当前文档 | 不存在的功能或未记录 | 不存在的功能或未记录 | |
组合 | 查看当前文档 | 不存在的功能或未记录 | 不存在的功能或未记录 | |
包组合 | 查看当前文档 | 不存在的功能或未记录 | 不存在的功能或未记录 | |
基础插件 | Controls | 查看当前文档 | Controls 是 6.0 版本特有的,请查看 Knobs 版本化文档 | Controls 是 6.0 版本特有的,请查看 Knobs 版本化文档 |
Actions | 查看当前文档 | 查看插件版本化文档 | 查看插件版本化文档 | |
视口 | 查看当前文档 | 查看插件版本化文档 | 查看插件版本化文档 | |
Backgrounds | 查看当前文档 | 查看插件版本化文档 | 查看插件版本化文档 | |
工具栏和全局变量 | 查看当前文档 | 查看版本化文档 | 不存在的功能或未记录 | |
配置 | 概览 | 查看当前文档 | 查看版本化文档 | 查看版本化文档 |
集成/框架 | 查看当前文档 | 不存在的功能或未记录 | 不存在的功能或未记录 | |
集成/框架对框架的支持 | 查看当前文档 | 不存在的功能或未记录 | 不存在的功能或未记录 | |
集成/编译器 | 查看当前文档 | 请查看版本化文档 此处 | 请查看版本化文档 此处 | |
集成/Typescript | 查看当前文档 | 查看版本化文档 | 查看版本化文档 | |
集成/样式和 CSS | 查看当前文档 | 查看版本化文档 | 查看版本化文档 | |
集成/图片和资产 | 查看当前文档 | 查看版本化文档 | 查看版本化文档 | |
故事 (Story) 渲染 | 查看当前文档 | 请查看版本化文档 此处 和 此处 | 请查看版本化文档 此处 | |
故事 (Story) 布局 | 查看当前文档 | 不存在的功能或未记录 | 不存在的功能或未记录 | |
用户界面/特性和行为 | 查看当前文档 | 查看版本化文档 | 查看版本化文档 | |
用户界面/主题 | 查看当前文档 | 查看版本化文档 | 查看版本化文档 | |
用户界面/侧边栏与 URL | 查看当前文档 | 查看版本化文档 | 查看版本化文档 | |
环境变量 | 查看当前文档 | 查看版本化文档 | 查看版本化文档 | |
构建器 | 介绍 | 查看当前文档 | 不存在的功能或未记录 | 不存在的功能或未记录 |
Vite | 查看当前文档 | 不存在的功能或未记录 | 不存在的功能或未记录 | |
Webpack | 查看当前文档 | 查看版本化文档 | 查看版本化文档 | |
构建器 API | 查看当前文档 | 不存在的功能或未记录 | 不存在的功能或未记录 | |
插件 | 介绍 | 查看当前文档 | 查看版本化文档 | 查看版本化文档 |
安装插件 | 查看当前文档 | 查看版本化文档 | 查看版本化文档 | |
编写插件 | 查看当前文档 | 查看版本化文档 | 查看版本化文档 | |
编写预设 | 查看当前文档 | 查看版本化文档 | 不存在的功能或未记录 | |
插件知识库 | 查看当前文档 | 查看版本化文档 | 查看版本化文档 | |
插件类型 | 查看当前文档 | 不存在的功能或未记录 | 不存在的功能或未记录 | |
插件 API | 查看当前文档 | 查看版本化文档 | 查看版本化文档 | |
API | @storybook/addon-docs/blocks/ArgTypes | 查看当前文档 | 不存在的功能或未记录 | 不存在的功能或未记录 |
@storybook/addon-docs/blocks/Canvas | 查看当前文档 | 不存在的功能或未记录 | 不存在的功能或未记录 | |
@storybook/addon-docs/blocks/ColorPalette | 查看当前文档 | 不存在的功能或未记录 | 不存在的功能或未记录 | |
@storybook/addon-docs/blocks/Controls | 查看当前文档 | 不存在的功能或未记录 | 不存在的功能或未记录 | |
@storybook/addon-docs/blocks/Description | 查看当前文档 | 不存在的功能或未记录 | 不存在的功能或未记录 | |
@storybook/addon-docs/blocks/IconGallery | 查看当前文档 | 不存在的功能或未记录 | 不存在的功能或未记录 | |
@storybook/addon-docs/blocks/Markdown | 查看当前文档 | 不存在的功能或未记录 | 不存在的功能或未记录 | |
@storybook/addon-docs/blocks/Meta | 查看当前文档 | 不存在的功能或未记录 | 不存在的功能或未记录 | |
@storybook/addon-docs/blocks/Primary | 查看当前文档 | 不存在的功能或未记录 | 不存在的功能或未记录 | |
@storybook/addon-docs/blocks/Source | 查看当前文档 | 不存在的功能或未记录 | 不存在的功能或未记录 | |
@storybook/addon-docs/blocks/Stories | 查看当前文档 | 不存在的功能或未记录 | 不存在的功能或未记录 | |
@storybook/addon-docs/blocks/Story | 查看当前文档 | 不存在的功能或未记录 | 不存在的功能或未记录 | |
@storybook/addon-docs/blocks/Subtitle | 查看当前文档 | 不存在的功能或未记录 | 不存在的功能或未记录 | |
@storybook/addon-docs/blocks/Title | 查看当前文档 | 不存在的功能或未记录 | 不存在的功能或未记录 | |
@storybook/addon-docs/blocks/Typeset | 查看当前文档 | 不存在的功能或未记录 | 不存在的功能或未记录 | |
@storybook/addon-docs/blocks/Unstyled | 查看当前文档 | 不存在的功能或未记录 | 不存在的功能或未记录 | |
@storybook/addon-docs/blocks/useOf | 查看当前文档 | 不存在的功能或未记录 | 不存在的功能或未记录 | |
故事 (Stories)/组件故事格式 (见下注) | 查看当前文档 | 查看版本化文档 | 不存在的功能或未记录 | |
ArgTypes | 查看当前文档 | 不存在的功能或未记录 | 不存在的功能或未记录 | |
main.js 配置/概览 | 查看当前文档 | 不存在的功能或未记录 | 不存在的功能或未记录 | |
main.js 配置/框架 | 查看当前文档 | 不存在的功能或未记录 | 不存在的功能或未记录 | |
main.js 配置/故事 (stories) | 查看当前文档 | 不存在的功能或未记录 | 不存在的功能或未记录 | |
main.js 配置/插件 | 查看当前文档 | 不存在的功能或未记录 | 不存在的功能或未记录 | |
main.js 配置/babel | 查看当前文档 | 不存在的功能或未记录 | 不存在的功能或未记录 | |
main.js 配置/babelDefault | 查看当前文档 | 不存在的功能或未记录 | 不存在的功能或未记录 | |
main.js 配置/构建 | 查看当前文档 | 不存在的功能或未记录 | 不存在的功能或未记录 | |
main.js 配置/核心 | 查看当前文档 | 不存在的功能或未记录 | 不存在的功能或未记录 | |
main.js 配置/文档 | 查看当前文档 | 不存在的功能或未记录 | 不存在的功能或未记录 | |
main.js 配置/环境 | 查看当前文档 | 不存在的功能或未记录 | 不存在的功能或未记录 | |
main.js 配置/特性 | 查看当前文档 | 不存在的功能或未记录 | 不存在的功能或未记录 | |
main.js 配置/索引器 | 查看当前文档 | 不存在的功能或未记录 | 不存在的功能或未记录 | |
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/icons
包,您可以获得一组可用于自定义 UI 的图标。查阅文档查看图标外观,并在编写插件或定义 Storybook 全局类型时将其作为参考。
Storybook 生产构建时出现“无预览”错误
如果您使用 serve
包验证 Storybook 的生产构建,就会出现该错误。这与 serve
处理重写的方式有关。例如,/iframe.html
被重写为 /iframe
,您就会收到该错误。
我们建议您使用 http-server 替代,并使用以下命令预览 Storybook
npx http-server storybook-static
如果您不想频繁运行上述命令。请将 http-server
添加为开发依赖项,并创建一个新脚本来预览您的 Storybook 生产构建。
我可以使用 Storybook 和 Vue 2 吗?
Vue 2 已于 2023 年 12 月 31 日进入生命周期结束 (EOL),Vue 团队不再提供支持。因此,我们已在 Storybook 8 及更高版本中停止支持 Vue 2,并且不会发布支持它的新版本。我们建议将您的项目升级到 Storybook 完全支持的 Vue 3。如果这不是一个选项,您仍然可以通过安装最新版本的 Storybook 7 来使用 Storybook 和 Vue 2,命令如下
npx storybook@^7 init
为什么我的 Storybook MDX 代码块没有高亮显示?
Storybook 开箱即用地为一组语言(例如 Javascript, Markdown, CSS, HTML, Typescript, GraphQL)提供语法高亮显示,您可以在代码块中使用。目前,当您尝试注册自定义语言以获取语法高亮时,存在一个已知限制。我们正在为此努力修复,修复可用后将更新此部分。
为什么我的 Storybook MDX 样式不生效?
使用 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 变更(mutation)吗?
目前不行,MSW 插件目前只支持 GraphQL 查询。如果你有兴趣包含此功能,请在MSW 插件仓库中提出 issue 并与维护者联系。
为什么在使用某些字符时,我的故事显示不正确?
Storybook 允许你在命名故事时使用大多数字符。但是,某些特定字符(例如,#
)在 Storybook 生成故事的内部标识符时可能导致问题,从而引起冲突并错误地输出正确的故事。我们建议尽量少使用此类字符。
为什么 Storybook 的源代码加载器对柯里化(curried)函数返回 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
来解决上述问题,现在不再需要这样做,你可以安全地将其从故事中移除。
此外,如果你之前使用 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),这样就可以运行了。更多信息请参阅以下问题。
Storybook 如何处理环境变量?
Storybook 内置支持环境变量。默认情况下,环境变量仅在 Node.js 代码中可用,而在浏览器中不可用,因为某些变量应保密(例如,API 密钥),并且不应暴露给访问已发布的 Storybook 的任何人。
要暴露变量,你必须在其名称前加上 STORYBOOK_
。因此 STORYBOOK_API_URL
将在浏览器代码中可用,但 API_KEY
不会。此外,你还可以通过在 .storybook/main.js
文件中设置 env
字段来自定义要暴露的变量。
变量在 JavaScript 编译时设置,即启动开发服务器或构建 Storybook 时。环境变量文件不应提交到 Git,因为它们通常包含不适合添加到 Git 的秘密信息。相反,应将 .env.*
添加到 .gitignore
文件中,并在托管提供商(例如,GitHub)上手动设置环境变量。