适用于 SvelteKit 的 Storybook

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

¥Storybook for SvelteKit is a framework that makes it easy to develop and test UI components in isolation for SvelteKit applications.

安装

¥Install

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

¥To install Storybook in an existing SvelteKit 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

• 

  SvelteKit ≥ 1.0

• 

  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).

配置

¥Configure

本节介绍 SvelteKit 支持和配置选项。

¥This section covers SvelteKit support and configuration options.

支持的功能

¥Supported features

所有 Svelte 语言功能均开箱即用，因为 Storybook 框架直接使用 Svelte 编译器。但是，SvelteKit 有一些不受支持的 Kit 特定模块。以下是 Storybook 中有效和无效功能的细分：

¥All Svelte language features are supported out of the box, as the Storybook framework uses the Svelte compiler directly. However, SvelteKit has some Kit-specific modules that aren't supported. Here's a breakdown of what will and will not work within Storybook:

如何模拟

¥How to mock

要模拟 SvelteKit 导入，你可以在 parameters.sveltekit_experimental 中定义它：

¥To mock a SvelteKit import you can define it within parameters.sveltekit_experimental:

<script module>
  import { defineMeta } from '@storybook/addon-svelte-csf';
 
  import MyComponent from './MyComponent.svelte';
 
  const { Story } = defineMeta({
    component: MyComponent,
  });
</script>
 
<Story
  name="MyStory"
  parameters={{
    sveltekit_experimental: {
      state: {
        page: {
          data: {
            test: 'passed',
          },
        },
        navigating: {
          to: {
            route: { id: '/storybook' },
            params: {},
            url: new URL('http://localhost/storybook'),
          },
        },
        updated: {
          current: true,
        },
      },
    },
  }}
/>

可用参数 在下面 API 部分中有记录。

¥The available parameters are documented in the API section, below.

模拟链接

¥Mocking links

默认的链接处理行为（例如，点击 <a href="..." /> 元素时）是将操作记录到 操作面板。

¥The default link-handling behavior (e.g., when clicking an <a href="..." /> element) is to log an action to the Actions panel.

你可以通过将对象分配给 parameters.sveltekit_experimental.hrefs 来覆盖此设置，其中键是表示 href 的字符串，值定义你的模拟。例如：

¥You can override this by assigning an object to parameters.sveltekit_experimental.hrefs, where the keys are strings representing an href, and the values define your mock. For example:

<script module>
  import { defineMeta } from '@storybook/addon-svelte-csf';
 
  import MyComponent from './MyComponent.svelte';
 
  const { Story } = defineMeta({
    component: MyComponent,
  });
</script>
 
<Story
  name="MyStory"
  parameters={{
    sveltekit_experimental: {
      hrefs: {
        '/basic-href': (to, event) => {
          console.log(to, event);
        },
        '/root.*': {
          callback: (to, event) => {
            console.log(to, event);
          },
          asRegex: true,
        },
      },
    },
  }}
/>

有关更多信息，请参阅 API 参考。

¥See the API reference for more information.

编写原生 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

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

¥If you initialized your project with the Sveltekit 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 的 SvelteKit 框架提供零配置支持。但是，你可以扩展 Storybook 配置文件（即 .storybook/main.js|ts）并提供其他插件选项。下面列出了可用的选项及其使用方法示例。

¥By default, the Svelte addon addon offers zero-config support for Storybook's SvelteKit 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

如何手动安装 SvelteKit 框架？

¥How do I manually install the SvelteKit framework?

首先，安装框架：

¥First, install the framework:

npm install --save-dev @storybook/sveltekit

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

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

import type { StorybookConfig } from '@storybook/sveltekit';
 
const config: StorybookConfig = {
  // ...
  framework: '@storybook/sveltekit', // 👈 Add this
  // svelteOptions: { ... }, 👈 Remove this
};
 
export default config;

最后，这些包现在要么已经过时，要么是 @storybook/sveltekit 的一部分，因此你不再需要直接依赖它们。你可以从项目中删除它们（npm uninstall、yarn remove、pnpm remove）：

¥Finally, these packages are now either obsolete or part of @storybook/sveltekit, so you no longer need to depend on them directly. You can remove them (npm uninstall, yarn remove, pnpm remove) from your project:

• @storybook/svelte-vite

• storybook-builder-vite

• @storybook/builder-vite

API

参数

¥Parameters

此框架在 sveltekit_experimental 命名空间下为 Storybook 贡献了以下 参数：

¥This framework contributes the following parameters to Storybook, under the sveltekit_experimental namespace:

forms

类型：{ enhance: () => void }

¥Type: { enhance: () => void }

为 $app/forms 模块提供模拟。

¥Provides mocks for the $app/forms module.

