storybook-addon-source-link

此插件添加了在编辑器中打开故事或组件源代码的链接。

入门

要求

• Storybook 8.0 或更高版本

1. 安装插件。

npm install -D storybook-addon-source-link
# or
yarn add -D storybook-addon-source-link
# or
pnpm add -D storybook-addon-source-link

2. 在 Storybook 配置中注册插件。

然后，在 .storybook/main.js（或 .storybook/main.ts）中将其注册为插件。

// .storybook/main.ts
import type { StorybookConfig } from "@storybook/your-framework";

const config: StorybookConfig = {
  // ...rest of config
  addons: [
    // ...other addons
    "storybook-addon-source-link",
  ],
};

export default config;

3. （可选）配置插件。

您可以使用 .storybook/preview.ts 或 Story 的参数修改或添加链接。

import type { Preview } from "@storybook/react";
import {
  type SourceLinkParameter,
  getFileUrl,
} from "storybook-addon-source-link";

const preview: Preview = {
  parameters: {
    // ...other parameters
    sourceLink: {
      links: {
        // override addon's default link
        "story-vscode": ({ importPath, rootPath, isStaticBuild }) => {
          if (isStaticBuild) return undefined;
          if (!rootPath) return undefined;
          const fileUrl = getFileUrl(rootPath, importPath);
          const href = `vscode://${fileUrl.href}`;
          return {
            label: importPath.split("/").at(-1) ?? "",
            href,
            icon: "StorybookIcon",
          };
        },

        // add a new link type
        "story-github": ({ importPath, rootPath }) => {
          if (!rootPath) return undefined;
          const href = `https://github.com/elecdeer/storybook-addon-source-link/blob/-/packages/demo${importPath.replace(
            /^\./,
            ""
          )}`;
          return {
            label: importPath,
            href,
            icon: "GithubIcon",
          };
        },
      },
    } satisfies SourceLinkParameter,
  },
};

export default preview;

API

参数

此插件在 sourceLink 命名空间下向 Storybook 提供以下参数。

[!TIP] Storybook 参数可以在故事、组件和全局级别指定，并针对每个值进行合并。

https://storybook.org.cn/docs/writing-stories/parameters

链接

类型：{ [key: string]: LinkEntry | undefined | ((context: ResolveContext) => LinkEntry | undefined) }

如果返回 undefined，则不会添加链接。

• ResolveContext:
  • rootPath：源文件根目录的路径。例如 "/Users/username/project"。如果 isStaticBuild 为 true，则此值为 ""。
  • isStaticBuild：Storybook 是否静态构建。
  • type：条目的类型。"story" 或 "docs"。
  • importPath：源文件的路径。例如 "./src/stories/Button.tsx"
  • id：故事的 ID。例如 "example-button--primary"
  • title：故事或组件的标题。例如 "Example/Button"
  • name：故事的名称。例如 "Primary"
  • tags：故事的标签。例如 ["autodocs"]
• LinkEntry:
  • label：链接的标签。
  • href：链接的 URL。
  • icon： （可选）@storybook/icons 中的图标名称
  • type： （可选）链接的类型。
    • "link"：链接将在同一标签页中打开。
    • "linkBlank"： （默认）链接将在新标签页中打开。在链接中添加了 target="_blank"。
    • "copy"：链接将复制到剪贴板。
  • order： （可选）当指定 order 时，它将按升序排序。默认值为 0。

插件提供的预设设置

// preview.tsx

const preview: Preview = {
  parameters: {
    sourceLink: {
      links: {
        "component-vscode": ({ importPath, rootPath }) => {
          if (!rootPath) return undefined;
          const componentPath = importPath.replace(/\.stories\.tsx?$/, ".tsx");
          const componentFileUrl = getFileUrl(rootPath, componentPath);
          return {
            label: componentPath,
            href: `vscode://${componentFileUrl.href}`,
            icon: "VSCodeIcon",
          };
        },
        "story-vscode": ({ importPath, rootPath }) => {
          if (!rootPath) return undefined;
          const fileUrl = getFileUrl(rootPath, importPath);
          const href = `vscode://${fileUrl.href}`;
          return {
            label: importPath,
            href,
            icon: "VSCodeIcon",
          };
        },
        "addon-powered-by": {
          label: "Powered by addon-source-link",
          href: "https://github.com/elecdeer/storybook-addon-source-link",
          order: Number.MAX_SAFE_INTEGER,
          icon: "InfoIcon",
        },
      },
    } satisfies SourceLinkParameter,
  },
};