乐趣区

关于前端:Docgeni-21-正式发布

往期回顾

以下是 Docgeni 从 2021-05-20 正式开源到目前公布的大版本更新:

Docgeni,开箱即用的 Angular 组件文档工具

喜迎国庆, Docgeni 1.1.0 正式公布!

Docgeni 2.0 公布,开启自动化

那么自 2022 年 11 月公布 2.0 后,Docgeni 应用曾经变得越来越简略,然而这条自动化之路并未进行,此次介绍一下 2.1.0 版本带来了一些新的个性:

如果你还没有给 Docgeni 仓储一个星星,请点击 docgeni 进入仓储后点击 Star。
示例反对独立组件

Angular 在 v14 版本正式推出了独立组件(无模块组件),v15 版本对于独立组件周边的生态进行了欠缺,那么能够说 15 版本后能够释怀的应用独立组件这一个性,对于之前的版本来说,所有的组件须要挂载在一个 NgModule 上,所以 Docgeni 写示例组件的时候须要定义一个 NgModule,那么为了简化手动申明示例组件的繁琐,同时又反对导入第三方模块以及提供 Providers,2.0 版本在 module.ts 新增了简化的写法:

> // module.ts
> import {CommonModule} from '@angular/common';
> import {AlibButtonModule} from '@docgeni/alib/button';
> 援用
> export default {>   imports: [ CommonModule, AlibButtonModule],
>   providers: [],
>   declarations: []
> }

这样 Docgeni 会主动依据 export default {} 的元数据主动生成 NgModule,并把所有示例组件放在模块的 declarations 中,那么 Angular 反对独立组件后,连定义一个 module.ts 都能够省略,所有的示例组件采纳独立组件即可:

import {Component, OnInit} from '@angular/core';
import {CommonModule} from '@angular/common';
import {AlibButtonModule} from '@docgeni/alib/button';

@Component({
    selector: 'alib-button-basic-example',
    templateUrl: './basic.component.html',
    styleUrls: ['./basic.component.scss'],
    standalone: true,
    imports: [AlibButtonModule, CommonModule]
})
export class AlibButtonBasicExampleComponent implements OnInit {constructor() {}

    ngOnInit(): void {}
}

如果你的类库曾经降级到 Angular 15 版本,举荐应用独立组件编写示例,查看更多点击 组件示例。

能够说独立组件在写组件示例和入门教学中的场景庸庸碌碌。

自定义组件反对独立组件

那么除了示例组件能够省略定义 module.ts 外,自定义组件此次也反对了独立组件,无需独自定义 module.ts申明导入的模块。

.docgeni/components/color 新增一个 color 组件:

import {CommonModule} from '@angular/common';
import {Component, ElementRef, Input, OnInit} from '@angular/core';
import {FormsModule} from '@angular/forms';
import {DocgeniBuiltInComponent} from '@docgeni/template';

@Component({
    selector: 'my-color',
    templateUrl: './color.component.html',
    standalone: true,
    imports: [FormsModule, CommonModule]
})
export class MyColorComponent extends DocgeniBuiltInComponent implements OnInit {@Input() set color(value: string) {this.hostElement.style.color = value;}

    constructor(elementRef: ElementRef<unknown>) {super(elementRef);
    }

    ngOnInit(): void {}
}

而后就能够在文档中插入 <my-color color="red">Color</my-color> 渲染自定义独立组件。

API 文档反对 Class 和 Interface

Docgeni 过来的版本只能生成 Angular 的组件 / 指令 / 服务 API 文档,然而在理论的场景中,往往是须要为一个类或者接口生成文档的,比方 Dialog 组件的参数配置,咱们只须要在对应的接口或者类正文中增加 @public 或者@publicApi 的标签即可,默认所有的 Class 和 Interface 是不生成文档的。

/**
 * Alib Dialog Config
 * @public
 * @order 20
 */
export interface AlibDialogConfig {
    /**
     * The ARIA role of the dialog element.
     * @default 'dialog'
     **/
    role?: DialogRole;

    /**
     * Position overrides.
     * @default top
     **/
    position?: OverlayPosition;

    /** Dialog size md, lg, sm*/
    size?: DialogSizes;
}

这样在 Dialog 组件的 API 文档中就会展现如下的接口文档:

对于 Class 的文档也是相似,同时咱们在定义 Class 或者 Interface 往往会应用继承,比方新增了一个 AbstractOverlayRef 抽象类,这个类会有 instanceonClose 形象函数,AlibDialogRef 类是继承上述的抽象类的,那么生成的 API 文档中会主动把父类的属性和参数都合并。

export abstract class AbstractOverlayRef<T> {
    /**
     * The instance of the dialog component.
     **/
    instance: T;

    abstract onClose(): void;}

/**
 * Alib Dialog Ref
 * @public
 * @order 30
 */
export abstract class AlibDialogRef<T = unknown, TResult = unknown> extends AbstractOverlayRef<T> {
    /**
     * Result of close dialog
     */
    result: TResult;

    /**
     * Close dialog
     */
    close(id?: string) {}}

最终生成的文档如下所示:

API 正文配置阐明

在此次版本中,新增了 API 正文标签文档,根本遵循了 TS Doc 正文标准,除个别自定义 Tag 外,点击 API 正文查看更多。

其余个性

除了独立组件和接口 / 类的 API 文档生成以外,2.1.0 还蕴含了如下个性:

  • 降级 Angular 站点到 v15 版本,2.1.0 版本只反对 Angular 15 版本
  • ng add @docgeni/cli 默认初始化类库配置的 apiMode 设置为 automatic
  • ng add @docgeni/cli 会依据类库的 rootDir 和 sourceRoot
  • 修复了文档内容对于表格、题目、代码段的款式影响示例的缺点
  • 修复 dg-doc-header h1 标签会和组件库的 h1 标签款式抵触的问题
  • 站点反对 tsconfig 设置 “strict”: true 严格模式
  • 站点反对 tsconfig 设置 “noImplicitOverride”: true

破坏性更改

在 2.1 版本中,Docgeni 不会主动解析类库 rootDir 下的文件夹为组件

  • 如果你的类库 rootDir 下的文件夹就是组件,须要在 include 配置中新增 ” 或者 ‘./’
  • 如果你的类库 rootDir 下的 src 文件夹下才是组件,须要在 include 配置中新增 ‘src’
  • 如果你的类库 rootDir 下的 src/lib 文件夹下才是组件,须要在 include 配置中新增 ‘src/lib’

对于咱们

PingCode 前端团队是一群酷爱开源,酷爱技术的小伙伴,除了 Docgeni 外,咱们团队还开源了多个我的项目:

  • ngx-planet:Angular 框架下性能最全面的微前端解决方案
  • slate-angular:Slate 富文本编辑器框架的 Angular 视图适配层,应用 Angular 轻松开发编辑器
  • ngx-gantt:最好用的 Angular 甘特图组件
  • @tethys/store:简略好用的 Angular 状态治理库
退出移动版