# @farris/extend-file-upload

## 修改记录

| 修改日期           | 修改要点                                     |
| ------------------ | :------------------------------------------- |
| 2020 年 1 月 17 日 | 支持预览、下载                               |
| 2020 年 1 月 9 日  | 支持通过后缀过滤                             |
| 2020 年 1 月 8 日  | 初版                                         |
| 2020 年 2 月 10 日 | 1.支持拖拽和批量上传 <br /> 2.优化交互方式   |
| 2020 年 2 月 11 日 | 预览组件支持列表、卡片展示方式以及自定义模板 |
| 2020 年 2 月 20 日 | 完善文档，修改类型问题                       |
| 2020 年 3 月 2 日 | 1.统一接口，涉及预览、上传抛出事件的类型<br /> 2.附件服务器端配置修改，接口统一<br />3.修改说明|
|2020年6月9日|可见的重置方法修改|
|2020年6月11日|图标异常问题修复|
|2026年3月21日|操作列按钮状态可通过回调方式控制|

## FFileUploadModule 附件模块

- 提供 forRoot 方法，可以预置附件服务器端配置和附件服务器端实现方法

| 方法    | 参数                                                                                                                    | 含义     |
| ------- | :---------------------------------------------------------------------------------------------------------------------- | :------- |
| forRoot | 两非必填个参数<br />1. config:FFileUploadServerConfig,附件服务器端配置 <br />2. uploadSer: UploadServerService 的实现类 | 提供扩展 |

#### UploadConfig 附件配置[接口]

| 方法      | 参数            | 含义                                                              |
| --------- | :-------------- | :---------------------------------------------------------------- |
| url       | string,可选     | 指定上传附件的服务器端路径      |
| method    | string:POST 或 GET，可选     | 指定传递到服务器端内容的方式                                                           |
| id        | string,可选     | 附件 ID                                                           |
| fieldName | string,可选     | 字段，当提交服务器端表单信息时，提交文件信息至此字段，默认是 file |
| file      | UploadFile,可选 | 附件信息                                                          |
| data      | 键值对像,可选   | 用于扩展传递服务器端的数据                                        |
| headers   | 键值对像,可选   | 用于扩展传递服务器端的头部信息                                    |

#### UploadInput 附件操作事件[接口]

- 继承自 UploadConfig
- 构造传递给服务的事件，比如在上传附件 uploadFile 的时候需要单独扩展传递服务器端数据，在删除单个文件 remove 的时候，需要单独扩展传递服务器端的头部信息

| 方法 | 参数 | 含义                                                                                                                                                                                                                |
| ---- | :--- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| type | 可选 | 事件名称：<br />1、uploadAll,上传所有 <br/> 2、uploadFile 上传单个 <br /> 3、cancel 取消 <br /> 4、cancelAll 取消所有 <br /> 5、remove 删除单个文件 <br />6、removeAll 删除所有文件 <br /> 7、config 配置类型<br /> |

#### FFileUploadServerConfig 附件服务器端配置[接口]

- 继承自 UploadConfig
- 针对服务器端方法，配置需要传递给服务器端的 data 或者 header

| 属性   | 类型        | 含义               |
| ------ | :---------- | :----------------- |
| upload | UploadInput | 单独用于处理附件上传时，传递到服务器端的配置     |
| remove | UploadInput | 单独用于处理删除单个文件时，传递到服务器端的配置 |

#### UploadServerService 附件服务类[抽象类]

- 抽象类用于限定附件接口服务，可以用于适配第三方附件接口
- 通过实现这个类，定义在上传和删除时候的服务器端方法，在模块初始化时传入。当附件上传和删除时，走实现类的 upload 和 remove 方法

| 方法   | 参数                                                                                                          | 返回值          | 含义         |
| ------ | :------------------------------------------------------------------------------------------------------------ | :-------------- | :----------- |
| upload | 两个参数:<br /> 1、files:UploadFile[]，附件信息 <br /> 2、event: UploadInput,事件信息包括配置服务器端扩展信息 | Observable<any> | 单个附件上传 |
| remove | 两个参数:<br /> 1、files:UploadFile[]，附件信息 <br /> 2、event: UploadInput,事件信息包括配置服务器端扩展信息 | Observable<any> | 单个附件上传 |

## 上传组件

- 默认启用文件按钮上传方式 -
  ```ts
   <f-file-upload [options]='上传配置项'
       (fUploadDoneEvent)="fUploadDoneHandler($event)" (fUploadRemovedEvent)="fUploadRemovedHandler($event)">
   </f-file-upload>
  ```

#### 属性说明

| 属性               | 值类型              | 含义                                                                                                                                    | 默认值                                                                    |
| ------------------ | :------------------ | :-------------------------------------------------------------------------------------------------------------------------------------- | :------------------------------------------------------------------------ |
| disabled           | boolean             | 是否禁用状态                                                                                                                            |
| visible            | boolean             | 上传组件是否可见<br />可与预览组件组合<br />控制状态                                                                                    | false                                                                     |
| enableDrop         | boolean             | 是否启用拖拽进行上传                                                                                                                    | false                                                                     |
| dropText           | string              | 拖拽区域提示文字                                                                                                                        | 拖拽文件                                                                  |
| enableSelect       | boolean             | 是否启用选择文件按钮                                                                                                                    | true                                                                      |
| selectText         | string              | 选择文件按钮文字                                                                                                                        | 选择文件                                                                  |
| multiple           | boolean             | 是否启用多选                                                                                                                            | 启用后可以一次选择多个文件                                                |
| options            | **UploaderOptions** | 上传配置项：<br />1. allowedContentTypes:允许上传的文件类型; <br /> 2.maxUploads:限制附件上传个数; <br /> 3.maxFileSize:单个文件最大 KB | 1. 允许上传任何类型;<br /> 2.不限制附件上传个数;<br />3.单个文件最大 12MB |
| extendServerConfig | any                 | 每个组可以设置特殊服务参数，来覆盖默认的统一模块级配置                                                                                  | null                                                                      |

