ng-bootstrap组件文档自动化：使用Storybook展示组件

ng-bootstrap组件文档自动化：使用Storybook展示组件

【免费下载链接】ng-bootstrap Angular powered Bootstrap 项目地址: https://gitcode.com/gh_mirrors/ng/ng-bootstrap

项目概述

ng-bootstrap是基于Angular和Bootstrap CSS构建的组件库，提供了丰富的UI组件，如日期选择器(Datepicker)、模态框(Modal)、下拉菜单(Dropdown)等。项目采用模块化架构，各组件独立开发并维护，通过Angular CLI进行构建和测试。官方文档和演示站点由demo/目录提供支持，用户可通过DEVELOPER.md了解本地开发环境搭建流程。

组件结构与文档现状

核心组件模块

ng-bootstrap的组件源代码集中在src/目录下，每个组件拥有独立的子目录，例如：

• 日期选择器(Datepicker): src/datepicker/，包含datepicker.module.ts和样式文件datepicker.scss
• 模态框(Modal): src/modal/，核心逻辑在modal.ts
• 下拉菜单(Dropdown): src/dropdown/，入口文件为dropdown.module.ts

现有文档系统

项目当前通过以下方式展示组件：

1. 演示站点: 运行yarn demo启动本地服务器，访问http://localhost:4200查看组件示例
2. API文档: 由misc/generate-docs.ts自动生成，提取src/目录中的代码注释
3. 开发指南: DEVELOPER.md提供本地构建和测试流程

Storybook集成方案

环境准备

1. 安装Storybook
   在项目根目录执行以下命令：

   npx storybook@latest init --type angular
   

   该命令会自动检测Angular项目结构，安装依赖并生成配置文件。

2. 配置TypeScript路径
   修改.storybook/main.ts，添加组件路径映射：

   module.exports = {
     stories: ['../src/**/*.stories.mdx', '../src/**/*.stories.@(js|jsx|ts|tsx)'],
     addons: ['@storybook/addon-links', '@storybook/addon-essentials'],
     framework: {
       name: '@storybook/angular',
       options: {}
     },
     typescript: {
       check: true,
       checkOptions: {},
       reactDocgen: 'react-docgen-typescript',
       reactDocgenTypescriptOptions: {
         shouldExtractLiteralValuesFromEnum: true,
         propFilter: (prop) => (prop.parent ? !/node_modules/.test(prop.parent.fileName) : true),
       },
     },
   };
   

编写组件Story

以日期选择器(Datepicker) 为例，创建src/datepicker/datepicker.stories.ts：

import { componentWrapperDecorator, moduleMetadata } from '@storybook/angular';
import { NgbDatepickerModule } from './datepicker.module';
import { NgbDateStruct } from './ngb-date-struct';
import { Component } from '@angular/core';

@Component({
  template: `
    <div class="container p-3">
      <ngb-datepicker [(ngModel)]="model"></ngb-datepicker>
      <hr>
      <pre>Model: {{ model | json }}</pre>
    </div>
  `
})
class DatepickerDemoComponent {
  model: NgbDateStruct | null = { year: 2025, month: 10, day: 29 };
}

export default {
  title: 'Components/Datepicker',
  component: DatepickerDemoComponent,
  decorators: [
    moduleMetadata({
      imports: [NgbDatepickerModule],
    }),
    componentWrapperDecorator((story) => `<div class="p-4">${story}</div>`),
  ],
};

export const Basic = {};
export const Disabled = {
  parameters: {
    docs: {
      description: {
        story: '禁用状态的日期选择器'
      }
    }
  },
  render: () => ({
    template: `
      <div class="container p-3">
        <ngb-datepicker [(ngModel)]="model" [disabled]="true"></ngb-datepicker>
      </div>
    `,
    props: {
      model: { year: 2025, month: 10, day: 29 }
    }
  })
};

添加文档插件

安装Storybook文档插件以支持自动API生成：

yarn add -D @storybook/addon-docs

在.storybook/main.ts中注册插件：

addons: [
  '@storybook/addon-links',
  '@storybook/addon-essentials',
  '@storybook/addon-docs'  // 添加文档插件
]

自动化文档生成

集成现有文档工具

利用项目内置的misc/generate-docs.ts提取组件注释，通过自定义脚本转换为Storybook支持的MDX格式：

// scripts/convert-docs-to-mdx.ts
import { generateApiDocs } from '../misc/generate-docs';
import fs from 'fs';
import path from 'path';

const docs = generateApiDocs();
Object.entries(docs).forEach(([component, doc]) => {
  const mdxContent = `
import { Meta } from '@storybook/addon-docs';

<Meta title="API/${component}" />

# ${component} API

${doc}
  `;
  fs.writeFileSync(
    path.join(__dirname, `../src/${component}/${component}.api.mdx`),
    mdxContent.trim()
  );
});

在package.json中添加脚本：

"scripts": {
  "docs:generate": "ts-node scripts/convert-docs-to-mdx.ts",
  "storybook:build": "yarn docs:generate && build-storybook"
}

视觉测试集成

结合Playwright进行组件视觉测试，创建src/datepicker/datepicker.stories.e2e.ts：

import { test, expect } from '@playwright/test';

test.describe('Datepicker Stories', () => {
  test('Basic story renders correctly', async ({ page }) => {
    await page.goto('http://localhost:6006/?path=/story/components-datepicker--basic');
    await expect(page.locator('ngb-datepicker')).toHaveScreenshot('datepicker-basic.png');
  });
});

部署与维护

本地开发流程

1. 启动Storybook

   yarn storybook
   

   访问http://localhost:6006查看组件文档

2. 构建静态站点

   yarn storybook:build
   

   输出文件位于storybook-static目录，可部署至GitHub Pages或企业内部服务器。

持续集成配置

修改.github/workflows/ci.yml，添加Storybook构建步骤：

jobs:
  storybook:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: 20
          cache: 'yarn'
      - run: yarn install --frozen-lockfile
      - run: yarn storybook:build
      - name: Upload artifact
        uses: actions/upload-artifact@v4
        with:
          name: storybook
          path: storybook-static

项目资源导航

• 核心组件: src/
  • 日期选择器: src/datepicker/
  • 模态框: src/modal/
  • 下拉菜单: src/dropdown/
• 开发文档: DEVELOPER.md
• 演示站点: demo/
• API生成工具: misc/generate-docs.ts
• 测试应用: e2e-app/src/app/datepicker/

通过Storybook集成，ng-bootstrap实现了组件开发与文档维护的无缝衔接，开发人员可在同一环境中迭代组件功能与使用示例，提升团队协作效率。

【免费下载链接】ng-bootstrap Angular powered Bootstrap 项目地址: https://gitcode.com/gh_mirrors/ng/ng-bootstrap