85,947
文档
Storybook 文档

indexers

(⚠️ 实验性功能)

虽然此功能是实验性的，但必须通过 experimental_indexers 属性在 StorybookConfig 中指定。

父级：main.js|ts 配置

类型：(existingIndexers: Indexer[]) => Promise<Indexer[]>

Indexers 负责构建 Storybook 的 stories 索引——所有 stories 的列表以及其元数据的子集，如 id、title、tags 等。索引可以在你的 Storybook 的 /index.json 路由中读取。

indexers API 是一个高级功能，允许你自定义 Storybook 的 indexers，它决定了 Storybook 如何索引和解析文件到 story 条目中。这为如何编写 stories 增加了更多的灵活性，包括 stories 以何种语言定义或从何处获取 stories。

它们被定义为一个返回完整 indexers 列表的函数，包括现有的 indexers。这允许你将自己的 indexer 添加到列表中，或替换现有的 indexer。

.storybook/main.ts
// Replace your-framework with the framework you are using (e.g., react-webpack5, vue3-vite)
import type { StorybookConfig } from '@storybook/your-framework';
 
const config: StorybookConfig = {
  framework: '@storybook/your-framework',
  stories: [
    '../src/**/*.mdx',
    '../src/**/*.stories.@(js|jsx|mjs|ts|tsx)',
    // 👇 Make sure files to index are included in `stories`
    '../src/**/*.custom-stories.@(js|jsx|ts|tsx)',
  ],
  experimental_indexers: async (existingIndexers) => {
    const customIndexer = {
      test: /\.custom-stories\.[tj]sx?$/,
      createIndex: async (fileName) => {
        // See API and examples below...
      },
    };
    return [...existingIndexers, customIndexer];
  },
};
 
export default config;

除非你的 indexer 正在做一些相对简单的事情（例如，使用不同的命名约定索引 stories），否则除了索引文件之外，你可能还需要将其转译为 CSF，以便 Storybook 可以在浏览器中读取它们。

Indexer

类型

{
  test: RegExp;
  createIndex: (fileName: string, options: IndexerOptions) => Promise<IndexInput[]>;
}

指定要索引哪些文件以及如何将它们作为 stories 索引。

test

（必需）

类型：RegExp

针对包含在 stories 配置中的文件名运行的正则表达式，应匹配由此 indexer 处理的所有文件。

createIndex

（必需）

类型：(fileName: string, options: IndexerOptions) => Promise<IndexInput[]>

接受单个 CSF 文件并返回要索引的条目列表的函数。

fileName

类型：string

用于创建要索引的条目的 CSF 文件的名称。

IndexerOptions

类型

{
  makeTitle: (userTitle?: string) => string;
}

用于索引文件的选项。

makeTitle

类型：(userTitle?: string) => string

一个函数，它接受用户提供的标题，并返回索引条目的格式化标题，该标题用于侧边栏。如果未提供用户标题，则会根据文件名和路径自动生成一个标题。

有关示例用法，请参阅 IndexInput.title。

IndexInput

类型

{
  exportName: string;
  importPath: string;
  type: 'story';
  rawComponentPath?: string;
  metaId?: string;
  name?: string;
  tags?: string[];
  title?: string;
  __id?: string;
}

表示要添加到 stories 索引的 story 的对象。

exportName

（必需）

类型：string

对于每个 IndexInput，indexer 将添加此导出（来自 importPath 中找到的文件）作为索引中的条目。

importPath

（必需）

类型：string

要从中导入的文件，例如 CSF 文件。

被索引的 fileName 很可能不是 CSF，在这种情况下，你将需要将其转译为 CSF，以便 Storybook 可以在浏览器中读取它。

type

（必需）

类型：'story'

条目的类型。

rawComponentPath

类型：string

提供 meta.component 的文件的原始路径/包（如果存在）。

metaId

类型：string

默认值：从 title 自动生成

定义条目元数据的自定义 ID。

如果指定，CSF 文件中的 export default (meta)必须具有相应的 id 属性，才能正确匹配。

name

类型：string

默认值：从 exportName 自动生成

条目的名称。

