Docgeni 2.1 正式发布

作者：PingCode研发中心

2023-04-23
江西
本文字数：2734 字
阅读完需：约 9 分钟

往期回顾

以下是 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.tsimport { 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 抽象类，这个类会有instance和onClose 抽象函数，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 状态管理库

发布于: 刚刚阅读数: 2

PingCode研发中心

关注

还未添加个人签名 2021-02-01 加入

还未添加个人简介

发布

暂无评论

创作场景

Docgeni 2.1 正式发布

往期回顾

示例支持独立组件

自定义组件支持独立组件

API 文档支持 Class 和 Interface

API 注释配置说明

其他特性

破坏性更改

关于我们

PingCode研发中心

评论