Transfer穿梭框

双栏穿梭选择框。

何时使用

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

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

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

代码演示Transfer穿梭框 - 图2

Transfer穿梭框 - 图3

基本用法

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

  1. import { Component, OnInit } from '@angular/core';
  2. import { TransferItem } from 'ng-zorro-antd/transfer';
  4. @Component({
  5.   selector: 'nz-demo-transfer-basic',
  6.   template: `
  7.     <nz-transfer
  8.       [nzDataSource]="list"
  9.       [nzDisabled]="disabled"
  10.       [nzTitles]="['Source', 'Target']"
  11.       (nzSelectChange)="select($event)"
  12.       [nzSelectedKeys]="['0', '2']"
  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 NzDemoTransferBasicComponent implements OnInit {
  23.   list: TransferItem[] = [];
  24.   disabled = false;
  26.   ngOnInit(): void {
  27.     for (let i = 0; i < 20; i++) {
  28.       this.list.push({
  29.         key: i.toString(),
  30.         title: `content${i + 1}`,
  31.         disabled: i % 3 < 1
  32.       });
  33.     }
  35.     [2, 3].forEach(idx => (this.list[idx].direction = 'right'));
  36.   }
  38.   select(ret: {}): void {
  39.     console.log('nzSelectChange', ret);
  40.   }
  42.   change(ret: {}): void {
  43.     console.log('nzChange', ret);
  44.   }
  45. }

Transfer穿梭框 - 图4

带搜索框

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

  1. import { Component, OnInit } from '@angular/core';
  2. import { TransferItem } from 'ng-zorro-antd/transfer';
  4. @Component({
  5.   selector: 'nz-demo-transfer-search',
  6.   template: `
  7.     <nz-transfer
  8.       [nzDataSource]="list"
  9.       [nzDisabled]="disabled"
  10.       nzShowSearch
  11.       [nzFilterOption]="filterOption"
  12.       (nzSearchChange)="search($event)"
  13.       (nzSelectChange)="select($event)"
  14.       (nzChange)="change($event)"
  15.     >
  16.     </nz-transfer>
  17.     <div style="margin-top: 8px;">
  18.       <nz-switch [(ngModel)]="disabled" nzCheckedChildren="disabled" nzUnCheckedChildren="disabled"></nz-switch>
  19.       <div></div>
  20.     </div>
  21.   `
  22. })
  23. export class NzDemoTransferSearchComponent implements OnInit {
  24.   list: TransferItem[] = [];
  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' : undefined
  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穿梭框 - 图5

高级用法

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

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

Transfer穿梭框 - 图6

自定义渲染行数据

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

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

Transfer穿梭框 - 图7

二次校验

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

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

Transfer穿梭框 - 图8

表格穿梭框

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

  1. import { Component, OnInit } from '@angular/core';
  2. import { TransferChange, TransferItem, TransferSelectChange } 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]="items" nzSize="small">
  26.           <thead>
  27.             <tr>
  28.               <th
  29.                 [nzDisabled]="disabled"
  30.                 [nzChecked]="stat.checkAll"
  31.                 [nzIndeterminate]="stat.checkHalf"
  32.                 (nzCheckedChange)="onItemSelectAll($event)"
  33.               ></th>
  34.               <th>Name</th>
  35.               <th *ngIf="direction === 'left'">Tag</th>
  36.               <th>Description</th>
  37.             </tr>
  38.           </thead>
  39.           <tbody>
  40.             <tr *ngFor="let data of t.data" (click)="onItemSelect(data)">
  41.               <td [nzChecked]="data.checked" [nzDisabled]="disabled || data.disabled" (nzCheckedChange)="onItemSelect(data)"></td>
  42.               <td>{{ data.title }}</td>
  43.               <td *ngIf="direction === 'left'">
  44.                 <nz-tag>{{ data.tag }}</nz-tag>
  45.               </td>
  46.               <td>{{ data.description }}</td>
  47.             </tr>
  48.           </tbody>
  49.         </nz-table>
  50.       </ng-template>
  51.     </nz-transfer>
  52.     <div style="margin-top: 8px;">
  53.       <nz-switch [(ngModel)]="disabled" nzCheckedChildren="disabled" nzUnCheckedChildren="disabled"></nz-switch>
  54.       <nz-switch [(ngModel)]="showSearch" nzCheckedChildren="showSearch" nzUnCheckedChildren="showSearch"></nz-switch>
  55.     </div>
  56.   `
  57. })
  58. export class NzDemoTransferTableTransferComponent implements OnInit {
  59.   list: TransferItem[] = [];
  60.   disabled = false;
  61.   showSearch = false;
  63.   ngOnInit(): void {
  64.     for (let i = 0; i < 20; i++) {
  65.       this.list.push({
  66.         key: i.toString(),
  67.         title: `content${i + 1}`,
  68.         description: `description of content${i + 1}`,
  69.         disabled: i % 4 === 0,
  70.         tag: ['cat', 'dog', 'bird'][i % 3]
  71.       });
  72.     }
  74.     [2, 3].forEach(idx => (this.list[idx].direction = 'right'));
  75.   }
  77.   select(ret: TransferSelectChange): void {
  78.     console.log('nzSelectChange', ret);
  79.   }
  81.   change(ret: TransferChange): void {
  82.     console.log('nzChange', ret);
  83.     const listKeys = ret.list.map(l => l.key);
  84.     const hasOwnKey = (e: TransferItem) => e.hasOwnProperty('key');
  85.     this.list = this.list.map(e => {
  86.       if (listKeys.includes(e.key) && hasOwnKey(e)) {
  87.         if (ret.to === 'left') {
  88.           delete e.hide;
  89.         } else if (ret.to === 'right') {
  90.           e.hide = false;
  91.         }
  92.       }
  93.       return e;
  94.     });
  95.   }
  96. }

Transfer穿梭框 - 图9

树穿梭框

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

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

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[]>-
[nzSelectedKeys]设置被选中的 key 集合string[]-
[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-