tags

类型：string[]

用于在 Storybook 及其工具中过滤条目的标签。

title

类型：string

默认值：从 importPath 的默认导出自动生成

确定条目在侧边栏中的位置。

大多数情况下，你不应指定标题，以便你的 indexer 使用默认的命名行为。当指定标题时，你必须使用 IndexerOptions 中提供的 makeTitle 函数，以同样使用此行为。例如，这是一个 indexer，它仅将 "Custom" 前缀附加到从文件名派生的标题

.storybook/main.ts
// Replace your-framework with the framework you are using (e.g., react-webpack5, vue3-vite)
import type { StorybookConfig } from '@storybook/your-framework';
import type { Indexer } from '@storybook/types';
 
const combosIndexer: Indexer = {
  test: /\.stories\.[tj]sx?$/,
  createIndex: async (fileName, { makeTitle }) => {
    // 👇 Grab title from fileName
    const title = fileName.match(/\/(.*)\.stories/)[1];
 
    // Read file and generate entries ...
    const entries = [];
 
    return entries.map((entry) => ({
      type: 'story',
      // 👇 Use makeTitle to format the title
      title: `${makeTitle(title)} Custom`,
      importPath: fileName,
      exportName: entry.name,
    }));
  },
};
 
const config: StorybookConfig = {
  framework: '@storybook/your-framework',
  stories: ['../src/**/*.mdx', '../src/**/*.stories.@(js|jsx|ts|tsx)'],
  experimental_indexers: async (existingIndexers) => [...existingIndexers, combosIndexer],
};
 
export default config;
__id

类型：string

默认值：从 title/metaId 和 exportName 自动生成

定义条目的 story 的自定义 ID。

如果指定，CSF 文件中的 story 必须具有相应的 __id 属性，才能正确匹配。

仅在你需要覆盖自动生成的 ID 时使用此选项。

转译为 CSF

IndexInput 中的 importPath 的值必须解析为 CSF 文件。然而，大多数自定义 indexers 仅在输入不是 CSF 时才是必要的。因此，你可能需要将输入转译为 CSF，以便 Storybook 可以在浏览器中读取它并渲染你的 stories。

将自定义源格式转译为 CSF 超出了本文档的范围。这种转译通常在构建器级别完成（Vite 和/或 Webpack），我们建议使用 unplugin 为多个构建器创建插件。

通用架构如下所示：

Architecture diagram showing how a custom indexer indexes stories from a source file

  1. 使用 stories 配置，Storybook 查找与你的 indexer 的 test 属性匹配的所有文件
  2. Storybook 将每个匹配的文件传递给你的 indexer 的 createIndex 函数，该函数使用文件内容生成并返回要添加到索引的索引条目（stories）列表
  3. 索引填充 Storybook UI 中的侧边栏

Architecture diagram showing how a build plugin transforms a source file into CSF

  1. 在 Storybook UI 中，用户导航到与 story ID 匹配的 URL，并且浏览器请求索引条目的 importPath 属性指定的 CSF 文件
  2. 回到服务器，你的构建器插件将源文件转译为 CSF，并将其提供给客户端
  3. Storybook UI 读取 CSF 文件，导入 exportName 指定的 story，并渲染它

让我们看一个例子，了解这可能如何工作。

首先，这是一个非 CSF 源文件的示例：

// Button.variants.js|ts
 
import { variantsFromComponent, createStoryFromVariant } from '../utils';
import { Button } from './Button';
 
/**
 * Returns raw strings representing stories via component props, eg.
 * 'export const PrimaryVariant = {
 *    args: {
 *      primary: true
 *    },
 *  };'
 */
export const generateStories = () => {
  const variants = variantsFromComponent(Button);
  return variants.map((variant) => createStoryFromVariant(variant));
};

构建器插件随后会：

  1. 接收并读取源文件
  2. 导入导出的 generateStories 函数
  3. 运行该函数以生成 stories
  4. 将 stories 写入 CSF 文件

生成的 CSF 文件随后将被 Storybook 索引。它看起来像这样：

// virtual:Button.variants.js|ts
 
