关于@delon包

  |   0 评论   |   0 浏览

ng-alain

转载请注明原出处,勘误请发送电子邮件

1.什么是 ng-alain?

ng-alain 是来自中国作者 卡色 开源出的一个企业级中后台前端/设计解决方案脚手架,秉承 Ant Design 的设计价值观,让 Angular 快速落地于企业生产实践中的一个高集成性框架。

其中提供了非常丰富的功能诸如

  • Dynamic Form
  • Antv/Echarts
  • Acl
  • Auth
  • Theme
  • Cache
  • Mock
  • Util (DeepCopy/TreeToArray 等等)

假如你对 Angular 有一些使用基础,那么使用起来会相当的得心应手。

假如你对 Angular 只有一些略微了解,那么也可以通过 ng-alain 提供的 CLI 快速的建立起一个可运行 Project 用来快速上手。

2.ng-alain 解析

  • 生成一个 ng-alain 项目首先需要安装 AngularCli
  • npm install @angular/cli@12.2.0
  • 其次使用 ng new my-project --style less --routing 创建名为 my-project 的纯 Angular 项目
  • 然后使用 ng-alainCLI 生成项目
  • ng add ng-alain
  • 最后使用 npm run start 启动项目
  • 或者直接前往预览地址

3.ng-alain 项目

“没有比浏览 angular.json 配置文件更能快速了解一个 angular 项目的方法了” -詹姆斯高斯林

