Storybook 组合

Composition 允许你浏览可通过本地 Storybook 中的 URL 访问的任何 Storybook 中的组件。无论视图层、技术堆栈或依赖如何，你都可以编写任何 Storybook 在线发布 或在本地运行。

¥Composition allows you to browse components from any Storybook accessible via URL inside your local Storybook. You can compose any Storybook published online or running locally no matter the view layer, tech stack, or dependencies.

你会在侧边栏中看到编写的 Storybook 故事以及你自己的故事。这解锁了团队经常遇到的常见工作流程：

¥You’ll see the composed Storybook’s stories in the sidebar alongside your own. This unlocks common workflows that teams often struggle with:

• 👩‍💻 UI 开发者无需在 Storybook 之间切换即可快速参考现有技术。

  ¥👩‍💻 UI developers can quickly reference prior art without switching between Storybooks.

• 🎨 设计系统可以通过将自己编写到用户的 Storybook 中来扩大采用范围。

  ¥🎨 Design systems can expand adoption by composing themselves into their users’ Storybooks.

• 🛠 前端平台可以审核组件在项目中的使用方式。

  ¥🛠 Frontend platform can audit how components are used across projects.

• 📚 在一个地方查看具有不同技术堆栈的多个 Storybook

  ¥📚 View multiple Storybooks with different tech stacks in one place

编写已发布的 Storybook

¥Compose published Storybooks

在你的 .storybook/main.js|ts 文件中添加一个 refs 字段，其中包含有关参考 Storybook 的信息。传递静态构建的 Storybook 的 URL。

¥In your .storybook/main.js|ts file add a refs field with information about the reference Storybook. Pass in a URL to a statically built Storybook.

// 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)'],
  refs: {
    'design-system': {
      title: 'Storybook Design System',
      url: 'https://master--5ccbc373887ca40020446347.chromatic.com/',
      expanded: false, // Optional, true by default,
      sourceUrl: 'https://github.com/storybookjs/storybook', // Optional
    },
  },
};
 
export default config;

编写本地 Storybook

¥Compose local Storybooks

你还可以编写在本地运行的多个 Storybook。例如，如果你有一个在不同端口上运行的 React Storybook 和一个 Angular Storybook，你可以更新配置文件（即 .storybook/main.js|ts）并按如下方式引用它们：

¥You can also compose multiple Storybooks that are running locally. For instance, if you have a React Storybook and an Angular Storybook running on different ports, you can update your configuration file (i.e., .storybook/main.js|ts) and reference them as follows:

// 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)'],
  refs: {
    react: {
      title: 'React',
      url: 'http://localhost:7007',
    },
    angular: {
      title: 'Angular',
      url: 'http://localhost:7008',
    },
  },
};
 
export default config;

添加此配置将把 React 和 Angular Storybooks 合并到你当前的配置中。当发生上述任一更改时，你都会看到自动应用的更改。使你能够同步开发两个框架。

¥Adding this configuration will combine React and Angular Storybooks into your current one. You’ll see the changes being applied automatically when either of these changes. Enabling you to develop both frameworks in sync.

按环境编写 Storybook

¥Compose Storybooks per environment

你还可以根据当前开发环境（例如，开发、登台、生产）编写 Storybook。例如，如果你正在处理的项目已经有一个已发布的 Storybook，但还包含一个尚未发布的具有提示功能的版本，你可以据此调整构图。例如：

¥You can also compose Storybooks based on the current development environment (e.g., development, staging, production). For instance, if the project you're working on already has a published Storybook but also includes a version with cutting-edge features not yet released, you can adjust the composition based on that. For example:

// 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)'],
 
  // 👇 Retrieve the current environment from the configType argument
  refs: (config, { configType }) => {
    if (configType === 'DEVELOPMENT') {
      return {
        react: {
          title: 'Composed React Storybook running in development mode',
          url: 'http://localhost:7007',
        },
        angular: {
          title: 'Composed Angular Storybook running in development mode',
          url: 'http://localhost:7008',
        },
      };
    }
    return {
      react: {
        title: 'Composed React Storybook running in production',
        url: 'https://your-production-react-storybook-url',
      },
      angular: {
        title: 'Composed Angular Storybook running in production',
        url: 'https://your-production-angular-storybook-url',
      },
    };
  },
};
 
export default config;

故障排除

¥Troubleshooting

Storybook 组合不适用于我的项目

¥Storybook composition is not working with my project

如果你正在使用过时的 Storybook 版本或有项目特定要求阻止你将 Storybook 更新到最新版本，你可以依靠 Storybook CLI 在部署 Storybook 时生成 index.json 文件。例如：

¥If you're working with an outdated Storybook version or have a project-specific requirement that prevents you from updating your Storybook to the latest version, you can rely on the Storybook CLI to generate the index.json file when you deploy your Storybook. For example:

npx storybook@7.5.3 extract