feat(module:breadcrumb): add nzRouteFn (#6313)

* feat(module:breadcrumb): add nzRouteFn

* feat(module:breadcrumb): update docs

* feat(module:breadcrumb): update docs

* docs: add Chinese doc

* Update breadcrumb.spec.ts to fix lint errors

---------

Co-authored-by: wendellhu95 <wendellhu95@gmail.com>
Co-authored-by: Laffery <49607541+Laffery@users.noreply.github.com>

Author: 3 people

components/breadcrumb/breadcrumb.component.ts

@@ -62,6 +62,7 @@ export class NzBreadCrumbComponent implements OnInit, OnDestroy, NzBreadcrumb {
   @Input() nzSeparator: string | TemplateRef<void> | null = '/';
   @Input() nzRouteLabel: string = 'breadcrumb';
   @Input() nzRouteLabelFn: (label: string) => string = label => label;
+  @Input() nzRouteFn: (route: string) => string = route => route;
 
   breadcrumbs: BreadcrumbOption[] = [];
   dir: Direction = 'ltr';
@@ -144,13 +145,13 @@ export class NzBreadCrumbComponent implements OnInit, OnDestroy, NzBreadcrumb {
         // Do not change nextUrl if routeUrl is falsy. This happens when it's a route lazy loading other modules.
         const nextUrl = routeUrl ? `${url}/${routeUrl}` : url;
         const breadcrumbLabel = this.nzRouteLabelFn(child.snapshot.data[this.nzRouteLabel]);
-
+        const shapedUrl = this.nzRouteFn(nextUrl);
         // If have data, go to generate a breadcrumb for it.
         if (routeUrl && breadcrumbLabel) {
           const breadcrumb: BreadcrumbOption = {
             label: breadcrumbLabel,
             params: child.snapshot.params,
-            url: nextUrl
+            url: shapedUrl
           };
           breadcrumbs.push(breadcrumb);
         }

components/breadcrumb/breadcrumb.spec.ts

@@ -208,6 +208,26 @@ describe('breadcrumb', () => {
       });
     }));
 
