Storybook for Svelte & Vite

Storybook for Svelte & Vite 是一个框架，使得使用 Vite 构建的 Svelte 应用能够轻松地独立开发和测试 UI 组件。

要求

Svelte ≥ 5.0
Vite ≥ 5.0

入门

在没有 Storybook 的项目中

在你的 Svelte 项目根目录中运行此命令后，按照提示操作

npm create storybook@latest

关于 Storybook 入门的更多信息。

在已有 Storybook 的项目中

该框架设计用于 Storybook 7+ 版本。如果你尚未使用 v7 版本，请运行此命令进行升级

npx storybook@next upgrade

自动迁移

当你运行上面的 upgrade 命令时，应该会收到一个提示，询问你是否迁移到 @storybook/svelte-vite，它会为你处理一切。如果自动迁移不适用于你的项目，请参考下面的手动迁移指南。

手动迁移

首先，安装该框架

npm install --save-dev @storybook/svelte-vite

然后，更新你的 .storybook/main.js|ts 文件以更改框架属性

.storybook/main.ts

import type { StorybookConfig } from '@storybook/svelte-vite';
 
const config: StorybookConfig = {
  // ...
  framework: '@storybook/svelte-vite', // 👈 Add this
};
 
export default config;

编写原生 Svelte Stories

Storybook 提供了一个由社区维护的 Svelte 插件，使你能够使用模板语法为 Svelte 组件编写 Stories。

社区积极维护 Svelte CSF 插件，但它目前仍缺少 Storybook 官方 Svelte 框架支持中的一些功能。欲了解更多信息，请参阅插件文档。

设置

如果你使用 Svelte 框架初始化了项目，该插件已经为你安装和配置好了。但是，如果你是从旧版本迁移过来，则需要执行额外的步骤来启用此功能。

运行以下命令来安装插件。

npx storybook@latest add @storybook/addon-svelte-csf

CLI 的 add 命令会自动完成插件的安装和设置。要手动安装，请参阅我们的文档了解如何安装插件。

更新你的 Storybook 配置文件（即 .storybook/main.js|ts）以启用对此格式的支持。

.storybook/main.ts

// Replace your-framework with svelte-vite or sveltekit
import type { StorybookConfig } from '@storybook/your-framework';
 
const config: StorybookConfig = {
  stories: ['../src/**/*.stories.@(js|jsx|ts|tsx|svelte)'],
  addons: [
    // Other Storybook addons
    '@storybook/addon-svelte-csf',
  ],
};
 
export default config;

配置

默认情况下，Svelte 插件为 Storybook 的 Svelte 框架提供零配置支持。但是，你可以扩展 Storybook 配置文件（即 .storybook/main.js|ts）并提供额外的插件选项。下面列出了可用选项及其使用示例。

.storybook/main.ts

// Replace your-framework with the name of your Svelte framework
import type { StorybookConfig } from '@storybook/your-framework';
 
const config: StorybookConfig = {
  // Other configuration
  addons: [
    {
      name: '@storybook/addon-svelte-csf',
      options: {
        legacyTemplate: true, // Enables the legacy template syntax
      },
    },
  ],
};
export default config;

选项	描述
`legacyTemplate`	启用对 `Template` 组件的支持，以实现向后兼容。 `options: { legacyTemplate: true }`

启用 legacyTemplate 选项可能会引入性能开销，应谨慎使用。欲了解更多信息，请参阅插件文档。

升级到 Svelte CSF 插件 v5

随着 Svelte 5 的发布，Storybook 的 Svelte CSF 插件已更新以支持新功能。本指南将帮助你迁移到最新版本的插件。以下是 5.0 版本的主要变化以及升级项目所需的步骤概述。

简化的 Story API

如果你使用 Meta 组件或 meta 命名导出项来定义 Story 的元数据（例如参数），你需要更新 Stories 以使用新的 defineMeta 函数。此函数返回一个包含所需信息的对象，其中包括一个你必须用于定义组件 Stories 的 Story 组件。

MyComponent.stories.svelte

<script>
  import { Meta, Story } from '@storybook/addon-svelte-csf';
 
  import MyComponent from './MyComponent.svelte';
</script>
 
 
<Meta title="MyComponent" component={MyComponent} />
 
<Story name="Default" />

Story 模板

如果你曾使用 Template 组件来控制组件在 Storybook 中的渲染方式，此功能已被 Story 组件中的内置 children 支持所取代，使你能够直接在 Story 中组合组件并定义 UI 结构。

MyComponent.stories.svelte

<script>
  import { Meta, Template, Story } from '@storybook/addon-svelte-csf';
 
  import OuterComponent from './OuterComponent.svelte';
  import MyComponent from './MyComponent.svelte';
</script>
 
<Meta title="MyComponent" component={MyComponent} />
 
<Template let:args>
  <OuterComponent>
    <MyComponent />
  </OuterComponent>
</Template>
 
<Story name="Default" />

如果你需要对 Template 组件的支持，该插件提供了一个功能标志用于向后兼容。欲了解更多信息，请参阅配置选项。

将 Story slots 转换为 snippets

随着 Svelte 弃用 slot 并引入可重用的snippets，该插件也引入了对此功能的支持，使你能够扩展 Story 组件并提供自定义 snippet 来为 Stories 提供动态内容。Story 接受 template snippet，使你能够在不丢失响应性的情况下创建动态 Stories。

MyComponent.stories.svelte

<script>
  import { defineMeta } from '@storybook/addon-svelte-csf';
 
  import MyComponent from './MyComponent.svelte';
 
  const { Story } = defineMeta({
    component: MyComponent,
  });
</script>
 
<Story name="Default" args={{ exampleProperty: true }}>
  {#snippet template(args)}
    <MyComponent {...args}>Reactive component</MyComponent>
  {/snippet}
</Story>

标签支持

如果你之前通过 autodocs story 属性启用了自动文档生成，你必须将其替换为tags。此属性允许你根据特定条件对 Stories 进行分类和过滤，并根据应用于 Stories 的标签生成文档。

MyComponent.stories.svelte

<script>
  import { Meta, Template, Story } from '@storybook/addon-svelte-csf';
 
  import MyComponent from './MyComponent.svelte';
</script>
 
<Meta title="MyComponent" component={MyComponent} />
 
<Template let:args>
  <MyComponent {...args} />
</Template>
 
<Story name="Default" autodocs />

API

选项

如果需要，你可以传递一个 options 对象进行额外配置

.storybook/main.ts

import type { StorybookConfig } from '@storybook/svelte-vite';
 
const config: StorybookConfig = {
  // ...
  framework: {
    name: '@storybook/svelte-vite',
    options: {
      // ...
    },
  },
};
 
export default config;

可用选项如下

`builder`

类型: Record<string, any>

配置框架的构建器选项。对于此框架，可用选项可以在Vite 构建器文档中找到。