框架
Storybook 的架构旨在支持各种 Web 框架,包括 React、Vue、Angular、Web Components、Svelte 以及十几个其他框架。本指南帮助您开始为 Storybook 添加新的框架支持。
搭建新的框架
首先要做的是在您自己的仓库中搭建框架支持。
我们建议采用与 Storybook monorepo 相同的项目结构。该结构包含框架包 (app/<framework>
) 和示例应用程序 (examples/<framework>-kitchen-sink
) 以及其他相关的文档和配置(如果需要)。
看起来它可能比必要的层级结构稍微复杂一些。但是,由于该结构镜像了 Storybook monorepo 的结构方式,您可以重用 Storybook 的工具。如果以后需要将框架移动到 Storybook monorepo 中,这也使其更容易。
我们建议使用 @storybook/html
作为入门框架,因为它最简单,并且不包含特定于框架的特性。这里有一个帮助您入门的样板文件 here。
框架架构
在 Storybook 中支持新框架通常包括两个主要方面
-
配置服务器。在 Storybook 中,服务器是您运行
storybook dev
或storybook build
时运行的 node 进程。配置服务器通常意味着以框架特定的方式配置 babel 和 webpack。 -
配置客户端。客户端是在浏览器中运行的代码,配置客户端意味着提供一个框架特定的 story 渲染函数。
配置服务器
Storybook 具有 预设 的概念,预设通常是用于文件加载的 babel/webpack 配置。如果您的框架有自己的文件格式(例如,“.vue”),您可能需要在加载时将它们转换为 JavaScript 文件。如果您假设框架的每个用户都需要这样做,则应将其添加到框架中。到目前为止,添加到 Storybook 的每个框架都这样做了,因为 Storybook 的核心配置非常简单。
包结构
在添加框架预设之前,了解 Storybook 的包结构很有帮助。每个框架通常在其 package.json
中公开两个可执行文件
{
"bin": {
"storybook": "./bin/index.js",
"build-storybook": "./bin/build.js"
}
}
这些脚本将 options
对象传递给 @storybook/core/server
,这是一个抽象了 Storybook 所有框架无关代码的库。
例如,这是使用 storybook dev
启动开发服务器的样板文件
import { buildDev } from '@storybook/core/server';
import options from './options';
buildDev(options);
因此,添加框架预设的本质只是填写该 options 对象。
服务器选项
如上所述,服务器 options
对象负责配置服务器的大部分工作。
让我们看一下 @storybook/vue
的 options 定义
import { sync } from 'read-pkg-up';
export default {
packageJson: sync({ cwd: __dirname }).packageJson,
framework: 'vue',
frameworkPresets: [require.resolve('./framework-preset-vue.js')],
};
framework
选项的值(即 ‘vue’)会传递给插件,并允许它们执行与您的框架相关的特定任务。
此文件的本质是框架预设,这些是标准的 Storybook 预设 -- 您可以查看 Storybook monorepo 中的框架包(例如 React、Vue、Web Components)以查看框架特定自定义的示例。
在开发您自定义的、非 Storybook 维护的框架时,您可以使用 frameworkPath
键指定位置文件的路径
import { sync } from 'read-pkg-up';
export default {
packageJson: sync({ cwd: __dirname }).packageJson,
framework: 'my-framework',
frameworkPath: '@my-framework/storybook',
frameworkPresets: [require.resolve('./framework-preset-my-framework.js')],
};
您可以添加 frameworkPath
的相对路径。不要忘记它们默认从 Storybook 配置目录(即 .storybook
)解析。
确保 frameworkPath
指向框架应用程序内的 dist/client/index.js
文件。
配置客户端
要配置客户端,您必须提供一个框架特定的渲染函数。在深入了解细节之前,必须了解用户编写的 stories 如何与屏幕上呈现的内容相关。
可渲染对象
Storybook stories 是 ES6 对象,它们返回一个“可渲染对象”。
考虑以下 React story
import { Button } from './Button';
export default {
component: Button,
};
export const Sample = {
render: () => <Button label="hello button" />,
};
在这种情况下,可渲染对象是 React 元素 <Button .../>
。
在大多数其他框架中,可渲染对象实际上是一个普通的 JavaScript 对象。
考虑以下假设示例
// Replace your-framework with the name of your framework
import type { Meta, StoryObj } from '@storybook/your-framework';
import { Button } from './Button';
const meta: Meta<typeof Button> = {
component: Button,
};
export default meta;
type Story = StoryObj<typeof Button>;
export const Sample: Story = {
render: () => ({
template: '<button :label=label />',
data: {
label: 'hello button',
},
}),
};
这种“可渲染对象”的设计是框架特定的,理想情况下应与该框架的习惯用法相匹配。
渲染函数
框架的渲染函数负责将可渲染对象转换为 DOM 节点。它通常采用以下形式
const rootElement = document.getElementById('root');
export default function renderMain({ storyFn }: RenderMainArgs) {
const storyObj = storyFn();
const html = fn(storyObj);
rootElement.innerHTML = html;
}
包结构
在客户端,关键文件是 src/client/preview.js
import { start } from '@storybook/preview-api';
import './globals';
import render from './render';
const api = start(render);
// the boilerplate code
globals 文件通常设置一个全局变量,客户端代码(例如插件提供的装饰器)如果需要了解它在哪个框架中运行,可以引用该变量
import { global } from '@storybook/global';
const { window: globalWindow } = global;
globalWindow.STORYBOOK_ENV = 'vue';
start
函数抽象了 Storybook 所有框架无关的客户端(浏览器)代码,它接受我们上面定义的渲染函数。有关渲染函数的示例,请参阅 Storybook monorepo 中的 React、Vue、Angular 和 Web Components。