#### 事件说明

| 事件                | 参数类型                | 含义                       |
| ------------------- | :---------------------- | :------------------------- |
| fUploadDoneEvent    | **FUploadFileExtend[]** | 附件上传完成后，抛出此事件 |
| fUploadRemovedEvent | **FUploadFileExtend[]** | 附件删除完成后，抛出此事件 |

## 预览组件

- 默认是列表(list)显示方式，内容：文件名，文档类型图标、下载按钮和预览按钮 -
  ```ts
  <f-file-preview [fileInfos]="文件信息" [itemCls]="项上单独的class">
  </f-file-preview>
  ```
- 列表(list)是纵向平铺每项数据，卡片(card)是横向平铺每项数据 -
- 支持自定义模板 -
  ```ts
  <f-file-preview [fileInfos]="文件信息" [itemCls]="项上单独的class">
       <ng-template filePreviewListTypeTemplate let-data let-readonly>
         ....
       </ng-template>
  </f-file-preview>
  ```

#### 属性说明

| 属性      | 值类型                  | 含义                                                       | 默认值 |
| --------- | :---------------------- | :--------------------------------------------------------- | :----- |
| type      | string                  | 文件布局类型：<br />1. list 列表类型 <br />2.card 卡片类型 | list   |
| itemCls   | string                  |                                                            | 空     |
| fileInfos | **FUploadFileExtend[]** | 附件信息数组                                               | []     |
| readonly  | boolean                 | 只读的状态,控制附件是否可删除                              | true   |

#### 事件说明

| 事件              | 参数类型              | 含义                               |
| ----------------- | :-------------------- | :--------------------------------- |
| filePreviewEvent  | **FUploadFileExtend** | 点击附件预览按钮时，抛出的附件信息 |
| fileDownloadEvent | **FUploadFileExtend** | 点击附件下载按钮时，抛出的附件信息 |
| fileRemoveEvent   | **FUploadFileExtend** | 点击附件删除按钮时，抛出的附件信息 |

#### filePreviewListTypeTemplate

- 预览组件的模板，提供预览界面自定义
- 两个属性
  1. data：**UploadFile** 类型，附件信息
  2. readonly：boolean 类型，只读状态

#### UploaderOptions 附件上传配置[接口]

| 属性                | 值类型   | 含义                                     |
| ------------------- | :------- | :--------------------------------------- |
| allowedContentTypes | string[] | 允许上传的文件类型，例 如['.jpg','.pdf'] |
| maxUploads          | number   | 最大上传个数                             |
| maxFileSize         | number   | 单个文件最大值 KB 为单位                 |

#### FUploadFileExtend 附件文件信息扩展[接口]

| 属性                | 值类型            | 含义                                               |
| ------------------- | :---------------- | :------------------------------------------------- |
| id                  | string            | 附件标识                                           |
| name                | string            | 文件名                                             |
| size [非必]         | number            | 文件大小                                           |
| type[非必]          | string            | 文件类型                                           |
| extend[非必]        | any 或 null       | 记录上传从服务器端返回的数据或者用于预览扩展的信息 |
| extendStatus[非必]  | number            | 记录上传服务器端返回的状态或者用于预览扩展状态     |
| extendHeaders[非必] | 键值对象或者 null | 记录服务器端返回的头信息或者用于预览扩展 Header    |

#### UploadFile 附件信息[接口]

| 属性            | 值类型        | 含义                     |
| --------------- | :------------ | :----------------------- |
| id              | string        | 附件上传后会自动生成 id  |
| fileIndex       | number        | 附件在数组中的位置       |
| name            | string        | 文件名                   |
| size            | number        | 文件大小，单位(B)        |
| type            | string        | 文件类型                 |
| form            | FormData      | 提交服务器的数据         |
| response        | any 可选      | 记录返回数据             |
| responseStatus  | number 可选   | 记录从服务器端返回的状态 |
| nativeFile      | File,可选     | 上传的原始文件信息       |
| responseHeaders | 键值对象,可选 | 服务器传递的 Header 信息 |

This library was generated with [Angular CLI](https://github.com/angular/angular-cli) version 7.2.0.

## Code scaffolding

Run `ng generate component component-name --project f-file-upload` to generate a new component. You can also use `ng generate directive|pipe|service|class|guard|interface|enum|module --project f-file-upload`.

> Note: Don't forget to add `--project f-file-upload` or else it will be added to the default project in your `angular.json` file.

## Build

Run `ng build f-file-upload` to build the project. The build artifacts will be stored in the `dist/` directory.

## Publishing

After building your library with `ng build f-file-upload`, go to the dist folder `cd dist/f-file-upload` and run `npm publish`.

## Running unit tests

Run `ng test f-file-upload` to execute the unit tests via [Karma](https://karma-runner.github.io).

## Further help

To get more help on the Angular CLI use `ng help` or go check out the [Angular CLI README](https://github.com/angular/angular-cli/blob/master/README.md).