Mention提及

提及组件。

何时使用

用于在输入中提及某人或某事，常用于发布、聊天或评论功能。

单独引入此组件

想要了解更多关于单独引入组件的内容，可以在快速上手页面进行查看。

  1. import { NzMentionModule } from 'ng-zorro-antd/mention';

代码演示

Mention提及 - 图1

基本使用

基本使用

  1. import { Component, ViewEncapsulation } from '@angular/core';
  3. @Component({
  4.   selector: 'nz-demo-mention-basic',
  5.   encapsulation: ViewEncapsulation.None,
  6.   template: `
  7.     <nz-mention [nzSuggestions]="suggestions" (nzOnSelect)="onSelect($event)">
  8.       <input
  9.         placeholder="input here"
  10.         nzMentionTrigger
  11.         nz-input
  12.         [(ngModel)]="inputValue"
  13.         (ngModelChange)="onChange($event)"
  14.       />
  15.     </nz-mention>
  16.   `
  17. })
  18. export class NzDemoMentionBasicComponent {
  19.   inputValue: string = '@afc163';
  20.   suggestions = ['afc163', 'benjycui', 'yiminghe', 'RaoHai', '中文', 'にほんご'];
  22.   onChange(value: string): void {
  23.     console.log(value);
  24.   }
  26.   onSelect(suggestion: string): void {
  27.     console.log(`onSelect ${suggestion}`);
  28.   }
  29. }

Mention提及 - 图2

异步加载

匹配内容列表为异步返回时。

  1. import { Component, ViewEncapsulation } from '@angular/core';
  2. import { MentionOnSearchTypes } from 'ng-zorro-antd/mention';
  4. @Component({
  5.   selector: 'nz-demo-mention-async',
  6.   encapsulation: ViewEncapsulation.None,
  7.   template: `
  8.     <nz-mention [nzSuggestions]="suggestions" [nzLoading]="loading" (nzOnSearchChange)="onSearchChange($event)">
  9.       <input nzMentionTrigger nz-input [(ngModel)]="inputValue" />
  10.     </nz-mention>
  11.   `
  12. })
  13. export class NzDemoMentionAsyncComponent {
  14.   inputValue: string;
  15.   loading = false;
  16.   suggestions: string[] = [];
  18.   onSearchChange({ value }: MentionOnSearchTypes): void {
  19.     console.log(`search: ${value}`);
  20.     this.loading = true;
  21.     this.fetchSuggestions(value, suggestions => {
  22.       console.log(suggestions);
  23.       this.suggestions = suggestions;
  24.       this.loading = false;
  25.     });
  26.   }
  28.   fetchSuggestions(value: string, callback: (suggestions: string[]) => void): void {
  29.     const users = ['afc163', 'benjycui', 'yiminghe', 'jljsj33', 'dqaria', 'RaoHai'];
  30.     setTimeout(() => {
  31.       return callback(users.filter(item => item.indexOf(value) !== -1));
  32.     }, 500);
  33.   }
  34. }

Mention提及 - 图3

头像

自定义建议（含头像）

注意，nzSuggestions 不为 string[] 时，需要提供 valueWith。

  1. import { Component, ViewEncapsulation } from '@angular/core';
  3. @Component({
  4.   selector: 'nz-demo-mention-avatar',
  5.   encapsulation: ViewEncapsulation.None,
  6.   template: `
  7.     <nz-mention [nzSuggestions]="webFrameworks" [nzValueWith]="valueWith" (nzOnSelect)="onSelect($event)">
  8.       <input nz-input nzMentionTrigger [(ngModel)]="inputValue" />
  9.       <ng-container *nzMentionSuggestion="let framework">
  10.         <nz-avatar nzSize="small" [nzText]="framework.name" [nzSrc]="framework.icon"></nz-avatar>
  11.         <span>{{ framework.name }} - {{ framework.type }}</span>
  12.       </ng-container>
  13.     </nz-mention>
  14.   `,
  15.   styles: [
  16.     `
  17.       .ant-avatar.ant-avatar-sm {
  18.         width: 14px;
  19.         height: 14px;
  20.         margin-right: 8px;
  21.         position: relative;
  22.       }
  23.     `
  24.   ]
  25. })
  26. export class NzDemoMentionAvatarComponent {
  27.   inputValue: string;
  28.   webFrameworks = [
  29.     { name: 'React', type: 'JavaScript', icon: 'https://zos.alipayobjects.com/rmsportal/LFIeMPzdLcLnEUe.svg' },
  30.     { name: 'Angular', type: 'JavaScript', icon: 'https://zos.alipayobjects.com/rmsportal/PJTbxSvzYWjDZnJ.png' },
  31.     { name: 'Dva', type: 'Javascript', icon: 'https://zos.alipayobjects.com/rmsportal/EYPwSeEJKxDtVxI.png' },
  32.     { name: 'Flask', type: 'Python', icon: 'https://zos.alipayobjects.com/rmsportal/xaypBUijfnpAlXE.png' }
  33.   ];
  35.   valueWith = (data: { name: string; type: string; icon: string }) => data.name;
  37.   onSelect(value: string): void {
  38.     console.log(value);
  39.   }
  40. }