forms.enhance

类型：() => void

¥Type: () => void

提交带有 use:enhance 的表单时将调用的回调。

¥A callback that will be called when a form with use:enhance is submitted.

hrefs

类型：Record<[path: string], (to: string, event: MouseEvent) => void | { callback: (to: string, event: MouseEvent) => void, asRegex?: boolean }>

¥Type: Record<[path: string], (to: string, event: MouseEvent) => void | { callback: (to: string, event: MouseEvent) => void, asRegex?: boolean }>

如果你的代码中有一个 <a /> 标签，并且 href 属性与定义的一个或多个链接匹配（如果 asRegex 属性是 true，则视为基于正则表达式），则会调用相应的 callback。如果没有定义匹配的 hrefs，则将操作记录到 操作面板。有关示例，请参阅 模拟链接。

¥If you have an <a /> tag inside your code with the href attribute that matches one or more of the links defined (treated as regex based if the asRegex property is true) the corresponding callback will be called. If no matching hrefs are defined, an action will be logged to the Actions panel. See Mocking links for an example.

navigation

类型：参见 SvelteKit 文档

¥Type: See SvelteKit docs

为 $app/navigation 模块提供模拟。

¥Provides mocks for the $app/navigation module.

navigation.goto

类型：参见 SvelteKit 文档

¥Type: See SvelteKit docs

每当调用 goto 时将调用的回调。如果没有提供函数，则将操作记录到 操作面板。

¥A callback that will be called whenever goto is called. If no function is provided, an action will be logged to the Actions panel.

navigation.pushState

类型：参见 SvelteKit 文档

¥Type: See SvelteKit docs

每当调用 pushState 时将调用的回调。如果没有提供函数，则将操作记录到 操作面板。

¥A callback that will be called whenever pushState is called. If no function is provided, an action will be logged to the Actions panel.

navigation.replaceState

类型：参见 SvelteKit 文档

¥Type: See SvelteKit docs

每当调用 replaceState 时将调用的回调。如果没有提供函数，则将操作记录到 操作面板。

¥A callback that will be called whenever replaceState is called. If no function is provided, an action will be logged to the Actions panel.

navigation.invalidate

类型：参见 SvelteKit 文档

¥Type: See SvelteKit docs

每当调用 invalidate 时将调用的回调。如果没有提供函数，则将操作记录到 操作面板。

¥A callback that will be called whenever invalidate is called. If no function is provided, an action will be logged to the Actions panel.

navigation.invalidateAll

类型：参见 SvelteKit 文档

¥Type: See SvelteKit docs

每当调用 invalidateAll 时将调用的回调。如果没有提供函数，则将操作记录到 操作面板。

¥A callback that will be called whenever invalidateAll is called. If no function is provided, an action will be logged to the Actions panel.

navigation.afterNavigate

类型：参见 SvelteKit 文档

¥Type: See SvelteKit docs

将传递给 afterNavigate 函数的对象，该函数将在 onMount 事件触发时调用。

¥An object that will be passed to the afterNavigate function, which will be invoked when the onMount event fires.

stores

类型：参见 SvelteKit 文档

¥Type: See SvelteKit docs

为 $app/stores 模块提供模拟。

¥Provides mocks for the $app/stores module.

stores.navigating

类型：参见 SvelteKit 文档

¥Type: See SvelteKit docs

navigating 商店的部分版本。

¥A partial version of the navigating store.

stores.page

类型：参见 SvelteKit 文档

¥Type: See SvelteKit docs

page 商店的部分版本。

¥A partial version of the page store.

stores.updated

类型：boolean

¥Type: boolean

表示 updated 值的布尔值（你也可以访问 updated.check()，这将是无操作）。

¥A boolean representing the value of updated (you can also access updated.check() which will be a no-op).

state

类型：参见 SvelteKit 文档

¥Type: See SvelteKit docs

为 $app/state 模块提供模拟。

¥Provides mocks for the $app/state module.

state.navigating

类型：参见 SvelteKit 文档

¥Type: See SvelteKit docs

navigating 商店的部分版本。

¥A partial version of the navigating store.

state.page

类型：参见 SvelteKit 文档

¥Type: See SvelteKit docs

page 商店的部分版本。

¥A partial version of the page store.

state.updated

类型：{ current: boolean }

¥Type: { current: boolean }

表示 updated 当前值的对象。你还可以访问 updated.check()，但此操作不会执行任何操作。

¥An object representing the current value of updated. You can also access updated.check(), which will be a no-op.

选项

¥Options

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

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

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

可用选项包括：

¥The available options are:

builder

类型：Record<string, any>

¥Type: Record<string, any>

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

¥Configure options for the framework's builder. For Sveltekit, 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.