storybook-addon-source-link

此擴充功能會新增連結，以便在您的編輯器中開啟 story 或元件的原始碼。

開始使用

需求

• 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

參數

此擴充功能在 Storybook 中貢獻了以下參數，位於 sourceLink 命名空間下。

[!TIP] Storybook 參數可以在 story、元件和全域層級指定，並且會針對每個值進行合併。

https://storybook.dev.org.tw/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：story 的 ID。例如："example-button--primary"
  • title：story 或元件的標題。例如："Example/Button"
  • name：story 的名稱。例如："Primary"
  • tags：story 的標籤。例如：["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,
  },
};