返回博客

Storybook 5 迁移指南

轻松跳跃,迈向全新的美妙开发者体验

loading
Michael Shilman
@mshilman
最后更新于

本分步指南将引导您迁移到 Storybook 5.0 (SB5)

如果您是 Storybook 的活跃用户,可能在短短几个月前才刚将 Storybook 升级到 4.0,现在可能觉得有些无奈。

好消息是,与此相比,5.0 升级简直是小菜一碟。您最大的变化将是适应 Storybook 华丽而实用的新设计。绝对值得!

本指南将带您了解

  1. 升级 Storybook 包
  2. 处理重大变更
  3. 熟悉新 UI

步骤 1: 包升级

首先要做的是升级 Storybook 的包,@storybook/*

注意:如果您从 3.x 版本升级,我建议您先遵循Storybook 4 升级指南,然后再回到这里。Storybook 4 包含了 BabelWebpack 的重大升级,这是一个相当具有破坏性的变化。一旦您完成了这一步,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。如果是,恭喜您,欢迎来到您的组件开发体验史诗级升级!

如果您在遵循本指南时遇到问题,或者已经完成了指南但仍然有问题,请执行以下步骤

  1. 在我们的Github issue中搜索您的问题——可能其他人也遇到过同样的问题。
  2. 创建一个新 issue 描述您的问题,最好附带一个指向我们可以重现问题的公共仓库链接。
  3. 加入我们的公共 Discord 并在 #support 频道提问。我们是一个友好的社区,乐于帮助您完成升级。

来自 Storybook 团队的 ❤️

加入 Storybook 邮件列表

获取最新消息、更新和发布

7,180开发者及以上

我们正在招聘!

加入 Storybook 和 Chromatic 背后的团队。构建被数十万开发者在生产中使用的工具。远程优先。

查看职位

热门文章

Storybook Docs 抢先看

将 Story 转化为实时文档
loading
Michael Shilman

Storybook 5.1

React Native • Accessibility • Context • Presets • Docs 更新
loading
Michael Shilman

Storybook 5.0

欢迎来到组件开发的未来!
loading
Michael Shilman
加入社区
7,180开发者及以上
原因为什么选择 Storybook组件驱动的 UI
文档指南教程更新日志遥测
社区插件参与贡献博客
案例展示探索项目组件词汇表
开源软件
Storybook - Storybook 中文

特别鸣谢 Netlify CircleCI