Mention提及 - 图4

多行

多行模式。

  1. import { Component, ViewEncapsulation } from '@angular/core';
  3. @Component({
  4.   selector: 'nz-demo-mention-multilines',
  5.   encapsulation: ViewEncapsulation.None,
  6.   template: `
  7.     <nz-mention [nzSuggestions]="suggestions">
  8.       <textarea nz-input [nzAutosize]="{ minRows: 4, maxRows: 4 }" [(ngModel)]="inputValue" nzMentionTrigger>
  9.       </textarea>
  10.     </nz-mention>
  11.   `
  12. })
  13. export class NzDemoMentionMultilinesComponent {
  14.   inputValue: string;
  15.   suggestions = ['afc163', 'benjycui', 'yiminghe', 'RaoHai', '中文', 'にほんご'];
  16. }

Mention提及 - 图5

自定义触发字符

通过 nzPrefix 属性自定义触发字符。默认为 @, 可以定义为数组。

  1. import { Component, ViewEncapsulation } from '@angular/core';
  2. import { MentionOnSearchTypes } from 'ng-zorro-antd/mention';
  4. @Component({
  5.   selector: 'nz-demo-mention-multiple-trigger',
  6.   encapsulation: ViewEncapsulation.None,
  7.   template: `
  8.     <nz-mention [nzSuggestions]="suggestions" (nzOnSearchChange)="onSearchChange($event)" [nzPrefix]="['#', '@']">
  9.       <input
  10.         placeholder="input @ to mention people, # to mention tag"
  11.         nzMentionTrigger
  12.         nz-input
  13.         [(ngModel)]="inputValue"
  14.       />
  15.     </nz-mention>
  16.   `
  17. })
  18. export class NzDemoMentionMultipleTriggerComponent {
  19.   inputValue: string;
  20.   suggestions: string[] = [];
  21.   users = ['afc163', 'benjycui', 'yiminghe', 'RaoHai', '中文', 'にほんご'];
  22.   tags = ['1.0', '2.0', '3.0'];
  24.   onSearchChange({ value, prefix }: MentionOnSearchTypes): void {
  25.     console.log('nzOnSearchChange', value, prefix);
  26.     this.suggestions = prefix === '@' ? this.users : this.tags;
  27.   }
  28. }

Mention提及 - 图6

向上展开

向上展开建议。

  1. import { Component, ViewEncapsulation } from '@angular/core';
  3. @Component({
  4.   selector: 'nz-demo-mention-placement',
  5.   encapsulation: ViewEncapsulation.None,
  6.   template: `
  7.     <nz-mention nzPlacement="top" [nzSuggestions]="suggestions" (nzOnSelect)="onSelect($event)">
  8.       <input nzMentionTrigger nz-input [(ngModel)]="inputValue" (ngModelChange)="onChange($event)" />
  9.     </nz-mention>
  10.   `
  11. })
  12. export class NzDemoMentionPlacementComponent {
  13.   inputValue: string;
  14.   suggestions = ['afc163', 'benjycui', 'yiminghe', 'RaoHai', '中文', 'にほんご'];
  16.   onChange(value: string): void {
  17.     console.log(value);
  18.   }
  20.   onSelect(suggestion: string): void {
  21.     console.log(`onSelect ${suggestion}`);
  22.   }
  23. }

Mention提及 - 图7

自定义建议

自定义建议

