
Storybook 5 迁移指南
轻松跳跃,迈向全新的美妙开发者体验

本分步指南将引导您迁移到 Storybook 5.0 (SB5)。
如果您是 Storybook 的活跃用户,可能在短短几个月前才刚将 Storybook 升级到 4.0,现在可能觉得有些无奈。
好消息是,与此相比,5.0 升级简直是小菜一碟。您最大的变化将是适应 Storybook 华丽而实用的新设计。绝对值得!
本指南将带您了解
- 升级 Storybook 包
- 处理重大变更
- 熟悉新 UI
步骤 1: 包升级
首先要做的是升级 Storybook 的包,@storybook/*
。
注意:如果您从 3.x 版本升级,我建议您先遵循Storybook 4 升级指南,然后再回到这里。Storybook 4 包含了 Babel 和 Webpack 的重大升级,这是一个相当具有破坏性的变化。一旦您完成了这一步,5.x 的升级应该会非常顺利。
因此从现在开始,我假设您是从 4.x 版本升级。
如果您使用 yarn
,可以像这样交互式升级
yarn upgrade-interactive --latest
或者如果您使用 npm
,这样就可以了
npx npm-check-updates '/storybook/' -u && npm install
然后尝试运行 Storybook
yarn storybook
如果浏览器打开并且一切看起来正常,那么您的大部分升级工作已经完成,可以直接跳到步骤 3。
步骤 2: 修复重大变更
如果您没有看到 Storybook,是时候找出是哪个重大变更导致了问题了。这个版本是一个 semver 主版本,所以有一些变更。
查看终端和浏览器控制台中的错误信息应该能给您一些关于问题原因的线索。
话虽如此,以下是一些您应该了解的变更
✅ 您是否在“full control”模式下使用自定义 webpack 配置?如果是,我们在 SB5 中简化了 API,这是一个重大变更。
✅ 您是否在“extend”模式下使用自定义 webpack 配置?如果是,我们在 5.0.0 中无意中改变了行为,然后在 5.0.2 中恢复了 4.x 的行为并废弃了 extend 模式。
✅ 您是否使用主题 (theming)?我们在 SB5 中重做了主题功能。
✅ 您是否使用 options 插件?我们在 SB5 中废弃了它,转而使用 story parameters(但目前它应该仍然可用)。
✅ 您是否使用 backgrounds / viewport / a11y 插件?现在使用 parameters 配置它们(backgrounds / viewport / a11y)
✅ 您是否使用键盘快捷键?我们在 SB5 中改进了它们(但现在键盘快捷键可以配置,如果您怀念旧的,可以使用旧的)。
✅ 您是否依赖 Storybook 的 URL 结构?我们在 SB5 中改进了它(但保持了 selectedKind/selectedStory 的向后兼容性)。
步骤 3: 成功!
您的 Storybook 现在正常工作了吗?是时候看看 Storybook 的新特性了。Storybook 5 拥有一个全新设计的 UI,亮点如下:
- 精心打造的美丽新设计,包含明亮和暗黑主题
- 一个新的画布工具栏,提供对插件的快速视觉访问
- 重新设计的导航侧边栏,菜单更好用
- 重新设计的插件面板,带有方便的按钮来切换可见性
- 改进的键盘快捷键,用户也可配置
在认识 Storybook 的新设计中熟悉新 UI,并在您自己的项目中体验所有新功能。
大功告成!
希望您此时已成功升级到 SB5。如果是,恭喜您,欢迎来到您的组件开发体验史诗级升级!
如果您在遵循本指南时遇到问题,或者已经完成了指南但仍然有问题,请执行以下步骤
- 在我们的Github issue中搜索您的问题——可能其他人也遇到过同样的问题。
- 创建一个新 issue 描述您的问题,最好附带一个指向我们可以重现问题的公共仓库链接。
- 加入我们的公共 Discord 并在 #support 频道提问。我们是一个友好的社区,乐于帮助您完成升级。
— 来自 Storybook 团队的 ❤️