
Storybook 5.2
世界一流的设计系统基础设施

Storybook 为像 Shopify Polaris、IBM Carbon、Salesforce Lightning、Auth0 Cosmos、Airbnb Lunar 等设计系统以及超过 25,000 个公共 GitHub 项目提供组件开发支持。
Storybook 5.2 简化了所有 Storybook 用户的组件文档编写。我们的目标是让所有 Storybook 项目都能轻松实现最佳实践文档——就像上面那些知名设计系统中那样。我们的首要步骤包括:
📚 DocsPage: 零配置组件文档
📝 MDX: 统一 Story 和长篇文档
📦 组件 Story 格式 (CSF): 简单、可移植的组件示例
🖼 Storybook 设计系统: 将最佳实践付诸实践
它还在各个层面带来了数百项改进,包括新的插件 API、原生 TypeScript 类型、新的预设、自定义 Story 排序、一流的 Hook 支持、性能提升等等。
请继续阅读,了解改进详情、升级说明和项目更新。
设计系统文档,我们来了
今年早些时候,我们制定了一个雄心勃勃的愿景,旨在彻底改进组件文档。
“借助 Storybook Docs,您可以快速生成设计系统文档,根据您的喜好进行自定义,并将最佳实践分享给您的团队。”
5.2 版本正式支持 Storybook Docs。与 Storybook 的其他部分一样,Docs 支持所有主流框架,包括 React、Vue、Angular、HTML Web Components、Svelte 等等。
DocsPage
5.2 的核心是 DocsPage,这是一个零配置模板,可根据您现有的 Story 自动生成最佳实践组件文档。

Storybook 的价值主张在于它使您能够**独立**开发 UI 组件。开发人员通过构建 Story(示例)来捕获组件的关键状态,而无需担心复杂的依赖关系或不稳定的数据 API。
DocsPage 背后的关键洞察在于,这些 Story(现代前端团队在开发过程中自然而然地会创建数百个)可以用来生成出色的文档。与传统文档一旦发布就会过时不同,Story 是可执行、可测试的,并且始终与生产代码保持同步。
DocsPage 会自动将您的 Story 与代码注释和组件属性表结合起来,生成美观的页面,其中融入了设计系统的最佳实践……而且您无需进行额外配置!
在DocsPage 发布公告中了解详情


MDX
DocsPage 是一种免费获取优秀文档的绝佳方式。如果您想要更多控制权,MDX 是一种在同一个文件中灵活地并排编写 Story 和长篇文档的方式。
以下是在 MDX 中编写 Story 的示例。这些 Story 与整个 Storybook 生态系统完全兼容
import { Meta, Story, Props } from '@storybook/addon-docs/blocks';
import { Badge } from './Badge';
<Meta title="Demo/Badge" component={Badge} />
# Badge
With `MDX` we write longform markdown documentation for our `Badge` component and embed Doc Blocks inline.
<Props of={Badge} />
<Story name="positive">
<Badge status="positive">Positive</Badge>
</Story>
MDX 将 markdown 文档的便利性和简洁性与任意 JSX 相结合,这意味着您可以使用任意内容和布局来配置您的组件文档。我们还提供了一个丰富的“文档块”(Doc Blocks)库,用于常见的文档任务,例如显示组件属性、调色板、排版示例和其他设计令牌。
MDX 支持已在 5.2 版本中提供,正式版本目前在 Storybook 5.3-rc 中可用。要了解更多信息,请参阅Storybook MDX 发布公告。
组件 Story 格式
为了支持 MDX Story,我们彻底改造了 Storybook 的 Story 格式。组件 Story 格式 (CSF) 是一个可移植的开放标准,用于在纯 ES6 模块中编写 Storybook Story。

