feat(module:mention): support nzClear (#9377)

Mention component now support nzClear icon

---

Co-authored-by: HyperLife1119 <hyperlife1119@qq.com>

Author: Nicoss54

components/mention/demo/clear.md

@@ -0,0 +1,14 @@
+---
+order: 11
+title:
+  zh-CN: 带移除图标
+  en-US: With clear icon
+---
+
+## zh-CN
+
+自定义清除按钮。
+
+## en-US
+
+Customize clear button.

components/mention/demo/clear.ts

@@ -0,0 +1,32 @@
+import { Component, model } from '@angular/core';
+import { FormsModule } from '@angular/forms';
+
+import { NzInputModule } from 'ng-zorro-antd/input';
+import { NzMentionModule } from 'ng-zorro-antd/mention';
+
+@Component({
+  selector: 'nz-demo-mention-clear',
+  imports: [FormsModule, NzInputModule, NzMentionModule],
+  template: `
+    <nz-mention [nzSuggestions]="suggestions" (nzOnSelect)="onSelect($event)" nzAllowClear (nzOnClear)="onClear()">
+      <textarea rows="1" placeholder="input here" nzMentionTrigger nz-input [(ngModel)]="inputValue"></textarea>
+    </nz-mention>
+    <br />
+    <br />
+    <nz-mention [nzSuggestions]="suggestions" (nzOnSelect)="onSelect($event)" nzAllowClear (nzOnClear)="onClear()">
+      <textarea rows="3" placeholder="input here" nzMentionTrigger nz-input [(ngModel)]="inputValue"></textarea>
+    </nz-mention>
+  `
+})
+export class NzDemoMentionClearComponent {
+  inputValue = model('@afc163');
+  suggestions = ['afc163', 'benjycui', 'yiminghe', 'RaoHai', '中文', 'にほんご'];
+
+  onSelect(e: string): void {
+    console.log(e);
+  }
+
+  onClear(): void {
+    console.log('onClear');
+  }
+}

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

@@ -30,10 +30,13 @@ When need to mention someone or something.
 | `[nzPrefix]`            | Character which will trigger Mention to show mention list                                 | `string \| string[]`                                     | `'@'`                            |
 | `[nzSuggestions]`       | Suggestion content                                                                        | `any[]`                                                  | `[]`                             |
 | `[nzStatus]`            | Set validation status                                                                     | `'error' \| 'warning'`                                   | -                                |
+| `[nzAllowClear]`        | If allow to remove mentions content with clear icon                                       | `boolean`                                                | `false`                          |
+| `[nzClearIcon]`         | The custom clear icon                                                                     | `TemplateRef<void>`                                      | -                                |
 | `[nzVariant]`           | Variants of Input                                                                         | `'outlined' \| 'filled' \| 'borderless' \| 'underlined'` | `'outlined'`                     |
 | `[nzValueWith]`         | Function that maps an suggestion's value                                                  | `(any) => string \| (value: string) => string`           |
 | `(nzOnSelect)`          | Callback function called when select from suggestions                                     | `EventEmitter<any>`                                      | -                                |
 | `(nzOnSearchChange)`    | Callback function called when search content changes                                      | `EventEmitter<MentionOnSearchTypes>`                     | -                                |
+| `(nzOnClear)`           | Callback function called when click on clear button                                       | `EventEmitter<void>`                                     | -                                |
 
 #### Methods
 

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

@@ -31,10 +31,13 @@ description: 用于在输入中提及某人或某事。
 | `[nzPrefix]`            | 触发弹出下拉框的字符              | `string \| string[]`                                     | `'@'`                            |
 | `[nzSuggestions]`       | 建议内容                          | `any[]`                                                  | `[]`                             |
 | `[nzStatus]`            | 设置校验状态                      | `'error' \| 'warning'`                                   | -                                |
+| `[nzAllowClear]`        | 支持清除                          | `boolean`                                                | `false`                          |
+| `[nzClearIcon]`         | 自定义的多选框清空图标            | `TemplateRef<void>`                                      | -                                |
 | `[nzVariant]`           | 形态变体                          | `'outlined' \| 'filled' \| 'borderless' \| 'underlined'` | `'outlined'`                     |
-| `[nzValueWith]`         | 建议选项的取值方法                | `(any) => string \| (value: string) => string`           |
+| `[nzValueWith]`         | 建议选项的取值方法                | `(any) => string \| (value: string) => string`           | -                                |
 | `(nzOnSelect)`          | 下拉框选择建议时回调              | `EventEmitter<any>`                                      | -                                |
 | `(nzOnSearchChange)`    | 输入框中 @ 变化时回调             | `EventEmitter<MentionOnSearchTypes>`                     | -                                |
+| `(nzOnClear)`           | 清空已选项时触发的回调函数        | `EventEmitter<void>`                                     | -                                |
 
 #### 方法
 

components/mention/mention-trigger.ts

@@ -61,7 +61,8 @@ export class NzMentionTriggerDirective implements ControlValueAccessor {
   @Output() readonly onKeydown = new EventEmitter<KeyboardEvent>();
   // eslint-disable-next-line @angular-eslint/no-output-on-prefix
   @Output() readonly onClick = new EventEmitter<MouseEvent>();
-  value?: string;
+
+  readonly value = signal<string>('');
 
   readonly disabled = signal(false);
 
@@ -103,16 +104,19 @@ export class NzMentionTriggerDirective implements ControlValueAccessor {
     this.elementRef.nativeElement.value = newValue;
     this.focus(mention.startPos + insertValue.length + 1);
     this.onChange(newValue);
-    this.value = newValue;
+    this.value.set(newValue);
+  }
+
+  clear(): void {
+    this.value.set('');
+    this.elementRef.nativeElement.value = '';
+    this.onChange('');
   }
 
   writeValue(value: string): void {
-    this.value = value;
-    if (typeof value === 'string') {
-      this.elementRef.nativeElement.value = value;
-    } else {
-      this.elementRef.nativeElement.value = '';
-    }
+    const parsedValue = typeof value === 'string' ? value : '';
+    this.value.set(parsedValue);
+    this.elementRef.nativeElement.value = parsedValue;
   }
 
   onChange: OnChangeType = () => {};

components/mention/mention.component.ts

@@ -49,6 +49,7 @@ import { merge, of as observableOf, Subscription } from 'rxjs';
 import { distinctUntilChanged, map, startWith, switchMap, withLatestFrom } from 'rxjs/operators';
 
 import { NzFormItemFeedbackIconComponent, NzFormNoStatusService, NzFormStatusService } from 'ng-zorro-antd/core/form';
+import { NzStringTemplateOutletDirective } from 'ng-zorro-antd/core/outlet';
 import { DEFAULT_MENTION_BOTTOM_POSITIONS, DEFAULT_MENTION_TOP_POSITIONS } from 'ng-zorro-antd/core/overlay';
 import { NgClassInterface, NzSafeAny, NzStatus, NzValidateStatus, NzVariant } from 'ng-zorro-antd/core/types';
 import {
@@ -120,6 +121,15 @@ export type MentionPlacement = 'top' | 'bottom';
     @if (hasFeedback && !!status) {
       <nz-form-item-feedback-icon class="ant-mentions-suffix" [status]="status" />
     }
+    @if (nzAllowClear && hasValue()) {
+      <span class="ant-mentions-suffix">
+        <button type="button" tabindex="-1" class="ant-mentions-clear-icon" (click)="clear()">
+          <ng-template [nzStringTemplateOutlet]="nzClearIcon">
+            <nz-icon nzType="close-circle" nzTheme="fill" />
+          </ng-template>
+        </button>
+      </span>
+    }
   `,
   changeDetection: ChangeDetectionStrategy.OnPush,
   host: {
@@ -131,7 +141,13 @@ export type MentionPlacement = 'top' | 'bottom';
     '[class.ant-mentions-focused]': `focused()`,
     '[class.ant-mentions-disabled]': `disabled()`
   },
-  imports: [NgTemplateOutlet, NzIconModule, NzEmptyModule, NzFormItemFeedbackIconComponent]
+  imports: [
+    NgTemplateOutlet,
+    NzIconModule,
+    NzEmptyModule,
+    NzFormItemFeedbackIconComponent,
+    NzStringTemplateOutletDirective
+  ]
 })
 export class NzMentionComponent implements OnInit, AfterViewInit, OnChanges {
   private ngZone = inject(NgZone);
@@ -150,8 +166,11 @@ export class NzMentionComponent implements OnInit, AfterViewInit, OnChanges {
   @Input() nzSuggestions: NzSafeAny[] = [];
   @Input() nzStatus: NzStatus = '';
   @Input() nzVariant: NzVariant = 'outlined';
+  @Input({ transform: booleanAttribute }) nzAllowClear = false;
+  @Input() nzClearIcon: TemplateRef<NzSafeAny> | null = null;
   @Output() readonly nzOnSelect = new EventEmitter<NzSafeAny>();
   @Output() readonly nzOnSearchChange = new EventEmitter<MentionOnSearchTypes>();
+  @Output() readonly nzOnClear = new EventEmitter<void>();
 
   @ViewChild(TemplateRef, { static: false }) suggestionsTemp?: TemplateRef<void>;
   @ViewChildren('items', { read: ElementRef })
@@ -181,6 +200,9 @@ export class NzMentionComponent implements OnInit, AfterViewInit, OnChanges {
   readonly disabled = computed(() => {
     return this.trigger().disabled();
   });
+  readonly hasValue = computed(() => {
+    return !!this.trigger()?.value().trim();
+  });
 
   private previousValue: string | null = null;
   private cursorMention: string | null = null;
@@ -285,7 +307,7 @@ export class NzMentionComponent implements OnInit, AfterViewInit, OnChanges {
   }
 
   getMentions(): string[] {
-    return this.trigger() ? getMentions(this.trigger().value!, this.nzPrefix) : [];
+    return this.trigger() ? getMentions(this.trigger().value(), this.nzPrefix) : [];
   }
 
   selectSuggestion(suggestion: string | {}): void {
@@ -300,10 +322,16 @@ export class NzMentionComponent implements OnInit, AfterViewInit, OnChanges {
     this.activeIndex = -1;
   }
 
+  clear(): void {
+    this.closeDropdown();
+    this.trigger().clear();
+    this.nzOnClear.emit();
+  }
+
   private handleInput(event: KeyboardEvent): void {
     const target = event.target as HTMLInputElement | HTMLTextAreaElement;
     this.trigger().onChange(target.value);
-    this.trigger().value = target.value;
+    this.trigger().value.set(target.value);
     this.resetDropdown();
   }
 

components/mention/mention.spec.ts

@@ -664,6 +664,88 @@ describe('mention', () => {
       });
     }));
   });
+
+  describe('clear button', () => {
+    let fixture: ComponentFixture<NzTestClearMentionComponent>;
+    let textarea: HTMLTextAreaElement;
+
+    beforeEach(fakeAsync(() => {
+      fixture = TestBed.createComponent(NzTestClearMentionComponent);
+      fixture.detectChanges();
+      textarea = fixture.debugElement.query(By.css('textarea')).nativeElement;
+      tick();
+    }));
+
+    it('should not show clear button when nzAllowClear is false', fakeAsync(() => {
+      fixture.componentInstance.allowClear = false;
+      fixture.detectChanges();
+      typeInElement('test value', textarea);
+      fixture.detectChanges();
+      tick();
+      expect(fixture.debugElement.query(By.css('.ant-mentions-clear-icon'))).toBeNull();
+    }));
+
+    it('should show clear button when nzAllowClear is true and has value', fakeAsync(() => {
+      fixture.componentInstance.allowClear = true;
+      fixture.detectChanges();
+      typeInElement('test value', textarea);
+      fixture.detectChanges();
+      tick();
+      expect(fixture.debugElement.query(By.css('.ant-mentions-clear-icon'))).toBeTruthy();
+    }));
+
+    it('should not show clear button when nzAllowClear is true but has no value', fakeAsync(() => {
+      fixture.componentInstance.allowClear = true;
+      fixture.detectChanges();
+      typeInElement('', textarea);
+      fixture.detectChanges();
+      tick();
+      expect(fixture.debugElement.query(By.css('.ant-mentions-clear-icon'))).toBeNull();
+    }));
+
+    it('should clear input value when clear button is clicked', fakeAsync(() => {
+      fixture.componentInstance.allowClear = true;
+      fixture.detectChanges();
+      typeInElement('test value', textarea);
+      fixture.detectChanges();
+      tick();
+
+      const clearButton = fixture.debugElement.query(By.css('.ant-mentions-clear-icon')).nativeElement;
+      clearButton.click();
+      fixture.detectChanges();
+      tick();
+
+      expect(textarea.value).toBe('');
+      expect(fixture.componentInstance.inputValue).toBe('');
+    }));
+
+    it('should emit nzOnClear when clear button is clicked', fakeAsync(() => {
+      const spy = spyOn(fixture.componentInstance, 'onClear');
+      fixture.componentInstance.allowClear = true;
+      fixture.detectChanges();
+      typeInElement('test value', textarea);
+      fixture.detectChanges();
+      tick();
+
+      const clearButton = fixture.debugElement.query(By.css('.ant-mentions-clear-icon')).nativeElement;
+      clearButton.click();
+      fixture.detectChanges();
+
+      expect(spy).toHaveBeenCalled();
+    }));
+
+    it('should use custom clear icon when provided', fakeAsync(() => {
+      fixture.componentInstance.allowClear = true;
+      fixture.componentInstance.useCustomClearIcon = true;
+      fixture.detectChanges();
+      typeInElement('test value', textarea);
+      fixture.detectChanges();
+      tick();
+
+      const clearIcon = fixture.debugElement.query(By.css('.custom-clear-icon'));
+      expect(clearIcon).toBeTruthy();
+    }));
+  });
 });
 
 @Component({
@@ -806,6 +888,33 @@ class NzTestVariantMentionComponent {
   @ViewChild(NzMentionComponent, { static: false }) mention!: NzMentionComponent;
 }
 
+@Component({
+  imports: [FormsModule, NzInputModule, NzMentionModule],
+  template: `
+    <nz-mention
+      [nzSuggestions]="suggestions"
+      [nzAllowClear]="allowClear"
+      [nzClearIcon]="useCustomClearIcon ? clearIconTemplate : null"
+      (nzOnClear)="onClear()"
+    >
+      <textarea nz-input [nzAutosize]="{ minRows: 4, maxRows: 4 }" [(ngModel)]="inputValue" nzMentionTrigger></textarea>
+      <ng-template #clearIconTemplate>
+        <span class="custom-clear-icon">×</span>
+      </ng-template>
+    </nz-mention>
+  `
+})
+class NzTestClearMentionComponent {
+  inputValue = '';
+  suggestions = ['angular', 'ant-design', 'mention'];
+  allowClear = false;
+  useCustomClearIcon = false;
+
+  @ViewChild(NzMentionComponent, { static: false }) mention!: NzMentionComponent;
+
+  onClear(): void {}
+}
+
 class MockDirectionality {
   value = 'ltr';
   change = new Subject();

components/mention/style/index.less

@@ -64,9 +64,11 @@
     border: none;
     outline: none;
     resize: none;
+
     & when (@theme = dark) {
       background-color: transparent;
     }
+
     .placeholder();
   }
 
@@ -175,6 +177,23 @@
     align-items: center;
     margin: auto;
   }
+
+  &-clear-icon {
+    padding: 0;
+    color: @disabled-color;
+    font-size: @font-size-sm;
+    line-height: 0;
+    vertical-align: -1px;
+    background-color: transparent;
+    border: none;
+    outline: none;
+    cursor: pointer;
+    transition: color 0.3s;
+
+    &:hover {
+      color: @text-color-secondary;
+    }
+  }
 }
 
 @import './rtl';