全局配置项

我们给众多组件添加了全局配置功能，你可以通过全局配置来定义组件的默认行为，从而减少在模板中需要写的代码（让你的代码更加清爽），还能在运行时修改全局配置项。

如何使用

想要为某些组件提供默认配置项，请在根注入器中根据注入令牌 NZ_CONFIG 提供一个符合 NzConfig 接口的对象，例如：

  1. import { NzConfig, NZ_CONFIG } from 'ng-zorro-antd/core/config';
  3. const ngZorroConfig: NzConfig = {
  4.   // 注意组件名称没有 nz 前缀
  5.   message: { nzTop: 120 },
  6.   notification: { nzTop: 240 }
  7. };
  9. @NgModule({
  10.   declarations: [AppComponent],
  11.   imports: [
  12.     CommonModule
  13.   ],
  14.   providers: [
  15.     { provide: NZ_CONFIG, useValue: ngZorroConfig }
  16.   ],
  17.   bootstrap: [AppComponent]
  18. })
  19. export class AppModule {}

这些全局配置项将会被注入 NzConfigService 当中并保存。

提供模板

一些组件支持传递模板 TemplateRef<T> 作为默认参数，我们来了解一下如何做到这一点。

最简单的方式是在应用的根组件中调用 NzConfigService 的相关方法：

  1. export class AppComponent implements OnInit {
  2.   @ViewChild('nzIndicatorTpl', { static: true })
  3.   nzIndicator!: TemplateRef<void>;
  5.   constructor(private readonly nzConfigService: NzConfigService) {}
  7.   ngOnInit(): void {
  8.     this.nzConfigService.set('spin', { nzIndicator: this.nzIndicator });
  9.   }
  10. }

然而这种方式可能会让你的 AppComponent 相当臃肿，并违反关注分离原则。

因此，当你的项目比较大时，我们建议你使用一个 FactoryProvider，如下所示：

  1. // The module-level Component which contains template references.
  2. // Exporting is required for AOT compatibility
  3. @Component({
  4.   template: `
  5.     <ng-template #nzIndicatorTpl>
  6.       <span class="ant-spin-dot">
  7.         <i nz-icon [nzType]="'loading'"></i>
  8.       </span>
  9.     </ng-template>
  10.   `
  11. })
  12. export class GlobalTemplatesComponent {
  13.   @ViewChild('nzIndicatorTpl', { static: true })
  14.   nzIndicator!: TemplateRef<void>;
  15. }
  17. // The Factory function
  18. const nzConfigFactory = (
  19.   injector: Injector,
  20.   resolver: ComponentFactoryResolver
  21. ): NzConfig => {
  22.   const factory = resolver.resolveComponentFactory(GlobalTemplatesComponent);
  23.   const { nzIndicator } = factory.create(injector).instance;
  24.   return {
  25.     spin: {
  26.       nzIndicator
  27.     }
  28.   };
  29. };
  31. @NgModule({
  32.   imports: [...],
  33.   declarations: [
  34.     AppComponent,
  35.     GlobalTemplatesComponent
  36.   ],
  37.   providers: [
  38.     { // The FactoryProvider
  39.       provide: NZ_CONFIG,
  40.       useFactory: nzConfigFactory,
  41.       deps: [Injector, ComponentFactoryResolver]
  42.     }
  43.   ]
  44. })
  45. export class AppModule {}

动态变更全局配置

你可以通过调用 NzConfigService 的 set 方法来改变某个组件的全局配置项，例如：

  1. import { NzConfigService } from 'ng-zorro-antd/core/config';
  3. @Component({
  4.   selector: 'app-change-zorro-config'
  5. })
  6. export class ChangeZorroConfigComponent {
  7.   constructor(private nzConfigService: NzConfigService) {}
  9.   onChangeConfig() {
  10.     // 爷爷：我就喜欢大号字！
  11.     this.nzConfigService.set('button', { nzSize: 'large' })
  12.   }
  13. }

所有的组件实例都会响应这些改变（只要它们没有被单独赋值）。

全局配置项的优先级

对于任何一个属性来说，各个来源的值的优先级如下：

为组件的某个实例单独设置的值（通过模板或类似于 service.create 的方法）> 通过 NZ_CONFIG 提供的全局默认值（包括 set 方法） > NG-ZORRO 内置的默认值。

例如，你想创建一个 NzNotification 组件：

  • 你在调用 NzNotificationService.success 时传递参数 { nzDuration: 6000 }
  • 你通过 NZ_CONFIG 提供了全局默认值 { notification: { nzDuration: 5000 } }
  • NG-ZORRO 内部默认值为 4500 最终该 Notification 将会显示 6000 毫秒。

查看所有可用的全局配置项

NzConfig 接口提供的类型定义信息能够帮助你找到所有支持全局配置项的组件和属性。另外，每个组件的文档都会指出哪些属性可以通过全局配置项的方式指定。