如果您使用过 Storybook 的早期版本,您可能熟悉“经典”的 storiesOf
API
import { storiesOf } from '@storybook/react';
storiesOf('atoms/Button', module)
.add('text', () => <Button>Hello</Button>)
.add('emoji', () => <Button>😀😎👍💯</Button>);
在 CSF 中,相同的示例看起来像这样
export default { title: 'atoms/Button' };
export const text = () => <Button>Hello</Button>;
export const emoji = () => <Button>😀😎👍💯</Button>;
CSF 支持 storiesOf
API 的所有功能,但它……太棒了。它是一个干净、标准的格式,您已经熟悉并喜爱它。CSF Story 没有 Storybook 特定的依赖,这意味着这些 Story 可以移植到任何支持 ES6 的环境。想象一下,能够在整个设计/开发堆栈中无缝重用组件示例:在您的设计工具中、在您的文档中,甚至在您的测试套件中!我们正积极致力于实现这一目标。
作为一个纯声明式标准,MDX 或 Github 风味 Markdown (GFM) 等更高级别的格式可以透明地编译为 CSF。这使得 Storybook 社区可以在尝试其他 Story 编写方式的同时,保持与整个生态系统的兼容性。
CSF 是 Storybook 5.2 中的默认格式。当您向新项目添加 Storybook 时,它现在会生成 CSF 格式的模板代码,而不是旧的 storiesOf
格式。当然,鉴于成千上万的项目依赖于 storiesOf
,我们将在可预见的未来继续提供支持。
要了解更多信息,请参阅CSF 发布公告

Storybook 设计系统
将所有这些工作联系在一起的是 Storybook 设计系统 (SDS)。该设计系统旨在提高三个高流量 Storybook 网站之间的组件复用性,同时也是 Storybook Docs 消费、内部测试并最终展示其潜力的起点。

SDS 源于统一三个不同网站中不同组件的需求:Storybook 官网、Learn Storybook 教程以及 Chromatic(Storybook 维护者提供的可视化测试服务)。
它包含 25 个生产级功能性 UI 组件和 95 个 Story,以及 Storybook 品牌的设计令牌和组件/库文档。
SDS 将使 Storybook 社区更容易开发和维护新的营销和文档网站。但它还有一个次要目的:它也是 Storybook Docs 本身的设计驱动因素和公共参考实现!如果您想了解如何开发组件 Story、如何记录、测试和发布它们,SDS 就是最佳实践的来源。
要了解更多信息,请浏览Storybook 设计系统或阅读设计系统发布公告

终于实现轻松文档化!
Storybook 已经是**设计系统工程**的首选工具。随着 DocsPage、MDX、组件 Story 格式以及新的设计系统的加入,我们正在改变组件文档的编写方式,并将设计系统的最佳实践带给所有使用 Storybook 的项目。立即在 5.2 版本中开始体验这些改进,并请继续关注 5.3 版本中的更多精彩更新。

