# fileinput.js
**Repository Path**: Zeng_YL/fileinput.js
## Basic Information
- **Project Name**: fileinput.js
- **Description**: 基于bootstrap和jQuery的文件上传组件。支持拖曳上传。占页面空间小，只需一个单行文本框的大小。
- **Primary Language**: Unknown
- **License**: MIT
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No
## Statistics
- **Stars**: 1
- **Forks**: 0
- **Created**: 2021-11-15
- **Last Updated**: 2022-06-12
## Categories & Tags
**Categories**: Uncategorized
**Tags**: None
## README
# **fileinput.js**
fileinput.js是一个基于bootstrap和jQuery的库，用于文件上传。
它占网页空间很小 *(相当于单行文本框)* ，支持拖曳上传，API非常简单。
没有过多的功能，用于在浏览器端处理或验证文件较方便。
[](https://imgtu.com/i/IRWEPP)
作者：zengyl
开源协议：MIT
----
## 支持的一些功能
- 拖曳上传文件
- 文件后缀筛选
- 在回调中验证文件
- 组件大小可变
- 自定义按钮的class
- 简便地更改提示文字 *(可作本地化)*
## 使用
它在浏览器中运行。必须先引入：
- **bootstrap** *(我使用3.4.1，不确保其他版本能用。只需css即可)*
- **jQuery** *(我使用3.6.0，不确保其他版本能用)*
然后引入 **fileinput.js** 和 **fileinput.css**。
正式使用建议去[这里](https://gitee.com/Zeng_YL/fileinput.js/releases)查看所有的发行版。那里的代码都已经压缩。
## 入门
对jQuery对象执行`fileinput()`即可。建议是空的div元素。
例如，有个id为id的元素，执行以下代码以获得基础效果：
```
$("#id").fileinput()
```
上面这个例子会返回一个对象。如果重复执行，则会返回false。
**注：暂不支持同时处理多个元素！**
现在它还不能处理任何文件，传入一个回调函数让它处理。
回调函数会传入两个参数，为上传的文件对象，和处理文件的对象。
举个例子，需要读取文件中的json，并存储到myJSON中：
```js
var myJSON = {};
$("#id").fileinput(function(file, fn) {
/**
* file是上传文件的对象
* fn是含有两个函数的对象：
* fn.error(s) 告知程序文件处理错误，s为错误消息，可传可不传。
* fn.ok() 告知程序文件处理完成。
* (注：参数名字可自己起！)
*/
let json;
//假定我们要读取这里可以读取file的内容到json中。不建议直接读到全局变量，具体见后。
if(/*读取失败*/) {
fn.error("读取失败。");
return;
}
myJSON = json;
fn.ok();
})
```
回调函数要做的事：可以读取文件内容，并判断是否符合规范；也可以直接将file提交到服务器并获取返回值。
**必须考虑到：用户可以重复上传并覆盖。而且error()执行时，文件可以回退到上一个ok()后的状态。** 因此如果不具备回退或覆盖的能力，不建议直接读取到全局变量或上传到服务器。
**函数中，必须且只能执行一次error()或ok()** 。多次执行无效，不执行则会一直在处理状态。
现在它可以真正发挥应有的作用了。你还可以传入一些设定，更改其默认行为。
将设定传入第二个参数。例如：
```js
#("#id").fileinput(/*回调函数*/, {
/*传入设定*/
size: "lg",
accept: ".html"
class: {
browser_btn: "btn btn-success"
}
})
```
这会产生大号的组件，具有绿色的上传按钮，并且只接收html文件。
有关设定的更多信息见后。由于很简单，我就不解释了。
## API
### 核心函数
```js
fileinput(cbfn, conf)
```
核心调用方式。
在 **仅包含一个元素的jQuery对象** 中调用它，以在这个元素里生成fileinput组件。
**参数：**
- cbfn：一个函数，将在文件上传时执行。见下文“回调函数”。
- conf：一个普通对象，进行一些参数的设定。见下文“参数设定”。
**返回值：**
如果该元素已经是fileinput组件，则返回false；否则返回一个普通对象。
返回值通常没有什么用，因为普通的设定就能满足一般的要求。
但如果普通的设定无法满足你的要求，返回值可能对你有所帮助。
**不要更改其中的值，除非你明白后果。**
具体见下文“返回值”。那里只讲返回普通对象的情况。
### 回调函数
```js
function(file, fn){}
```
回调函数传入核心函数，以在文件上传时执行。它可以用来判断文件是否合规，或做基本的读取。
它应当接受两个参数。
**参数：**
- file：一个File对象，包含本次上传的文件。
- fn：普通对象，有两个成员。
- error(s)：函数，表示文件处理错误。可以选择传入一个字符串，作为错误提示。
- ok()：函数，表示文件处理成功。
使用前建议阅读“入门”的内容。
> **必须考虑到：用户可以重复上传并覆盖。而且error()执行时，文件可以回退到上一个ok()后的状态。** 因此如果不具备回退或覆盖的能力，不建议直接读取到全局变量或上传到服务器。
**函数中，必须且只能执行一次error()或ok()** 。多次执行无效，不执行则会一直在处理状态。
### 参数设定
默认值：
```js
{
accept: "",
size: "",
class: {
browser_btn: "btn btn-primary",
},
lang: {
nameCapt: "拖动文件或点击按钮以上传文件",
browser: "浏览文件",
processing: "处理中：",
error: ["错误。", "错误："],
done: "完成：",
drag: "松开以上传文件",
nonfile: "不是文件！",
refuseType: "不支持该文件类型！",
},
drag: true
}
```
- accept：支持的文件类型。可以是字符串或数组。字符串如".html,.js"，数组如[".html",".js"]。默认为空字符串，即支持所有。
- size：大小尺寸。lg为大，sm为小，默认空字符串
- class：元素的类，用于快速自定义样式
- browser_btn：“浏览文件”按钮
- lang：规定显示的文字。
- nameCapt：左侧文本框在无文件时的显示
- browser：“浏览文件”按钮
- process：正在处理文件的提示，后面将会接入文件名
- error：处理错误的提示。是数组，有两项，分别为后面会接入错误消息、和没有错误消息。
- done：处理完成的提示，后面将会接入文件名
- drag：拖动文件到组件上的提示
- nonfile：拖动到组件上的不是文件的错误提示
- refuseType：文件类型（后缀）错误的提示
- drag：是否支持拖曳上传文件
### 返回值
```js
{
elements: {
browser_btn: $(),
fileinput: $(),
nameCapt: $(),
wrapper: $()
},
file: File,
trueFile: File,
state: ""
}
```
- elements：普通对象，包含fileinput组件中的一些元素。其中每一项都是jQuery对象。
- browser_btn：右边“浏览文件”的按钮。
- fileinput：核心的\元素，被隐藏。
- nameCapt：左边用于显示提示和文件名的\元素。
- wrapper：用于包裹组件的元素。是bootstrap输入框组。
- file：File对象，包含有正在处理的文件。默认为null，处理完后 (执行error()或ok()) 将被置为null。
- trueFile：File对象，包含有处理成功 (执行ok()) 的文件。处理错误或正在处理的文件和它无关。
- state：字符串，记录目前组件的状态。可以是：
- processing：处理中，指上传了文件但还没有执行error()或ok()。此时file不为空。
- waiting：等待文件上传。此时没有文件，file和trueFile都为null。
- ok：处理成功。此时file为空，trueFile不为空，显示文件名。
- error：处理错误。这是临时状态，很快就会回到处理前的值。
- done：处理完成。这是临时状态，很快就会变成ok状态。