Storybook 在 Angular 项目中的完整使用指南-优快云博客

本文链接：https://blog.youkuaiyun.com/gitblog_00014/article/details/148323232

Storybook 在 Angular 项目中的完整使用指南

storybook 项目地址: https://gitcode.com/gh_mirrors/sto/storybook

前言

Storybook 是一个强大的前端工具，它允许开发者独立地构建、测试和展示 UI 组件。对于 Angular 开发者来说，Storybook 提供了专门的支持，使得在 Angular 生态系统中使用 Storybook 变得异常简单。本文将全面介绍如何在 Angular 项目中配置和使用 Storybook。

环境要求

在开始之前，请确保您的开发环境满足以下要求：

Angular 版本 ≥ 15.0 且 < 19.0
Webpack ≥ 5.0
Storybook ≥ 8.0

安装与初始化

全新项目安装

对于尚未集成 Storybook 的 Angular 项目，可以通过以下命令快速初始化：

npx storybook@latest init

执行此命令后，Storybook 会自动检测您的项目类型并完成基本配置。过程中会提示您选择是否启用 Compodoc 集成等选项。

已有 Storybook 项目升级

如果您的项目已经使用了旧版 Storybook，可以运行以下命令升级到最新版本：

npx storybook@latest upgrade

升级过程中，系统会提示您迁移到 @storybook/angular 框架。大多数情况下，自动迁移能够顺利完成所有必要的配置变更。

核心配置

Angular 构建器配置

Storybook 提供了专门的 Angular 构建器，需要在 angular.json 文件中进行配置：

{
  "projects": {
    "your-project": {
      "architect": {
        "storybook": {
          "builder": "@storybook/angular:start-storybook",
          "options": {
            "configDir": ".storybook",
            "browserTarget": "your-project:build",
            "port": 6006
          }
        },
        "build-storybook": {
          "builder": "@storybook/angular:build-storybook",
          "options": {
            "configDir": ".storybook",
            "browserTarget": "your-project:build",
            "outputDir": "dist/storybook/your-project"
          }
        }
      }
    }
  }
}

主配置文件

在 .storybook/main.js|ts 中，需要指定使用 Angular 框架：

export default {
  framework: {
    name: '@storybook/angular',
    options: {}
  }
};

运行与构建

配置完成后，可以通过以下命令操作 Storybook：

启动开发服务器：
```
ng run <your-project>:storybook
```
构建生产版本：
```
ng run <your-project>:build-storybook
```

构建产物默认输出到 dist/storybook/<your-project> 目录。

Compodoc 集成

Compodoc 是 Angular 项目的文档生成工具，Storybook 提供了无缝集成：

安装依赖：

npm install --save-dev @compodoc/compodoc

在 angular.json 中启用 Compodoc：

{
  "storybook": {
    "options": {
      "compodoc": true,
      "compodocArgs": ["-e", "json", "-d", "."]
    }
  }
}

在 .storybook/preview.js 中加载生成的文档：

import { setCompodocJson } from '@storybook/addon-docs/angular';
import docJson from '../documentation.json';
setCompodocJson(docJson);

关键装饰器

applicationConfig 装饰器

对于依赖全局提供者的组件（如 BrowserAnimationsModule），可以使用 applicationConfig 装饰器：

import { applicationConfig } from '@storybook/angular';
import { provideAnimations } from '@angular/platform-browser/animations';

export default {
  decorators: [
    applicationConfig({
      providers: [provideAnimations()]
    })
  ]
};

moduleMetadata 装饰器

为组件提供必要的 Angular 模块和依赖：

import { moduleMetadata } from '@storybook/angular';

export default {
  decorators: [
    moduleMetadata({
      imports: [/* 所需模块 */],
      declarations: [/* 组件声明 */],
      providers: [/* 服务提供者 */]
    })
  ]
};

常见问题解答

多项目工作区配置

对于包含多个 Angular 项目的工作区：

为每个项目创建独立的 .storybook 配置目录
在每个项目的 angular.json 中添加 Storybook 构建器配置
使用 Storybook 的组合功能将多个 Storybook 实例合并展示

构建器配置选项

常用的构建器配置选项包括：

| 选项 | 描述 | 示例 | |------|------|------| | browserTarget | 构建目标配置 | "example-project:builder:config" | | tsConfig | TypeScript 配置文件路径 | "./tsconfig.json" | | port | 开发服务器端口 | 6006 | | https | 启用 HTTPS | true | | styles | 全局样式文件 | ["src/styles.css"] |