• Transfer穿梭框
    • 何时使用
    • 单独引入此组件
    • 代码演示
    • API
      • nz-transfercomponent
        • TransferItem
        • TransferCanMove
        • TransferChange
        • TransferSearchChange
        • nzRenderList

    Transfer穿梭框

    双栏穿梭选择框。

    何时使用

    用直观的方式在两栏中移动元素，完成选择行为。

    选择一个或以上的选项后，点击对应的方向键，可以把选中的选项移动到另一栏。其中，左边一栏为 source，右边一栏为 target，API 的设计也反映了这两个概念。

    单独引入此组件

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

    1. import { NzTransferModule } from 'ng-zorro-antd/transfer';

    代码演示

    Transfer穿梭框 - 图1

    基本用法

    最基本的用法，展示了 nzDataSource 每行的渲染函数 nzRender 以及回调函数 nzChange、nzSelectChange 的用法。

    1. import { Component, OnInit } from '@angular/core';
    3. @Component({
    4.   selector: 'nz-demo-transfer-basic',
    5.   template: `
    6.     <nz-transfer
    7.       [nzDataSource]="list"
    8.       [nzDisabled]="disabled"
    9.       [nzTitles]="['Source', 'Target']"
    10.       (nzSelectChange)="select($event)"
    11.       (nzChange)="change($event)"
    12.     >
    13.     </nz-transfer>
    14.     <div style="margin-top: 8px;">
    15.       <nz-switch [(ngModel)]="disabled" nzCheckedChildren="disabled" nzUnCheckedChildren="disabled"></nz-switch>
    16.       <div></div>
    17.     </div>
    18.   `
    19. })
    20. export class NzDemoTransferBasicComponent implements OnInit {
    21.   // tslint:disable-next-line:no-any
    22.   list: any[] = [];
    23.   disabled = false;
    25.   ngOnInit(): void {
    26.     for (let i = 0; i < 20; i++) {
    27.       this.list.push({
    28.         key: i.toString(),
    29.         title: `content${i + 1}`,
    30.         disabled: i % 3 < 1
    31.       });
    32.     }
    34.     [2, 3].forEach(idx => (this.list[idx].direction = 'right'));
    35.   }
    37.   select(ret: {}): void {
    38.     console.log('nzSelectChange', ret);
    39.   }
    41.   change(ret: {}): void {
    42.     console.log('nzChange', ret);
    43.   }
    44. }

    Transfer穿梭框 - 图2

    带搜索框

    带搜索框的穿梭框，可以自定义搜索函数。

    1. import { Component, OnInit } from '@angular/core';
    3. @Component({
    4.   selector: 'nz-demo-transfer-search',
    5.   template: `
    6.     <nz-transfer
    7.       [nzDataSource]="list"
    8.       [nzDisabled]="disabled"
    9.       nzShowSearch
    10.       [nzFilterOption]="filterOption"
    11.       (nzSearchChange)="search($event)"
    12.       (nzSelectChange)="select($event)"
    13.       (nzChange)="change($event)"
    14.     >
    15.     </nz-transfer>
    16.     <div style="margin-top: 8px;">
    17.       <nz-switch [(ngModel)]="disabled" nzCheckedChildren="disabled" nzUnCheckedChildren="disabled"></nz-switch>
    18.       <div></div>
    19.     </div>
    20.   `
    21. })
    22. export class NzDemoTransferSearchComponent implements OnInit {
    23.   // tslint:disable-next-line:no-any
    24.   list: any[] = [];
    25.   disabled = false;
    27.   ngOnInit(): void {
    28.     for (let i = 0; i < 20; i++) {
    29.       this.list.push({
    30.         key: i.toString(),
    31.         title: `content${i + 1}`,
    32.         description: `description of content${i + 1}`,
    33.         direction: Math.random() * 2 > 1 ? 'right' : ''
    34.       });
    35.     }
    36.   }
    38.   // tslint:disable-next-line:no-any
    39.   filterOption(inputValue: string, item: any): boolean {
    40.     return item.description.indexOf(inputValue) > -1;
    41.   }
    43.   search(ret: {}): void {
    44.     console.log('nzSearchChange', ret);
    45.   }
    47.   select(ret: {}): void {
    48.     console.log('nzSelectChange', ret);
    49.   }
    51.   change(ret: {}): void {
    52.     console.log('nzChange', ret);
    53.   }
    54. }

    Transfer穿梭框 - 图3

    高级用法

    穿梭框高级用法，可配置操作文案，可定制宽高，可对底部进行自定义渲染。

    1. import { Component, OnInit } from '@angular/core';
    2. import { NzMessageService } from 'ng-zorro-antd/message';
    4. @Component({
    5.   selector: 'nz-demo-transfer-advanced',
    6.   template: `
    7.     <nz-transfer
    8.       [nzDataSource]="list"
    9.       nzShowSearch
    10.       [nzOperations]="['to right', 'to left']"
    11.       [nzListStyle]="{ 'width.px': 250, 'height.px': 300 }"
    12.       [nzRender]="render"
    13.       [nzFooter]="footer"
    14.       (nzSelectChange)="select($event)"
    15.       (nzChange)="change($event)"
    16.     >
    17.       <ng-template #render let-item> {{ item.title }}-{{ item.description }} </ng-template>
    18.       <ng-template #footer let-direction>
    19.         <button nz-button (click)="reload(direction)" [nzSize]="'small'" style="float: right; margin: 5px;">
    20.           reload
    21.         </button>
    22.       </ng-template>
    23.     </nz-transfer>
    24.   `
    25. })
    26. export class NzDemoTransferAdvancedComponent implements OnInit {
    27.   list: Array<{ key: string; title: string; description: string; direction: string }> = [];
    29.   ngOnInit(): void {
    30.     this.getData();
    31.   }
    33.   getData(): void {
    34.     const ret: Array<{ key: string; title: string; description: string; direction: string }> = [];
    35.     for (let i = 0; i < 20; i++) {
    36.       ret.push({
    37.         key: i.toString(),
    38.         title: `content${i + 1}`,
    39.         description: `description of content${i + 1}`,
    40.         direction: Math.random() * 2 > 1 ? 'right' : ''
    41.       });
    42.     }
    43.     this.list = ret;
    44.   }
    46.   reload(direction: string): void {
    47.     this.getData();
    48.     this.msg.success(`your clicked ${direction}!`);
    49.   }
    51.   select(ret: {}): void {
    52.     console.log('nzSelectChange', ret);
    53.   }
    55.   change(ret: {}): void {
    56.     console.log('nzChange', ret);
    57.   }
    59.   constructor(public msg: NzMessageService) {}
    60. }

    Transfer穿梭框 - 图4

    自定义渲染行数据

    自定义渲染每一个 Transfer Item，可用于渲染复杂数据。

    1. import { Component, OnInit } from '@angular/core';
    2. import { NzMessageService } from 'ng-zorro-antd/message';
    4. @Component({
    5.   selector: 'nz-demo-transfer-custom-item',
    6.   template: `
    7.     <nz-transfer
    8.       [nzDataSource]="list"
    9.       [nzListStyle]="{ 'width.px': 300, 'height.px': 300 }"
    10.       [nzRender]="render"
    11.       (nzSelectChange)="select($event)"
    12.       (nzChange)="change($event)"
    13.     >
    14.       <ng-template #render let-item> <i nz-icon nzType="{{ item.icon }}"></i> {{ item.title }} </ng-template>
    15.     </nz-transfer>
    16.   `
    17. })
    18. export class NzDemoTransferCustomItemComponent implements OnInit {
    19.   list: Array<{ key: string; title: string; description: string; direction: string; icon: string }> = [];
    21.   ngOnInit(): void {
    22.     this.getData();
    23.   }
    25.   getData(): void {
    26.     const ret: Array<{ key: string; title: string; description: string; direction: string; icon: string }> = [];
    27.     for (let i = 0; i < 20; i++) {
    28.       ret.push({
    29.         key: i.toString(),
    30.         title: `content${i + 1}`,
    31.         description: `description of content${i + 1}`,
    32.         direction: Math.random() * 2 > 1 ? 'right' : '',
    33.         icon: `frown-o`
    34.       });
    35.     }
    36.     this.list = ret;
    37.   }
    39.   select(ret: {}): void {
    40.     console.log('nzSelectChange', ret);
    41.   }
    43.   change(ret: {}): void {
    44.     console.log('nzChange', ret);
    45.   }
    47.   constructor(public msg: NzMessageService) {}
    48. }

    Transfer穿梭框 - 图5

    二次校验

    利用 nzCanMove 允许在穿梭过程中二次校验；示例默认向右移时强制选中的第一项不可穿梭。

    1. import { Component, OnInit } from '@angular/core';
    2. import { TransferCanMove, TransferItem } from 'ng-zorro-antd/transfer';
    3. import { of, Observable } from 'rxjs';
    4. import { delay } from 'rxjs/operators';
    6. @Component({
    7.   selector: 'nz-demo-transfer-can-move',
    8.   template: `
    9.     <nz-transfer
    10.       [nzDataSource]="list"
    11.       [nzCanMove]="canMove"
    12.       (nzSelectChange)="select($event)"
    13.       (nzChange)="change($event)"
    14.     >
    15.     </nz-transfer>
    16.   `
    17. })
    18. export class NzDemoTransferCanMoveComponent implements OnInit {
    19.   list: Array<{ key: string; title: string; disabled: boolean; direction?: string }> = [];
    21.   ngOnInit(): void {
    22.     for (let i = 0; i < 20; i++) {
    23.       this.list.push({
    24.         key: i.toString(),
    25.         title: `content${i + 1}`,
    26.         disabled: i % 3 < 1
    27.       });
    28.     }
    30.     [2, 3].forEach(idx => (this.list[idx].direction = 'right'));
    31.   }
    33.   canMove(arg: TransferCanMove): Observable<TransferItem[]> {
    34.     if (arg.direction === 'right' && arg.list.length > 0) {
    35.       arg.list.splice(0, 1);
    36.     }
    37.     // or
    38.     // if (arg.direction === 'right' && arg.list.length > 0) delete arg.list[0];
    39.     return of(arg.list).pipe(delay(1000));
    40.   }
    42.   select(ret: {}): void {
    43.     console.log('nzSelectChange', ret);
    44.   }
    46.   change(ret: {}): void {
    47.     console.log('nzChange', ret);
    48.   }
    49. }

    Transfer穿梭框 - 图6

    表格穿梭框

    使用 Table 组件作为自定义渲染列表。

    1. import { Component, OnInit } from '@angular/core';
    2. import { TransferItem } from 'ng-zorro-antd/transfer';
    4. @Component({
    5.   selector: 'nz-demo-transfer-table-transfer',
    6.   template: `
    7.     <nz-transfer
    8.       [nzDataSource]="list"
    9.       [nzDisabled]="disabled"
    10.       [nzShowSearch]="showSearch"
    11.       [nzShowSelectAll]="false"
    12.       [nzRenderList]="[renderList, renderList]"
    13.       (nzSelectChange)="select($event)"
    14.       (nzChange)="change($event)"
    15.     >
    16.       <ng-template
    17.         #renderList
    18.         let-items
    19.         let-direction="direction"
    20.         let-stat="stat"
    21.         let-disabled="disabled"
    22.         let-onItemSelectAll="onItemSelectAll"
    23.         let-onItemSelect="onItemSelect"
    24.       >
    25.         <nz-table #t [nzData]="convertItems(items)" nzSize="small">
    26.           <thead>
    27.             <tr>
    28.               <th
    29.                 nzShowCheckbox
    30.                 [nzDisabled]="disabled"
    31.                 [nzChecked]="stat.checkAll"
    32.                 [nzIndeterminate]="stat.checkHalf"
    33.                 (nzCheckedChange)="onItemSelectAll($event)"
    34.               ></th>
    35.               <th>Name</th>
    36.               <th *ngIf="direction === 'left'">Tag</th>
    37.               <th>Description</th>
    38.             </tr>
    39.           </thead>
    40.           <tbody>
    41.             <tr *ngFor="let data of t.data" (click)="onItemSelect(data)">
    42.               <td
    43.                 nzShowCheckbox
    44.                 [nzChecked]="data.checked"
    45.                 [nzDisabled]="disabled || data.disabled"
    46.                 (nzCheckedChange)="onItemSelect(data)"
    47.               ></td>
    48.               <td>{{ data.title }}</td>
    49.               <td *ngIf="direction === 'left'">
    50.                 <nz-tag>{{ data.tag }}</nz-tag>
    51.               </td>
    52.               <td>{{ data.description }}</td>
    53.             </tr>
    54.           </tbody>
    55.         </nz-table>
    56.       </ng-template>
    57.     </nz-transfer>
    58.     <div style="margin-top: 8px;">
    59.       <nz-switch [(ngModel)]="disabled" nzCheckedChildren="disabled" nzUnCheckedChildren="disabled"></nz-switch>
    60.       <nz-switch [(ngModel)]="showSearch" nzCheckedChildren="showSearch" nzUnCheckedChildren="showSearch"></nz-switch>
    61.     </div>
    62.   `
    63. })
    64. export class NzDemoTransferTableTransferComponent implements OnInit {
    65.   // tslint:disable-next-line:no-any
    66.   list: any[] = [];
    67.   disabled = false;
    68.   showSearch = false;
    70.   ngOnInit(): void {
    71.     for (let i = 0; i < 20; i++) {
    72.       this.list.push({
    73.         key: i.toString(),
    74.         title: `content${i + 1}`,
    75.         description: `description of content${i + 1}`,
    76.         disabled: i % 4 === 0,
    77.         tag: ['cat', 'dog', 'bird'][i % 3]
    78.       });
    79.     }
    81.     [2, 3].forEach(idx => (this.list[idx].direction = 'right'));
    82.   }
    84.   convertItems(items: TransferItem[]): TransferItem[] {
    85.     return items.filter(i => !i.hide);
    86.   }
    88.   select(ret: {}): void {
    89.     console.log('nzSelectChange', ret);
    90.   }
    92.   change(ret: {}): void {
    93.     console.log('nzChange', ret);
    94.   }
    95. }

    Transfer穿梭框 - 图7

    树穿梭框

    使用 Tree 组件作为自定义渲染列表。

    1. // tslint:disable: no-any
    2. import { ChangeDetectionStrategy, Component, ViewChild } from '@angular/core';
    3. import { NzTreeNode } from 'ng-zorro-antd/core';
    4. import { TransferChange, TransferItem } from 'ng-zorro-antd/transfer';
    5. import { NzTreeComponent } from 'ng-zorro-antd/tree';
    7. @Component({
    8.   selector: 'nz-demo-transfer-tree-transfer',
    9.   template: `
    10.     <nz-transfer
    11.       [nzDataSource]="list"
    12.       [nzShowSelectAll]="false"
    13.       [nzRenderList]="[leftRenderList, null]"
    14.       (nzChange)="change($event)"
    15.     >
    16.       <ng-template #leftRenderList let-items let-onItemSelectAll="onItemSelectAll" let-onItemSelect="onItemSelect">
    17.         <nz-tree #tree [nzData]="treeData" nzExpandAll nzBlockNode>
    18.           <ng-template #nzTreeTemplate let-node>
    19.             <span
    20.               class="ant-tree-checkbox"
    21.               [class.ant-tree-checkbox-disabled]="node.isDisabled"
    22.               [class.ant-tree-checkbox-checked]="node.isChecked"
    23.               (click)="checkBoxChange(node, onItemSelect)"
    24.             >
    25.               <span class="ant-tree-checkbox-inner"></span>
    26.             </span>
    27.             <span
    28.               (click)="checkBoxChange(node, onItemSelect)"
    29.               class="ant-tree-node-content-wrapper ant-tree-node-content-wrapper-open"
    30.               >{{ node.title }}</span
    31.             >
    32.           </ng-template>
    33.         </nz-tree>
    34.       </ng-template>
    35.     </nz-transfer>
    36.   `,
    37.   changeDetection: ChangeDetectionStrategy.OnPush
    38. })
    39. export class NzDemoTransferTreeTransferComponent {
    40.   @ViewChild('tree', { static: true }) tree: NzTreeComponent;
    41.   list: any[] = [
    42.     { id: 1, parentid: 0, title: 'parent 1' },
    43.     { id: 2, parentid: 1, title: 'leaf 1-1', disabled: true, isLeaf: true },
    44.     { id: 3, parentid: 1, title: 'leaf 1-2', isLeaf: true }
    45.   ];
    46.   treeData = this.generateTree(this.list);
    47.   checkedNodeList: NzTreeNode[] = [];
    49.   private generateTree(arr: TransferItem[]): TransferItem[] {
    50.     const tree: TransferItem[] = [];
    51.     const mappedArr: any = {};
    52.     let arrElem: TransferItem;
    53.     let mappedElem: TransferItem;
    55.     for (let i = 0, len = arr.length; i < len; i++) {
    56.       arrElem = arr[i];
    57.       mappedArr[arrElem.id] = { ...arrElem };
    58.       mappedArr[arrElem.id].children = [];
    59.     }
    61.     for (const id in mappedArr) {
    62.       if (mappedArr.hasOwnProperty(id)) {
    63.         mappedElem = mappedArr[id];
    64.         if (mappedElem.parentid) {
    65.           mappedArr[mappedElem.parentid].children.push(mappedElem);
    66.         } else {
    67.           tree.push(mappedElem);
    68.         }
    69.       }
    70.     }
    71.     return tree;
    72.   }
    74.   checkBoxChange(node: NzTreeNode, onItemSelect: (item: TransferItem) => void): void {
    75.     if (node.isDisabled) {
    76.       return;
    77.     }
    78.     node.isChecked = !node.isChecked;
    79.     if (node.isChecked) {
    80.       this.checkedNodeList.push(node);
    81.     } else {
    82.       const idx = this.checkedNodeList.indexOf(node);
    83.       if (idx !== -1) {
    84.         this.checkedNodeList.splice(idx, 1);
    85.       }
    86.     }
    87.     const item = this.list.find(w => w.id === node.origin.id);
    88.     onItemSelect(item);
    89.   }
    91.   change(ret: TransferChange): void {
    92.     const isDisabled = ret.to === 'right';
    93.     this.checkedNodeList.forEach(node => {
    94.       node.isDisabled = isDisabled;
    95.       node.isChecked = isDisabled;
    96.     });
    97.   }
    98. }

    API

    nz-transfercomponent

    参数说明类型默认值
    [nzDataSource]数据源，其中若数据属性 direction: 'right' 将会被渲染到右边一栏中或使用 nzTargetKeysTransferItem[][]
    [nzDisabled]是否禁用booleanfalse
    [nzTitles]标题集合，顺序从左至右string[]['', '']
    [nzOperations]操作文案集合，顺序从下至上string[]['', '']
    [nzListStyle]两个穿梭框的自定义样式，等同 ngStyleobject-
    [nzItemUnit]单数单位string'项目'
    [nzItemsUnit]复数单位string'项目'
    [nzRenderList]自定义渲染列表，见示例Array<TemplateRef<void> | null>[null, null]
    [nzRender]每行数据渲染模板，见示例TemplateRef<void>-
    [nzFooter]底部渲染模板，见示例TemplateRef<void>-
    [nzShowSearch]是否显示搜索框booleanfalse
    [nzFilterOption]接收 inputValueoption 两个参数，当 option 符合筛选条件时，应返回 true，反之则返回 false。(inputValue: string, item: TransferItem) => boolean-
    [nzSearchPlaceholder]搜索框的默认值string'请输入搜索内容'
    [nzNotFoundContent]当列表为空时显示的内容string'列表为空'
    [nzCanMove]穿梭时二次校验。注意： 穿梭组件内部始终只保留一份数据，二次校验过程中需取消穿梭项则直接删除该项；具体用法见示例。(arg: TransferCanMove) => Observable<TransferItem[]>-
    [nzTargetKeys]显示在右侧框数据的 key 集合string[]-
    (nzChange)选项在两栏之间转移时的回调函数EventEmitter<TransferChange>-
    (nzSearchChange)搜索框内容时改变时的回调函数EventEmitter<TransferSearchChange>-
    (nzSelectChange)选中项发生改变时的回调函数EventEmitter<TransferSearchChange>-

    TransferItem

    参数说明类型默认值
    title标题，用于显示及搜索关键字判断string-
    direction指定数据方向，若指定 right 为右栏，其他情况为左栏'left' | 'right'-
    disabled指定checkbox为不可用状态booleanfalse
    checked指定checkbox为选中状态booleanfalse

    TransferCanMove

    参数说明类型默认值
    direction数据方向'left' | 'right'-
    list数据源TransferItem[][]

    TransferChange

    参数说明类型默认值
    from数据方向'left' | 'right'-
    to数据方向'left' | 'right'-
    list数据源TransferItem[][]

    TransferSearchChange

    参数说明类型默认值
    direction数据方向'left' | 'right'-
    value搜索关键词string-

    nzRenderList

    参数说明类型默认值
    direction渲染列表的方向'left' | 'right'-
    disabled是否禁用列表boolean-
    items过滤后的数据TransferItem[]-
    onItemSelect勾选条目(item: TransferItem) => void-
    onItemSelectAll勾选一组条目(selected: boolean) => void-