还有(数百)件事
一个拥有 750 多名贡献者的繁荣社区项目的惊人之处在于,该系统在各个层面都在不断改进。
5.2 版本的其他亮点包括:
✅ 插件 API。Storybook 以其丰富的插件生态系统而闻名,得益于 Norbert de Langen 和 Filipp Riabchun 新的基于 Hook 的 API,在 5.2 版本中编写插件变得容易多了。新的 API 遵循 React hooks 模式,使状态管理和通信更简单、更简洁。改进详情在此记录。
✅ TypeScript 支持。TypeScript 最近在 Storybook 的代码库中超过了 Javascript,并且 5.2 包含了大多数软件包的“原生”TypeScript 类型。我们将很快发布正式公告,但与此同时,您可以在大多数常见情况下不再依赖 DefinitelyTyped。感谢 Kai Röder、Gaëtan Maisse、Norbert de Langen 以及众多积极参与转换工作的贡献者们。
✅ React hooks 支持。得益于 小幅修复,Storybook 5.2 在 Story 中包含了对 React hook 的一流支持,感谢 Michael Shilman 和 Atanas Stoyanov。
✅ Story 排序。应大众需求,Storybook 现在支持 Story 排序功能,以控制导航面板中 Story 的顺序。由 Robert Snow 贡献,Tom Coleman 提供了帮助。
✅ 性能。大型 Storybook 的 Story 切换和搜索性能显著提升(约 1000ms => 约 50ms),这得益于 Kevin Weber 重现的慢速问题以及 Michael Shilman 的优化。
✅ 独立模式。Storybook 仍基于 Webpack,但现在可以将 UI 连接到外部服务器,这得益于 RP Deshaies 在 Tom Coleman 和 Michael Shilman 的帮助下完成的工作。我们在 5.2 版本中原型实现了一个在 Parcel 打包器下运行的 Storybook 实例。这为未来许多有趣的事情奠定了基础。有没有人想要 Storybook for Rails?
✅ 新预设。Storybook 5.1 引入了预设:用于 babel、webpack 和插件的单行配置。Storybook 5.2 增加了 Igor Davydkin 贡献的 SCSS 预设以及 Brody McKee 贡献的测试版 Create-React App 预设,后者极大地改进了 Storybook 内置的 CRA 支持。
升级到 Storybook 5.2
Storybook 5.2 包含许多新功能,据我所知没有任何破坏性更改。如果您是从 3.x/4.x 版本升级,我们提供了5.0 升级指南。如果您已经在 5.x 版本,升级非常容易
npx npm-check-updates '/storybook/' -u
npm install # or yarn
如果您是 Storybook 的新手,现在是入门的最佳时机。查阅Storybook 教程,了解 React/Angular/Vue 的分步指南。或者直接开始
cd my-project
npx -p @storybook/cli sb init
yarn storybook
一旦升级到 5.2,将 DocsPage 添加到您的项目将非常简单
npm install @storybook/addon-docs --save-dev # or yarn
然后将以下行添加到您的 .storybook/presets.js
文件中
module.exports = ['@storybook/addon-docs/react/preset'];
将 react
替换为您选择的框架。有关配置 DocsPage 的更多信息,请阅读 addon-docs
安装说明。
参与进来
Storybook 的基石是其令人难以置信的开发者和用户社区。该项目最近超过了 41,000 个 Github 星,这使我们与 Rails 和 Bitcoin 等传奇项目并驾齐驱。我们共同构建组件开发的未来。
我们非常欢迎您的参与,无论您的经验水平如何。如果 Storybook 让您的 UI 开发工作流程更轻松,请帮助 Storybook 变得更好。您可以贡献新功能、修复错误或改进文档。加入我们的 Discord,在 Open Collective 上支持我们,或直接在 Github 上参与。请为这篇文章👏鼓掌并分享,帮助更多人发现它。
Storybook 5.2 代码贡献者
@8beeeaaat @adamdoyle @atanasster @autarc @baraalex @benoitdion @bqrichards @chaseadamsio @chris-dura @christianliebel @christoph-fricke @christophehurpeau @codebyalex @crimx@ctavan @danielduan @danrha @darondel-yoobic @debel27 @dogafincan @domyen @dylanpiercey @edumoreira1506 @elliotlarson @emilio-martinez @enagy27 @enuvid @ewgenius @expe-lbenychou @fabianmarinog-turner @fabiradi @forbeslindesay @gaetanmaisse @ghengeveld @gnujim @gongreg @graup @hipstersmoothie @hypnosphi @indigolain @jamesgeorge007 @jballin @jeffgukang @jendowns @jessica-koch @jimmydalecleveland @joeycozza @jounqin @jsomsanith-tlnd @juliamitchelmore @kaelig @kamahl19 @kroeder @leoyli @libetl @lonyele @lucasterra @mariocadenas @matt-tingen @matthewlehner @mrmckeb @ndelangen @ndom91 @nzacca @pascaliske @piperchester @pksunkara @pocka @rembrandtreyes @resource11 @richardtorres314 @robaxelsen @roydipti23 @rwoverdijk @sakito21 @shilman @simenb @smasontst @stephanemw @stereodenis @testerez @thebuilder @tylerlee @wa4-fearless-otter @xyshaokang @zkochan @zol