使用 Vite 的 Svelte Storybook

Storybook for Svelte & Vite 是一个 framework，它可以轻松地为使用 Svelte 和 Vite 构建的应用单独开发和测试 UI 组件。

¥Storybook for Svelte & Vite is a framework that makes it easy to develop and test UI components in isolation for applications using Svelte built with Vite.

安装

¥Install

要在现有的 Svelte 项目中安装 Storybook，请在项目根目录下运行以下命令：

¥To install Storybook in an existing Svelte project, run this command in your project's root directory:

npm create storybook@latest

接下来，你可以开始使用 写故事、运行测试 和 组件文档。要更好地控制安装过程，请参阅 安装指南。

¥You can then get started writing stories, running tests and documenting your components. For more control over the installation process, refer to the installation guide.

要求

¥Requirements

• 

  Svelte ≥ 5

• 

  Vite ≥ 5

运行 Storybook

¥Run Storybook

要为特定项目运行 Storybook，请运行以下命令：

¥To run Storybook for a particular project, run the following:

npm run storybook

要构建 Storybook，请运行：

¥To build Storybook, run:

npm run build-storybook

你将在配置的 outputDir（默认为 storybook-static）中找到输出。

¥You will find the output in the configured outputDir (default is storybook-static).

编写原生 Svelte 故事

¥Writing native Svelte stories

Storybook 提供了由社区维护的 Svelte addon，使你可以使用模板语法为 Svelte 组件编写故事。

¥Storybook provides a Svelte addon maintained by the community, enabling you to write stories for your Svelte components using the template syntax.

设置

¥Setup

如果你使用 Svelte 框架初始化项目，则该插件已为你安装并配置完毕。但是，如果你是从以前版本安装的 migrating，则需要执行其他步骤来启用此功能。

¥If you initialized your project with the Svelte framework, the addon has already been installed and configured for you. However, if you're migrating from a previous version, you'll need to take additional steps to enable this feature.

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

¥Run the following command to install the addon.

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

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

¥Update your Storybook configuration file (i.e., .storybook/main.js|ts) to enable support for this format.

// 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;

配置

¥Configure

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

¥By default, the Svelte addon offers zero-config support for Storybook's Svelte framework. However, you can extend your Storybook configuration file (i.e., .storybook/main.js|ts) and provide additional addon options. Listed below are the available options and examples of how to use them.

// 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;

升级到 Svelte CSF 插件 v5

¥Upgrade to Svelte CSF addon v5

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

¥With the Svelte 5 release, Storybook's Svelte CSF addon has been updated to support the new features. This guide will help you migrate to the latest version of the addon. Below is an overview of the major changes in version 5.0 and the steps needed to upgrade your project.

简化的故事 API

¥Simplified story API

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

¥If you are using the Meta component or the meta named export to define the story's metadata (e.g., parameters), you'll need to update your stories to use the new defineMeta function. This function returns an object with the required information, including a Story component that you must use to define your component stories.

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

Story 模板

¥Story templates

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

¥If you used the Template component to control how the component renders in the Storybook, this feature was replaced with built-in children support in the Story component, enabling you to compose components and define the UI structure directly in the story.

<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" />

故事片段插槽

¥Story slots to snippets

随着 Svelte 插槽的弃用和可复用 snippets 的引入，该插件也引入了对此功能的支持，允许你扩展 Story 组件并提供自定义代码片段，为你的故事提供动态内容。Story 接受 template 代码片段，允许你创建动态故事而不损失响应性。

¥With Svelte's slot deprecation and the introduction of reusable snippets, the addon also introduced support for this feature allowing you to extend the Story component and provide a custom snippet to provide dynamic content to your stories. Story accepts a template snippet, allowing you to create dynamic stories without losing reactivity.

<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 support

如果你启用了使用 autodocs 故事属性的自动文档生成功能，则必须将其替换为 tags。此属性允许你根据特定条件对故事进行分类和筛选，并根据应用于故事的标签生成文档。

¥If you enabled automatic documentation generation with the autodocs story property, you must replace it with tags. This property allows you to categorize and filter stories based on specific criteria and generate documentation based on the tags applied to the stories.

<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 />

常见问题

¥FAQ

如何手动安装 Svelte 框架？

¥How do I manually install the Svelte framework?

首先，安装框架：

¥First, install the framework:

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

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

¥Then, update your .storybook/main.js|ts to change the framework property:

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

API

选项

¥Options

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

¥You can pass an options object for additional configuration if needed:

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

可用选项包括：

¥The available options are:

builder

类型：Record<string, any>

¥Type: Record<string, any>

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

¥Configure options for the framework's builder. For this framework, available options can be found in the Vite builder docs.

docgen

类型：boolean

¥Type: boolean

默认：true

¥Default: true

启用或禁用组件属性的自动文档生成。禁用此选项后，Storybook 将在构建过程中跳过文档生成 (docgen) 处理步骤，从而提升构建性能。

¥Enables or disables automatic documentation generation for component properties. When disabled, Storybook will skip the docgen processing step during build, which can improve build performance.

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

何时禁用文档生成器 (docgen)？

¥When to disable docgen

禁用文档生成可以提高大型项目的构建性能，但 argTypes 将不会自动推断 会导致 控件 和 docs 等功能无法正常工作。要使用这些功能，需要使用 手动定义 argTypes。

¥Disabling docgen can improve build performance for large projects, but argTypes won't be inferred automatically, which will prevent features like Controls and docs from working as expected. To use those features, you will need to define argTypes manually.