feat(module:icon): support add icon in feat modules (#4711)

feat(module:icon): support import icon in submodules fix: fix patch feat: rename API docs: fix doc fix: remove redundant code docs: fix unrenamed API chore(module:icon): refactor test: fix tests fix: fix tests BREAKING CHANGE: - `NZ_ICON_DEFAULT_TWOTONE_COLOR` is removed. Use `NzGlobalConfigService` instead. chore: remove strange file test: fix test feat: add forRoot docs: change doc docs: fix icon English doc
NG-ZORRO · Mar 15, 2020 · 0bcd2a9 · 0bcd2a9
1 parent 2553328
commit 0bcd2a9
Show file tree

Hide file tree

Showing 12 changed files with 319 additions and 199 deletions.
diff --git a/components/core/testing/componet-bed.ts b/components/core/testing/componet-bed.ts
@@ -1,10 +1,10 @@
 import { CommonModule } from '@angular/common';
-import { DebugElement, NO_ERRORS_SCHEMA, Provider, Type } from '@angular/core';
+import { DebugElement, ModuleWithProviders, NO_ERRORS_SCHEMA, Provider, Type } from '@angular/core';
 import { ComponentFixture, TestBed, TestBedStatic } from '@angular/core/testing';
 import { NoopAnimationsModule } from '@angular/platform-browser/animations';
 import { NzSafeAny } from 'ng-zorro-antd/core/types';
 
-type ComponentDeps = Array<Type<NzSafeAny>>;
+type ComponentDeps = Array<Type<NzSafeAny> | ModuleWithProviders>;
 export interface ComponentBed<T> {
   bed: TestBedStatic;
   fixture: ComponentFixture<T>;

diff --git a/components/icon/doc/index.en-US.md b/components/icon/doc/index.en-US.md
@@ -37,12 +37,6 @@ import { NzIconModule } from 'ng-zorro-antd/icon';
 | `fetchFromIconfont()` | To get icon assets from fonticon | `NzIconfontOption` |
 | `changeAssetsSource()` | To change the location of your icon assets, so that you can deploy these icons wherever you want | `string` |
 
-### InjectionToken
-
-| Token | Description | Parameters |
-| --- | --- | --- |
-| `NZ_ICONS` | To import icons statically | `IconDefinition[]`, `useValue` |
-
 ### SVG icons
 
 We synced to Ant Design and replaced font icons with svg icons which bring benefits below:
@@ -74,7 +68,7 @@ Static loading. By registering icons to `AppModule` you load icons statically.
 
 ```ts
 import { IconDefinition } from '@ant-design/icons-angular';
-import { NzIconModule, NZ_ICON_DEFAULT_TWOTONE_COLOR, NZ_ICONS } from 'ng-zorro-antd/icon';
+import { NzIconModule } from 'ng-zorro-antd/icon';
 
 // Import what you need. RECOMMENDED. ✔️
 import { AccountBookFill, AlertFill, AlertOutline } from '@ant-design/icons-angular/icons';
@@ -94,19 +88,15 @@ const icons: IconDefinition[] = [ AccountBookFill, AlertOutline, AlertFill ];
     AppComponent
   ],
   imports: [
-    NzIconModule,
-  ],
-  providers: [
-    { provide: NZ_ICON_DEFAULT_TWOTONE_COLOR, useValue: '#00ff00' }, // If not provided, Ant Design's official blue would be used
-    { provide: NZ_ICONS, useValue: icons }
-  ],
+    NzIconModule.forRoot(icons),
+  ]
   bootstrap: [ AppComponent ]
 })
 export class AppModule {
 }
 ```
 
-Actually this calls `addIcon` of `NzIconService`. Icons imported would be bundled into your `.js` files. Static loading would increase your bundle's size so we recommend use dynamic importing as much as you can. You can track this [issue](https://github.com/ant-design/ant-design/issues/12011) of Ant Design for more details.
+Actually this calls `addIcon` of `NzIconService`. Icons imported would be bundled into your `.js` files. Static loading would increase your bundle's size so we recommend use dynamic importing as much as you can.
 
 > Icons used by `NG-ZORRO` itself are imported statically to increase loading speed. However, icons demonstrated on the official website are loaded dynamically.
 
@@ -130,6 +120,19 @@ Let's assume that you deploy static assets under `https://mycdn.somecdn.com/icon
 
 Please call this in component's constructor or `AppInitService`.
 
+### Add Icons in Lazy-loaded Modules
+
+Sometimes, you want to import icons in lazy modules to avoid increasing the size of the main.js. You can use `NzIconModule.patch`.
+
+```ts
+@NgModule({
+  imports: [CommonModule, NzIconModule.forChild([QuestionOutline])],
+})
+class ChildModule {}
+```
+
+When `ChildModule` get loaded, the icon QuestionOutline would be usable across the application.
+
 ### Set Default TwoTone Color
 
 When using the two-tone icons, you provide a global configuration like `{ nzIcon: { nzTwotoneColor: 'xxx' } }` via `NzConfigService` or call corresponding `set` method to change two default twotone color.

diff --git a/components/icon/doc/index.zh-CN.md b/components/icon/doc/index.zh-CN.md
@@ -39,12 +39,6 @@ import { NzIconModule } from 'ng-zorro-antd/icon';
 | `fetchFromIconfont()` | 用于从 FontIcon 获取图标资源文件 | `NzIconfontOption` |
 | `changeAssetypescriptSource()` | 用于修改动态加载 icon 的资源前缀，使得你可以部署图标资源到你想要的任何位置，例如 cdn | `string` |
 
-### InjectionToken
-
-| Token | 说明 | 参数 |
-| --- | --- | --- |
-| `NZ_ICONS` | 用于静态引入图标，传入数组 | `IconDefinition[]`, `useValue` |
-
 ### SVG 图标
 
 我们与 Ant Design 同步，使用了 svg 图标替换了原先的 font 图标，从而带来了以下优势：
@@ -76,7 +70,7 @@ NG-ZORRO 之前并没有图标组件，而是提供了基于字体文件的解
 
 ```ts
 import { IconDefinition } from '@ant-design/icons-angular';
-import { NzIconModule, NZ_ICON_DEFAULT_TWOTONE_COLOR, NZ_ICONS } from 'ng-zorro-antd/icon';
+import { NzIconModule } from 'ng-zorro-antd/icon';
 
 // 引入你需要的图标，比如你需要 fill 主题的 AccountBook Alert 和 outline 主题的 Alert，推荐 ✔️
 import { AccountBookFill, AlertFill, AlertOutline } from '@ant-design/icons-angular/icons';
@@ -96,19 +90,15 @@ const icons: IconDefinition[] = [ AccountBookFill, AlertOutline, AlertFill ];
     AppComponent
   ],
   imports: [
-    NzIconModule,
-  ],
-  providers: [
-    { provide: NZ_ICON_DEFAULT_TWOTONE_COLOR, useValue: '#00ff00' }, // 不提供的话，即为 Ant Design 的主题蓝色
-    { provide: NZ_ICONS, useValue: icons }
-  ],
+    NzIconModule.forRoot(icons)
+  ]
   bootstrap: [ AppComponent ]
 })
 export class AppModule {
 }
 ```
 
-本质上是调用了 `NzIconService` 的 `addIcon` 方法，引入后的文件会被打包到 `.js` 文件中。静态引入会增加包体积，所以我们建议尽可能地使用动态加载，如果要静态加载，也仅仅加载你需要用到的图标，具体请看 Ant Design 的 [issue](https://github.com/ant-design/ant-design/issues/12011)。
+本质上是调用了 `NzIconService` 的 `addIcon` 方法，引入后的文件会被打包到 `.js` 文件中。静态引入会增加包体积，所以我们建议尽可能地使用动态加载，如果要静态加载，也仅仅加载你需要用到的图标。
 
 > 为了加快渲染速度，NG-ZORRO 本身用到的 icon 是静态引入的。而官网的图标是动态引入的。
 
@@ -132,6 +122,21 @@ export class AppModule {
 
 请在 constructor 里或者在 `AppInitService` 里调用这个方法。
 
+### 在子模块中补充图标
+
+有时候，为了避免增大 main.js 的体积，你可能想要从懒加载模块中引入图标，这时你就可以使用 `NzIconModule.patch` 来追加图标。
+
+```ts
+@NgModule({
+  imports: [CommonModule, NzIconModule.forChild([QuestionOutline])],
+})
+class ChildModule {}
+```
+
+这样，当 `ChildModule` 加载之后，整个应用都能够使用 QuestionOutline 图标。
+
+当然，不要忘记在 `NZ_ICONS` 中删除该图标。
+
 ### 双色图标主色
 
 对于双色图标，可以通过提供全局配置 `{ nzIcon: { nzTwotoneColor: 'xxx' } }` 或 `NzConfigService` 的对应方法修改来全局设置图标主色。

diff --git a/components/icon/nz-icon.directive.ts → components/icon/icon.directive.ts b/components/icon/nz-icon.directive.ts → components/icon/icon.directive.ts
@@ -6,24 +6,12 @@
  * found in the LICENSE file at https://github.com/NG-ZORRO/ng-zorro-antd/blob/master/LICENSE
  */
 
-import { AfterContentChecked, Directive, ElementRef, Input, OnChanges, OnInit, Renderer2, SimpleChanges } from '@angular/core';
+import { AfterContentChecked, Directive, ElementRef, Input, OnChanges, OnInit, Optional, Renderer2, SimpleChanges } from '@angular/core';
 import { IconDirective, ThemeType } from '@ant-design/icons-angular';
 import { InputBoolean, NzUpdateHostClassService } from 'ng-zorro-antd/core';
 
-import { NzIconService } from './nz-icon.service';
+import { NzIconPatchService, NzIconService } from './icon.service';
 
-/**
- * This directive extends IconDirective to provide:
- *
- * - IconFont support
- * - spinning
- * - old API compatibility
- *
- * @break-changes
- *
- * - old API compatibility, icon class names would not be supported.
- * - properties that not started with `nz`.
- */
 @Directive({
   selector: '[nz-icon]',
   exportAs: 'nzIcon',
@@ -75,10 +63,15 @@ export class NzIconDirective extends IconDirective implements OnInit, OnChanges,
     elementRef: ElementRef,
     public iconService: NzIconService,
     public renderer: Renderer2,
-    private nzUpdateHostClassService: NzUpdateHostClassService
+    private nzUpdateHostClassService: NzUpdateHostClassService,
+    @Optional() iconPatch: NzIconPatchService
   ) {
     super(iconService, elementRef, renderer);
 
+    if (iconPatch) {
+      iconPatch.doPatch();
+    }
+
     this.el = elementRef.nativeElement;
   }
 

diff --git a/components/icon/icon.module.ts b/components/icon/icon.module.ts
@@ -0,0 +1,45 @@
+/**
+ * @license
+ * Copyright Alibaba.com All Rights Reserved.
+ *
+ * Use of this source code is governed by an MIT-style license that can be
+ * found in the LICENSE file at https://github.com/NG-ZORRO/ng-zorro-antd/blob/master/LICENSE
+ */
+import { PlatformModule } from '@angular/cdk/platform';
+import { ModuleWithProviders, NgModule } from '@angular/core';
+import { IconDefinition } from '@ant-design/icons-angular';
+
+import { NzIconDirective } from './icon.directive';
+import { NZ_ICONS, NZ_ICONS_PATCH, NzIconPatchService } from './icon.service';
+
+@NgModule({
+  exports: [NzIconDirective],
+  declarations: [NzIconDirective],
+  imports: [PlatformModule]
+})
+export class NzIconModule {
+  static forRoot(icons: IconDefinition[]): ModuleWithProviders<NzIconModule> {
+    return {
+      ngModule: NzIconModule,
+      providers: [
+        {
+          provide: NZ_ICONS,
+          useValue: icons
+        }
+      ]
+    };
+  }
+
+  static forChild(icons: IconDefinition[]): ModuleWithProviders<NzIconModule> {
+    return {
+      ngModule: NzIconModule,
+      providers: [
+        NzIconPatchService,
+        {
+          provide: NZ_ICONS_PATCH,
+          useValue: icons
+        }
+      ]
+    };
+  }
+}
diff --git a/components/icon/nz-icon.service.ts → components/icon/icon.service.ts b/components/icon/nz-icon.service.ts → components/icon/icon.service.ts
@@ -8,7 +8,7 @@
 
 import { DOCUMENT } from '@angular/common';
 import { HttpBackend } from '@angular/common/http';
-import { Inject, Injectable, InjectionToken, Optional, RendererFactory2 } from '@angular/core';
+import { Inject, Injectable, InjectionToken, Optional, RendererFactory2, Self } from '@angular/core';
 import { DomSanitizer } from '@angular/platform-browser';
 import { IconDefinition, IconService } from '@ant-design/icons-angular';
 import {
@@ -53,7 +53,7 @@ import {
   UploadOutline,
   UpOutline
 } from '@ant-design/icons-angular/icons';
-import { IconConfig, NzConfigService, warn, warnDeprecation } from 'ng-zorro-antd/core';
+import { IconConfig, NzConfigService, warn } from 'ng-zorro-antd/core';
 import { Subject } from 'rxjs';
 
 export interface NzIconfontOption {
@@ -152,23 +152,12 @@ export class NzIconService extends IconService {
     @Optional() handler: HttpBackend,
     // tslint:disable-next-line:no-any
     @Optional() @Inject(DOCUMENT) _document: any,
-    @Optional() @Inject(NZ_ICONS) icons?: IconDefinition[],
-    /**
-     * @deprecated
-     * @inner
-     */
-    @Optional() @Inject(NZ_ICON_DEFAULT_TWOTONE_COLOR) private legacyDefaultTwotoneColor?: string
+    @Optional() @Inject(NZ_ICONS) icons?: IconDefinition[]
   ) {
     super(rendererFactory, handler, _document, sanitizer);
 
     this.onConfigChange();
-
     this.addIcon(...NZ_ICONS_USED_BY_ZORRO, ...(icons || []));
-
-    if (legacyDefaultTwotoneColor) {
-      warnDeprecation(`'NZ_ICON_DEFAULT_TWOTONE_COLOR' is deprecated and will be removed in 9.0.0. Please use 'NZ_CONFIG' instead!`);
-    }
-
     this.configDefaultTwotoneColor();
     this.configDefaultTheme();
   }
@@ -188,7 +177,7 @@ export class NzIconService extends IconService {
 
   private configDefaultTwotoneColor(): void {
     const iconConfig = this.getConfig();
-    const defaultTwotoneColor = iconConfig.nzTwotoneColor || this.legacyDefaultTwotoneColor;
+    const defaultTwotoneColor = iconConfig.nzTwotoneColor || DEFAULT_TWOTONE_COLOR;
 
     let primaryColor = DEFAULT_TWOTONE_COLOR;
 
@@ -207,3 +196,21 @@ export class NzIconService extends IconService {
     return this.nzConfigService.getConfigForComponent('icon') || {};
   }
 }
+
+export const NZ_ICONS_PATCH = new InjectionToken('nz_icons_patch');
+
+@Injectable()
+export class NzIconPatchService {
+  patched = false;
+
+  constructor(@Self() @Inject(NZ_ICONS_PATCH) private extraIcons: IconDefinition[], private rootIconService: NzIconService) {}
+
+  doPatch(): void {
+    if (this.patched) {
+      return;
+    }
+
+    this.extraIcons.forEach(iconDefinition => this.rootIconService.addIcon(iconDefinition));
+    this.patched = true;
+  }
+}