import { Button } from './Button';
 
export default {
  component: Button,
};
 
export const Primary = {
  args: {
    primary: true,
  },
};

示例

自定义 indexers 的一些示例用法包括：

从 fixture 数据或 API 端点动态生成 stories

此 indexer 基于 JSON fixture 数据为组件生成 stories。它在项目中查找 *.stories.json 文件，将它们添加到索引，并分别将其内容转换为 CSF。

.storybook/main.ts
// Replace your-framework with the framework you are using (e.g., react-webpack5, vue3-vite)
import type { StorybookConfig } from '@storybook/your-framework';
import type { Indexer } from '@storybook/types';
 
import fs from 'fs/promises';
 
const jsonStoriesIndexer: Indexer = {
  test: /stories\.json$/,
  createIndex: async (fileName) => {
    const content = JSON.parse(fs.readFileSync(fileName));
 
    const stories = generateStoryIndexesFromJson(content);
 
    return stories.map((story) => ({
      type: 'story',
      importPath: `virtual:jsonstories--${fileName}--${story.componentName}`,
      exportName: story.name,
    }));
  },
};
 
const config: StorybookConfig = {
  framework: '@storybook/your-framework',
  stories: [
    '../src/**/*.mdx',
    '../src/**/*.stories.@(js|jsx|mjs|ts|tsx)',
    // 👇 Make sure files to index are included in `stories`
    '../src/**/*.stories.json',
  ],
  experimental_indexers: async (existingIndexers) => [...existingIndexers, jsonStoriesIndexer],
};
 
export default config;

一个输入 JSON 文件示例可能如下所示：