{
  "$schema": "./node_modules/@angular/cli/lib/config/schema.json",
  "version": 1,
  "newProjectRoot": "projects",
  "projects": {
    "ng-alain": {
      "projectType": "application",
      "root": "",
      "sourceRoot": "src",
      "prefix": "app",
      "schematics": {
        "@schematics/angular:component": {
          "style": "less"
        },
        "@schematics/angular:application": {
          "strict": true
        }
      },
      "architect": {
        "build": {
          "builder": "@angular-devkit/build-angular:browser",
          "options": {
            "outputPath": "dist",
            "index": "src/index.html",
            "main": "src/main.ts",
            "tsConfig": "tsconfig.app.json",
            "polyfills": "src/polyfills.ts",
            "assets": ["src/assets", "src/favicon.ico"],
            "styles": ["src/styles.less"],
            "scripts": [],
            "allowedCommonJsDependencies": ["ajv", "ajv-formats"]
          },
          "configurations": {
            "production": {
              "fileReplacements": [
                {
                  "replace": "src/environments/environment.ts",
                  "with": "src/environments/environment.prod.ts"
                }
              ],
              "outputHashing": "all",
              "budgets": [
                {
                  "type": "initial",
                  "maximumWarning": "2mb",
                  "maximumError": "6mb"
                },
                {
                  "type": "anyComponentStyle",
                  "maximumWarning": "6kb",
                  "maximumError": "10kb"
                }
              ]
            },
            "development": {
              "buildOptimizer": false,
              "optimization": false,
              "vendorChunk": true,
              "extractLicenses": false,
              "sourceMap": true,
              "namedChunks": true
            }
          },
          "defaultConfiguration": "production"
        },
        "serve": {
          "builder": "@angular-devkit/build-angular:dev-server",
          "options": {
            "browserTarget": "ng-alain:build",
            "proxyConfig": "proxy.conf.json"
          },
          "configurations": {
            "production": {
              "browserTarget": "ng-alain:build:production"
            },
            "development": {
              "browserTarget": "ng-alain:build:development"
            }
          },
          "defaultConfiguration": "development"
        },
        "extract-i18n": {
          "builder": "@angular-devkit/build-angular:extract-i18n",
          "options": {
            "browserTarget": "ng-alain:build"
          }
        },
      ....

我们可以清晰的从 angular.json 中看出

  • build 部分
  • projects 中仅仅含有一个类型为 application 的项目 ng-alain
  • builder 编译器使用了默认的 @angular-devkit/build-angular:browser,当然还有许多其他的编译器,可以自行搜索使用。
  • builder 中的 options 指定了一些入口文件
  • 引入了 CommanJS: ajv,ajv-formatsajvJSON Schema 的一种验证器
  • build 中的 configuration 会使用 env.prod.ts 替换 env.ts
  • outputHashing 打包文件带有哈希值
  • serve 部分
  • serve 对应的命令为 ng serve,使用的 builder@angular-devkit/build-angular:dev-server,我们可以在 @angular-devikt 找到这个包,有一些配置参数和说明,刚刚 build 时使用的 browser,还有 app-shell 呦

找到了入口文件 index.html

<app-root></app-root>
  <div class="preloader">
    <div class="cs-loader">
      <div class="cs-loader-inner">
        <label> ●</label>
        <label> ●</label>
        <label> ●</label>
        <label> ●</label>
        <label> ●</label>
        <label> ●</label>
      </div>
    </div>
  </div>

比较重要的一部分

  • <app-root> ,这里是对 app.component.ts 的直接引用
  • 下面的 div 中使用 classcss 做了一个加载动画,可以理解成遮罩层,利用最先渲染 index.html,使用 css 将整个 webapp 遮盖住
  • index.html 结束

找到了入口文件 main.ts

preloaderFinished();

第九行调用了 preloaderFinished,这个函数是在 alain 的另一个基础项目 delon 中以基础包的形式出现的

export function preloaderFinished(): void {
  const body = document.querySelector('body')!;
  const preloader = document.querySelector('.preloader')!;

  body.style.overflow = 'hidden';

  function remove(): void {
    // preloader value null when running --hmr
    if (!preloader) return;
    preloader.addEventListener('transitionend', () => {
      preloader.className = 'preloader-hidden';
    });

    preloader.className += ' preloader-hidden-add preloader-hidden-add-active';
  }

  (window as NzSafeAny).appBootstrap = () => {
    setTimeout(() => {
      remove();
      body.style.overflow = '';
    }, 100);
  };
}
  • 写了之前说的遮罩层如何删除

  • 赋予 window 对象一个 appBootstrap 函数,用来进行调用 remove 删除掉 index.html 中的遮罩层

    if (environment.production) {
    enableProdMode();
    }

如果环境为 prod 模式那么开启 Prod 模式

platformBrowserDynamic()
  .bootstrapModule(AppModule, {
    defaultEncapsulation: ViewEncapsulation.Emulated,
    preserveWhitespaces: false
  })
  .then(res => {
    const win = window as NzSafeAny;
    if (win && win.appBootstrap) {
      win.appBootstrap();
    }
    return res;
  })
  .catch(err => console.error(err));

上面为 main.ts 中最后的内容

  • 引导 AppModule 启动
  • 启动完毕后调用 win 中存下的 remove 函数,删除遮罩层

@import '~@delon/theme/system/index';
@import '~@delon/abc/index';
@import '~@delon/chart/index';
@import '~@delon/theme/layout-default/style/index';
@import '~@delon/theme/layout-blank/style/index';

@import './styles/index';
@import './styles/theme';

style.less 中引入了一些 less 变量,以供全局 css 使用,这些 less 变量也是 @delon/theme 包中出现的,后续可能会看到


至此,除了 assets 静态资源目录,其余从 angular.json 找到的入口的启动过程梳理完毕,分别

  • 提供了模版
  • 提供了静态资源
  • 提供了 JS 启动模块
  • 提供了全局 CSS

3.1 项目配置

接下来看被 bootstrapAppModule

const LANG = {
  abbr: 'zh',
  ng: ngLang,
  zorro: zorroLang,
  date: dateLang,
  delon: delonLang
};
registerLocaleData(LANG.ng, LANG.abbr);
const LANG_PROVIDES = [
  { provide: LOCALE_ID, useValue: LANG.abbr },
  { provide: NZ_I18N, useValue: LANG.zorro },
  { provide: NZ_DATE_LOCALE, useValue: LANG.date },
  { provide: DELON_LOCALE, useValue: LANG.delon }
];

前面主要是本地化/i18n 的一些配置,通过 provide 键值对的方式注入到包里,使得第三方库使用 useValue 提供的值

const I18NSERVICE_PROVIDES = [{ provide: ALAIN_I18N_TOKEN, useClass: I18NService, multi: false }];

当然除了使用 useValue 的方式,还可以使用 useClass

export const ALAIN_I18N_TOKEN = new InjectionToken<AlainI18NService>('alainI18nToken', {
  providedIn: 'root',
  factory: () => new AlainI18NServiceFake()
});

上文的 ALAIN_I18N_TOKEN@delon/theme 中,接收一个 AlainI18nService类型 的 class

I18nService 继承自 AlainI18nBaseService,而 AlainI18nBaseService 又实现了 AlainI18NService 接口,所以类型匹配,这样我们就可以把自己的 class 传入第三方包中,第三方包注入 class 时调用的 function 就可以来自外部实际项目了


const GLOBAL_THIRD_MODULES: Array<Type<any>> = [BidiModule]

引入了一个左右布局切换的 Module,在 cdk 里,cdk@angular 提供的一个工具包


const INTERCEPTOR_PROVIDES = [
  { provide: HTTP_INTERCEPTORS, useClass: SimpleInterceptor, multi: true },
  { provide: HTTP_INTERCEPTORS, useClass: DefaultInterceptor, multi: true }
];

再往下就是这两个拦截器

  • Simple: 验证 token
  • Default: 处理错误信息

export function StartupServiceFactory(startupService: StartupService): () => Observable<void> {
  return () => startupService.load();
}
const APPINIT_PROVIDES = [
  StartupService,
  {
    provide: APP_INITIALIZER,
    useFactory: StartupServiceFactory,
    deps: [StartupService],
    multi: true
  }
];

重点,这里我称为 实际引导项目启动 的一个函数,这里作为整个项目声明周期的 初始化 周期,使用了 Angular 内置的 provide: APP_INITIALIZER 并返回了一个 Promise 函数 load

@Injectable()
export class StartupService {
  constructor(
    iconSrv: NzIconService,
    private menuService: MenuService,
    @Inject(ALAIN_I18N_TOKEN) private i18n: I18NService,
    private settingService: SettingsService,
    private aclService: ACLService,
    private titleService: TitleService,
    private httpClient: HttpClient
  ) {
    iconSrv.addIcon(...ICONS_AUTO, ...ICONS);
  }

  load(): Observable<void> {
    const defaultLang = this.i18n.defaultLang;
    return zip(this.i18n.loadLangData(defaultLang), this.httpClient.get('assets/tmp/app-data.json')).pipe(
      // 接收其他拦截器后产生的异常消息
      catchError(res => {
        console.warn(`StartupService.load: Network request failed`, res);
        return [];
      }),
      map(([langData, appData]: [Record<string, string>, NzSafeAny]) => {
        // setting language data
        this.i18n.use(defaultLang, langData);
        // 应用信息:包括站点名、描述、年份
        this.settingService.setApp(appData.app);
        // 用户信息:包括姓名、头像、邮箱地址
        this.settingService.setUser(appData.user);
        // ACL:设置权限为全量
        this.aclService.setFull(true);
        // 初始化菜单
        this.menuService.add(appData.menu);
        // 设置页面标题的后缀
        this.titleService.default = '';
        this.titleService.suffix = appData.app.name;
      })
    );
  }
}

以上代码初始化了整体项目必备的数据


@NgModule({
  declarations: [AppComponent],
  imports: [
    BrowserModule,
    BrowserAnimationsModule,
    HttpClientModule,
    GlobalConfigModule.forRoot(),
    CoreModule,
    SharedModule,
    LayoutModule,
    RoutesModule,
    STWidgetModule,
    NzNotificationModule,
    ...GLOBAL_THIRD_MODULES,
    ...FORM_MODULES
  ],
  providers: [...LANG_PROVIDES, ...INTERCEPTOR_PROVIDES, ...I18NSERVICE_PROVIDES, ...APPINIT_PROVIDES],
  bootstrap: [AppComponent]
})
export class AppModule {}

回到 app.module 中,imports 一些模块,providers 一些服务,

其中对于整体项目比较重要的模块有

  • GlobalConfigModule.forRoot() 全局配置模块,主要配置 alain 中的一些组件功能/认证/等各方面的内容
  • LayoutModule 在用户端的一个布局模块
  • SharedModule 共享模块
  • RoutesModule 总体路由模块,比如 /app/v1 路径,要渲染哪个模块的那个组件,就是这个模块决定的,在这个项目里,也称为 业务模块
  • CoreModule core 模块,刚才提到的拦截器和 i18n 和 startup 就在这个模块中

const alainConfig: AlainConfig = {
  st: { modal: { size: 'lg' } },
  pageHeader: { homeI18n: 'home' },
  lodop: {
    license: `A59B099A586B3851E0F0D7FDBF37B603`,
    licenseA: `C94CEE276DB2187AE6B65D56B3FC2848`
  },
  auth: { login_url: '/passport/login' }
};

const alainModules: any[] = [AlainThemeModule.forRoot(), DelonACLModule.forRoot()];
const alainProvides = [{ provide: ALAIN_CONFIG, useValue: alainConfig }];

const ngZorroConfig: NzConfig = {};

const zorroProvides = [{ provide: NZ_CONFIG, useValue: ngZorroConfig }];

// #endregion

@NgModule({
  imports: [...alainModules, ...(environment.modules || [])]
})
export class GlobalConfigModule {
  constructor(@Optional() @SkipSelf() parentModule: GlobalConfigModule) {
    throwIfAlreadyLoaded(parentModule, 'GlobalConfigModule');
  }

  static forRoot(): ModuleWithProviders<GlobalConfigModule> {
    return {
      ngModule: GlobalConfigModule,
      providers: [...alainProvides, ...zorroProvides]
    };
  }
}

配置了一些基于 AlainConfig 接口的配置,配置了一些 zorro 的配置,然后再次通过 providers 传入到 @delon 包中


@NgModule({
  imports: [
    CommonModule,
    FormsModule,
    RouterModule,
    ReactiveFormsModule,
    AlainThemeModule.forChild(),
    DelonACLModule,
    DelonFormModule,
    ...SHARED_DELON_MODULES,
    ...SHARED_ZORRO_MODULES,
    // third libs
    ...THIRDMODULES
  ],
  declarations: [
    // your components
    ...COMPONENTS,
    ...DIRECTIVES
  ],
  exports: [
    CommonModule,
    FormsModule,
    ReactiveFormsModule,
    RouterModule,
    AlainThemeModule,
    DelonACLModule,
    DelonFormModule,
    ...SHARED_DELON_MODULES,
    ...SHARED_ZORRO_MODULES,
    // third libs
    ...THIRDMODULES,
    // your components
    ...COMPONENTS,
    ...DIRECTIVES
  ]
})

shared 模块存在的意义就是,统一管理每个 routes 模块所依赖的其他模块,新增业务模块时,只需要引入 SharedModule 就可以将其中的一大坨模块直接引入到你建立的模块中,至于文件体积和过多引用不用担心,打包时编译器会做优化的

export const SHARED_ZORRO_MODULES = [
  NzButtonModule,
  NzMessageModule,
  NzDropDownModule,
  NzGridModule,
  NzCheckboxModule,
  NzToolTipModule,
  NzPopoverModule,
  NzSelectModule,
  NzIconModule,
  NzBadgeModule,
  NzAlertModule,
  NzModalModule,
  NzTableModule,
  NzDrawerModule,
  NzTabsModule,
  NzInputModule,
  NzDatePickerModule,
  NzTimePickerModule,
  NzTagModule,
  NzInputNumberModule,
  NzBreadCrumbModule,
  NzListModule,
  NzSwitchModule,
  NzRadioModule,
  NzFormModule,
  NzAvatarModule,
  NzSpinModule,
  NzCardModule,
  NzDividerModule,
  NzProgressModule,
  NzPopconfirmModule,
  NzUploadModule
];

zorro 模块,将 zorro 中所有的模块封装起来,为了之后全量引入,不再做按需引入


接下来是布局,在 app.component 中的模版只有一个 router-outlet,这里直接为后续所有组件渲染放出了位置接口,所有其他的组件会渲染到 HTML 中的这个位置

const routes: Routes = [
  {
    path: '',
    component: LayoutBasicComponent,
    canActivate: [SimpleGuard],
    canActivateChild: [SimpleGuard],
    data: {},
    children: [
      { path: '', redirectTo: 'dashboard', pathMatch: 'full' },
      { path: 'dashboard', loadChildren: () => import('./dashboard/dashboard.module').then(m => m.DashboardModule) },
      {
        path: 'widgets',
        loadChildren: () => import('./widgets/widgets.module').then(m => m.WidgetsModule)
      },
      { path: 'style', loadChildren: () => import('./style/style.module').then(m => m.StyleModule) },
      { path: 'delon', loadChildren: () => import('./delon/delon.module').then(m => m.DelonModule) },
      { path: 'extras', loadChildren: () => import('./extras/extras.module').then(m => m.ExtrasModule) },
      { path: 'pro', loadChildren: () => import('./pro/pro.module').then(m => m.ProModule) }
    ]
  },
  // Blak Layout 空白布局
  {
    path: 'data-v',
    component: LayoutBlankComponent,
    children: [{ path: '', loadChildren: () => import('./data-v/data-v.module').then(m => m.DataVModule) }]
  },
  // passport
  { path: '', loadChildren: () => import('./passport/passport.module').then(m => m.PassportModule) },
  { path: 'exception', loadChildren: () => import('./exception/exception.module').then(m => m.ExceptionModule) },
  { path: '**', redirectTo: 'exception/404' }
];

然后看路由表,最外层的父路由中,指定了渲染的 component: LayoutBasicComponent,这个组件就是定义在 LayoutModule 中的

....
<ng-template #asideUserTpl>
        <div nz-dropdown nzTrigger="click" [nzDropdownMenu]="userMenu" class="alain-default__aside-user">
          <nz-avatar class="alain-default__aside-user-avatar" [nzSrc]="user.avatar"></nz-avatar>
          <div class="alain-default__aside-user-info">
            <strong>{{ user.name }}</strong>
            <p class="mb0">{{ user.email }}</p>
          </div>
        </div>
        <nz-dropdown-menu #userMenu="nzDropdownMenu">
          <ul nz-menu>
            <li nz-menu-item routerLink="/pro/account/center">{{ 'menu.account.center' | i18n }}</li>
            <li nz-menu-item routerLink="/pro/account/settings">{{ 'menu.account.settings' | i18n }}</li>
          </ul>
        </nz-dropdown-menu>
      </ng-template>


      <ng-template #contentTpl>
        <router-outlet></router-outlet>
      </ng-template>

.....

拿出一段 LayoutBasicComponent 的 HTML,其中又有一个 <router-outlet>

这里是为子路由对应的组件放出的渲染位置

假设我的访问路径为:/dashboard/

  • 首先会匹配到路由表中: '' 空路由,将 LayoutBasicComponent 渲染在 app.component 中的 router-outlet 上,又由于,index.html 在删除 preloader-div 后只剩下 app-root,所以 LayoutBasicComponent 占了整张页面
  • 其次匹配 dashboard 路由,这里 dashboard 指向的组件为 dashboard/dashboard.module 模块中的 DashboardV1Component,所以 DashboardV1Component 就会渲染在 已经渲染完 LayoutBasicComponent 组件中的 router-outlet 位置
  • 这样通过路由和子路由加上 router-outlet 完成了整体布局
  • PS: loadChildren: () => import('./dashboard/dashboard.module').then(m => m.DashboardModule) 这种加载方法被称为懒加载,在 DashboardModule 中还有一个子路由表我这里没贴出来,感兴趣可以自己去看一下

至此,大体上过了个差不多,你可以看到虽然 alain 是一个项目,但它又不仅仅是一个项目,下面我们分析一下 alain 项目的组成

4.alain 项目组成

直接看 package.json 吧,就不对照模块了,刚才涉及到的代码有很多都来自以下这些 npm

"ng-zorro-antd": "^12.0.1", 阿里ant组件库

  "@delon/abc": "^12.1.0",  delon包,也是最核心的包
  "@delon/acl": "^12.1.0",
  "@delon/auth": "^12.1.0",
  "@delon/cache": "^12.1.0",
  "@delon/chart": "^12.1.0",
  "@delon/form": "^12.1.0",
  "@delon/mock": "^12.1.0",
  "@delon/theme": "^12.1.0",
  "@delon/util": "^12.1.0",

  "ngx-tinymce": "^12.0.0", 两个编辑器包
   "ngx-ueditor": "^12.0.0",
   "screenfull": "^5.1.0",

   "ajv": "^8.6.2" jsonSchematicValidate包

  "ng-alain": "^12.1.0",  脚手架包

    "ng-alain-plugin-theme": "^12.0.0",  主题生成插件
    "ng-alain-sts": "^0.0.1",  构建 Swagger API 转换为列表、编辑页的命令行工具

5.delon

delon 的项目地址位于: https://github.com/ng-alain/delon

按照惯例先看 angular.json

"delon": {
      "root": "packages",
      "projectType": "library",
      "prefix": "",
      "architect": {
        "lint": {
          "builder": "@angular-eslint/builder:lint",
          "options": {
            "fix": true,
            "lintFilePatterns": [
              "packages/**/*.ts",
              "packages/**/*.html"
            ]
          }
        },
        "test": {
          "builder": "@angular-devkit/build-angular:karma",
          "options": {
            "main": "packages/test.ts",
            "karmaConfig": "packages/karma.conf.js",
            "polyfills": "packages/polyfills.ts",
            "tsConfig": "packages/tsconfig.spec.json",
            "scripts": ["node_modules/@antv/g2/dist/g2.min.js", "node_modules/@antv/data-set/dist/data-set.js"],
            "codeCoverageExclude": ["schematics/**", "packages/testing/**"]
          }
        }
      }
    }

可以看到这里 delon 的跟路径为 packages,应用类行为 package,并不是刚才的 application,说明它并不是一个应用,而是一个最终为 npm 包 形式的项目,所以自然没有 serve 启动项的配置

但是我们找到了入口 root 配置项配置的是 packages

5.1 delon/packages

5.2 delon build

5.3 delon schematics

5.4 sts

5.5 plugin-theme

plugin-theme 主要是用来生成主题配置的一个插件

plugin-theme 的项目在 https://github.com/ng-alain/plugin-theme.git

const cli = meow({
  help: `
  Usage
    ng-alain-plugin-theme
  Example
    ng-alain-plugin-theme -t=themeCss -c=ng-alain.json
  Options
    -t, --type    Can be set 'themeCss', 'colorLess'
    -c, --config  A filepath of NG-ALAIN config script
    -d, --debug   Debug mode
  `,
  flags: {
    type: {
      type: 'string',
      default: 'themeCss',
      alias: 't',
    },
    config: {
      type: 'string',
      default: 'ng-alain.json',
      alias: 'c',
    },
    debug: {
      type: 'boolean',
      default: false,
      alias: 'd',
    },
  },
});

这里使用了基于 nodejs 的 meow 包,构建了一个 CLI 工具,所谓 CLI 即为 Command Line Interface,其实就是命令行,这里给出了三个配置项

  • -t 文件类型,less/css
  • -c 自定义主题 config,详情见 ng-alalin 项目内的 ng-alain.json,也可以在主题切换中找到使用方式
  • -d 是否开启 debug 模式

let config: { theme: Config; colorLess: Config; [key: string]: Config };

传入 JSON 的格式

[key:string]:Config

意思是接口的任何属性,都要是 Config 格式

try {
  const configFile = resolve(process.cwd(), cli.flags.config);
  if (existsSync(configFile)) {
    config = getJSON(configFile);
  } else {
    console.error(`The config file '${cli.flags.config}' will not found`);
    process.exit(1);
  }
} catch (err) {
  console.error('Invalid config file', err);
  process.exit(1);
}

读取 cli 传入的 文件路径 然后转换成 JSON,赋值给 config

if (cli.flags.type === 'themeCss') {
  buildThemeCSS(config.theme);
} else if (cli.flags.type === 'colorLess') {
  genColorLess(config.colorLess);
} else {
  throw new Error(`Invalid type, can be set themeCss or colorLess value`);
}

假如 type 是 css 那么走 buildThemeCSS 函数

假如 type 是 less 那么走 genColorLess 函数


export async function genColorLess(config: ColorLessConfig): Promise<void> {
  config = fixConfig(config);

  if (existsSync(config.outputFilePath!)) {
    unlinkSync(config.outputFilePath!);
  }

  await generateTheme(config);
}

genColorLess 简单的处理 config 传入的 ng-alalin.json 转换成的对象,然后调用了 generateTheme 来生成主题,最后输出到项目的目录中,具体通过 json 来生成 theme 的函数规则较为复杂,概括一下就是 拿json传入的配置,对文件内容自动进行@import,替换等操作,最后生成目标文件 less,写入原项目中

5.6 scripts

5.7 site

5.8 changelog

5.9 publish

5.10 release

来不及整理用到啥写啥


标题:关于@delon包
作者:devcui
地址:https://blog.eiyouhe.com/articles/2021/08/15/1629025990196.html