注意，nzSuggestions 不为 string[] 时，需要提供 valueWith。

  1. import { Component, ViewEncapsulation } from '@angular/core';
  3. @Component({
  4.   selector: 'nz-demo-mention-custom-tag',
  5.   encapsulation: ViewEncapsulation.None,
  6.   template: `
  7.     <nz-mention [nzSuggestions]="webFrameworks" [nzValueWith]="valueWith" (nzOnSelect)="onSelect($event)">
  8.       <input placeholder="@someone" nz-input nzMentionTrigger [(ngModel)]="inputValue" />
  9.       <ng-container *nzMentionSuggestion="let framework">
  10.         <span>{{ framework.name }} - {{ framework.type }}</span>
  11.       </ng-container>
  12.     </nz-mention>
  13.   `
  14. })
  15. export class NzDemoMentionCustomTagComponent {
  16.   inputValue: string;
  17.   webFrameworks = [
  18.     { name: 'React', type: 'JavaScript' },
  19.     { name: 'Angular', type: 'JavaScript' },
  20.     { name: 'Laravel', type: 'PHP' },
  21.     { name: 'Flask', type: 'Python' },
  22.     { name: 'Django', type: 'Python' }
  23.   ];
  25.   valueWith = (data: { name: string; type: string }) => data.name;
  27.   onSelect(value: string): void {
  28.     console.log(value);
  29.   }
  30. }

Mention提及 - 图8

配合 Form 使用

受控模式，例如配合 Form 使用。

  1. import { Component, OnInit, ViewChild, ViewEncapsulation } from '@angular/core';
  2. import { AbstractControl, FormBuilder, FormControl, FormGroup, Validators } from '@angular/forms';
  4. @Component({
  5.   selector: 'nz-demo-mention-controlled',
  6.   encapsulation: ViewEncapsulation.None,
  7.   template: `
  8.     <form nz-form [formGroup]="validateForm" (ngSubmit)="submitForm()">
  9.       <nz-form-item>
  10.         <nz-form-label [nzSm]="6" nzFor="mention">Top coders</nz-form-label>
  11.         <nz-form-control [nzSm]="16" nzErrorTip="More than one must be selected!">
  12.           <nz-mention #mentions [nzSuggestions]="suggestions">
  13.             <input id="mention" placeholder="input here" formControlName="mention" nzMentionTrigger nz-input />
  14.           </nz-mention>
  15.         </nz-form-control>
  16.       </nz-form-item>
  17.       <nz-form-item nz-row style="margin-bottom:8px;">
  18.         <nz-form-control [nzSpan]="14" [nzOffset]="6">
  19.           <button type="button" nz-button nzType="primary" (click)="submitForm()">Submit</button>
  20.           &nbsp;&nbsp;&nbsp;
  21.           <button type="button" nz-button (click)="resetForm()">Reset</button>
  22.         </nz-form-control>
  23.       </nz-form-item>
  24.     </form>
  25.   `
  26. })
  27. export class NzDemoMentionControlledComponent implements OnInit {
  28.   suggestions = ['afc163', 'benjycui', 'yiminghe', 'RaoHai', '中文', 'にほんご'];
  29.   validateForm: FormGroup;
  30.   @ViewChild('mentions', { static: true }) mentionChild: any;
  32.   get mention(): AbstractControl {
  33.     return this.validateForm.get('mention')!;
  34.   }
  36.   constructor(private fb: FormBuilder) {}
  38.   ngOnInit(): void {
  39.     this.validateForm = this.fb.group({
  40.       mention: ['@afc163 ', [Validators.required, this.mentionValidator]]
  41.     });
  42.   }
  44.   mentionValidator = (control: FormControl): { [s: string]: boolean } => {
  45.     if (!control.value) {
  46.       return { required: true };
  47.     } else if (this.mentionChild.getMentions().length < 2) {
  48.       return { confirm: true, error: true };
  49.     }
  50.     return {};
  51.   };
  53.   submitForm(): void {
  54.     this.mention.markAsDirty();
  55.     this.mention.updateValueAndValidity();
  56.     if (this.mention.valid) {
  57.       console.log('Submit!!!', this.mention.value);
  58.       console.log(this.mentionChild.getMentions());
  59.     } else {
  60.       console.log('Errors in form!!!');
  61.     }
  62.   }
  64.   resetForm(): void {
  65.     this.validateForm.reset({
  66.       mention: '@afc163 '
  67.     });
  68.   }
  69. }

Mention提及 - 图9

无效或只读

通过 disabled 属性设置是否生效。通过 readOnly 属性设置是否只读。

  1. import { Component, ViewEncapsulation } from '@angular/core';
  3. @Component({
  4.   selector: 'nz-demo-mention-readonly',
  5.   encapsulation: ViewEncapsulation.None,
  6.   template: `
  7.     <nz-mention [nzSuggestions]="suggestions">
  8.       <input
  9.         style="margin-bottom: 10px"
  10.         placeholder="this is disabled Mention"
  11.         nzMentionTrigger
  12.         nz-input
  13.         disabled
  14.         [(ngModel)]="inputValue"
  15.       />
  16.       <input placeholder="this is readOnly Mention" nzMentionTrigger nz-input readOnly [(ngModel)]="inputValue" />
  17.     </nz-mention>
  18.   `
  19. })
  20. export class NzDemoMentionReadonlyComponent {
  21.   inputValue: string;
  22.   suggestions = ['afc163', 'benjycui', 'yiminghe', 'RaoHai', '中文', 'にほんご'];
  23. }

