feat(module:transfer): add transfer component (#1052)

* wip(module:transfer): add transfer component * fix tslint fix titles i18n
NG-ZORRO · Mar 2, 2018 · bd3b710 · bd3b710
1 parent 9e71deb
commit bd3b710
Show file tree

Hide file tree

Showing 19 changed files with 516 additions and 157 deletions.
diff --git a/PROGRESS.md b/PROGRESS.md
@@ -41,7 +41,7 @@
 | timepicker | x | x | x | trotyl | - |
 | calendar | x | x | x | trotyl | - |
 | affix | x | x | x | cipchk | - |
-| transfer | x | x | x | cipchk | - |
+| transfer | √ | 100% | 100% | cipchk | x |
 | avatar | √ | 100% | 100% | cipchk | x |
 | list | √ | 100% | 100% | cipchk | x |
 | upload | x | x | x | cipchk | - |

diff --git a/components/index.ts b/components/index.ts
@@ -49,6 +49,7 @@ export * from './grid';
 export * from './layout';
 export * from './dropdown';
 export * from './menu';
+export * from './transfer';
 export * from './i18n';
 export * from './locale/index';
 export * from './list/index';

diff --git a/components/transfer/demo/advanced.ts b/components/transfer/demo/advanced.ts
@@ -23,11 +23,11 @@ import { NzMessageService } from 'ng-zorro-antd';
 export class NzDemoTransferAdvancedComponent implements OnInit {
   list = [];
 
-  ngOnInit() {
+  ngOnInit(): void {
     this.getData();
   }
 
-  getData() {
+  getData(): void {
     const ret = [];
     for (let i = 0; i < 20; i++) {
       ret.push({
@@ -40,16 +40,16 @@ export class NzDemoTransferAdvancedComponent implements OnInit {
     this.list = ret;
   }
 
-  reload(direction: string) {
+  reload(direction: string): void {
     this.getData();
     this.msg.success(`your clicked ${direction}!`);
   }
 
-  select(ret: {}) {
+  select(ret: {}): void {
     console.log('nzSelectChange', ret);
   }
 
-  change(ret: {}) {
+  change(ret: {}): void {
     console.log('nzChange', ret);
   }
 

diff --git a/components/transfer/demo/basic.ts b/components/transfer/demo/basic.ts
@@ -13,9 +13,10 @@ import { NzMessageService } from 'ng-zorro-antd';
   `
 })
 export class NzDemoTransferBasicComponent implements OnInit {
+  // tslint:disable-next-line:no-any
   list: any[] = [];
 
-  ngOnInit() {
+  ngOnInit(): void {
     for (let i = 0; i < 20; i++) {
       this.list.push({
         key     : i.toString(),
@@ -27,11 +28,11 @@ export class NzDemoTransferBasicComponent implements OnInit {
     [ 2, 3 ].forEach(idx => this.list[ idx ].direction = 'right');
   }
 
-  select(ret: any) {
+  select(ret: {}): void {
     console.log('nzSelectChange', ret);
   }
 
-  change(ret: any) {
+  change(ret: {}): void {
     console.log('nzChange', ret);
   }
 }
diff --git a/components/transfer/demo/can-move.ts b/components/transfer/demo/can-move.ts
@@ -1,15 +1,14 @@
 import { Component, OnInit } from '@angular/core';
-import { NzMessageService } from 'ng-zorro-antd';
 import { Observable } from 'rxjs/Observable';
 import { of } from 'rxjs/observable/of';
 import { delay } from 'rxjs/operators';
+import { TransferCanMove, TransferItem, NzMessageService } from 'ng-zorro-antd';
 
 @Component({
   selector: 'nz-demo-transfer-can-move',
   template: `
     <nz-transfer
       [nzDataSource]="list"
-      [nzTitles]="['Source', 'Target']"
       [canMove]="canMove"
       (nzSelectChange)="select($event)"
       (nzChange)="change($event)">
@@ -31,7 +30,7 @@ export class NzDemoTransferCanMoveComponent implements OnInit {
     [ 2, 3 ].forEach(idx => this.list[ idx ].direction = 'right');
   }
 
-  canMove(arg) {
+  canMove(arg: TransferCanMove): Observable<TransferItem[]> {
     if (arg.direction === 'right' && arg.list.length > 0) arg.list.splice(0, 1);
     // or
     // if (arg.direction === 'right' && arg.list.length > 0) delete arg.list[0];

diff --git a/components/transfer/demo/custom-item.ts b/components/transfer/demo/custom-item.ts
@@ -16,13 +16,14 @@ import { NzMessageService } from 'ng-zorro-antd';
   `
 })
 export class NzDemoTransferCustomItemComponent implements OnInit {
-  list: {}[] = [];
+  // tslint:disable-next-line:no-any
+  list: any[] = [];
 
-  ngOnInit() {
+  ngOnInit(): void {
     this.getData();
   }
 
-  getData() {
+  getData(): void {
     const ret = [];
     for (let i = 0; i < 20; i++) {
       ret.push({
@@ -36,11 +37,11 @@ export class NzDemoTransferCustomItemComponent implements OnInit {
     this.list = ret;
   }
 
-  select(ret: {}) {
+  select(ret: {}): void {
     console.log('nzSelectChange', ret);
   }
 
-  change(ret: {}) {
+  change(ret: {}): void {
     console.log('nzChange', ret);
   }
 

diff --git a/components/transfer/demo/search.ts b/components/transfer/demo/search.ts
@@ -15,9 +15,10 @@ import { NzMessageService } from 'ng-zorro-antd';
   `
 })
 export class NzDemoTransferSearchComponent implements OnInit {
+  // tslint:disable-next-line:no-any
   list: any[] = [];
 
-  ngOnInit() {
+  ngOnInit(): void {
     for (let i = 0; i < 20; i++) {
       this.list.push({
         key        : i.toString(),
@@ -28,19 +29,20 @@ export class NzDemoTransferSearchComponent implements OnInit {
     }
   }
 
-  filterOption(inputValue, option) {
-    return option.description.indexOf(inputValue) > -1;
+  // tslint:disable-next-line:no-any
+  filterOption(inputValue: string, item: any): boolean {
+    return item.description.indexOf(inputValue) > -1;
   }
 
-  search(ret: any) {
+  search(ret: {}): void {
     console.log('nzSearchChange', ret);
   }
 
-  select(ret: any) {
+  select(ret: {}): void {
     console.log('nzSelectChange', ret);
   }
 
-  change(ret: any) {
+  change(ret: {}): void {
     console.log('nzChange', ret);
   }
 }
diff --git a/components/transfer/doc/index.en-US.md b/components/transfer/doc/index.en-US.md
@@ -17,32 +17,50 @@ One or more elements can be selected from either column, one click on the proper
 
 | Property | Description | Type | Default |
 | -------- | ----------- | ---- | ------- |
-| className | A custom CSS class. | string | ['', ''] |
-| dataSource | Used for setting the source data. The elements that are part of this array will be present the left column. Except the elements whose keys are included in `targetKeys` prop. | [TransferItem](https://git.io/vMM64)\[] | \[] |
-| filterOption | A function to determine whether an item should show in search result list | (inputValue, option): boolean |  |
-| footer | A function used for rendering the footer. | (props): ReactNode |  |
-| lazy | property of [react-lazy-load](https://github.com/loktar00/react-lazy-load) for lazy rendering items. Turn off it by set to `false`. | object｜boolean | `{ height: 32, offset: 32 }` |
-| listStyle | A custom CSS style used for rendering the transfer columns. | object |  |
-| notFoundContent | Text to display when a column is empty. | string｜ReactNode | 'The list is empty' |
-| operations | A set of operations that are sorted from bottom to top. | string\[] | ['>', '<'] |
-| render | The function to generate the item shown on a column. Based on an record (element of the dataSource array), this function should return a React element which is generated from that record. Also, it can return a plain object with `value` and `label`, `label` is a React element and `value` is for title | Function(record) |  |
-| searchPlaceholder | The hint text of the search box. | string | 'Search here' |
-| selectedKeys | A set of keys of selected items. | string\[] | \[] |
-| showSearch | If included, a search box is shown on each column. | boolean | false |
-| targetKeys | A set of keys of elements that are listed on the right column. | string\[] | \[] |
-| titles | A set of titles that are sorted from left to right. | string\[] | - |
-| onChange | A callback function that is executed when the transfer between columns is complete. | (targetKeys, direction, moveKeys): void |  |
-| onScroll | A callback function which is executed when scroll options list | (direction, event): void |  |
-| onSearchChange | A callback function which is executed when search field are changed | (direction: 'left'｜'right', event: Event): void | - |
-| onSelectChange | A callback function which is executed when selected items are changed. | (sourceSelectedKeys, targetSelectedKeys): void |  |
-
-## Warning
-
-According the [standard](http://facebook.github.io/react/docs/lists-and-keys.html#keys) of React, the key should always be supplied directly to the elements in the array. In Transfer, the keys should be set on the elements included in `dataSource` array. By default, `key` property is used as an unique identifier.
-
-If there's no `key` in your data, you should use `rowKey` to specify the key that will be used for uniquely identify each element.
-
-```jsx
-// eg. your primary key is `uid`
-return <Transfer rowKey={record => record.uid} />;
-```
+| nzDataSource | Used for setting the source data. Except the elements whose keys are `direction: 'right'` prop. | TransferItem[] | [] |
+| nzTitles | A set of titles that are sorted from left to right. | string[] | ['', ''] |
+| nzOperations | A set of operations that are sorted from bottom to top. | string[] | ['', ''] |
+| nzListStyle | A custom CSS style used for rendering the transfer columns. equal `ngStyle` | object |  |
+| nzItemUnit | single unit | string | item |
+| nzItemsUnit | multiple unit | string | items |
+| #render | The function to generate the item shown on a column. please refer to the case. | `TemplateRef<void>` | - |
+| #footer | A function used for rendering the footer. please refer to the case. | `TemplateRef<void>` | - |
+| nzShowSearch | If included, a search box is shown on each column. | boolean | false |
+| nzFilterOption | A function to determine whether an item should show in search result list | `(inputValue: string, item: TransferItem) => boolean` |
+| nzSearchPlaceholder | The hint text of the search box. | string | 'Search here' |
+| nzNotFoundContent | Text to display when a column is empty. | string | 'The list is empty' |
+| canMove | Two verification when transfer choice box. please refer to the case. | `(arg: TransferCanMove) => Observable<TransferItem[]>` | - |
+| (nzChange) | A callback function that is executed when the transfer between columns is complete. | `EventEmitter<TransferChange>` | - |
+| (nzSearchChange) | A callback function which is executed when search field are changed | `EventEmitter<TransferSearchChange>` | - |
+| (nzSelectChange) | A callback function which is executed when selected items are changed. | `EventEmitter<TransferSearchChange>` | - |
+
+### TransferItem
+
+| Property | Description | Type | Default |
+| -------- | ----------- | ---- | ------- |
+| title | Used to display and search keyword | string | - |
+| direction | Used for setting the source data. Except the elements whose keys are `direction: 'right'` prop. | `left,right` | - |
+| disabled | specifies whether the checkbox is disabled | boolean | false |
+| checked | specifies whether the checkbox is selected | boolean | false |
+
+### TransferCanMove
+
+| Property | Description | Type | Default |
+| -------- | ----------- | ---- | ------- |
+| direction | data direction | `left,right` | - |
+| list | Used for setting the source data. | TransferItem[] | [] |
+
+### TransferChange
+
+| Property | Description | Type | Default |
+| -------- | ----------- | ---- | ------- |
+| from | data direction | `left,right` | - |
+| to | data direction | `left,right` | - |
+| list | Used for setting the source data. | TransferItem[] | [] |
+
+### TransferSearchChange
+
+| Property | Description | Type | Default |
+| -------- | ----------- | ---- | ------- |
+| direction | data direction | `left,right` | - |
+| value | Search keyword | string | - |
diff --git a/components/transfer/doc/index.zh-CN.md b/components/transfer/doc/index.zh-CN.md
@@ -19,32 +19,50 @@ title: Transfer
 
 | 参数 | 说明 | 类型 | 默认值 |
 | --- | --- | --- | --- |
-| className | 自定义类 | string |  |
-| dataSource | 数据源，其中的数据将会被渲染到左边一栏中，`targetKeys` 中指定的除外。 | [TransferItem](https://git.io/vMM64)\[] | \[] |
-| filterOption | 接收 `inputValue` `option` 两个参数，当 `option` 符合筛选条件时，应返回 `true`，反之则返回 `false`。 | (inputValue, option): boolean |  |
-| footer | 底部渲染函数 | (props): ReactNode |  |
-| lazy | Transfer 使用了 [react-lazy-load](https://github.com/loktar00/react-lazy-load) 优化性能，这里可以设置相关参数。设为 `false` 可以关闭懒加载。 | object｜boolean | `{ height: 32, offset: 32 }` |
-| listStyle | 两个穿梭框的自定义样式 | object |  |
-| notFoundContent | 当列表为空时显示的内容 | string｜ReactNode | '列表为空' |
-| operations | 操作文案集合，顺序从下至上 | string\[] | ['>', '<'] |
-| render | 每行数据渲染函数，该函数的入参为 `dataSource` 中的项，返回值为 ReactElement。或者返回一个普通对象，其中 `label` 字段为 ReactElement，`value` 字段为 title | Function(record) |  |
-| searchPlaceholder | 搜索框的默认值 | string | '请输入搜索内容' |
-| selectedKeys | 设置哪些项应该被选中 | string\[] | \[] |
-| showSearch | 是否显示搜索框 | boolean | false |
-| targetKeys | 显示在右侧框数据的key集合 | string\[] | \[] |
-| titles | 标题集合，顺序从左至右 | string\[] | ['', ''] |
-| onChange | 选项在两栏之间转移时的回调函数 | (targetKeys, direction, moveKeys): void |  |
-| onScroll | 选项列表滚动时的回调函数 | (direction, event): void |  |
-| onSearchChange | 搜索框内容时改变时的回调函数 | (direction: 'left'｜'right', event: Event): void | - |
-| onSelectChange | 选中项发生改变时的回调函数 | (sourceSelectedKeys, targetSelectedKeys): void |  |
-
-## 注意
-
-按照 React 的[规范](http://facebook.github.io/react/docs/lists-and-keys.html#keys)，所有的组件数组必须绑定 key。在 Transfer 中，`dataSource`里的数据值需要指定 `key` 值。对于 `dataSource` 默认将每列数据的 `key` 属性作为唯一的标识。
-
-如果你的数据没有这个属性，务必使用 `rowKey` 来指定数据列的主键。
-
-```jsx
-// 比如你的数据主键是 uid
-return <Transfer rowKey={record => record.uid} />;
-```
+| nzDataSource | 数据源，其中若数据属性 `direction: 'right'` 将会被渲染到右边一栏中 | TransferItem[] | [] |
+| nzTitles | 标题集合，顺序从左至右 | string[] | ['', ''] |
+| nzOperations | 操作文案集合，顺序从下至上 | string[] | ['', ''] |
+| nzListStyle | 两个穿梭框的自定义样式，等同 `ngStyle` | object |  |
+| nzItemUnit | 单数单位 | string | 项目 |
+| nzItemsUnit | 复数单位 | string | 项目 |
+| #render | 每行数据渲染模板，见示例 | `TemplateRef<void>` | - |
+| #footer | 底部渲染模板，见示例 | `TemplateRef<void>` | - |
+| nzShowSearch | 是否显示搜索框 | boolean | false |
+| nzFilterOption | 接收 `inputValue` `option` 两个参数，当 `option` 符合筛选条件时，应返回 `true`，反之则返回 `false`。 | (inputValue, option): boolean | `(inputValue: string, item: TransferItem) => boolean` |
+| nzSearchPlaceholder | 搜索框的默认值 | string | '请输入搜索内容' |
+| nzNotFoundContent | 当列表为空时显示的内容 | string | '列表为空' |
+| canMove | 穿梭时二次校验。**注意：** 穿梭组件内部始终只保留一份数据，二次校验过程中需取消穿梭项则直接删除该项；具体用法见示例。 | `(arg: TransferCanMove) => Observable<TransferItem[]>` | - |
+| (nzChange) | 选项在两栏之间转移时的回调函数 | `EventEmitter<TransferChange>` | - |
+| (nzSearchChange) | 搜索框内容时改变时的回调函数 | `EventEmitter<TransferSearchChange>` | - |
+| (nzSelectChange) | 选中项发生改变时的回调函数 | `EventEmitter<TransferSearchChange>` | - |
+
+### TransferItem
+
+| 参数 | 说明 | 类型 | 默认值 |
+| --- | --- | --- | --- |
+| title | 标题，用于显示及搜索关键字判断 | string | - |
+| direction | 指定数据方向，若指定 `right` 为右栏，其他情况为左栏 | `left,right` | - |
+| disabled | 指定checkbox为不可用状态 | boolean | false |
+| checked | 指定checkbox为选中状态 | boolean | false |
+
+### TransferCanMove
+
+| 参数 | 说明 | 类型 | 默认值 |
+| --- | --- | --- | --- |
+| direction | 数据方向 | `left,right` | - |
+| list | 数据源 | TransferItem[] | [] |
+
+### TransferChange
+
+| 参数 | 说明 | 类型 | 默认值 |
+| --- | --- | --- | --- |
+| from | 数据方向 | `left,right` | - |
+| to | 数据方向 | `left,right` | - |
+| list | 数据源 | TransferItem[] | [] |
+
+### TransferSearchChange
+
+| 参数 | 说明 | 类型 | 默认值 |
+| --- | --- | --- | --- |
+| direction | 数据方向 | `left,right` | - |
+| value | 搜索关键词 | string | - |
diff --git a/components/transfer/index.ts b/components/transfer/index.ts
@@ -0,0 +1 @@
+export * from './public-api';
diff --git a/components/transfer/interface.ts b/components/transfer/interface.ts
@@ -0,0 +1,31 @@
+export interface TransferItem {
+  title: string;
+  direction?: 'left' | 'right';
+  disabled?: boolean;
+  checked?: boolean;
+  _hiden?: boolean;
+  [key: string]: {};
+}
+
+export interface TransferCanMove {
+  direction: string;
+  list: TransferItem[];
+}
+
+export interface TransferChange {
+  from: string;
+  to: string;
+  list: TransferItem[];
+}
+
+export interface TransferSearchChange {
+  direction: string;
+  value: string;
+}
+
+export interface TransferSelectChange {
+  direction: string;
+  checked: boolean;
+  list: TransferItem[];
+  item: TransferItem;
+}
diff --git a/components/transfer/item.ts b/components/transfer/item.ts