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@latest 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 命名导出（例如 parameters）来定义 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>

Tags 支持

如果您启用了 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

选项

如果需要，您可以传递一个选项对象进行其他配置

.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 构建器文档中找到。

`docgen`

类型：boolean

默认：true

启用或禁用组件属性的自动文档生成。禁用时，Storybook 将在构建过程中跳过 docgen 处理步骤，这可以提高构建性能。

.storybook/main.ts

import type { StorybookConfig } from '@storybook/svelte-vite';
 
const config: StorybookConfig = {
  framework: {
    name: '@storybook/svelte-vite',
    options: {
      docgen: false, // Disable docgen for better performance
    },
  },
};
 
export default config;

何时禁用 docgen

禁用 docgen 可以提高大型项目的构建性能，但 argTypes 将不会自动推断，这将阻止 Controls 和 docs 等功能正常工作。要使用这些功能，您需要手动定义 argTypes。