+    it('should [nzRouteFn] work', fakeAsync(() => {
+      TestBed.configureTestingModule({
+        imports: [CommonModule, NzBreadCrumbModule, RouterTestingModule.withRoutes(customRouteLabelRoutes)],
+        declarations: [NzBreadcrumbRouteWithCustomFnDemoComponent, NzBreadcrumbNullComponent]
+      }).compileComponents();
+
+      fixture = TestBed.createComponent(NzBreadcrumbRouteWithCustomFnDemoComponent);
+      breadcrumb = fixture.debugElement.query(By.directive(NzBreadCrumbComponent));
+
+      fixture.ngZone!.run(() => {
+        router = TestBed.inject(Router);
+        router.initialNavigation();
+
+        // Breadcrumb should conatin added params by nzRouteFn
+        router.navigate(['one', 'two']);
+        flushFixture(fixture);
+        expect(breadcrumb.componentInstance.breadcrumbs[0].url).toContain('active=true');
+      });
+    }));
+
     it('should route data breadcrumb navigate work', fakeAsync(() => {
       TestBed.configureTestingModule({
         imports: [CommonModule, NzBreadCrumbModule, RouterTestingModule.withRoutes(customRouteLabelRoutes)],
@@ -332,6 +352,16 @@ class NzBreadcrumbRouteLabelWithCustomFnDemoComponent {
   labelFn = (label: string): string => (label ? `${label} ${label}` : '');
 }
 
+@Component({
+  template: `
+    <nz-breadcrumb [nzAutoGenerate]="true" [nzRouteLabel]="'customBreadcrumb'" [nzRouteFn]="routeFn"></nz-breadcrumb>
+    <router-outlet></router-outlet>
+  `
+})
+class NzBreadcrumbRouteWithCustomFnDemoComponent {
+  routeFn = (route: string): string => `${route};active=true`;
+}
+
 @Component({
   template: '<nz-breadcrumb [nzAutoGenerate]="true"></nz-breadcrumb>'
 })

components/breadcrumb/doc/index.en-US.md

@@ -27,7 +27,8 @@ import { NzBreadCrumbModule } from 'ng-zorro-antd/breadcrumb';
 | `[nzSeparator]` | Custom separator | `string \| TemplateRef<void> \| null` | `'/'` |
 | `[nzAutoGenerate]` | Auto generate breadcrumb | `boolean` | `false` |
 | `[nzRouteLabel]` | Name of property that determines displayed text in routing config. It should be used when `nzAutoGenerate` is `true` | `string` | `'breadcrumb'` |
-| `[nzRouteLabelFn]` | Format breadcrumb item label text，normally used in international app to translate i18n key. It should be used when `nzAutoGenerate` is `true` | `(label:string) => string` | `label => label` |
+| `[nzRouteLabelFn]` | Format breadcrumb item label text, normally used in international app to translate i18n key. It should be used when `nzAutoGenerate` is `true` | `(label:string) => string` | `label => label` |
+| `[nzRouteFn]` | Format breadcrumb item route, normally used in international app to bind current params or query strings to avoid losing them while navigate using breadcrumb. It should be used when `nzAutoGenerate` is `true` | `(route:string) => route` | `route => route` |
 
 Using `[nzAutoGenerate]` by configuring `data` like this:
 
@@ -53,7 +54,7 @@ For lazy loading modules, you should write `data` in parent module like this:
 }
 ```
 
-use `nzRouteLabel` to custom `data` breadcrumb label:
+Use `nzRouteLabel` to custom `data` breadcrumb label:
 
 ```html
 <nz-breadcrumb [nzAutoGenerate]="true" [nzRouteLabel]="'customBreadcrumb'"></nz-breadcrumb>
@@ -69,7 +70,7 @@ use `nzRouteLabel` to custom `data` breadcrumb label:
 }
 ```
 
-use `nzRouteLabelFn` to format breadcrumb label in international application:
+Use `nzRouteLabelFn` to format breadcrumb label in international application:
 
 ```html
 <nz-breadcrumb [nzAutoGenerate]="true" [nzRouteLabel]="'breadcrumbI18nKey'" [nzRouteLabelFn]="translateFn"></nz-breadcrumb>
@@ -88,3 +89,27 @@ use `nzRouteLabelFn` to format breadcrumb label in international application:
 // In component
 translateFn = (key:string) => this.yourI18nService.translate(key);
 ```
+
+Use `nzRouteFn` to format or bind params and query strings to the route it self in international application:
+
+```html
+<nz-breadcrumb [nzAutoGenerate]="true" [nzRouteLabel]="'breadcrumbI18nKey'" [nzRouteLabelFn]="translateFn" [nzRouteFn]="customRoute"></nz-breadcrumb>
+```
+
+```ts
+// In component
+
+bindCurrentParams(params, route) {
+  let newRoute = route;
+  for (const key in params) {
+    if (params.hasOwnProperty(key)) {
+      newRoute += `;${key}=${params[key]}`;
+    }
+  }
+  return newRoute;
+}
+
+const params = this.activatedRoute.snapshot.params;
+
+customRoute = (route:string) => this.bindCurrentParams(params,route);
+```

components/breadcrumb/doc/index.zh-CN.md

@@ -26,8 +26,9 @@ import { NzBreadCrumbModule } from 'ng-zorro-antd/breadcrumb';
 | --- | --- | --- | --- |
 | `[nzSeparator]` | 分隔符自定义 | `string \| TemplateRef<void> \| null` | `'/'` |
 | `[nzAutoGenerate]` | 自动生成 Breadcrumb | `boolean` | `false` |
-| `[nzRouteLabel]` | 自定义 route data 属性名称, `nzAutoGenerate` 为 `true` 时才生效 | `string` | `'breadcrumb'` |
-| `[nzRouteLabelFn]` | 格式化面包屑导航项的显示文字，通常用于在国际化应用中翻译键值, `nzAutoGenerate` 为 `true` 时才生效 | `(label:string) => string` | `label => label` |
+| `[nzRouteLabel]` | 自定义 route data 属性名称，`nzAutoGenerate` 为 `true` 时才生效 | `string` | `'breadcrumb'` |
+| `[nzRouteLabelFn]` | 格式化面包屑导航项的显示文字，通常用于在国际化应用中翻译键值， `nzAutoGenerate` 为 `true` 时才生效 | `(label:string) => string` | `label => label` |
+| `[nzRouteFn]` | 格式化面包屑路由格式，可用于为 URL 添加 query params，`nzAutoGenerate` 为 `true` 时才生效  | `(route:string) => route` | `route => route` |
 
 使用 `[nzAutoGenerate]` 时，需要在路由类中定义 `data`:
 
@@ -88,3 +89,28 @@ import { NzBreadCrumbModule } from 'ng-zorro-antd/breadcrumb';
 // In component
 translateFn = (key: string) => this.yourI18nService.translate(key);
 ```
+
+使用 `nzRouteFn` 来使用格式化 URL 或添加 query params：
+
+
+```html
+<nz-breadcrumb [nzAutoGenerate]="true" [nzRouteLabel]="'breadcrumbI18nKey'" [nzRouteLabelFn]="translateFn" [nzRouteFn]="customRoute"></nz-breadcrumb>
+```
+
+```ts
+// In component
+
+bindCurrentParams(params, route) {
+  let newRoute = route;
+  for (const key in params) {
+    if (params.hasOwnProperty(key)) {
+      newRoute += `;${key}=${params[key]}`;
+    }
+  }
+  return newRoute;
+}
+
+const params = this.activatedRoute.snapshot.params;
+
+customRoute = (route:string) => this.bindCurrentParams(params,route);
+```