diff --git a/docs/zh-CN/components/form/input-file.md b/docs/zh-CN/components/form/input-file.md index 2e046f2f6..35ea0a8e7 100755 --- a/docs/zh-CN/components/form/input-file.md +++ b/docs/zh-CN/components/form/input-file.md @@ -12,6 +12,8 @@ order: 21 用来负责文件上传,文件上传成功后会返回文件地址,这个文件地址会作为这个表单项的值,整个表单提交的时候,其实提交的是文件地址,文件上传已经在这个控件中完成了。 +> 如果希望文件内容伴随表单一起提交,可以配置 `asBlob` 或者 `asBase64`。 + ```schema: scope="body" { "type": "form", @@ -28,7 +30,11 @@ order: 21 } ``` -### 接口返回格式 +### 接口说明 + +这是单文件上传模式,通过配置 `receiver` 来接管文件上传。 + +接口发送方式是 POST, 数据体为 form-data 格式。对应的文件字段名为 `file`。这个可以通过 `fileField` 来配置。要求返回的数据格式如下。 ```json { @@ -42,6 +48,8 @@ order: 21 - value:必须返回该字段用作回显,一般是文件资源地址 +> 注意这只是单文件上传部分,如果允许上传的文件比较大,建议用分块上传,请阅读下面的分块上传部分。 + ## 限制文件类型 可以配置`accept`来限制可选择的文件类型,格式是文件后缀名`.xxx` @@ -89,7 +97,90 @@ order: 21 ## 分块上传 -如果文件过大,则可能需要使用分块上传 +如果文件过大,则可能需要使用分块上传,默认大于 5M(chunkSize 配置决定) 的文件是会自动开启,可以通过 `useChunk` 配置成 false 关闭。 + +分块上传需要配置三个接口来完成分别是: + +- `startChunkApi` 用来做分块前的准备工作 +- `chunkApi` 用来接收每个分块上传 +- `finishChunkApi` 用来收尾分块上传 + +### startChunkApi + +用来做分块前的准备工作,一个文件只会调用一次。如果出错了,后续的分块上传就会中断。 + +发送说明:默认是 post,发送的数据中会包含 `filename` 字段,记录文件名,默认的数据体格式为 json。可以额外配置参数,请参考 API 的配置说明。 + +要求返回的数据中必须包含: + +- `uploadId` 这次上传的唯一 ID。 +- `key` 有点类似 `uploadId`,可有可无,爱速搭中用来记录后端文件存储路径。 + +其他属性返回目前是没有任何作用的。 + +如: + +``` +{ + "status": 0, + "msg": "", + "data": { + "key": "images/JSSDK_page-xxxx.zip", + "uploadId": "036f64cd5dd95750d4bcb33556b629c6" + } +} +``` + +### chunkApi + +用来接收每个分块上传,大文件会根据 chunkSize 分割成多块,然后每块上传都会调用这个接口。 + +发送说明:默认为 post,发送体格式为 form-data。包含以下信息: + +- `uploadId` startChunkApi 返回的 +- `key` startChunkApi 返回的 +- `partNumber` 分块序号,从 1 开始。 +- `partSize` 分块大小 +- `file` 文件体 + +要求返回的数据中必须包含: + +- `eTag` 通常为文件的内容戳。 + +如: + +``` +{ + "status": 0, + "msg": "", + "data": { + "eTag": "016bd9b68ddd5cd7318875da3ea28207" + } +} +``` + +### finishChunkApi + +等所有分块上传完后,将上传文件收集到的 `eTag` 信息合并一起,再次请求后端完成文件上传。 + +发送说明:默认为 post,数据体默认为 json,包含以下信息 + +- `filename` 文件名 +- `key` startChunkApi 返回的 +- `uploadId` startChunkApi 返回的 +- `partList` 数组,每个成员为 `{partNumber: xxx, eTag: "xxxxx"}` 即分块编号和分块 `eTag` 信息。 + +数据返回,类似单文件上传一样,必须有 `value` 属性,可选返回 `url` 用来决定文件的下载地址。如: + +``` +{ + "status": 0, + "msg": "", + "data": { + "value": "https://xxxx.cdn.bcebos.com/images/JSSDK_page-xxxxx.zip" + } +} +``` ## 自动填充