Mention提及 - 图10

预览

渲染提及

  1. import { Component, ViewEncapsulation } from '@angular/core';
  2. import { DomSanitizer, SafeHtml } from '@angular/platform-browser';
  3. @Component({
  4.   selector: 'nz-demo-mention-preview',
  5.   encapsulation: ViewEncapsulation.None,
  6.   template: `
  7.     <nz-tabset>
  8.       <nz-tab nzTitle="Write">
  9.         <nz-mention [nzSuggestions]="suggestions">
  10.           <textarea
  11.             nz-input
  12.             [nzAutosize]="{ minRows: 4, maxRows: 4 }"
  13.             [(ngModel)]="inputValue"
  14.             (ngModelChange)="renderPreView()"
  15.             nzMentionTrigger
  16.           >
  17.           </textarea>
  18.         </nz-mention>
  19.       </nz-tab>
  20.       <nz-tab nzTitle="Preview">
  21.         <pre [innerHTML]="preview"></pre>
  22.       </nz-tab>
  23.     </nz-tabset>
  24.   `
  25. })
  26. export class NzDemoMentionPreviewComponent {
  27.   inputValue: string = 'Switch tab view preview @NG-ZORRO ';
  28.   preview: SafeHtml;
  29.   suggestions = ['NG-ZORRO', 'angular', 'Reactive-Extensions'];
  31.   constructor(private sanitizer: DomSanitizer) {
  32.     this.renderPreView();
  33.   }
  35.   getRegExp(prefix: string | string[]): RegExp {
  36.     const prefixArray = Array.isArray(prefix) ? prefix : [prefix];
  37.     let prefixToken = prefixArray.join('').replace(/(\$|\^)/g, '\\$1');
  39.     if (prefixArray.length > 1) {
  40.       prefixToken = `[${prefixToken}]`;
  41.     }
  43.     return new RegExp(`(\\s|^)(${prefixToken})[^\\s]*`, 'g');
  44.   }
  46.   renderPreView(): void {
  47.     if (this.inputValue) {
  48.       const regex = this.getRegExp('@');
  49.       const previewValue = this.inputValue.replace(
  50.         regex,
  51.         match => `<a target="_blank" href="https://github.com/${match.trim().substring(1)}">${match}</a>`
  52.       );
  53.       this.preview = this.sanitizer.bypassSecurityTrustHtml(previewValue);
  54.     }
  55.   }
  56. }

API

  1. <nz-mention [nzSuggestions]="suggestions">
  2.  <textarea
  3.     nz-input
  4.     [(ngModel)]="value"
  5.     nzMentionTrigger>
  6.   </textarea>
  7. </nz-mention>

nz-mentioncomponent

参数说明类型默认值
[nzMentionTrigger]用于指定提及的触发元素 (必须)HTMLTextAreaElement | HTMLInputElement-
[nzMentionSuggestion]自定义建议渲染模板TemplateRef<any>-
[nzLoading]加载中booleanfalse
[nzNotFoundContent]未找到时的内容string'无匹配结果，轻敲空格完成输入'
[nzPlacement]建议框位置'button' | 'top''bottom'
[nzPrefix]触发弹出下拉框的字符string | string[]'@'
[nzSuggestions]建议内容any[][]
[nzValueWith]建议选项的取值方法(any) => string | (value: string) => string
(nzOnSelect)下拉框选择建议时回调EventEmitter<any>-
(nzOnSearchChange)输入框中 @ 变化时回调EventEmitter<MentionOnSearchTypes>-

方法

方法名说明
getMentions获取 input[nzMentionTrigger] 中的提及数组

nzMentionTrigger

用于指定提及的触发元素

  1. <nz-mention>
  2.  <textarea nzMentionTrigger></textarea>
  3. </nz-mention>
  1. <nz-mention>
  2.  <input nzMentionTrigger>
  3. </nz-mention>

nzMentionSuggestion

自定义建议渲染模板

  1.   <nz-mention
  2.     [nzSuggestions]="items"
  3.     [nzValueWith]="valueWith">
  4.     <input nz-input nzMentionTrigger>
  5.     <ng-container *nzMentionSuggestion="let item">
  6.         <span>{{ item.label }} - {{ item.value }}</span>
  7.     </ng-container>
  8.   </nz-mention>

MentionOnSearchTypes

参数说明类型默认值
value搜索关键词string-
prefix触发前缀string-