• Mention提及
    • 何时使用
    • 单独引入此组件
    • 代码演示
    • API
      • nz-mentioncomponent
        • 方法
      • nzMentionTrigger
      • nzMentionSuggestion
      • MentionOnSearchTypes

    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-