{
  "Button": {
    "componentPath": "./button/Button.jsx",
    "stories": {
      "Primary": {
        "args": {
          "primary": true
        },
      "Secondary": {
        "args": {
          "primary": false
        }
      }
    }
  },
  "Dialog": {
    "componentPath": "./dialog/Dialog.jsx",
    "stories": {
      "Closed": {},
      "Open": {
        "args": {
          "isOpen": true
        }
      },
    }
  }
}

然后，构建器插件将需要将 JSON 文件转换为常规 CSF 文件。这种转换可以使用类似于以下的 Vite 插件完成：

// vite-plugin-storybook-json-stories.ts
 
import type { PluginOption } from 'vite';
import fs from 'fs/promises';
 
function JsonStoriesPlugin(): PluginOption {
  return {
    name: 'vite-plugin-storybook-json-stories',
    load(id) {
      if (!id.startsWith('virtual:jsonstories')) {
        return;
      }
 
      const [, fileName, componentName] = id.split('--');
      const content = JSON.parse(fs.readFileSync(fileName));
 
      const { componentPath, stories } = getComponentStoriesFromJson(content, componentName);
 
      return `
        import ${componentName} from '${componentPath}';
 
        export default { component: ${componentName} };
 
        ${stories.map((story) => `export const ${story.name} = ${story.config};\n`)}
      `;
    },
  };
}
使用替代 API 生成 stories

你可以使用自定义 indexer 和构建器插件来创建你的 API，以定义扩展 CSF 格式的 stories。要了解更多信息，请参阅以下 概念验证，以设置自定义 indexer 来动态生成 stories。它包含支持此类功能所需的一切，包括 indexer、Vite 插件和 Webpack 加载器。

在非 JavaScript 语言中定义 stories

自定义 indexers 可以用于一个高级目的：以任何语言（包括模板语言）定义 stories，并将文件转换为 CSF。要查看实际应用示例，你可以参考 @storybook/addon-svelte-csf 用于 Svelte 模板语法，以及 storybook-vue-addon 用于 Vue 模板语法。

从 URL 集合添加侧边栏链接

indexer API 足够灵活，可以让你处理任意内容，只要你的框架工具可以将该内容中的导出转换为它可以运行的实际 stories。这个高级示例演示了如何创建一个自定义 indexer 来处理 URL 集合，从每个页面提取标题和 URL，并在 UI 中将其渲染为侧边栏链接。使用 Svelte 实现，它可以适应任何框架。

首先创建 URL 集合文件（即，src/MyLinks.url.js），其中 URL 列表列为命名导出。indexer 将使用导出名称作为 story 标题，并将值作为唯一标识符。

MyLinks.url.js
export default {};
 
export const DesignTokens = 'https://www.designtokens.org/';
export const CobaltUI = 'https://cobalt-ui.pages.dev/';
export const MiseEnMode = 'https://mode.place/';
export const IndexerAPI = 'https://github.com/storybookjs/storybook/discussions/23176';

调整你的 Vite 配置文件以包含补充 indexer 的自定义插件。这将允许 Storybook 处理 URL 集合文件并将其作为 stories 导入。

vite.config.ts
import * as acorn from 'acorn';
import * as walk from 'acorn-walk';
import { defineConfig, type Plugin } from 'vite';
import { svelte } from '@sveltejs/vite-plugin-svelte';
 
function StorybookUrlLinksPlugin(): Plugin {
  return {
    name: 'storybook-url-links',
    async transform(code: string, id: string) {
      if (id.endsWith('.url.js')) {
        const ast = acorn.parse(code, {
          ecmaVersion: 2020,
          sourceType: 'module',
        });
 
        const namedExports: string[] = [];
        let defaultExport = 'export default {};';
 
        walk.simple(ast, {
          // Extracts the named exports, those represent our stories, and for each of them, we'll return a valid Svelte component.
          ExportNamedDeclaration(node: acorn.ExportNamedDeclaration) {
            if (
              node.declaration &&
              node.declaration.type === 'VariableDeclaration'
            ) {
              node.declaration.declarations.forEach((declaration) => {
                if ('name' in declaration.id) {
                  namedExports.push(declaration.id.name);
                }
              });
            }
          },
          // Preserve our default export.
          ExportDefaultDeclaration(node: acorn.ExportDefaultDeclaration) {
            defaultExport = code.slice(node.start, node.end);
          },
        });
 
        return {
          code: `
            import RedirectBack from '../../.storybook/components/RedirectBack.svelte';
            ${namedExports
              .map(
                (name) =>
                  `export const ${name} = () => new RedirectBack();`
              )
              .join('\n')}
            ${defaultExport}
          `,
          map: null,
        };
      }
    },
  };
}
 
export default defineConfig({
  plugins: [StorybookUrlLinksPlugin(), svelte()],
})

更新你的 Storybook 配置（即，.storybook/main.js|ts）以包含自定义 indexer。

.storybook/main.js|ts
import type { StorybookConfig } from '@storybook/svelte-vite';
import type { Indexer } from '@storybook/types';
 
const urlIndexer: Indexer = {
  test: /\.url\.js$/,
  createIndex: async (fileName, { makeTitle }) => {
    const fileData = await import(fileName);
 
    return Object.entries(fileData)
      .filter(([key]) => key != 'default')
      .map(([name, url]) => {
        return {
          type: 'docs',
          importPath: fileName,
          exportName: name,
          title: makeTitle(name)
            .replace(/([a-z])([A-Z])/g, '$1 $2')
            .trim(),
          __id: `url--${name}--${encodeURIComponent(url as string)}`,
          tags: ['!autodocs', 'url']
        };
      });
  }
};
 
const config: StorybookConfig = {
  stories: ['../src/**/*.stories.@(js|ts|svelte)', '../src/**/*.url.js'],
  framework: {
    name: '@storybook/svelte-vite',
    options: {},
  },
  experimental_indexers: async (existingIndexers) => [urlIndexer, ...existingIndexers]
};
export default config;

添加 Storybook UI 配置文件（即，.storybook/manager.js|ts）以在 UI 中将索引的 URL 渲染为侧边栏链接

.storybook/manager.ts
import { addons } from '@storybook/manager-api';
 
import SidebarLabelWrapper from './components/SidebarLabelWrapper.tsx';
 
addons.setConfig({
    sidebar: {
      renderLabel: (item) => SidebarLabelWrapper({ item }),
    },
});

此示例的代码和实时演示可在 StackBlitz 上找到。

此页内容是否对您有帮助？
✍️ 在 Github 上编辑